3D textures

## 3D textures 3D textures — Functions 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);
    CoglTexture3D *     cogl_texture_3d_new_from_bitmap     (CoglBitmap *bitmap,
                                                             unsigned int height,
                                                             unsigned int depth,
                                                             CoglPixelFormat internal_format,
                                                             CoglError **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 uint8_t *data,
                                                             CoglError **error);
    CoglBool            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);

Creates a new CoglTexture3D texture with the specified dimensions and pixel format.

The storage for the texture is not allocated before this function returns. You can call `cogl_texture_allocate()` to explicitly allocate the underlying storage or preferably let Cogl automatically allocate storage lazily when it may know more about how the texture is going to be used and can optimize how it is allocated.

### Note

This texture will fail to allocate later if `COGL_FEATURE_ID_TEXTURE_3D` is not advertised. Allocation 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.
Returns : | A new CoglTexture3D object with no storage yet allocated. [transfer full]

Since 1.10

Stability Level: Unstable

### cogl_texture_3d_new_from_bitmap ()

    CoglTexture3D *     cogl_texture_3d_new_from_bitmap     (CoglBitmap *bitmap,
                                                             unsigned int height,
                                                             unsigned int depth,
                                                             CoglPixelFormat internal_format,
                                                             CoglError **error);

Creates a new 3D texture and initializes it with the images in `bitmap`. The images are assumed to be packed together after one another in the increasing y axis. The height of individual image is given as `height` and the number of images is given in `depth`. The actual height of the bitmap can be larger than `height` × `depth`. In this case it assumes there is padding between the images.

`bitmap` : | A CoglBitmap object.
`height` : | height of the texture in pixels.
`depth` : | depth of the texture in pixels.
`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_pipeline_set_blend()`) or use the data for something other than straight blending.
`error` : | A CoglError return location.
Returns : | the newly created texture or `NULL` if there was an error. [transfer full]

Since 2.0

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 uint8_t *data,
                                                             CoglError **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 CoglError if `COGL_FEATURE_ID_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_pipeline_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 CoglError return location.
Returns : | the newly created CoglTexture3D or `NULL` if there was an error an an exception will be returned through `error`. [transfer full]

Since 1.10

Stability Level: Unstable

### cogl_is_texture_3d ()

    CoglBool            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