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;
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.
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_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
<TODO: Explain dynamic rects>
rect r_dynamic_rect(const r_dynamic_rect_data* y, rect r);
<TODO: Explain dynamic rect evaluation>
Concepts: dynamic_rect, binding
r_drawable r_drawable_eval(r_context* c, const r_drawable* d);
<TODO: Explain drawable evaluation>
Concepts: dynamic_rect, drawable
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* 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* 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* 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
<TODO: Explain callbacks>
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
void r_callback_set_data(r_ui_list* l, r_callback* c, const void* data, int data_length);
<TODO: Explain callback data storage>
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.
bool r_copy_last_frame_data(r_ui_list* l, r_callback* c);
<TODO: Explain persistent callback data>
Concepts: callback, rebuild, storage
<TODO: Explain menus>
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>
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_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_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
<TODO: Explain storage>
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.
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.
<TODO: Explain context>
typedef struct r_context r_context;
<TODO: Explain context ownership, usage>
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
void r_free_context(r_context* r);
Frees all UI lists and memory owned by the context.
See also: r_init_context
Concepts: context
void r_advance_time(r_context* r, float dt);
<TODO: Explain per-frame time update>
bool r_context_sweep(r_context* c);
<TODO: Explain ephemeral sweep, return>
Concepts: context, ephemeral, rebuild
<TODO: Explain frontends>
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>
<TODO: Explain damage>
void r_damage_id(r_context* c, uint64_t id);
<TODO: Explain damage tracking>
Concepts: damage
void r_damage_clear(r_context* c);
<TODO: Explain when to call>
Concepts: damage
#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
#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
<TODO: Explain input>
bool r_dispatch(r_interact* target, r_event_type event_type, r_event* event);
<TODO: Explain event dispatch, return>
Concepts: input, interactable
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 | |
|---|---|
keycode | Keys 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. |
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_button | R_MOUSE_LEFT, R_MOUSE_MIDDLE or R_MOUSE_RIGHT (same numbering as SDL). |
#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:
RCUT_MOUSE_DRAG_DISTANCE_DEFAULT: Pixels the mouse must move while pressed before a drag starts.RCUT_MOUSE_PRESSED_INITIAL_REPEAT: Seconds a mouse button must be held before R_MOUSE_PRESSED starts repeating.RCUT_MOUSE_PRESSED_REPEAT: Seconds between repeated R_MOUSE_PRESSED events.RCUT_MOUSE_HOVER_INITIAL_DELAY: Seconds the mouse must rest on an element before the first R_MOUSE_HOVER event.RCUT_MOUSE_HOVER_REPEAT: Seconds between repeated R_MOUSE_HOVER events.RCUT_MOUSE_MULTI_CLICK_TIME: Maximum seconds between clicks on the same element to count as a double or triple click.See also: r_event_type, r_advance_time
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
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
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
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
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
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>
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>
#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
#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