diff options
Diffstat (limited to 'include/netsurf/bitmap.h')
-rw-r--r-- | include/netsurf/bitmap.h | 154 |
1 files changed, 94 insertions, 60 deletions
diff --git a/include/netsurf/bitmap.h b/include/netsurf/bitmap.h index f5de51423..10e9a07fb 100644 --- a/include/netsurf/bitmap.h +++ b/include/netsurf/bitmap.h @@ -20,64 +20,120 @@ * \file * Generic bitmap handling interface. * - * This interface wraps the native platform-specific image format, so that - * portable image convertors can be written. + * This interface wraps the native platform-specific image format. * - * Bitmaps are required to be 32bpp with components in the order RR GG BB AA. + * Bitmaps are required to be 32bpp with 8-bit components. The components are + * red, green, blue, and alpha, in client specified order. * - * For example, an opaque 1x1 pixel image would yield the following bitmap - * data: - * - * > Red : 0xff 0x00 0x00 0x00 - * > Green: 0x00 0xff 0x00 0x00 - * > Blue : 0x00 0x00 0xff 0x00 - * - * Any attempt to read pixels by casting bitmap data to uint32_t or similar - * will need to cater for the order of bytes in a word being different on - * big and little endian systems. To avoid confusion, it is recommended - * that pixel data is loaded as follows: - * - * uint32_t read_pixel(const uint8_t *bmp) - * { - * // red green blue alpha - * return bmp[0] | (bmp[1] << 8) | (bmp[2] << 16) | (bmp[3] << 24); - * } - * - * and *not* as follows: - * - * uint32_t read_pixel(const uint8_t *bmp) - * { - * return *((uint32_t *) bmp); - * } + * The component order may be set in the front ends by calling + * \ref bitmap_set_format(). */ #ifndef _NETSURF_BITMAP_H_ #define _NETSURF_BITMAP_H_ -#define BITMAP_NEW 0 -#define BITMAP_OPAQUE (1 << 0) /**< image is opaque */ -#define BITMAP_MODIFIED (1 << 1) /**< buffer has been modified */ -#define BITMAP_CLEAR_MEMORY (1 << 2) /**< memory should be wiped */ +/** Bitmap creation flags. */ +enum gui_bitmap_flags { + BITMAP_NONE = 0, + BITMAP_OPAQUE = (1 << 0), /**< image is opaque */ + BITMAP_CLEAR = (1 << 1), /**< memory should be wiped to 0 */ +}; + +/** + * NetSurf bitmap pixel layout. + * + * All pixels are 32 bits per pixel (bpp). The different layouts allow control + * over the ordering of colour channels. All colour channels are 8 bits wide. + */ +enum bitmap_layout { + /** Bite-wise RGBA: Byte order: 0xRR, 0xGG, 0xBB, 0xAA. */ + BITMAP_LAYOUT_R8G8B8A8, + + /** Bite-wise BGRA: Byte order: 0xBB, 0xGG, 0xRR, 0xAA. */ + BITMAP_LAYOUT_B8G8R8A8, + + /** Bite-wise ARGB: Byte order: 0xAA, 0xRR, 0xGG, 0xBB. */ + BITMAP_LAYOUT_A8R8G8B8, + + /** Bite-wise ABGR: Byte order: 0xAA, 0xBB, 0xGG, 0xRR. */ + BITMAP_LAYOUT_A8B8G8R8, + + /** + * 32-bit RGBA (0xRRGGBBAA). + * + * * On little endian host, same as \ref BITMAP_LAYOUT_A8B8G8R8. + * * On big endian host, same as \ref BITMAP_LAYOUT_R8G8B8A8. + */ + BITMAP_LAYOUT_RGBA8888, + + /** + * 32-bit BGRA (0xBBGGRRAA). + * + * * On little endian host, same as \ref BITMAP_LAYOUT_A8R8G8B8. + * * On big endian host, same as \ref BITMAP_LAYOUT_B8G8R8A8. + */ + BITMAP_LAYOUT_BGRA8888, + + /** + * 32-bit ARGB (0xAARRGGBB). + * + * * On little endian host, same as \ref BITMAP_LAYOUT_B8G8R8A8. + * * On big endian host, same as \ref BITMAP_LAYOUT_A8R8G8B8. + */ + BITMAP_LAYOUT_ARGB8888, + + /** + * 32-bit BGRA (0xAABBGGRR). + * + * * On little endian host, same as \ref BITMAP_LAYOUT_R8G8B8A8. + * * On big endian host, same as \ref BITMAP_LAYOUT_A8B8G8R8. + */ + BITMAP_LAYOUT_ABGR8888, +}; + +/** Bitmap format specifier. */ +typedef struct bitmap_fmt { + enum bitmap_layout layout; /**< Colour component layout. */ + bool pma; /**< Premultiplied alpha. */ +} bitmap_fmt_t; struct content; struct bitmap; struct hlcache_handle; /** + * Set client bitmap format. + * + * Set this to ensure that the bitmaps decoded by the core are in the + * correct format for the front end. + * + * \param[in] bitmap_format The bitmap format specification to set. + */ +void bitmap_set_format(const bitmap_fmt_t *bitmap_format); + +/** + * Test whether a bitmap is completely opaque (no transparency). + * + * \param[in] bitmap The bitmap to test. + * \return Returns true if the bitmap is opaque, false otherwise. + */ +bool bitmap_test_opaque(void *bitmap); + +/** * Bitmap operations. */ struct gui_bitmap_table { - /* Mandantory entries */ + /* Mandatory entries */ /** * Create a new bitmap. * - * \param width width of image in pixels - * \param height width of image in pixels - * \param state The state to create the bitmap in. + * \param width width of image in pixels + * \param height height of image in pixels + * \param flags flags for bitmap creation * \return A bitmap structure or NULL on error. */ - void *(*create)(int width, int height, unsigned int state); + void *(*create)(int width, int height, enum gui_bitmap_flags flags); /** * Destroy a bitmap. @@ -103,16 +159,10 @@ struct gui_bitmap_table { bool (*get_opaque)(void *bitmap); /** - * Test if a bitmap is opaque. - * - * \param bitmap The bitmap to examine. - * \return The bitmap opacity. - */ - bool (*test_opaque)(void *bitmap); - - /** * Get the image buffer from a bitmap * + * Note that all pixels must be 4-byte aligned. + * * \param bitmap The bitmap to get the buffer from. * \return The image buffer or NULL if there is none. */ @@ -143,22 +193,6 @@ struct gui_bitmap_table { int (*get_height)(void *bitmap); /** - * Get the *bytes* per pixel. - * - * \param bitmap The bitmap - */ - size_t (*get_bpp)(void *bitmap); - - /** - * Save a bitmap to disc. - * - * \param bitmap The bitmap to save - * \param path The path to save the bitmap to. - * \param flags Flags affecting the save. - */ - bool (*save)(void *bitmap, const char *path, unsigned flags); - - /** * Marks a bitmap as modified. * * \param bitmap The bitmap set as modified. |