Bitmap

Bitmap — Functions for loading images

Synopsis

                    CoglBitmap;
CoglBool            cogl_is_bitmap                      (void *object);

CoglBitmap *        cogl_bitmap_new_from_file           (CoglContext *context,
                                                         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);


#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           (CoglContext *context,
                                                         const char *filename,
                                                         CoglError **error);

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

context :

A CoglContext

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_BITMAP_ERROR

#define COGL_BITMAP_ERROR (cogl_bitmap_error_domain ())

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