## Buffers

Buffers — Common buffer functions, including data upload APIs

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

    #define             cogl_pixel_buffer_new
    #define             cogl_is_pixel_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);

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

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

    #define cogl_pixel_buffer_new cogl_pixel_buffer_new_EXP

### cogl_is_pixel_buffer

    #define cogl_is_pixel_buffer cogl_is_pixel_buffer_EXP

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