Buffers

Buffers — Buffer creation and manipulation

Stability Level

Unstable, unless otherwise indicated

Synopsis

gboolean            cogl_is_buffer                      (CoglHandle handle);
guint               cogl_buffer_get_size                (CoglHandle handle);
enum                CoglBufferUsageHint;
void                cogl_buffer_set_usage_hint          (CoglHandle handle,
                                                         CoglBufferUsageHint hint);
CoglBufferUsageHint  cogl_buffer_get_usage_hint         (CoglHandle handle);
enum                CoglBufferUpdateHint;
void                cogl_buffer_set_update_hint         (CoglHandle handle,
                                                         CoglBufferUpdateHint hint);
CoglBufferUpdateHint  cogl_buffer_get_update_hint       (CoglHandle handle);
enum                CoglBufferAccess;
guchar *            cogl_buffer_map                     (CoglHandle handle,
                                                         CoglBufferAccess access);
void                cogl_buffer_unmap                   (CoglHandle handle);
gboolean            cogl_buffer_set_data                (CoglHandle handle,
                                                         gsize offset,
                                                         const guchar *data,
                                                         gsize size);

CoglHandle          cogl_pixel_buffer_new               (guint size);
CoglHandle          cogl_pixel_buffer_new_for_size      (guint width,
                                                         guint height,
                                                         CoglPixelFormat format,
                                                         guint *stride);
gboolean            cogl_is_pixel_buffer                (CoglHandle handle);

CoglHandle          cogl_texture_new_from_buffer        (CoglHandle buffer,
                                                         guint width,
                                                         guint height,
                                                         CoglTextureFlags flags,
                                                         CoglPixelFormat format,
                                                         CoglPixelFormat internal_format,
                                                         guint rowstride,
                                                         guint 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 ()

gboolean            cogl_is_buffer                      (CoglHandle handle);

Checks whether handle is a buffer handle.

handle :

a CoglHandle to test

Returns :

TRUE if the handle is a CoglBuffer, and FALSE otherwise

Since 1.2

Stability Level: Unstable


cogl_buffer_get_size ()

guint               cogl_buffer_get_size                (CoglHandle handle);

Retrieves the size of buffer

handle :

a buffer handle

Returns :

the size of the buffer in bytes

Since 1.2

Stability Level: Unstable


enum CoglBufferUsageHint

typedef enum { /*< prefix=COGL_BUFFER_USAGE_HINT >*/
 COGL_BUFFER_USAGE_HINT_TEXTURE,
} CoglBufferUsageHint;

The usage hint on a buffer allows the user to give some clue on how the buffer will be used.

COGL_BUFFER_USAGE_HINT_TEXTURE

the buffer will be used as a source data for a texture

Since 1.2

Stability Level: Unstable


cogl_buffer_set_usage_hint ()

void                cogl_buffer_set_usage_hint          (CoglHandle handle,
                                                         CoglBufferUsageHint hint);

Set the usage hint on a buffer. See CoglBufferUsageHint for a description of the available hints.

handle :

a buffer handle

hint :

the new hint

Since 1.2

Stability Level: Unstable


cogl_buffer_get_usage_hint ()

CoglBufferUsageHint  cogl_buffer_get_usage_hint         (CoglHandle handle);

handle :

a buffer handle

Returns :

the CoglBufferUsageHint currently used by the buffer

Since 1.2

Stability Level: Unstable


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 clue 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         (CoglHandle handle,
                                                         CoglBufferUpdateHint hint);

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

handle :

a buffer handle

hint :

the new hint

Since 1.2

Stability Level: Unstable


cogl_buffer_get_update_hint ()

CoglBufferUpdateHint  cogl_buffer_get_update_hint       (CoglHandle handle);

handle :

a buffer handle

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;

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

guchar *            cogl_buffer_map                     (CoglHandle handle,
                                                         CoglBufferAccess access);

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

handle :

a buffer handle

access :

how the mapped buffer will by use by the application

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                   (CoglHandle handle);

Unmaps a buffer previously mapped by cogl_buffer_map().

handle :

a buffer handle

Since 1.2

Stability Level: Unstable


cogl_buffer_set_data ()

gboolean            cogl_buffer_set_data                (CoglHandle handle,
                                                         gsize offset,
                                                         const guchar *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.

handle :

a buffer handle

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

CoglHandle          cogl_pixel_buffer_new               (guint size);

Creates a new buffer to store pixel data. You can create a new texture from this buffer using cogl_texture_new_from_buffer().

size :

size of the buffer in bytes

Returns :

a CoglHandle representing the newly created buffer or COGL_INVALID_HANDLE on failure

Since 1.2

Stability Level: Unstable


cogl_pixel_buffer_new_for_size ()

CoglHandle          cogl_pixel_buffer_new_for_size      (guint width,
                                                         guint height,
                                                         CoglPixelFormat format,
                                                         guint *stride);

Creates a new buffer to store pixel data.

Note

COGL will try its best to provide a hardware buffer you can map, write into and effectively do a zero copy upload when creating a texture from it with cogl_texture_new_from_buffer(). For various reasons, such buffers are likely to have a stride larger than width * bytes_per_pixel. The user must take the stride into account when writing into it.

width :

width of the pixel buffer in pixels

height :

height of the pixel buffer in pixels

format :

the format of the pixels the buffer will store

stride :

if not NULL the function will return the stride of the buffer in bytes

Returns :

a CoglHandle representing the newly created buffer or COGL_INVALID_HANDLE on failure

Since 1.2

Stability Level: Unstable


cogl_is_pixel_buffer ()

gboolean            cogl_is_pixel_buffer                (CoglHandle handle);

Checks whether handle is a pixel buffer.

handle :

a CoglHandle to test

Returns :

TRUE if the handle is a pixel buffer, and FALSE otherwise

Since 1.2

Stability Level: Unstable


cogl_texture_new_from_buffer ()

CoglHandle          cogl_texture_new_from_buffer        (CoglHandle buffer,
                                                         guint width,
                                                         guint height,
                                                         CoglTextureFlags flags,
                                                         CoglPixelFormat format,
                                                         CoglPixelFormat internal_format,
                                                         guint rowstride,
                                                         guint 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