Textures

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

## Functions

CoglTexture * | cogl_texture_new_with_size ()
CoglTexture * | cogl_texture_new_from_file ()
CoglTexture * | cogl_texture_new_from_data ()
CoglTexture * | cogl_texture_new_from_foreign ()
CoglTexture * | cogl_texture_new_from_bitmap ()
CoglTexture * | cogl_texture_new_from_sub_texture ()
CoglBool | cogl_is_texture ()
unsigned int | cogl_texture_get_width ()
unsigned int | cogl_texture_get_height ()
CoglPixelFormat | cogl_texture_get_format ()
unsigned int | cogl_texture_get_rowstride ()
int | cogl_texture_get_max_waste ()
CoglBool | cogl_texture_is_sliced ()
CoglBool | cogl_texture_get_gl_texture ()
int | cogl_texture_get_data ()
CoglBool | cogl_texture_set_region ()

## Types and Values

struct | CoglTextureVertex
enum | CoglTextureFlags

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

## Functions

### cogl_texture_new_with_size ()

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

`cogl_texture_new_with_size` has been deprecated since version 1.18 and should not be used in newly-written code.

Use specific constructors such as `cogl_texture_2d_new_with_size()`

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

#### Parameters

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 or `NULL` on failure.

[transfer full]

Since 0.8

### cogl_texture_new_from_file ()

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

`cogl_texture_new_from_file` has been deprecated since version 1.18 and should not be used in newly-written code.

Use specific constructors such as `cogl_texture_2d_new_from_file()`

Creates a CoglTexture from an image file.

#### Parameters

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.

[transfer full]

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

`cogl_texture_new_from_data` has been deprecated since version 1.18 and should not be used in newly-written code.

Use specific constructors such as `cogl_texture_2d_new_from_data()`

Creates a new CoglTexture based on data residing in memory.

#### Parameters

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.

[transfer full]

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

`cogl_texture_new_from_foreign` has been deprecated since version 1.18 and should not be used in newly-written code.

Use specific constructors such as `cogl_texture_2d_new_from_foreign()`

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].

#### Parameters

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.

[transfer full]

Since 0.8

### cogl_texture_new_from_bitmap ()

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

`cogl_texture_new_from_bitmap` has been deprecated since version 1.18 and should not be used in newly-written code.

Use specific constructors such as `cogl_texture_2d_new_from_bitmap()`

Creates a CoglTexture from a CoglBitmap.

#### Parameters

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.

[transfer full]

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

`cogl_texture_new_from_sub_texture` has been deprecated since version 1.18 and should not be used in newly-written code.

Use `cogl_sub_texture_new()`

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.

#### Parameters

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.

[transfer full]

Since 1.2

### cogl_is_texture ()

    CoglBool
    cogl_is_texture (void *object);

Gets whether the given object references a texture object.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

`cogl_texture_get_format` has been deprecated since version 1.18 and should not be used in newly-written code.

This api is misleading

Queries the CoglPixelFormat of a cogl texture.

#### Parameters

texture | a CoglTexture pointer. |

#### Returns

the CoglPixelFormat of the GPU side texture

### cogl_texture_get_rowstride ()

    unsigned int
    cogl_texture_get_rowstride (CoglTexture *texture);

`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.

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

#### Parameters

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).

#### Parameters

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.

#### Parameters

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.

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

#### Parameters

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.

The region set can't be larger than the source `data`

#### Parameters

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

## Types and Values

### struct CoglTextureVertex

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

      CoglColor color;
    };

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

#### Members

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

Flags to pass to the cogl_texture_new_* family of functions.

#### Members

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