## Rectangle textures (non-normalized coordinates) Rectangle textures (non-normalized coordinates) — Functions for creating and manipulating rectangle textures for use with non-normalized coordinates. |

## Synopsis

                        CoglTextureRectangle;
    CoglTextureRectangle * cogl_texture_rectangle_new_with_size
                                                            (CoglContext *ctx,
                                                             int width,
                                                             int height,
                                                             CoglPixelFormat internal_format,
                                                             CoglError **error);
    CoglTextureRectangle * cogl_texture_rectangle_new_from_bitmap
                                                            (CoglBitmap *bitmap,
                                                             CoglPixelFormat internal_format,
                                                             CoglError **error);
    CoglBool            cogl_is_texture_rectangle           (void *object);

## Description

These functions allow low-level "rectangle" textures to be allocated. These textures are never constrained to power-of-two sizes but they also don't support having a mipmap and can only be wrapped with `COGL_PIPELINE_WRAP_MODE_CLAMP_TO_EDGE`.

The most notable difference between rectangle textures and 2D textures is that rectangle textures are sampled using un-normalized texture coordinates, so instead of using coordinates (0,0) and (1,1) to map to the top-left and bottom right corners of the texture you would instead use (0,0) and (width,height).

The use of non-normalized coordinates can be particularly convenient when writing glsl shaders that use a texture as a lookup table since you don't need to upload separate uniforms to map normalized coordinates to texels.

If you want to sample from a rectangle texture from GLSL you should use the sampler2DRect sampler type.

Applications wanting to use CoglTextureRectangle should first check for the `COGL_FEATURE_ID_TEXTURE_RECTANGLE` feature using `cogl_has_feature()`.

## Details

### CoglTextureRectangle

    typedef struct _CoglTextureRectangle CoglTextureRectangle;

### cogl_texture_rectangle_new_with_size ()

    CoglTextureRectangle * cogl_texture_rectangle_new_with_size
                                                            (CoglContext *ctx,
                                                             int width,
                                                             int height,
                                                             CoglPixelFormat internal_format,
                                                             CoglError **error);

Allocates a new CoglTextureRectangle texture with a given `width`, `height` and `internal_format`. This texture is a low-level texture that the GPU can sample from directly unlike high-level textures such as CoglTexture2DSliced and CoglAtlasTexture.

### Note

Unlike for CoglTexture2D textures, coordinates for CoglTextureRectangle textures should not be normalized. So instead of using the coordinate (1, 1) to sample the bottom right corner of a rectangle texture you would use (`width`, `height`) where `width` and `height` are the width and height of the texture.

### Note

If you want to sample from a rectangle texture from GLSL you should use the sampler2DRect sampler type.

### Note

Applications wanting to use CoglTextureRectangle should first check for the `COGL_FEATURE_ID_TEXTURE_RECTANGLE` feature using `cogl_has_feature()`.

`ctx` : | A CoglContext pointer
`width` : | The texture width to allocate
`height` : | The texture height to allocate
`internal_format` : | The desired internal texture format
`error` : | An optional CoglError pointer for reporting exceptions
Returns : | A pointer to a newly allocated CoglTextureRectangle texture or if the size was too large or there wasn't enough memory `NULL` is returned and `error` set.

Since 1.10

Stability Level: Unstable

### cogl_texture_rectangle_new_from_bitmap ()

    CoglTextureRectangle * cogl_texture_rectangle_new_from_bitmap
                                                            (CoglBitmap *bitmap,
                                                             CoglPixelFormat internal_format,
                                                             CoglError **error);

Allocates a new CoglTextureRectangle texture which will be initialized with the pixel data from `bitmap`. Internally the data will be stored in the format given by `internal_format`. This texture is a low-level texture that the GPU can sample from directly unlike high-level textures such as CoglTexture2DSliced and CoglAtlasTexture.

### Note

Unlike for CoglTexture2D textures, coordinates for CoglTextureRectangle textures should not be normalized. So instead of using the coordinate (1, 1) to sample the bottom right corner of a rectangle texture you would use (`width`, `height`) where `width` and `height` are the width and height of the texture.

### Note

If you want to sample from a rectangle texture from GLSL you should use the sampler2DRect sampler type.

### Note

Applications wanting to use CoglTextureRectangle should first check for the `COGL_FEATURE_ID_TEXTURE_RECTANGLE` feature using `cogl_has_feature()`.

`bitmap` : | A CoglBitmap
`internal_format` : | the CoglPixelFormat to use for the GPU storage of the texture
`error` : | A return location for a CoglError or `NULL`
Returns : | A pointer to a newly allocated CoglTextureRectangle texture or if the size was too large or there wasn't enough memory `NULL` is returned and `error` set.

Since 2.0

Stability Level: Unstable

### cogl_is_texture_rectangle ()

    CoglBool            cogl_is_texture_rectangle           (void *object);

Gets whether the given object references an existing CoglTextureRectangle object.

`object` : | A CoglObject
Returns : | `TRUE` if the object references a CoglTextureRectangle, `FALSE` otherwise.