2D textures

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

Synopsis

                    CoglTexture2D;
#define             cogl_texture_2d_new_with_size
CoglTexture2D *     cogl_texture_2d_new_from_bitmap     (CoglBitmap *bitmap,
                                                         CoglPixelFormat internal_format,
                                                         GError **error);
#define             cogl_texture_2d_new_from_data
#define             cogl_texture_2d_new_from_foreign
#define             cogl_is_texture_rectangle

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

Details

CoglTexture2D

typedef struct _CoglTexture2D CoglTexture2D;

cogl_texture_2d_new_with_size

#define cogl_texture_2d_new_with_size cogl_texture_2d_new_with_size_EXP

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.

Note

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

ctx :

A CoglContext

width :

Width of the texture to allocate

height :

Height of the texture to allocate

internal_format :

The format of the texture

error :

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

Since 2.0


cogl_texture_2d_new_from_bitmap ()

CoglTexture2D *     cogl_texture_2d_new_from_bitmap     (CoglBitmap *bitmap,
                                                         CoglPixelFormat internal_format,
                                                         GError **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.

Note

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

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

Since 2.0

Stability Level: Unstable


cogl_texture_2d_new_from_data

#define cogl_texture_2d_new_from_data cogl_texture_2d_new_from_data_EXP

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.

Note

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

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

Since 2.0


cogl_texture_2d_new_from_foreign

#define cogl_texture_2d_new_from_foreign cogl_texture_2d_new_from_foreign_EXP

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

Note

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

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

internal_format :

The format of the texture

error :

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

Since 2.0


cogl_is_texture_rectangle

#define cogl_is_texture_rectangle cogl_is_texture_rectangle_EXP

Gets whether the given object references an existing CoglTextureRectangle object.

object :

A CoglObject

Returns :

TRUE if the object references a CoglTextureRectangle, FALSE otherwise.