CoglTexture

typedef void CoglTexture;

cogl_is_texture ()

CoglBool            cogl_is_texture                     (void *object);

Gets whether the given object references a texture object.

COGL_TEXTURE_ERROR

#define COGL_TEXTURE_ERROR (cogl_texture_error_quark ())

CoglError domain for texture errors.

Since 1.8

Stability Level: Unstable

enum CoglTextureError

typedef enum {
  COGL_TEXTURE_ERROR_SIZE,
  COGL_TEXTURE_ERROR_FORMAT,
  COGL_TEXTURE_ERROR_BAD_PARAMETER,
  COGL_TEXTURE_ERROR_TYPE
} CoglTextureError;

Error codes that can be thrown when allocating textures.

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.

cogl_texture_get_width ()

unsigned int        cogl_texture_get_width              (CoglTexture *texture);

Queries the width of a cogl texture.

cogl_texture_get_height ()

unsigned int        cogl_texture_get_height             (CoglTexture *texture);

Queries the height of a cogl 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).

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.

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
20
21
22
23
24
25

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
20
21
22
23
24
25

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.

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.

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.

Since 1.10

Stability Level: Unstable

enum CoglTextureComponents

typedef enum {
  COGL_TEXTURE_COMPONENTS_A = 1,
  COGL_TEXTURE_COMPONENTS_RG,
  COGL_TEXTURE_COMPONENTS_RGB,
  COGL_TEXTURE_COMPONENTS_RGBA,
  COGL_TEXTURE_COMPONENTS_DEPTH
} CoglTextureComponents;

See cogl_texture_set_components().

Since 1.18

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.

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.

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.

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.

Since 1.18