Matrix of pixels. More...

Collaboration diagram for Bitmap:

Detailed Description

Typedefs
typedef int	bj_pixel[2]
	Represents a pixel position in a bitmap.

typedef struct bj_bitmap_t	bj_bitmap
	Typedef for the bj_bitmap struct.

Functions
bj_bitmap *	bj_bitmap_alloc (void)
	Allocate a new bitmap object.

bj_bitmap *	bj_bitmap_new (size_t width, size_t height, bj_pixel_mode mode, size_t stride)
	Creates a new bj_bitmap with the specified width and height.

void	bj_bitmap_del (bj_bitmap *p_bitmap)
	Deletes a bj_bitmap object and releases associated memory.

bj_bitmap *	bj_bitmap_new_from_file (const char p_path, bj_error *p_error)
	Creates a new bitmap by loading from a file.

bj_bool	bj_bitmap_blit_stretched (const bj_bitmap p_source, const bj_rect p_source_area, bj_bitmap p_destination, const bj_rect p_destination_area)

Function Documentation

◆ bj_bitmap_alloc()

bj_bitmap * bj_bitmap_alloc ( void )

Returns: A new bj_bitmap instance

◆ bj_bitmap_blit_stretched()

bj_bool bj_bitmap_blit_stretched	(	const bj_bitmap *	p_source,
		const bj_rect *	p_source_area,
		bj_bitmap *	p_destination,
		const bj_rect *	p_destination_area )

Creates a new bj_bitmap with the specified width and height.

Contrary to \ref bj_bitmap_new, the pixel data is explicitely provided
by the caller through `p_pixels`.
The caller is responsible for ensuring the allocated pixel data matches
`width, `height`, `mode` and `stride`.

/ / You can use bj_compute_bitmap_stride with width and mode to / retrieve the most suitable value for stride. / It's also possible to set stride to 0 and let Banjo compute it / automatically. / /

Parameters

p_pixels	A pre-allocated array of pixels /
width	Width of the bitmap. /
height	Height of the bitmap. /
mode	The pixel mode. /
stride	The suggested bitmap stride. /

Returns: A new instance of bj_bitmap. / /

Behaviour: / / Returns 0 if p_pixels is 0. / /

Memory Management: / / The caller is responsible for the memory management of p_pixels. / bj_bitmap will not modify it and it will not be released upon calling / bj_bitmap_del. / / The caller is responsible for releasing the bitmap using bj_bitmap_del. / ////////////////////////////////////////////////////////////////////////////// bj_bitmap* bj_bitmap_new_from_pixels( void* p_pixels, size_t width, size_t height, bj_pixel_mode mode, size_t stride );

////////////////////////////////////////////////////////////////////////////// / Creates a new bj_bitmap by copying p_bitmap. / /

Parameters

p_bitmap The source bitmap. / /

Returns: A pointer to the newly created bj_bitmap object. / / The new bitmap will have exactly the same properties than the source bitmap. / /

Memory Management: / / The caller is responsible from releasing the bitmap using / bj_bitmap_del. / / If p_source was initially created using bj_bitmap_new_from_pixels, / the "weak" property of the bitmap is not maintained in the new bitmap and / the caller is not responsible for manually releasing its pixel data. / ////////////////////////////////////////////////////////////////////////////// bj_bitmap* bj_bitmap_copy( const bj_bitmap* p_bitmap );

////////////////////////////////////////////////////////////////////////////// / Creates a new bj_bitmap by converting p_bitmap. / /

Parameters

p_bitmap	The source bitmap. /
mode	The new pixel mode. / /

Returns: A pointer to the newly created bj_bitmap object. / / The new bitmap is provided by creating a new empty bitmap matching source's / width and height, but using mode as pixel mode. / The pixels are then converted to fill-in the new buffer. / /

Behaviour: / / Returns bj_bitmap_copy(p_bitmap) if mode == bj_bitmap_mode(p_bitmap). / / Returns 0 if mode is BJ_PIXEL_MODE_UNKNOWN or an unsupported value. / /

Memory Management: / / The caller is responsible from releasing the bitmap using / bj_bitmap_del. / / If p_bitmap was initially created using bj_bitmap_new_from_pixels, / the "weak" property of the bitmap is not maintained in the new bitmap and / the caller is not responsible for manually releasing its pixel data. / ////////////////////////////////////////////////////////////////////////////// bj_bitmap* bj_bitmap_convert( const bj_bitmap* p_bitmap, bj_pixel_mode mode );

////////////////////////////////////////////////////////////////////////////// / Initializes a new bj_bitmap with the specified width and height. / /

Parameters

p_bitmap	The bitmap object. /
p_pixels	The pixel buffer data. /
width	Width of the bitmap. /
height	Height of the bitmap. /
mode	The pixel mode. /
stride	The suggested bitmap stride. / / If the pixel buffer provided by `p_pixels` is 0, the buffer will allocate / /

Returns: A pointer to the newly created bj_bitmap object. / / The stride corresponds to the size in bytes of a row. / If the value is less than the required stride, the actual minimum stride / is used. ////////////////////////////////////////////////////////////////////////////// bj_bitmap* bj_bitmap_init( bj_bitmap* p_bitmap, void* p_pixels, size_t width, size_t height, bj_pixel_mode mode, size_t stride );

////////////////////////////////////////////////////////////////////////////// / Resets a bj_bitmap object making it ready for a new init or free. / /

Parameters

p_bitmap Pointer to the bj_bitmap object to reset. ////////////////////////////////////////////////////////////////////////////// void bj_bitmap_reset( bj_bitmap* p_bitmap );

////////////////////////////////////////////////////////////////////////////// / Get the underlying pixels data for direct access. / /

Parameters

p_bitmap The bitmap object. /

Returns: The buffer data. ////////////////////////////////////////////////////////////////////////////// void* bj_bitmap_pixels( bj_bitmap* p_bitmap );

////////////////////////////////////////////////////////////////////////////// / Get the width of the given bitmap / /

Parameters

p_bitmap The bitmap object. /

Returns: The bitmap width as number of pixels. ////////////////////////////////////////////////////////////////////////////// size_t bj_bitmap_width( const bj_bitmap* p_bitmap );

////////////////////////////////////////////////////////////////////////////// / Get the height of the given bitmap / /

Parameters

p_bitmap The bitmap object. /

Returns: The bitmap height as number of pixels. ////////////////////////////////////////////////////////////////////////////// size_t bj_bitmap_height( const bj_bitmap* p_bitmap );

////////////////////////////////////////////////////////////////////////////// / Get the pixel mode of the given bitmap / /

Parameters

p_bitmap The bitmap object. /

Returns: The bitmap pixel mode. ////////////////////////////////////////////////////////////////////////////// int bj_bitmap_mode( bj_bitmap* p_bitmap );

////////////////////////////////////////////////////////////////////////////// / Get the number of bytes in a row of pixel data, including the padding. / /

Parameters

p_bitmap The bitmap object. /

Returns: The bitmap stride ////////////////////////////////////////////////////////////////////////////// size_t bj_bitmap_stride( bj_bitmap* p_bitmap );

////////////////////////////////////////////////////////////////////////////// / Gets the RGB value of a pixel given its 32-bits representation. / /

Parameters

p_bitmap	The bitmap object /
x	The X coordinate of the pixel. /
y	The Y coordinate of the pixel. /
p_red	A location to the red component /
p_green	A location to the green component /
p_blue	A location to the blue component / ////////////////////////////////////////////////////////////////////////////// void bj_bitmap_rgb( const bj_bitmap* p_bitmap, size_t x, size_t y, uint8_t* p_red, uint8_t* p_green, uint8_t* p_blue );

////////////////////////////////////////////////////////////////////////////// / Returns an opaque value representing a pixel color, given its RGB composition. / /

Parameters

p_bitmap	The bitmap object. /
red	The red component of the color /
green	The green component of the color /
blue	The blue component of the color /

Returns: An opaque uint32_t value. / ////////////////////////////////////////////////////////////////////////////// uint32_t bj_bitmap_pixel_value( bj_bitmap* p_bitmap, uint8_t red, uint8_t green, uint8_t blue );

////////////////////////////////////////////////////////////////////////////// / Change the pixel color at given coordinate. / /

Parameters

p_bitmap	The bitmap object. /
x	The X coordinate of the pixel. /
y	The Y coordinate of the pixel. /
value	The pixel value to put. ////////////////////////////////////////////////////////////////////////////// void bj_bitmap_put_pixel( bj_bitmap* p_bitmap, size_t x, size_t y, uint32_t value );

////////////////////////////////////////////////////////////////////////////// / Fills the entire bitmap with the clear color. / /

Parameters

p_bitmap The bitmap object to reset. / / The clear color can be set with bj_bitmap_set_clear_color. / This function effectively fills all the pixels of the bitmap with / the clear color. ////////////////////////////////////////////////////////////////////////////// void bj_bitmap_clear( bj_bitmap* p_bitmap );

////////////////////////////////////////////////////////////////////////////// / Draws a line of pixels in the given bitmap. / / The line is drawn for each pixel between p0 and p1. / /

Parameters

p_bitmap	The bitmap object. /
p0	The first point in the line. /
p1	The second point in the line. /
pixel	The line pixel value. / /

Memory Safety: / / This function does not perform any bound checking on the pixel coordinates. / It is up to you to ensure the coordinates lie between / [0, bj_bitmap->width * bj_bitmap->height]. / Writing outside of these bounds will result in undefined behavior or / corrupted memory access. ////////////////////////////////////////////////////////////////////////////// void bj_bitmap_draw_line( bj_bitmap* p_bitmap, bj_pixel p0, bj_pixel p1, uint32_t pixel );

////////////////////////////////////////////////////////////////////////////// / Draws the edges of a triangle given its 3 corners. / /

Parameters

p_bitmap	The bitmap object. /
p0	The first point of the triangle. /
p1	The second point of the triangle. /
p2	The third point of the triangle. /
color	The line color. / /

Memory Safety: / / This function does not perform any bound checking on the pixel coordinates. / It is up to you to ensure the coordinates lie between / [0, bj_bitmap->width * bj_bitmap->height]. / Writing outside of these bounds will result in undefined behavior or / corrupted memory access. ////////////////////////////////////////////////////////////////////////////// void bj_bitmap_draw_triangle( bj_bitmap* p_bitmap, bj_pixel p0, bj_pixel p1, bj_pixel p2, uint32_t color );

////////////////////////////////////////////////////////////////////////////// / Gets the color of a bitmap pixel, given its coordinates. / /

Parameters

p_bitmap	The bitmap object. /
x	The X coordinate of the pixel. /
y	The Y coordinate of the pixel. /

Returns: The color at (x, y). / /

Memory Safety: / / This function does not perform any bound checking on the pixel coordinates. / It is up to you to ensure the coordinates lie between / [0, bj_bitmap->width * bj_bitmap->height]. / Writing outside of these bounds will result in undefined behavior or / corrupted memory access. ////////////////////////////////////////////////////////////////////////////// uint32_t bj_bitmap_get( const bj_bitmap* p_bitmap, size_t x, size_t y );

////////////////////////////////////////////////////////////////////////////// / Sets the color used for clearing the bitmap. / /

Parameters

p_bitmap	The target bitmap. /
clear_color	The new clear color. ////////////////////////////////////////////////////////////////////////////// void bj_bitmap_set_clear_color( bj_bitmap* p_bitmap, uint32_t clear_color );

////////////////////////////////////////////////////////////////////////////// / Bitmap blitting operation from a source to a destination bitmap. / /

Parameters

p_source	The source bj_bitmap to copy from. /
p_source_area	The area to copy from in the source bitmap. /
p_destination	The destination bitmap. /
p_destination_area	The area to copy to in the destination bitmap. /

Returns: BJ_TRUE if a blit actually happened, BJ_FALSE otherwise. / / If p_source_area is NULL, the entire bitmap is copied. / p_destination_area can also be NULL, which is equivalent to / using an area at {.x = 0, .y = 0}. / /

Clipping: / / The resulting blit can be clipped if it is performed partially or totally / outside of the destination bitmap. / / p_destination_area.w and p_destination_area.h are ignored for reading / but are set to the actual dimensions of the blit. / ////////////////////////////////////////////////////////////////////////////// bj_bool bj_bitmap_blit( const bj_bitmap* p_source, const bj_rect* p_source_area, bj_bitmap* p_destination, const bj_rect* p_destination_area );

////////////////////////////////////////////////////////////////////////////// / Stretched bitmap blitting operation from a source to a destination bitmap. / /

Parameters

p_source	The source bj_bitmap to copy from. /
p_source_area	The area to copy from in the source bitmap. /
p_destination	The destination bitmap. /
p_destination_area	The area to copy to in the destination bitmap. /

Returns: BJ_TRUE if a blit actually happened, BJ_FALSE otherwise. / / If p_source_area is 0, the entire bitmap is copied. / If p_destination_area is 0, the source will fill in the entire / destination bitmap. / / Contrary to bj_bitmap_blit, this function scales the source bitmap's / area to fille the entire destination area. / /

Behaviour

/ / The scale is done using nearest interpolation (the nearest real pixel in / source area is used to color the destination pixel). / This scale is suitable for pixel-art programs but will make the sprites / appear jagged. / / The blit is not performed if the source or destination area have .w or / .h set to 0.

\par Clipping

The resulting blit can be clipped if it is performed partially or totally
outside of the destination bitmap.

Examples: load_bmp.c, and sprite_animation.c.

◆ bj_bitmap_del()

void bj_bitmap_del ( bj_bitmap * p_bitmap )

Parameters

p_bitmap Pointer to the bj_bitmap object to delete.

Examples: bitmap_blit.c, load_bmp.c, and sprite_animation.c.

◆ bj_bitmap_new()

bj_bitmap * bj_bitmap_new	(	size_t	width,
		size_t	height,
		bj_pixel_mode	mode,
		size_t	stride )

Parameters

width	Width of the bitmap.
height	Height of the bitmap.
mode	The pixel mode.
stride	The suggested bitmap stride.

Returns: A pointer to the newly created bj_bitmap object.

The stride corresponds to the size in bytes of a row. If the value is less than the required stride, the actual minimum stride is used. Set it to 0 to automatically compute the stride.

Examples: bitmap_blit.c, and sprite_animation.c.

◆ bj_bitmap_new_from_file()

bj_bitmap * bj_bitmap_new_from_file	(	const char *	p_path,
		bj_error **	p_error )

Parameters

p_path	Path to the bitmap file.
p_error	Pointer to an error object to store any errors encountered during loading.

Returns: A pointer to the newly created bj_bitmap object, or 0 if loading failed.

The new object must be deleted using bj_bitmap_del.

Pixel Mode

Banjo supports the reading or 1, 4, 8, 24 and 32 bits per pixels images. Reading RLE encoding for 4 and 8 bpp is also supported.

According to the file compression (MSDN) and the pixel byte size, the created Bitmap will have one of the following pixel mode:

Bits Per Pixel	Compression	`bj_pixel_mode`
1	`BI_RGB`	`BJ_PIXEL_MODE_INDEXED_1`
4	`BI_RGB`	`BJ_PIXEL_MODE_INDEXED_4`
4	`BJ_RLE4`	`BJ_PIXEL_MODE_INDEXED_4`
8	`BI_RGB`	`BJ_PIXEL_MODE_INDEXED_8`
8	`BI_RLE8`	`BJ_PIXEL_MODE_INDEXED_8`
16	`BI_RGB`	`BJ_PIXEL_MODE_XRGB1555`
16	`BI_BITFIELDS`	Depends on bit fields
24	`BI_RGB`	`BJ_PIXEL_MODE_BGR24`
32	`BI_RGB`	`BJ_PIXEL_MODE_XRGB8888`
32	`BI_BITFIELDS`	Depends on bit fields

Banjo does not support all bitfield configuration. The following table shows our supported bit fields:

Bits Per Pixel	Red Mask	Green Mask	Blue Mask	`bj_pixel_mode`
16	`0x0000F800`	`0x000007E0`	`0x0000001F`	`BJ_PIXEL_MODE_RGB565`
32	`0x00FF0000`	`0x0000FF00`	`0x000000FF`	`BJ_PIXEL_MODE_XRGB8888`

Any other configuration leads to either BJ_PIXEL_MODE_UNKNOWN or a failure in loading the file.

Once loaded, the pixel mode can be retrieved using bj_bitmap_mode.

Edge cases

If a bitmap indicates a color palette size but the file does not contain any palette, a same size palette is provided with the first index set to black (red = 0x00, green = 0x00, blue = 0x00) and remaining colors to white (red = 0xFF, green = 0xFF, blue = 0xFF). Banjo does not consider such bitmaps as invalid, but a warning message is logged.

Limitations

While reading indexed Bitmap works, 1, 4 and 8bpp images are automatically converted to 24bpp images for now.

See also: BMP file format (Wikipedia); Bitmap Compression (MSDN)

Examples: bitmap_blit.c, load_bmp.c, and sprite_animation.c.

Detailed Description

Typedefs

Functions

Function Documentation

◆ bj_bitmap_alloc()

◆ bj_bitmap_blit_stretched()

◆ bj_bitmap_del()

◆ bj_bitmap_new()

◆ bj_bitmap_new_from_file()