libnsbmp.h File Reference

#include <stdbool.h>
#include <stdint.h>
#include <stddef.h>

Include dependency graph for libnsbmp.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	bmp_bitmap_callback_vt_s
struct	bmp_image
struct	ico_image
struct	ico_collection

Macros
#define	BMP_NEW   0
#define	BMP_OPAQUE   (1 << 0)
#define	BMP_CLEAR_MEMORY   (1 << 1)

Typedefs
typedef void *(*	bmp_bitmap_cb_create) (int width, int height, unsigned int state)
typedef void(*	bmp_bitmap_cb_destroy) (void *bitmap)
typedef unsigned char *(*	bmp_bitmap_cb_get_buffer) (void *bitmap)
typedef size_t(*	bmp_bitmap_cb_get_bpp) (void *bitmap)
typedef struct bmp_bitmap_callback_vt_s	bmp_bitmap_callback_vt
typedef struct bmp_image	bmp_image
typedef struct ico_image	ico_image
typedef struct ico_collection	ico_collection

Enumerations
enum	bmp_result { BMP_OK = 0 , BMP_INSUFFICIENT_MEMORY = 1 , BMP_INSUFFICIENT_DATA = 2 , BMP_DATA_ERROR = 3 }
enum	bmp_encoding { BMP_ENCODING_RGB = 0 , BMP_ENCODING_RLE8 = 1 , BMP_ENCODING_RLE4 = 2 , BMP_ENCODING_BITFIELDS = 3 }

Functions
bmp_result	bmp_create (bmp_image *bmp, bmp_bitmap_callback_vt *callbacks)
bmp_result	ico_collection_create (ico_collection *ico, bmp_bitmap_callback_vt *callbacks)
bmp_result	bmp_analyse (bmp_image *bmp, size_t size, uint8_t *data)
bmp_result	ico_analyse (ico_collection *ico, size_t size, uint8_t *data)
bmp_result	bmp_decode (bmp_image *bmp)
bmp_result	bmp_decode_trans (bmp_image *bmp, uint32_t transparent_colour)
bmp_image *	ico_find (ico_collection *ico, uint16_t width, uint16_t height)
void	bmp_finalise (bmp_image *bmp)
void	ico_finalise (ico_collection *ico)

Detailed Description

Bitmap file decoding interface.

Macro Definition Documentation

BMP_CLEAR_MEMORY

#define BMP_CLEAR_MEMORY   (1 << 1)

memory should be wiped

BMP_NEW

#define BMP_NEW   0

BMP_OPAQUE

#define BMP_OPAQUE   (1 << 0)

image is opaque (as opposed to having an alpha mask)

Typedef Documentation

bmp_bitmap_callback_vt

typedef struct bmp_bitmap_callback_vt_s bmp_bitmap_callback_vt

The Bitmap callbacks function table

bmp_bitmap_cb_create

typedef void *(* bmp_bitmap_cb_create) (int width, int height, unsigned int state)

bmp_bitmap_cb_destroy

typedef void(* bmp_bitmap_cb_destroy) (void *bitmap)

bmp_bitmap_cb_get_bpp

typedef size_t(* bmp_bitmap_cb_get_bpp) (void *bitmap)

bmp_bitmap_cb_get_buffer

typedef unsigned char *(* bmp_bitmap_cb_get_buffer) (void *bitmap)

bmp_image

typedef struct bmp_image bmp_image

bitmap image

ico_collection

typedef struct ico_collection ico_collection

icon image collection

ico_image

typedef struct ico_image ico_image

Enumeration Type Documentation

bmp_encoding

enum bmp_encoding

encoding types

Enumerator
BMP_ENCODING_RGB
BMP_ENCODING_RLE8
BMP_ENCODING_RLE4
BMP_ENCODING_BITFIELDS

bmp_result

enum bmp_result

error return values

Enumerator
BMP_OK
BMP_INSUFFICIENT_MEMORY
BMP_INSUFFICIENT_DATA
BMP_DATA_ERROR

Function Documentation

bmp_analyse()

bmp_result bmp_analyse	(	bmp_image *	bmp,
		size_t	size,
		uint8_t *	data
	)

Analyse a BMP prior to decoding.

This will scan the data provided and perform checks to ensure the data is a valid BMP and prepare the bitmap image structure ready for decode.

This function must be called and resturn BMP_OK before bmp_decode() as it prepares the bmp internal state for the decode process.

Parameters

bmp	the BMP image to analyse.
size	The size of data in cdata.
data	The bitmap source data.

Returns

BMP_OK on success or error code on faliure.

bmp_create()

bmp_result bmp_create	(	bmp_image *	bmp,
		bmp_bitmap_callback_vt *	callbacks
	)

Initialises bitmap ready for analysing the bitmap.

Parameters

bmp	The Bitmap to initialise
callbacks	The callbacks the library will call on operations.

Returns

BMP_OK on success or appropriate error code.

bmp_decode()

bmp_result bmp_decode

(

bmp_image *

bmp

)

Decode a BMP

This function decodes the BMP data such that bmp->bitmap is a valid image. The state of bmp->decoded is set to TRUE on exit such that it can easily be identified which BMPs are in a fully decoded state.

Parameters

bmp	the BMP image to decode

Returns

BMP_OK on success

bmp_decode_trans()

bmp_result bmp_decode_trans	(	bmp_image *	bmp,
		uint32_t	transparent_colour
	)

Decode a BMP using "limited transparency"

Bitmaps do not have native transparency support. However, there is a "trick" that is used in some instances in which the first pixel of the bitmap becomes the "transparency index". The decoding application can replace this index with whatever background colour it chooses to create the illusion of transparency.

When to use transparency is at the discretion of the decoding application.

Parameters

bmp	the BMP image to decode
colour	the colour to use as "transparent"

Returns

BMP_OK on success

bmp_finalise()

void bmp_finalise

(

bmp_image *

bmp

)

Finalise a BMP prior to destruction.

Parameters

bmp	the BMP image to finalise.

ico_analyse()

bmp_result ico_analyse	(	ico_collection *	ico,
		size_t	size,
		uint8_t *	data
	)

Analyse an ICO prior to decoding.

This function will scan the data provided and perform checks to ensure the data is a valid ICO.

This function must be called before ico_find().

Parameters

ico	the ICO image to analyse
size	The size of data in cdata.
data	The bitmap source data.

Returns

BMP_OK on success

ico_collection_create()

bmp_result ico_collection_create	(	ico_collection *	ico,
		bmp_bitmap_callback_vt *	callbacks
	)

Initialises icon ready for analysing the icon

Parameters

bmp	The Bitmap to initialise
callbacks	The callbacks the library will call on operations.

Returns

BMP_OK on success or appropriate error code.

ico_finalise()

void ico_finalise

(

ico_collection *

ico

)

Finalise an ICO prior to destruction.

Parameters

ico	the ICO image to finalise,

ico_find()

bmp_image * ico_find	(	ico_collection *	ico,
		uint16_t	width,
		uint16_t	height
	)

Finds the closest BMP within an ICO collection

This function finds the BMP with dimensions as close to a specified set as possible from the images in the collection.

Parameters

ico	the ICO collection to examine
width	the preferred width (0 to use ICO header width)
height	the preferred height (0 to use ICO header height)