core_extended

Image buffers

r_image_buffer

typedef struct r_image_buffer
{
	uint32_t* pixels; // Premultiplied ARGB
	int w, h;
	int stride; // stride in pixels
	uint8_t upload; // Either R_IMAGE_UPLOAD_ONCE or R_IMAGE_UPLOAD_ALWAYS.
	uint8_t mode;   // r_image_mode
	// Note that the software renderer references the pixel data without copying.

	uint64_t handle; // Internal handle assigned by the render backend. Usually a cache handle.
} r_image_buffer;

r_image_upload

typedef enum r_image_upload
{
	R_IMAGE_UPLOAD_ONCE, // Upload to the cache once, then set to R_IMAGE_UPLOAD_FINISHED.
	R_IMAGE_UPLOAD_ALWAYS, // Upload to the cache every frame, also causes it to be redrawn every frame.
	R_IMAGE_UPLOAD_FINISHED,
} r_image_upload;

R_IMAGE_UPLOAD_ONCE is uploaded on first draw and then set to R_IMAGE_UPLOAD_FINISHED, for static image data or image data that changes rarely. R_IMAGE_UPLOAD_ALWAYS is uploaded and redrawn every frame, for dynamic content.

r_image_mode

typedef enum r_image_mode
{
	R_IMAGE_STRETCHED,
	R_IMAGE_COVER,    // Preserves aspect ratio, cropped and centered.
	R_IMAGE_CENTERED, // Native size, cropped if larger.
	R_IMAGE_REPEATED, // Tiled at native size from the top left.
} r_image_mode;

How the image is fitted into the target rect.

r_image

r_drawable* r_image(r_ui_list* l, rect r, r_image_buffer* img);

Draws img in r according to r_image_buffer.mode.

static uint32_t px[16 * 16];
static r_image_buffer img[4];
for(int i = 0; i < 16 * 16; i++)
	px[i] = ((i % 16) / 4 + (i / 16) / 4) % 2 ? 0xFF3070C0 : 0xFFE0E0E0;
rect row = r_shrink(ui->root_area, 8);
for(int m = 0; m < 4; m++)
{
	img[m] = (r_image_buffer){ .pixels = px, .w = 16, .h = 16, .stride = 16, .upload = R_IMAGE_UPLOAD_ONCE, .mode = m };
	r_image(ui, r_cut_px(R_LEFT, &row, 64, R_SALT00 + m), &img[m]);
	r_cut_px(R_LEFT, &row, 8, R_SALT04 + m);
}

A 16x16 checker drawn in each mode.

See also: r_image_buffer, r_image_invalidate

Concepts: image, drawable

Dynamic rects

<TODO: Explain dynamic rects>

r_dynamic_rect

rect r_dynamic_rect(const r_dynamic_rect_data* y, rect r);

<TODO: Explain dynamic rect evaluation>

Concepts: dynamic_rect, binding

r_drawable_eval

r_drawable r_drawable_eval(r_context* c, const r_drawable* d);

<TODO: Explain drawable evaluation>

Concepts: dynamic_rect, drawable

r_drawable_thumb

r_drawable* r_drawable_thumb(r_ui_list* l, r_drawable* d, r_data_binding binding, float min, float max, rect area, r_alignment from);

<TODO: Describe bound thumb drawables>

Concepts: dynamic_rect, drawable, binding

r_drawable_fill

r_drawable* r_drawable_fill(r_ui_list* l, r_drawable* d, r_data_binding binding, float min, float max, rect area, r_alignment from);

<TODO: Describe bound fill drawables>

Concepts: dynamic_rect, drawable, binding

r_drawable_toggled

r_drawable* r_drawable_toggled(r_ui_list* l, r_drawable* d, r_data_binding binding, int64_t value, bool set_value, int state, int icon);

<TODO: Describe bound toggle drawables>

Concepts: dynamic_rect, drawable, binding

r_drawable_custom

r_drawable* r_drawable_custom(r_ui_list* l, r_drawable* d, r_data_binding binding, void (*update)(r_context* c, r_drawable* d), void* data);

<TODO: Describe custom update drawables>

Concepts: dynamic_rect, drawable

Callbacks

<TODO: Explain callbacks>

r_attach_callback

r_callback* r_attach_callback(r_ui_list* l, rect r, r_event_type event, r_callback_fn* function);
r_callback* r_attach_callback_to(r_ui_list* l, r_interact* it, r_event_type event, r_callback_fn* function);

<TODO: Explain callback attachment>

Concepts: callback, interactable

r_callback_set_data

void r_callback_set_data(r_ui_list* l, r_callback* c, const void* data, int data_length);

<TODO: Explain callback data storage>

Concepts: callback, storage

r_callback_share_data

void r_callback_share_data(r_ui_list* l, r_callback* dst, r_callback* src);

<TODO: Rewrite, explain data sharing>

Don't share data from last frames callback. Use r_copy_last_frame_data instead.

Concepts: callback, storage

r_copy_last_frame_data

bool r_copy_last_frame_data(r_ui_list* l, r_callback* c);

<TODO: Explain persistent callback data>

Concepts: callback, rebuild, storage

Menus

<TODO: Explain menus>

r_menu_item

typedef struct r_menu_item
{
	char* label;
	int   icon;
	char* shortcut;
	void (*on_click)(void);
	const struct r_menu_item* submenu;
	bool* checked;
	bool  disabled;
} r_menu_item;

<TODO: Describe item fields, submenus>

r_menubar

void r_menubar(r_ui_list* l, rect r, const r_menu_item* menus);

<TODO: Explain menu array termination>

static const r_menu_item file_menu[] = {
	{ .label = "New",  .icon = R_ICON_FILE, .shortcut = "Ctrl+N", .on_click = on_ok },
	{ .label = "Quit", .icon = R_ICON_CLOSE, .on_click = on_close },
	{ 0 },
};
static const r_menu_item menus[] = {
	{ .label = "File", .submenu = file_menu },
	{ .label = "Edit", .submenu = file_menu },
	{ .label = "Help", .submenu = file_menu },
	{ 0 },
};
rect area = ui->root_area;
r_menubar(ui, r_cut_px(R_TOP, &area, 30, R_SALT00), menus);

Concepts: menu, callback, ephemeral

r_menu_popup

r_ui_list* r_menu_popup(r_ui_list* parent, rect anchor, const r_menu_item* items, r_alignment side);

<TODO: Describe popup menu placement>

Concepts: menu, callback, ephemeral

r_on_context

r_callback* r_on_context(r_ui_list* l, rect r, const char* label, void (*on_select)(void));

<TODO: Explain context menu entries>

Concepts: menu, callback, ephemeral

Storage

<TODO: Explain storage>

r_storage_alloc

void* r_storage_alloc(r_ui_list* l, int size);

<TODO: Explain storage lifetime>

Returns a pointer to a block of memory with lifetime scoped to this rebuild.

Concepts: storage, rebuild

r_store

void* r_store(r_ui_list* l, const void* data, int size);
char* r_store_string(r_ui_list* l, const char* s);

<TODO: Explain storage lifetime>

r_storage_alloc + copy, zeroed if data is NULL.

Concepts: storage, rebuild

Context

<TODO: Explain context>

r_context

typedef struct r_context r_context;

<TODO: Explain context ownership, usage>

r_init_context

void r_init_context(r_context* r);

Initializes the context and reserves memory for its UI lists.

See also: r_free_context, r_context, r_create_ui_list

Concepts: context

r_free_context

void r_free_context(r_context* r);

Frees all UI lists and memory owned by the context.

See also: r_init_context

Concepts: context

r_advance_time

void r_advance_time(r_context* r, float dt);

<TODO: Explain per-frame time update>

Concepts: context, input

r_context_sweep

bool r_context_sweep(r_context* c);

<TODO: Explain ephemeral sweep, return>

Concepts: context, ephemeral, rebuild

Frontends

<TODO: Explain frontends>

r_interface

typedef struct r_interface
{
	rect     (*calc_outer_rect)    (r_context* c, int style, rect* inner);
	rect     (*calc_inner_rect)    (r_context* c, int style, rect outer);
	uint64_t (*get_viewport_target)(r_ui_list* parent, rect relative_to);
	rect     (*measure_text)       (r_context* c, int style, const char* text, int len);
	rect     (*measure_icon)       (r_context* c, int style, int icon, int* gap);
	int      (*break_text)         (r_context* c, int style, const char* text, int len, int width, bool force, int* w);
	void     (*get_layout)         (r_context* c, int style, int* size, int* spacing);
	void     (*set_clipboard)      (r_context* c, const char* text);
	char*    (*get_clipboard)      (r_context* c);
} r_interface;

<TODO: Describe frontend callbacks>

Damage

<TODO: Explain damage>

r_damage_id

void r_damage_id(r_context* c, uint64_t id);

<TODO: Explain damage tracking>

Concepts: damage

r_damage_clear

void r_damage_clear(r_context* c);

<TODO: Explain when to call>

Concepts: damage

RCUT_CONTEXT_MAX_LISTS

#define RCUT_CONTEXT_MAX_LISTS 128
#define RCUT_CONTEXT_MAX_LISTS 256

Maximum number of regular UI lists per context.

See also: RCUT_CONTEXT_MAX_EPHEMERAL_LISTS, r_create_ui_list

RCUT_CONTEXT_MAX_EPHEMERAL_LISTS

#define RCUT_CONTEXT_MAX_EPHEMERAL_LISTS 128
#define RCUT_CONTEXT_MAX_EPHEMERAL_LISTS 256

Maximum number of ephemeral UI lists (popups, viewports, tooltips) per context.

See also: RCUT_CONTEXT_MAX_LISTS, r_popup, r_viewport

Input

<TODO: Explain input>

r_dispatch

bool r_dispatch(r_interact* target, r_event_type event_type, r_event* event);

<TODO: Explain event dispatch, return>

Concepts: input, interactable

r_post_key_input

uint64_t r_post_key_input(r_context* r, uint64_t target, int32_t keycode, int32_t scancode, uint32_t modifier_flags);

<TODO: Describe return value, modifiers>

Parameter
keycodeKeys that are special cased by rcut use Windows virtual key codes (R_KEY_*), frontends need to map their keys to these. Letters are expected as uppercase ASCII ('A'-'Z'), digits as ASCII.

Concepts: input, frontend

r_post_mouse_down

uint64_t r_post_mouse_down(r_context* r, uint64_t target, int mouse_button, float x, float y);

<TODO: Describe coordinates, return value>

Parameter
mouse_buttonR_MOUSE_LEFT, R_MOUSE_MIDDLE or R_MOUSE_RIGHT (same numbering as SDL).

Concepts: input, frontend

RCUT_MOUSE_*

#define RCUT_MOUSE_DRAG_DISTANCE_DEFAULT 4
#define RCUT_MOUSE_PRESSED_INITIAL_REPEAT 0.5
#define RCUT_MOUSE_PRESSED_REPEAT 0.2
#define RCUT_MOUSE_HOVER_INITIAL_DELAY 0.4
#define RCUT_MOUSE_HOVER_REPEAT  0.2
#define RCUT_MOUSE_MULTI_CLICK_TIME 0.4

Mouse timings in seconds and the drag threshold in pixels:

See also: r_event_type, r_advance_time

r_post_mouse_move

uint64_t r_post_mouse_move(r_context* r, uint64_t target, float x, float y);

Sends a mouse move in target space to the context and returns the ID of the element that handled it, or 0.

See also: r_post_mouse_down, r_post_mouse_up, r_post_mouse_wheel

Concepts: input, frontend

r_post_mouse_up

uint64_t r_post_mouse_up(r_context* r, uint64_t target, int mouse_button, float x, float y);

Sends a mouse button release in target space to the context and returns the ID of the element that handled it, or 0.

See also: r_post_mouse_down, r_post_mouse_move

Concepts: input, frontend

r_post_mouse_wheel

uint64_t r_post_mouse_wheel(r_context* r, uint64_t target, float x, float y, float scroll_x, float scroll_y);

Sends a scroll event to the elements under the mouse, topmost first, and returns the ID of the one that handled it, or 0.

See also: r_post_mouse_move, r_scroll_begin

Concepts: input, frontend

r_post_text

uint64_t r_post_text(r_context* r, uint64_t target, const char* str);
uint64_t r_post_text_edit(r_context* r, uint64_t target, const char* str, int start, int length);

Sends committed text to the focused element, r_post_text_edit sends IME composition text, both return the ID of the element that handled it, or 0.

See also: r_post_key_input, r_focus_wants_text

Concepts: input, frontend

r_modifier_flags

typedef enum r_modifier_flags
{
	R_MOD_CTRL  = (1 << 0),
	R_MOD_ALT   = (1 << 1),
	R_MOD_SHIFT = (1 << 2),
	R_MOD_WIN   = (1 << 3)
} r_modifier_flags;

Modifier key flags for r_post_key_input.

See also: r_post_key_input

r_event_type

typedef enum r_event_type
{
	R_ACTIVATION,  // Sent on mouse_click or via a Enter keypress if focused.
	// Also sent when Alt was pressed to enter menu accelerator mode and then the interactables accelerator key was pressed.
	R_CONTEXT,     // Triggered when it's label is selected in the context menu, or when it's hotkey is pressed while this element is focused.

	R_TEXT_INPUT,  // Only sent if in focus and if has_text is true.
	R_TEXT_EDIT,   // IME input: show a transient text fragment with selection.
	R_KEY_INPUT,   // Only sent if in focus. Tabs and arrow key events will only be sent if not in navigation mode and traps_tab_focus/traps_arrow_focus is true.
	R_MOUSE_IN,
	R_MOUSE_HOVER, // For popups primarily. Mouse hover is sent after MOUSE_HOVER_INITIAL_DELAY (Default: 0.4) seconds after the R_MOUSE_IN event, then repeated every MOUSE_HOVER_REPEAT_DELAY (Default: 0.2) seconds.
	R_MOUSE_OUT,
	R_MOUSE_CLICK,      // Mouse click is sent on mouse release and is never repeated.
	R_MOUSE_PRESSED,    // Mouse pressed is sent once during the initial mouse_down, then after MOUSE_PRESSED_INITIAL_REPEAT seconds then repeated every MOUSE_PRESSED_REPEAT seconds.
	R_MOUSE_DRAG_START, // Drags are stateful: Whichever interactable got the drag_start_ event will also get the drag_ and drag_release_ events, regardless of mouse position. 
	R_MOUSE_DRAG_MOVE,  // Drag start/drag release events will always be accompanied by drag move events.
	R_MOUSE_DRAG_RELEASE,
	R_MOUSE_SCROLL,
	R_FOCUS_ENTER,
	R_FOCUS_EXIT,
} r_event_type;

<TODO: Describe event order>

r_event

typedef struct r_event
{
	r_ui_list* ui_list;
	r_context* context;
	int mouse_button;
	int mouse_state;
	int click_count;
	// The three coordinate spaces:
	// Target space: The mouse position relative to the render-target/window.
	float target_mouse_x, target_mouse_y;
	// List space: After applying the transformation matrix of the UI list.
	float list_mouse_x, list_mouse_y;
	// Rectangle space: List space coordinates relative to rectangle X/Y.
	float rect_mouse_x, rect_mouse_y;
	// Drag coordinates are in List space.
	float drag_start_x, drag_start_y;
	float drag_delta_x, drag_delta_y;
	float scroll_x, scroll_y;
	// Keyboard
	int keycode;
	int scancode;
	int modifier_state;
	// Text input
	char* text; // UTF-8 fragment. R_TEXT_INPUT needs to append it, R_TEXT_EDIT needs to display it without committing.
	int ime_highlight_start; // For R_TEXT_EDIT: Which part of text needs to be highlighted.
	int ime_highlight_length;
} r_event;

<TODO: Describe event fields>

R_MOUSE_*

#define R_MOUSE_LEFT   1
#define R_MOUSE_MIDDLE 2
#define R_MOUSE_RIGHT  3

Mouse buttons, numbered the same as in SDL.

See also: r_post_mouse_down, r_post_mouse_up

R_KEY_*

#define R_KEY_BACKSPACE 8
#define R_KEY_TAB       9
#define R_KEY_ENTER     13
#define R_KEY_ALT       18
#define R_KEY_ESCAPE    27
#define R_KEY_SPACE     32
#define R_KEY_PAGEUP    33
#define R_KEY_PAGEDOWN  34
#define R_KEY_END       35
#define R_KEY_HOME      36
#define R_KEY_LEFT      37
#define R_KEY_UP        38
#define R_KEY_RIGHT     39
#define R_KEY_DOWN      40
#define R_KEY_DELETE    46

Key codes of the keys rcut handles specially, they are Windows virtual key codes that frontends need to map their keys to; letters are expected as uppercase ASCII ('A'-'Z') and digits as ASCII.

See also: r_post_key_input