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. [transfer full]

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. [transfer full]

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. [transfer full]

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. [transfer full]

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. [transfer none]

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);

Warning

cogl_texture_new_from_bitmap has been deprecated since version 1.18 and should not be used in newly-written code. Use specific constructors such as cogl_texture_2d_new_from_bitmap()

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. [transfer full]

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

Generated by GTK-Doc V1.19.1