Pixels

The Pixel module provides shared types and drawing primitives for software framebuffers and display-backed surfaces. More...

Collaboration diagram for Pixels:

Modules
	Bitmap
	A bitmap is a plain, backend-agnostic pixel buffer descriptor - see pix_bitmap_t's own doc.
	Display
	Displays can be created by a backend, which returns a pix_display_t handle.

Files
file	color.h
	RGBA color type and helpers.

Data Structures
struct	pix_point_t
	Point structure representing X,Y coordinates. More...
struct	pix_size_t
	Size structure representing width and height dimensions. More...

Macros
#define	PIX_COLOR_NONE   0x00000000u
	Fully transparent (all channels zero) - a "no color" sentinel, distinct from the opaque PIX_COLOR_BLACK.
#define	PIX_COLOR_BLACK   0x000000FFu
	Common opaque colors (0xRRGGBBAA).
#define	PIX_COLOR_RGBA(r, g, b, a)
	Construct a pix_color_t from separate R/G/B/A components. More...
#define	PIX_COLOR_RGB(r, g, b)   PIX_COLOR_RGBA(r, g, b, 0xFFu)
	Construct a fully-opaque pix_color_t from R/G/B components.

Typedefs
typedef uint32_t	pix_color_t
	Color value type for pixel operations. More...

Enumerations
enum	pix_format_t { PIX_FMT_RGBA32, PIX_FMT_RGB888, PIX_FMT_RGB565, PIX_FMT_MONO }
	Pixel format enumeration defining color depth and layout. More...
enum	pix_op_t { PIX_SET, PIX_BLEND }
	Compositing mode for drawing operations. More...

Functions
static uint8_t	pix_color_r (pix_color_t color)
	Extract the red channel.
static uint8_t	pix_color_g (pix_color_t color)
	Extract the green channel.
static uint8_t	pix_color_b (pix_color_t color)
	Extract the blue channel.
static uint8_t	pix_color_a (pix_color_t color)
	Extract the alpha channel.
static pix_color_t	pix_color_blend (pix_color_t src, pix_color_t dst)
	Alpha-composite src over dst ("over" compositing). More...

Scheduling
bool	pix_poll (void)
	Service whichever allocated display needs updating. More...

Detailed Description

The Pixel module provides shared types and drawing primitives for software framebuffers and display-backed surfaces.

Macro Definition Documentation

PIX_COLOR_RGBA

#define PIX_COLOR_RGBA	(		r,
			g,
			b,
			a
	)

Value:

((pix_color_t)(((uint32_t)(uint8_t)(r) << 24) |                            \
                ((uint32_t)(uint8_t)(g) << 16) |                            \
                ((uint32_t)(uint8_t)(b) << 8) |                              \
                (uint32_t)(uint8_t)(a)))

Construct a pix_color_t from separate R/G/B/A components.

Definition at line 46 of file color.h.

Typedef Documentation

pix_color_t

typedef uint32_t pix_color_t

Color value type for pixel operations.

Encoded as 0xRRGGBBAA (red in the most-significant byte, alpha in the least-significant byte). This is independent of any particular storage layout (e.g. a bitmap's own pixel format) - it's how a single color is passed around, not how a buffer of pixels is packed in memory.

Definition at line 17 of file color.h.

Enumeration Type Documentation

pix_format_t

enum pix_format_t

Pixel format enumeration defining color depth and layout.

Enumerator
PIX_FMT_RGBA32	32-bit RGBA format with alpha channel
PIX_FMT_RGB888	24-bit RGB format without alpha channel
PIX_FMT_RGB565	16-bit RGB format without alpha channel
PIX_FMT_MONO	Monochrome format (1-bit per pixel)

Definition at line 35 of file types.h.

             {
  PIX_FMT_RGBA32, 
  PIX_FMT_RGB888, 
  PIX_FMT_RGB565, 
  PIX_FMT_MONO,   
} pix_format_t;

pix_op_t

enum pix_op_t

Compositing mode for drawing operations.

Enumerator
PIX_SET	Overwrite the destination outright with the drawn color as given, alpha channel included - no compositing against the destination's previous color.
PIX_BLEND	Alpha-composite the drawn color over the destination's existing color ("src over dst") - see pix_color_blend.

Definition at line 46 of file types.h.

             {
  PIX_SET,   
  PIX_BLEND, 
} pix_op_t;

Function Documentation

pix_color_blend()

static pix_color_t pix_color_blend ( pix_color_t  src, pix_color_t  dst  )

inlinestatic

Alpha-composite src over dst ("over" compositing).

Parameters

src	The color being drawn.
dst	The color already there.

Returns

The blended color. Exactly src when src is fully opaque, exactly dst when src is fully transparent - callers on a hot path may want to special-case those rather than call this.

Definition at line 99 of file color.h.

                                                                            {
  uint32_t sa = pix_color_a(src);
  uint32_t da = pix_color_a(dst);
  uint32_t ia = 255u - sa;

  // dst's RGB must be weighted by dst's own alpha too - a partially
  // transparent dst shouldn't contribute its raw RGB at full strength, the
  // same way its own draw would only have partially covered whatever was
  // beneath it. The result is then un-premultiplied by the composited
  // alpha, since pix_color_t stores straight (not premultiplied) RGB.
  uint32_t out_a = sa + (da * ia + 127u) / 255u;
  if (out_a == 0) {
    return PIX_COLOR_NONE;
  }

  uint32_t denom = out_a * 255u;
  uint32_t half = denom / 2u;
  uint8_t r = (uint8_t)((pix_color_r(src) * sa * 255u +
                        pix_color_r(dst) * da * ia + half) / denom);
  uint8_t g = (uint8_t)((pix_color_g(src) * sa * 255u +
                        pix_color_g(dst) * da * ia + half) / denom);
  uint8_t b = (uint8_t)((pix_color_b(src) * sa * 255u +
                        pix_color_b(dst) * da * ia + half) / denom);
  return PIX_COLOR_RGBA(r, g, b, (uint8_t)out_a);
}

pix_poll()

bool pix_poll

(

void

)

Service whichever allocated display needs updating.

Returns

true if a display is found and polled.

Call this from the application's own main loop. It picks the next display which needs updated, polls it, and - if its backend reports it's due a redraw and a draw callback is registered (see pix_display_set_callback()) - locks it, runs the callback, and unlocks it again.