Cogl 2.0 Reference Manual: 2D textures

2D textures

2D textures — Functions for creating and manipulating 2D textures

Functions

CoglTexture2D *	cogl_texture_2d_new_with_size ()
CoglTexture2D *	cogl_texture_2d_new_from_file ()
CoglTexture2D *	cogl_texture_2d_new_from_bitmap ()
CoglTexture2D *	cogl_texture_2d_new_from_data ()
CoglTexture2D *	cogl_texture_2d_new_from_foreign ()
CoglBool	cogl_is_texture_rectangle ()

Types and Values

CoglTexture2D

Object Hierarchy

Description

These functions allow low-level 2D textures to be allocated. These differ from sliced textures for example which may internally be made up of multiple 2D textures, or atlas textures where Cogl must internally modify user texture coordinates before they can be used by the GPU.

You should be aware that many GPUs only support power of two sizes for CoglTexture2D textures. You can check support for non power of two textures by checking for the COGL_FEATURE_ID_TEXTURE_NPOT feature via cogl_has_feature().

Functions

cogl_texture_2d_new_with_size ()

CoglTexture2D *
cogl_texture_2d_new_with_size (CoglContext *ctx,
                               int width,
                               int height,
                               CoglPixelFormat internal_format);

Allocates a low-level CoglTexture2D texture that your GPU can texture from directly. This is unlike sliced textures for example which may be comprised of multiple internal textures, or atlas textures where Cogl has to modify texture coordinates before they may be used by the GPU.

The storage for the texture is not allocated before this function returns. You can call cogl_texture_allocate() to explicitly allocate the underlying storage or preferably let Cogl automatically allocate storage lazily when it may know more about how the texture is being used and can optimize how it is allocated.

Many GPUs only support power of two sizes for CoglTexture2D textures. You can check support for non power of two textures by checking for the COGL_FEATURE_ID_TEXTURE_NPOT feature via cogl_has_feature().

Parameters

ctx	A CoglContext
width	Width of the texture to allocate
height	Height of the texture to allocate
internal_format	The format of the texture

Returns

A new CoglTexture2D object with no storage yet allocated.

[transfer full]

Since 2.0

cogl_texture_2d_new_from_file ()

CoglTexture2D *
cogl_texture_2d_new_from_file (CoglContext *ctx,
                               const char *filename,
                               CoglPixelFormat internal_format,
                               CoglError **error);

Creates a CoglTexture2D from an image file.

Parameters

ctx	A CoglContext
filename	the file to load
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	A CoglError to catch exceptional errors or `NULL`

Returns

A newly created CoglTexture2D or NULL on failure and error will be updated.

[transfer full]

Since 1.16

cogl_texture_2d_new_from_bitmap ()

CoglTexture2D *
cogl_texture_2d_new_from_bitmap (CoglBitmap *bitmap,
                                 CoglPixelFormat internal_format,
                                 CoglError **error);

Creates a new CoglTexture2D texture based on data residing in a bitmap. These are unlike sliced textures for example which may be comprised of multiple internal textures, or atlas textures where Cogl has to modify texture coordinates before they may be used by the GPU.

Parameters

bitmap	A CoglBitmap
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_pipeline_set_blend()`) or use the data for something other than straight blending.
error	A CoglError for exceptions

Returns

A newly allocated CoglTexture2D, or if the size is not supported (because it is too large or a non-power-of-two size that the hardware doesn't support) it will return NULL and set error .

[transfer full]

Since 2.0

Stability Level: Unstable

cogl_texture_2d_new_from_data ()

CoglTexture2D *
cogl_texture_2d_new_from_data (CoglContext *ctx,
                               int width,
                               int height,
                               CoglPixelFormat format,
                               CoglPixelFormat internal_format,
                               int rowstride,
                               const uint8_t *data,
                               CoglError **error);

Creates a new CoglTexture2D texture based on data residing in memory. These are unlike sliced textures for example which may be comprised of multiple internal textures, or atlas textures where Cogl has to modify texture coordinates before they may be used by the GPU.

Parameters

ctx	A CoglContext
width	width of texture in pixels
height	height of texture in pixels
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_pipeline_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` . A value of 0 will make Cogl automatically calculate `rowstride` from `width` and `format` .
data	pointer the memory region where the source buffer resides
error	A CoglError for exceptions

Returns

A newly allocated CoglTexture2D, or if the size is not supported (because it is too large or a non-power-of-two size that the hardware doesn't support) it will return NULL and set error .

[transfer full]

Since 2.0

cogl_texture_2d_new_from_foreign ()

CoglTexture2D *
cogl_texture_2d_new_from_foreign (CoglContext *ctx,
                                  unsigned int gl_handle,
                                  int width,
                                  int height,
                                  CoglPixelFormat format,
                                  CoglError **error);

Wraps an existing GL_TEXTURE_2D texture object as a CoglTexture2D. This can be used for integrating Cogl with software using OpenGL directly.

The results are undefined for passing an invalid gl_handle or if width or height don't have the correct texture geometry.

Parameters

ctx	A CoglContext
gl_handle	A GL handle for a GL_TEXTURE_2D texture object
width	Width of the foreign GL texture
height	Height of the foreign GL texture
format	The format of the texture
error	A CoglError for exceptions

Returns

A newly allocated CoglTexture2D, or if Cogl could not validate the gl_handle in some way (perhaps because of an unsupported format) it will return NULL and set error .

[transfer full]

Since 2.0

cogl_is_texture_rectangle ()

CoglBool
cogl_is_texture_rectangle (void *object);

Gets whether the given object references an existing CoglTextureRectangle object.

Parameters

object

A CoglObject

Returns

TRUE if the object references a CoglTextureRectangle, FALSE otherwise.

Types and Values

CoglTexture2D

typedef struct _CoglTexture2D CoglTexture2D;