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

## Synopsis

    struct              CoglTextureVertex;
    enum                CoglTextureFlags;
    CoglHandle          cogl_texture_new_with_size          (unsigned int width,
                                                             unsigned int height,
                                                             CoglTextureFlags flags,
                                                             CoglPixelFormat internal_format);
    CoglHandle          cogl_texture_new_from_file          (const char *filename,
                                                             CoglTextureFlags flags,
                                                             CoglPixelFormat internal_format,
                                                             GError **error);
    CoglHandle          cogl_texture_new_from_data          (unsigned int width,
                                                             unsigned int height,
                                                             CoglTextureFlags flags,
                                                             CoglPixelFormat format,
                                                             CoglPixelFormat internal_format,
                                                             unsigned int rowstride,
                                                             const guint8 *data);
    CoglHandle          cogl_texture_new_from_foreign       (GLuint gl_handle,
                                                             GLenum gl_target,
                                                             GLuint width,
                                                             GLuint height,
                                                             GLuint x_pot_waste,
                                                             GLuint y_pot_waste,
                                                             CoglPixelFormat format);
    CoglHandle          cogl_texture_new_from_bitmap        (CoglHandle bmp_handle,
                                                             CoglTextureFlags flags,
                                                             CoglPixelFormat internal_format);
    CoglHandle          cogl_texture_new_from_sub_texture   (CoglHandle full_texture,
                                                             int sub_x,
                                                             int sub_y,
                                                             int sub_width,
                                                             int sub_height);
    gboolean            cogl_is_texture                     (CoglHandle handle);

    unsigned int        cogl_texture_get_width              (CoglHandle handle);
    unsigned int        cogl_texture_get_height             (CoglHandle handle);
    CoglPixelFormat     cogl_texture_get_format             (CoglHandle handle);
    unsigned int        cogl_texture_get_rowstride          (CoglHandle handle);
    int                 cogl_texture_get_max_waste          (CoglHandle handle);
    gboolean            cogl_texture_is_sliced              (CoglHandle handle);
    gboolean            cogl_texture_get_gl_texture         (CoglHandle handle,
                                                             GLuint *out_gl_handle,
                                                             GLenum *out_gl_target);
    int                 cogl_texture_get_data               (CoglHandle handle,
                                                             CoglPixelFormat format,
                                                             unsigned int rowstride,
                                                             guint8 *data);
    gboolean            cogl_texture_set_region             (CoglHandle handle,
                                                             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 GL 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 ()

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

Creates a new COGL texture with the specified dimensions and pixel format.

`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 CoglHandle to the newly created texture or `COGL_INVALID_HANDLE` on failure

Since 0.8

### cogl_texture_new_from_file ()

    CoglHandle          cogl_texture_new_from_file          (const char *filename,
                                                             CoglTextureFlags flags,
                                                             CoglPixelFormat internal_format,
                                                             GError **error);

Creates a COGL texture 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 GError or `NULL`
Returns : | a CoglHandle to the newly created texture or `COGL_INVALID_HANDLE` on failure

Since 0.8

### cogl_texture_new_from_data ()

    CoglHandle          cogl_texture_new_from_data          (unsigned int width,
                                                             unsigned int height,
                                                             CoglTextureFlags flags,
                                                             CoglPixelFormat format,
                                                             CoglPixelFormat internal_format,
                                                             unsigned int rowstride,
                                                             const guint8 *data);

Creates a new COGL texture 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 CoglHandle to the newly created texture or `COGL_INVALID_HANDLE` on failure

Since 0.8

### cogl_texture_new_from_foreign ()

    CoglHandle          cogl_texture_new_from_foreign       (GLuint gl_handle,
                                                             GLenum gl_target,
                                                             GLuint width,
                                                             GLuint height,
                                                             GLuint x_pot_waste,
                                                             GLuint y_pot_waste,
                                                             CoglPixelFormat format);

Creates a COGL texture 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 CoglHandle to the newly created texture or `COGL_INVALID_HANDLE` on failure

Since 0.8

### cogl_texture_new_from_bitmap ()

    CoglHandle          cogl_texture_new_from_bitmap        (CoglHandle bmp_handle,
                                                             CoglTextureFlags flags,
                                                             CoglPixelFormat internal_format);

Creates a COGL texture from a CoglBitmap.

`bmp_handle` : | A CoglBitmap handle
`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 CoglHandle to the newly created texture or `COGL_INVALID_HANDLE` on failure

Since 1.0

### cogl_texture_new_from_sub_texture ()

    CoglHandle          cogl_texture_new_from_sub_texture   (CoglHandle 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 CoglHandle to an existing texture
`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 CoglHandle to the new texture.

Since 1.2

### cogl_is_texture ()

    gboolean            cogl_is_texture                     (CoglHandle handle);

Gets whether the given handle references an existing texture object.

`handle` : | A CoglHandle
Returns : | `TRUE` if the handle references a texture, and `FALSE` otherwise

### cogl_texture_get_width ()

    unsigned int        cogl_texture_get_width              (CoglHandle handle);

Queries the width of a cogl texture.

`handle` : | a CoglHandle for a texture.
Returns : | the width of the GPU side texture in pixels

### cogl_texture_get_height ()

    unsigned int        cogl_texture_get_height             (CoglHandle handle);

Queries the height of a cogl texture.

`handle` : | a CoglHandle for a texture.
Returns : | the height of the GPU side texture in pixels

### cogl_texture_get_format ()

    CoglPixelFormat     cogl_texture_get_format             (CoglHandle handle);

Queries the CoglPixelFormat of a cogl texture.

`handle` : | a CoglHandle for a texture.
Returns : | the CoglPixelFormat of the GPU side texture

### cogl_texture_get_rowstride ()

    unsigned int        cogl_texture_get_rowstride          (CoglHandle handle);

Queries the rowstride of a cogl texture.

`handle` : | a CoglHandle for a texture.
Returns : | the offset in bytes between each consequetive row of pixels

### cogl_texture_get_max_waste ()

    int                 cogl_texture_get_max_waste          (CoglHandle handle);

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

`handle` : | a CoglHandle for a texture.
Returns : | the maximum waste

### cogl_texture_is_sliced ()

    gboolean            cogl_texture_is_sliced              (CoglHandle handle);

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

`handle` : | a CoglHandle for a texture.
Returns : | `TRUE` if the texture is sliced, `FALSE` if the texture is stored as a single GPU texture

### cogl_texture_get_gl_texture ()

    gboolean            cogl_texture_get_gl_texture         (CoglHandle handle,
                                                             GLuint *out_gl_handle,
                                                             GLenum *out_gl_target);

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

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

`handle` : | a CoglHandle for a texture.
`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               (CoglHandle handle,
                                                             CoglPixelFormat format,
                                                             unsigned int rowstride,
                                                             guint8 *data);

Copies the pixel data from a cogl texture to system memory.

`handle` : | a CoglHandle for a texture.
`format` : | the CoglPixelFormat to store the texture as.
`rowstride` : | the rowstride of `data` or retrieved from texture if none is specified.
`data` : | memory location to write contents of buffer, or `NULL` if we're only querying the data size through the return value.
Returns : | the size of the texture data in bytes, or 0 if the texture is not valid

### cogl_texture_set_region ()

    gboolean            cogl_texture_set_region             (CoglHandle handle,
                                                             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.

`handle` : | a CoglHandle.
`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