Textures
3
COGL Library

# Textures

Fuctions for creating and manipulating textures

## Synopsis

                        CoglTextureVertex;
    enum                CoglTextureFlags;
    CoglHandle          cogl_texture_new_with_size          (guint width,
                                                             guint height,
                                                             CoglTextureFlags flags,
                                                             CoglPixelFormat internal_format);
    CoglHandle          cogl_texture_new_from_file          (const gchar *filename,
                                                             CoglTextureFlags flags,
                                                             CoglPixelFormat internal_format,
                                                             GError **error);
    CoglHandle          cogl_texture_new_from_data          (guint width,
                                                             guint height,
                                                             CoglTextureFlags flags,
                                                             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);
    CoglHandle          cogl_texture_new_from_bitmap        (CoglHandle bmp_handle,
                                                             CoglTextureFlags flags,
                                                             CoglPixelFormat internal_format);
    gboolean            cogl_is_texture                     (CoglHandle handle);
    CoglHandle          cogl_texture_ref                    (CoglHandle handle);
    void                cogl_texture_unref                  (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);
    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);
    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);

## 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 {
      float x, y, z;
      float tx, ty;
      CoglColor color;
    } CoglTextureVertex;

Used to specify vertex information when calling `cogl_texture_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_texture_polygon()`.

### enum CoglTextureFlags

    typedef enum {
      COGL_TEXTURE_NONE           = 0,
      COGL_TEXTURE_NO_AUTO_MIPMAP = 1 << 0,
      COGL_TEXTURE_NO_SLICING     = 1 << 1
    } 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

Since 1.0

### cogl_texture_new_with_size ()

    CoglHandle          cogl_texture_new_with_size          (guint width,
                                                             guint 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 gchar *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          (guint width,
                                                             guint height,
                                                             CoglTextureFlags flags,
                                                             CoglPixelFormat format,
                                                             CoglPixelFormat internal_format,
                                                             guint rowstride,
                                                             const guchar *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 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` 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_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_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_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_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_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`.