Pixel Definition

Collaboration diagram for Pixel Definition:

Macros
#define	BJ_PIXEL_TYPE_INDEX   0x01
#define	BJ_PIXEL_TYPE_BITFIELD   0x02
#define	BJ_PIXEL_TYPE_BYTES   0x03
#define	BJ_PIXEL_ORDER_RGB   0x01
#define	BJ_PIXEL_ORDER_XRGB   BJ_PIXEL_ORDER_RGB
#define	BJ_PIXEL_ORDER_BGR   0x02
#define	BJ_PIXEL_ORDER_XBGR   BJ_PIXEL_ORDER_BGR
#define	BJ_PIXEL_ORDER_RGBX   0x03
#define	BJ_PIXEL_ORDER_BGRX   0x04
#define	BJ_PIXEL_ORDER_ARGB   0x05
#define	BJ_PIXEL_ORDER_ABGR   0x06
#define	BJ_PIXEL_ORDER_RGBA   0x07
#define	BJ_PIXEL_ORDER_BGRA   0x08
#define	BJ_PIXEL_LAYOUT_1555   0x00
#define	BJ_PIXEL_LAYOUT_8888   0x01
#define	BJ_PIXEL_LAYOUT_565   0x02
#define	BJ_PIXEL_MODE_MAKE(bpp, type, layout, order)
#define	BJ_PIXEL_MODE_MAKE_INDEXED(bpp)
#define	BJ_PIXEL_MODE_MAKE_BITFIELD_16(layout, order)
#define	BJ_PIXEL_MODE_MAKE_BITFIELD_32(layout, order)
#define	BJ_PIXEL_MODE_MAKE_BYTES(bpp, order)
#define	BJ_PIXEL_GET_BPP(fmt)
#define	BJ_PIXEL_GET_TYPE(fmt)
#define	BJ_PIXEL_GET_LAYOUT(fmt)
#define	BJ_PIXEL_GET_ORDER(fmt)

Typedefs
typedef enum bj_pixel_mode	bj_pixel_mode

Enumerations
enum	bj_pixel_mode {   BJ_PIXEL_MODE_UNKNOWN = 0x00u , BJ_PIXEL_MODE_INDEXED_1 = 0x00000101u , BJ_PIXEL_MODE_INDEXED_4 = 0x00000104u , BJ_PIXEL_MODE_INDEXED_8 = 0x00000108u ,   BJ_PIXEL_MODE_XRGB1555 = 0x01000210u , BJ_PIXEL_MODE_RGB565 = 0x01020210u , BJ_PIXEL_MODE_XRGB8888 = 0x01010220u , BJ_PIXEL_MODE_BGR24 = 0x02000318u }

Functions
void	bj_make_pixel_rgb (enum bj_pixel_mode mode, uint32_t value, uint8_t *red, uint8_t *green, uint8_t *blue)
uint32_t	bj_get_pixel_value (enum bj_pixel_mode mode, uint8_t red, uint8_t green, uint8_t blue)
int	bj_compute_pixel_mode (uint8_t bpp, uint32_t red_mask, uint32_t green_mask, uint32_t blue_mask)
size_t	bj_compute_bitmap_stride (size_t width, enum bj_pixel_mode mode)

Detailed Description

How a pixel's colour is stored in memory.

A pixel in a Banjo bitmap is just a small block of bytes (one to four, depending on the bitmap) that encodes one dot of colour. The interesting question is what those bytes mean: is the first byte red, or blue? Is the colour stored as (R, G, B) directly, or as an index into a separate palette? How many bits go to each channel?

Banjo answers that with a pixel mode (bj_pixel_mode). A pixel mode is a 32-bit value that says four things at once:

• bits-per-pixel: 8, 16, 24, 32, i.e. how many bits one pixel occupies.
• type: indexed (the pixel byte is an index into a palette of colours), bitfield (red, green, blue squeezed into specific bit positions of a 16- or 32-bit word), or bytes (each channel in its own byte).
• layout: e.g. 8888 (each of 4 channels gets 8 bits), 565 (5 bits red, 6 bits green, 5 bits blue, a common 16-bit format).
• channel order: e.g. RGB, BGR, ARGB, BGRA, i.e. what order the channels appear in the bytes.

The fields are packed into one 32-bit integer like this:

+----------+------------+------------+----------+
|  order   |   layout   |   type     |   bpp    |
| (8 bits) |  (8 bits)  |  (8 bits)  | (8 bits) |
+----------+------------+------------+----------+
  MSB                                       LSB

You rarely build pixel modes from scratch: Banjo provides constants for the common cases: BJ_PIXEL_MODE_INDEXED_1 / _4 / _8, BJ_PIXEL_MODE_XRGB1555, BJ_PIXEL_MODE_RGB565, BJ_PIXEL_MODE_XRGB8888, BJ_PIXEL_MODE_BGR24. If you do need to compose a custom one, the BJ_PIXEL_MODE_MAKE macros build them from (bpp, type, layout, order), and BJ_PIXEL_GET_* decodes an existing mode back into those parts.

Pack and unpack a pixel by hand

// Pack (R, G, B) into one 16-bit RGB565 value
uint32_t pixel = bj_get_pixel_value(BJ_PIXEL_MODE_RGB565, 0xFF, 0x80, 0x00);
 
// Unpack a packed pixel back into R, G, B bytes
uint8_t r, g, b;
bj_make_pixel_rgb(BJ_PIXEL_MODE_RGB565, pixel, &r, &g, &b);

When drawing into a specific bitmap, prefer bj_make_bitmap_pixel. It reads the mode from the bitmap so you don't have to pass it. The whole reason pixel modes exist as data (rather than each function having an _RGB565, _XRGB8888, _INDEXED_8 variant) is so the same drawing code works on any bitmap, whatever its format.

Stride: how many bytes one row really takes

A row of pixels can take more bytes than width * bytes_per_pixel because Banjo pads each row up to a multiple of 4 bytes (this makes memory access faster on most CPUs). The padded number is the stride. bj_compute_bitmap_stride computes it for you, so the total memory needed for a width × height bitmap is bj_compute_bitmap_stride(width, mode) * height.

See also

pixel_mode.c for a runnable demo, Bitmap for the Bitmap container that uses these modes.

Macro Definition Documentation

BJ_PIXEL_GET_BPP

#define BJ_PIXEL_GET_BPP

(

fmt

)

Value:

((fmt) & 0xFF)

Extracts the bits-per-pixel from a pixel format.

Parameters

fmt	Pixel format value.

Definition at line 255 of file pixel.h.

BJ_PIXEL_GET_LAYOUT

#define BJ_PIXEL_GET_LAYOUT

(

fmt

)

Value:

(((fmt) >> 16) & 0xFF)

Extracts the pixel layout from a pixel format.

Parameters

fmt	Pixel format value.

Definition at line 267 of file pixel.h.

BJ_PIXEL_GET_ORDER

#define BJ_PIXEL_GET_ORDER

(

fmt

)

Value:

(((fmt) >> 24) & 0xFF)

Extracts the pixel order from a pixel format.

Parameters

fmt	Pixel format value.

Definition at line 273 of file pixel.h.

BJ_PIXEL_GET_TYPE

#define BJ_PIXEL_GET_TYPE

(

fmt

)

Value:

(((fmt) >> 8) & 0xFF)

Extracts the pixel type from a pixel format.

Parameters

fmt	Pixel format value.

Definition at line 261 of file pixel.h.

BJ_PIXEL_LAYOUT_1555

#define BJ_PIXEL_LAYOUT_1555   0x00

Pixel layout: 16-bit with 1-bit alpha, 5-bit red, green, and blue (1555).

Definition at line 209 of file pixel.h.

BJ_PIXEL_LAYOUT_565

#define BJ_PIXEL_LAYOUT_565   0x02

Pixel layout: 16-bit with 5 bits for red and blue, 6 bits for green (565).

Definition at line 213 of file pixel.h.

BJ_PIXEL_LAYOUT_8888

#define BJ_PIXEL_LAYOUT_8888   0x01

Pixel layout: 32-bit with 8 bits per channel (8888).

Definition at line 211 of file pixel.h.

BJ_PIXEL_MODE_MAKE

#define BJ_PIXEL_MODE_MAKE	(		bpp,
			type,
			layout,
			order )

Value:

(((order & 0xFF) << 24) | ((layout & 0xFF) << 16) | ((type & 0xFF) << 8) | (bpp & 0xFF))

Creates a pixel format mode from bits-per-pixel, type, layout, and order.

Parameters

bpp	Bits-per-pixel.
type	Pixel type (e.g., indexed, bitfield, or bytes).
layout	Pixel layout (e.g., 1555, 8888, or 565).
order	Pixel order (e.g., RGB, ARGB, etc.).

Definition at line 222 of file pixel.h.

BJ_PIXEL_MODE_MAKE_BITFIELD_16

#define BJ_PIXEL_MODE_MAKE_BITFIELD_16	(		layout,
			order )

Value:

BJ_PIXEL_MODE_MAKE(16, BJ_PIXEL_TYPE_BITFIELD, layout, order)

Creates a 16-bit bitfield pixel format.

Parameters

layout	Pixel layout (e.g., 1555, 565).
order	Pixel order (e.g., RGB, ARGB).

Definition at line 235 of file pixel.h.

BJ_PIXEL_MODE_MAKE_BITFIELD_32

#define BJ_PIXEL_MODE_MAKE_BITFIELD_32	(		layout,
			order )

Value:

BJ_PIXEL_MODE_MAKE(32, BJ_PIXEL_TYPE_BITFIELD, layout, order)

Creates a 32-bit bitfield pixel format.

Parameters

layout	Pixel layout (e.g., 8888).
order	Pixel order (e.g., RGB, ARGB).

Definition at line 242 of file pixel.h.

BJ_PIXEL_MODE_MAKE_BYTES

#define BJ_PIXEL_MODE_MAKE_BYTES	(		bpp,
			order )

Value:

BJ_PIXEL_MODE_MAKE(bpp, BJ_PIXEL_TYPE_BYTES, 0, order)

Creates a byte-packed pixel format.

Parameters

bpp	Bits-per-pixel.
order	Pixel order (e.g., RGB, ARGB).

Definition at line 249 of file pixel.h.

BJ_PIXEL_MODE_MAKE_INDEXED

#define BJ_PIXEL_MODE_MAKE_INDEXED

(

bpp

)

Value:

BJ_PIXEL_MODE_MAKE(bpp, BJ_PIXEL_TYPE_INDEX, 0, 0)

Creates a pixel format for indexed (palette-based) pixels.

Parameters

bpp	Bits-per-pixel.

Definition at line 228 of file pixel.h.

BJ_PIXEL_ORDER_ABGR

#define BJ_PIXEL_ORDER_ABGR   0x06

Pixel order: Alpha-Blue-Green-Red (ABGR).

Definition at line 202 of file pixel.h.

BJ_PIXEL_ORDER_ARGB

#define BJ_PIXEL_ORDER_ARGB   0x05

Pixel order: Alpha-Red-Green-Blue (ARGB).

Definition at line 200 of file pixel.h.

BJ_PIXEL_ORDER_BGR

#define BJ_PIXEL_ORDER_BGR   0x02

Pixel order: Blue-Green-Red (BGR).

Definition at line 192 of file pixel.h.

BJ_PIXEL_ORDER_BGRA

#define BJ_PIXEL_ORDER_BGRA   0x08

Pixel order: Blue-Green-Red-Alpha (BGRA).

Definition at line 206 of file pixel.h.

BJ_PIXEL_ORDER_BGRX

#define BJ_PIXEL_ORDER_BGRX   0x04

Pixel order: Blue-Green-Red with padding byte (BGRX).

Definition at line 198 of file pixel.h.

BJ_PIXEL_ORDER_RGB

#define BJ_PIXEL_ORDER_RGB   0x01

Pixel order: Red-Green-Blue (RGB).

Definition at line 188 of file pixel.h.

BJ_PIXEL_ORDER_RGBA

#define BJ_PIXEL_ORDER_RGBA   0x07

Pixel order: Red-Green-Blue-Alpha (RGBA).

Definition at line 204 of file pixel.h.

BJ_PIXEL_ORDER_RGBX

#define BJ_PIXEL_ORDER_RGBX   0x03

Pixel order: Red-Green-Blue with padding byte (RGBX).

Definition at line 196 of file pixel.h.

BJ_PIXEL_ORDER_XBGR

#define BJ_PIXEL_ORDER_XBGR   BJ_PIXEL_ORDER_BGR

Pixel order: Same as BJ_PIXEL_ORDER_BGR with unused alpha.

Definition at line 194 of file pixel.h.

BJ_PIXEL_ORDER_XRGB

#define BJ_PIXEL_ORDER_XRGB   BJ_PIXEL_ORDER_RGB

Pixel order: Same as BJ_PIXEL_ORDER_RGB with unused alpha.

Definition at line 190 of file pixel.h.

BJ_PIXEL_TYPE_BITFIELD

#define BJ_PIXEL_TYPE_BITFIELD   0x02

Pixel type: Bitfield representation (e.g., RGB565).

Definition at line 183 of file pixel.h.

BJ_PIXEL_TYPE_BYTES

#define BJ_PIXEL_TYPE_BYTES   0x03

Pixel type: Byte-packed representation (e.g., RGBA8888).

Definition at line 185 of file pixel.h.

BJ_PIXEL_TYPE_INDEX

#define BJ_PIXEL_TYPE_INDEX   0x01

Pixel type: Indexed (palette-based).

Definition at line 181 of file pixel.h.

Typedef Documentation

bj_pixel_mode

typedef enum bj_pixel_mode bj_pixel_mode

Definition at line 99 of file pixel.h.

Enumeration Type Documentation

bj_pixel_mode

enum bj_pixel_mode

Representation of a pixel encoding.

Enumerator
BJ_PIXEL_MODE_UNKNOWN	Unknown/Invalid pixel mode.
BJ_PIXEL_MODE_INDEXED_1	1bpp indexed
BJ_PIXEL_MODE_INDEXED_4	4bpp indexed
BJ_PIXEL_MODE_INDEXED_8	8bpp indexed
BJ_PIXEL_MODE_XRGB1555	16bpp 555-RGB
BJ_PIXEL_MODE_RGB565	16bpp 565-RGB
BJ_PIXEL_MODE_XRGB8888	32bpp RGB
BJ_PIXEL_MODE_BGR24	24bpp BGR

Examples

pixel_mode.c.

Definition at line 86 of file pixel.h.

Function Documentation

bj_compute_bitmap_stride()

size_t bj_compute_bitmap_stride	(	size_t	width,
		enum bj_pixel_mode	mode )

Returns the stride used for encoding a bitmaps in Banjo.

In a bitmap, the stride is the actual number of bytes used to encode a single row of pixels. Hence, the total size needed for a bitmap of width x height encoded with mode is equal to bj_compute_bitmap_stride(width, mode) * height.

Banjo uses the bits-per-pixel information from mode to compute the stride and aligns the byte count to 4.

Parameters

width	The width in pixel of a row
mode	The pixel mode

Returns

The bitmap stride in bytes

bj_compute_pixel_mode()

int bj_compute_pixel_mode	(	uint8_t	bpp,
		uint32_t	red_mask,
		uint32_t	green_mask,
		uint32_t	blue_mask )

Determine the most suitable bj_pixel_mode from a set of masks.

This function can be used to retrieve what Banjo consider as the pixel mode corresponding to a given depth and masks.

If not suitable pixel mode is found, BJ_PIXEL_MODE_UNKNOWN is returned.

Parameters

bpp	The number of bits used to encode a pixel.
red_mask	A bitmask for the red channel information in the bits.
green_mask	A bitmask for the green channel information in the bits.
blue_mask	A bitmask for the blue channel information in the bits.

Returns

A bj_pixel_mode value.

bj_get_pixel_value()

uint32_t bj_get_pixel_value	(	enum bj_pixel_mode	mode,
		uint8_t	red,
		uint8_t	green,
		uint8_t	blue )

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

Parameters

mode	The pixel mode
red	The red component of the colour
green	The green component of the colour
blue	The blue component of the colour

Returns

An opaque uint32_t value.

Examples

physics_kinematics.c, physics_particle.c, pixel_mode.c, and random_distribution.c.

Referenced by display_value(), draw(), init_asteroids(), init_distributions(), initialize(), and reset_ball().

bj_make_pixel_rgb()

void bj_make_pixel_rgb	(	enum bj_pixel_mode	mode,
		uint32_t	value,
		uint8_t *	red,
		uint8_t *	green,
		uint8_t *	blue )

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

Parameters

mode	The pixel mode
value	The opaque pixel value
red	A location to the red component
green	A location to the green component
blue	A location to the blue component

Examples

random_distribution.c.

Referenced by darken_color().