CoglBuffer: The Buffer Interface

CoglBuffer: The Buffer Interface — Common buffer functions, including data upload APIs

Stability Level

Unstable, unless otherwise indicated

Synopsis

gboolean            cogl_is_buffer                      (const void *object);
unsigned int        cogl_buffer_get_size                (CoglBuffer *buffer);
#define             cogl_buffer_set_usage_hint
#define             cogl_buffer_get_usage_hint
enum                CoglBufferUpdateHint;
void                cogl_buffer_set_update_hint         (CoglBuffer *buffer,
                                                         CoglBufferUpdateHint hint);
CoglBufferUpdateHint  cogl_buffer_get_update_hint       (CoglBuffer *buffer);
enum                CoglBufferAccess;
void *              cogl_buffer_map                     (CoglBuffer *buffer,
                                                         CoglBufferAccess access,
                                                         CoglBufferMapHint hints);
void                cogl_buffer_unmap                   (CoglBuffer *buffer);
gboolean            cogl_buffer_set_data                (CoglBuffer *buffer,
                                                         gsize offset,
                                                         const void *data,
                                                         gsize size);

#define             cogl_pixel_buffer_new
gboolean            cogl_is_pixel_buffer                (void *object);

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

The CoglBuffer API provides a common interface to manipulate buffers that have been allocated either via cogl_pixel_buffer_new() or cogl_attribute_buffer_new(). The API allows you to upload data to these buffers and define usage hints that help Cogl manage your buffer optimally.

Data can either be uploaded by supplying a pointer and size so Cogl can copy your data, or you can mmap() a CoglBuffer and then you can copy data to the buffer directly.

One of the most common uses for CoglBuffers is to upload texture data asynchronously since the ability to mmap the buffers into the CPU makes it possible for another thread to handle the IO of loading an image file and unpacking it into the mapped buffer without blocking other Cogl operations.

Details

cogl_is_buffer ()

gboolean            cogl_is_buffer                      (const void *object);

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

unsigned int        cogl_buffer_get_size                (CoglBuffer *buffer);

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

void                cogl_buffer_set_update_hint         (CoglBuffer *buffer,
                                                         CoglBufferUpdateHint hint);

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

CoglBufferUpdateHint  cogl_buffer_get_update_hint       (CoglBuffer *buffer);

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

void *              cogl_buffer_map                     (CoglBuffer *buffer,
                                                         CoglBufferAccess access,
                                                         CoglBufferMapHint hints);

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

void                cogl_buffer_unmap                   (CoglBuffer *buffer);

Unmaps a buffer previously mapped by cogl_buffer_map().

buffer :

a buffer object

Since 1.2

Stability Level: Unstable


cogl_buffer_set_data ()

gboolean            cogl_buffer_set_data                (CoglBuffer *buffer,
                                                         gsize offset,
                                                         const void *data,
                                                         gsize size);

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_pixel_buffer_new

#define cogl_pixel_buffer_new cogl_pixel_buffer_new_EXP

cogl_is_pixel_buffer ()

gboolean            cogl_is_pixel_buffer                (void *object);

Checks whether handle is a pixel array.

object :

a CoglObject to test

Returns :

TRUE if the handle is a pixel array, and 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