Buffers

Buffers — Buffer creation and manipulation

Stability Level

Unstable, unless otherwise indicated

Synopsis

#define             cogl_is_buffer
#define             cogl_buffer_get_size
#define             cogl_buffer_set_usage_hint
#define             cogl_buffer_get_usage_hint
enum                CoglBufferUpdateHint;
#define             cogl_buffer_set_update_hint
#define             cogl_buffer_get_update_hint
enum                CoglBufferAccess;
#define             cogl_buffer_map
#define             cogl_buffer_unmap
#define             cogl_buffer_set_data


CoglHandle          cogl_texture_new_from_buffer        (CoglHandle buffer,
                                                         unsigned int width,
                                                         unsigned int height,
                                                         CoglTextureFlags flags,
                                                         CoglPixelFormat format,
                                                         CoglPixelFormat internal_format,
                                                         unsigned int rowstride,
                                                         unsigned int offset);

Description

COGL allows the creation and the manipulation of buffers. If the underlying OpenGL implementation allows it, COGL will use Pixel Buffer Objects.

Details

cogl_is_buffer

#define cogl_is_buffer  cogl_is_buffer_EXP

Checks whether buffer is a buffer object.

buffer :

a buffer object

Returns :

TRUE if the handle is a CoglBuffer, and FALSE otherwise

Since 1.2

Stability Level: Unstable


cogl_buffer_get_size

#define cogl_buffer_get_size cogl_buffer_get_size_EXP

Retrieves the size of buffer

buffer :

a buffer object

Returns :

the size of the buffer in bytes

Since 1.2

Stability Level: Unstable


cogl_buffer_set_usage_hint

#define cogl_buffer_set_usage_hint cogl_buffer_set_usage_hint_EXP

cogl_buffer_get_usage_hint

#define cogl_buffer_get_usage_hint cogl_buffer_get_usage_hint_EXP

enum CoglBufferUpdateHint

typedef enum { /*< prefix=COGL_BUFFER_UPDATE_HINT >*/
  COGL_BUFFER_UPDATE_HINT_STATIC,
  COGL_BUFFER_UPDATE_HINT_DYNAMIC,
  COGL_BUFFER_UPDATE_HINT_STREAM
} CoglBufferUpdateHint;

The update hint on a buffer allows the user to give some detail on how often the buffer data is going to be updated.

COGL_BUFFER_UPDATE_HINT_STATIC

the buffer will not change over time

COGL_BUFFER_UPDATE_HINT_DYNAMIC

the buffer will change from time to time

COGL_BUFFER_UPDATE_HINT_STREAM

the buffer will be used once or a couple of times

Since 1.2

Stability Level: Unstable


cogl_buffer_set_update_hint

#define cogl_buffer_set_update_hint cogl_buffer_set_update_hint_EXP

Sets the update hint on a buffer. See CoglBufferUpdateHint for a description of the available hints.

buffer :

a buffer object

hint :

the new hint

Since 1.2

Stability Level: Unstable


cogl_buffer_get_update_hint

#define cogl_buffer_get_update_hint cogl_buffer_get_update_hint_EXP

Retrieves the update hints set using cogl_buffer_set_update_hint()

buffer :

a buffer object

Returns :

the CoglBufferUpdateHint currently used by the buffer

Since 1.2

Stability Level: Unstable


enum CoglBufferAccess

typedef enum { /*< prefix=COGL_BUFFER_ACCESS >*/
 COGL_BUFFER_ACCESS_READ       = 1 << 0,
 COGL_BUFFER_ACCESS_WRITE      = 1 << 1,
 COGL_BUFFER_ACCESS_READ_WRITE = COGL_BUFFER_ACCESS_READ | COGL_BUFFER_ACCESS_WRITE
} CoglBufferAccess;

The access hints for cogl_buffer_set_update_hint()

COGL_BUFFER_ACCESS_READ

the buffer will be read

COGL_BUFFER_ACCESS_WRITE

the buffer will written to

COGL_BUFFER_ACCESS_READ_WRITE

the buffer will be used for both reading and writing

Since 1.2

Stability Level: Unstable


cogl_buffer_map

#define cogl_buffer_map cogl_buffer_map_EXP

Maps the buffer into the application address space for direct access.

It is strongly recommended that you pass COGL_BUFFER_MAP_HINT_DISCARD as a hint if you are going to replace all the buffer's data. This way if the buffer is currently being used by the GPU then the driver won't have to stall the CPU and wait for the hardware to finish because it can instead allocate a new buffer to map.

The behaviour is undefined if you access the buffer in a way conflicting with the access mask you pass. It is also an error to release your last reference while the buffer is mapped.

buffer :

a buffer object

access :

how the mapped buffer will be used by the application

hints :

A mask of CoglBufferMapHints that tell Cogl how the data will be modified once mapped.

Returns :

A pointer to the mapped memory or NULL is the call fails

Since 1.2

Stability Level: Unstable


cogl_buffer_unmap

#define cogl_buffer_unmap cogl_buffer_unmap_EXP

Unmaps a buffer previously mapped by cogl_buffer_map().

buffer :

a buffer object

Since 1.2

Stability Level: Unstable


cogl_buffer_set_data

#define cogl_buffer_set_data cogl_buffer_set_data_EXP

Updates part of the buffer with new data from data. Where to put this new data is controlled by offset and offset + data should be less than the buffer size.

buffer :

a buffer object

offset :

destination offset (in bytes) in the buffer

data :

a pointer to the data to be copied into the buffer

size :

number of bytes to copy

Returns :

TRUE is the operation succeeded, FALSE otherwise

Since 1.2

Stability Level: Unstable


cogl_texture_new_from_buffer ()

CoglHandle          cogl_texture_new_from_buffer        (CoglHandle buffer,
                                                         unsigned int width,
                                                         unsigned int height,
                                                         CoglTextureFlags flags,
                                                         CoglPixelFormat format,
                                                         CoglPixelFormat internal_format,
                                                         unsigned int rowstride,
                                                         unsigned int offset);

Creates a new texture using the buffer specified by handle. If the buffer has been created using cogl_pixel_buffer_new_for_size() it's possible to omit the height and width values already specified at creation time.

buffer :

the CoglHandle of a pixel buffer

width :

width of texture in pixels or 0

height :

height of texture in pixels or 0

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. If 0 is given the row stride will be deduced from width and format or the stride given by cogl_pixel_buffer_new_for_size()

offset :

offset in bytes in buffer from where the texture data starts

Returns :

a CoglHandle to the new texture or COGL_INVALID_HANDLE on failure

Since 1.2

Stability Level: Unstable