LwTexture

LwTexture — OpenGL texture wrapper

Functions

Properties

guint height Read / Write / Construct Only
guint target Read / Write / Construct Only
guint width Read / Write / Construct Only

Types and Values

Object Hierarchy

    GObject
    ╰── LwTexture
        ╰── LwCairoTexture

Description

LwTexture is an easy way to work with OpenGL textures.

There are three ways to create a LwTexture. The easiest way is to load an image file (lw_texture_new_from_file()), but you can also use an existing GdkPixbuf (lw_texture_new_from_pixbuf()). The last option is to create a texture directly out of in-memory image data (lw_texture_new_from_data()). In each case you should free the LwTexture if you don't need it anymore by using g_object_unref().

LwTexture only supports 2D textures at the moment.

Use lw_texture_enable() to bind the texture. This does everything that is needed to use the texture. If you are finished with drawing, use lw_texture_disable().

Example 6. Using a LwTexture

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
GError *error = NULL;
LwTexture *tex = lw_texture_new_from_file("/path/to/texture.image", &error);

if(error != NULL)
{
    g_warning("Could not load the texture: %s", error->message);
    g_error_free(error);
    return;
}

lw_texture_enable(tex);

// Draw your textured object here, for example a quad
glBegin(GL_QUADS);
    glTexCoord2f(...);
    glVertex3f(...);
    ...
glEnd();

lw_texture_disable(tex);

Functions

LW_TEX_COORD_X()

#define LW_TEX_COORD_X(m, px) ((m).xx * (px) + (m).x0)

Transforms the X coordinate by a 2D texture matrix.

Parameters

m

A LwTextureMatrix

 

px

A X coordinate

 

Returns

A transformed X coordinate


LW_TEX_COORD_XY()

#define LW_TEX_COORD_XY(m, px, py) ((m).xx * (px) + (m).xy * (py) + (m).x0)

Transforms the X coordinate by a 2D texture matrix.

Use this macro if the LwTextureMatrix rotates the texture coordinates, otherwise use LW_TEX_COORD_X.

Parameters

m

A LwTextureMatrix

 

px

A X coordinate

 

py

A Y coordinate

 

Returns

A transformed X coordinate


LW_TEX_COORD_Y()

#define LW_TEX_COORD_Y(m, py) ((m).yy * (py) + (m).y0)

Transforms the Y coordinate by a 2D texture matrix.

Parameters

m

A LwTextureMatrix

 

py

A Y coordinate

 

Returns

A transformed Y coordinate


LW_TEX_COORD_YX()

#define LW_TEX_COORD_YX(m, px, py) ((m).yx * (px) + (m).yy * (py) + (m).y0)

Transforms the Y coordinate by a 2D texture matrix.

Use this macro if the LwTextureMatrix rotates the texture coordinates, otherwise use LW_TEX_COORD_Y.

Parameters

m

A LwTextureMatrix

 

px

A X coordinate

 

py

A Y coordinate

 

Returns

A transformed Y coordinate


lw_texture_new_from_data ()

LwTexture *
lw_texture_new_from_data (const guchar *data,
                          guint width,
                          guint height,
                          guint format,
                          guint type);

Creates a new texture out of in-memory image data. Internally glTexImage2D is used to create the texture. You can find a more detailed description of format and type on the documentation page of glTexImage2D.

You have to free the image data by yourself. You can free it directly after calling this function, LwTexture does not need it anymore.

Parameters

data

A pointer to the image data

 

width

Width of the image in pixels

 

height

Height of the image in pixels

 

format

Format of the image data

 

type

Data type of the image data

 

Returns

A new LwTexture. You should use g_object_unref() to free the LwTexture.


lw_texture_new_from_file ()

LwTexture *
lw_texture_new_from_file (const gchar *path);

Creates a new texture by loading an image from a file. This function supports all file formats supported by gdk-pixbuf. If NULL is returned, then error will be set. Internally the image file will be loaded into a GdkPixbuf first before creating the LwTexture.

Parameters

path

Name of the file to load

 

Returns

A new LwTexture, or NULL in case of an error. You should use g_object_unref() to free the LwTexture.

Since: 0.5


lw_texture_new_from_pixbuf ()

LwTexture *
lw_texture_new_from_pixbuf (GdkPixbuf *pixbuf);

Creates a new texture by using the image data of the GdkPixbuf.

You have to free the pixbuf by yourself. You can free it directly after calling this function, LwTexture does not need it anymore.

Parameters

pixbuf

A GdkPixbuf holding the image data

 

Returns

A new LwTexture. You should use g_object_unref() to free the LwTexture.


lw_texture_new_from_resource ()

LwTexture *
lw_texture_new_from_resource (const gchar *path);

Creates a new texture by loading an image from a gresource. This function supports all file formats supported by gdk-pixbuf. If NULL is returned, then error will be set. Internally the image file will be loaded into a GdkPixbuf first before creating the LwTexture.

Parameters

path

Name of the resource to load

 

Returns

A new LwTexture, or NULL in case of an error. You should use g_object_unref() to free the LwTexture.

Since: 0.5


lw_texture_disable ()

void
lw_texture_disable (LwTexture *self);

Disables the texture target.

Parameters

self

A LwTexture

 

lw_texture_enable ()

void
lw_texture_enable (LwTexture *self);

Enables the texture target.

Parameters

self

A LwTexture

 

lw_texture_get_filter ()

guint
lw_texture_get_filter (LwTexture *self);

Parameters

self

A LwTexture

 

Returns

The currently applied texture filter


lw_texture_get_height ()

guint
lw_texture_get_height (LwTexture *self);

Parameters

self

A LwTexture

 

Returns

The height of the texture


lw_texture_get_name ()

guint
lw_texture_get_name (LwTexture *self);

Parameters

self

A LwTexture

 

Returns

The texture name returned by glGenTextures


lw_texture_get_target ()

guint
lw_texture_get_target (LwTexture *self);

Returns the texture's target. At the moment only GL_TEXTURE_2D is supported, so this function always returns GL_TEXTURE_2D.

Parameters

self

A LwTexture

 

Returns

The texture target


lw_texture_get_width ()

guint
lw_texture_get_width (LwTexture *self);

Parameters

self

A LwTexture

 

Returns

The width of the texture


lw_texture_get_wrap ()

guint
lw_texture_get_wrap (LwTexture *self);

Parameters

self

A LwTexture

 

Returns

The current wrap parameter


lw_texture_set_filter ()

void
lw_texture_set_filter (LwTexture *self,
                       guint filter);

Sets the texture's minifying and magnification function. Possible values are GL_NEAREST and GL_LINEAR. GL_NEAREST is generally faster than GL_LINEAR, but it produces sharper edges. LwTexture uses GL_NEAREST by default.

To get a more detailed description of all possible filters, take a look at the documentation page of glTexParameter. This functions sets the GL_TEXTURE_MIN_FILTER and GL_TEXTURE_MAG_FILTER at the same time, so only filters supported by both are vaild arguments.

Parameters

self

A LwTexture

 

filter

The new texture filter

 

lw_texture_set_wrap ()

void
lw_texture_set_wrap (LwTexture *self,
                     guint wrap);

Sets the wrap parameter for texture coordinate s and t. The wrap parameter is set to GL_CLAMP_TO_EDGE by default.

This functions calls glTexParameter for GL_TEXTURE_WRAP_S and GL_TEXTURE_WRAP_T. You can find a complete list of all supported parameters at the documentation page of glTexParameter.

Parameters

self

A LwTexture

 

wrap

The new wrap parameter

 

lw_texture_bind ()

void
lw_texture_bind (LwTexture *self);

Uses lw_texture_bind_to() to bind this texture to the texture unit 0. If you just need one texture this is the function to use. If you want to use multiple textures with a fragment shader, take a look at lw_program_set_texture() or lw_texture_bind_to().

Parameters

self

A LwTexture

 

Since: 0.5


lw_texture_bind_to ()

gboolean
lw_texture_bind_to (LwTexture *self,
                    guint unit);

Binds the texture self to the specified texture unit. If you just need one texture, the lw_texture_bind() function might be simpler to use. You usually do not have to use this function directly if you use lw_program_set_texture().

Before binding the specified texture to its target using glBindTexture, it switches to the specified texture unit using glActiveTexture.

Parameters

self

A LwTexture

 

unit

The texture unit to use from 0 to lw_texture_get_max_texture_units()

 

Returns

TRUE on success and FALSE if unit is not a valid texture unit

Since: 0.5


lw_texture_get_max_texture_units ()

gint
lw_texture_get_max_texture_units ();

Returns

The value of GL_MAX_COMBINED_TEXTURE_IMAGE_UNITS

Since: 0.5


lw_texture_unbind ()

void
lw_texture_unbind (LwTexture *self);

Unbinds the texture by binding 0 to the texture's target. This operation switches to the texture unit specified by lw_texture_bind() or lw_texture_bind_to() using glActiveTexture. This function unbinds every texture currently bound to the same target and texture unit of self , even if self is not the active texture.

Parameters

self

A LwTexture

 

Since: 0.5

Types and Values

struct LwTexture

struct LwTexture {
	LwTextureMatrix matrix;
};

A structure for easier OpenGL texture handling.

Members

LwTextureMatrix matrix;

The LwTextureMatrix of this texture

 

struct LwTextureClass

struct LwTextureClass {
};

struct LwTextureMatrix

struct LwTextureMatrix {
	gfloat xx, yx;
	gfloat xy, yy;
	gfloat x0, y0;
};

A 2D matrix to transform texture coordinates.

Members

gfloat xx;

The xx component (scale and rotation)

 

gfloat yx;

The yx component (rotation only)

 

gfloat xy;

The xy component (rotation only)

 

gfloat yy;

The yy component (scale and rotation)

 

gfloat x0;

The offset in x direction

 

gfloat y0;

The offset in y direction

 

Property Details

The “height” property

  “height”                   guint

The height of the texture

Flags: Read / Write / Construct Only

Default value: 0


The “target” property

  “target”                   guint

The texture's target

Flags: Read / Write / Construct Only

Default value: 3553


The “width” property

  “width”                    guint

The width of the texture

Flags: Read / Write / Construct Only

Default value: 0