Textures

Textures — Fuctions for creating and manipulating textures

Synopsis

                    CoglTextureVertex;
CoglHandle          cogl_texture_new_with_size          (guint width,
                                                         guint height,
                                                         gint max_waste,
                                                         gboolean auto_mipmap,
                                                         CoglPixelFormat internal_format);
CoglHandle          cogl_texture_new_from_file          (const gchar *filename,
                                                         gint max_waste,
                                                         gboolean auto_mipmap,
                                                         CoglPixelFormat internal_format,
                                                         GError **error);
CoglHandle          cogl_texture_new_from_data          (guint width,
                                                         guint height,
                                                         gint max_waste,
                                                         gboolean auto_mipmap,
                                                         CoglPixelFormat format,
                                                         CoglPixelFormat internal_format,
                                                         guint rowstride,
                                                         const guchar *data);
CoglHandle          cogl_texture_new_from_foreign       (GLuint gl_handle,
                                                         GLenum gl_target,
                                                         GLuint width,
                                                         GLuint height,
                                                         GLuint x_pot_waste,
                                                         GLuint y_pot_waste,
                                                         CoglPixelFormat format);
gboolean            cogl_is_texture                     (CoglHandle handle);
guint               cogl_texture_get_width              (CoglHandle handle);
guint               cogl_texture_get_height             (CoglHandle handle);
CoglPixelFormat     cogl_texture_get_format             (CoglHandle handle);
guint               cogl_texture_get_rowstride          (CoglHandle handle);
gint                cogl_texture_get_max_waste          (CoglHandle handle);
COGLenum            cogl_texture_get_min_filter         (CoglHandle handle);
COGLenum            cogl_texture_get_mag_filter         (CoglHandle handle);
gboolean            cogl_texture_is_sliced              (CoglHandle handle);
gboolean            cogl_texture_get_gl_texture         (CoglHandle handle,
                                                         GLuint *out_gl_handle,
                                                         GLenum *out_gl_target);
gint                cogl_texture_get_data               (CoglHandle handle,
                                                         CoglPixelFormat format,
                                                         guint rowstride,
                                                         guchar *data);
void                cogl_texture_set_filters            (CoglHandle handle,
                                                         COGLenum min_filter,
                                                         COGLenum mag_filter);
gboolean            cogl_texture_set_region             (CoglHandle handle,
                                                         gint src_x,
                                                         gint src_y,
                                                         gint dst_x,
                                                         gint dst_y,
                                                         guint dst_width,
                                                         guint dst_height,
                                                         gint width,
                                                         gint height,
                                                         CoglPixelFormat format,
                                                         guint rowstride,
                                                         const guchar *data);
CoglHandle          cogl_texture_ref                    (CoglHandle handle);
void                cogl_texture_unref                  (CoglHandle handle);
void                cogl_texture_rectangle              (CoglHandle handle,
                                                         ClutterFixed x1,
                                                         ClutterFixed y1,
                                                         ClutterFixed x2,
                                                         ClutterFixed y2,
                                                         ClutterFixed tx1,
                                                         ClutterFixed ty1,
                                                         ClutterFixed tx2,
                                                         ClutterFixed ty2);
void                cogl_texture_polygon                (CoglHandle handle,
                                                         guint n_vertices,
                                                         CoglTextureVertex *vertices,
                                                         gboolean use_color);

Description

COGL allows creating and manipulating GL textures using a uniform API that tries to hide all the various complexities of creating, loading and manipulating textures.

Details

CoglTextureVertex

typedef struct {
  ClutterFixed x, y, z;
  ClutterFixed tx, ty;
  ClutterColor color;
} CoglTextureVertex;

Used to specify vertex information when calling cogl_texture_polygon().

ClutterFixed x;

Model x-coordinate

ClutterFixed y;

Model y-coordinate

ClutterFixed z;

Model z-coordinate

ClutterFixed tx;

Texture x-coordinate

ClutterFixed ty;

Texture y-coordinate

ClutterColor color;

The color to use at this vertex. This is ignored if use_color is FALSE when calling cogl_texture_polygon().

cogl_texture_new_with_size ()

CoglHandle          cogl_texture_new_with_size          (guint width,
                                                         guint height,
                                                         gint max_waste,
                                                         gboolean auto_mipmap,
                                                         CoglPixelFormat internal_format);

Create a new texture with specified dimensions and pixel format.

width :

width of texture in pixels.

height :

height of texture in pixels.

max_waste :

maximum extra horizontal and|or vertical margin pixels to make texture fit GPU limitations.

auto_mipmap :

enable or disable automatic generation of mipmap pyramid from the base level image whenever it is updated.

internal_format :

the CoglPixelFormat to use for the GPU storage of the texture.

Returns :

a CoglHandle to the newly created texture or COGL_INVALID_HANDLE if texture creation failed.

cogl_texture_new_from_file ()

CoglHandle          cogl_texture_new_from_file          (const gchar *filename,
                                                         gint max_waste,
                                                         gboolean auto_mipmap,
                                                         CoglPixelFormat internal_format,
                                                         GError **error);

Load an image file from disk.

filename :

the file to load

max_waste :

maximum extra horizontal and|or vertical margin pixels to make texture fit GPU limitations.

auto_mipmap :

enable or disable automatic generation of mipmap pyramid from the base level image whenever it is updated.

internal_format :

the CoglPixelFormat to use for the GPU storage of the texture.

error :

a GError or NULL.

Returns :

a CoglHandle to the newly created texture or COGL_INVALID_HANDLE if creating the texture failed.

cogl_texture_new_from_data ()

CoglHandle          cogl_texture_new_from_data          (guint width,
                                                         guint height,
                                                         gint max_waste,
                                                         gboolean auto_mipmap,
                                                         CoglPixelFormat format,
                                                         CoglPixelFormat internal_format,
                                                         guint rowstride,
                                                         const guchar *data);

Create a new cogl texture based on data residing in memory.

width :

width of texture in pixels.

height :

height of texture in pixels.

max_waste :

maximum extra horizontal and|or vertical margin pixels to make

auto_mipmap :

enable or disable automatic generation of mipmap pyramid from the base level image whenever it is updated.

format :

the CoglPixelFormat the buffer is stored in in RAM

internal_format :

the CoglPixelFormat that will be used for storing the buffer on the GPU.

rowstride :

the memory offset in bytes between the starts of scanlines in data.

data :

pointer the memory region where the source buffer resides.

Returns :

a CoglHandle to the newly created texture or COGL_INVALID_HANDLE if creating the texture failed.

cogl_texture_new_from_foreign ()

CoglHandle          cogl_texture_new_from_foreign       (GLuint gl_handle,
                                                         GLenum gl_target,
                                                         GLuint width,
                                                         GLuint height,
                                                         GLuint x_pot_waste,
                                                         GLuint y_pot_waste,
                                                         CoglPixelFormat format);

Create a cogl texture based on an existing OpenGL texture, the width, height and format are passed along since it is not possible to query this from a handle with GLES 1.0.

gl_handle :

opengl target type of foreign texture

gl_target :

opengl handle of foreign texture.

width :

width of foreign texture

height :

height of foreign texture.

x_pot_waste :

maximum horizontal waste.

y_pot_waste :

maximum vertical waste.

format :

format of the foreign texture.

Returns :

a CoglHandle to the newly created texture or COGL_INVALID_HANDLE if creating the texture failed.

cogl_is_texture ()

gboolean            cogl_is_texture                     (CoglHandle handle);

Gets whether the given handle references an existing texture object.

handle :

A CoglHandle

Returns :

TRUE if the handle references a texture, FALSE otherwise

cogl_texture_get_width ()

guint               cogl_texture_get_width              (CoglHandle handle);

Query the width of a cogl texture.

handle :

a CoglHandle for a texture.

Returns :

the width of the GPU side texture in pixels:

cogl_texture_get_height ()

guint               cogl_texture_get_height             (CoglHandle handle);

Query the height of a cogl texture.

handle :

a CoglHandle for a texture.

Returns :

the height of the GPU side texture in pixels:

cogl_texture_get_format ()

CoglPixelFormat     cogl_texture_get_format             (CoglHandle handle);

Query the CoglPixelFormat of a cogl texture.

handle :

a CoglHandle for a texture.

Returns :

the CoglPixelFormat of the GPU side texture.

cogl_texture_get_rowstride ()

guint               cogl_texture_get_rowstride          (CoglHandle handle);

Query the rowstride of a cogl texture.

handle :

a CoglHandle for a texture.

Returns :

the offset in bytes between each consequetive row of pixels.

cogl_texture_get_max_waste ()

gint                cogl_texture_get_max_waste          (CoglHandle handle);

Query the maximum wasted (unused) pixels in one dimension of a GPU side texture.

handle :

a CoglHandle for a texture.

Returns :

the maximum waste.

cogl_texture_get_min_filter ()

COGLenum            cogl_texture_get_min_filter         (CoglHandle handle);

Query the currently set downscaling filter for a cogl texture.

handle :

a CoglHandle for a texture.

Returns :

the current downscaling filter for a cogl texture.

cogl_texture_get_mag_filter ()

COGLenum            cogl_texture_get_mag_filter         (CoglHandle handle);

Query the currently set downscaling filter for a cogl texture.

handle :

a CoglHandle for a texture.

Returns :

the current downscaling filter for a cogl texture.

cogl_texture_is_sliced ()

gboolean            cogl_texture_is_sliced              (CoglHandle handle);

Query if a texture is sliced (stored as multiple GPU side tecture objects).

handle :

a CoglHandle for a texture.

Returns :

TRUE if the texture is sliced, FALSE if the texture is stored as a single GPU texture.

cogl_texture_get_gl_texture ()

gboolean            cogl_texture_get_gl_texture         (CoglHandle handle,
                                                         GLuint *out_gl_handle,
                                                         GLenum *out_gl_target);

Query the GL handles for a GPU side texture through it's CoglHandle, if the texture is spliced the data for the first sub texture will be queried.

handle :

a CoglHandle for a texture.

out_gl_handle :

pointer to return location for the textures GL handle, or NULL.

out_gl_target :

pointer to return location for the GL target type, or NULL.

Returns :

TRUE if the handle was successfully retrieved FALSE if the handle was invalid.

cogl_texture_get_data ()

gint                cogl_texture_get_data               (CoglHandle handle,
                                                         CoglPixelFormat format,
                                                         guint rowstride,
                                                         guchar *data);

Copy the pixel data from a cogl texture to system memory.

handle :

a CoglHandle for a texture.

format :

the CoglPixelFormat to store the texture as.

rowstride :

the rowstride of data or retrieved from texture if none is specified.

data :

memory location to write contents of buffer, or NULL if we're only querying the data size through the return value.

Returns :

the size of the texture data in bytes (or 0 if the texture is not valid.)

cogl_texture_set_filters ()

void                cogl_texture_set_filters            (CoglHandle handle,
                                                         COGLenum min_filter,
                                                         COGLenum mag_filter);

Changes the decimation and interpolation filters used when the texture is drawn at other scales than 100%.

handle :

a CoglHandle.

min_filter :

the filter used when scaling the texture down.

mag_filter :

the filter used when magnifying the texture.

cogl_texture_set_region ()

gboolean            cogl_texture_set_region             (CoglHandle handle,
                                                         gint src_x,
                                                         gint src_y,
                                                         gint dst_x,
                                                         gint dst_y,
                                                         guint dst_width,
                                                         guint dst_height,
                                                         gint width,
                                                         gint height,
                                                         CoglPixelFormat format,
                                                         guint rowstride,
                                                         const guchar *data);

Sets the pixels in a rectangular subregion of handle from an in-memory buffer containing pixel data.

handle :

a CoglHandle.

src_x :

upper left coordinate to use from source data.

src_y :

upper left coordinate to use from source data.

dst_x :

upper left destination horizontal coordinate.

dst_y :

upper left destination vertical coordinate.

dst_width :

width of destination region to write.

dst_height :

height of destination region to write.

width :

width of source data buffer.

height :

height of source data buffer.

format :

the CoglPixelFormat used in the source buffer.

rowstride :

rowstride of source buffer (computed from width if none specified)

data :

the actual pixel data.

Returns :

TRUE if the subregion upload was successful, otherwise FALSE.

cogl_texture_ref ()

CoglHandle          cogl_texture_ref                    (CoglHandle handle);

Increment the reference count for a cogl texture.

handle :

a CoglHandle.

Returns :

the handle.

cogl_texture_unref ()

void                cogl_texture_unref                  (CoglHandle handle);

Deccrement the reference count for a cogl texture.

handle :

a CoglHandle.

cogl_texture_rectangle ()

void                cogl_texture_rectangle              (CoglHandle handle,
                                                         ClutterFixed x1,
                                                         ClutterFixed y1,
                                                         ClutterFixed x2,
                                                         ClutterFixed y2,
                                                         ClutterFixed tx1,
                                                         ClutterFixed ty1,
                                                         ClutterFixed tx2,
                                                         ClutterFixed ty2);

Draw a rectangle from a texture to the display, to draw the entire texture pass in tx1=0.0 ty1=0.0 tx2=1.0 ty2=1.0.

handle :

a CoglHandle.

x1 :

x coordinate upper left on screen.

y1 :

y coordinate upper left on screen.

x2 :

x coordinate lower right on screen.

y2 :

y coordinate lower right on screen.

tx1 :

x part of texture coordinate to use for upper left pixel

ty1 :

y part of texture coordinate to use for upper left pixel

tx2 :

x part of texture coordinate to use for lower right pixel

ty2 :

y part of texture coordinate to use for left pixel

cogl_texture_polygon ()

void                cogl_texture_polygon                (CoglHandle handle,
                                                         guint n_vertices,
                                                         CoglTextureVertex *vertices,
                                                         gboolean use_color);

Draws a polygon from a texture with the given model and texture coordinates. This can be used to draw arbitrary shapes textured with a COGL texture. If use_color is TRUE then the current COGL color will be changed for each vertex using the value specified in the color member of CoglTextureVertex. This can be used for example to make the texture fade out by setting the alpha value of the color.

All of the texture coordinates must be in the range [0,1] and repeating the texture is not supported.

Because of the way this function is implemented it will currently only work if either the texture is not sliced or the backend is not OpenGL ES and the minifying and magnifying functions are both set to CGL_NEAREST.

handle :

A CoglHandle for a texture

n_vertices :

The length of the vertices array

vertices :

An array of CoglTextureVertex structs

use_color :

TRUE if the color member of CoglTextureVertex should be used