3D textures

## 3D textures 3D textures — Fuctions for creating and manipulating 3D textures |

## Synopsis

                        CoglTexture3D;
    CoglTexture3D *     cogl_texture_3d_new_with_size       (CoglContext *context,
                                                             int width,
                                                             int height,
                                                             int depth,
                                                             CoglPixelFormat internal_format,
                                                             GError **error);
    CoglTexture3D *     cogl_texture_3d_new_from_data       (CoglContext *context,
                                                             int width,
                                                             int height,
                                                             int depth,
                                                             CoglPixelFormat format,
                                                             CoglPixelFormat internal_format,
                                                             int rowstride,
                                                             int image_stride,
                                                             const guint8 *data,
                                                             GError **error);
    gboolean            cogl_is_texture_3d                  (void *object);

## Description

These functions allow 3D textures to be used. 3D textures can be thought of as layers of 2D images arranged into a cuboid shape. When choosing a texel from the texture, Cogl will take into account the 'r' texture coordinate to select one of the images.

## Details

### CoglTexture3D

    typedef struct _CoglTexture3D CoglTexture3D;

### cogl_texture_3d_new_with_size ()

    CoglTexture3D *     cogl_texture_3d_new_with_size       (CoglContext *context,
                                                             int width,
                                                             int height,
                                                             int depth,
                                                             CoglPixelFormat internal_format,
                                                             GError **error);

Creates a new Cogl 3D texture with the specified dimensions and pixel format.

Note that this function will throw a GError if `COGL_FEATURE_TEXTURE_3D` is not advertised. It can also fail if the requested dimensions are not supported by the GPU.

`context` : | a CoglContext
`width` : | width of the texture in pixels.
`height` : | height of the texture in pixels.
`depth` : | depth of the texture in pixels.
`internal_format` : | the CoglPixelFormat to use for the GPU storage of the texture.
`error` : | A GError return location.
Returns : | a new CoglTexture3D object or `NULL` on failure and an exception will be returned in `error`.

Since 1.10

Stability Level: Unstable

### cogl_texture_3d_new_from_data ()

    CoglTexture3D *     cogl_texture_3d_new_from_data       (CoglContext *context,
                                                             int width,
                                                             int height,
                                                             int depth,
                                                             CoglPixelFormat format,
                                                             CoglPixelFormat internal_format,
                                                             int rowstride,
                                                             int image_stride,
                                                             const guint8 *data,
                                                             GError **error);

Creates a new 3D texture and initializes it with `data`. The data is assumed to be packed array of `depth` images. There can be padding between the images using `image_stride`.

Note that this function will throw a GError if `COGL_FEATURE_TEXTURE_3D` is not advertised. It can also fail if the requested dimensions are not supported by the GPU.

`context` : | a CoglContext
`width` : | width of the texture in pixels.
`height` : | height of the texture in pixels.
`depth` : | depth of the texture in pixels.
`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` or 0 to infer it from the width and format
`image_stride` : | the number of bytes from one image to the next. This can be used to add padding between the images in a similar way that the rowstride can be used to add padding between rows. Alternatively 0 can be passed to infer the `image_stride` from the `height`.
`data` : | pointer the memory region where the source buffer resides
`error` : | A GError return location.
Returns : | the newly created CoglTexture3D or `NULL` if there was an error an an exception will be returned through `error`.

Since 1.10

Stability Level: Unstable

### cogl_is_texture_3d ()

    gboolean            cogl_is_texture_3d                  (void *object);

Checks whether the given object references a CoglTexture3D

`object` : | a CoglObject
Returns : | `TRUE` if the passed object represents a 3D texture and `FALSE` otherwise

Since 1.4

Stability Level: Unstable