## Textures

Textures — Fuctions for creating and manipulating textures

## Synopsis

                        CoglTextureVertex;
    CoglHandle          cogl_texture_new_with_size          (guint width,
                                                             guint height,
                                                             gint max_waste,
                                                             gboolean auto_mipmap,
                                                             CoglPixelFormat internal_format);
    CoglHandle          cogl_texture_new_from_file          (const gchar *filename,
                                                             gint max_waste,
                                                             gboolean auto_mipmap,
                                                             CoglPixelFormat internal_format,
                                                             GError **error);
    CoglHandle          cogl_texture_new_from_data          (guint width,
                                                             guint height,
                                                             gint max_waste,
                                                             gboolean auto_mipmap,
                                                             CoglPixelFormat format,
                                                             CoglPixelFormat internal_format,
                                                             guint rowstride,
                                                             const guchar *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);
    gboolean            cogl_is_texture                     (CoglHandle handle);
    guint               cogl_texture_get_width              (CoglHandle handle);
    guint               cogl_texture_get_height             (CoglHandle handle);
    CoglPixelFormat     cogl_texture_get_format             (CoglHandle handle);
    guint               cogl_texture_get_rowstride          (CoglHandle handle);
    gint                cogl_texture_get_max_waste          (CoglHandle handle);
    COGLenum            cogl_texture_get_min_filter         (CoglHandle handle);
    COGLenum            cogl_texture_get_mag_filter         (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);
    gint                cogl_texture_get_data               (CoglHandle handle,
                                                             CoglPixelFormat format,
                                                             guint rowstride,
                                                             guchar *data);
    void                cogl_texture_set_filters            (CoglHandle handle,
                                                             COGLenum min_filter,
                                                             COGLenum mag_filter);
    gboolean            cogl_texture_set_region             (CoglHandle handle,
                                                             gint src_x,
                                                             gint src_y,
                                                             gint dst_x,
                                                             gint dst_y,
                                                             guint dst_width,
                                                             guint dst_height,
                                                             gint width,
                                                             gint height,
                                                             CoglPixelFormat format,
                                                             guint rowstride,
                                                             const guchar *data);
    CoglHandle          cogl_texture_ref                    (CoglHandle handle);
    void                cogl_texture_unref                  (CoglHandle handle);
    void                cogl_texture_rectangle              (CoglHandle handle,
                                                             ClutterFixed x1,
                                                             ClutterFixed y1,
                                                             ClutterFixed x2,
                                                             ClutterFixed y2,
                                                             ClutterFixed tx1,
                                                             ClutterFixed ty1,
                                                             ClutterFixed tx2,
                                                             ClutterFixed ty2);
    void                cogl_texture_multiple_rectangles    (CoglHandle handle,
                                                             const ClutterFixed *verts,
                                                             guint n_rects);
    void                cogl_texture_polygon                (CoglHandle handle,
                                                             guint n_vertices,
                                                             CoglTextureVertex *vertices,
                                                             gboolean use_color);

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

### CoglTextureVertex

    typedef struct {
      ClutterFixed x, y, z;
      ClutterFixed tx, ty;
      ClutterColor color;
    } CoglTextureVertex;

Used to specify vertex information when calling `cogl_texture_polygon()`.

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

### cogl_texture_new_with_size ()

    CoglHandle          cogl_texture_new_with_size          (guint width,
                                                             guint height,
                                                             gint max_waste,
                                                             gboolean auto_mipmap,
                                                             CoglPixelFormat internal_format);

Create a new texture with specified dimensions and pixel format.

`width` : | width of texture in pixels.
`height` : | height of texture in pixels.
`max_waste` : | maximum extra horizontal and|or vertical margin pixels to make texture fit GPU limitations.
`auto_mipmap` : | enable or disable automatic generation of mipmap pyramid from the base level image whenever it is updated.
`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 if texture creation failed.

### cogl_texture_new_from_file ()

    CoglHandle          cogl_texture_new_from_file          (const gchar *filename,
                                                             gint max_waste,
                                                             gboolean auto_mipmap,
                                                             CoglPixelFormat internal_format,
                                                             GError **error);

Load an image file from disk.

`filename` : | the file to load
`max_waste` : | maximum extra horizontal and|or vertical margin pixels to make texture fit GPU limitations.
`auto_mipmap` : | enable or disable automatic generation of mipmap pyramid from the base level image whenever it is updated.
`internal_format` : | the CoglPixelFormat to use for the GPU storage of the texture.
`error` : | a GError or NULL.
Returns : | a CoglHandle to the newly created texture or COGL_INVALID_HANDLE if creating the texture failed.

### cogl_texture_new_from_data ()

    CoglHandle          cogl_texture_new_from_data          (guint width,
                                                             guint height,
                                                             gint max_waste,
                                                             gboolean auto_mipmap,
                                                             CoglPixelFormat format,
                                                             CoglPixelFormat internal_format,
                                                             guint rowstride,
                                                             const guchar *data);

Create a new cogl texture based on data residing in memory.

`width` : | width of texture in pixels.
`height` : | height of texture in pixels.
`max_waste` : | maximum extra horizontal and|or vertical margin pixels to make
`auto_mipmap` : | enable or disable automatic generation of mipmap pyramid from the base level image whenever it is updated.
`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.
`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 if creating the texture failed.

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

Create a cogl texture based on an existing OpenGL texture, the width, height and format are passed along since it is not possible to query this from a handle with GLES 1.0.

`gl_handle` : | opengl target type of foreign texture
`gl_target` : | opengl handle of foreign texture.
`width` : | width of foreign texture
`height` : | height of foreign texture.
`x_pot_waste` : | maximum horizontal waste.
`y_pot_waste` : | maximum vertical waste.
`format` : | format of the foreign texture.
Returns : | a CoglHandle to the newly created texture or COGL_INVALID_HANDLE if creating the texture failed.

### 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, `FALSE` otherwise

### cogl_texture_get_width ()

    guint               cogl_texture_get_width              (CoglHandle handle);

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

    guint               cogl_texture_get_height             (CoglHandle handle);

Query 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);

Query the CoglPixelFormat of a cogl texture.

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

### cogl_texture_get_rowstride ()

    guint               cogl_texture_get_rowstride          (CoglHandle handle);

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

    gint                cogl_texture_get_max_waste          (CoglHandle handle);

Query 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_get_min_filter ()

    COGLenum            cogl_texture_get_min_filter         (CoglHandle handle);

Query the currently set downscaling filter for a cogl texture.

`handle` : | a CoglHandle for a texture.
Returns : | the current downscaling filter for a cogl texture.

### cogl_texture_get_mag_filter ()

    COGLenum            cogl_texture_get_mag_filter         (CoglHandle handle);

Query the currently set downscaling filter for a cogl texture.

`handle` : | a CoglHandle for a texture.
Returns : | the current downscaling filter for a cogl texture.

### cogl_texture_is_sliced ()

    gboolean            cogl_texture_is_sliced              (CoglHandle handle);

Query 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);

Query the GL handles for a GPU side texture through it's 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_gl_target` : | pointer to return location for the GL target type, or NULL.
Returns : | `TRUE` if the handle was successfully retrieved `FALSE` if the handle was invalid.

### cogl_texture_get_data ()

    gint                cogl_texture_get_data               (CoglHandle handle,
                                                             CoglPixelFormat format,
                                                             guint rowstride,
                                                             guchar *data);

Copy 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_filters ()

    void                cogl_texture_set_filters            (CoglHandle handle,
                                                             COGLenum min_filter,
                                                             COGLenum mag_filter);

Changes the decimation and interpolation filters used when the texture is drawn at other scales than 100%.

`handle` : | a CoglHandle.
`min_filter` : | the filter used when scaling the texture down.
`mag_filter` : | the filter used when magnifying the texture.

### cogl_texture_set_region ()

    gboolean            cogl_texture_set_region             (CoglHandle handle,
                                                             gint src_x,
                                                             gint src_y,
                                                             gint dst_x,
                                                             gint dst_y,
                                                             guint dst_width,
                                                             guint dst_height,
                                                             gint width,
                                                             gint height,
                                                             CoglPixelFormat format,
                                                             guint rowstride,
                                                             const guchar *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, otherwise `FALSE`.

### cogl_texture_ref ()

    CoglHandle          cogl_texture_ref                    (CoglHandle handle);

Increment the reference count for a cogl texture.

`handle` : | a `CoglHandle`.
Returns : | the `handle`.

### cogl_texture_unref ()

    void                cogl_texture_unref                  (CoglHandle handle);

Deccrement the reference count for a cogl texture.

`handle` : | a `CoglHandle`.

### cogl_texture_rectangle ()

    void                cogl_texture_rectangle              (CoglHandle handle,
                                                             ClutterFixed x1,
                                                             ClutterFixed y1,
                                                             ClutterFixed x2,
                                                             ClutterFixed y2,
                                                             ClutterFixed tx1,
                                                             ClutterFixed ty1,
                                                             ClutterFixed tx2,
                                                             ClutterFixed ty2);

Draw a rectangle from a texture to the display, to draw the entire texture pass in `tx1`=0.0 `ty1`=0.0 `tx2`=1.0 `ty2`=1.0.

`handle` : | a `CoglHandle`.
`x1` : | x coordinate upper left on screen.
`y1` : | y coordinate upper left on screen.
`x2` : | x coordinate lower right on screen.
`y2` : | y coordinate lower right on screen.
`tx1` : | x part of texture coordinate to use for upper left pixel
`ty1` : | y part of texture coordinate to use for upper left pixel
`tx2` : | x part of texture coordinate to use for lower right pixel
`ty2` : | y part of texture coordinate to use for left pixel

### cogl_texture_multiple_rectangles ()

    void                cogl_texture_multiple_rectangles    (CoglHandle handle,
                                                             const ClutterFixed *verts,
                                                             guint n_rects);

Draws a series of rectangles in the same way that `cogl_texture_rectangle()` does. In some situations it can give a significant performance boost to use this function rather than calling `cogl_texture_rectangle()` separately for each rectangle.

`verts` should point to an array of CoglFixeds with `n_rects` * 8 elements. Each group of 8 values corresponds to the parameters x1, y1, x2, y2, tx1, ty1, tx2 and ty2 and have the same meaning as in `cogl_texture_rectangle()`.

`handle` : | a `CoglHandle`.
`verts` : | an array of vertices
`n_rects` : | number of rectangles to draw

Since 0.8.6

### cogl_texture_polygon ()

    void                cogl_texture_polygon                (CoglHandle handle,
                                                             guint n_vertices,
                                                             CoglTextureVertex *vertices,
                                                             gboolean use_color);

Draws a polygon from a texture with the given model and texture coordinates. This can be used to draw arbitrary shapes textured with a COGL texture. If `use_color` is `TRUE` then the current COGL color will be changed for each vertex using the value specified in the color member of CoglTextureVertex. This can be used for example to make the texture fade out by setting the alpha value of the color.

All of the texture coordinates must be in the range [0,1] and repeating the texture is not supported.

Because of the way this function is implemented it will currently only work if either the texture is not sliced or the backend is not OpenGL ES and the minifying and magnifying functions are both set to CGL_NEAREST.

`handle` : | A CoglHandle for a texture
`n_vertices` : | The length of the vertices array
`vertices` : | An array of CoglTextureVertex structs
`use_color` : | `TRUE` if the color member of CoglTextureVertex should be used