Cogl 2.0 Reference Manual: The Texture Interface

The Texture Interface

The Texture Interface — Functions for creating and manipulating textures

Functions

CoglBool	cogl_is_texture ()
unsigned int	cogl_texture_get_width ()
unsigned int	cogl_texture_get_height ()
CoglPixelFormat	cogl_texture_get_format ()
CoglBool	cogl_texture_is_sliced ()
int	cogl_texture_get_data ()
CoglBool	cogl_texture_set_data ()
CoglBool	cogl_texture_set_region ()

Types and Values

	CoglTexture
enum	CoglTextureType

Object Hierarchy

Description

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

Functions

cogl_is_texture ()

CoglBool
cogl_is_texture (void *object);

Gets whether the given object references a texture object.

Parameters

object

A CoglObject pointer

Returns

TRUE if the object references a texture, and FALSE otherwise

cogl_texture_get_width ()

unsigned int
cogl_texture_get_width (CoglTexture *texture);

Queries the width of a cogl texture.

Parameters

texture

a CoglTexture pointer.

Returns

the width of the GPU side texture in pixels

cogl_texture_get_height ()

unsigned int
cogl_texture_get_height (CoglTexture *texture);

Queries the height of a cogl texture.

Parameters

texture

a CoglTexture pointer.

Returns

the height of the GPU side texture in pixels

cogl_texture_get_format ()

CoglPixelFormat
cogl_texture_get_format (CoglTexture *texture);

Queries the CoglPixelFormat of a cogl texture.

Parameters

texture

a CoglTexture pointer.

Returns

the CoglPixelFormat of the GPU side texture

cogl_texture_is_sliced ()

CoglBool
cogl_texture_is_sliced (CoglTexture *texture);

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

Parameters

texture

a CoglTexture pointer.

Returns

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

cogl_texture_get_data ()

int
cogl_texture_get_data (CoglTexture *texture,
                       CoglPixelFormat format,
                       unsigned int rowstride,
                       uint8_t *data);

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

Don't pass the value of cogl_texture_get_rowstride() as the rowstride argument, the rowstride should be the rowstride you want for the destination data buffer not the rowstride of the source texture

Parameters

texture	a CoglTexture pointer.
format	the CoglPixelFormat to store the texture as.
rowstride	the rowstride of `data` in bytes or pass 0 to calculate from the bytes-per-pixel of `format` multiplied by the `texture` width.
data	memory location to write the `texture` 's contents, or `NULL` to only query the data size through the return value.

Returns

the size of the texture data in bytes

cogl_texture_set_data ()

CoglBool
cogl_texture_set_data (CoglTexture *texture,
                       CoglPixelFormat format,
                       int rowstride,
                       const uint8_t *data,
                       int level,
                       CoglError **error);

Sets all the pixels for a given mipmap level by copying the pixel data pointed to by the data argument into the given texture .

data should point to the first pixel to copy corresponding to the top left of the mipmap level being set.

If rowstride equals 0 then it will be automatically calculated from the width of the mipmap level and the bytes-per-pixel for the given format .

A mipmap level of 0 corresponds to the largest, base image of a texture and level 1 is half the width and height of level 0. If dividing any dimension of the previous level by two results in a fraction then round the number down (floor()), but clamp to 1 something like this:

 next_width = MAX (1, floor (prev_width));

You can determine the number of mipmap levels for a given texture like this:

 n_levels = 1 + floor (log2 (max_dimension));

Where max_dimension is the larger of cogl_texture_get_width() and cogl_texture_get_height().

It is an error to pass a level number >= the number of levels that texture can have according to the above calculation.

Since the storage for a CoglTexture is allocated lazily then if the given texture has not previously been allocated then this api can return FALSE and throw an exceptional error if there is not enough memory to allocate storage for texture.

Parameters

format	the CoglPixelFormat used in the source `data` buffer.
rowstride	rowstride of the source `data` buffer (computed from the texture width and `format` if it equals 0)
data	the source data, pointing to the first top-left pixel to set
level	The mipmap level to update (Normally 0 for the largest, base texture)
error	A CoglError to return exceptional errors

Returns

TRUE if the data upload was successful, and FALSE otherwise

cogl_texture_set_region ()

CoglBool
cogl_texture_set_region (CoglTexture *texture,
                         int src_x,
                         int src_y,
                         int dst_x,
                         int dst_y,
                         unsigned int dst_width,
                         unsigned int dst_height,
                         int width,
                         int height,
                         CoglPixelFormat format,
                         unsigned int rowstride,
                         const uint8_t *data);

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

The region set can't be larger than the source data

Parameters

texture	a CoglTexture.
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. (Must be less than or equal to `width` )
dst_height	height of destination region to write. (Must be less than or equal to `height` )
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, and FALSE otherwise

Types and Values

CoglTexture

typedef struct _CoglTexture CoglTexture;

enum CoglTextureType

Constants representing the underlying hardware texture type of a CoglTexture.

Members

COGL_TEXTURE_TYPE_2D	A CoglTexture2D
COGL_TEXTURE_TYPE_3D	A CoglTexture3D
COGL_TEXTURE_TYPE_RECTANGLE	A CoglTextureRectangle

Since 1.10

Stability Level: Unstable