The Texture Interface

The Texture Interface — Functions for creating and manipulating textures

Types and Values

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_ERROR

#define COGL_TEXTURE_ERROR (cogl_texture_error_quark ())

CoglError domain for texture errors.

Since: 1.8

Stability Level: Unstable


cogl_texture_allocate ()

CoglBool
cogl_texture_allocate (CoglTexture *texture,
                       CoglError **error);

Explicitly allocates the storage for the given texture which allows you to be sure that there is enough memory for the texture and if not then the error can be handled gracefully.

Normally applications don't need to use this api directly since the texture will be implicitly allocated when data is set on the texture, or if the texture is attached to a CoglOffscreen framebuffer and rendered too.

Parameters

texture

A CoglTexture

 

error

A CoglError to return exceptional errors or NULL

 

Returns

TRUE if the texture was successfully allocated, otherwise FALSE and error will be updated if it wasn't NULL.


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_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:

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

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

1
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


cogl_texture_set_components ()

void
cogl_texture_set_components (CoglTexture *texture,
                             CoglTextureComponents components);

Affects the internal storage format for this texture by specifying what components will be required for sampling later.

This api affects how data is uploaded to the GPU since unused components can potentially be discarded from source data.

For textures created by the ‘_with_size’ constructors the default is COGL_TEXTURE_COMPONENTS_RGBA. The other constructors which take a CoglBitmap or a data pointer default to the same components as the pixel format of the data.

Note that the COGL_TEXTURE_COMPONENTS_RG format is not available on all drivers. The availability can be determined by checking for the COGL_FEATURE_ID_TEXTURE_RG feature. If this format is used on a driver where it is not available then COGL_TEXTURE_ERROR_FORMAT will be raised when the texture is allocated. Even if the feature is not available then COGL_PIXEL_FORMAT_RG_88 can still be used as an image format as long as COGL_TEXTURE_COMPONENTS_RG isn't used as the texture's components.

Parameters

texture

a CoglTexture pointer.

 

Since: 1.18


cogl_texture_get_components ()

CoglTextureComponents
cogl_texture_get_components (CoglTexture *texture);

Queries what components the given texture stores internally as set via cogl_texture_set_components().

For textures created by the ‘_with_size’ constructors the default is COGL_TEXTURE_COMPONENTS_RGBA. The other constructors which take a CoglBitmap or a data pointer default to the same components as the pixel format of the data.

Parameters

texture

a CoglTexture pointer.

 

Since: 1.18


cogl_texture_set_premultiplied ()

void
cogl_texture_set_premultiplied (CoglTexture *texture,
                                CoglBool premultiplied);

Affects the internal storage format for this texture by specifying whether red, green and blue color components should be stored as pre-multiplied alpha values.

This api affects how data is uploaded to the GPU since Cogl will convert source data to have premultiplied or unpremultiplied components according to this state.

For example if you create a texture via cogl_texture_2d_new_with_size() and then upload data via cogl_texture_set_data() passing a source format of COGL_PIXEL_FORMAT_RGBA_8888 then Cogl will internally multiply the red, green and blue components of the source data by the alpha component, for each pixel so that the internally stored data has pre-multiplied alpha components. If you instead upload data that already has pre-multiplied components by passing COGL_PIXEL_FORMAT_RGBA_8888_PRE as the source format to cogl_texture_set_data() then the data can be uploaded without being converted.

By default the premultipled state is TRUE .

Parameters

texture

a CoglTexture pointer.

 

premultiplied

Whether any internally stored red, green or blue components are pre-multiplied by an alpha component.

 

Since: 1.18


cogl_texture_get_premultiplied ()

CoglBool
cogl_texture_get_premultiplied (CoglTexture *texture);

Queries the pre-multiplied alpha status for internally stored red, green and blue components for the given texture as set by cogl_texture_set_premultiplied().

By default the pre-multipled state is TRUE .

Parameters

texture

a CoglTexture pointer.

 

Returns

TRUE if red, green and blue components are internally stored pre-multiplied by the alpha value or FALSE if not.

Since: 1.18

Types and Values

CoglTexture

typedef void CoglTexture;

enum CoglTextureError

Error codes that can be thrown when allocating textures.

Members

COGL_TEXTURE_ERROR_SIZE

Unsupported size

 

COGL_TEXTURE_ERROR_FORMAT

Unsupported format

 

COGL_TEXTURE_ERROR_BAD_PARAMETER

   

COGL_TEXTURE_ERROR_TYPE

A primitive texture type that is unsupported by the driver was used

 

Since: 1.8

Stability Level: Unstable


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


enum CoglTextureComponents

See cogl_texture_set_components().

Members

COGL_TEXTURE_COMPONENTS_A

Only the alpha component

 

COGL_TEXTURE_COMPONENTS_RG

Red and green components. Note that this can only be used if the COGL_FEATURE_ID_TEXTURE_RG feature is advertised.

 

COGL_TEXTURE_COMPONENTS_RGB

Red, green and blue components

 

COGL_TEXTURE_COMPONENTS_RGBA

Red, green, blue and alpha components

 

COGL_TEXTURE_COMPONENTS_DEPTH

Only a depth component

 

Since: 1.18