The Texture Interface

## The Texture Interface The Texture Interface — Functions for creating and 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 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);
    enum                CoglTextureType;

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

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

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

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

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

### Note

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

`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

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