2D textures

## 2D textures 2D textures — Functions for creating and manipulating 2D textures |

## Functions

CoglTexture2D * | cogl_texture_2d_new_with_size ()
CoglTexture2D * | cogl_texture_2d_new_from_file ()
CoglTexture2D * | cogl_texture_2d_new_from_bitmap ()
CoglTexture2D * | cogl_texture_2d_new_from_data ()
CoglTexture2D * | cogl_texture_2d_gl_new_from_foreign ()
CoglBool | cogl_is_texture_rectangle ()

## Types and Values

| CoglTexture2D

## Description

These functions allow low-level 2D textures to be allocated. These differ from sliced textures for example which may internally be made up of multiple 2D textures, or atlas textures where Cogl must internally modify user texture coordinates before they can be used by the GPU.

You should be aware that many GPUs only support power of two sizes for CoglTexture2D textures. You can check support for non power of two textures by checking for the `COGL_FEATURE_ID_TEXTURE_NPOT` feature via `cogl_has_feature()`.

## Functions

### cogl_texture_2d_new_with_size ()

    CoglTexture2D *
    cogl_texture_2d_new_with_size (CoglContext *ctx,
                                   int width,
                                   int height);

Creates a low-level CoglTexture2D texture with a given `width` and `height` that your GPU can texture from directly.

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 being used and can optimize how it is allocated.

The texture is still configurable until it has been allocated so for example you can influence the internal format of the texture using `cogl_texture_set_components()` and `cogl_texture_set_premultiplied()`.

Many GPUs only support power of two sizes for CoglTexture2D textures. You can check support for non power of two textures by checking for the `COGL_FEATURE_ID_TEXTURE_NPOT` feature via `cogl_has_feature()`.

#### Parameters

ctx | A CoglContext |
width | Width of the texture to allocate |
height | Height of the texture to allocate |

#### Returns

A new CoglTexture2D object with no storage yet allocated.

[transfer full]

Since 2.0

### cogl_texture_2d_new_from_file ()

    CoglTexture2D *
    cogl_texture_2d_new_from_file (CoglContext *ctx,
                                   const char *filename,
                                   CoglError **error);

Creates a low-level CoglTexture2D texture from an image file.

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 being used and can optimize how it is allocated.

The texture is still configurable until it has been allocated so for example you can influence the internal format of the texture using `cogl_texture_set_components()` and `cogl_texture_set_premultiplied()`.

Many GPUs only support power of two sizes for CoglTexture2D textures. You can check support for non power of two textures by checking for the `COGL_FEATURE_ID_TEXTURE_NPOT` feature via `cogl_has_feature()`.

#### Parameters

ctx | A CoglContext |
filename | the file to load |
error | A CoglError to catch exceptional errors or `NULL` |

#### Returns

A newly created CoglTexture2D or `NULL` on failure and `error` will be updated.

[transfer full]

Since 1.16

### cogl_texture_2d_new_from_bitmap ()

    CoglTexture2D *
    cogl_texture_2d_new_from_bitmap (CoglBitmap *bitmap);

Creates a low-level CoglTexture2D texture based on data residing in a CoglBitmap.

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 being used and can optimize how it is allocated.

The texture is still configurable until it has been allocated so for example you can influence the internal format of the texture using `cogl_texture_set_components()` and `cogl_texture_set_premultiplied()`.

Many GPUs only support power of two sizes for CoglTexture2D textures. You can check support for non power of two textures by checking for the `COGL_FEATURE_ID_TEXTURE_NPOT` feature via `cogl_has_feature()`.

#### Parameters

bitmap | A CoglBitmap |

#### Returns

A newly allocated CoglTexture2D.

[transfer full]

Since 2.0

Stability Level: Unstable

### cogl_texture_2d_new_from_data ()

    CoglTexture2D *
    cogl_texture_2d_new_from_data (CoglContext *ctx,
                                   int width,
                                   int height,
                                   CoglPixelFormat format,
                                   int rowstride,
                                   const uint8_t *data,
                                   CoglError **error);

Creates a low-level CoglTexture2D texture based on data residing in memory.

This api will always immediately allocate GPU memory for the texture and upload the given data so that the `data` pointer does not need to remain valid once this function returns. This means it is not possible to configure the texture before it is allocated. If you do need to configure the texture before allocation (to specify constraints on the internal format for example) then you can instead create a CoglBitmap for your data and use `cogl_texture_2d_new_from_bitmap()` or use `cogl_texture_2d_new_with_size()` and then upload data using `cogl_texture_set_data()`
Many GPUs only support power of two sizes for CoglTexture2D textures. You can check support for non power of two textures by checking for the `COGL_FEATURE_ID_TEXTURE_NPOT` feature via `cogl_has_feature()`.

#### Parameters

ctx | A CoglContext |
width | width of texture in pixels |
height | height of texture in pixels |
format | the CoglPixelFormat the buffer is stored in in RAM |
rowstride | the memory offset in bytes between the starts of scanlines in `data` . A value of 0 will make Cogl automatically calculate `rowstride` from `width` and `format` . |
data | pointer the memory region where the source buffer resides |
error | A CoglError for exceptions |

#### Returns

A newly allocated CoglTexture2D, or if the size is not supported (because it is too large or a non-power-of-two size that the hardware doesn't support) it will return `NULL` and set `error` .

[transfer full]

Since 2.0

### cogl_texture_2d_gl_new_from_foreign ()

    CoglTexture2D *
    cogl_texture_2d_gl_new_from_foreign (CoglContext *ctx,
                                         unsigned int gl_handle,
                                         int width,
                                         int height,
                                         CoglPixelFormat format);

Wraps an existing GL_TEXTURE_2D texture object as a CoglTexture2D. This can be used for integrating Cogl with software using OpenGL directly.

The texture is still configurable until it has been allocated so for example you can declare whether the texture is premultiplied with `cogl_texture_set_premultiplied()`.

The results are undefined for passing an invalid `gl_handle` or if `width` or `height` don't have the correct texture geometry.

#### Parameters

ctx | A CoglContext |
gl_handle | A GL handle for a GL_TEXTURE_2D texture object |
width | Width of the foreign GL texture |
height | Height of the foreign GL texture |
format | The format of the texture |

#### Returns

A newly allocated CoglTexture2D.

[transfer full]

Since 2.0

### cogl_is_texture_rectangle ()

    CoglBool
    cogl_is_texture_rectangle (void *object);

Gets whether the given object references an existing CoglTextureRectangle object.

#### Parameters

object | A CoglObject |

#### Returns

`TRUE` if the object references a CoglTextureRectangle, `FALSE` otherwise.

## Types and Values

### CoglTexture2D

    typedef struct _CoglTexture2D CoglTexture2D;