gfx_damage.h File Reference

Damage: the part of one frame buffer the rasteriser wrote since the last reset, kept as 16-row bands with one x-span each. More...

#include <stdbool.h>
#include <stdint.h>
#include "gfx.h"

Go to the source code of this file.

Data Structures
struct	gfx_damage_t
	What one buffer has had written since gfx_damage_reset(). More...

Macros
#define	GFX_DAMAGE_BAND_SHIFT   4
	A band is 1 << GFX_DAMAGE_BAND_SHIFT rows, 16.
#define	GFX_DAMAGE_BAND_H   (1 << GFX_DAMAGE_BAND_SHIFT)
	The rows of one band, 16.
#define	GFX_DAMAGE_MAX_BANDS   64
	The bands a record holds, 64: 1,024 rows.
#define	GFX_DAMAGE_MAX_RECTS   8
	The most rectangles gfx_damage_rects() returns, 8.

Functions
void	gfx_damage_init (gfx_damage_t *d, const gfx_canvas_t *root)
	Bind d to the buffer under root, empty.
void	gfx_damage_reset (gfx_damage_t *d)
	Forget what d holds: nothing written.
void	gfx_damage_all (gfx_damage_t *d)
	Count the whole buffer as written.
void	gfx_damage_mark (gfx_damage_t *d, const gfx_canvas_t *c, int x, int y, int w, int h)
	Count a rectangle written through c as written.
bool	gfx_damage_empty (const gfx_damage_t *d)
	Whether d holds no write.
int	gfx_damage_rects (const gfx_damage_t *d, gfx_rect_t *out, int max)
	The written area as at most max rectangles, top to bottom.
gfx_rect_t	gfx_damage_turn (gfx_rect_t r, int width, int height)
	Where r lies in a width x height buffer turned by 180°.
void	gfx_damage_attach (gfx_damage_t *d)
	Report the primitives' writes to d, or to nothing.

Variables
gfx_damage_t *	gfx_damage_sink
	The record the primitives report to, or NULL; gfx_damage.c.

Detailed Description

Damage: the part of one frame buffer the rasteriser wrote since the last reset, kept as 16-row bands with one x-span each.

The four places that write pixels (gfx_fill_rect(), gfx_pixel() and the glyph loop through gfx_pixel_inl(), gfx_blit() and gfx_blit_key()) report the clipped rectangle they wrote to the attached record (gfx_damage_attach()). A write through a canvas whose pixels lie outside the record's buffer, an off-screen band for instance, is not counted. With no record attached a write costs one load and one branch.

Screen rotation 180° reads the record to copy only what changed from the picture the UI draws to the frame buffer the panel scans, turned (gfx_turn.h). The record holds at most GFX_DAMAGE_MAX_BANDS bands, 1,024 rows; a taller buffer counts as wholly written on every write.

One drawing task: the attached record is one global pointer, written and read by the task that renders.

SPDX-License-Identifier: MIT

Function Documentation

gfx_damage_all()

void gfx_damage_all

(

gfx_damage_t *

d

)

Count the whole buffer as written.

Parameters

d	the record

gfx_damage_attach()

void gfx_damage_attach

(

gfx_damage_t *

d

)

Report the primitives' writes to d, or to nothing.

Parameters

d	the record, or NULL to stop counting

gfx_damage_empty()

bool gfx_damage_empty

(

const gfx_damage_t *

d

)

Whether d holds no write.

Parameters

d	the record

Returns

true when nothing was written since the last reset

gfx_damage_init()

void gfx_damage_init	(	gfx_damage_t *	d,
		const gfx_canvas_t *	root )

Bind d to the buffer under root, empty.

Parameters

d	the record
root	a canvas whose pixels are the buffer's first pixel and whose width, height and stride are the buffer's

gfx_damage_mark()

void gfx_damage_mark	(	gfx_damage_t *	d,
		const gfx_canvas_t *	c,
		int	x,
		int	y,
		int	w,
		int	h )

Count a rectangle written through c as written.

Nothing when c's pixels lie outside d's buffer. A canvas inside it with another stride counts the whole buffer.

Parameters

d	the record
c	the canvas written through
x	the rectangle's left edge, in c's coordinates
y	its top edge
w	its width, already clipped to c
h	its height, already clipped

gfx_damage_rects()

int gfx_damage_rects	(	const gfx_damage_t *	d,
		gfx_rect_t *	out,
		int	max )

The written area as at most max rectangles, top to bottom.

Each band's span is one rectangle; neighbouring bands then merge, the pair that adds the fewest unwritten pixels first, while a merge adds none or more than max are left. Every written pixel lies in one of the rectangles; a rectangle may hold unwritten pixels.

Parameters

d	the record
out	the rectangles, in buffer coordinates
max	room in out, 1 or more

Returns

the rectangles written to out, 0 when nothing was written

gfx_damage_reset()

void gfx_damage_reset

(

gfx_damage_t *

d

)

Forget what d holds: nothing written.

Parameters

d	the record

gfx_damage_turn()

gfx_rect_t gfx_damage_turn	(	gfx_rect_t	r,
		int	width,
		int	height )

Where r lies in a width x height buffer turned by 180°.

Parameters

r	a rectangle inside the buffer
width	the buffer's width, pixels
height	its height, rows

Returns

the turned rectangle, of the same size