Textures

Textures — 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