## Textures Textures — Functions for creating and manipulating textures |

## Synopsis

    struct              CoglTextureVertex;
    enum                CoglTextureFlags;
    CoglTexture *       cogl_texture_new_with_size          (unsigned int width,
                                                             unsigned int height,
                                                             CoglTextureFlags flags,
                                                             CoglPixelFormat internal_format);
    CoglTexture *       cogl_texture_new_from_file          (const char *filename,
                                                             CoglTextureFlags flags,
                                                             CoglPixelFormat internal_format,
                                                             CoglError **error);
    CoglTexture *       cogl_texture_new_from_data          (int width,
                                                             int height,
                                                             CoglTextureFlags flags,
                                                             CoglPixelFormat format,
                                                             CoglPixelFormat internal_format,
                                                             int rowstride,
                                                             const uint8_t *data);
    CoglTexture *       cogl_texture_new_from_foreign       (unsigned int gl_handle,
                                                             unsigned int gl_target,
                                                             unsigned int width,
                                                             unsigned int height,
                                                             unsigned int x_pot_waste,
                                                             unsigned int y_pot_waste,
                                                             CoglPixelFormat format);
    CoglTexture *       cogl_texture_new_from_bitmap        (CoglBitmap *bitmap,
                                                             CoglTextureFlags flags,
                                                             CoglPixelFormat internal_format);
    CoglTexture *       cogl_texture_new_from_sub_texture   (CoglTexture *full_texture,
                                                             int sub_x,
                                                             int sub_y,
                                                             int sub_width,
                                                             int sub_height);
    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);
    unsigned int        cogl_texture_get_rowstride          (CoglTexture *texture);
    int                 cogl_texture_get_max_waste          (CoglTexture *texture);
    CoglBool            cogl_texture_is_sliced              (CoglTexture *texture);
    CoglBool            cogl_texture_get_gl_texture         (CoglTexture *texture,
                                                             unsigned int *out_gl_handle,
                                                             unsigned int *out_gl_target);
    int                 cogl_texture_get_data               (CoglTexture *texture,
                                                             CoglPixelFormat format,
                                                             unsigned int rowstride,
                                                             uint8_t *data);
    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);

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

### struct CoglTextureVertex

    struct CoglTextureVertex {
      float x, y, z;
      float tx, ty;

      CoglColor color;
    };

Used to specify vertex information when calling `cogl_polygon()`

float `x`; | Model x-coordinate
float `y`; | Model y-coordinate
float `z`; | Model z-coordinate
float `tx`; | Texture x-coordinate
float `ty`; | Texture y-coordinate
CoglColor `color`; | The color to use at this vertex. This is ignored if use_color is `FALSE` when calling `cogl_polygon()`

### enum CoglTextureFlags

    typedef enum {
      COGL_TEXTURE_NONE           = 0,
      COGL_TEXTURE_NO_AUTO_MIPMAP = 1 << 0,
      COGL_TEXTURE_NO_SLICING     = 1 << 1,
      COGL_TEXTURE_NO_ATLAS       = 1 << 2
    } CoglTextureFlags;

Flags to pass to the cogl_texture_new_* family of functions.

`COGL_TEXTURE_NONE` | No flags specified
`COGL_TEXTURE_NO_AUTO_MIPMAP` | Disables the automatic generation of the mipmap pyramid from the base level image whenever it is updated. The mipmaps are only generated when the texture is rendered with a mipmap filter so it should be free to leave out this flag when using other filtering modes
`COGL_TEXTURE_NO_SLICING` | Disables the slicing of the texture
`COGL_TEXTURE_NO_ATLAS` | Disables the insertion of the texture inside the texture atlas used by Cogl

Since 1.0

### cogl_texture_new_with_size ()

    CoglTexture *       cogl_texture_new_with_size          (unsigned int width,
                                                             unsigned int height,
                                                             CoglTextureFlags flags,
                                                             CoglPixelFormat internal_format);

Creates a new CoglTexture with the specified dimensions and pixel format.

The storage for the texture is not necesarily created before this function returns. The storage can be explicitly allocated using `cogl_texture_allocate()` or preferably you can let Cogl automatically allocate the storage lazily when uploading data when Cogl may know more about how the texture will be used and can optimize how it is allocated.

`width` : | width of texture in pixels.
`height` : | height of texture in pixels.
`flags` : | Optional flags for the texture, or `COGL_TEXTURE_NONE`
`internal_format` : | the CoglPixelFormat to use for the GPU storage of the texture.
Returns : | A newly created CoglTexture

Since 0.8

### cogl_texture_new_from_file ()

    CoglTexture *       cogl_texture_new_from_file          (const char *filename,
                                                             CoglTextureFlags flags,
                                                             CoglPixelFormat internal_format,
                                                             CoglError **error);

Creates a CoglTexture from an image file.

`filename` : | the file to load
`flags` : | Optional flags for the texture, or `COGL_TEXTURE_NONE`
`internal_format` : | the CoglPixelFormat to use for the GPU storage of the texture. If `COGL_PIXEL_FORMAT_ANY` is given then a premultiplied format similar to the format of the source data will be used. The default blending equations of Cogl expect premultiplied color data; the main use of passing a non-premultiplied format here is if you have non-premultiplied source data and are going to adjust the blend mode (see `cogl_material_set_blend()`) or use the data for something other than straight blending.
`error` : | return location for a CoglError or `NULL`
Returns : | A newly created CoglTexture or `NULL` on failure

Since 0.8

### cogl_texture_new_from_data ()

    CoglTexture *       cogl_texture_new_from_data          (int width,
                                                             int height,
                                                             CoglTextureFlags flags,
                                                             CoglPixelFormat format,
                                                             CoglPixelFormat internal_format,
                                                             int rowstride,
                                                             const uint8_t *data);

Creates a new CoglTexture based on data residing in memory.

`width` : | width of texture in pixels
`height` : | height of texture in pixels
`flags` : | Optional flags for the texture, or `COGL_TEXTURE_NONE`
`format` : | the CoglPixelFormat the buffer is stored in in RAM
`internal_format` : | the CoglPixelFormat that will be used for storing the buffer on the GPU. If COGL_PIXEL_FORMAT_ANY is given then a premultiplied format similar to the format of the source data will be used. The default blending equations of Cogl expect premultiplied color data; the main use of passing a non-premultiplied format here is if you have non-premultiplied source data and are going to adjust the blend mode (see `cogl_material_set_blend()`) or use the data for something other than straight blending.
`rowstride` : | the memory offset in bytes between the starts of scanlines in `data`
`data` : | pointer the memory region where the source buffer resides
Returns : | A newly created CoglTexture or `NULL` on failure

Since 0.8

### cogl_texture_new_from_foreign ()

    CoglTexture *       cogl_texture_new_from_foreign       (unsigned int gl_handle,
                                                             unsigned int gl_target,
                                                             unsigned int width,
                                                             unsigned int height,
                                                             unsigned int x_pot_waste,
                                                             unsigned int y_pot_waste,
                                                             CoglPixelFormat format);

Creates a CoglTexture based on an existing OpenGL texture; the width, height and format are passed along since it is not always possible to query these from OpenGL.

The waste arguments allow you to create a Cogl texture that maps to a region smaller than the real OpenGL texture. For instance if your hardware only supports power-of-two textures you may load a non-power-of-two image into a larger power-of-two texture and use the waste arguments to tell Cogl which region should be mapped to the texture coordinate range [0:1].

`gl_handle` : | opengl handle of foreign texture.
`gl_target` : | opengl target type of foreign texture
`width` : | width of foreign texture
`height` : | height of foreign texture.
`x_pot_waste` : | horizontal waste on the right hand edge of the texture.
`y_pot_waste` : | vertical waste on the bottom edge of the texture.
`format` : | format of the foreign texture.
Returns : | A newly created CoglTexture or `NULL` on failure

Since 0.8

### cogl_texture_new_from_bitmap ()

    CoglTexture *       cogl_texture_new_from_bitmap        (CoglBitmap *bitmap,
                                                             CoglTextureFlags flags,
                                                             CoglPixelFormat internal_format);

Creates a CoglTexture from a CoglBitmap.

`bitmap` : | A CoglBitmap pointer
`flags` : | Optional flags for the texture, or `COGL_TEXTURE_NONE`
`internal_format` : | the CoglPixelFormat to use for the GPU storage of the texture
Returns : | A newly created CoglTexture or `NULL` on failure

Since 1.0

### cogl_texture_new_from_sub_texture ()

    CoglTexture *       cogl_texture_new_from_sub_texture   (CoglTexture *full_texture,
                                                             int sub_x,
                                                             int sub_y,
                                                             int sub_width,
                                                             int sub_height);

Creates a new texture which represents a subregion of another texture. The GL resources will be shared so that no new texture data is actually allocated.

Sub textures have undefined behaviour texture coordinates outside of the range [0,1] are used. They also do not work with CoglVertexBuffers.

The sub texture will keep a reference to the full texture so you do not need to keep one separately if you only want to use the sub texture.

`full_texture` : | a CoglTexture pointer
`sub_x` : | X coordinate of the top-left of the subregion
`sub_y` : | Y coordinate of the top-left of the subregion
`sub_width` : | Width in pixels of the subregion
`sub_height` : | Height in pixels of the subregion
Returns : | A newly created CoglTexture or `NULL` on failure

Since 1.2

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

    unsigned int        cogl_texture_get_rowstride          (CoglTexture *texture);

### Warning

`cogl_texture_get_rowstride` has been deprecated since version 1.10 and should not be used in newly-written code. There's no replacement for the API but there's also no known need for API either. It was just a mistake that it was ever published.

Determines the bytes-per-pixel for the CoglPixelFormat retrieved from `cogl_texture_get_format()` and multiplies that by the texture's width.

### Note

It's very unlikely that anyone would need to use this API to query the internal rowstride of a CoglTexture which can just be considered an implementation detail. Actually it's not even useful internally since underlying drivers are free to use a different format

### Note

This API is only here for backwards compatibility and shouldn't be used in new code. In particular please don't be mislead to pass the returned value to `cogl_texture_get_data()` for the rowstride, since you should be passing the rowstride you desire for your destination buffer not the rowstride of the source texture.

Returns : | The bytes-per-pixel for the current format multiplied by the texture's width

### cogl_texture_get_max_waste ()

    int                 cogl_texture_get_max_waste          (CoglTexture *texture);

Queries the maximum wasted (unused) pixels in one dimension of a GPU side texture.

`texture` : | a CoglTexture pointer.
Returns : | the maximum waste

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

    CoglBool            cogl_texture_get_gl_texture         (CoglTexture *texture,
                                                             unsigned int *out_gl_handle,
                                                             unsigned int *out_gl_target);

Queries the GL handles for a GPU side texture through its CoglTexture.

If the texture is spliced the data for the first sub texture will be queried.

`texture` : | a CoglTexture pointer.
`out_gl_handle` : | pointer to return location for the textures GL handle, or `NULL`. [out][allow-none]
`out_gl_target` : | pointer to return location for the GL target type, or `NULL`. [out][allow-none]
Returns : | `TRUE` if the handle was successfully retrieved, `FALSE` if the handle was invalid

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