Banjo API 1.1.0-alpha
Low-level C99 game development API
Loading...
Searching...
No Matches
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_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)

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_pack_pixel_rgb(BJ_PIXEL_MODE_RGB565, 0xFF, 0x80, 0x00);
// Unpack a packed pixel back into R, G, B bytes
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
Definition pixel.h:93

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.

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
fmtPixel format value.

Definition at line 284 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
fmtPixel format value.

Definition at line 296 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
fmtPixel format value.

Definition at line 302 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
fmtPixel format value.

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
bppBits-per-pixel.
typePixel type (e.g., indexed, bitfield, or bytes).
layoutPixel layout (e.g., 1555, 8888, or 565).
orderPixel 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.
Definition pixel.h:251
#define BJ_PIXEL_TYPE_BITFIELD
Pixel type: Bitfield representation (e.g., RGB565).
Definition pixel.h:212

Creates a 16-bit bitfield pixel format.

Parameters
layoutPixel layout (e.g., 1555, 565).
orderPixel 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
layoutPixel layout (e.g., 8888).
orderPixel 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).
Definition pixel.h:214

Creates a byte-packed pixel format.

Parameters
bppBits-per-pixel.
orderPixel 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).
Definition pixel.h:210

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

Parameters
bppBits-per-pixel.

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

#define BJ_PIXEL_ORDER_XBGR   BJ_PIXEL_ORDER_BGR

Pixel order: Same as BJ_PIXEL_ORDER_BGR with unused alpha.

Definition at line 223 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 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.

Typedef Documentation

◆ bj_pixel_mode

Definition at line 99 of file pixel.h.

Enumeration Type Documentation

◆ 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.

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 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
widthThe width in pixel of a row
modeThe 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
bppThe number of bits used to encode a pixel.
red_maskA bitmask for the red channel information in the bits.
green_maskA bitmask for the green channel information in the bits.
blue_maskA 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 )
Deprecated
Renamed to bj_pack_pixel_rgb. Removed in 2.0.

◆ 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 )
Deprecated
Renamed to bj_unpack_pixel_rgb. Removed in 2.0.

◆ 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
modeThe pixel mode
redThe red component of the colour
greenThe green component of the colour
blueThe 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
modeThe pixel mode
valueThe opaque pixel value
redA location to the red component, or 0 to skip it
greenA location to the green component, or 0 to skip it
blueA location to the blue component, or 0 to skip it
Examples
random_distribution.c.

Referenced by darken_color().