## Bitmap Bitmap — Functions for loading images |

## Synopsis

                        CoglBitmap;
    CoglBool            cogl_is_bitmap                      (void *object);

    CoglBitmap *        cogl_bitmap_new_from_file           (const char *filename,
                                                             CoglError **error);
    CoglBitmap *        cogl_bitmap_new_from_buffer         (CoglBuffer *buffer,
                                                             CoglPixelFormat format,
                                                             int width,
                                                             int height,
                                                             int rowstride,
                                                             int offset);
    CoglBitmap *        cogl_bitmap_new_with_size           (CoglContext *context,
                                                             unsigned int width,
                                                             unsigned int height,
                                                             CoglPixelFormat format);
    CoglBitmap *        cogl_bitmap_new_for_data            (CoglContext *context,
                                                             int width,
                                                             int height,
                                                             CoglPixelFormat format,
                                                             int rowstride,
                                                             uint8_t *data);

    CoglPixelFormat     cogl_bitmap_get_format              (CoglBitmap *bitmap);
    int                 cogl_bitmap_get_width               (CoglBitmap *bitmap);
    int                 cogl_bitmap_get_height              (CoglBitmap *bitmap);
    int                 cogl_bitmap_get_rowstride           (CoglBitmap *bitmap);
    CoglPixelBuffer *   cogl_bitmap_get_buffer              (CoglBitmap *bitmap);
    CoglBool            cogl_bitmap_get_size_from_file      (const char *filename,
                                                             int *width,
                                                             int *height);

    CoglTexture *       cogl_texture_new_from_bitmap        (CoglBitmap *bitmap,
                                                             CoglTextureFlags flags,
                                                             CoglPixelFormat internal_format);

    #define             COGL_BITMAP_ERROR
    enum                CoglBitmapError;

## Description

Cogl allows loading image data into memory as CoglBitmaps without loading them immediately into GPU textures.

CoglBitmap is available since Cogl 1.0

## Details

### CoglBitmap

    typedef struct _CoglBitmap CoglBitmap;

### cogl_is_bitmap ()

    CoglBool            cogl_is_bitmap                      (void *object);

Checks whether `object` is a CoglBitmap

`object` : | a CoglObject pointer
Returns : | `TRUE` if the passed `object` represents a bitmap, and `FALSE` otherwise

Since 1.0

### cogl_bitmap_new_from_file ()

    CoglBitmap *        cogl_bitmap_new_from_file           (const char *filename,
                                                             CoglError **error);

Loads an image file from disk. This function can be safely called from within a thread.

`filename` : | the file to load.
`error` : | a CoglError or `NULL`.
Returns : | a CoglBitmap to the new loaded image data, or `NULL` if loading the image failed.

Since 1.0

### cogl_bitmap_new_from_buffer ()

    CoglBitmap *        cogl_bitmap_new_from_buffer         (CoglBuffer *buffer,
                                                             CoglPixelFormat format,
                                                             int width,
                                                             int height,
                                                             int rowstride,
                                                             int offset);

Wraps some image data that has been uploaded into a CoglBuffer as a CoglBitmap. The data is not copied in this process.

`buffer` : | A CoglBuffer containing image data
`format` : | The CoglPixelFormat defining the format of the image data in the given `buffer`.
`width` : | The width of the image data in the given `buffer`.
`height` : | The height of the image data in the given `buffer`.
`rowstride` : | The rowstride in bytes of the image data in the given `buffer`.
`offset` : | The offset into the given `buffer` to the first pixel that should be considered part of the CoglBitmap.
Returns : | a CoglBitmap encapsulating the given `buffer`.

Since 1.8

Stability Level: Unstable

### cogl_bitmap_new_with_size ()

    CoglBitmap *        cogl_bitmap_new_with_size           (CoglContext *context,
                                                             unsigned int width,
                                                             unsigned int height,
                                                             CoglPixelFormat format);

Creates a new CoglBitmap with the given width, height and format. The initial contents of the bitmap are undefined.

The data for the bitmap will be stored in a newly created CoglPixelBuffer. You can get a pointer to the pixel buffer using `cogl_bitmap_get_buffer()`. The CoglBuffer API can then be used to fill the bitmap with data.

### Note

Cogl will try its best to provide a hardware array you can map, write into and effectively do a zero copy upload when creating a texture from it with `cogl_texture_new_from_bitmap()`. For various reasons, such arrays are likely to have a stride larger than width * bytes_per_pixel. The user must take the stride into account when writing into it. The stride can be retrieved with `cogl_bitmap_get_rowstride()`.

`context` : | A CoglContext
`width` : | width of the bitmap in pixels
`height` : | height of the bitmap in pixels
`format` : | the format of the pixels the array will store
Returns : | a CoglPixelBuffer representing the newly created array or `NULL` on failure

Since 1.10

Stability Level: Unstable

### cogl_bitmap_new_for_data ()

    CoglBitmap *        cogl_bitmap_new_for_data            (CoglContext *context,
                                                             int width,
                                                             int height,
                                                             CoglPixelFormat format,
                                                             int rowstride,
                                                             uint8_t *data);

Creates a bitmap using some existing data. The data is not copied so the application must keep the buffer alive for the lifetime of the CoglBitmap. This can be used for example with `cogl_framebuffer_read_pixels_into_bitmap()` to read data directly into an application buffer with the specified rowstride.

`context` : | A CoglContext
`width` : | The width of the bitmap.
`height` : | The height of the bitmap.
`format` : | The format of the pixel data.
`rowstride` : | The rowstride of the bitmap (the number of bytes from the start of one row of the bitmap to the next).
`data` : | A pointer to the data. The bitmap will take ownership of this data.
Returns : | A new CoglBitmap.

Since 1.10

Stability Level: Unstable

### cogl_bitmap_get_format ()

    CoglPixelFormat     cogl_bitmap_get_format              (CoglBitmap *bitmap);

`bitmap` : | A CoglBitmap
Returns : | the CoglPixelFormat that the data for the bitmap is in.

Since 1.10

Stability Level: Unstable

### cogl_bitmap_get_width ()

    int                 cogl_bitmap_get_width               (CoglBitmap *bitmap);

`bitmap` : | A CoglBitmap
Returns : | the width of the bitmap

Since 1.10

Stability Level: Unstable

### cogl_bitmap_get_height ()

    int                 cogl_bitmap_get_height              (CoglBitmap *bitmap);

`bitmap` : | A CoglBitmap
Returns : | the height of the bitmap

Since 1.10

Stability Level: Unstable

### cogl_bitmap_get_rowstride ()

    int                 cogl_bitmap_get_rowstride           (CoglBitmap *bitmap);

`bitmap` : | A CoglBitmap
Returns : | the rowstride of the bitmap. This is the number of bytes between the address of start of one row to the address of the next row in the image.

Since 1.10

Stability Level: Unstable

### cogl_bitmap_get_buffer ()

    CoglPixelBuffer *   cogl_bitmap_get_buffer              (CoglBitmap *bitmap);

`bitmap` : | A CoglBitmap
Returns : | the CoglPixelBuffer that this buffer uses for storage. Note that if the bitmap was created with `cogl_bitmap_new_from_file()` then it will not actually be using a pixel buffer and this function will return `NULL`.

Since 1.10

Stability Level: Unstable

### cogl_bitmap_get_size_from_file ()

    CoglBool            cogl_bitmap_get_size_from_file      (const char *filename,
                                                             int *width,
                                                             int *height);

Parses an image file enough to extract the width and height of the bitmap.

`filename` : | the file to check
`width` : | return location for the bitmap width, or `NULL`. [out]
`height` : | return location for the bitmap height, or `NULL`. [out]
Returns : | `TRUE` if the image was successfully parsed

Since 1.0

### cogl_texture_new_from_bitmap ()

    CoglTexture *       cogl_texture_new_from_bitmap        (CoglBitmap *bitmap,
                                                             CoglTextureFlags flags,
                                                             CoglPixelFormat internal_format);

Creates a CoglTexture from a CoglBitmap.

`bitmap` : | A CoglBitmap pointer
`flags` : | Optional flags for the texture, or `COGL_TEXTURE_NONE`
`internal_format` : | the CoglPixelFormat to use for the GPU storage of the texture
Returns : | A newly created CoglTexture or `NULL` on failure

Since 1.0

### COGL_BITMAP_ERROR

    #define COGL_BITMAP_ERROR (cogl_bitmap_error_quark ())

CoglError domain for bitmap errors.

Since 1.4

### enum CoglBitmapError

    typedef enum {
      COGL_BITMAP_ERROR_FAILED,
      COGL_BITMAP_ERROR_UNKNOWN_TYPE,
      COGL_BITMAP_ERROR_CORRUPT_IMAGE
    } CoglBitmapError;

Error codes that can be thrown when performing bitmap operations. Note that `gdk_pixbuf_new_from_file()` can also throw errors directly from the underlying image loading library. For example, if GdkPixbuf is used then errors GdkPixbufErrors will be used directly.

`COGL_BITMAP_ERROR_FAILED` | Generic failure code, something went wrong.
`COGL_BITMAP_ERROR_UNKNOWN_TYPE` | Unknown image type.
`COGL_BITMAP_ERROR_CORRUPT_IMAGE` | An image file was broken somehow.

Since 1.4