The best way to control Claude Code, Codex and more from any computer or phone

main
h 795 lines 28.8 KB
Raw
1 /**
2 * @file render.h
3 *
4 * Render state for creating high performance renderers.
5 */
6
7 #ifndef GHOSTTY_VT_RENDER_H
8 #define GHOSTTY_VT_RENDER_H
9
10 #include <stdbool.h>
11 #include <stddef.h>
12 #include <stdint.h>
13 #include <ghostty/vt/allocator.h>
14 #include <ghostty/vt/color.h>
15 #include <ghostty/vt/terminal.h>
16 #include <ghostty/vt/types.h>
17
18 #ifdef __cplusplus
19 extern "C" {
20 #endif
21
22 /** @defgroup render Render State
23 *
24 * Represents the state required to render a visible screen (a viewport)
25 * of a terminal instance. This is stateful and optimized for repeated
26 * updates from a single terminal instance and only updating dirty regions
27 * of the screen.
28 *
29 * The key design principle of this API is that it only needs read/write
30 * access to the terminal instance during the update call. This allows
31 * the render state to minimally impact terminal IO performance and also
32 * allows the renderer to be safely multi-threaded (as long as a lock is
33 * held during the update call to ensure exclusive access to the terminal
34 * instance).
35 *
36 * The basic usage of this API is:
37 *
38 * 1. Create an empty render state
39 * 2. Update it from a terminal instance whenever you need.
40 * 3. Read from the render state to get the data needed to draw your frame.
41 *
42 * ## Two-Phase Updates
43 *
44 * For callers that synchronize terminal access (e.g. a renderer thread
45 * sharing a lock with an IO thread), the update can be split into two
46 * phases to minimize the time the terminal must be held exclusively:
47 * ghostty_render_state_begin_update requires terminal access, while
48 * ghostty_render_state_end_update completes any deferred work using only
49 * memory owned by the render state. A typical renderer would lock, begin
50 * the update, unlock, and then end the update while the IO thread is free
51 * to continue modifying the terminal. ghostty_render_state_update is a
52 * convenience that performs both phases in one call.
53 *
54 * ## Dirty Tracking
55 *
56 * Dirty tracking is a key feature of the render state that allows renderers
57 * to efficiently determine what parts of the screen have changed and only
58 * redraw changed regions.
59 *
60 * The render state API keeps track of dirty state at two independent layers:
61 * a global dirty state that indicates whether the entire frame is clean,
62 * partially dirty, or fully dirty, and a per-row dirty state that allows
63 * tracking which rows in a partially dirty frame have changed.
64 *
65 * The user of the render state API is expected to unset both of these.
66 * The `update` call does not unset dirty state, it only updates it.
67 *
68 * An extremely important detail: setting one dirty state doesn't unset
69 * the other. For example, setting the global dirty state to false does not
70 * reset the row-level dirty flags. So, the caller of the render state API must
71 * be careful to manage both layers of dirty state correctly.
72 *
73 * ## Examples
74 *
75 * ### Creating and updating render state
76 * @snippet c-vt-render/src/main.c render-state-update
77 *
78 * ### Checking dirty state
79 * @snippet c-vt-render/src/main.c render-dirty-check
80 *
81 * ### Reading colors
82 * @snippet c-vt-render/src/main.c render-colors
83 *
84 * ### Reading cursor state
85 * @snippet c-vt-render/src/main.c render-cursor
86 *
87 * ### Iterating rows and cells
88 * @snippet c-vt-render/src/main.c render-row-iterate
89 *
90 * ### Resetting dirty state after rendering
91 * @snippet c-vt-render/src/main.c render-dirty-reset
92 *
93 * @{
94 */
95
96 /**
97 * Dirty state of a render state after update.
98 *
99 * @ingroup render
100 */
101 typedef enum GHOSTTY_ENUM_TYPED {
102 /** Not dirty at all; rendering can be skipped. */
103 GHOSTTY_RENDER_STATE_DIRTY_FALSE = 0,
104
105 /** Some rows changed; renderer can redraw incrementally. */
106 GHOSTTY_RENDER_STATE_DIRTY_PARTIAL = 1,
107
108 /** Global state changed; renderer should redraw everything. */
109 GHOSTTY_RENDER_STATE_DIRTY_FULL = 2,
110 GHOSTTY_RENDER_STATE_DIRTY_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
111 } GhosttyRenderStateDirty;
112
113 /**
114 * Visual style of the cursor.
115 *
116 * @ingroup render
117 */
118 typedef enum GHOSTTY_ENUM_TYPED {
119 /** Bar cursor (DECSCUSR 5, 6). */
120 GHOSTTY_RENDER_STATE_CURSOR_VISUAL_STYLE_BAR = 0,
121
122 /** Block cursor (DECSCUSR 1, 2). */
123 GHOSTTY_RENDER_STATE_CURSOR_VISUAL_STYLE_BLOCK = 1,
124
125 /** Underline cursor (DECSCUSR 3, 4). */
126 GHOSTTY_RENDER_STATE_CURSOR_VISUAL_STYLE_UNDERLINE = 2,
127
128 /** Hollow block cursor. */
129 GHOSTTY_RENDER_STATE_CURSOR_VISUAL_STYLE_BLOCK_HOLLOW = 3,
130 GHOSTTY_RENDER_STATE_CURSOR_VISUAL_STYLE_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
131 } GhosttyRenderStateCursorVisualStyle;
132
133 /**
134 * Queryable data kinds for ghostty_render_state_get().
135 *
136 * @ingroup render
137 */
138 typedef enum GHOSTTY_ENUM_TYPED {
139 /** Invalid / sentinel value. */
140 GHOSTTY_RENDER_STATE_DATA_INVALID = 0,
141
142 /** Viewport width in cells (uint16_t). */
143 GHOSTTY_RENDER_STATE_DATA_COLS = 1,
144
145 /** Viewport height in cells (uint16_t). */
146 GHOSTTY_RENDER_STATE_DATA_ROWS = 2,
147
148 /** Current dirty state (GhosttyRenderStateDirty). */
149 GHOSTTY_RENDER_STATE_DATA_DIRTY = 3,
150
151 /** Populate a pre-allocated GhosttyRenderStateRowIterator with row data
152 * from the render state (GhosttyRenderStateRowIterator). Row data is
153 * only valid as long as the underlying render state is not updated.
154 * It is unsafe to use row data after updating the render state.
155 * */
156 GHOSTTY_RENDER_STATE_DATA_ROW_ITERATOR = 4,
157
158 /** Default/current background color (GhosttyColorRgb). */
159 GHOSTTY_RENDER_STATE_DATA_COLOR_BACKGROUND = 5,
160
161 /** Default/current foreground color (GhosttyColorRgb). */
162 GHOSTTY_RENDER_STATE_DATA_COLOR_FOREGROUND = 6,
163
164 /** Cursor color when explicitly set by terminal state (GhosttyColorRgb).
165 * Returns GHOSTTY_INVALID_VALUE if no explicit cursor color is set;
166 * use COLOR_CURSOR_HAS_VALUE to check first. */
167 GHOSTTY_RENDER_STATE_DATA_COLOR_CURSOR = 7,
168
169 /** Whether an explicit cursor color is set (bool). */
170 GHOSTTY_RENDER_STATE_DATA_COLOR_CURSOR_HAS_VALUE = 8,
171
172 /** The active 256-color palette (GhosttyColorRgb[256]). */
173 GHOSTTY_RENDER_STATE_DATA_COLOR_PALETTE = 9,
174
175 /** The visual style of the cursor (GhosttyRenderStateCursorVisualStyle). */
176 GHOSTTY_RENDER_STATE_DATA_CURSOR_VISUAL_STYLE = 10,
177
178 /** Whether the cursor is visible based on terminal modes (bool). */
179 GHOSTTY_RENDER_STATE_DATA_CURSOR_VISIBLE = 11,
180
181 /** Whether the cursor should blink based on terminal modes (bool). */
182 GHOSTTY_RENDER_STATE_DATA_CURSOR_BLINKING = 12,
183
184 /** Whether the cursor is at a password input field (bool). */
185 GHOSTTY_RENDER_STATE_DATA_CURSOR_PASSWORD_INPUT = 13,
186
187 /** Whether the cursor is visible within the viewport (bool).
188 * If false, the cursor viewport position values are undefined. */
189 GHOSTTY_RENDER_STATE_DATA_CURSOR_VIEWPORT_HAS_VALUE = 14,
190
191 /** Cursor viewport x position in cells (uint16_t).
192 * Only valid when CURSOR_VIEWPORT_HAS_VALUE is true. */
193 GHOSTTY_RENDER_STATE_DATA_CURSOR_VIEWPORT_X = 15,
194
195 /** Cursor viewport y position in cells (uint16_t).
196 * Only valid when CURSOR_VIEWPORT_HAS_VALUE is true. */
197 GHOSTTY_RENDER_STATE_DATA_CURSOR_VIEWPORT_Y = 16,
198
199 /** Whether the cursor is on the tail of a wide character (bool).
200 * Only valid when CURSOR_VIEWPORT_HAS_VALUE is true. */
201 GHOSTTY_RENDER_STATE_DATA_CURSOR_VIEWPORT_WIDE_TAIL = 17,
202 GHOSTTY_RENDER_STATE_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
203 } GhosttyRenderStateData;
204
205 /**
206 * Settable options for ghostty_render_state_set().
207 *
208 * @ingroup render
209 */
210 typedef enum GHOSTTY_ENUM_TYPED {
211 /** Set dirty state (GhosttyRenderStateDirty). */
212 GHOSTTY_RENDER_STATE_OPTION_DIRTY = 0,
213 GHOSTTY_RENDER_STATE_OPTION_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
214 } GhosttyRenderStateOption;
215
216 /**
217 * Queryable data kinds for ghostty_render_state_row_get().
218 *
219 * @ingroup render
220 */
221 typedef enum GHOSTTY_ENUM_TYPED {
222 /** Invalid / sentinel value. */
223 GHOSTTY_RENDER_STATE_ROW_DATA_INVALID = 0,
224
225 /** Whether the current row is dirty (bool). */
226 GHOSTTY_RENDER_STATE_ROW_DATA_DIRTY = 1,
227
228 /** The raw row value (GhosttyRow). */
229 GHOSTTY_RENDER_STATE_ROW_DATA_RAW = 2,
230
231 /** Populate a pre-allocated GhosttyRenderStateRowCells with cell data for
232 * the current row (GhosttyRenderStateRowCells). Cell data is only
233 * valid as long as the underlying render state is not updated.
234 * It is unsafe to use cell data after updating the render state. */
235 GHOSTTY_RENDER_STATE_ROW_DATA_CELLS = 3,
236
237 /** Row-local selected cell range (GhosttyRenderStateRowSelection). */
238 GHOSTTY_RENDER_STATE_ROW_DATA_SELECTION = 4,
239 GHOSTTY_RENDER_STATE_ROW_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
240 } GhosttyRenderStateRowData;
241
242 /**
243 * Settable options for ghostty_render_state_row_set().
244 *
245 * @ingroup render
246 */
247 typedef enum GHOSTTY_ENUM_TYPED {
248 /** Set dirty state for the current row (bool). */
249 GHOSTTY_RENDER_STATE_ROW_OPTION_DIRTY = 0,
250 GHOSTTY_RENDER_STATE_ROW_OPTION_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
251 } GhosttyRenderStateRowOption;
252
253 /**
254 * Row-local selection range.
255 *
256 * This struct uses the sized-struct ABI pattern. Initialize with
257 * GHOSTTY_INIT_SIZED(GhosttyRenderStateRowSelection) before querying
258 * GHOSTTY_RENDER_STATE_ROW_DATA_SELECTION.
259 *
260 * Querying GHOSTTY_RENDER_STATE_ROW_DATA_SELECTION returns GHOSTTY_NO_VALUE
261 * if the current row does not intersect the current selection.
262 *
263 * @ingroup render
264 */
265 typedef struct {
266 /** Size of this struct in bytes. Must be set to sizeof(GhosttyRenderStateRowSelection). */
267 size_t size;
268
269 /** Start column of the row-local selection range, inclusive. */
270 uint16_t start_x;
271
272 /** End column of the row-local selection range, inclusive. */
273 uint16_t end_x;
274 } GhosttyRenderStateRowSelection;
275
276 /**
277 * Render-state color information.
278 *
279 * This struct uses the sized-struct ABI pattern. Initialize with
280 * GHOSTTY_INIT_SIZED(GhosttyRenderStateColors) before calling
281 * ghostty_render_state_colors_get().
282 *
283 * Example:
284 * @code
285 * GhosttyRenderStateColors colors = GHOSTTY_INIT_SIZED(GhosttyRenderStateColors);
286 * GhosttyResult result = ghostty_render_state_colors_get(state, &colors);
287 * @endcode
288 *
289 * @ingroup render
290 */
291 typedef struct {
292 /** Size of this struct in bytes. Must be set to sizeof(GhosttyRenderStateColors). */
293 size_t size;
294
295 /** The default/current background color for the render state. */
296 GhosttyColorRgb background;
297
298 /** The default/current foreground color for the render state. */
299 GhosttyColorRgb foreground;
300
301 /** The cursor color when explicitly set by terminal state. */
302 GhosttyColorRgb cursor;
303
304 /**
305 * True when cursor contains a valid explicit cursor color value.
306 * If this is false, the cursor color should be ignored; it will
307 * contain undefined data.
308 * */
309 bool cursor_has_value;
310
311 /** The active 256-color palette for this render state. */
312 GhosttyColorRgb palette[256];
313 } GhosttyRenderStateColors;
314
315 /**
316 * Create a new render state instance.
317 *
318 * @param allocator Pointer to allocator, or NULL to use the default allocator
319 * @param state Pointer to store the created render state handle
320 * @return GHOSTTY_SUCCESS on success, GHOSTTY_OUT_OF_MEMORY on allocation
321 * failure
322 *
323 * @ingroup render
324 */
325 GHOSTTY_API GhosttyResult ghostty_render_state_new(const GhosttyAllocator* allocator,
326 GhosttyRenderState* state);
327
328 /**
329 * Free a render state instance.
330 *
331 * Releases all resources associated with the render state. After this call,
332 * the render state handle becomes invalid.
333 *
334 * @param state The render state handle to free (may be NULL)
335 *
336 * @ingroup render
337 */
338 GHOSTTY_API void ghostty_render_state_free(GhosttyRenderState state);
339
340 /**
341 * Update a render state instance from a terminal.
342 *
343 * This consumes terminal/screen dirty state in the same way as the internal
344 * render state update path.
345 *
346 * This is a convenience function that performs a full update in one call,
347 * equivalent to ghostty_render_state_begin_update immediately followed by
348 * ghostty_render_state_end_update. Callers that hold a lock over the
349 * terminal state should prefer calling the two phases directly so that the
350 * lock is only held for the begin phase.
351 *
352 * @param state The render state handle (NULL returns GHOSTTY_INVALID_VALUE)
353 * @param terminal The terminal handle to read from (NULL returns GHOSTTY_INVALID_VALUE)
354 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if `state` or
355 * `terminal` is NULL, GHOSTTY_OUT_OF_MEMORY if updating the state requires
356 * allocation and that allocation fails
357 *
358 * @ingroup render
359 */
360 GHOSTTY_API GhosttyResult ghostty_render_state_update(GhosttyRenderState state,
361 GhosttyTerminal terminal);
362
363 /**
364 * Begin an update of a render state instance from a terminal.
365 *
366 * Every begin must be completed with a ghostty_render_state_end_update call
367 * before the render state is read.
368 *
369 * This two-phase structure exists for callers that synchronize access to the
370 * terminal state (e.g. with a lock shared with an IO thread): only this
371 * function requires terminal access, so a caller can hold its lock for this
372 * call only and then call ghostty_render_state_end_update after releasing
373 * it. The end phase exclusively reads and writes memory owned by the render
374 * state, so it is safe to call while the terminal is being modified.
375 *
376 * Work that doesn't require terminal access may be deferred to the end phase
377 * to keep this call (and therefore lock hold time) as short as possible.
378 * Callers must treat the render state as incomplete until
379 * ghostty_render_state_end_update is called.
380 *
381 * This consumes terminal/screen dirty state in the same way as the internal
382 * render state update path.
383 *
384 * @param state The render state handle (NULL returns GHOSTTY_INVALID_VALUE)
385 * @param terminal The terminal handle to read from (NULL returns GHOSTTY_INVALID_VALUE)
386 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if `state` or
387 * `terminal` is NULL, GHOSTTY_OUT_OF_MEMORY if updating the state requires
388 * allocation and that allocation fails
389 *
390 * @ingroup render
391 */
392 GHOSTTY_API GhosttyResult ghostty_render_state_begin_update(GhosttyRenderState state,
393 GhosttyTerminal terminal);
394
395 /**
396 * Complete a prior ghostty_render_state_begin_update call by performing any
397 * deferred work.
398 *
399 * This only reads and writes memory owned by the render state, so it is safe
400 * to call while the terminal is being modified (no terminal synchronization
401 * is required). Calling this without a prior begin is a safe no-op.
402 *
403 * @param state The render state handle (NULL returns GHOSTTY_INVALID_VALUE)
404 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if `state` is
405 * NULL
406 *
407 * @ingroup render
408 */
409 GHOSTTY_API GhosttyResult ghostty_render_state_end_update(GhosttyRenderState state);
410
411 /**
412 * Get a value from a render state.
413 *
414 * The `out` pointer must point to a value of the type corresponding to the
415 * requested data kind (see GhosttyRenderStateData).
416 *
417 * @param state The render state handle (NULL returns GHOSTTY_INVALID_VALUE)
418 * @param data The data kind to query
419 * @param[out] out Pointer to receive the queried value
420 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if `state` is
421 * NULL or `data` is not a recognized enum value
422 *
423 * @ingroup render
424 */
425 GHOSTTY_API GhosttyResult ghostty_render_state_get(GhosttyRenderState state,
426 GhosttyRenderStateData data,
427 void* out);
428
429 /**
430 * Get multiple data fields from a render state in a single call.
431 *
432 * Each element in the keys array specifies a data kind, and the
433 * corresponding element in the values array receives the result.
434 *
435 * Processing stops at the first error; on success out_written
436 * is set to count, on error it is set to the index of the
437 * failing key (i.e. the number of values successfully written).
438 *
439 * @param state The render state handle (NULL returns GHOSTTY_INVALID_VALUE)
440 * @param count Number of key/value pairs
441 * @param keys Array of data kinds to query
442 * @param values Array of output pointers (types must match each key's
443 * documented output type)
444 * @param[out] out_written On return, receives the number of values
445 * successfully written (may be NULL)
446 * @return GHOSTTY_SUCCESS if all queries succeed
447 *
448 * @ingroup render
449 */
450 GHOSTTY_API GhosttyResult ghostty_render_state_get_multi(
451 GhosttyRenderState state,
452 size_t count,
453 const GhosttyRenderStateData* keys,
454 void** values,
455 size_t* out_written);
456
457 /**
458 * Set an option on a render state.
459 *
460 * The `value` pointer must point to a value of the type corresponding to the
461 * requested option kind (see GhosttyRenderStateOption).
462 *
463 * @param state The render state handle (NULL returns GHOSTTY_INVALID_VALUE)
464 * @param option The option to set
465 * @param[in] value Pointer to the value to set (NULL returns
466 * GHOSTTY_INVALID_VALUE)
467 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if `state` or
468 * `value` is NULL
469 *
470 * @ingroup render
471 */
472 GHOSTTY_API GhosttyResult ghostty_render_state_set(GhosttyRenderState state,
473 GhosttyRenderStateOption option,
474 const void* value);
475
476 /**
477 * Get the current color information from a render state.
478 *
479 * This writes as many fields as fit in the caller-provided sized struct.
480 * `out_colors->size` must be set by the caller (typically via
481 * GHOSTTY_INIT_SIZED(GhosttyRenderStateColors)).
482 *
483 * @param state The render state handle (NULL returns GHOSTTY_INVALID_VALUE)
484 * @param[out] out_colors Sized output struct to receive render-state colors
485 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if `state` or
486 * `out_colors` is NULL, or if `out_colors->size` is smaller than
487 * `sizeof(size_t)`
488 *
489 * @ingroup render
490 */
491 GHOSTTY_API GhosttyResult ghostty_render_state_colors_get(GhosttyRenderState state,
492 GhosttyRenderStateColors* out_colors);
493
494 /**
495 * Create a new row iterator instance.
496 *
497 * All fields except the allocator are left undefined until populated
498 * via ghostty_render_state_get() with
499 * GHOSTTY_RENDER_STATE_DATA_ROW_ITERATOR.
500 *
501 * @param allocator Pointer to allocator, or NULL to use the default allocator
502 * @param[out] out_iterator On success, receives the created iterator handle
503 * @return GHOSTTY_SUCCESS on success, GHOSTTY_OUT_OF_MEMORY on allocation
504 * failure
505 *
506 * @ingroup render
507 */
508 GHOSTTY_API GhosttyResult ghostty_render_state_row_iterator_new(
509 const GhosttyAllocator* allocator,
510 GhosttyRenderStateRowIterator* out_iterator);
511
512 /**
513 * Free a render-state row iterator.
514 *
515 * @param iterator The iterator handle to free (may be NULL)
516 *
517 * @ingroup render
518 */
519 GHOSTTY_API void ghostty_render_state_row_iterator_free(GhosttyRenderStateRowIterator iterator);
520
521 /**
522 * Move a render-state row iterator to the next row.
523 *
524 * Returns true if the iterator moved successfully and row data is
525 * available to read at the new position.
526 *
527 * @param iterator The iterator handle to advance (may be NULL)
528 * @return true if advanced to the next row, false if `iterator` is
529 * NULL or if the iterator has reached the end
530 *
531 * @ingroup render
532 */
533 GHOSTTY_API bool ghostty_render_state_row_iterator_next(GhosttyRenderStateRowIterator iterator);
534
535 /**
536 * Get a value from the current row in a render-state row iterator.
537 *
538 * The `out` pointer must point to a value of the type corresponding to the
539 * requested data kind (see GhosttyRenderStateRowData).
540 * Call ghostty_render_state_row_iterator_next() at least once before
541 * calling this function.
542 *
543 * @param iterator The iterator handle to query (NULL returns GHOSTTY_INVALID_VALUE)
544 * @param data The data kind to query
545 * @param[out] out Pointer to receive the queried value
546 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if
547 * `iterator` is NULL or the iterator is not positioned on a row
548 *
549 * @ingroup render
550 */
551 GHOSTTY_API GhosttyResult ghostty_render_state_row_get(
552 GhosttyRenderStateRowIterator iterator,
553 GhosttyRenderStateRowData data,
554 void* out);
555
556 /**
557 * Get multiple data fields from the current row in a single call.
558 *
559 * Each element in the keys array specifies a data kind, and the
560 * corresponding element in the values array receives the result.
561 *
562 * Processing stops at the first error; on success out_written
563 * is set to count, on error it is set to the index of the
564 * failing key (i.e. the number of values successfully written).
565 *
566 * @param iterator The iterator handle (NULL returns GHOSTTY_INVALID_VALUE)
567 * @param count Number of key/value pairs
568 * @param keys Array of data kinds to query
569 * @param values Array of output pointers (types must match each key's
570 * documented output type)
571 * @param[out] out_written On return, receives the number of values
572 * successfully written (may be NULL)
573 * @return GHOSTTY_SUCCESS if all queries succeed
574 *
575 * @ingroup render
576 */
577 GHOSTTY_API GhosttyResult ghostty_render_state_row_get_multi(
578 GhosttyRenderStateRowIterator iterator,
579 size_t count,
580 const GhosttyRenderStateRowData* keys,
581 void** values,
582 size_t* out_written);
583
584 /**
585 * Set an option on the current row in a render-state row iterator.
586 *
587 * The `value` pointer must point to a value of the type corresponding to the
588 * requested option kind (see GhosttyRenderStateRowOption).
589 * Call ghostty_render_state_row_iterator_next() at least once before
590 * calling this function.
591 *
592 * @param iterator The iterator handle to update (NULL returns GHOSTTY_INVALID_VALUE)
593 * @param option The option to set
594 * @param[in] value Pointer to the value to set (NULL returns
595 * GHOSTTY_INVALID_VALUE)
596 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if
597 * `iterator` is NULL or the iterator is not positioned on a row
598 *
599 * @ingroup render
600 */
601 GHOSTTY_API GhosttyResult ghostty_render_state_row_set(
602 GhosttyRenderStateRowIterator iterator,
603 GhosttyRenderStateRowOption option,
604 const void* value);
605
606 /**
607 * Create a new row cells instance.
608 *
609 * All fields except the allocator are left undefined until populated
610 * via ghostty_render_state_row_get() with
611 * GHOSTTY_RENDER_STATE_ROW_DATA_CELLS.
612 *
613 * You can reuse this value repeatedly with ghostty_render_state_row_get() to
614 * avoid allocating a new cells container for every row.
615 *
616 * @param allocator Pointer to allocator, or NULL to use the default allocator
617 * @param[out] out_cells On success, receives the created row cells handle
618 * @return GHOSTTY_SUCCESS on success, GHOSTTY_OUT_OF_MEMORY on allocation
619 * failure
620 *
621 * @ingroup render
622 */
623 GHOSTTY_API GhosttyResult ghostty_render_state_row_cells_new(
624 const GhosttyAllocator* allocator,
625 GhosttyRenderStateRowCells* out_cells);
626
627 /**
628 * Queryable data kinds for ghostty_render_state_row_cells_get().
629 *
630 * @ingroup render
631 */
632 typedef enum GHOSTTY_ENUM_TYPED {
633 /** Invalid / sentinel value. */
634 GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_INVALID = 0,
635
636 /** The raw cell value (GhosttyCell). */
637 GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_RAW = 1,
638
639 /** The style for the current cell (GhosttyStyle). */
640 GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_STYLE = 2,
641
642 /** The total number of grapheme codepoints including the base codepoint
643 * (uint32_t). Returns 0 if the cell has no text. */
644 GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_GRAPHEMES_LEN = 3,
645
646 /** Write grapheme codepoints into a caller-provided buffer (uint32_t*).
647 * The buffer must be at least graphemes_len elements. The base codepoint
648 * is written first, followed by any extra codepoints. */
649 GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_GRAPHEMES_BUF = 4,
650
651 /** The resolved background color of the cell (GhosttyColorRgb).
652 * Flattens the three possible sources: content-tag bg_color_rgb,
653 * content-tag bg_color_palette (looked up in the palette), or the
654 * style's bg_color. Returns GHOSTTY_INVALID_VALUE if the cell has
655 * no background color, in which case the caller should use whatever
656 * default background color it wants (e.g. the terminal background). */
657 GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_BG_COLOR = 5,
658
659 /** The resolved foreground color of the cell (GhosttyColorRgb).
660 * Resolves palette indices through the palette. Bold color handling
661 * is not applied; the caller should handle bold styling separately.
662 * Returns GHOSTTY_INVALID_VALUE if the cell has no explicit foreground
663 * color, in which case the caller should use whatever default foreground
664 * color it wants (e.g. the terminal foreground). */
665 GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_FG_COLOR = 6,
666
667 /** Whether the cell is contained within the current selection (bool).
668 * This returns true when the cell's column is within the current row's
669 * row-local selection range, and false otherwise. Rendering policy for
670 * selected cells (colors, inversion, etc.) is left to the caller.
671 *
672 * Renderers that can draw cells in spans may be more efficient querying
673 * GHOSTTY_RENDER_STATE_ROW_DATA_SELECTION once per row and applying that
674 * range directly, avoiding one C API call per cell for selection state. */
675 GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_SELECTED = 7,
676
677 /** Whether the cell has any explicit styling (bool).
678 * This is equivalent to querying the raw cell's
679 * GHOSTTY_CELL_DATA_HAS_STYLING value, but avoids materializing the raw
680 * GhosttyCell for renderers that only need to know whether fetching the
681 * full style is necessary. */
682 GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_HAS_STYLING = 8,
683
684 /**
685 * Encode the current cell's full grapheme cluster as UTF-8 into a
686 * caller-provided buffer (GhosttyBuffer).
687 *
688 * The base codepoint is encoded first, followed by any extra grapheme
689 * codepoints. Returns GHOSTTY_SUCCESS with len=0 when the cell has no text.
690 *
691 * If ptr is NULL or cap is too small for a non-empty cell, returns
692 * GHOSTTY_OUT_OF_SPACE without writing any bytes and sets len to the required
693 * buffer size in bytes.
694 */
695 GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_GRAPHEMES_UTF8 = 9,
696 GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
697 } GhosttyRenderStateRowCellsData;
698
699 /**
700 * Move a render-state row cells iterator to the next cell.
701 *
702 * Returns true if the iterator moved successfully and cell data is
703 * available to read at the new position.
704 *
705 * @param cells The row cells handle to advance (may be NULL)
706 * @return true if advanced to the next cell, false if `cells` is
707 * NULL or if the iterator has reached the end
708 *
709 * @ingroup render
710 */
711 GHOSTTY_API bool ghostty_render_state_row_cells_next(GhosttyRenderStateRowCells cells);
712
713 /**
714 * Move a render-state row cells iterator to a specific column.
715 *
716 * Positions the iterator at the given x (column) index so that
717 * subsequent reads return data for that cell.
718 *
719 * @param cells The row cells handle to reposition (NULL returns
720 * GHOSTTY_INVALID_VALUE)
721 * @param x The zero-based column index to select
722 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if `cells`
723 * is NULL or `x` is out of range
724 *
725 * @ingroup render
726 */
727 GHOSTTY_API GhosttyResult ghostty_render_state_row_cells_select(
728 GhosttyRenderStateRowCells cells, uint16_t x);
729
730 /**
731 * Get a value from the current cell in a render-state row cells iterator.
732 *
733 * The `out` pointer must point to a value of the type corresponding to the
734 * requested data kind (see GhosttyRenderStateRowCellsData).
735 * Call ghostty_render_state_row_cells_next() or
736 * ghostty_render_state_row_cells_select() at least once before
737 * calling this function.
738 *
739 * @param cells The row cells handle to query (NULL returns GHOSTTY_INVALID_VALUE)
740 * @param data The data kind to query
741 * @param[out] out Pointer to receive the queried value
742 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if
743 * `cells` is NULL or the iterator is not positioned on a cell
744 *
745 * @ingroup render
746 */
747 GHOSTTY_API GhosttyResult ghostty_render_state_row_cells_get(
748 GhosttyRenderStateRowCells cells,
749 GhosttyRenderStateRowCellsData data,
750 void* out);
751
752 /**
753 * Get multiple data fields from the current cell in a single call.
754 *
755 * Each element in the keys array specifies a data kind, and the
756 * corresponding element in the values array receives the result.
757 *
758 * Processing stops at the first error; on success out_written
759 * is set to count, on error it is set to the index of the
760 * failing key (i.e. the number of values successfully written).
761 *
762 * @param cells The row cells handle (NULL returns GHOSTTY_INVALID_VALUE)
763 * @param count Number of key/value pairs
764 * @param keys Array of data kinds to query
765 * @param values Array of output pointers (types must match each key's
766 * documented output type)
767 * @param[out] out_written On return, receives the number of values
768 * successfully written (may be NULL)
769 * @return GHOSTTY_SUCCESS if all queries succeed
770 *
771 * @ingroup render
772 */
773 GHOSTTY_API GhosttyResult ghostty_render_state_row_cells_get_multi(
774 GhosttyRenderStateRowCells cells,
775 size_t count,
776 const GhosttyRenderStateRowCellsData* keys,
777 void** values,
778 size_t* out_written);
779
780 /**
781 * Free a row cells instance.
782 *
783 * @param cells The row cells handle to free (may be NULL)
784 *
785 * @ingroup render
786 */
787 GHOSTTY_API void ghostty_render_state_row_cells_free(GhosttyRenderStateRowCells cells);
788
789 /** @} */
790
791 #ifdef __cplusplus
792 }
793 #endif
794
795 #endif /* GHOSTTY_VT_RENDER_H */