## 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