ui_cats.h File Reference

Cat drawings on the screens: the poses, the spots a screen offers them, the random pick of one and the source of the random number. More...

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

Go to the source code of this file.

Data Structures
struct	ui_cat_pose_t
	One pose: its drawing and the spots it may take. More...
struct	ui_cat_spot_t
	A free place on one screen, where a cat stands on a line. More...
struct	ui_cat_pick_t
	A pick: a pose and the index of its spot in the screen's list, or both UI_CAT_NONE. More...

Macros
#define	UI_CAT_IN(spot)
	The bit of spot spot in a pose's mask.
#define	UI_CAT_GAP   4
	The clear margin around a cat, px: nothing drawn or pressed lies closer.
#define	UI_CAT_RANDOM   (-1)
	ui_cats_force(): pick at random (the default).
#define	UI_CAT_NONE   (-2)
	ui_cats_force(): no cat; ui_cats_pick(): none picked.
#define	UI_CAT_PICK_NONE   ((ui_cat_pick_t){ UI_CAT_NONE, UI_CAT_NONE })
	No cat.

Typedefs
typedef bool(*)	ui_cat_clear_fn(gfx_rect_t r)
	Whether a screen has nothing within UI_CAT_GAP of a box.
typedef uint32_t(*)	ui_cats_random_fn(void)
	The source of random numbers.

Enumerations
enum	ui_cat_side_t { UI_CAT_FROM_LEFT = 0 , UI_CAT_FROM_RIGHT }
	Which corner of the cat a spot's point holds. More...

Functions
gfx_rect_t	ui_cat_rect (int pose, const ui_cat_spot_t *spot)
	The box pose pose covers in spot.
ui_cat_pick_t	ui_cats_pick (const ui_cat_spot_t *spots, int n, ui_cat_clear_fn clear, uint32_t roll)
	Pick a pose among the ones with a clear spot, and that spot.
gfx_rect_t	ui_cats_draw (gfx_canvas_t *c, ui_cat_pick_t pick, const ui_cat_spot_t *spots, int n)
	Draw a pick.
void	ui_cats_set_random (ui_cats_random_fn fn)
	Name the source ui_cats_roll() reads.
void	ui_cats_seed (uint32_t seed)
	Seed the built-in xorshift.
uint32_t	ui_cats_roll (void)
	The next random number from the source.
void	ui_cats_force (int pose)
	Put one pose, or none, in place of the random pick.
int	ui_cats_forced (void)
	The pose ui_cats_force() set.

Variables
const ui_cat_pose_t	ui_cat_poses [UI_CAT_POSES]
	Every pose; ui_cats_art.c, generated by tools/gen_cats.py.

Detailed Description

Cat drawings on the screens: the poses, the spots a screen offers them, the random pick of one and the source of the random number.

A cat is decoration. It takes no touch, and a screen places one only where nothing it draws or takes a press on lies within UI_CAT_GAP of it. The poses are tools/gen_cats.py's table (ui_cats_art.c, generated); each names the spots it may take. A screen lists its spots, says what is clear, and draws the pose ui_cats_pick() returns with its static parts, so a frame that repaints nothing pays nothing for it.

The random number comes from ui_cats_roll(): the source ui_cats_set_random() names, esp_random() on the panel, or else a 32-bit xorshift that ui_cats_seed() sets, so the host suite and the screenshots are repeatable. ui_cats_force() puts one pose, or none, in place of the random pick.

One drawing task: the source and the forced pose are plain globals, set at start-up and read by the task that renders.

SPDX-License-Identifier: MIT

Macro Definition Documentation

UI_CAT_IN

#define UI_CAT_IN

(

spot

)

Value:

(1u << (unsigned)(spot))

The bit of spot spot in a pose's mask.

Typedef Documentation

ui_cat_clear_fn

typedef bool(*) ui_cat_clear_fn(gfx_rect_t r)

Whether a screen has nothing within UI_CAT_GAP of a box.

Parameters

r	the box a cat would cover, in the screen's coordinates

Returns

true when the cat may go there

ui_cats_random_fn

typedef uint32_t(*) ui_cats_random_fn(void)

The source of random numbers.

Returns

a 32-bit random number

Enumeration Type Documentation

ui_cat_side_t

enum ui_cat_side_t

Which corner of the cat a spot's point holds.

Enumerator
UI_CAT_FROM_LEFT	bottom-left: x is the cat's left edge
UI_CAT_FROM_RIGHT	bottom-right: x is one past its right edge

Function Documentation

ui_cat_rect()

gfx_rect_t ui_cat_rect	(	int	pose,
		const ui_cat_spot_t *	spot )

The box pose pose covers in spot.

Parameters

pose	index into ui_cat_poses[]
spot	the spot

Returns

the box; empty for a pose out of range or a NULL spot

ui_cats_draw()

gfx_rect_t ui_cats_draw	(	gfx_canvas_t *	c,
		ui_cat_pick_t	pick,
		const ui_cat_spot_t *	spots,
		int	n )

Draw a pick.

Parameters

c	the canvas
pick	the pick
spots	the list its spot indexes
n	how many

Returns

the box drawn, empty for none

ui_cats_force()

void ui_cats_force

(

int

pose

)

Put one pose, or none, in place of the random pick.

Parameters

pose	index into ui_cat_poses[], UI_CAT_RANDOM or UI_CAT_NONE; anything else is UI_CAT_NONE

ui_cats_forced()

int ui_cats_forced

(

void

)

The pose ui_cats_force() set.

Returns

the pose, UI_CAT_RANDOM or UI_CAT_NONE

ui_cats_pick()

ui_cat_pick_t ui_cats_pick	(	const ui_cat_spot_t *	spots,
		int	n,
		ui_cat_clear_fn	clear,
		uint32_t	roll )

Pick a pose among the ones with a clear spot, and that spot.

A pose counts when one of the n spots is one it may take and clear says its box there is clear. roll picks among them, and among the clear spots of the pose picked: pose roll mod P, spot (roll / P) mod S. A forced pose (ui_cats_force()) is the only one looked at; UI_CAT_NONE forced picks none.

Parameters

spots	the screen's spots
n	how many, at most 32
clear	the screen's test of a box
roll	the random number

Returns

the pick, or UI_CAT_PICK_NONE when no pose fits

ui_cats_roll()

uint32_t ui_cats_roll

(

void

)

The next random number from the source.

Returns

the number

ui_cats_seed()

void ui_cats_seed

(

uint32_t

seed

)

Seed the built-in xorshift.

Parameters

seed	the seed; 0 is taken as 1, which xorshift needs nonzero

ui_cats_set_random()

void ui_cats_set_random

(

ui_cats_random_fn

fn

)

Name the source ui_cats_roll() reads.

Parameters

fn	the source, esp_random() on the panel; NULL for the built-in xorshift