|
| void | bj_unpack_pixel_rgb (enum bj_pixel_mode mode, uint32_t value, uint8_t *red, uint8_t *green, uint8_t *blue) |
| 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_pack_pixel_rgb (enum bj_pixel_mode mode, 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) |
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
uint8_t r, g, b;
void bj_unpack_pixel_rgb(enum bj_pixel_mode mode, uint32_t value, uint8_t *red, uint8_t *green, uint8_t *blue)
Unpacks the red, green, and blue components of a packed pixel value.
uint32_t bj_pack_pixel_rgb(enum bj_pixel_mode mode, uint8_t red, uint8_t green, uint8_t blue)
Packs red, green, and blue components into one opaque pixel value.
@ BJ_PIXEL_MODE_RGB565
16bpp 565-RGB
When drawing into a specific bitmap, prefer bj_pack_bitmap_rgb. 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.
◆ BJ_PIXEL_GET_BPP
| #define BJ_PIXEL_GET_BPP |
( |
| fmt | ) |
|
Value:
Extracts the bits-per-pixel from a pixel format.
- Parameters
-
Definition at line 284 of file pixel.h.
◆ BJ_PIXEL_GET_LAYOUT
| #define BJ_PIXEL_GET_LAYOUT |
( |
| fmt | ) |
|
Value:
Extracts the pixel layout from a pixel format.
- Parameters
-
Definition at line 296 of file pixel.h.
◆ BJ_PIXEL_GET_ORDER
| #define BJ_PIXEL_GET_ORDER |
( |
| fmt | ) |
|
Value:
Extracts the pixel order from a pixel format.
- Parameters
-
Definition at line 302 of file pixel.h.
◆ BJ_PIXEL_GET_TYPE
| #define BJ_PIXEL_GET_TYPE |
( |
| fmt | ) |
|
Value:
Extracts the pixel type from a pixel format.
- Parameters
-
Definition at line 290 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 238 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 242 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 240 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 251 of file pixel.h.
◆ BJ_PIXEL_MODE_MAKE_BITFIELD_16
| #define BJ_PIXEL_MODE_MAKE_BITFIELD_16 |
( |
| layout, |
|
|
| order ) |
Value:
#define BJ_PIXEL_MODE_MAKE(bpp, type, layout, order)
Creates a pixel format mode from bits-per-pixel, type, layout, and order.
#define BJ_PIXEL_TYPE_BITFIELD
Pixel type: Bitfield representation (e.g., RGB565).
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 264 of file pixel.h.
◆ BJ_PIXEL_MODE_MAKE_BITFIELD_32
| #define BJ_PIXEL_MODE_MAKE_BITFIELD_32 |
( |
| layout, |
|
|
| order ) |
Value:
Creates a 32-bit bitfield pixel format.
- Parameters
-
| layout | Pixel layout (e.g., 8888). |
| order | Pixel order (e.g., RGB, ARGB). |
Definition at line 271 of file pixel.h.
◆ BJ_PIXEL_MODE_MAKE_BYTES
| #define BJ_PIXEL_MODE_MAKE_BYTES |
( |
| bpp, |
|
|
| order ) |
Value:
#define BJ_PIXEL_TYPE_BYTES
Pixel type: Byte-packed representation (e.g., RGBA8888).
Creates a byte-packed pixel format.
- Parameters
-
| bpp | Bits-per-pixel. |
| order | Pixel order (e.g., RGB, ARGB). |
Definition at line 278 of file pixel.h.
◆ BJ_PIXEL_MODE_MAKE_INDEXED
| #define BJ_PIXEL_MODE_MAKE_INDEXED |
( |
| bpp | ) |
|
Value:
#define BJ_PIXEL_TYPE_INDEX
Pixel type: Indexed (palette-based).
Creates a pixel format for indexed (palette-based) pixels.
- Parameters
-
Definition at line 257 of file pixel.h.
◆ BJ_PIXEL_ORDER_ABGR
| #define BJ_PIXEL_ORDER_ABGR 0x06 |
Pixel order: Alpha-Blue-Green-Red (ABGR).
Definition at line 231 of file pixel.h.
◆ BJ_PIXEL_ORDER_ARGB
| #define BJ_PIXEL_ORDER_ARGB 0x05 |
Pixel order: Alpha-Red-Green-Blue (ARGB).
Definition at line 229 of file pixel.h.
◆ BJ_PIXEL_ORDER_BGR
| #define BJ_PIXEL_ORDER_BGR 0x02 |
Pixel order: Blue-Green-Red (BGR).
Definition at line 221 of file pixel.h.
◆ BJ_PIXEL_ORDER_BGRA
| #define BJ_PIXEL_ORDER_BGRA 0x08 |
Pixel order: Blue-Green-Red-Alpha (BGRA).
Definition at line 235 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 227 of file pixel.h.
◆ BJ_PIXEL_ORDER_RGB
| #define BJ_PIXEL_ORDER_RGB 0x01 |
Pixel order: Red-Green-Blue (RGB).
Definition at line 217 of file pixel.h.
◆ BJ_PIXEL_ORDER_RGBA
| #define BJ_PIXEL_ORDER_RGBA 0x07 |
Pixel order: Red-Green-Blue-Alpha (RGBA).
Definition at line 233 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 225 of file pixel.h.
◆ BJ_PIXEL_ORDER_XBGR
Pixel order: Same as BJ_PIXEL_ORDER_BGR with unused alpha.
Definition at line 223 of file pixel.h.
◆ BJ_PIXEL_ORDER_XRGB
Pixel order: Same as BJ_PIXEL_ORDER_RGB with unused alpha.
Definition at line 219 of file pixel.h.
◆ BJ_PIXEL_TYPE_BITFIELD
| #define BJ_PIXEL_TYPE_BITFIELD 0x02 |
Pixel type: Bitfield representation (e.g., RGB565).
Definition at line 212 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 214 of file pixel.h.
◆ BJ_PIXEL_TYPE_INDEX
| #define BJ_PIXEL_TYPE_INDEX 0x01 |
Pixel type: Indexed (palette-based).
Definition at line 210 of file pixel.h.
◆ bj_pixel_mode
◆ 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, and random_distribution.c.
Definition at line 86 of file pixel.h.
◆ 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 computes the stride for the predefined BJ_PIXEL_MODE_* modes and aligns the byte count to 4; any other mode, even one with the same bits per pixel, gives 0. A row whose aligned byte count does not fit a size_t gives 0 too.
- 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 ) |
◆ 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 ) |
◆ bj_pack_pixel_rgb()
| uint32_t bj_pack_pixel_rgb |
( |
enum bj_pixel_mode | mode, |
|
|
uint8_t | red, |
|
|
uint8_t | green, |
|
|
uint8_t | blue ) |
Packs red, green, and blue components into one opaque pixel value.
An indexed or unknown mode, and a bitfield mode whose layout is none of the BJ_PIXEL_LAYOUT_* values, have no colour: they pack to 0.
- 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_unpack_pixel_rgb()
| void bj_unpack_pixel_rgb |
( |
enum bj_pixel_mode | mode, |
|
|
uint32_t | value, |
|
|
uint8_t * | red, |
|
|
uint8_t * | green, |
|
|
uint8_t * | blue ) |
Unpacks the red, green, and blue components of a packed pixel value.
A channel of fewer than 8 bits is widened by repeating its top bits in its low ones, so a full channel unpacks to 0xFF and an empty one to 0, and packing the result gives the value back.
An indexed or unknown mode, and a bitfield mode whose layout is none of the BJ_PIXEL_LAYOUT_* values, have no colour: they unpack to black.
- Parameters
-
| mode | The pixel mode |
| value | The opaque pixel value |
| red | A location to the red component, or 0 to skip it |
| green | A location to the green component, or 0 to skip it |
| blue | A location to the blue component, or 0 to skip it |
- Examples
- random_distribution.c.
Referenced by darken_color().