The Texture Interface

The Texture Interface — Common interface for manipulating textures

Synopsis

                    CoglTexture;
CoglBool            cogl_is_texture                     (void *object);

unsigned int        cogl_texture_get_width              (CoglTexture *texture);
unsigned int        cogl_texture_get_height             (CoglTexture *texture);
CoglPixelFormat     cogl_texture_get_format             (CoglTexture *texture);
CoglBool            cogl_texture_is_sliced              (CoglTexture *texture);
int                 cogl_texture_get_data               (CoglTexture *texture,
                                                         CoglPixelFormat format,
                                                         unsigned int rowstride,
                                                         uint8_t *data);
CoglBool            cogl_texture_set_data               (CoglTexture *texture,
                                                         CoglPixelFormat format,
                                                         int rowstride,
                                                         const uint8_t *data,
                                                         int level,
                                                         CoglError **error);
CoglBool            cogl_texture_set_region             (CoglTexture *texture,
                                                         int width,
                                                         int height,
                                                         CoglPixelFormat format,
                                                         int rowstride,
                                                         const uint8_t *data,
                                                         int dst_x,
                                                         int dst_y,
                                                         int level,
                                                         CoglError **error);
enum                CoglTextureType;

Description

Cogl provides several different types of textures such as CoglTexture2D, CoglTexture3D, CoglTextureRectangle, CoglTexture2DSliced, CoglAtlasTexture, CoglSubTexture and CoglTexturePixmapX11 that each have specific apis for creating and manipulating them, but there are a number of common operations that can be applied to any of these texture types which are handled via this CoglTexture interface.

Details

CoglTexture

typedef struct _CoglTexture CoglTexture;

cogl_is_texture ()

CoglBool            cogl_is_texture                     (void *object);

Gets whether the given object references a texture object.

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.

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.

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.

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).

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.

Note

The rowstride should be the rowstride you want for the destination data buffer you don't need to try and calculate the rowstride of the source texture

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
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19










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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19










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.

Note

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.

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 width,
                                                         int height,
                                                         CoglPixelFormat format,
                                                         int rowstride,
                                                         const uint8_t *data,
                                                         int dst_x,
                                                         int dst_y,
                                                         int level,
                                                         CoglError **error);

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

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

The rowstride determines how many bytes between the first pixel of a row of data and the first pixel of the next row. If rowstride equals 0 then it will be automatically calculated from width 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. The size of any level can be calculated from the size of the base level as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20










width = MAX (1, floor (base_width / 2 ^ level));
 height = MAX (1, floor (base_height / 2 ^ level));

Or more succinctly put using C:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20










width = MAX (1, base_width >> level);
 height = MAX (1, base_height >> level);

You can get the size of the base level using cogl_texture_get_width() and cogl_texture_get_height().

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19










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

Or more succinctly in C using the fls() - "Find Last Set" - function:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18










n_levels = fls (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.

Note

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.

texture :

a CoglTexture.

width :

width of the region to set.

height :

height of the region to set.

format :

the CoglPixelFormat used in the source data buffer.

rowstride :

rowstride in bytes of the source data buffer (computed from width and format if it equals 0)

data :

the source data, pointing to the first top-left pixel to set

dst_x :

upper left destination x coordinate.

dst_y :

upper left destination y coordinate.

level :

The mipmap level to update (Normally 0 for the largest, base image)

error :

A CoglError to return exceptional errors

Returns :

TRUE if the subregion upload was successful, and FALSE otherwise

enum CoglTextureType

typedef enum {
  COGL_TEXTURE_TYPE_2D,
  COGL_TEXTURE_TYPE_3D,
  COGL_TEXTURE_TYPE_RECTANGLE
} CoglTextureType;

Constants representing the underlying hardware texture type of a CoglTexture.

COGL_TEXTURE_TYPE_2D

A CoglTexture2D

COGL_TEXTURE_TYPE_3D

A CoglTexture3D

COGL_TEXTURE_TYPE_RECTANGLE

A CoglTextureRectangle

Since 1.10

Stability Level: Unstable