## The Texture Interface

The Texture Interface — Fuctions for creating and manipulating textures

## Synopsis

                        CoglTexture;
    gboolean            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);
    gboolean            cogl_texture_is_sliced              (CoglTexture *texture);
    int                 cogl_texture_get_data               (CoglTexture *texture,
                                                             CoglPixelFormat format,
                                                             unsigned int rowstride,
                                                             guint8 *data);
    gboolean            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 guint8 *data);

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

    gboolean            cogl_is_texture                     (void *object);

Gets whether the given object references a texture object.

`object` : | A CoglObject pointer
Returns : | `TRUE` if the handle 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.

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.

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.

Returns : | the CoglPixelFormat of the GPU side texture

### cogl_texture_is_sliced ()

    gboolean            cogl_texture_is_sliced              (CoglTexture *texture);

Queries if a texture is sliced (stored as multiple GPU side tecture objects).

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,
                                                             guint8 *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

`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_region ()

    gboolean            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 guint8 *data);

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

`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.
`dst_height` : | height of destination region to write.
`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