## 3D textures

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

## Synopsis

    #define             cogl_texture_3d_new_with_size
    #define             cogl_texture_3d_new_from_data
    #define             cogl_is_texture_3d

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

### cogl_texture_3d_new_with_size

    #define cogl_texture_3d_new_with_size cogl_texture_3d_new_with_size_EXP

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.

`width` : | width of the texture in pixels.
`height` : | height of the texture in pixels.
`depth` : | depth of the texture in pixels.
`flags` : | Optional flags for the texture, or `COGL_TEXTURE_NONE`
`internal_format` : | the CoglPixelFormat to use for the GPU storage of the texture.
`error` : | A GError return location.
Returns : | a new handle to a CoglTexture3D object or `COGL_INVALID_HANDLE` on failure.

Since 1.4

Stability Level: Unstable

### cogl_texture_3d_new_from_data

    #define cogl_texture_3d_new_from_data cogl_texture_3d_new_from_data_EXP

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.

`width` : | width of the texture in pixels.
`height` : | height of the texture in pixels.
`depth` : | depth of the texture in pixels.
`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` 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 texture or `COGL_INVALID_HANDLE` if there was an error.

Since 1.4

Stability Level: Unstable

### cogl_is_texture_3d

    #define cogl_is_texture_3d cogl_is_texture_3d_EXP

Checks whether `handle` is a CoglHandle for a 3D texture.

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

Since 1.4

Stability Level: Unstable