Textures

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_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
} 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 : out) (allow-none. out. allow-none.
out_gl_target : out) (allow-none. out. allow-none.
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.
Generated by GTK-Doc V1.11