## Buffers

Buffers — Buffer creation and manipulation

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

    gboolean            cogl_is_buffer                      (CoglHandle handle);
    unsigned int        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;
    guint8 *            cogl_buffer_map                     (CoglHandle handle,
                                                             CoglBufferAccess access);
    void                cogl_buffer_unmap                   (CoglHandle handle);
    gboolean            cogl_buffer_set_data                (CoglHandle handle,
                                                             gsize offset,
                                                             const guint8 *data,
                                                             gsize size);

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

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

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

    unsigned int        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);

Sets 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);

Retrieves the usage hint set using `cogl_buffer_set_usage_hint()`

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

Sets 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);

Retrieves the update hints set using `cogl_buffer_set_update_hint()`

`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;

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

    guint8 *            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 guint8 *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               (unsigned int 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      (unsigned int width,
                                                             unsigned int height,
                                                             CoglPixelFormat format,
                                                             unsigned int *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,
                                                             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