The Texture Interface

## The Texture Interface The Texture Interface — Functions for creating and manipulating textures |

## Functions

CoglBool | cogl_is_texture ()
#define | COGL_TEXTURE_ERROR
CoglBool | cogl_texture_allocate ()
unsigned int | cogl_texture_get_width ()
unsigned int | cogl_texture_get_height ()
CoglBool | cogl_texture_is_sliced ()
int | cogl_texture_get_data ()
CoglBool | cogl_texture_set_data ()
CoglBool | cogl_texture_set_region ()
void | cogl_texture_set_components ()
CoglTextureComponents | cogl_texture_get_components ()
void | cogl_texture_set_premultiplied ()
CoglBool | cogl_texture_get_premultiplied ()

## Types and Values

typedef | CoglTexture
enum | CoglTextureError
enum | CoglTextureType
enum | CoglTextureComponents

## 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