1 /* 2 * Copyright 2006 Richard Wilson <richard.wilson@netsurf-browser.org> 3 * Copyright 2008 Sean Fox <dyntryx@gmail.com> 4 * 5 * This file is part of NetSurf's libnsbmp, http://www.netsurf-browser.org/ 6 * Licenced under the MIT License, 7 * http://www.opensource.org/licenses/mit-license.php 8 */ 9 10 /** 11 * \file 12 * Bitmap file decoding interface. 13 */ 14 15 #ifndef _LIBNSBMP_H_ 16 #define _LIBNSBMP_H_ 17 18 #include <common.h> 19 #include <malloc.h> 20 #include <linux/types.h> 21 22 #ifndef INT32_MAX 23 #define INT32_MAX (2147483647) 24 #endif 25 26 /* bmp flags */ 27 #define BMP_NEW 0 28 /** image is opaque (as opposed to having an alpha mask) */ 29 #define BMP_OPAQUE (1 << 0) 30 /** memory should be wiped */ 31 #define BMP_CLEAR_MEMORY (1 << 1) 32 33 /** 34 * error return values 35 */ 36 typedef enum { 37 BMP_OK = 0, 38 BMP_INSUFFICIENT_MEMORY = 1, 39 BMP_INSUFFICIENT_DATA = 2, 40 BMP_DATA_ERROR = 3 41 } bmp_result; 42 43 /** 44 * encoding types 45 */ 46 typedef enum { 47 BMP_ENCODING_RGB = 0, 48 BMP_ENCODING_RLE8 = 1, 49 BMP_ENCODING_RLE4 = 2, 50 BMP_ENCODING_BITFIELDS = 3 51 } bmp_encoding; 52 53 /* API for Bitmap callbacks */ 54 typedef void* (*bmp_bitmap_cb_create)(int width, int height, unsigned int state); 55 typedef void (*bmp_bitmap_cb_destroy)(void *bitmap); 56 typedef unsigned char* (*bmp_bitmap_cb_get_buffer)(void *bitmap); 57 typedef size_t (*bmp_bitmap_cb_get_bpp)(void *bitmap); 58 59 /** 60 * The Bitmap callbacks function table 61 */ 62 typedef struct bmp_bitmap_callback_vt_s { 63 /** Callback to allocate bitmap storage. */ 64 bmp_bitmap_cb_create bitmap_create; 65 /** Called to free bitmap storage. */ 66 bmp_bitmap_cb_destroy bitmap_destroy; 67 /** Return a pointer to the pixel data in a bitmap. */ 68 bmp_bitmap_cb_get_buffer bitmap_get_buffer; 69 } bmp_bitmap_callback_vt; 70 71 /** 72 * bitmap image 73 */ 74 typedef struct bmp_img { 75 /** callbacks for bitmap functions */ 76 bmp_bitmap_callback_vt bitmap_callbacks; 77 /** pointer to BMP data */ 78 uint8_t *bmp_data; 79 /** width of BMP (valid after _analyse) */ 80 uint32_t width; 81 /** heigth of BMP (valid after _analyse) */ 82 uint32_t height; 83 /** whether the image has been decoded */ 84 bool decoded; 85 /** decoded image */ 86 void *bitmap; 87 88 /* Internal members are listed below */ 89 /** total number of bytes of BMP data available */ 90 uint32_t buffer_size; 91 /** pixel encoding type */ 92 bmp_encoding encoding; 93 /** offset of bitmap data */ 94 uint32_t bitmap_offset; 95 /** bits per pixel */ 96 uint16_t bpp; 97 /** number of colours */ 98 uint32_t colours; 99 /** colour table */ 100 uint32_t *colour_table; 101 /** whether to use bmp's limited transparency */ 102 bool limited_trans; 103 /** colour to display for "transparent" pixels when using limited 104 * transparency 105 */ 106 uint32_t trans_colour; 107 /** scanlines are top to bottom */ 108 bool reversed; 109 /** image is part of an ICO, mask follows */ 110 bool ico; 111 /** true if the bitmap does not contain an alpha channel */ 112 bool opaque; 113 /** four bitwise mask */ 114 uint32_t mask[4]; 115 /** four bitwise shifts */ 116 int32_t shift[4]; 117 /** colour representing "transparency" in the bitmap */ 118 uint32_t transparent_index; 119 } bmp_image; 120 121 typedef struct ico_image { 122 bmp_image bmp; 123 struct ico_image *next; 124 } ico_image; 125 126 /** 127 * icon image collection 128 */ 129 typedef struct ico_collection { 130 /** callbacks for bitmap functions */ 131 bmp_bitmap_callback_vt bitmap_callbacks; 132 /** width of largest BMP */ 133 uint16_t width; 134 /** heigth of largest BMP */ 135 uint16_t height; 136 137 /* Internal members are listed below */ 138 /** pointer to ICO data */ 139 uint8_t *ico_data; 140 /** total number of bytes of ICO data available */ 141 uint32_t buffer_size; 142 /** root of linked list of images */ 143 ico_image *first; 144 } ico_collection; 145 146 /** 147 * Initialises bitmap ready for analysing the bitmap. 148 * 149 * \param bmp The Bitmap to initialise 150 * \param callbacks The callbacks the library will call on operations. 151 * \return BMP_OK on success or appropriate error code. 152 */ 153 bmp_result bmp_create(bmp_image *bmp, bmp_bitmap_callback_vt *callbacks); 154 155 /** 156 * Initialises icon ready for analysing the icon 157 * 158 * \param bmp The Bitmap to initialise 159 * \param callbacks The callbacks the library will call on operations. 160 * \return BMP_OK on success or appropriate error code. 161 */ 162 bmp_result ico_collection_create(ico_collection *ico, 163 bmp_bitmap_callback_vt *callbacks); 164 165 /** 166 * Analyse a BMP prior to decoding. 167 * 168 * This will scan the data provided and perform checks to ensure the data is a 169 * valid BMP and prepare the bitmap image structure ready for decode. 170 * 171 * This function must be called and resturn BMP_OK before bmp_decode() as it 172 * prepares the bmp internal state for the decode process. 173 * 174 * \param bmp the BMP image to analyse. 175 * \param size The size of data in cdata. 176 * \param data The bitmap source data. 177 * \return BMP_OK on success or error code on faliure. 178 */ 179 bmp_result bmp_analyse(bmp_image *bmp, size_t size, uint8_t *data); 180 181 /** 182 * Analyse an ICO prior to decoding. 183 * 184 * This function will scan the data provided and perform checks to ensure the 185 * data is a valid ICO. 186 * 187 * This function must be called before ico_find(). 188 * 189 * \param ico the ICO image to analyse 190 * \param size The size of data in cdata. 191 * \param data The bitmap source data. 192 * \return BMP_OK on success 193 */ 194 bmp_result ico_analyse(ico_collection *ico, size_t size, uint8_t *data); 195 196 /** 197 * Decode a BMP 198 * 199 * This function decodes the BMP data such that bmp->bitmap is a valid 200 * image. The state of bmp->decoded is set to TRUE on exit such that it 201 * can easily be identified which BMPs are in a fully decoded state. 202 * 203 * \param bmp the BMP image to decode 204 * \return BMP_OK on success 205 */ 206 bmp_result bmp_decode(bmp_image *bmp); 207 208 /** 209 * Decode a BMP using "limited transparency" 210 * 211 * Bitmaps do not have native transparency support. However, there is a 212 * "trick" that is used in some instances in which the first pixel of the 213 * bitmap becomes the "transparency index". The decoding application can 214 * replace this index with whatever background colour it chooses to 215 * create the illusion of transparency. 216 * 217 * When to use transparency is at the discretion of the decoding 218 * application. 219 * 220 * \param bmp the BMP image to decode 221 * \param colour the colour to use as "transparent" 222 * \return BMP_OK on success 223 */ 224 bmp_result bmp_decode_trans(bmp_image *bmp, uint32_t transparent_colour); 225 226 /** 227 * Finds the closest BMP within an ICO collection 228 * 229 * This function finds the BMP with dimensions as close to a specified set 230 * as possible from the images in the collection. 231 * 232 * \param ico the ICO collection to examine 233 * \param width the preferred width (0 to use ICO header width) 234 * \param height the preferred height (0 to use ICO header height) 235 */ 236 bmp_image *ico_find(ico_collection *ico, uint16_t width, uint16_t height); 237 238 /** 239 * Finalise a BMP prior to destruction. 240 * 241 * \param bmp the BMP image to finalise. 242 */ 243 void bmp_finalise(bmp_image *bmp); 244 245 /** 246 * Finalise an ICO prior to destruction. 247 * 248 * \param ico the ICO image to finalise, 249 */ 250 void ico_finalise(ico_collection *ico); 251 252 #endif 253