authorgravatar for 71498452+StiensWout@users.noreply.github.comWout Stiens <71498452+StiensWout@users.noreply.github.com> 2026-07-31 14:20:27+02:00
committergravatar for noreply@github.comGitHub <noreply@github.com> 2026-07-31 14:20:27+02:00
log964cc279014f512b4fc4c719377403417744ace2
tree08bc6dd3b72001e6667008435b038cf7cf5ea612
parentacf761b2f511e1918260a8043e151bbc2849e29a
signature Signed by PGP key B5690EEEBB952194

refactor: move the canonical libghostty-vt vendor to the repository root (#5102)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

72 files changed, 8950 insertions(+), 8950 deletions(-)

apps/mobile/modules/t3-terminal/README.md+1-1
......@@ -40,7 +40,7 @@ fails, run `xcodebuild -downloadComponent MetalToolchain`.
4040## Rebuilding libghostty-vt for Android
4141
4242The checked-in Android shared libraries and headers are pinned to the revision recorded in
43`Vendor/libghostty-vt/VERSION`. Set `ANDROID_NDK_HOME` and run:
43`native/libghostty-vt/VERSION` at the repository root. Set `ANDROID_NDK_HOME` and run:
4444
4545```bash
4646apps/mobile/modules/t3-terminal/scripts/build-libghostty-android.sh
apps/mobile/modules/t3-terminal/THIRD_PARTY_NOTICES.md+1-1
......@@ -25,7 +25,7 @@ The web terminal vendors a WebAssembly build from the same revision and uses the
2525- License: MIT
2626
2727Ghostty's MIT license applies to the vendored Android and web libraries. Keep this notice and both
28artifacts in sync when updating `Vendor/libghostty-vt`.
28artifacts in sync when updating the repository-root `native/libghostty-vt`.
2929
3030## MesloLGS NF (Android terminal font)
3131
apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/LICENSE deleted-21
......@@ -1,21 +0,0 @@
1MIT License
2
3Copyright (c) 2024 Mitchell Hashimoto, Ghostty contributors
4
5Permission is hereby granted, free of charge, to any person obtaining a copy
6of this software and associated documentation files (the "Software"), to deal
7in the Software without restriction, including without limitation the rights
8to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9copies of the Software, and to permit persons to whom the Software is
10furnished to do so, subject to the following conditions:
11
12The above copyright notice and this permission notice shall be included in all
13copies or substantial portions of the Software.
14
15THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21SOFTWARE.
apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/VERSION deleted-1
......@@ -1 +0,0 @@
19f62873bf195e4d8a762d768a1405a5f2f7b1697
apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt.h deleted-154
......@@ -1,154 +0,0 @@
1/**
2 * @file vt.h
3 *
4 * libghostty-vt - Virtual terminal emulator library
5 *
6 * This library provides functionality for parsing and handling terminal
7 * escape sequences as well as maintaining terminal state such as styles,
8 * cursor position, screen, scrollback, and more.
9 *
10 * WARNING: This is an incomplete, work-in-progress API. It is not yet
11 * stable and is definitely going to change.
12 */
13
14/**
15 * @mainpage libghostty-vt - Virtual Terminal Emulator Library
16 *
17 * libghostty-vt is a C library which implements a modern terminal emulator,
18 * extracted from the [Ghostty](https://ghostty.org) terminal emulator.
19 *
20 * libghostty-vt contains the logic for handling the core parts of a terminal
21 * emulator: parsing terminal escape sequences, maintaining terminal state,
22 * encoding input events, etc. It can handle scrollback, line wrapping,
23 * reflow on resize, and more.
24 *
25 * @warning This library is currently in development and the API is not yet stable.
26 * Breaking changes are expected in future versions. Use with caution in production code.
27 *
28 * @section groups_sec API Reference
29 *
30 * The API is organized into the following groups:
31 * - @ref terminal "Terminal" - Complete terminal emulator state and rendering
32 * - @ref render "Render State" - Incremental render state updates for custom renderers
33 * - @ref formatter "Formatter" - Format terminal content as plain text, VT sequences, or HTML
34 * - @ref osc "OSC Parser" - Parse OSC (Operating System Command) sequences
35 * - @ref sgr "SGR Parser" - Parse SGR (Select Graphic Rendition) sequences
36 * - @ref paste "Paste Utilities" - Validate paste data safety
37 * - @ref build_info "Build Info" - Query compile-time build configuration
38 * - @ref allocator "Memory Management" - Memory management and custom allocators
39 * - @ref wasm "WebAssembly Utilities" - WebAssembly convenience functions
40 *
41 * Encoding related APIs:
42 * - @ref focus "Focus Encoding" - Encode focus in/out events into terminal sequences
43 * - @ref key "Key Encoding" - Encode key events into terminal sequences
44 * - @ref mouse "Mouse Encoding" - Encode mouse events into terminal sequences
45 *
46 * @section examples_sec Examples
47 *
48 * Complete working examples:
49 * - @ref c-vt-build-info/src/main.c - Build info query example
50 * - @ref c-vt/src/main.c - OSC parser example
51 * - @ref c-vt-encode-key/src/main.c - Key encoding example
52 * - @ref c-vt-encode-mouse/src/main.c - Mouse encoding example
53 * - @ref c-vt-paste/src/main.c - Paste safety check example
54 * - @ref c-vt-sgr/src/main.c - SGR parser example
55 * - @ref c-vt-formatter/src/main.c - Terminal formatter example
56 * - @ref c-vt-grid-traverse/src/main.c - Grid traversal example using grid refs
57 * - @ref c-vt-grid-ref-tracked/src/main.c - Tracked grid ref example
58 *
59 */
60
61/** @example c-vt-build-info/src/main.c
62 * This example demonstrates how to query compile-time build configuration
63 * such as SIMD support, Kitty graphics, and tmux control mode availability.
64 */
65
66/** @example c-vt/src/main.c
67 * This example demonstrates how to use the OSC parser to parse an OSC sequence,
68 * extract command information, and retrieve command-specific data like window titles.
69 */
70
71/** @example c-vt-encode-key/src/main.c
72 * This example demonstrates how to use the key encoder to convert key events
73 * into terminal escape sequences using the Kitty keyboard protocol.
74 */
75
76/** @example c-vt-encode-mouse/src/main.c
77 * This example demonstrates how to use the mouse encoder to convert mouse events
78 * into terminal escape sequences using the SGR mouse format.
79 */
80
81/** @example c-vt-paste/src/main.c
82 * This example demonstrates how to use the paste utilities to check if
83 * paste data is safe before sending it to the terminal.
84 */
85
86/** @example c-vt-sgr/src/main.c
87 * This example demonstrates how to use the SGR parser to parse terminal
88 * styling sequences and extract text attributes like colors and underline styles.
89 */
90
91/** @example c-vt-formatter/src/main.c
92 * This example demonstrates how to use the terminal and formatter APIs to
93 * create a terminal, write VT-encoded content into it, and format the screen
94 * contents as plain text.
95 */
96
97/** @example c-vt-grid-traverse/src/main.c
98 * This example demonstrates how to traverse the entire terminal grid using
99 * grid refs to inspect cell codepoints, row wrap state, and cell styles.
100 */
101
102/** @example c-vt-grid-ref-tracked/src/main.c
103 * This example demonstrates how to track a grid ref as the terminal scrolls,
104 * detect when it loses its value, and move it to a new point.
105 */
106
107/** @example c-vt-selection-gesture/src/main.c
108 * This example demonstrates how to use synthetic selection gesture events to
109 * derive drag and deep-press selection snapshots.
110 */
111
112/** @example c-vt-kitty-graphics/src/main.c
113 * This example demonstrates how to use the system interface to install a
114 * PNG decoder callback and send a Kitty Graphics Protocol image.
115 */
116
117#ifndef GHOSTTY_VT_H
118#define GHOSTTY_VT_H
119
120#ifdef __cplusplus
121extern "C" {
122#endif
123
124#include <ghostty/vt/types.h>
125#include <ghostty/vt/allocator.h>
126#include <ghostty/vt/build_info.h>
127#include <ghostty/vt/color.h>
128#include <ghostty/vt/device.h>
129#include <ghostty/vt/focus.h>
130#include <ghostty/vt/formatter.h>
131#include <ghostty/vt/render.h>
132#include <ghostty/vt/terminal.h>
133#include <ghostty/vt/grid_ref.h>
134#include <ghostty/vt/grid_ref_tracked.h>
135#include <ghostty/vt/osc.h>
136#include <ghostty/vt/sgr.h>
137#include <ghostty/vt/style.h>
138#include <ghostty/vt/sys.h>
139#include <ghostty/vt/key.h>
140#include <ghostty/vt/kitty_graphics.h>
141#include <ghostty/vt/modes.h>
142#include <ghostty/vt/mouse.h>
143#include <ghostty/vt/paste.h>
144#include <ghostty/vt/point.h>
145#include <ghostty/vt/screen.h>
146#include <ghostty/vt/selection.h>
147#include <ghostty/vt/size_report.h>
148#include <ghostty/vt/wasm.h>
149
150#ifdef __cplusplus
151}
152#endif
153
154#endif /* GHOSTTY_VT_H */
apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/allocator.h deleted-255
......@@ -1,255 +0,0 @@
1/**
2 * @file allocator.h
3 *
4 * Memory management interface for libghostty-vt.
5 */
6
7#ifndef GHOSTTY_VT_ALLOCATOR_H
8#define GHOSTTY_VT_ALLOCATOR_H
9
10#include <stdbool.h>
11#include <stddef.h>
12#include <stdint.h>
13#include <ghostty/vt/types.h>
14
15/** @defgroup allocator Memory Management
16 *
17 * libghostty-vt does require memory allocation for various operations,
18 * but is resilient to allocation failures and will gracefully handle
19 * out-of-memory situations by returning error codes.
20 *
21 * The exact memory management semantics are documented in the relevant
22 * functions and data structures.
23 *
24 * libghostty-vt uses explicit memory allocation via an allocator
25 * interface provided by GhosttyAllocator. The interface is based on the
26 * [Zig](https://ziglang.org) allocator interface, since this has been
27 * shown to be a flexible and powerful interface in practice and enables
28 * a wide variety of allocation strategies.
29 *
30 * **For the common case, you can pass NULL as the allocator for any
31 * function that accepts one,** and libghostty will use a default allocator.
32 * The default allocator will be libc malloc/free if libc is linked.
33 * Otherwise, a custom allocator is used (currently Zig's SMP allocator)
34 * that doesn't require any external dependencies.
35 *
36 * ## Basic Usage
37 *
38 * For simple use cases, you can ignore this interface entirely by passing NULL
39 * as the allocator parameter to functions that accept one. This will use the
40 * default allocator (typically libc malloc/free, if libc is linked, but
41 * we provide our own default allocator if libc isn't linked).
42 *
43 * To use a custom allocator:
44 * 1. Implement the GhosttyAllocatorVtable function pointers
45 * 2. Create a GhosttyAllocator struct with your vtable and context
46 * 3. Pass the allocator to functions that accept one
47 *
48 * ## Alloc/Free Helpers
49 *
50 * ghostty_alloc() and ghostty_free() provide a simple malloc/free-style
51 * interface for allocating and freeing byte buffers through the library's
52 * allocator. These are useful when:
53 *
54 * - You need to allocate a buffer to pass into a libghostty-vt function
55 * (e.g. preparing input data for ghostty_terminal_vt_write()).
56 * - You need to free a buffer returned by a libghostty-vt function
57 * (e.g. the output of ghostty_formatter_format_alloc()).
58 * - You are on a platform where the library's internal allocator differs
59 * from the consumer's C runtime (e.g. Windows, where Zig's libc and
60 * MSVC's CRT maintain separate heaps), so calling the standard C
61 * free() on library-allocated memory would be undefined behavior.
62 *
63 * Always use the same allocator (or NULL) for both the allocation and
64 * the corresponding free.
65 *
66 * @{
67 */
68
69/**
70 * Function table for custom memory allocator operations.
71 *
72 * This vtable defines the interface for a custom memory allocator. All
73 * function pointers must be valid and non-NULL.
74 *
75 * @ingroup allocator
76 *
77 * If you're not going to use a custom allocator, you can ignore all of
78 * this. All functions that take an allocator pointer allow NULL to use a
79 * default allocator.
80 *
81 * The interface is based on the Zig allocator interface. I'll say up front
82 * that it is easy to look at this interface and think "wow, this is really
83 * overcomplicated". The reason for this complexity is well thought out by
84 * the Zig folks, and it enables a diverse set of allocation strategies
85 * as shown by the Zig ecosystem. As a consolation, please note that many
86 * of the arguments are only needed for advanced use cases and can be
87 * safely ignored in simple implementations. For example, if you look at
88 * the Zig implementation of the libc allocator in `lib/std/heap.zig`
89 * (search for CAllocator), you'll see it is very simple.
90 *
91 * We chose to align with the Zig allocator interface because:
92 *
93 * 1. It is a proven interface that serves a wide variety of use cases
94 * in the real world via the Zig ecosystem. It's shown to work.
95 *
96 * 2. Our core implementation itself is Zig, and this lets us very
97 * cheaply and easily convert between C and Zig allocators.
98 *
99 * NOTE(mitchellh): In the future, we can have default implementations of
100 * resize/remap and allow those to be null.
101 */
102typedef struct {
103 /**
104 * Return a pointer to `len` bytes with specified `alignment`, or return
105 * `NULL` indicating the allocation failed.
106 *
107 * @param ctx The allocator context
108 * @param len Number of bytes to allocate
109 * @param alignment Required alignment for the allocation. Guaranteed to
110 * be a power of two between 1 and 16 inclusive.
111 * @param ret_addr First return address of the allocation call stack (0 if not provided)
112 * @return Pointer to allocated memory, or NULL if allocation failed
113 */
114 void* (*alloc)(void *ctx, size_t len, uint8_t alignment, uintptr_t ret_addr);
115
116 /**
117 * Attempt to expand or shrink memory in place.
118 *
119 * `memory_len` must equal the length requested from the most recent
120 * successful call to `alloc`, `resize`, or `remap`. `alignment` must
121 * equal the same value that was passed as the `alignment` parameter to
122 * the original `alloc` call.
123 *
124 * `new_len` must be greater than zero.
125 *
126 * @param ctx The allocator context
127 * @param memory Pointer to the memory block to resize
128 * @param memory_len Current size of the memory block
129 * @param alignment Alignment (must match original allocation)
130 * @param new_len New requested size
131 * @param ret_addr First return address of the allocation call stack (0 if not provided)
132 * @return true if resize was successful in-place, false if relocation would be required
133 */
134 bool (*resize)(void *ctx, void *memory, size_t memory_len, uint8_t alignment, size_t new_len, uintptr_t ret_addr);
135
136 /**
137 * Attempt to expand or shrink memory, allowing relocation.
138 *
139 * `memory_len` must equal the length requested from the most recent
140 * successful call to `alloc`, `resize`, or `remap`. `alignment` must
141 * equal the same value that was passed as the `alignment` parameter to
142 * the original `alloc` call.
143 *
144 * A non-`NULL` return value indicates the resize was successful. The
145 * allocation may have same address, or may have been relocated. In either
146 * case, the allocation now has size of `new_len`. A `NULL` return value
147 * indicates that the resize would be equivalent to allocating new memory,
148 * copying the bytes from the old memory, and then freeing the old memory.
149 * In such case, it is more efficient for the caller to perform the copy.
150 *
151 * `new_len` must be greater than zero.
152 *
153 * @param ctx The allocator context
154 * @param memory Pointer to the memory block to remap
155 * @param memory_len Current size of the memory block
156 * @param alignment Alignment (must match original allocation)
157 * @param new_len New requested size
158 * @param ret_addr First return address of the allocation call stack (0 if not provided)
159 * @return Pointer to resized memory (may be relocated), or NULL if manual copy is needed
160 */
161 void* (*remap)(void *ctx, void *memory, size_t memory_len, uint8_t alignment, size_t new_len, uintptr_t ret_addr);
162
163 /**
164 * Free and invalidate a region of memory.
165 *
166 * `memory_len` must equal the length requested from the most recent
167 * successful call to `alloc`, `resize`, or `remap`. `alignment` must
168 * equal the same value that was passed as the `alignment` parameter to
169 * the original `alloc` call.
170 *
171 * @param ctx The allocator context
172 * @param memory Pointer to the memory block to free
173 * @param memory_len Size of the memory block
174 * @param alignment Alignment (must match original allocation)
175 * @param ret_addr First return address of the allocation call stack (0 if not provided)
176 */
177 void (*free)(void *ctx, void *memory, size_t memory_len, uint8_t alignment, uintptr_t ret_addr);
178} GhosttyAllocatorVtable;
179
180/**
181 * Custom memory allocator.
182 *
183 * For functions that take an allocator pointer, a NULL pointer indicates
184 * that the default allocator should be used. The default allocator will
185 * be libc malloc/free if we're linking to libc. If libc isn't linked,
186 * a custom allocator is used (currently Zig's SMP allocator).
187 *
188 * @ingroup allocator
189 *
190 * Usage example:
191 * @code
192 * GhosttyAllocator allocator = {
193 * .vtable = &my_allocator_vtable,
194 * .ctx = my_allocator_state
195 * };
196 * @endcode
197 */
198typedef struct GhosttyAllocator {
199 /**
200 * Opaque context pointer passed to all vtable functions.
201 * This allows the allocator implementation to maintain state
202 * or reference external resources needed for memory management.
203 */
204 void *ctx;
205
206 /**
207 * Pointer to the allocator's vtable containing function pointers
208 * for memory operations (alloc, resize, remap, free).
209 */
210 const GhosttyAllocatorVtable *vtable;
211} GhosttyAllocator;
212
213/**
214 * Allocate a buffer of `len` bytes.
215 *
216 * Uses the provided allocator, or the default allocator if NULL is passed.
217 * The returned buffer must be freed with ghostty_free() using the same
218 * allocator.
219 *
220 * @param allocator Pointer to the allocator to use, or NULL for the default
221 * @param len Number of bytes to allocate
222 * @return Pointer to the allocated buffer, or NULL if allocation failed
223 *
224 * @ingroup allocator
225 */
226GHOSTTY_API uint8_t* ghostty_alloc(const GhosttyAllocator* allocator, size_t len);
227
228/**
229 * Free memory that was allocated by a libghostty-vt function.
230 *
231 * Use this to free buffers returned by functions such as
232 * ghostty_formatter_format_alloc(). Pass the same allocator that was
233 * used for the allocation, or NULL if the default allocator was used.
234 *
235 * On platforms where the library's internal allocator differs from the
236 * consumer's C runtime (e.g. Windows, where Zig's libc and MSVC's CRT
237 * maintain separate heaps), calling the standard C free() on memory
238 * allocated by the library causes undefined behavior. This function
239 * guarantees the correct allocator is used regardless of platform.
240 *
241 * It is safe to pass a NULL pointer; the call is a no-op in that case.
242 *
243 * @param allocator Pointer to the allocator that was used to allocate the
244 * memory, or NULL if the default allocator was used
245 * @param ptr Pointer to the memory to free (may be NULL)
246 * @param len Length of the allocation in bytes (must match the original
247 * allocation size)
248 *
249 * @ingroup allocator
250 */
251GHOSTTY_API void ghostty_free(const GhosttyAllocator* allocator, uint8_t* ptr, size_t len);
252
253/** @} */
254
255#endif /* GHOSTTY_VT_ALLOCATOR_H */
apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/build_info.h deleted-150
......@@ -1,150 +0,0 @@
1/**
2 * @file build_info.h
3 *
4 * Build info - query compile-time build configuration of libghostty-vt.
5 */
6
7#ifndef GHOSTTY_VT_BUILD_INFO_H
8#define GHOSTTY_VT_BUILD_INFO_H
9
10/** @defgroup build_info Build Info
11 *
12 * Query compile-time build configuration of libghostty-vt.
13 *
14 * These values reflect the options the library was built with and are
15 * constant for the lifetime of the process.
16 *
17 * ## Basic Usage
18 *
19 * Use ghostty_build_info() to query individual build options:
20 *
21 * @snippet c-vt-build-info/src/main.c build-info-query
22 *
23 * @{
24 */
25
26#include <stddef.h>
27#include <stdbool.h>
28
29#include <ghostty/vt/types.h>
30
31#ifdef __cplusplus
32extern "C" {
33#endif
34
35/**
36 * Build optimization mode.
37 */
38typedef enum GHOSTTY_ENUM_TYPED {
39 GHOSTTY_OPTIMIZE_DEBUG = 0,
40 GHOSTTY_OPTIMIZE_RELEASE_SAFE = 1,
41 GHOSTTY_OPTIMIZE_RELEASE_SMALL = 2,
42 GHOSTTY_OPTIMIZE_RELEASE_FAST = 3,
43 GHOSTTY_OPTIMIZE_MODE_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
44} GhosttyOptimizeMode;
45
46/**
47 * Build info data types that can be queried.
48 *
49 * Each variant documents the expected output pointer type.
50 */
51typedef enum GHOSTTY_ENUM_TYPED {
52 /** Invalid data type. Never results in any data extraction. */
53 GHOSTTY_BUILD_INFO_INVALID = 0,
54
55 /**
56 * Whether SIMD-accelerated code paths are enabled.
57 *
58 * Output type: bool *
59 */
60 GHOSTTY_BUILD_INFO_SIMD = 1,
61
62 /**
63 * Whether Kitty graphics protocol support is available.
64 *
65 * Output type: bool *
66 */
67 GHOSTTY_BUILD_INFO_KITTY_GRAPHICS = 2,
68
69 /**
70 * Whether tmux control mode support is available.
71 *
72 * Output type: bool *
73 */
74 GHOSTTY_BUILD_INFO_TMUX_CONTROL_MODE = 3,
75
76 /**
77 * The optimization mode the library was built with.
78 *
79 * Output type: GhosttyOptimizeMode *
80 */
81 GHOSTTY_BUILD_INFO_OPTIMIZE = 4,
82
83 /**
84 * The full version string (e.g. "1.2.3" or "1.2.3-dev+abcdef").
85 *
86 * Output type: GhosttyString *
87 */
88 GHOSTTY_BUILD_INFO_VERSION_STRING = 5,
89
90 /**
91 * The major version number.
92 *
93 * Output type: size_t *
94 */
95 GHOSTTY_BUILD_INFO_VERSION_MAJOR = 6,
96
97 /**
98 * The minor version number.
99 *
100 * Output type: size_t *
101 */
102 GHOSTTY_BUILD_INFO_VERSION_MINOR = 7,
103
104 /**
105 * The patch version number.
106 *
107 * Output type: size_t *
108 */
109 GHOSTTY_BUILD_INFO_VERSION_PATCH = 8,
110
111 /**
112 * The pre metadata string (e.g. "alpha", "beta", "dev"). Has zero length if
113 * no pre metadata is present.
114 *
115 * Output type: GhosttyString *
116 */
117 GHOSTTY_BUILD_INFO_VERSION_PRE = 9,
118
119 /**
120 * The build metadata string (e.g. commit hash). Has zero length if
121 * no build metadata is present.
122 *
123 * Output type: GhosttyString *
124 */
125 GHOSTTY_BUILD_INFO_VERSION_BUILD = 10,
126 GHOSTTY_BUILD_INFO_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
127} GhosttyBuildInfo;
128
129/**
130 * Query a compile-time build configuration value.
131 *
132 * The caller must pass a pointer to the correct output type for the
133 * requested data (see GhosttyBuildInfo variants for types).
134 *
135 * @param data The build info field to query
136 * @param out Pointer to store the result (type depends on data parameter)
137 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the
138 * data type is invalid
139 *
140 * @ingroup build_info
141 */
142GHOSTTY_API GhosttyResult ghostty_build_info(GhosttyBuildInfo data, void *out);
143
144#ifdef __cplusplus
145}
146#endif
147
148/** @} */
149
150#endif /* GHOSTTY_VT_BUILD_INFO_H */
apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/color.h deleted-97
......@@ -1,97 +0,0 @@
1/**
2 * @file color.h
3 *
4 * Color types and utilities.
5 */
6
7#ifndef GHOSTTY_VT_COLOR_H
8#define GHOSTTY_VT_COLOR_H
9
10#include <stdint.h>
11#include <ghostty/vt/types.h>
12
13#ifdef __cplusplus
14extern "C" {
15#endif
16
17/**
18 * RGB color value.
19 *
20 * @ingroup sgr
21 */
22typedef struct {
23 uint8_t r; /**< Red component (0-255) */
24 uint8_t g; /**< Green component (0-255) */
25 uint8_t b; /**< Blue component (0-255) */
26} GhosttyColorRgb;
27
28/**
29 * Palette color index (0-255).
30 *
31 * @ingroup sgr
32 */
33typedef uint8_t GhosttyColorPaletteIndex;
34
35/** @addtogroup sgr
36 * @{
37 */
38
39/** Black color (0) @ingroup sgr */
40#define GHOSTTY_COLOR_NAMED_BLACK 0
41/** Red color (1) @ingroup sgr */
42#define GHOSTTY_COLOR_NAMED_RED 1
43/** Green color (2) @ingroup sgr */
44#define GHOSTTY_COLOR_NAMED_GREEN 2
45/** Yellow color (3) @ingroup sgr */
46#define GHOSTTY_COLOR_NAMED_YELLOW 3
47/** Blue color (4) @ingroup sgr */
48#define GHOSTTY_COLOR_NAMED_BLUE 4
49/** Magenta color (5) @ingroup sgr */
50#define GHOSTTY_COLOR_NAMED_MAGENTA 5
51/** Cyan color (6) @ingroup sgr */
52#define GHOSTTY_COLOR_NAMED_CYAN 6
53/** White color (7) @ingroup sgr */
54#define GHOSTTY_COLOR_NAMED_WHITE 7
55/** Bright black color (8) @ingroup sgr */
56#define GHOSTTY_COLOR_NAMED_BRIGHT_BLACK 8
57/** Bright red color (9) @ingroup sgr */
58#define GHOSTTY_COLOR_NAMED_BRIGHT_RED 9
59/** Bright green color (10) @ingroup sgr */
60#define GHOSTTY_COLOR_NAMED_BRIGHT_GREEN 10
61/** Bright yellow color (11) @ingroup sgr */
62#define GHOSTTY_COLOR_NAMED_BRIGHT_YELLOW 11
63/** Bright blue color (12) @ingroup sgr */
64#define GHOSTTY_COLOR_NAMED_BRIGHT_BLUE 12
65/** Bright magenta color (13) @ingroup sgr */
66#define GHOSTTY_COLOR_NAMED_BRIGHT_MAGENTA 13
67/** Bright cyan color (14) @ingroup sgr */
68#define GHOSTTY_COLOR_NAMED_BRIGHT_CYAN 14
69/** Bright white color (15) @ingroup sgr */
70#define GHOSTTY_COLOR_NAMED_BRIGHT_WHITE 15
71
72/** @} */
73
74/**
75 * Get the RGB color components.
76 *
77 * This function extracts the individual red, green, and blue components
78 * from a GhosttyColorRgb value. Primarily useful in WebAssembly environments
79 * where accessing struct fields directly is difficult.
80 *
81 * @param color The RGB color value
82 * @param r Pointer to store the red component (0-255)
83 * @param g Pointer to store the green component (0-255)
84 * @param b Pointer to store the blue component (0-255)
85 *
86 * @ingroup sgr
87 */
88GHOSTTY_API void ghostty_color_rgb_get(GhosttyColorRgb color,
89 uint8_t* r,
90 uint8_t* g,
91 uint8_t* b);
92
93#ifdef __cplusplus
94}
95#endif
96
97#endif /* GHOSTTY_VT_COLOR_H */
apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/device.h deleted-151
......@@ -1,151 +0,0 @@
1/**
2 * @file device.h
3 *
4 * Device types used by the terminal for device status and device attribute
5 * queries.
6 */
7
8#ifndef GHOSTTY_VT_DEVICE_H
9#define GHOSTTY_VT_DEVICE_H
10
11#include <stddef.h>
12#include <stdint.h>
13
14/* DA1 conformance levels (Pp parameter). */
15#define GHOSTTY_DA_CONFORMANCE_VT100 1
16#define GHOSTTY_DA_CONFORMANCE_VT101 1
17#define GHOSTTY_DA_CONFORMANCE_VT102 6
18#define GHOSTTY_DA_CONFORMANCE_VT125 12
19#define GHOSTTY_DA_CONFORMANCE_VT131 7
20#define GHOSTTY_DA_CONFORMANCE_VT132 4
21#define GHOSTTY_DA_CONFORMANCE_VT220 62
22#define GHOSTTY_DA_CONFORMANCE_VT240 62
23#define GHOSTTY_DA_CONFORMANCE_VT320 63
24#define GHOSTTY_DA_CONFORMANCE_VT340 63
25#define GHOSTTY_DA_CONFORMANCE_VT420 64
26#define GHOSTTY_DA_CONFORMANCE_VT510 65
27#define GHOSTTY_DA_CONFORMANCE_VT520 65
28#define GHOSTTY_DA_CONFORMANCE_VT525 65
29#define GHOSTTY_DA_CONFORMANCE_LEVEL_2 62
30#define GHOSTTY_DA_CONFORMANCE_LEVEL_3 63
31#define GHOSTTY_DA_CONFORMANCE_LEVEL_4 64
32#define GHOSTTY_DA_CONFORMANCE_LEVEL_5 65
33
34/* DA1 feature codes (Ps parameters). */
35#define GHOSTTY_DA_FEATURE_COLUMNS_132 1
36#define GHOSTTY_DA_FEATURE_PRINTER 2
37#define GHOSTTY_DA_FEATURE_REGIS 3
38#define GHOSTTY_DA_FEATURE_SIXEL 4
39#define GHOSTTY_DA_FEATURE_SELECTIVE_ERASE 6
40#define GHOSTTY_DA_FEATURE_USER_DEFINED_KEYS 8
41#define GHOSTTY_DA_FEATURE_NATIONAL_REPLACEMENT 9
42#define GHOSTTY_DA_FEATURE_TECHNICAL_CHARACTERS 15
43#define GHOSTTY_DA_FEATURE_LOCATOR 16
44#define GHOSTTY_DA_FEATURE_TERMINAL_STATE 17
45#define GHOSTTY_DA_FEATURE_WINDOWING 18
46#define GHOSTTY_DA_FEATURE_HORIZONTAL_SCROLLING 21
47#define GHOSTTY_DA_FEATURE_ANSI_COLOR 22
48#define GHOSTTY_DA_FEATURE_RECTANGULAR_EDITING 28
49#define GHOSTTY_DA_FEATURE_ANSI_TEXT_LOCATOR 29
50#define GHOSTTY_DA_FEATURE_CLIPBOARD 52
51
52/* DA2 device type identifiers (Pp parameter). */
53#define GHOSTTY_DA_DEVICE_TYPE_VT100 0
54#define GHOSTTY_DA_DEVICE_TYPE_VT220 1
55#define GHOSTTY_DA_DEVICE_TYPE_VT240 2
56#define GHOSTTY_DA_DEVICE_TYPE_VT330 18
57#define GHOSTTY_DA_DEVICE_TYPE_VT340 19
58#define GHOSTTY_DA_DEVICE_TYPE_VT320 24
59#define GHOSTTY_DA_DEVICE_TYPE_VT382 32
60#define GHOSTTY_DA_DEVICE_TYPE_VT420 41
61#define GHOSTTY_DA_DEVICE_TYPE_VT510 61
62#define GHOSTTY_DA_DEVICE_TYPE_VT520 64
63#define GHOSTTY_DA_DEVICE_TYPE_VT525 65
64
65#ifdef __cplusplus
66extern "C" {
67#endif
68
69/**
70 * Color scheme reported in response to a CSI ? 996 n query.
71 *
72 * @ingroup terminal
73 */
74typedef enum GHOSTTY_ENUM_TYPED {
75 GHOSTTY_COLOR_SCHEME_LIGHT = 0,
76 GHOSTTY_COLOR_SCHEME_DARK = 1,
77 GHOSTTY_COLOR_SCHEME_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
78} GhosttyColorScheme;
79
80/**
81 * Primary device attributes (DA1) response data.
82 *
83 * Returned as part of GhosttyDeviceAttributes in response to a CSI c query.
84 * The conformance_level is the Pp parameter and features contains the Ps
85 * feature codes.
86 *
87 * @ingroup terminal
88 */
89typedef struct {
90 /** Conformance level (Pp parameter). E.g. 62 for VT220. */
91 uint16_t conformance_level;
92
93 /** DA1 feature codes. Only the first num_features entries are valid. */
94 uint16_t features[64];
95
96 /** Number of valid entries in the features array. */
97 size_t num_features;
98} GhosttyDeviceAttributesPrimary;
99
100/**
101 * Secondary device attributes (DA2) response data.
102 *
103 * Returned as part of GhosttyDeviceAttributes in response to a CSI > c query.
104 * Response format: CSI > Pp ; Pv ; Pc c
105 *
106 * @ingroup terminal
107 */
108typedef struct {
109 /** Terminal type identifier (Pp). E.g. 1 for VT220. */
110 uint16_t device_type;
111
112 /** Firmware/patch version number (Pv). */
113 uint16_t firmware_version;
114
115 /** ROM cartridge registration number (Pc). Always 0 for emulators. */
116 uint16_t rom_cartridge;
117} GhosttyDeviceAttributesSecondary;
118
119/**
120 * Tertiary device attributes (DA3) response data.
121 *
122 * Returned as part of GhosttyDeviceAttributes in response to a CSI = c query.
123 * Response format: DCS ! | D...D ST (DECRPTUI).
124 *
125 * @ingroup terminal
126 */
127typedef struct {
128 /** Unit ID encoded as 8 uppercase hex digits in the response. */
129 uint32_t unit_id;
130} GhosttyDeviceAttributesTertiary;
131
132/**
133 * Device attributes response data for all three DA levels.
134 *
135 * Filled by the device_attributes callback in response to CSI c,
136 * CSI > c, or CSI = c queries. The terminal uses whichever sub-struct
137 * matches the request type.
138 *
139 * @ingroup terminal
140 */
141typedef struct {
142 GhosttyDeviceAttributesPrimary primary;
143 GhosttyDeviceAttributesSecondary secondary;
144 GhosttyDeviceAttributesTertiary tertiary;
145} GhosttyDeviceAttributes;
146
147#ifdef __cplusplus
148}
149#endif
150
151#endif /* GHOSTTY_VT_DEVICE_H */
apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/focus.h deleted-76
......@@ -1,76 +0,0 @@
1/**
2 * @file focus.h
3 *
4 * Focus encoding - encode focus in/out events into terminal escape sequences.
5 */
6
7#ifndef GHOSTTY_VT_FOCUS_H
8#define GHOSTTY_VT_FOCUS_H
9
10/** @defgroup focus Focus Encoding
11 *
12 * Utilities for encoding focus gained/lost events into terminal escape
13 * sequences (CSI I / CSI O) for focus reporting mode (mode 1004).
14 *
15 * ## Basic Usage
16 *
17 * Use ghostty_focus_encode() to encode a focus event into a caller-provided
18 * buffer. If the buffer is too small, the function returns
19 * GHOSTTY_OUT_OF_SPACE and sets the required size in the output parameter.
20 *
21 * ## Example
22 *
23 * @snippet c-vt-encode-focus/src/main.c focus-encode
24 *
25 * @{
26 */
27
28#include <stddef.h>
29#include <ghostty/vt/types.h>
30
31#ifdef __cplusplus
32extern "C" {
33#endif
34
35/**
36 * Focus event types for focus reporting mode (mode 1004).
37 */
38typedef enum GHOSTTY_ENUM_TYPED {
39 /** Terminal window gained focus */
40 GHOSTTY_FOCUS_GAINED = 0,
41 /** Terminal window lost focus */
42 GHOSTTY_FOCUS_LOST = 1,
43 GHOSTTY_FOCUS_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
44} GhosttyFocusEvent;
45
46/**
47 * Encode a focus event into a terminal escape sequence.
48 *
49 * Encodes a focus gained (CSI I) or focus lost (CSI O) report into the
50 * provided buffer.
51 *
52 * If the buffer is too small, the function returns GHOSTTY_OUT_OF_SPACE
53 * and writes the required buffer size to @p out_written. The caller can
54 * then retry with a sufficiently sized buffer.
55 *
56 * @param event The focus event to encode
57 * @param buf Output buffer to write the encoded sequence into (may be NULL)
58 * @param buf_len Size of the output buffer in bytes
59 * @param[out] out_written On success, the number of bytes written. On
60 * GHOSTTY_OUT_OF_SPACE, the required buffer size.
61 * @return GHOSTTY_SUCCESS on success, GHOSTTY_OUT_OF_SPACE if the buffer
62 * is too small
63 */
64GHOSTTY_API GhosttyResult ghostty_focus_encode(
65 GhosttyFocusEvent event,
66 char* buf,
67 size_t buf_len,
68 size_t* out_written);
69
70#ifdef __cplusplus
71}
72#endif
73
74/** @} */
75
76#endif /* GHOSTTY_VT_FOCUS_H */
apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/formatter.h deleted-207
......@@ -1,207 +0,0 @@
1/**
2 * @file formatter.h
3 *
4 * Format terminal content as plain text, VT sequences, or HTML.
5 */
6
7#ifndef GHOSTTY_VT_FORMATTER_H
8#define GHOSTTY_VT_FORMATTER_H
9
10#include <stdbool.h>
11#include <stddef.h>
12#include <stdint.h>
13#include <ghostty/vt/allocator.h>
14#include <ghostty/vt/selection.h>
15#include <ghostty/vt/types.h>
16#include <ghostty/vt/terminal.h>
17
18#ifdef __cplusplus
19extern "C" {
20#endif
21
22/** @defgroup formatter Formatter
23 *
24 * Format terminal content as plain text, VT sequences, or HTML.
25 *
26 * A formatter captures a reference to a terminal and formatting options.
27 * It can be used repeatedly to produce output that reflects the current
28 * terminal state at the time of each format call.
29 *
30 * The terminal must outlive the formatter.
31 *
32 * @{
33 */
34
35/**
36 * Extra screen state to include in styled output.
37 *
38 * @ingroup formatter
39 */
40typedef struct {
41 /** Size of this struct in bytes. Must be set to sizeof(GhosttyFormatterScreenExtra). */
42 size_t size;
43
44 /** Emit cursor position using CUP (CSI H). */
45 bool cursor;
46
47 /** Emit current SGR style state based on the cursor's active style_id. */
48 bool style;
49
50 /** Emit current hyperlink state using OSC 8 sequences. */
51 bool hyperlink;
52
53 /** Emit character protection mode using DECSCA. */
54 bool protection;
55
56 /** Emit Kitty keyboard protocol state using CSI > u and CSI = sequences. */
57 bool kitty_keyboard;
58
59 /** Emit character set designations and invocations. */
60 bool charsets;
61} GhosttyFormatterScreenExtra;
62
63/**
64 * Extra terminal state to include in styled output.
65 *
66 * @ingroup formatter
67 */
68typedef struct {
69 /** Size of this struct in bytes. Must be set to sizeof(GhosttyFormatterTerminalExtra). */
70 size_t size;
71
72 /** Emit the palette using OSC 4 sequences. */
73 bool palette;
74
75 /** Emit terminal modes that differ from their defaults using CSI h/l. */
76 bool modes;
77
78 /** Emit scrolling region state using DECSTBM and DECSLRM sequences. */
79 bool scrolling_region;
80
81 /** Emit tabstop positions by clearing all tabs and setting each one. */
82 bool tabstops;
83
84 /** Emit the present working directory using OSC 7. */
85 bool pwd;
86
87 /** Emit keyboard modes such as ModifyOtherKeys. */
88 bool keyboard;
89
90 /** Screen-level extras. */
91 GhosttyFormatterScreenExtra screen;
92} GhosttyFormatterTerminalExtra;
93
94/**
95 * Options for creating a terminal formatter.
96 *
97 * @ingroup formatter
98 */
99typedef struct {
100 /** Size of this struct in bytes. Must be set to sizeof(GhosttyFormatterTerminalOptions). */
101 size_t size;
102
103 /** Output format to emit. */
104 GhosttyFormatterFormat emit;
105
106 /** Whether to unwrap soft-wrapped lines. */
107 bool unwrap;
108
109 /** Whether to trim trailing whitespace on non-blank lines. */
110 bool trim;
111
112 /** Extra terminal state to include in styled output. */
113 GhosttyFormatterTerminalExtra extra;
114
115 /** Optional selection to restrict output to a range.
116 * If NULL, the entire screen is formatted. */
117 const GhosttySelection *selection;
118} GhosttyFormatterTerminalOptions;
119
120/**
121 * Create a formatter for a terminal's active screen.
122 *
123 * The terminal must outlive the formatter. The formatter stores a borrowed
124 * reference to the terminal and reads its current state on each format call.
125 *
126 * @param allocator Pointer to allocator, or NULL to use the default allocator
127 * @param formatter Pointer to store the created formatter handle
128 * @param terminal The terminal to format (must not be NULL)
129 * @param options Formatting options
130 * @return GHOSTTY_SUCCESS on success, or an error code on failure
131 *
132 * @ingroup formatter
133 */
134GHOSTTY_API GhosttyResult ghostty_formatter_terminal_new(
135 const GhosttyAllocator* allocator,
136 GhosttyFormatter* formatter,
137 GhosttyTerminal terminal,
138 GhosttyFormatterTerminalOptions options);
139
140/**
141 * Run the formatter and produce output into the caller-provided buffer.
142 *
143 * Each call formats the current terminal state. Pass NULL for buf to
144 * query the required buffer size without writing any output; in that case
145 * out_written receives the required size and the return value is
146 * GHOSTTY_OUT_OF_SPACE.
147 *
148 * If the buffer is too small, returns GHOSTTY_OUT_OF_SPACE and sets
149 * out_written to the required size. The caller can then retry with a
150 * larger buffer.
151 *
152 * @param formatter The formatter handle (must not be NULL)
153 * @param buf Pointer to the output buffer, or NULL to query size
154 * @param buf_len Length of the output buffer in bytes
155 * @param out_written Pointer to receive the number of bytes written,
156 * or the required size on failure
157 * @return GHOSTTY_SUCCESS on success, or an error code on failure
158 *
159 * @ingroup formatter
160 */
161GHOSTTY_API GhosttyResult ghostty_formatter_format_buf(GhosttyFormatter formatter,
162 uint8_t* buf,
163 size_t buf_len,
164 size_t* out_written);
165
166/**
167 * Run the formatter and return an allocated buffer with the output.
168 *
169 * Each call formats the current terminal state. The buffer is allocated
170 * using the provided allocator (or the default allocator if NULL).
171 * The caller is responsible for freeing the returned buffer with
172 * ghostty_free(), passing the same allocator (or NULL for the default)
173 * that was used for the allocation.
174 *
175 * @param formatter The formatter handle (must not be NULL)
176 * @param allocator Pointer to allocator, or NULL to use the default allocator
177 * @param out_ptr Pointer to receive the allocated buffer
178 * @param out_len Pointer to receive the length of the output in bytes
179 * @return GHOSTTY_SUCCESS on success, GHOSTTY_OUT_OF_MEMORY on allocation
180 * failure
181 *
182 * @ingroup formatter
183 */
184GHOSTTY_API GhosttyResult ghostty_formatter_format_alloc(GhosttyFormatter formatter,
185 const GhosttyAllocator* allocator,
186 uint8_t** out_ptr,
187 size_t* out_len);
188
189/**
190 * Free a formatter instance.
191 *
192 * Releases all resources associated with the formatter. After this call,
193 * the formatter handle becomes invalid.
194 *
195 * @param formatter The formatter handle to free (may be NULL)
196 *
197 * @ingroup formatter
198 */
199GHOSTTY_API void ghostty_formatter_free(GhosttyFormatter formatter);
200
201/** @} */
202
203#ifdef __cplusplus
204}
205#endif
206
207#endif /* GHOSTTY_VT_FORMATTER_H */
apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/grid_ref.h deleted-212
......@@ -1,212 +0,0 @@
1/**
2 * @file grid_ref.h
3 *
4 * Terminal grid reference type for referencing a resolved position in the
5 * terminal grid.
6 */
7
8#ifndef GHOSTTY_VT_GRID_REF_H
9#define GHOSTTY_VT_GRID_REF_H
10
11#include <stddef.h>
12#include <stdint.h>
13#include <ghostty/vt/types.h>
14#include <ghostty/vt/screen.h>
15#include <ghostty/vt/style.h>
16
17#ifdef __cplusplus
18extern "C" {
19#endif
20
21/** @defgroup grid_ref Grid Reference
22 *
23 * A grid reference is a reference to a specific cell position in the
24 * terminal. Obtain a grid reference from `ghostty_terminal_grid_ref`
25 * for untracked or `ghostty_terminal_grid_ref_track` for tracked. Untracked
26 * vs tracked is explained next.
27 *
28 * Important: The grid reference APIs are not meant to be used as the core of a render
29 * loop. They are not built to sustain the framerates needed for rendering large
30 * screens. Use the render state API for that.
31 *
32 * ## Untracked vs Tracked References
33 *
34 * ### Untracked Reference
35 *
36 * An untracked grid reference is a value type that snapshots a specific
37 * cell. It is only valid until the next update to the terminal instance.
38 * There is no guarantee that it will remain valid after any operation,
39 * even if a seemingly unrelated part of the grid is changed. These are meant
40 * to be read and have their values cached immediately after obtaining it.
41 *
42 * An untracked grid reference has a performance cost in its initial lookup,
43 * but doesn't affect the ongoing performance of the terminal in any way,
44 * since it is a one-time snapshot.
45 *
46 * ### Tracked Reference
47 *
48 * A tracked grid reference follows its cell across normal screen operations.
49 * For example scrolling, scrollback pruning, resize/reflow, and other
50 * terminal mutations update the tracked reference automatically.
51 *
52 * A tracked reference can still lose its original semantic location. This can
53 * happen when the underlying grid is reset, pruned, or otherwise discarded in a
54 * way that cannot be mapped to a meaningful new cell. In that state,
55 * ghostty_tracked_grid_ref_has_value() returns false and
56 * ghostty_tracked_grid_ref_snapshot() / ghostty_tracked_grid_ref_point() return
57 * GHOSTTY_NO_VALUE. The handle remains valid, and callers may move it to a new
58 * point with ghostty_tracked_grid_ref_set().
59 *
60 * To read cell data from a tracked reference, first snapshot it with
61 * ghostty_tracked_grid_ref_snapshot(). The returned `GhosttyGridRef` is again
62 * an untracked reference and follows the same short lifetime rules as any other
63 * untracked grid reference.
64 *
65 * A tracked reference belongs to the terminal screen/page-list that was active
66 * when it was created or last set. Converting it to a point uses that owning
67 * screen/page-list, even if the terminal has since switched between primary and
68 * alternate screens. Calling ghostty_tracked_grid_ref_set() resolves the new
69 * point against the terminal's currently active screen/page-list and may move
70 * the tracked reference between screens.
71 *
72 * Tracked references are owned by the caller and must be freed with
73 * ghostty_tracked_grid_ref_free(). If the terminal that created a tracked
74 * reference is freed first, the handle remains valid only for tracked-grid-ref
75 * APIs: it reports no value and can still be freed.
76 *
77 * Each tracked reference adds bookkeeping to terminal mutations. Use them
78 * sparingly for long-lived anchors such as selections, search state, marks,
79 * or application-side bookmarks.
80 *
81 * ## Lifetime
82 *
83 * An untracked reference is a snapshot. It doesn't need to be freed.
84 * The safety of accessing the value is documented explicitly above: it
85 * is only safe to access any data until the next terminal mutating
86 * operation (including free).
87 *
88 * A tracked reference is allocated and must be freed when it is no
89 * longer needed. A tracked reference may outlive the terminal that created it;
90 * after terminal free, it reports no value and can still be freed.
91 *
92 * ## Examples
93 *
94 * @snippet c-vt-grid-traverse/src/main.c grid-ref-traverse
95 * @snippet c-vt-grid-ref-tracked/src/main.c grid-ref-tracked
96 *
97 * @{
98 */
99
100/**
101 * A resolved reference to a terminal cell position.
102 *
103 * This is a sized struct. Use GHOSTTY_INIT_SIZED() to initialize it.
104 *
105 * @ingroup grid_ref
106 */
107typedef struct {
108 size_t size;
109 void *node;
110 uint16_t x;
111 uint16_t y;
112} GhosttyGridRef;
113
114/**
115 * Get the cell from a grid reference.
116 *
117 * @param ref Pointer to the grid reference
118 * @param[out] out_cell On success, set to the cell at the ref's position (may be NULL)
119 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the ref's
120 * node is NULL
121 *
122 * @ingroup grid_ref
123 */
124GHOSTTY_API GhosttyResult ghostty_grid_ref_cell(const GhosttyGridRef *ref,
125 GhosttyCell *out_cell);
126
127/**
128 * Get the row from a grid reference.
129 *
130 * @param ref Pointer to the grid reference
131 * @param[out] out_row On success, set to the row at the ref's position (may be NULL)
132 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the ref's
133 * node is NULL
134 *
135 * @ingroup grid_ref
136 */
137GHOSTTY_API GhosttyResult ghostty_grid_ref_row(const GhosttyGridRef *ref,
138 GhosttyRow *out_row);
139
140/**
141 * Get the grapheme cluster codepoints for the cell at the grid reference's
142 * position.
143 *
144 * Writes the full grapheme cluster (the cell's primary codepoint followed by
145 * any combining codepoints) into the provided buffer. If the cell has no text,
146 * out_len is set to 0 and GHOSTTY_SUCCESS is returned.
147 *
148 * If the buffer is too small (or NULL), the function returns
149 * GHOSTTY_OUT_OF_SPACE and writes the required number of codepoints to
150 * out_len. The caller can then retry with a sufficiently sized buffer.
151 *
152 * @param ref Pointer to the grid reference
153 * @param buf Output buffer of uint32_t codepoints (may be NULL)
154 * @param buf_len Number of uint32_t elements in the buffer
155 * @param[out] out_len On success, the number of codepoints written. On
156 * GHOSTTY_OUT_OF_SPACE, the required buffer size in codepoints.
157 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the ref's
158 * node is NULL, GHOSTTY_OUT_OF_SPACE if the buffer is too small
159 *
160 * @ingroup grid_ref
161 */
162GHOSTTY_API GhosttyResult ghostty_grid_ref_graphemes(const GhosttyGridRef *ref,
163 uint32_t *buf,
164 size_t buf_len,
165 size_t *out_len);
166
167/**
168 * Get the hyperlink URI for the cell at the grid reference's position.
169 *
170 * Writes the URI bytes into the provided buffer. If the cell has no
171 * hyperlink, out_len is set to 0 and GHOSTTY_SUCCESS is returned.
172 *
173 * If the buffer is too small (or NULL), the function returns
174 * GHOSTTY_OUT_OF_SPACE and writes the required number of bytes to
175 * out_len. The caller can then retry with a sufficiently sized buffer.
176 *
177 * @param ref Pointer to the grid reference
178 * @param buf Output buffer for the URI bytes (may be NULL)
179 * @param buf_len Size of the output buffer in bytes
180 * @param[out] out_len On success, the number of bytes written. On
181 * GHOSTTY_OUT_OF_SPACE, the required buffer size in bytes.
182 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the ref's
183 * node is NULL, GHOSTTY_OUT_OF_SPACE if the buffer is too small
184 *
185 * @ingroup grid_ref
186 */
187GHOSTTY_API GhosttyResult ghostty_grid_ref_hyperlink_uri(
188 const GhosttyGridRef *ref,
189 uint8_t *buf,
190 size_t buf_len,
191 size_t *out_len);
192
193/**
194 * Get the style of the cell at the grid reference's position.
195 *
196 * @param ref Pointer to the grid reference
197 * @param[out] out_style On success, set to the cell's style (may be NULL)
198 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the ref's
199 * node is NULL
200 *
201 * @ingroup grid_ref
202 */
203GHOSTTY_API GhosttyResult ghostty_grid_ref_style(const GhosttyGridRef *ref,
204 GhosttyStyle *out_style);
205
206/** @} */
207
208#ifdef __cplusplus
209}
210#endif
211
212#endif /* GHOSTTY_VT_GRID_REF_H */
apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/grid_ref_tracked.h deleted-139
......@@ -1,139 +0,0 @@
1/**
2 * @file grid_ref_tracked.h
3 *
4 * Tracked terminal grid references.
5 */
6
7#ifndef GHOSTTY_VT_GRID_REF_TRACKED_H
8#define GHOSTTY_VT_GRID_REF_TRACKED_H
9
10#include <stdbool.h>
11#include <ghostty/vt/types.h>
12#include <ghostty/vt/grid_ref.h>
13#include <ghostty/vt/point.h>
14
15#ifdef __cplusplus
16extern "C" {
17#endif
18
19/**
20 * Tracked grid references are owned grid references that move with the
21 * terminal. See @ref grid_ref for the full overview of tracked and untracked
22 * grid reference behavior.
23 *
24 * @ingroup grid_ref
25 */
26
27/**
28 * Free a tracked grid reference.
29 *
30 * Passing NULL is allowed and has no effect. A tracked reference may be freed
31 * after the terminal that created it is freed.
32 *
33 * @param ref Tracked grid reference to free.
34 *
35 * @ingroup grid_ref
36 */
37GHOSTTY_API void ghostty_tracked_grid_ref_free(GhosttyTrackedGridRef ref);
38
39/**
40 * Return whether a tracked grid reference currently has a meaningful value.
41 *
42 * If the terminal that created the tracked reference has been freed, this
43 * returns false.
44 *
45 * @param ref Tracked grid reference.
46 * @return true if the reference currently has a meaningful value.
47 *
48 * @ingroup grid_ref
49 */
50GHOSTTY_API bool ghostty_tracked_grid_ref_has_value(
51 GhosttyTrackedGridRef ref);
52
53/**
54 * Convert a tracked grid reference to a point in the requested coordinate
55 * space.
56 *
57 * This is the tracked equivalent of ghostty_terminal_point_from_grid_ref().
58 * Unlike snapshotting, this does not expose an intermediate untracked
59 * GhosttyGridRef.
60 *
61 * A tracked reference is resolved against the terminal screen/page-list that
62 * currently owns the reference. If the terminal has switched between primary
63 * and alternate screens since the reference was created or last set, this may
64 * be different from the terminal's currently active screen.
65 *
66 * If the tracked reference no longer has a meaningful value, this returns
67 * GHOSTTY_NO_VALUE. GHOSTTY_NO_VALUE is also returned when the reference cannot
68 * be represented in the requested coordinate space, including after the
69 * terminal that created the tracked reference has been freed.
70 *
71 * @param ref Tracked grid reference.
72 * @param tag Coordinate space to convert into.
73 * @param[out] out_point On success, receives the coordinate. May be NULL.
74 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if ref is invalid,
75 * or GHOSTTY_NO_VALUE if there is no representable value.
76 *
77 * @ingroup grid_ref
78 */
79GHOSTTY_API GhosttyResult ghostty_tracked_grid_ref_point(
80 GhosttyTrackedGridRef ref,
81 GhosttyPointTag tag,
82 GhosttyPointCoordinate *out_point);
83
84/**
85 * Move an existing tracked grid reference to a new terminal point.
86 *
87 * On success, the tracked reference begins tracking the new point and any prior
88 * "no value" state is cleared. On GHOSTTY_OUT_OF_MEMORY, the original tracked
89 * reference is left unchanged.
90 *
91 * The terminal must be the same terminal that created the tracked reference.
92 * The point is resolved against the terminal screen/page-list that is active at
93 * the time this function is called. If the terminal has switched between
94 * primary and alternate screens, this may move the tracked reference from one
95 * screen/page-list to the other.
96 *
97 * @param ref Tracked grid reference.
98 * @param terminal Terminal instance that owns the reference.
99 * @param point New point to track.
100 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if ref, terminal,
101 * or point is invalid, or GHOSTTY_OUT_OF_MEMORY if allocation fails.
102 *
103 * @ingroup grid_ref
104 */
105GHOSTTY_API GhosttyResult ghostty_tracked_grid_ref_set(
106 GhosttyTrackedGridRef ref,
107 GhosttyTerminal terminal,
108 GhosttyPoint point);
109
110/**
111 * Snapshot a tracked grid reference into a regular GhosttyGridRef.
112 *
113 * The returned GhosttyGridRef is an untracked snapshot and has the same
114 * lifetime rules as ghostty_terminal_grid_ref(): it is only valid until the
115 * next terminal update. Snapshot immediately before calling
116 * ghostty_grid_ref_cell(), ghostty_grid_ref_row(),
117 * ghostty_grid_ref_graphemes(), ghostty_grid_ref_hyperlink_uri(), or
118 * ghostty_grid_ref_style().
119 *
120 * If the tracked reference no longer has a meaningful value, this returns
121 * GHOSTTY_NO_VALUE. This includes references whose owning terminal has been
122 * freed.
123 *
124 * @param ref Tracked grid reference.
125 * @param[out] out_ref On success, receives an untracked snapshot. May be NULL.
126 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if ref is invalid,
127 * or GHOSTTY_NO_VALUE if the tracked location was discarded.
128 *
129 * @ingroup grid_ref
130 */
131GHOSTTY_API GhosttyResult ghostty_tracked_grid_ref_snapshot(
132 GhosttyTrackedGridRef ref,
133 GhosttyGridRef *out_ref);
134
135#ifdef __cplusplus
136}
137#endif
138
139#endif /* GHOSTTY_VT_GRID_REF_TRACKED_H */
apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/key.h deleted-73
......@@ -1,73 +0,0 @@
1/**
2 * @file key.h
3 *
4 * Key encoding module - encode key events into terminal escape sequences.
5 */
6
7#ifndef GHOSTTY_VT_KEY_H
8#define GHOSTTY_VT_KEY_H
9
10/** @defgroup key Key Encoding
11 *
12 * Utilities for encoding key events into terminal escape sequences,
13 * supporting both legacy encoding as well as Kitty Keyboard Protocol.
14 *
15 * ## Basic Usage
16 *
17 * 1. Create an encoder instance with ghostty_key_encoder_new()
18 * 2. Configure encoder options with ghostty_key_encoder_setopt()
19 * or ghostty_key_encoder_setopt_from_terminal() if you have a
20 * GhosttyTerminal.
21 * 3. For each key event:
22 * - Create a key event with ghostty_key_event_new()
23 * - Set event properties (action, key, modifiers, etc.)
24 * - Encode with ghostty_key_encoder_encode()
25 * - Free the event with ghostty_key_event_free()
26 * - Note: You can also reuse the same key event multiple times by
27 * changing its properties.
28 * 4. Free the encoder with ghostty_key_encoder_free() when done
29 *
30 * For a complete working example, see example/c-vt-encode-key in the
31 * repository.
32 *
33 * ## Example
34 *
35 * @snippet c-vt-encode-key/src/main.c key-encode
36 *
37 * ## Example: Encoding with Terminal State
38 *
39 * When you have a GhosttyTerminal, you can sync its modes (cursor key
40 * application, Kitty flags, etc.) into the encoder automatically:
41 *
42 * @code{.c}
43 * // Create a terminal and feed it some VT data that changes modes
44 * GhosttyTerminal terminal;
45 * ghostty_terminal_new(NULL, &terminal,
46 * (GhosttyTerminalOptions){.cols = 80, .rows = 24, .max_scrollback = 0});
47 *
48 * // Application might write data that enables Kitty keyboard protocol, etc.
49 * ghostty_terminal_vt_write(terminal, vt_data, vt_len);
50 *
51 * // Create an encoder and sync its options from the terminal
52 * GhosttyKeyEncoder encoder;
53 * ghostty_key_encoder_new(NULL, &encoder);
54 * ghostty_key_encoder_setopt_from_terminal(encoder, terminal);
55 *
56 * // Encode a key event using the terminal-derived options
57 * char buf[128];
58 * size_t written = 0;
59 * ghostty_key_encoder_encode(encoder, event, buf, sizeof(buf), &written);
60 *
61 * ghostty_key_encoder_free(encoder);
62 * ghostty_terminal_free(terminal);
63 * @endcode
64 *
65 * @{
66 */
67
68#include <ghostty/vt/key/event.h>
69#include <ghostty/vt/key/encoder.h>
70
71/** @} */
72
73#endif /* GHOSTTY_VT_KEY_H */
apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/key/encoder.h deleted-255
......@@ -1,255 +0,0 @@
1/**
2 * @file encoder.h
3 *
4 * Key event encoding to terminal escape sequences.
5 */
6
7#ifndef GHOSTTY_VT_KEY_ENCODER_H
8#define GHOSTTY_VT_KEY_ENCODER_H
9
10#include <stddef.h>
11#include <stdint.h>
12#include <ghostty/vt/types.h>
13#include <ghostty/vt/allocator.h>
14#include <ghostty/vt/terminal.h>
15#include <ghostty/vt/key/event.h>
16
17/**
18 * Opaque handle to a key encoder instance.
19 *
20 * This handle represents a key encoder that converts key events into terminal
21 * escape sequences.
22 *
23 * @ingroup key
24 */
25typedef struct GhosttyKeyEncoderImpl *GhosttyKeyEncoder;
26
27/**
28 * Kitty keyboard protocol flags.
29 *
30 * Bitflags representing the various modes of the Kitty keyboard protocol.
31 * These can be combined using bitwise OR operations. Valid values all
32 * start with `GHOSTTY_KITTY_KEY_`.
33 *
34 * @ingroup key
35 */
36typedef uint8_t GhosttyKittyKeyFlags;
37
38/** Kitty keyboard protocol disabled (all flags off) */
39#define GHOSTTY_KITTY_KEY_DISABLED 0
40
41/** Disambiguate escape codes */
42#define GHOSTTY_KITTY_KEY_DISAMBIGUATE (1 << 0)
43
44/** Report key press and release events */
45#define GHOSTTY_KITTY_KEY_REPORT_EVENTS (1 << 1)
46
47/** Report alternate key codes */
48#define GHOSTTY_KITTY_KEY_REPORT_ALTERNATES (1 << 2)
49
50/** Report all key events including those normally handled by the terminal */
51#define GHOSTTY_KITTY_KEY_REPORT_ALL (1 << 3)
52
53/** Report associated text with key events */
54#define GHOSTTY_KITTY_KEY_REPORT_ASSOCIATED (1 << 4)
55
56/** All Kitty keyboard protocol flags enabled */
57#define GHOSTTY_KITTY_KEY_ALL (GHOSTTY_KITTY_KEY_DISAMBIGUATE | GHOSTTY_KITTY_KEY_REPORT_EVENTS | GHOSTTY_KITTY_KEY_REPORT_ALTERNATES | GHOSTTY_KITTY_KEY_REPORT_ALL | GHOSTTY_KITTY_KEY_REPORT_ASSOCIATED)
58
59/**
60 * macOS option key behavior.
61 *
62 * Determines whether the "option" key on macOS is treated as "alt" or not.
63 * See the Ghostty `macos-option-as-alt` configuration option for more details.
64 *
65 * @ingroup key
66 */
67typedef enum GHOSTTY_ENUM_TYPED {
68 /** Option key is not treated as alt */
69 GHOSTTY_OPTION_AS_ALT_FALSE = 0,
70 /** Option key is treated as alt */
71 GHOSTTY_OPTION_AS_ALT_TRUE = 1,
72 /** Only left option key is treated as alt */
73 GHOSTTY_OPTION_AS_ALT_LEFT = 2,
74 /** Only right option key is treated as alt */
75 GHOSTTY_OPTION_AS_ALT_RIGHT = 3,
76 GHOSTTY_OPTION_AS_ALT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
77} GhosttyOptionAsAlt;
78
79/**
80 * Key encoder option identifiers.
81 *
82 * These values are used with ghostty_key_encoder_setopt() to configure
83 * the behavior of the key encoder.
84 *
85 * @ingroup key
86 */
87typedef enum GHOSTTY_ENUM_TYPED {
88 /** Terminal DEC mode 1: cursor key application mode (value: bool) */
89 GHOSTTY_KEY_ENCODER_OPT_CURSOR_KEY_APPLICATION = 0,
90
91 /** Terminal DEC mode 66: keypad key application mode (value: bool) */
92 GHOSTTY_KEY_ENCODER_OPT_KEYPAD_KEY_APPLICATION = 1,
93
94 /** Terminal DEC mode 1035: ignore keypad with numlock (value: bool) */
95 GHOSTTY_KEY_ENCODER_OPT_IGNORE_KEYPAD_WITH_NUMLOCK = 2,
96
97 /** Terminal DEC mode 1036: alt sends escape prefix (value: bool) */
98 GHOSTTY_KEY_ENCODER_OPT_ALT_ESC_PREFIX = 3,
99
100 /** xterm modifyOtherKeys mode 2 (value: bool) */
101 GHOSTTY_KEY_ENCODER_OPT_MODIFY_OTHER_KEYS_STATE_2 = 4,
102
103 /** Kitty keyboard protocol flags (value: GhosttyKittyKeyFlags bitmask) */
104 GHOSTTY_KEY_ENCODER_OPT_KITTY_FLAGS = 5,
105
106 /** macOS option-as-alt setting (value: GhosttyOptionAsAlt) */
107 GHOSTTY_KEY_ENCODER_OPT_MACOS_OPTION_AS_ALT = 6,
108
109 /** Backarrow key mode (value: bool)
110 * See https://vt100.net/dec/ek-vt3xx-tp-002.pdf page 170
111 * If `false` (the default), `backspace` emits 0x7f
112 * If `true`, `backspace` emits 0x08
113 */
114 GHOSTTY_KEY_ENCODER_OPT_BACKARROW_KEY_MODE = 7,
115
116 GHOSTTY_KEY_ENCODER_OPT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
117} GhosttyKeyEncoderOption;
118
119/**
120 * Create a new key encoder instance.
121 *
122 * Creates a new key encoder with default options. The encoder can be configured
123 * using ghostty_key_encoder_setopt() and must be freed using
124 * ghostty_key_encoder_free() when no longer needed.
125 *
126 * @param allocator Pointer to the allocator to use for memory management, or NULL to use the default allocator
127 * @param encoder Pointer to store the created encoder handle
128 * @return GHOSTTY_SUCCESS on success, or an error code on failure
129 *
130 * @ingroup key
131 */
132GHOSTTY_API GhosttyResult ghostty_key_encoder_new(const GhosttyAllocator *allocator, GhosttyKeyEncoder *encoder);
133
134/**
135 * Free a key encoder instance.
136 *
137 * Releases all resources associated with the key encoder. After this call,
138 * the encoder handle becomes invalid and must not be used.
139 *
140 * @param encoder The encoder handle to free (may be NULL)
141 *
142 * @ingroup key
143 */
144GHOSTTY_API void ghostty_key_encoder_free(GhosttyKeyEncoder encoder);
145
146/**
147 * Set an option on the key encoder.
148 *
149 * Configures the behavior of the key encoder. Options control various aspects
150 * of encoding such as terminal modes (cursor key application mode, keypad mode),
151 * protocol selection (Kitty keyboard protocol flags), and platform-specific
152 * behaviors (macOS option-as-alt).
153 *
154 * If you are using a terminal instance, you can set the key encoding
155 * options based on the active terminal state (e.g. legacy vs Kitty mode
156 * and associated flags) with ghostty_key_encoder_setopt_from_terminal().
157 *
158 * A null pointer value does nothing. It does not reset the value to the
159 * default. The setopt call will do nothing.
160 *
161 * @param encoder The encoder handle, must not be NULL
162 * @param option The option to set
163 * @param value Pointer to the value to set (type depends on the option)
164 *
165 * @ingroup key
166 */
167GHOSTTY_API void ghostty_key_encoder_setopt(GhosttyKeyEncoder encoder, GhosttyKeyEncoderOption option, const void *value);
168
169/**
170 * Set encoder options from a terminal's current state.
171 *
172 * Reads the terminal's current modes and flags and applies them to the
173 * encoder's options. This sets cursor key application mode, keypad mode,
174 * alt escape prefix, modifyOtherKeys state, and Kitty keyboard protocol
175 * flags from the terminal state.
176 *
177 * Note that the `macos_option_as_alt` option cannot be determined from
178 * terminal state and is reset to `GHOSTTY_OPTION_AS_ALT_FALSE` by this
179 * call. Use ghostty_key_encoder_setopt() to set it afterward if needed.
180 *
181 * @param encoder The encoder handle, must not be NULL
182 * @param terminal The terminal handle, must not be NULL
183 *
184 * @ingroup key
185 */
186GHOSTTY_API void ghostty_key_encoder_setopt_from_terminal(GhosttyKeyEncoder encoder, GhosttyTerminal terminal);
187
188/**
189 * Encode a key event into a terminal escape sequence.
190 *
191 * Converts a key event into the appropriate terminal escape sequence based on
192 * the encoder's current options. The sequence is written to the provided buffer.
193 *
194 * Not all key events produce output. For example, unmodified modifier keys
195 * typically don't generate escape sequences. Check the out_len parameter to
196 * determine if any data was written.
197 *
198 * If the output buffer is too small, this function returns GHOSTTY_OUT_OF_SPACE
199 * and out_len will contain the required buffer size. The caller can then
200 * allocate a larger buffer and call the function again.
201 *
202 * @param encoder The encoder handle, must not be NULL
203 * @param event The key event to encode, must not be NULL
204 * @param out_buf Buffer to write the encoded sequence to
205 * @param out_buf_size Size of the output buffer in bytes
206 * @param out_len Pointer to store the number of bytes written (may be NULL)
207 * @return GHOSTTY_SUCCESS on success, GHOSTTY_OUT_OF_SPACE if buffer too small, or other error code
208 *
209 * ## Example: Calculate required buffer size
210 *
211 * @code{.c}
212 * // Query the required size with a NULL buffer (always returns OUT_OF_SPACE)
213 * size_t required = 0;
214 * GhosttyResult result = ghostty_key_encoder_encode(encoder, event, NULL, 0, &required);
215 * assert(result == GHOSTTY_OUT_OF_SPACE);
216 *
217 * // Allocate buffer of required size
218 * char *buf = malloc(required);
219 *
220 * // Encode with properly sized buffer
221 * size_t written = 0;
222 * result = ghostty_key_encoder_encode(encoder, event, buf, required, &written);
223 * assert(result == GHOSTTY_SUCCESS);
224 *
225 * // Use the encoded sequence...
226 *
227 * free(buf);
228 * @endcode
229 *
230 * ## Example: Direct encoding with static buffer
231 *
232 * @code{.c}
233 * // Most escape sequences are short, so a static buffer often suffices
234 * char buf[128];
235 * size_t written = 0;
236 * GhosttyResult result = ghostty_key_encoder_encode(encoder, event, buf, sizeof(buf), &written);
237 *
238 * if (result == GHOSTTY_SUCCESS) {
239 * // Write the encoded sequence to the terminal
240 * write(pty_fd, buf, written);
241 * } else if (result == GHOSTTY_OUT_OF_SPACE) {
242 * // Buffer too small, written contains required size
243 * char *dynamic_buf = malloc(written);
244 * result = ghostty_key_encoder_encode(encoder, event, dynamic_buf, written, &written);
245 * assert(result == GHOSTTY_SUCCESS);
246 * write(pty_fd, dynamic_buf, written);
247 * free(dynamic_buf);
248 * }
249 * @endcode
250 *
251 * @ingroup key
252 */
253GHOSTTY_API GhosttyResult ghostty_key_encoder_encode(GhosttyKeyEncoder encoder, GhosttyKeyEvent event, char *out_buf, size_t out_buf_size, size_t *out_len);
254
255#endif /* GHOSTTY_VT_KEY_ENCODER_H */
apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/key/event.h deleted-482
......@@ -1,482 +0,0 @@
1/**
2 * @file event.h
3 *
4 * Key event representation and manipulation.
5 */
6
7#ifndef GHOSTTY_VT_KEY_EVENT_H
8#define GHOSTTY_VT_KEY_EVENT_H
9
10#include <stdbool.h>
11#include <stddef.h>
12#include <stdint.h>
13#include <ghostty/vt/types.h>
14#include <ghostty/vt/allocator.h>
15
16/**
17 * Opaque handle to a key event.
18 *
19 * This handle represents a keyboard input event containing information about
20 * the physical key pressed, modifiers, and generated text.
21 *
22 * @ingroup key
23 */
24typedef struct GhosttyKeyEventImpl *GhosttyKeyEvent;
25
26/**
27 * Keyboard input event types.
28 *
29 * @ingroup key
30 */
31typedef enum GHOSTTY_ENUM_TYPED {
32 /** Key was released */
33 GHOSTTY_KEY_ACTION_RELEASE = 0,
34 /** Key was pressed */
35 GHOSTTY_KEY_ACTION_PRESS = 1,
36 /** Key is being repeated (held down) */
37 GHOSTTY_KEY_ACTION_REPEAT = 2,
38 GHOSTTY_KEY_ACTION_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
39} GhosttyKeyAction;
40
41/**
42 * Keyboard modifier keys bitmask.
43 *
44 * A bitmask representing all keyboard modifiers. This tracks which modifier keys
45 * are pressed and, where supported by the platform, which side (left or right)
46 * of each modifier is active.
47 *
48 * Use the GHOSTTY_MODS_* constants to test and set individual modifiers.
49 *
50 * Modifier side bits are only meaningful when the corresponding modifier bit is set.
51 * Not all platforms support distinguishing between left and right modifier
52 * keys and Ghostty is built to expect that some platforms may not provide this
53 * information.
54 *
55 * @ingroup key
56 */
57typedef uint16_t GhosttyMods;
58
59/** Shift key is pressed */
60#define GHOSTTY_MODS_SHIFT (1 << 0)
61/** Control key is pressed */
62#define GHOSTTY_MODS_CTRL (1 << 1)
63/** Alt/Option key is pressed */
64#define GHOSTTY_MODS_ALT (1 << 2)
65/** Super/Command/Windows key is pressed */
66#define GHOSTTY_MODS_SUPER (1 << 3)
67/** Caps Lock is active */
68#define GHOSTTY_MODS_CAPS_LOCK (1 << 4)
69/** Num Lock is active */
70#define GHOSTTY_MODS_NUM_LOCK (1 << 5)
71
72/**
73 * Right shift is pressed (0 = left, 1 = right).
74 * Only meaningful when GHOSTTY_MODS_SHIFT is set.
75 */
76#define GHOSTTY_MODS_SHIFT_SIDE (1 << 6)
77/**
78 * Right ctrl is pressed (0 = left, 1 = right).
79 * Only meaningful when GHOSTTY_MODS_CTRL is set.
80 */
81#define GHOSTTY_MODS_CTRL_SIDE (1 << 7)
82/**
83 * Right alt is pressed (0 = left, 1 = right).
84 * Only meaningful when GHOSTTY_MODS_ALT is set.
85 */
86#define GHOSTTY_MODS_ALT_SIDE (1 << 8)
87/**
88 * Right super is pressed (0 = left, 1 = right).
89 * Only meaningful when GHOSTTY_MODS_SUPER is set.
90 */
91#define GHOSTTY_MODS_SUPER_SIDE (1 << 9)
92
93/**
94 * Physical key codes.
95 *
96 * The set of key codes that Ghostty is aware of. These represent physical keys
97 * on the keyboard and are layout-independent. For example, the "a" key on a US
98 * keyboard is the same as the "ф" key on a Russian keyboard, but both will
99 * report the same key_a value.
100 *
101 * Layout-dependent strings are provided separately as UTF-8 text and are produced
102 * by the platform. These values are based on the W3C UI Events KeyboardEvent code
103 * standard. See: https://www.w3.org/TR/uievents-code
104 *
105 * @ingroup key
106 */
107typedef enum GHOSTTY_ENUM_TYPED {
108 GHOSTTY_KEY_UNIDENTIFIED = 0,
109
110 // Writing System Keys (W3C § 3.1.1)
111 GHOSTTY_KEY_BACKQUOTE,
112 GHOSTTY_KEY_BACKSLASH,
113 GHOSTTY_KEY_BRACKET_LEFT,
114 GHOSTTY_KEY_BRACKET_RIGHT,
115 GHOSTTY_KEY_COMMA,
116 GHOSTTY_KEY_DIGIT_0,
117 GHOSTTY_KEY_DIGIT_1,
118 GHOSTTY_KEY_DIGIT_2,
119 GHOSTTY_KEY_DIGIT_3,
120 GHOSTTY_KEY_DIGIT_4,
121 GHOSTTY_KEY_DIGIT_5,
122 GHOSTTY_KEY_DIGIT_6,
123 GHOSTTY_KEY_DIGIT_7,
124 GHOSTTY_KEY_DIGIT_8,
125 GHOSTTY_KEY_DIGIT_9,
126 GHOSTTY_KEY_EQUAL,
127 GHOSTTY_KEY_INTL_BACKSLASH,
128 GHOSTTY_KEY_INTL_RO,
129 GHOSTTY_KEY_INTL_YEN,
130 GHOSTTY_KEY_A,
131 GHOSTTY_KEY_B,
132 GHOSTTY_KEY_C,
133 GHOSTTY_KEY_D,
134 GHOSTTY_KEY_E,
135 GHOSTTY_KEY_F,
136 GHOSTTY_KEY_G,
137 GHOSTTY_KEY_H,
138 GHOSTTY_KEY_I,
139 GHOSTTY_KEY_J,
140 GHOSTTY_KEY_K,
141 GHOSTTY_KEY_L,
142 GHOSTTY_KEY_M,
143 GHOSTTY_KEY_N,
144 GHOSTTY_KEY_O,
145 GHOSTTY_KEY_P,
146 GHOSTTY_KEY_Q,
147 GHOSTTY_KEY_R,
148 GHOSTTY_KEY_S,
149 GHOSTTY_KEY_T,
150 GHOSTTY_KEY_U,
151 GHOSTTY_KEY_V,
152 GHOSTTY_KEY_W,
153 GHOSTTY_KEY_X,
154 GHOSTTY_KEY_Y,
155 GHOSTTY_KEY_Z,
156 GHOSTTY_KEY_MINUS,
157 GHOSTTY_KEY_PERIOD,
158 GHOSTTY_KEY_QUOTE,
159 GHOSTTY_KEY_SEMICOLON,
160 GHOSTTY_KEY_SLASH,
161
162 // Functional Keys (W3C § 3.1.2)
163 GHOSTTY_KEY_ALT_LEFT,
164 GHOSTTY_KEY_ALT_RIGHT,
165 GHOSTTY_KEY_BACKSPACE,
166 GHOSTTY_KEY_CAPS_LOCK,
167 GHOSTTY_KEY_CONTEXT_MENU,
168 GHOSTTY_KEY_CONTROL_LEFT,
169 GHOSTTY_KEY_CONTROL_RIGHT,
170 GHOSTTY_KEY_ENTER,
171 GHOSTTY_KEY_META_LEFT,
172 GHOSTTY_KEY_META_RIGHT,
173 GHOSTTY_KEY_SHIFT_LEFT,
174 GHOSTTY_KEY_SHIFT_RIGHT,
175 GHOSTTY_KEY_SPACE,
176 GHOSTTY_KEY_TAB,
177 GHOSTTY_KEY_CONVERT,
178 GHOSTTY_KEY_KANA_MODE,
179 GHOSTTY_KEY_NON_CONVERT,
180
181 // Control Pad Section (W3C § 3.2)
182 GHOSTTY_KEY_DELETE,
183 GHOSTTY_KEY_END,
184 GHOSTTY_KEY_HELP,
185 GHOSTTY_KEY_HOME,
186 GHOSTTY_KEY_INSERT,
187 GHOSTTY_KEY_PAGE_DOWN,
188 GHOSTTY_KEY_PAGE_UP,
189
190 // Arrow Pad Section (W3C § 3.3)
191 GHOSTTY_KEY_ARROW_DOWN,
192 GHOSTTY_KEY_ARROW_LEFT,
193 GHOSTTY_KEY_ARROW_RIGHT,
194 GHOSTTY_KEY_ARROW_UP,
195
196 // Numpad Section (W3C § 3.4)
197 GHOSTTY_KEY_NUM_LOCK,
198 GHOSTTY_KEY_NUMPAD_0,
199 GHOSTTY_KEY_NUMPAD_1,
200 GHOSTTY_KEY_NUMPAD_2,
201 GHOSTTY_KEY_NUMPAD_3,
202 GHOSTTY_KEY_NUMPAD_4,
203 GHOSTTY_KEY_NUMPAD_5,
204 GHOSTTY_KEY_NUMPAD_6,
205 GHOSTTY_KEY_NUMPAD_7,
206 GHOSTTY_KEY_NUMPAD_8,
207 GHOSTTY_KEY_NUMPAD_9,
208 GHOSTTY_KEY_NUMPAD_ADD,
209 GHOSTTY_KEY_NUMPAD_BACKSPACE,
210 GHOSTTY_KEY_NUMPAD_CLEAR,
211 GHOSTTY_KEY_NUMPAD_CLEAR_ENTRY,
212 GHOSTTY_KEY_NUMPAD_COMMA,
213 GHOSTTY_KEY_NUMPAD_DECIMAL,
214 GHOSTTY_KEY_NUMPAD_DIVIDE,
215 GHOSTTY_KEY_NUMPAD_ENTER,
216 GHOSTTY_KEY_NUMPAD_EQUAL,
217 GHOSTTY_KEY_NUMPAD_MEMORY_ADD,
218 GHOSTTY_KEY_NUMPAD_MEMORY_CLEAR,
219 GHOSTTY_KEY_NUMPAD_MEMORY_RECALL,
220 GHOSTTY_KEY_NUMPAD_MEMORY_STORE,
221 GHOSTTY_KEY_NUMPAD_MEMORY_SUBTRACT,
222 GHOSTTY_KEY_NUMPAD_MULTIPLY,
223 GHOSTTY_KEY_NUMPAD_PAREN_LEFT,
224 GHOSTTY_KEY_NUMPAD_PAREN_RIGHT,
225 GHOSTTY_KEY_NUMPAD_SUBTRACT,
226 GHOSTTY_KEY_NUMPAD_SEPARATOR,
227 GHOSTTY_KEY_NUMPAD_UP,
228 GHOSTTY_KEY_NUMPAD_DOWN,
229 GHOSTTY_KEY_NUMPAD_RIGHT,
230 GHOSTTY_KEY_NUMPAD_LEFT,
231 GHOSTTY_KEY_NUMPAD_BEGIN,
232 GHOSTTY_KEY_NUMPAD_HOME,
233 GHOSTTY_KEY_NUMPAD_END,
234 GHOSTTY_KEY_NUMPAD_INSERT,
235 GHOSTTY_KEY_NUMPAD_DELETE,
236 GHOSTTY_KEY_NUMPAD_PAGE_UP,
237 GHOSTTY_KEY_NUMPAD_PAGE_DOWN,
238
239 // Function Section (W3C § 3.5)
240 GHOSTTY_KEY_ESCAPE,
241 GHOSTTY_KEY_F1,
242 GHOSTTY_KEY_F2,
243 GHOSTTY_KEY_F3,
244 GHOSTTY_KEY_F4,
245 GHOSTTY_KEY_F5,
246 GHOSTTY_KEY_F6,
247 GHOSTTY_KEY_F7,
248 GHOSTTY_KEY_F8,
249 GHOSTTY_KEY_F9,
250 GHOSTTY_KEY_F10,
251 GHOSTTY_KEY_F11,
252 GHOSTTY_KEY_F12,
253 GHOSTTY_KEY_F13,
254 GHOSTTY_KEY_F14,
255 GHOSTTY_KEY_F15,
256 GHOSTTY_KEY_F16,
257 GHOSTTY_KEY_F17,
258 GHOSTTY_KEY_F18,
259 GHOSTTY_KEY_F19,
260 GHOSTTY_KEY_F20,
261 GHOSTTY_KEY_F21,
262 GHOSTTY_KEY_F22,
263 GHOSTTY_KEY_F23,
264 GHOSTTY_KEY_F24,
265 GHOSTTY_KEY_F25,
266 GHOSTTY_KEY_FN,
267 GHOSTTY_KEY_FN_LOCK,
268 GHOSTTY_KEY_PRINT_SCREEN,
269 GHOSTTY_KEY_SCROLL_LOCK,
270 GHOSTTY_KEY_PAUSE,
271
272 // Media Keys (W3C § 3.6)
273 GHOSTTY_KEY_BROWSER_BACK,
274 GHOSTTY_KEY_BROWSER_FAVORITES,
275 GHOSTTY_KEY_BROWSER_FORWARD,
276 GHOSTTY_KEY_BROWSER_HOME,
277 GHOSTTY_KEY_BROWSER_REFRESH,
278 GHOSTTY_KEY_BROWSER_SEARCH,
279 GHOSTTY_KEY_BROWSER_STOP,
280 GHOSTTY_KEY_EJECT,
281 GHOSTTY_KEY_LAUNCH_APP_1,
282 GHOSTTY_KEY_LAUNCH_APP_2,
283 GHOSTTY_KEY_LAUNCH_MAIL,
284 GHOSTTY_KEY_MEDIA_PLAY_PAUSE,
285 GHOSTTY_KEY_MEDIA_SELECT,
286 GHOSTTY_KEY_MEDIA_STOP,
287 GHOSTTY_KEY_MEDIA_TRACK_NEXT,
288 GHOSTTY_KEY_MEDIA_TRACK_PREVIOUS,
289 GHOSTTY_KEY_POWER,
290 GHOSTTY_KEY_SLEEP,
291 GHOSTTY_KEY_AUDIO_VOLUME_DOWN,
292 GHOSTTY_KEY_AUDIO_VOLUME_MUTE,
293 GHOSTTY_KEY_AUDIO_VOLUME_UP,
294 GHOSTTY_KEY_WAKE_UP,
295
296 // Legacy, Non-standard, and Special Keys (W3C § 3.7)
297 GHOSTTY_KEY_COPY,
298 GHOSTTY_KEY_CUT,
299 GHOSTTY_KEY_PASTE,
300 GHOSTTY_KEY_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
301} GhosttyKey;
302
303/**
304 * Create a new key event instance.
305 *
306 * Creates a new key event with default values. The event must be freed using
307 * ghostty_key_event_free() when no longer needed.
308 *
309 * @param allocator Pointer to the allocator to use for memory management, or NULL to use the default allocator
310 * @param event Pointer to store the created key event handle
311 * @return GHOSTTY_SUCCESS on success, or an error code on failure
312 *
313 * @ingroup key
314 */
315GHOSTTY_API GhosttyResult ghostty_key_event_new(const GhosttyAllocator *allocator, GhosttyKeyEvent *event);
316
317/**
318 * Free a key event instance.
319 *
320 * Releases all resources associated with the key event. After this call,
321 * the event handle becomes invalid and must not be used.
322 *
323 * @param event The key event handle to free (may be NULL)
324 *
325 * @ingroup key
326 */
327GHOSTTY_API void ghostty_key_event_free(GhosttyKeyEvent event);
328
329/**
330 * Set the key action (press, release, repeat).
331 *
332 * @param event The key event handle, must not be NULL
333 * @param action The action to set
334 *
335 * @ingroup key
336 */
337GHOSTTY_API void ghostty_key_event_set_action(GhosttyKeyEvent event, GhosttyKeyAction action);
338
339/**
340 * Get the key action (press, release, repeat).
341 *
342 * @param event The key event handle, must not be NULL
343 * @return The key action
344 *
345 * @ingroup key
346 */
347GHOSTTY_API GhosttyKeyAction ghostty_key_event_get_action(GhosttyKeyEvent event);
348
349/**
350 * Set the physical key code.
351 *
352 * @param event The key event handle, must not be NULL
353 * @param key The physical key code to set
354 *
355 * @ingroup key
356 */
357GHOSTTY_API void ghostty_key_event_set_key(GhosttyKeyEvent event, GhosttyKey key);
358
359/**
360 * Get the physical key code.
361 *
362 * @param event The key event handle, must not be NULL
363 * @return The physical key code
364 *
365 * @ingroup key
366 */
367GHOSTTY_API GhosttyKey ghostty_key_event_get_key(GhosttyKeyEvent event);
368
369/**
370 * Set the modifier keys bitmask.
371 *
372 * @param event The key event handle, must not be NULL
373 * @param mods The modifier keys bitmask to set
374 *
375 * @ingroup key
376 */
377GHOSTTY_API void ghostty_key_event_set_mods(GhosttyKeyEvent event, GhosttyMods mods);
378
379/**
380 * Get the modifier keys bitmask.
381 *
382 * @param event The key event handle, must not be NULL
383 * @return The modifier keys bitmask
384 *
385 * @ingroup key
386 */
387GHOSTTY_API GhosttyMods ghostty_key_event_get_mods(GhosttyKeyEvent event);
388
389/**
390 * Set the consumed modifiers bitmask.
391 *
392 * @param event The key event handle, must not be NULL
393 * @param consumed_mods The consumed modifiers bitmask to set
394 *
395 * @ingroup key
396 */
397GHOSTTY_API void ghostty_key_event_set_consumed_mods(GhosttyKeyEvent event, GhosttyMods consumed_mods);
398
399/**
400 * Get the consumed modifiers bitmask.
401 *
402 * @param event The key event handle, must not be NULL
403 * @return The consumed modifiers bitmask
404 *
405 * @ingroup key
406 */
407GHOSTTY_API GhosttyMods ghostty_key_event_get_consumed_mods(GhosttyKeyEvent event);
408
409/**
410 * Set whether the key event is part of a composition sequence.
411 *
412 * @param event The key event handle, must not be NULL
413 * @param composing Whether the key event is part of a composition sequence
414 *
415 * @ingroup key
416 */
417GHOSTTY_API void ghostty_key_event_set_composing(GhosttyKeyEvent event, bool composing);
418
419/**
420 * Get whether the key event is part of a composition sequence.
421 *
422 * @param event The key event handle, must not be NULL
423 * @return Whether the key event is part of a composition sequence
424 *
425 * @ingroup key
426 */
427GHOSTTY_API bool ghostty_key_event_get_composing(GhosttyKeyEvent event);
428
429/**
430 * Set the UTF-8 text generated by the key for the current keyboard layout.
431 *
432 * Must contain the unmodified character before any Ctrl/Meta transformations.
433 * The encoder derives modifier sequences from the logical key and mods
434 * bitmask, not from this text. Do not pass C0 control characters
435 * (U+0000-U+001F, U+007F) or platform function key codes (e.g. macOS PUA
436 * U+F700-U+F8FF); pass NULL instead and let the encoder use the logical key.
437 *
438 * The key event does NOT take ownership of the text pointer. The caller
439 * must ensure the string remains valid for the lifetime needed by the event.
440 *
441 * @param event The key event handle, must not be NULL
442 * @param utf8 The UTF-8 text to set (or NULL for empty)
443 * @param len Length of the UTF-8 text in bytes
444 *
445 * @ingroup key
446 */
447GHOSTTY_API void ghostty_key_event_set_utf8(GhosttyKeyEvent event, const char *utf8, size_t len);
448
449/**
450 * Get the UTF-8 text generated by the key event.
451 *
452 * The returned pointer is valid until the event is freed or the UTF-8 text is modified.
453 *
454 * @param event The key event handle, must not be NULL
455 * @param len Pointer to store the length of the UTF-8 text in bytes (may be NULL)
456 * @return The UTF-8 text (or NULL for empty)
457 *
458 * @ingroup key
459 */
460GHOSTTY_API const char *ghostty_key_event_get_utf8(GhosttyKeyEvent event, size_t *len);
461
462/**
463 * Set the unshifted Unicode codepoint.
464 *
465 * @param event The key event handle, must not be NULL
466 * @param codepoint The unshifted Unicode codepoint to set
467 *
468 * @ingroup key
469 */
470GHOSTTY_API void ghostty_key_event_set_unshifted_codepoint(GhosttyKeyEvent event, uint32_t codepoint);
471
472/**
473 * Get the unshifted Unicode codepoint.
474 *
475 * @param event The key event handle, must not be NULL
476 * @return The unshifted Unicode codepoint
477 *
478 * @ingroup key
479 */
480GHOSTTY_API uint32_t ghostty_key_event_get_unshifted_codepoint(GhosttyKeyEvent event);
481
482#endif /* GHOSTTY_VT_KEY_EVENT_H */
apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/kitty_graphics.h deleted-775
......@@ -1,775 +0,0 @@
1/**
2 * @file kitty_graphics.h
3 *
4 * Kitty graphics protocol
5 *
6 * See @ref kitty_graphics for a full usage guide.
7 */
8
9#ifndef GHOSTTY_VT_KITTY_GRAPHICS_H
10#define GHOSTTY_VT_KITTY_GRAPHICS_H
11
12#include <stdbool.h>
13#include <stdint.h>
14#include <ghostty/vt/allocator.h>
15#include <ghostty/vt/selection.h>
16#include <ghostty/vt/types.h>
17
18#ifdef __cplusplus
19extern "C" {
20#endif
21
22/** @defgroup kitty_graphics Kitty Graphics
23 *
24 * API for inspecting images and placements stored via the
25 * [Kitty graphics protocol](https://sw.kovidgoyal.net/kitty/graphics-protocol/).
26 *
27 * The central object is @ref GhosttyKittyGraphics, an opaque handle to
28 * the image storage associated with a terminal's active screen. From it
29 * you can iterate over placements and look up individual images.
30 *
31 * ## Obtaining a KittyGraphics Handle
32 *
33 * A @ref GhosttyKittyGraphics handle is obtained from a terminal via
34 * ghostty_terminal_get() with @ref GHOSTTY_TERMINAL_DATA_KITTY_GRAPHICS.
35 * The handle is borrowed from the terminal and remains valid until the
36 * next mutating terminal call (e.g. ghostty_terminal_vt_write() or
37 * ghostty_terminal_reset()).
38 *
39 * Before images can be stored, Kitty graphics must be enabled on the
40 * terminal by setting a non-zero storage limit with
41 * @ref GHOSTTY_TERMINAL_OPT_KITTY_IMAGE_STORAGE_LIMIT, and a PNG
42 * decoder callback must be installed via ghostty_sys_set() with
43 * @ref GHOSTTY_SYS_OPT_DECODE_PNG.
44 *
45 * @snippet c-vt-kitty-graphics/src/main.c kitty-graphics-decode-png
46 *
47 * ## Iterating Placements
48 *
49 * Placements are inspected through a @ref GhosttyKittyGraphicsPlacementIterator.
50 * The typical workflow is:
51 *
52 * 1. Create an iterator with ghostty_kitty_graphics_placement_iterator_new().
53 * 2. Populate it from the storage with ghostty_kitty_graphics_get() using
54 * @ref GHOSTTY_KITTY_GRAPHICS_DATA_PLACEMENT_ITERATOR.
55 * 3. Optionally filter by z-layer with
56 * ghostty_kitty_graphics_placement_iterator_set().
57 * 4. Advance with ghostty_kitty_graphics_placement_next() and read
58 * per-placement data with ghostty_kitty_graphics_placement_get().
59 * 5. For each placement, look up its image with
60 * ghostty_kitty_graphics_image() to access pixel data and dimensions.
61 * 6. Free the iterator with ghostty_kitty_graphics_placement_iterator_free().
62 *
63 * ## Looking Up Images
64 *
65 * Given an image ID (obtained from a placement via
66 * @ref GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_IMAGE_ID), call
67 * ghostty_kitty_graphics_image() to get a @ref GhosttyKittyGraphicsImage
68 * handle. From this handle, ghostty_kitty_graphics_image_get() provides
69 * the image dimensions, pixel format, compression, and a borrowed pointer
70 * to the raw pixel data.
71 *
72 * ## Rendering Helpers
73 *
74 * Several functions assist with rendering a placement:
75 *
76 * - ghostty_kitty_graphics_placement_pixel_size() — rendered pixel
77 * dimensions accounting for source rect and aspect ratio.
78 * - ghostty_kitty_graphics_placement_grid_size() — number of grid
79 * columns and rows the placement occupies.
80 * - ghostty_kitty_graphics_placement_viewport_pos() — viewport-relative
81 * grid position (may be negative for partially scrolled placements).
82 * - ghostty_kitty_graphics_placement_source_rect() — resolved source
83 * rectangle in pixels, clamped to image bounds.
84 * - ghostty_kitty_graphics_placement_rect() — bounding rectangle as a
85 * @ref GhosttySelection.
86 *
87 * ## Lifetime and Thread Safety
88 *
89 * All handles borrowed from the terminal (GhosttyKittyGraphics,
90 * GhosttyKittyGraphicsImage) are invalidated by any mutating terminal
91 * call. The placement iterator is independently owned and must be freed
92 * by the caller, but the data it yields is only valid while the
93 * underlying terminal is not mutated.
94 *
95 * ## Example
96 *
97 * The following example creates a terminal, sends a Kitty graphics
98 * image, then iterates placements and prints image metadata:
99 *
100 * @snippet c-vt-kitty-graphics/src/main.c kitty-graphics-main
101 *
102 * @{
103 */
104
105/**
106 * Queryable data kinds for ghostty_kitty_graphics_get().
107 *
108 * @ingroup kitty_graphics
109 */
110typedef enum GHOSTTY_ENUM_TYPED {
111 /** Invalid / sentinel value. */
112 GHOSTTY_KITTY_GRAPHICS_DATA_INVALID = 0,
113
114 /**
115 * Populate a pre-allocated placement iterator with placement data from
116 * the storage. Iterator data is only valid as long as the underlying
117 * terminal is not mutated.
118 *
119 * Output type: GhosttyKittyGraphicsPlacementIterator *
120 */
121 GHOSTTY_KITTY_GRAPHICS_DATA_PLACEMENT_ITERATOR = 1,
122 GHOSTTY_KITTY_GRAPHICS_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
123} GhosttyKittyGraphicsData;
124
125/**
126 * Queryable data kinds for ghostty_kitty_graphics_placement_get().
127 *
128 * @ingroup kitty_graphics
129 */
130typedef enum GHOSTTY_ENUM_TYPED {
131 /** Invalid / sentinel value. */
132 GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_INVALID = 0,
133
134 /**
135 * The image ID this placement belongs to.
136 *
137 * Output type: uint32_t *
138 */
139 GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_IMAGE_ID = 1,
140
141 /**
142 * The placement ID.
143 *
144 * Output type: uint32_t *
145 */
146 GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_PLACEMENT_ID = 2,
147
148 /**
149 * Whether this is a virtual placement (unicode placeholder).
150 *
151 * Output type: bool *
152 */
153 GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_IS_VIRTUAL = 3,
154
155 /**
156 * Pixel offset from the left edge of the cell.
157 *
158 * Output type: uint32_t *
159 */
160 GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_X_OFFSET = 4,
161
162 /**
163 * Pixel offset from the top edge of the cell.
164 *
165 * Output type: uint32_t *
166 */
167 GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_Y_OFFSET = 5,
168
169 /**
170 * Source rectangle x origin in pixels.
171 *
172 * Output type: uint32_t *
173 */
174 GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_SOURCE_X = 6,
175
176 /**
177 * Source rectangle y origin in pixels.
178 *
179 * Output type: uint32_t *
180 */
181 GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_SOURCE_Y = 7,
182
183 /**
184 * Source rectangle width in pixels (0 = full image width).
185 *
186 * Output type: uint32_t *
187 */
188 GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_SOURCE_WIDTH = 8,
189
190 /**
191 * Source rectangle height in pixels (0 = full image height).
192 *
193 * Output type: uint32_t *
194 */
195 GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_SOURCE_HEIGHT = 9,
196
197 /**
198 * Number of columns this placement occupies.
199 *
200 * Output type: uint32_t *
201 */
202 GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_COLUMNS = 10,
203
204 /**
205 * Number of rows this placement occupies.
206 *
207 * Output type: uint32_t *
208 */
209 GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_ROWS = 11,
210
211 /**
212 * Z-index for this placement.
213 *
214 * Output type: int32_t *
215 */
216 GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_Z = 12,
217
218 GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
219} GhosttyKittyGraphicsPlacementData;
220
221/**
222 * Z-layer classification for kitty graphics placements.
223 *
224 * Based on the kitty protocol z-index conventions:
225 * - BELOW_BG: z < INT32_MIN/2 (drawn below cell background)
226 * - BELOW_TEXT: INT32_MIN/2 <= z < 0 (above background, below text)
227 * - ABOVE_TEXT: z >= 0 (above text)
228 * - ALL: no filtering (current behavior)
229 *
230 * @ingroup kitty_graphics
231 */
232typedef enum GHOSTTY_ENUM_TYPED {
233 GHOSTTY_KITTY_PLACEMENT_LAYER_ALL = 0,
234 GHOSTTY_KITTY_PLACEMENT_LAYER_BELOW_BG = 1,
235 GHOSTTY_KITTY_PLACEMENT_LAYER_BELOW_TEXT = 2,
236 GHOSTTY_KITTY_PLACEMENT_LAYER_ABOVE_TEXT = 3,
237 GHOSTTY_KITTY_PLACEMENT_LAYER_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
238} GhosttyKittyPlacementLayer;
239
240/**
241 * Settable options for ghostty_kitty_graphics_placement_iterator_set().
242 *
243 * @ingroup kitty_graphics
244 */
245typedef enum GHOSTTY_ENUM_TYPED {
246 /**
247 * Set the z-layer filter for the iterator.
248 *
249 * Input type: GhosttyKittyPlacementLayer *
250 */
251 GHOSTTY_KITTY_GRAPHICS_PLACEMENT_ITERATOR_OPTION_LAYER = 0,
252 GHOSTTY_KITTY_GRAPHICS_PLACEMENT_ITERATOR_OPTION_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
253} GhosttyKittyGraphicsPlacementIteratorOption;
254
255/**
256 * Pixel format of a Kitty graphics image.
257 *
258 * @ingroup kitty_graphics
259 */
260typedef enum GHOSTTY_ENUM_TYPED {
261 GHOSTTY_KITTY_IMAGE_FORMAT_RGB = 0,
262 GHOSTTY_KITTY_IMAGE_FORMAT_RGBA = 1,
263 GHOSTTY_KITTY_IMAGE_FORMAT_PNG = 2,
264 GHOSTTY_KITTY_IMAGE_FORMAT_GRAY_ALPHA = 3,
265 GHOSTTY_KITTY_IMAGE_FORMAT_GRAY = 4,
266 GHOSTTY_KITTY_IMAGE_FORMAT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
267} GhosttyKittyImageFormat;
268
269/**
270 * Compression of a Kitty graphics image.
271 *
272 * @ingroup kitty_graphics
273 */
274typedef enum GHOSTTY_ENUM_TYPED {
275 GHOSTTY_KITTY_IMAGE_COMPRESSION_NONE = 0,
276 GHOSTTY_KITTY_IMAGE_COMPRESSION_ZLIB_DEFLATE = 1,
277 GHOSTTY_KITTY_IMAGE_COMPRESSION_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
278} GhosttyKittyImageCompression;
279
280/**
281 * Queryable data kinds for ghostty_kitty_graphics_image_get().
282 *
283 * @ingroup kitty_graphics
284 */
285typedef enum GHOSTTY_ENUM_TYPED {
286 /** Invalid / sentinel value. */
287 GHOSTTY_KITTY_IMAGE_DATA_INVALID = 0,
288
289 /**
290 * The image ID.
291 *
292 * Output type: uint32_t *
293 */
294 GHOSTTY_KITTY_IMAGE_DATA_ID = 1,
295
296 /**
297 * The image number.
298 *
299 * Output type: uint32_t *
300 */
301 GHOSTTY_KITTY_IMAGE_DATA_NUMBER = 2,
302
303 /**
304 * Image width in pixels.
305 *
306 * Output type: uint32_t *
307 */
308 GHOSTTY_KITTY_IMAGE_DATA_WIDTH = 3,
309
310 /**
311 * Image height in pixels.
312 *
313 * Output type: uint32_t *
314 */
315 GHOSTTY_KITTY_IMAGE_DATA_HEIGHT = 4,
316
317 /**
318 * Pixel format of the image.
319 *
320 * Output type: GhosttyKittyImageFormat *
321 */
322 GHOSTTY_KITTY_IMAGE_DATA_FORMAT = 5,
323
324 /**
325 * Compression of the image.
326 *
327 * Output type: GhosttyKittyImageCompression *
328 */
329 GHOSTTY_KITTY_IMAGE_DATA_COMPRESSION = 6,
330
331 /**
332 * Borrowed pointer to the raw pixel data. Valid as long as the
333 * underlying terminal is not mutated.
334 *
335 * Output type: const uint8_t **
336 */
337 GHOSTTY_KITTY_IMAGE_DATA_DATA_PTR = 7,
338
339 /**
340 * Length of the raw pixel data in bytes.
341 *
342 * Output type: size_t *
343 */
344 GHOSTTY_KITTY_IMAGE_DATA_DATA_LEN = 8,
345
346 GHOSTTY_KITTY_IMAGE_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
347} GhosttyKittyGraphicsImageData;
348
349/**
350 * Combined rendering geometry for a placement in a single sized struct.
351 *
352 * Combines the results of ghostty_kitty_graphics_placement_pixel_size(),
353 * ghostty_kitty_graphics_placement_grid_size(),
354 * ghostty_kitty_graphics_placement_viewport_pos(), and
355 * ghostty_kitty_graphics_placement_source_rect() into one call. This is
356 * an optimization over calling those four functions individually,
357 * particularly useful in environments with high per-call overhead such
358 * as FFI or Cgo.
359 *
360 * This struct uses the sized-struct ABI pattern. Initialize with
361 * GHOSTTY_INIT_SIZED(GhosttyKittyGraphicsPlacementRenderInfo) before calling
362 * ghostty_kitty_graphics_placement_render_info().
363 *
364 * @ingroup kitty_graphics
365 */
366typedef struct {
367 /** Size of this struct in bytes. Must be set to sizeof(GhosttyKittyGraphicsPlacementRenderInfo). */
368 size_t size;
369 /** Rendered width in pixels. */
370 uint32_t pixel_width;
371 /** Rendered height in pixels. */
372 uint32_t pixel_height;
373 /** Number of grid columns the placement occupies. */
374 uint32_t grid_cols;
375 /** Number of grid rows the placement occupies. */
376 uint32_t grid_rows;
377 /** Viewport-relative column (may be negative for partially visible placements). */
378 int32_t viewport_col;
379 /** Viewport-relative row (may be negative for partially visible placements). */
380 int32_t viewport_row;
381 /** False when the placement is fully off-screen or virtual. */
382 bool viewport_visible;
383 /** Resolved source rectangle x origin in pixels. */
384 uint32_t source_x;
385 /** Resolved source rectangle y origin in pixels. */
386 uint32_t source_y;
387 /** Resolved source rectangle width in pixels. */
388 uint32_t source_width;
389 /** Resolved source rectangle height in pixels. */
390 uint32_t source_height;
391} GhosttyKittyGraphicsPlacementRenderInfo;
392
393/**
394 * Get data from a kitty graphics storage instance.
395 *
396 * The output pointer must be of the appropriate type for the requested
397 * data kind.
398 *
399 * Returns GHOSTTY_NO_VALUE when Kitty graphics are disabled at build time.
400 *
401 * @param graphics The kitty graphics handle
402 * @param data The type of data to extract
403 * @param[out] out Pointer to store the extracted data
404 * @return GHOSTTY_SUCCESS on success
405 *
406 * @ingroup kitty_graphics
407 */
408GHOSTTY_API GhosttyResult ghostty_kitty_graphics_get(
409 GhosttyKittyGraphics graphics,
410 GhosttyKittyGraphicsData data,
411 void* out);
412
413/**
414 * Look up a Kitty graphics image by its image ID.
415 *
416 * Returns NULL if no image with the given ID exists or if Kitty graphics
417 * are disabled at build time.
418 *
419 * @param graphics The kitty graphics handle
420 * @param image_id The image ID to look up
421 * @return An opaque image handle, or NULL if not found
422 *
423 * @ingroup kitty_graphics
424 */
425GHOSTTY_API GhosttyKittyGraphicsImage ghostty_kitty_graphics_image(
426 GhosttyKittyGraphics graphics,
427 uint32_t image_id);
428
429/**
430 * Get data from a Kitty graphics image.
431 *
432 * The output pointer must be of the appropriate type for the requested
433 * data kind.
434 *
435 * @param image The image handle (NULL returns GHOSTTY_INVALID_VALUE)
436 * @param data The data kind to query
437 * @param[out] out Pointer to receive the queried value
438 * @return GHOSTTY_SUCCESS on success
439 *
440 * @ingroup kitty_graphics
441 */
442GHOSTTY_API GhosttyResult ghostty_kitty_graphics_image_get(
443 GhosttyKittyGraphicsImage image,
444 GhosttyKittyGraphicsImageData data,
445 void* out);
446
447/**
448 * Get multiple data fields from a Kitty graphics image in a single call.
449 *
450 * This is an optimization over calling ghostty_kitty_graphics_image_get()
451 * repeatedly, particularly useful in environments with high per-call
452 * overhead such as FFI or Cgo.
453 *
454 * Each element in the keys array specifies a data kind, and the
455 * corresponding element in the values array receives the result.
456 * The type of each values[i] pointer must match the output type
457 * documented for keys[i].
458 *
459 * Processing stops at the first error; on success out_written
460 * is set to count, on error it is set to the index of the
461 * failing key (i.e. the number of values successfully written).
462 *
463 * @param image The image handle (NULL returns GHOSTTY_INVALID_VALUE)
464 * @param count Number of key/value pairs
465 * @param keys Array of data kinds to query
466 * @param values Array of output pointers (types must match each key's
467 * documented output type)
468 * @param[out] out_written On return, receives the number of values
469 * successfully written (may be NULL)
470 * @return GHOSTTY_SUCCESS if all queries succeed
471 *
472 * @ingroup kitty_graphics
473 */
474GHOSTTY_API GhosttyResult ghostty_kitty_graphics_image_get_multi(
475 GhosttyKittyGraphicsImage image,
476 size_t count,
477 const GhosttyKittyGraphicsImageData* keys,
478 void** values,
479 size_t* out_written);
480
481/**
482 * Create a new placement iterator instance.
483 *
484 * All fields except the allocator are left undefined until populated
485 * via ghostty_kitty_graphics_get() with
486 * GHOSTTY_KITTY_GRAPHICS_DATA_PLACEMENT_ITERATOR.
487 *
488 * @param allocator Pointer to allocator, or NULL to use the default allocator
489 * @param[out] out_iterator On success, receives the created iterator handle
490 * @return GHOSTTY_SUCCESS on success, GHOSTTY_OUT_OF_MEMORY on allocation
491 * failure
492 *
493 * @ingroup kitty_graphics
494 */
495GHOSTTY_API GhosttyResult ghostty_kitty_graphics_placement_iterator_new(
496 const GhosttyAllocator* allocator,
497 GhosttyKittyGraphicsPlacementIterator* out_iterator);
498
499/**
500 * Free a placement iterator.
501 *
502 * @param iterator The iterator handle to free (may be NULL)
503 *
504 * @ingroup kitty_graphics
505 */
506GHOSTTY_API void ghostty_kitty_graphics_placement_iterator_free(
507 GhosttyKittyGraphicsPlacementIterator iterator);
508
509/**
510 * Set an option on a placement iterator.
511 *
512 * Use GHOSTTY_KITTY_GRAPHICS_PLACEMENT_ITERATOR_OPTION_LAYER with a
513 * GhosttyKittyPlacementLayer value to filter placements by z-layer.
514 * The filter is applied during iteration: ghostty_kitty_graphics_placement_next()
515 * will skip placements that do not match the configured layer.
516 *
517 * The default layer is GHOSTTY_KITTY_PLACEMENT_LAYER_ALL (no filtering).
518 *
519 * @param iterator The iterator handle (NULL returns GHOSTTY_INVALID_VALUE)
520 * @param option The option to set
521 * @param value Pointer to the value (type depends on option; NULL returns
522 * GHOSTTY_INVALID_VALUE)
523 * @return GHOSTTY_SUCCESS on success
524 *
525 * @ingroup kitty_graphics
526 */
527GHOSTTY_API GhosttyResult ghostty_kitty_graphics_placement_iterator_set(
528 GhosttyKittyGraphicsPlacementIterator iterator,
529 GhosttyKittyGraphicsPlacementIteratorOption option,
530 const void* value);
531
532/**
533 * Advance the placement iterator to the next placement.
534 *
535 * If a layer filter has been set via
536 * ghostty_kitty_graphics_placement_iterator_set(), only placements
537 * matching that layer are returned.
538 *
539 * @param iterator The iterator handle (may be NULL)
540 * @return true if advanced to the next placement, false if at the end
541 *
542 * @ingroup kitty_graphics
543 */
544GHOSTTY_API bool ghostty_kitty_graphics_placement_next(
545 GhosttyKittyGraphicsPlacementIterator iterator);
546
547/**
548 * Get data from the current placement in a placement iterator.
549 *
550 * Call ghostty_kitty_graphics_placement_next() at least once before
551 * calling this function.
552 *
553 * @param iterator The iterator handle (NULL returns GHOSTTY_INVALID_VALUE)
554 * @param data The data kind to query
555 * @param[out] out Pointer to receive the queried value
556 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the
557 * iterator is NULL or not positioned on a placement
558 *
559 * @ingroup kitty_graphics
560 */
561GHOSTTY_API GhosttyResult ghostty_kitty_graphics_placement_get(
562 GhosttyKittyGraphicsPlacementIterator iterator,
563 GhosttyKittyGraphicsPlacementData data,
564 void* out);
565
566/**
567 * Get multiple data fields from the current placement in a single call.
568 *
569 * This is an optimization over calling ghostty_kitty_graphics_placement_get()
570 * repeatedly, particularly useful in environments with high per-call
571 * overhead such as FFI or Cgo.
572 *
573 * Each element in the keys array specifies a data kind, and the
574 * corresponding element in the values array receives the result.
575 * The type of each values[i] pointer must match the output type
576 * documented for keys[i].
577 *
578 * Processing stops at the first error; on success out_written
579 * is set to count, on error it is set to the index of the
580 * failing key (i.e. the number of values successfully written).
581 *
582 * @param iterator The iterator handle (NULL returns GHOSTTY_INVALID_VALUE)
583 * @param count Number of key/value pairs
584 * @param keys Array of data kinds to query
585 * @param values Array of output pointers (types must match each key's
586 * documented output type)
587 * @param[out] out_written On return, receives the number of values
588 * successfully written (may be NULL)
589 * @return GHOSTTY_SUCCESS if all queries succeed
590 *
591 * @ingroup kitty_graphics
592 */
593GHOSTTY_API GhosttyResult ghostty_kitty_graphics_placement_get_multi(
594 GhosttyKittyGraphicsPlacementIterator iterator,
595 size_t count,
596 const GhosttyKittyGraphicsPlacementData* keys,
597 void** values,
598 size_t* out_written);
599
600/**
601 * Compute the grid rectangle occupied by the current placement.
602 *
603 * Uses the placement's pin, the image dimensions, and the terminal's
604 * cell/pixel geometry to calculate the bounding rectangle. Virtual
605 * placements (unicode placeholders) return GHOSTTY_NO_VALUE.
606 *
607 * @param terminal The terminal handle
608 * @param image The image handle for this placement's image
609 * @param iterator The placement iterator positioned on a placement
610 * @param[out] out_selection On success, receives the bounding rectangle
611 * as a selection with rectangle=true
612 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if any handle
613 * is NULL or the iterator is not positioned, GHOSTTY_NO_VALUE for
614 * virtual placements or when Kitty graphics are disabled
615 *
616 * @ingroup kitty_graphics
617 */
618GHOSTTY_API GhosttyResult ghostty_kitty_graphics_placement_rect(
619 GhosttyKittyGraphicsPlacementIterator iterator,
620 GhosttyKittyGraphicsImage image,
621 GhosttyTerminal terminal,
622 GhosttySelection* out_selection);
623
624/**
625 * Compute the rendered pixel size of the current placement.
626 *
627 * Takes into account the placement's source rectangle, specified
628 * columns/rows, and aspect ratio to calculate the final rendered
629 * pixel dimensions.
630 *
631 * @param iterator The placement iterator positioned on a placement
632 * @param image The image handle for this placement's image
633 * @param terminal The terminal handle
634 * @param[out] out_width On success, receives the width in pixels
635 * @param[out] out_height On success, receives the height in pixels
636 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if any handle
637 * is NULL or the iterator is not positioned, GHOSTTY_NO_VALUE when
638 * Kitty graphics are disabled
639 *
640 * @ingroup kitty_graphics
641 */
642GHOSTTY_API GhosttyResult ghostty_kitty_graphics_placement_pixel_size(
643 GhosttyKittyGraphicsPlacementIterator iterator,
644 GhosttyKittyGraphicsImage image,
645 GhosttyTerminal terminal,
646 uint32_t* out_width,
647 uint32_t* out_height);
648
649/**
650 * Compute the grid cell size of the current placement.
651 *
652 * Returns the number of columns and rows that the placement occupies
653 * in the terminal grid. If the placement specifies explicit columns
654 * and rows, those are returned directly; otherwise they are calculated
655 * from the pixel size and cell dimensions.
656 *
657 * @param iterator The placement iterator positioned on a placement
658 * @param image The image handle for this placement's image
659 * @param terminal The terminal handle
660 * @param[out] out_cols On success, receives the number of columns
661 * @param[out] out_rows On success, receives the number of rows
662 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if any handle
663 * is NULL or the iterator is not positioned, GHOSTTY_NO_VALUE when
664 * Kitty graphics are disabled
665 *
666 * @ingroup kitty_graphics
667 */
668GHOSTTY_API GhosttyResult ghostty_kitty_graphics_placement_grid_size(
669 GhosttyKittyGraphicsPlacementIterator iterator,
670 GhosttyKittyGraphicsImage image,
671 GhosttyTerminal terminal,
672 uint32_t* out_cols,
673 uint32_t* out_rows);
674
675/**
676 * Get the viewport-relative grid position of the current placement.
677 *
678 * Converts the placement's internal pin to viewport-relative column and
679 * row coordinates. The returned coordinates represent the top-left
680 * corner of the placement in the viewport's grid coordinate space.
681 *
682 * The row value can be negative when the placement's origin has
683 * scrolled above the top of the viewport. For example, a 4-row
684 * image that has scrolled up by 2 rows returns row=-2, meaning
685 * its top 2 rows are above the visible area but its bottom 2 rows
686 * are still on screen. Embedders should use these coordinates
687 * directly when computing the destination rectangle for rendering;
688 * the embedder is responsible for clipping the portion of the image
689 * that falls outside the viewport.
690 *
691 * Returns GHOSTTY_SUCCESS for any placement that is at least
692 * partially visible in the viewport. Returns GHOSTTY_NO_VALUE when
693 * the placement is completely outside the viewport (its bottom edge
694 * is above the viewport or its top edge is at or below the last
695 * viewport row), or when the placement is a virtual (unicode
696 * placeholder) placement.
697 *
698 * @param iterator The placement iterator positioned on a placement
699 * @param image The image handle for this placement's image
700 * @param terminal The terminal handle
701 * @param[out] out_col On success, receives the viewport-relative column
702 * @param[out] out_row On success, receives the viewport-relative row
703 * (may be negative for partially visible placements)
704 * @return GHOSTTY_SUCCESS on success, GHOSTTY_NO_VALUE if fully
705 * off-screen or virtual, GHOSTTY_INVALID_VALUE if any handle
706 * is NULL or the iterator is not positioned
707 *
708 * @ingroup kitty_graphics
709 */
710GHOSTTY_API GhosttyResult ghostty_kitty_graphics_placement_viewport_pos(
711 GhosttyKittyGraphicsPlacementIterator iterator,
712 GhosttyKittyGraphicsImage image,
713 GhosttyTerminal terminal,
714 int32_t* out_col,
715 int32_t* out_row);
716
717/**
718 * Get the resolved source rectangle for the current placement.
719 *
720 * Applies kitty protocol semantics: a width or height of 0 in the
721 * placement means "use the full image dimension", and the resulting
722 * rectangle is clamped to the actual image bounds. The returned
723 * values are in pixels and are ready to use for texture sampling.
724 *
725 * @param iterator The placement iterator positioned on a placement
726 * @param image The image handle for this placement's image
727 * @param[out] out_x Source rect x origin in pixels
728 * @param[out] out_y Source rect y origin in pixels
729 * @param[out] out_width Source rect width in pixels
730 * @param[out] out_height Source rect height in pixels
731 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if any
732 * handle is NULL or the iterator is not positioned
733 *
734 * @ingroup kitty_graphics
735 */
736GHOSTTY_API GhosttyResult ghostty_kitty_graphics_placement_source_rect(
737 GhosttyKittyGraphicsPlacementIterator iterator,
738 GhosttyKittyGraphicsImage image,
739 uint32_t* out_x,
740 uint32_t* out_y,
741 uint32_t* out_width,
742 uint32_t* out_height);
743
744/**
745 * Get all rendering geometry for a placement in a single call.
746 *
747 * Combines pixel size, grid size, viewport position, and source
748 * rectangle into one struct. Initialize with
749 * GHOSTTY_INIT_SIZED(GhosttyKittyGraphicsPlacementRenderInfo).
750 *
751 * When viewport_visible is false, the placement is fully off-screen
752 * or is a virtual placement; viewport_col and viewport_row may
753 * contain meaningless values in that case.
754 *
755 * @param iterator The iterator positioned on a placement
756 * @param image The image handle for this placement's image
757 * @param terminal The terminal handle
758 * @param[out] out_info Pointer to receive the rendering geometry
759 * @return GHOSTTY_SUCCESS on success
760 *
761 * @ingroup kitty_graphics
762 */
763GHOSTTY_API GhosttyResult ghostty_kitty_graphics_placement_render_info(
764 GhosttyKittyGraphicsPlacementIterator iterator,
765 GhosttyKittyGraphicsImage image,
766 GhosttyTerminal terminal,
767 GhosttyKittyGraphicsPlacementRenderInfo* out_info);
768
769/** @} */
770
771#ifdef __cplusplus
772}
773#endif
774
775#endif /* GHOSTTY_VT_KITTY_GRAPHICS_H */
apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/modes.h deleted-198
......@@ -1,198 +0,0 @@
1/**
2 * @file modes.h
3 *
4 * Terminal mode utilities - pack and unpack ANSI/DEC mode identifiers.
5 */
6
7#ifndef GHOSTTY_VT_MODES_H
8#define GHOSTTY_VT_MODES_H
9
10/** @defgroup modes Mode Utilities
11 *
12 * Utilities for working with terminal modes. A mode is a compact
13 * 16-bit representation of a terminal mode identifier that encodes both
14 * the numeric mode value (up to 15 bits) and whether the mode is an ANSI
15 * mode or a DEC private mode (?-prefixed).
16 *
17 * The packed layout (least-significant bit first) is:
18 * - Bits 0–14: mode value (u15)
19 * - Bit 15: ANSI flag (0 = DEC private mode, 1 = ANSI mode)
20 *
21 * ## Example
22 *
23 * @snippet c-vt-modes/src/main.c modes-pack-unpack
24 *
25 * ## DECRPM Report Encoding
26 *
27 * Use ghostty_mode_report_encode() to encode a DECRPM response into a
28 * caller-provided buffer:
29 *
30 * @snippet c-vt-modes/src/main.c modes-decrpm
31 *
32 * @{
33 */
34
35#include <stdbool.h>
36#include <stddef.h>
37#include <stdint.h>
38
39#include <ghostty/vt/types.h>
40
41#ifdef __cplusplus
42extern "C" {
43#endif
44
45/** @name ANSI Modes
46 * Modes for standard ANSI modes.
47 * @{
48 */
49#define GHOSTTY_MODE_KAM (ghostty_mode_new(2, true)) /**< Keyboard action (disable keyboard) */
50#define GHOSTTY_MODE_INSERT (ghostty_mode_new(4, true)) /**< Insert mode */
51#define GHOSTTY_MODE_SRM (ghostty_mode_new(12, true)) /**< Send/receive mode */
52#define GHOSTTY_MODE_LINEFEED (ghostty_mode_new(20, true)) /**< Linefeed/new line mode */
53/** @} */
54
55/** @name DEC Private Modes
56 * Modes for DEC private modes (?-prefixed).
57 * @{
58 */
59#define GHOSTTY_MODE_DECCKM (ghostty_mode_new(1, false)) /**< Cursor keys */
60#define GHOSTTY_MODE_132_COLUMN (ghostty_mode_new(3, false)) /**< 132/80 column mode */
61#define GHOSTTY_MODE_SLOW_SCROLL (ghostty_mode_new(4, false)) /**< Slow scroll */
62#define GHOSTTY_MODE_REVERSE_COLORS (ghostty_mode_new(5, false)) /**< Reverse video */
63#define GHOSTTY_MODE_ORIGIN (ghostty_mode_new(6, false)) /**< Origin mode */
64#define GHOSTTY_MODE_WRAPAROUND (ghostty_mode_new(7, false)) /**< Auto-wrap mode */
65#define GHOSTTY_MODE_AUTOREPEAT (ghostty_mode_new(8, false)) /**< Auto-repeat keys */
66#define GHOSTTY_MODE_X10_MOUSE (ghostty_mode_new(9, false)) /**< X10 mouse reporting */
67#define GHOSTTY_MODE_CURSOR_BLINKING (ghostty_mode_new(12, false)) /**< Cursor blink */
68#define GHOSTTY_MODE_CURSOR_VISIBLE (ghostty_mode_new(25, false)) /**< Cursor visible (DECTCEM) */
69#define GHOSTTY_MODE_ENABLE_MODE_3 (ghostty_mode_new(40, false)) /**< Allow 132 column mode */
70#define GHOSTTY_MODE_REVERSE_WRAP (ghostty_mode_new(45, false)) /**< Reverse wrap */
71#define GHOSTTY_MODE_ALT_SCREEN_LEGACY (ghostty_mode_new(47, false)) /**< Alternate screen (legacy) */
72#define GHOSTTY_MODE_KEYPAD_KEYS (ghostty_mode_new(66, false)) /**< Application keypad */
73#define GHOSTTY_MODE_BACKARROW_KEY_MODE (ghostty_mode_new(67, false)) /**< Backarrow key mode (DECBKM) */
74#define GHOSTTY_MODE_LEFT_RIGHT_MARGIN (ghostty_mode_new(69, false)) /**< Left/right margin mode */
75#define GHOSTTY_MODE_NORMAL_MOUSE (ghostty_mode_new(1000, false)) /**< Normal mouse tracking */
76#define GHOSTTY_MODE_BUTTON_MOUSE (ghostty_mode_new(1002, false)) /**< Button-event mouse tracking */
77#define GHOSTTY_MODE_ANY_MOUSE (ghostty_mode_new(1003, false)) /**< Any-event mouse tracking */
78#define GHOSTTY_MODE_FOCUS_EVENT (ghostty_mode_new(1004, false)) /**< Focus in/out events */
79#define GHOSTTY_MODE_UTF8_MOUSE (ghostty_mode_new(1005, false)) /**< UTF-8 mouse format */
80#define GHOSTTY_MODE_SGR_MOUSE (ghostty_mode_new(1006, false)) /**< SGR mouse format */
81#define GHOSTTY_MODE_ALT_SCROLL (ghostty_mode_new(1007, false)) /**< Alternate scroll mode */
82#define GHOSTTY_MODE_URXVT_MOUSE (ghostty_mode_new(1015, false)) /**< URxvt mouse format */
83#define GHOSTTY_MODE_SGR_PIXELS_MOUSE (ghostty_mode_new(1016, false)) /**< SGR-Pixels mouse format */
84#define GHOSTTY_MODE_NUMLOCK_KEYPAD (ghostty_mode_new(1035, false)) /**< Ignore keypad with NumLock */
85#define GHOSTTY_MODE_ALT_ESC_PREFIX (ghostty_mode_new(1036, false)) /**< Alt key sends ESC prefix */
86#define GHOSTTY_MODE_ALT_SENDS_ESC (ghostty_mode_new(1039, false)) /**< Alt sends escape */
87#define GHOSTTY_MODE_REVERSE_WRAP_EXT (ghostty_mode_new(1045, false)) /**< Extended reverse wrap */
88#define GHOSTTY_MODE_ALT_SCREEN (ghostty_mode_new(1047, false)) /**< Alternate screen */
89#define GHOSTTY_MODE_SAVE_CURSOR (ghostty_mode_new(1048, false)) /**< Save cursor (DECSC) */
90#define GHOSTTY_MODE_ALT_SCREEN_SAVE (ghostty_mode_new(1049, false)) /**< Alt screen + save cursor + clear */
91#define GHOSTTY_MODE_BRACKETED_PASTE (ghostty_mode_new(2004, false)) /**< Bracketed paste mode */
92#define GHOSTTY_MODE_SYNC_OUTPUT (ghostty_mode_new(2026, false)) /**< Synchronized output */
93#define GHOSTTY_MODE_GRAPHEME_CLUSTER (ghostty_mode_new(2027, false)) /**< Grapheme cluster mode */
94#define GHOSTTY_MODE_COLOR_SCHEME_REPORT (ghostty_mode_new(2031, false)) /**< Report color scheme */
95#define GHOSTTY_MODE_IN_BAND_RESIZE (ghostty_mode_new(2048, false)) /**< In-band size reports */
96/** @} */
97
98/**
99 * A packed 16-bit terminal mode.
100 *
101 * Encodes a mode value (bits 0–14) and an ANSI flag (bit 15) into a
102 * single 16-bit integer. Use the inline helper functions to construct
103 * and inspect modes rather than manipulating bits directly.
104 */
105typedef uint16_t GhosttyMode;
106
107/**
108 * Create a mode from a mode value and ANSI flag.
109 *
110 * @param value The numeric mode value (0–32767)
111 * @param ansi true for an ANSI mode, false for a DEC private mode
112 * @return The packed mode
113 *
114 * @ingroup modes
115 */
116static inline GhosttyMode ghostty_mode_new(uint16_t value, bool ansi) {
117 return (GhosttyMode)((value & 0x7FFF) | ((uint16_t)ansi << 15));
118}
119
120/**
121 * Extract the numeric mode value from a mode.
122 *
123 * @param mode The mode
124 * @return The mode value (0–32767)
125 *
126 * @ingroup modes
127 */
128static inline uint16_t ghostty_mode_value(GhosttyMode mode) {
129 return mode & 0x7FFF;
130}
131
132/**
133 * Check whether a mode represents an ANSI mode.
134 *
135 * @param mode The mode
136 * @return true if this is an ANSI mode, false if it is a DEC private mode
137 *
138 * @ingroup modes
139 */
140static inline bool ghostty_mode_ansi(GhosttyMode mode) {
141 return (mode >> 15) != 0;
142}
143
144/**
145 * DECRPM report state values.
146 *
147 * These correspond to the Ps2 parameter in a DECRPM response
148 * sequence (CSI ? Ps1 ; Ps2 $ y).
149 */
150typedef enum GHOSTTY_ENUM_TYPED {
151 /** Mode is not recognized */
152 GHOSTTY_MODE_REPORT_NOT_RECOGNIZED = 0,
153 /** Mode is set (enabled) */
154 GHOSTTY_MODE_REPORT_SET = 1,
155 /** Mode is reset (disabled) */
156 GHOSTTY_MODE_REPORT_RESET = 2,
157 /** Mode is permanently set */
158 GHOSTTY_MODE_REPORT_PERMANENTLY_SET = 3,
159 /** Mode is permanently reset */
160 GHOSTTY_MODE_REPORT_PERMANENTLY_RESET = 4,
161 GHOSTTY_MODE_REPORT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
162} GhosttyModeReportState;
163
164/**
165 * Encode a DECRPM (DEC Private Mode Report) response sequence.
166 *
167 * Writes a mode report escape sequence into the provided buffer.
168 * The generated sequence has the form:
169 * - DEC private mode: CSI ? Ps1 ; Ps2 $ y
170 * - ANSI mode: CSI Ps1 ; Ps2 $ y
171 *
172 * If the buffer is too small, the function returns GHOSTTY_OUT_OF_SPACE
173 * and writes the required buffer size to @p out_written. The caller can
174 * then retry with a sufficiently sized buffer.
175 *
176 * @param mode The mode identifying the mode to report on
177 * @param state The report state for this mode
178 * @param buf Output buffer to write the encoded sequence into (may be NULL)
179 * @param buf_len Size of the output buffer in bytes
180 * @param[out] out_written On success, the number of bytes written. On
181 * GHOSTTY_OUT_OF_SPACE, the required buffer size.
182 * @return GHOSTTY_SUCCESS on success, GHOSTTY_OUT_OF_SPACE if the buffer
183 * is too small
184 */
185GHOSTTY_API GhosttyResult ghostty_mode_report_encode(
186 GhosttyMode mode,
187 GhosttyModeReportState state,
188 char* buf,
189 size_t buf_len,
190 size_t* out_written);
191
192#ifdef __cplusplus
193}
194#endif
195
196/** @} */
197
198#endif /* GHOSTTY_VT_MODES_H */
apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/mouse.h deleted-70
......@@ -1,70 +0,0 @@
1/**
2 * @file mouse.h
3 *
4 * Mouse encoding module - encode mouse events into terminal escape sequences.
5 */
6
7#ifndef GHOSTTY_VT_MOUSE_H
8#define GHOSTTY_VT_MOUSE_H
9
10/** @defgroup mouse Mouse Encoding
11 *
12 * Utilities for encoding mouse events into terminal escape sequences,
13 * supporting X10, UTF-8, SGR, URxvt, and SGR-Pixels mouse protocols.
14 *
15 * ## Basic Usage
16 *
17 * 1. Create an encoder instance with ghostty_mouse_encoder_new().
18 * 2. Configure encoder options with ghostty_mouse_encoder_setopt() or
19 * ghostty_mouse_encoder_setopt_from_terminal().
20 * 3. For each mouse event:
21 * - Create a mouse event with ghostty_mouse_event_new().
22 * - Set event properties (action, button, modifiers, position).
23 * - Encode with ghostty_mouse_encoder_encode().
24 * - Free the event with ghostty_mouse_event_free() or reuse it.
25 * 4. Free the encoder with ghostty_mouse_encoder_free() when done.
26 *
27 * For a complete working example, see example/c-vt-encode-mouse in the
28 * repository.
29 *
30 * ## Example
31 *
32 * @snippet c-vt-encode-mouse/src/main.c mouse-encode
33 *
34 * ## Example: Encoding with Terminal State
35 *
36 * When you have a GhosttyTerminal, you can sync its tracking mode and
37 * output format into the encoder automatically:
38 *
39 * @code{.c}
40 * // Create a terminal and feed it some VT data that enables mouse tracking
41 * GhosttyTerminal terminal;
42 * ghostty_terminal_new(NULL, &terminal,
43 * (GhosttyTerminalOptions){.cols = 80, .rows = 24, .max_scrollback = 0});
44 *
45 * // Application might write data that enables mouse reporting, etc.
46 * ghostty_terminal_vt_write(terminal, vt_data, vt_len);
47 *
48 * // Create an encoder and sync its options from the terminal
49 * GhosttyMouseEncoder encoder;
50 * ghostty_mouse_encoder_new(NULL, &encoder);
51 * ghostty_mouse_encoder_setopt_from_terminal(encoder, terminal);
52 *
53 * // Encode a mouse event using the terminal-derived options
54 * char buf[128];
55 * size_t written = 0;
56 * ghostty_mouse_encoder_encode(encoder, event, buf, sizeof(buf), &written);
57 *
58 * ghostty_mouse_encoder_free(encoder);
59 * ghostty_terminal_free(terminal);
60 * @endcode
61 *
62 * @{
63 */
64
65#include <ghostty/vt/mouse/event.h>
66#include <ghostty/vt/mouse/encoder.h>
67
68/** @} */
69
70#endif /* GHOSTTY_VT_MOUSE_H */
apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/mouse/encoder.h deleted-214
......@@ -1,214 +0,0 @@
1/**
2 * @file encoder.h
3 *
4 * Mouse event encoding to terminal escape sequences.
5 */
6
7#ifndef GHOSTTY_VT_MOUSE_ENCODER_H
8#define GHOSTTY_VT_MOUSE_ENCODER_H
9
10#include <stdbool.h>
11#include <stddef.h>
12#include <stdint.h>
13#include <ghostty/vt/allocator.h>
14#include <ghostty/vt/mouse/event.h>
15#include <ghostty/vt/terminal.h>
16#include <ghostty/vt/types.h>
17
18/**
19 * Opaque handle to a mouse encoder instance.
20 *
21 * This handle represents a mouse encoder that converts normalized
22 * mouse events into terminal escape sequences.
23 *
24 * @ingroup mouse
25 */
26typedef struct GhosttyMouseEncoderImpl *GhosttyMouseEncoder;
27
28/**
29 * Mouse tracking mode.
30 *
31 * @ingroup mouse
32 */
33typedef enum GHOSTTY_ENUM_TYPED {
34 /** Mouse reporting disabled. */
35 GHOSTTY_MOUSE_TRACKING_NONE = 0,
36
37 /** X10 mouse mode. */
38 GHOSTTY_MOUSE_TRACKING_X10 = 1,
39
40 /** Normal mouse mode (button press/release only). */
41 GHOSTTY_MOUSE_TRACKING_NORMAL = 2,
42
43 /** Button-event tracking mode. */
44 GHOSTTY_MOUSE_TRACKING_BUTTON = 3,
45
46 /** Any-event tracking mode. */
47 GHOSTTY_MOUSE_TRACKING_ANY = 4,
48 GHOSTTY_MOUSE_TRACKING_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
49} GhosttyMouseTrackingMode;
50
51/**
52 * Mouse output format.
53 *
54 * @ingroup mouse
55 */
56typedef enum GHOSTTY_ENUM_TYPED {
57 GHOSTTY_MOUSE_FORMAT_X10 = 0,
58 GHOSTTY_MOUSE_FORMAT_UTF8 = 1,
59 GHOSTTY_MOUSE_FORMAT_SGR = 2,
60 GHOSTTY_MOUSE_FORMAT_URXVT = 3,
61 GHOSTTY_MOUSE_FORMAT_SGR_PIXELS = 4,
62 GHOSTTY_MOUSE_FORMAT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
63} GhosttyMouseFormat;
64
65/**
66 * Mouse encoder size and geometry context.
67 *
68 * This describes the rendered terminal geometry used to convert
69 * surface-space positions into encoded coordinates.
70 *
71 * @ingroup mouse
72 */
73typedef struct {
74 /** Size of this struct in bytes. Must be set to sizeof(GhosttyMouseEncoderSize). */
75 size_t size;
76
77 /** Full screen width in pixels. */
78 uint32_t screen_width;
79
80 /** Full screen height in pixels. */
81 uint32_t screen_height;
82
83 /** Cell width in pixels. Must be non-zero. */
84 uint32_t cell_width;
85
86 /** Cell height in pixels. Must be non-zero. */
87 uint32_t cell_height;
88
89 /** Top padding in pixels. */
90 uint32_t padding_top;
91
92 /** Bottom padding in pixels. */
93 uint32_t padding_bottom;
94
95 /** Right padding in pixels. */
96 uint32_t padding_right;
97
98 /** Left padding in pixels. */
99 uint32_t padding_left;
100} GhosttyMouseEncoderSize;
101
102/**
103 * Mouse encoder option identifiers.
104 *
105 * These values are used with ghostty_mouse_encoder_setopt() to configure
106 * the behavior of the mouse encoder.
107 *
108 * @ingroup mouse
109 */
110typedef enum GHOSTTY_ENUM_TYPED {
111 /** Mouse tracking mode (value: GhosttyMouseTrackingMode). */
112 GHOSTTY_MOUSE_ENCODER_OPT_EVENT = 0,
113
114 /** Mouse output format (value: GhosttyMouseFormat). */
115 GHOSTTY_MOUSE_ENCODER_OPT_FORMAT = 1,
116
117 /** Renderer size context (value: GhosttyMouseEncoderSize). */
118 GHOSTTY_MOUSE_ENCODER_OPT_SIZE = 2,
119
120 /** Whether any mouse button is currently pressed (value: bool). */
121 GHOSTTY_MOUSE_ENCODER_OPT_ANY_BUTTON_PRESSED = 3,
122
123 /** Whether to enable motion deduplication by last cell (value: bool). */
124 GHOSTTY_MOUSE_ENCODER_OPT_TRACK_LAST_CELL = 4,
125 GHOSTTY_MOUSE_ENCODER_OPT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
126} GhosttyMouseEncoderOption;
127
128/**
129 * Create a new mouse encoder instance.
130 *
131 * @param allocator Pointer to allocator, or NULL to use the default allocator
132 * @param encoder Pointer to store the created encoder handle
133 * @return GHOSTTY_SUCCESS on success, or an error code on failure
134 *
135 * @ingroup mouse
136 */
137GHOSTTY_API GhosttyResult ghostty_mouse_encoder_new(const GhosttyAllocator *allocator,
138 GhosttyMouseEncoder *encoder);
139
140/**
141 * Free a mouse encoder instance.
142 *
143 * @param encoder The encoder handle to free (may be NULL)
144 *
145 * @ingroup mouse
146 */
147GHOSTTY_API void ghostty_mouse_encoder_free(GhosttyMouseEncoder encoder);
148
149/**
150 * Set an option on the mouse encoder.
151 *
152 * A null pointer value does nothing. It does not reset to defaults.
153 *
154 * @param encoder The encoder handle, must not be NULL
155 * @param option The option to set
156 * @param value Pointer to option value (type depends on option)
157 *
158 * @ingroup mouse
159 */
160GHOSTTY_API void ghostty_mouse_encoder_setopt(GhosttyMouseEncoder encoder,
161 GhosttyMouseEncoderOption option,
162 const void *value);
163
164/**
165 * Set encoder options from a terminal's current state.
166 *
167 * This sets tracking mode and output format from terminal state.
168 * It does not modify size or any-button state.
169 *
170 * @param encoder The encoder handle, must not be NULL
171 * @param terminal The terminal handle, must not be NULL
172 *
173 * @ingroup mouse
174 */
175GHOSTTY_API void ghostty_mouse_encoder_setopt_from_terminal(GhosttyMouseEncoder encoder,
176 GhosttyTerminal terminal);
177
178/**
179 * Reset internal encoder state.
180 *
181 * This clears motion deduplication state (last tracked cell).
182 *
183 * @param encoder The encoder handle (may be NULL)
184 *
185 * @ingroup mouse
186 */
187GHOSTTY_API void ghostty_mouse_encoder_reset(GhosttyMouseEncoder encoder);
188
189/**
190 * Encode a mouse event into a terminal escape sequence.
191 *
192 * Not all mouse events produce output. In such cases this returns
193 * GHOSTTY_SUCCESS with out_len set to 0.
194 *
195 * If the output buffer is too small, this returns GHOSTTY_OUT_OF_SPACE
196 * and out_len contains the required size.
197 *
198 * @param encoder The encoder handle, must not be NULL
199 * @param event The mouse event to encode, must not be NULL
200 * @param out_buf Buffer to write encoded bytes to, or NULL to query required size
201 * @param out_buf_size Size of out_buf in bytes
202 * @param out_len Pointer to store bytes written (or required bytes on failure)
203 * @return GHOSTTY_SUCCESS on success, GHOSTTY_OUT_OF_SPACE if buffer is too small,
204 * or another error code
205 *
206 * @ingroup mouse
207 */
208GHOSTTY_API GhosttyResult ghostty_mouse_encoder_encode(GhosttyMouseEncoder encoder,
209 GhosttyMouseEvent event,
210 char *out_buf,
211 size_t out_buf_size,
212 size_t *out_len);
213
214#endif /* GHOSTTY_VT_MOUSE_ENCODER_H */
apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/mouse/event.h deleted-195
......@@ -1,195 +0,0 @@
1/**
2 * @file event.h
3 *
4 * Mouse event representation and manipulation.
5 */
6
7#ifndef GHOSTTY_VT_MOUSE_EVENT_H
8#define GHOSTTY_VT_MOUSE_EVENT_H
9
10#include <stdbool.h>
11#include <ghostty/vt/allocator.h>
12#include <ghostty/vt/key/event.h>
13#include <ghostty/vt/types.h>
14
15/**
16 * Opaque handle to a mouse event.
17 *
18 * This handle represents a normalized mouse input event containing
19 * action, button, modifiers, and surface-space position.
20 *
21 * @ingroup mouse
22 */
23typedef struct GhosttyMouseEventImpl *GhosttyMouseEvent;
24
25/**
26 * Mouse event action type.
27 *
28 * @ingroup mouse
29 */
30typedef enum GHOSTTY_ENUM_TYPED {
31 /** Mouse button was pressed. */
32 GHOSTTY_MOUSE_ACTION_PRESS = 0,
33
34 /** Mouse button was released. */
35 GHOSTTY_MOUSE_ACTION_RELEASE = 1,
36
37 /** Mouse moved. */
38 GHOSTTY_MOUSE_ACTION_MOTION = 2,
39 GHOSTTY_MOUSE_ACTION_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
40} GhosttyMouseAction;
41
42/**
43 * Mouse button identity.
44 *
45 * @ingroup mouse
46 */
47typedef enum GHOSTTY_ENUM_TYPED {
48 GHOSTTY_MOUSE_BUTTON_UNKNOWN = 0,
49 GHOSTTY_MOUSE_BUTTON_LEFT = 1,
50 GHOSTTY_MOUSE_BUTTON_RIGHT = 2,
51 GHOSTTY_MOUSE_BUTTON_MIDDLE = 3,
52 GHOSTTY_MOUSE_BUTTON_FOUR = 4,
53 GHOSTTY_MOUSE_BUTTON_FIVE = 5,
54 GHOSTTY_MOUSE_BUTTON_SIX = 6,
55 GHOSTTY_MOUSE_BUTTON_SEVEN = 7,
56 GHOSTTY_MOUSE_BUTTON_EIGHT = 8,
57 GHOSTTY_MOUSE_BUTTON_NINE = 9,
58 GHOSTTY_MOUSE_BUTTON_TEN = 10,
59 GHOSTTY_MOUSE_BUTTON_ELEVEN = 11,
60 GHOSTTY_MOUSE_BUTTON_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
61} GhosttyMouseButton;
62
63/**
64 * Mouse position in surface-space pixels.
65 *
66 * @ingroup mouse
67 */
68typedef struct {
69 float x;
70 float y;
71} GhosttyMousePosition;
72
73/**
74 * Create a new mouse event instance.
75 *
76 * @param allocator Pointer to allocator, or NULL to use the default allocator
77 * @param event Pointer to store the created event handle
78 * @return GHOSTTY_SUCCESS on success, or an error code on failure
79 *
80 * @ingroup mouse
81 */
82GHOSTTY_API GhosttyResult ghostty_mouse_event_new(const GhosttyAllocator *allocator,
83 GhosttyMouseEvent *event);
84
85/**
86 * Free a mouse event instance.
87 *
88 * @param event The mouse event handle to free (may be NULL)
89 *
90 * @ingroup mouse
91 */
92GHOSTTY_API void ghostty_mouse_event_free(GhosttyMouseEvent event);
93
94/**
95 * Set the event action.
96 *
97 * @param event The event handle, must not be NULL
98 * @param action The action to set
99 *
100 * @ingroup mouse
101 */
102GHOSTTY_API void ghostty_mouse_event_set_action(GhosttyMouseEvent event,
103 GhosttyMouseAction action);
104
105/**
106 * Get the event action.
107 *
108 * @param event The event handle, must not be NULL
109 * @return The event action
110 *
111 * @ingroup mouse
112 */
113GHOSTTY_API GhosttyMouseAction ghostty_mouse_event_get_action(GhosttyMouseEvent event);
114
115/**
116 * Set the event button.
117 *
118 * This sets a concrete button identity for the event.
119 * To represent "no button" (for motion events), use
120 * ghostty_mouse_event_clear_button().
121 *
122 * @param event The event handle, must not be NULL
123 * @param button The button to set
124 *
125 * @ingroup mouse
126 */
127GHOSTTY_API void ghostty_mouse_event_set_button(GhosttyMouseEvent event,
128 GhosttyMouseButton button);
129
130/**
131 * Clear the event button.
132 *
133 * This sets the event button to "none".
134 *
135 * @param event The event handle, must not be NULL
136 *
137 * @ingroup mouse
138 */
139GHOSTTY_API void ghostty_mouse_event_clear_button(GhosttyMouseEvent event);
140
141/**
142 * Get the event button.
143 *
144 * @param event The event handle, must not be NULL
145 * @param out_button Output pointer for the button value (may be NULL)
146 * @return true if a button is set, false if no button is set
147 *
148 * @ingroup mouse
149 */
150GHOSTTY_API bool ghostty_mouse_event_get_button(GhosttyMouseEvent event,
151 GhosttyMouseButton *out_button);
152
153/**
154 * Set keyboard modifiers held during the event.
155 *
156 * @param event The event handle, must not be NULL
157 * @param mods Modifier bitmask
158 *
159 * @ingroup mouse
160 */
161GHOSTTY_API void ghostty_mouse_event_set_mods(GhosttyMouseEvent event,
162 GhosttyMods mods);
163
164/**
165 * Get keyboard modifiers held during the event.
166 *
167 * @param event The event handle, must not be NULL
168 * @return Modifier bitmask
169 *
170 * @ingroup mouse
171 */
172GHOSTTY_API GhosttyMods ghostty_mouse_event_get_mods(GhosttyMouseEvent event);
173
174/**
175 * Set the event position in surface-space pixels.
176 *
177 * @param event The event handle, must not be NULL
178 * @param position The position to set
179 *
180 * @ingroup mouse
181 */
182GHOSTTY_API void ghostty_mouse_event_set_position(GhosttyMouseEvent event,
183 GhosttyMousePosition position);
184
185/**
186 * Get the event position in surface-space pixels.
187 *
188 * @param event The event handle, must not be NULL
189 * @return The current event position
190 *
191 * @ingroup mouse
192 */
193GHOSTTY_API GhosttyMousePosition ghostty_mouse_event_get_position(GhosttyMouseEvent event);
194
195#endif /* GHOSTTY_VT_MOUSE_EVENT_H */
apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/osc.h deleted-215
......@@ -1,215 +0,0 @@
1/**
2 * @file osc.h
3 *
4 * OSC (Operating System Command) sequence parser and command handling.
5 */
6
7#ifndef GHOSTTY_VT_OSC_H
8#define GHOSTTY_VT_OSC_H
9
10#include <stdbool.h>
11#include <stddef.h>
12#include <stdint.h>
13#include <ghostty/vt/types.h>
14#include <ghostty/vt/allocator.h>
15
16/** @defgroup osc OSC Parser
17 *
18 * OSC (Operating System Command) sequence parser and command handling.
19 *
20 * The parser operates in a streaming fashion, processing input byte-by-byte
21 * to handle OSC sequences that may arrive in fragments across multiple reads.
22 * This interface makes it easy to integrate into most environments and avoids
23 * over-allocating buffers.
24 *
25 * ## Basic Usage
26 *
27 * 1. Create a parser instance with ghostty_osc_new()
28 * 2. Feed bytes to the parser using ghostty_osc_next()
29 * 3. Finalize parsing with ghostty_osc_end() to get the command
30 * 4. Query command type and extract data using ghostty_osc_command_type()
31 * and ghostty_osc_command_data()
32 * 5. Free the parser with ghostty_osc_free() when done
33 *
34 * @{
35 */
36
37/**
38 * OSC command types.
39 *
40 * @ingroup osc
41 */
42typedef enum GHOSTTY_ENUM_TYPED {
43 GHOSTTY_OSC_COMMAND_INVALID = 0,
44 GHOSTTY_OSC_COMMAND_CHANGE_WINDOW_TITLE = 1,
45 GHOSTTY_OSC_COMMAND_CHANGE_WINDOW_ICON = 2,
46 GHOSTTY_OSC_COMMAND_SEMANTIC_PROMPT = 3,
47 GHOSTTY_OSC_COMMAND_CLIPBOARD_CONTENTS = 4,
48 GHOSTTY_OSC_COMMAND_REPORT_PWD = 5,
49 GHOSTTY_OSC_COMMAND_MOUSE_SHAPE = 6,
50 GHOSTTY_OSC_COMMAND_COLOR_OPERATION = 7,
51 GHOSTTY_OSC_COMMAND_KITTY_COLOR_PROTOCOL = 8,
52 GHOSTTY_OSC_COMMAND_SHOW_DESKTOP_NOTIFICATION = 9,
53 GHOSTTY_OSC_COMMAND_HYPERLINK_START = 10,
54 GHOSTTY_OSC_COMMAND_HYPERLINK_END = 11,
55 GHOSTTY_OSC_COMMAND_CONEMU_SLEEP = 12,
56 GHOSTTY_OSC_COMMAND_CONEMU_SHOW_MESSAGE_BOX = 13,
57 GHOSTTY_OSC_COMMAND_CONEMU_CHANGE_TAB_TITLE = 14,
58 GHOSTTY_OSC_COMMAND_CONEMU_PROGRESS_REPORT = 15,
59 GHOSTTY_OSC_COMMAND_CONEMU_WAIT_INPUT = 16,
60 GHOSTTY_OSC_COMMAND_CONEMU_GUIMACRO = 17,
61 GHOSTTY_OSC_COMMAND_CONEMU_RUN_PROCESS = 18,
62 GHOSTTY_OSC_COMMAND_CONEMU_OUTPUT_ENVIRONMENT_VARIABLE = 19,
63 GHOSTTY_OSC_COMMAND_CONEMU_XTERM_EMULATION = 20,
64 GHOSTTY_OSC_COMMAND_CONEMU_COMMENT = 21,
65 GHOSTTY_OSC_COMMAND_KITTY_TEXT_SIZING = 22,
66 GHOSTTY_OSC_COMMAND_TYPE_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
67} GhosttyOscCommandType;
68
69/**
70 * OSC command data types.
71 *
72 * These values specify what type of data to extract from an OSC command
73 * using `ghostty_osc_command_data`.
74 *
75 * @ingroup osc
76 */
77typedef enum GHOSTTY_ENUM_TYPED {
78 /** Invalid data type. Never results in any data extraction. */
79 GHOSTTY_OSC_DATA_INVALID = 0,
80
81 /**
82 * Window title string data.
83 *
84 * Valid for: GHOSTTY_OSC_COMMAND_CHANGE_WINDOW_TITLE
85 *
86 * Output type: const char ** (pointer to null-terminated string)
87 *
88 * Lifetime: Valid until the next call to any ghostty_osc_* function with
89 * the same parser instance. Memory is owned by the parser.
90 */
91 GHOSTTY_OSC_DATA_CHANGE_WINDOW_TITLE_STR = 1,
92 GHOSTTY_OSC_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
93} GhosttyOscCommandData;
94
95/**
96 * Create a new OSC parser instance.
97 *
98 * Creates a new OSC (Operating System Command) parser using the provided
99 * allocator. The parser must be freed using ghostty_vt_osc_free() when
100 * no longer needed.
101 *
102 * @param allocator Pointer to the allocator to use for memory management, or NULL to use the default allocator
103 * @param parser Pointer to store the created parser handle
104 * @return GHOSTTY_SUCCESS on success, or an error code on failure
105 *
106 * @ingroup osc
107 */
108GHOSTTY_API GhosttyResult ghostty_osc_new(const GhosttyAllocator *allocator, GhosttyOscParser *parser);
109
110/**
111 * Free an OSC parser instance.
112 *
113 * Releases all resources associated with the OSC parser. After this call,
114 * the parser handle becomes invalid and must not be used.
115 *
116 * @param parser The parser handle to free (may be NULL)
117 *
118 * @ingroup osc
119 */
120GHOSTTY_API void ghostty_osc_free(GhosttyOscParser parser);
121
122/**
123 * Reset an OSC parser instance to its initial state.
124 *
125 * Resets the parser state, clearing any partially parsed OSC sequences
126 * and returning the parser to its initial state. This is useful for
127 * reusing a parser instance or recovering from parse errors.
128 *
129 * @param parser The parser handle to reset, must not be null.
130 *
131 * @ingroup osc
132 */
133GHOSTTY_API void ghostty_osc_reset(GhosttyOscParser parser);
134
135/**
136 * Parse the next byte in an OSC sequence.
137 *
138 * Processes a single byte as part of an OSC sequence. The parser maintains
139 * internal state to track the progress through the sequence. Call this
140 * function for each byte in the sequence data.
141 *
142 * When finished pumping the parser with bytes, call ghostty_osc_end
143 * to get the final result.
144 *
145 * @param parser The parser handle, must not be null.
146 * @param byte The next byte to parse
147 *
148 * @ingroup osc
149 */
150GHOSTTY_API void ghostty_osc_next(GhosttyOscParser parser, uint8_t byte);
151
152/**
153 * Finalize OSC parsing and retrieve the parsed command.
154 *
155 * Call this function after feeding all bytes of an OSC sequence to the parser
156 * using ghostty_osc_next() with the exception of the terminating character
157 * (ESC or ST). This function finalizes the parsing process and returns the
158 * parsed OSC command.
159 *
160 * The return value is never NULL. Invalid commands will return a command
161 * with type GHOSTTY_OSC_COMMAND_INVALID.
162 *
163 * The terminator parameter specifies the byte that terminated the OSC sequence
164 * (typically 0x07 for BEL or 0x5C for ST after ESC). This information is
165 * preserved in the parsed command so that responses can use the same terminator
166 * format for better compatibility with the calling program. For commands that
167 * do not require a response, this parameter is ignored and the resulting
168 * command will not retain the terminator information.
169 *
170 * The returned command handle is valid until the next call to any
171 * `ghostty_osc_*` function with the same parser instance with the exception
172 * of command introspection functions such as `ghostty_osc_command_type`.
173 *
174 * @param parser The parser handle, must not be null.
175 * @param terminator The terminating byte of the OSC sequence (0x07 for BEL, 0x5C for ST)
176 * @return Handle to the parsed OSC command
177 *
178 * @ingroup osc
179 */
180GHOSTTY_API GhosttyOscCommand ghostty_osc_end(GhosttyOscParser parser, uint8_t terminator);
181
182/**
183 * Get the type of an OSC command.
184 *
185 * Returns the type identifier for the given OSC command. This can be used
186 * to determine what kind of command was parsed and what data might be
187 * available from it.
188 *
189 * @param command The OSC command handle to query (may be NULL)
190 * @return The command type, or GHOSTTY_OSC_COMMAND_INVALID if command is NULL
191 *
192 * @ingroup osc
193 */
194GHOSTTY_API GhosttyOscCommandType ghostty_osc_command_type(GhosttyOscCommand command);
195
196/**
197 * Extract data from an OSC command.
198 *
199 * Extracts typed data from the given OSC command based on the specified
200 * data type. The output pointer must be of the appropriate type for the
201 * requested data kind. Valid command types, output types, and memory
202 * safety information are documented in the `GhosttyOscCommandData` enum.
203 *
204 * @param command The OSC command handle to query (may be NULL)
205 * @param data The type of data to extract
206 * @param out Pointer to store the extracted data (type depends on data parameter)
207 * @return true if data extraction was successful, false otherwise
208 *
209 * @ingroup osc
210 */
211GHOSTTY_API bool ghostty_osc_command_data(GhosttyOscCommand command, GhosttyOscCommandData data, void *out);
212
213/** @} */
214
215#endif /* GHOSTTY_VT_OSC_H */
apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/paste.h deleted-101
......@@ -1,101 +0,0 @@
1/**
2 * @file paste.h
3 *
4 * Paste utilities - validate and encode paste data for terminal input.
5 */
6
7#ifndef GHOSTTY_VT_PASTE_H
8#define GHOSTTY_VT_PASTE_H
9
10/** @defgroup paste Paste Utilities
11 *
12 * Utilities for validating and encoding paste data for terminal input.
13 *
14 * ## Basic Usage
15 *
16 * Use ghostty_paste_is_safe() to check if paste data contains potentially
17 * dangerous sequences before sending it to the terminal.
18 *
19 * Use ghostty_paste_encode() to encode paste data for writing to the pty,
20 * including bracketed paste wrapping and unsafe byte stripping.
21 *
22 * ## Examples
23 *
24 * ### Safety Check
25 *
26 * @snippet c-vt-paste/src/main.c paste-safety
27 *
28 * ### Encoding
29 *
30 * @snippet c-vt-paste/src/main.c paste-encode
31 *
32 * @{
33 */
34
35#include <stdbool.h>
36#include <stddef.h>
37#include <ghostty/vt/types.h>
38
39#ifdef __cplusplus
40extern "C" {
41#endif
42
43/**
44 * Check if paste data is safe to paste into the terminal.
45 *
46 * Data is considered unsafe if it contains:
47 * - Newlines (`\n`) which can inject commands
48 * - The bracketed paste end sequence (`\x1b[201~`) which can be used
49 * to exit bracketed paste mode and inject commands
50 *
51 * This check is conservative and considers data unsafe regardless of
52 * current terminal state.
53 *
54 * @param data The paste data to check (must not be NULL)
55 * @param len The length of the data in bytes
56 * @return true if the data is safe to paste, false otherwise
57 */
58GHOSTTY_API bool ghostty_paste_is_safe(const char* data, size_t len);
59
60/**
61 * Encode paste data for writing to the terminal pty.
62 *
63 * This function prepares paste data for terminal input by:
64 * - Stripping unsafe control bytes (NUL, ESC, DEL, etc.) by replacing
65 * them with spaces
66 * - Wrapping the data in bracketed paste sequences if @p bracketed is true
67 * - Replacing newlines with carriage returns if @p bracketed is false
68 *
69 * The input @p data buffer is modified in place during encoding. The
70 * encoded result (potentially with bracketed paste prefix/suffix) is
71 * written to the output buffer.
72 *
73 * If the output buffer is too small, the function returns
74 * GHOSTTY_OUT_OF_SPACE and sets the required size in @p out_written.
75 * The caller can then retry with a sufficiently sized buffer.
76 *
77 * @param data The paste data to encode (modified in place, may be NULL)
78 * @param data_len The length of the input data in bytes
79 * @param bracketed Whether bracketed paste mode is active
80 * @param buf Output buffer to write the encoded result into (may be NULL)
81 * @param buf_len Size of the output buffer in bytes
82 * @param[out] out_written On success, the number of bytes written. On
83 * GHOSTTY_OUT_OF_SPACE, the required buffer size.
84 * @return GHOSTTY_SUCCESS on success, GHOSTTY_OUT_OF_SPACE if the buffer
85 * is too small
86 */
87GHOSTTY_API GhosttyResult ghostty_paste_encode(
88 char* data,
89 size_t data_len,
90 bool bracketed,
91 char* buf,
92 size_t buf_len,
93 size_t* out_written);
94
95#ifdef __cplusplus
96}
97#endif
98
99/** @} */
100
101#endif /* GHOSTTY_VT_PASTE_H */
apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/point.h deleted-89
......@@ -1,89 +0,0 @@
1/**
2 * @file point.h
3 *
4 * Terminal point types for referencing locations in the terminal grid.
5 */
6
7#ifndef GHOSTTY_VT_POINT_H
8#define GHOSTTY_VT_POINT_H
9
10#include <stdint.h>
11
12#ifdef __cplusplus
13extern "C" {
14#endif
15
16/** @defgroup point Point
17 *
18 * Types for referencing x/y positions in the terminal grid under
19 * different coordinate systems (active area, viewport, full screen,
20 * scrollback history).
21 *
22 * @{
23 */
24
25/**
26 * A coordinate in the terminal grid.
27 *
28 * @ingroup point
29 */
30typedef struct {
31 /** Column (0-indexed). */
32 uint16_t x;
33
34 /** Row (0-indexed). May exceed page size for screen/history tags. */
35 uint32_t y;
36} GhosttyPointCoordinate;
37
38/**
39 * Point reference tag.
40 *
41 * Determines which coordinate system a point uses.
42 *
43 * @ingroup point
44 */
45typedef enum GHOSTTY_ENUM_TYPED {
46 /** Active area where the cursor can move. */
47 GHOSTTY_POINT_TAG_ACTIVE = 0,
48
49 /** Visible viewport (changes when scrolled). */
50 GHOSTTY_POINT_TAG_VIEWPORT = 1,
51
52 /** Full screen including scrollback. */
53 GHOSTTY_POINT_TAG_SCREEN = 2,
54
55 /** Scrollback history only (before active area). */
56 GHOSTTY_POINT_TAG_HISTORY = 3,
57 GHOSTTY_POINT_TAG_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
58 } GhosttyPointTag;
59
60/**
61 * Point value union.
62 *
63 * @ingroup point
64 */
65typedef union {
66 /** Coordinate (used for all tag variants). */
67 GhosttyPointCoordinate coordinate;
68
69 /** Padding for ABI compatibility. Do not use. */
70 uint64_t _padding[2];
71} GhosttyPointValue;
72
73/**
74 * Tagged union for a point in the terminal grid.
75 *
76 * @ingroup point
77 */
78typedef struct {
79 GhosttyPointTag tag;
80 GhosttyPointValue value;
81} GhosttyPoint;
82
83/** @} */
84
85#ifdef __cplusplus
86}
87#endif
88
89#endif /* GHOSTTY_VT_POINT_H */
apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/render.h deleted-729
......@@ -1,729 +0,0 @@
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
19extern "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 * ## Dirty Tracking
43 *
44 * Dirty tracking is a key feature of the render state that allows renderers
45 * to efficiently determine what parts of the screen have changed and only
46 * redraw changed regions.
47 *
48 * The render state API keeps track of dirty state at two independent layers:
49 * a global dirty state that indicates whether the entire frame is clean,
50 * partially dirty, or fully dirty, and a per-row dirty state that allows
51 * tracking which rows in a partially dirty frame have changed.
52 *
53 * The user of the render state API is expected to unset both of these.
54 * The `update` call does not unset dirty state, it only updates it.
55 *
56 * An extremely important detail: setting one dirty state doesn't unset
57 * the other. For example, setting the global dirty state to false does not
58 * reset the row-level dirty flags. So, the caller of the render state API must
59 * be careful to manage both layers of dirty state correctly.
60 *
61 * ## Examples
62 *
63 * ### Creating and updating render state
64 * @snippet c-vt-render/src/main.c render-state-update
65 *
66 * ### Checking dirty state
67 * @snippet c-vt-render/src/main.c render-dirty-check
68 *
69 * ### Reading colors
70 * @snippet c-vt-render/src/main.c render-colors
71 *
72 * ### Reading cursor state
73 * @snippet c-vt-render/src/main.c render-cursor
74 *
75 * ### Iterating rows and cells
76 * @snippet c-vt-render/src/main.c render-row-iterate
77 *
78 * ### Resetting dirty state after rendering
79 * @snippet c-vt-render/src/main.c render-dirty-reset
80 *
81 * @{
82 */
83
84/**
85 * Dirty state of a render state after update.
86 *
87 * @ingroup render
88 */
89typedef enum GHOSTTY_ENUM_TYPED {
90 /** Not dirty at all; rendering can be skipped. */
91 GHOSTTY_RENDER_STATE_DIRTY_FALSE = 0,
92
93 /** Some rows changed; renderer can redraw incrementally. */
94 GHOSTTY_RENDER_STATE_DIRTY_PARTIAL = 1,
95
96 /** Global state changed; renderer should redraw everything. */
97 GHOSTTY_RENDER_STATE_DIRTY_FULL = 2,
98 GHOSTTY_RENDER_STATE_DIRTY_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
99} GhosttyRenderStateDirty;
100
101/**
102 * Visual style of the cursor.
103 *
104 * @ingroup render
105 */
106typedef enum GHOSTTY_ENUM_TYPED {
107 /** Bar cursor (DECSCUSR 5, 6). */
108 GHOSTTY_RENDER_STATE_CURSOR_VISUAL_STYLE_BAR = 0,
109
110 /** Block cursor (DECSCUSR 1, 2). */
111 GHOSTTY_RENDER_STATE_CURSOR_VISUAL_STYLE_BLOCK = 1,
112
113 /** Underline cursor (DECSCUSR 3, 4). */
114 GHOSTTY_RENDER_STATE_CURSOR_VISUAL_STYLE_UNDERLINE = 2,
115
116 /** Hollow block cursor. */
117 GHOSTTY_RENDER_STATE_CURSOR_VISUAL_STYLE_BLOCK_HOLLOW = 3,
118 GHOSTTY_RENDER_STATE_CURSOR_VISUAL_STYLE_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
119} GhosttyRenderStateCursorVisualStyle;
120
121/**
122 * Queryable data kinds for ghostty_render_state_get().
123 *
124 * @ingroup render
125 */
126typedef enum GHOSTTY_ENUM_TYPED {
127 /** Invalid / sentinel value. */
128 GHOSTTY_RENDER_STATE_DATA_INVALID = 0,
129
130 /** Viewport width in cells (uint16_t). */
131 GHOSTTY_RENDER_STATE_DATA_COLS = 1,
132
133 /** Viewport height in cells (uint16_t). */
134 GHOSTTY_RENDER_STATE_DATA_ROWS = 2,
135
136 /** Current dirty state (GhosttyRenderStateDirty). */
137 GHOSTTY_RENDER_STATE_DATA_DIRTY = 3,
138
139 /** Populate a pre-allocated GhosttyRenderStateRowIterator with row data
140 * from the render state (GhosttyRenderStateRowIterator). Row data is
141 * only valid as long as the underlying render state is not updated.
142 * It is unsafe to use row data after updating the render state.
143 * */
144 GHOSTTY_RENDER_STATE_DATA_ROW_ITERATOR = 4,
145
146 /** Default/current background color (GhosttyColorRgb). */
147 GHOSTTY_RENDER_STATE_DATA_COLOR_BACKGROUND = 5,
148
149 /** Default/current foreground color (GhosttyColorRgb). */
150 GHOSTTY_RENDER_STATE_DATA_COLOR_FOREGROUND = 6,
151
152 /** Cursor color when explicitly set by terminal state (GhosttyColorRgb).
153 * Returns GHOSTTY_INVALID_VALUE if no explicit cursor color is set;
154 * use COLOR_CURSOR_HAS_VALUE to check first. */
155 GHOSTTY_RENDER_STATE_DATA_COLOR_CURSOR = 7,
156
157 /** Whether an explicit cursor color is set (bool). */
158 GHOSTTY_RENDER_STATE_DATA_COLOR_CURSOR_HAS_VALUE = 8,
159
160 /** The active 256-color palette (GhosttyColorRgb[256]). */
161 GHOSTTY_RENDER_STATE_DATA_COLOR_PALETTE = 9,
162
163 /** The visual style of the cursor (GhosttyRenderStateCursorVisualStyle). */
164 GHOSTTY_RENDER_STATE_DATA_CURSOR_VISUAL_STYLE = 10,
165
166 /** Whether the cursor is visible based on terminal modes (bool). */
167 GHOSTTY_RENDER_STATE_DATA_CURSOR_VISIBLE = 11,
168
169 /** Whether the cursor should blink based on terminal modes (bool). */
170 GHOSTTY_RENDER_STATE_DATA_CURSOR_BLINKING = 12,
171
172 /** Whether the cursor is at a password input field (bool). */
173 GHOSTTY_RENDER_STATE_DATA_CURSOR_PASSWORD_INPUT = 13,
174
175 /** Whether the cursor is visible within the viewport (bool).
176 * If false, the cursor viewport position values are undefined. */
177 GHOSTTY_RENDER_STATE_DATA_CURSOR_VIEWPORT_HAS_VALUE = 14,
178
179 /** Cursor viewport x position in cells (uint16_t).
180 * Only valid when CURSOR_VIEWPORT_HAS_VALUE is true. */
181 GHOSTTY_RENDER_STATE_DATA_CURSOR_VIEWPORT_X = 15,
182
183 /** Cursor viewport y position in cells (uint16_t).
184 * Only valid when CURSOR_VIEWPORT_HAS_VALUE is true. */
185 GHOSTTY_RENDER_STATE_DATA_CURSOR_VIEWPORT_Y = 16,
186
187 /** Whether the cursor is on the tail of a wide character (bool).
188 * Only valid when CURSOR_VIEWPORT_HAS_VALUE is true. */
189 GHOSTTY_RENDER_STATE_DATA_CURSOR_VIEWPORT_WIDE_TAIL = 17,
190 GHOSTTY_RENDER_STATE_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
191} GhosttyRenderStateData;
192
193/**
194 * Settable options for ghostty_render_state_set().
195 *
196 * @ingroup render
197 */
198typedef enum GHOSTTY_ENUM_TYPED {
199 /** Set dirty state (GhosttyRenderStateDirty). */
200 GHOSTTY_RENDER_STATE_OPTION_DIRTY = 0,
201 GHOSTTY_RENDER_STATE_OPTION_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
202} GhosttyRenderStateOption;
203
204/**
205 * Queryable data kinds for ghostty_render_state_row_get().
206 *
207 * @ingroup render
208 */
209typedef enum GHOSTTY_ENUM_TYPED {
210 /** Invalid / sentinel value. */
211 GHOSTTY_RENDER_STATE_ROW_DATA_INVALID = 0,
212
213 /** Whether the current row is dirty (bool). */
214 GHOSTTY_RENDER_STATE_ROW_DATA_DIRTY = 1,
215
216 /** The raw row value (GhosttyRow). */
217 GHOSTTY_RENDER_STATE_ROW_DATA_RAW = 2,
218
219 /** Populate a pre-allocated GhosttyRenderStateRowCells with cell data for
220 * the current row (GhosttyRenderStateRowCells). Cell data is only
221 * valid as long as the underlying render state is not updated.
222 * It is unsafe to use cell data after updating the render state. */
223 GHOSTTY_RENDER_STATE_ROW_DATA_CELLS = 3,
224
225 /** Row-local selected cell range (GhosttyRenderStateRowSelection). */
226 GHOSTTY_RENDER_STATE_ROW_DATA_SELECTION = 4,
227 GHOSTTY_RENDER_STATE_ROW_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
228} GhosttyRenderStateRowData;
229
230/**
231 * Settable options for ghostty_render_state_row_set().
232 *
233 * @ingroup render
234 */
235typedef enum GHOSTTY_ENUM_TYPED {
236 /** Set dirty state for the current row (bool). */
237 GHOSTTY_RENDER_STATE_ROW_OPTION_DIRTY = 0,
238 GHOSTTY_RENDER_STATE_ROW_OPTION_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
239} GhosttyRenderStateRowOption;
240
241/**
242 * Row-local selection range.
243 *
244 * This struct uses the sized-struct ABI pattern. Initialize with
245 * GHOSTTY_INIT_SIZED(GhosttyRenderStateRowSelection) before querying
246 * GHOSTTY_RENDER_STATE_ROW_DATA_SELECTION.
247 *
248 * Querying GHOSTTY_RENDER_STATE_ROW_DATA_SELECTION returns GHOSTTY_NO_VALUE
249 * if the current row does not intersect the current selection.
250 *
251 * @ingroup render
252 */
253typedef struct {
254 /** Size of this struct in bytes. Must be set to sizeof(GhosttyRenderStateRowSelection). */
255 size_t size;
256
257 /** Start column of the row-local selection range, inclusive. */
258 uint16_t start_x;
259
260 /** End column of the row-local selection range, inclusive. */
261 uint16_t end_x;
262} GhosttyRenderStateRowSelection;
263
264/**
265 * Render-state color information.
266 *
267 * This struct uses the sized-struct ABI pattern. Initialize with
268 * GHOSTTY_INIT_SIZED(GhosttyRenderStateColors) before calling
269 * ghostty_render_state_colors_get().
270 *
271 * Example:
272 * @code
273 * GhosttyRenderStateColors colors = GHOSTTY_INIT_SIZED(GhosttyRenderStateColors);
274 * GhosttyResult result = ghostty_render_state_colors_get(state, &colors);
275 * @endcode
276 *
277 * @ingroup render
278 */
279typedef struct {
280 /** Size of this struct in bytes. Must be set to sizeof(GhosttyRenderStateColors). */
281 size_t size;
282
283 /** The default/current background color for the render state. */
284 GhosttyColorRgb background;
285
286 /** The default/current foreground color for the render state. */
287 GhosttyColorRgb foreground;
288
289 /** The cursor color when explicitly set by terminal state. */
290 GhosttyColorRgb cursor;
291
292 /**
293 * True when cursor contains a valid explicit cursor color value.
294 * If this is false, the cursor color should be ignored; it will
295 * contain undefined data.
296 * */
297 bool cursor_has_value;
298
299 /** The active 256-color palette for this render state. */
300 GhosttyColorRgb palette[256];
301} GhosttyRenderStateColors;
302
303/**
304 * Create a new render state instance.
305 *
306 * @param allocator Pointer to allocator, or NULL to use the default allocator
307 * @param state Pointer to store the created render state handle
308 * @return GHOSTTY_SUCCESS on success, GHOSTTY_OUT_OF_MEMORY on allocation
309 * failure
310 *
311 * @ingroup render
312 */
313GHOSTTY_API GhosttyResult ghostty_render_state_new(const GhosttyAllocator* allocator,
314 GhosttyRenderState* state);
315
316/**
317 * Free a render state instance.
318 *
319 * Releases all resources associated with the render state. After this call,
320 * the render state handle becomes invalid.
321 *
322 * @param state The render state handle to free (may be NULL)
323 *
324 * @ingroup render
325 */
326GHOSTTY_API void ghostty_render_state_free(GhosttyRenderState state);
327
328/**
329 * Update a render state instance from a terminal.
330 *
331 * This consumes terminal/screen dirty state in the same way as the internal
332 * render state update path.
333 *
334 * @param state The render state handle (NULL returns GHOSTTY_INVALID_VALUE)
335 * @param terminal The terminal handle to read from (NULL returns GHOSTTY_INVALID_VALUE)
336 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if `state` or
337 * `terminal` is NULL, GHOSTTY_OUT_OF_MEMORY if updating the state requires
338 * allocation and that allocation fails
339 *
340 * @ingroup render
341 */
342GHOSTTY_API GhosttyResult ghostty_render_state_update(GhosttyRenderState state,
343 GhosttyTerminal terminal);
344
345/**
346 * Get a value from a render state.
347 *
348 * The `out` pointer must point to a value of the type corresponding to the
349 * requested data kind (see GhosttyRenderStateData).
350 *
351 * @param state The render state handle (NULL returns GHOSTTY_INVALID_VALUE)
352 * @param data The data kind to query
353 * @param[out] out Pointer to receive the queried value
354 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if `state` is
355 * NULL or `data` is not a recognized enum value
356 *
357 * @ingroup render
358 */
359GHOSTTY_API GhosttyResult ghostty_render_state_get(GhosttyRenderState state,
360 GhosttyRenderStateData data,
361 void* out);
362
363/**
364 * Get multiple data fields from a render state in a single call.
365 *
366 * Each element in the keys array specifies a data kind, and the
367 * corresponding element in the values array receives the result.
368 *
369 * Processing stops at the first error; on success out_written
370 * is set to count, on error it is set to the index of the
371 * failing key (i.e. the number of values successfully written).
372 *
373 * @param state The render state handle (NULL returns GHOSTTY_INVALID_VALUE)
374 * @param count Number of key/value pairs
375 * @param keys Array of data kinds to query
376 * @param values Array of output pointers (types must match each key's
377 * documented output type)
378 * @param[out] out_written On return, receives the number of values
379 * successfully written (may be NULL)
380 * @return GHOSTTY_SUCCESS if all queries succeed
381 *
382 * @ingroup render
383 */
384GHOSTTY_API GhosttyResult ghostty_render_state_get_multi(
385 GhosttyRenderState state,
386 size_t count,
387 const GhosttyRenderStateData* keys,
388 void** values,
389 size_t* out_written);
390
391/**
392 * Set an option on a render state.
393 *
394 * The `value` pointer must point to a value of the type corresponding to the
395 * requested option kind (see GhosttyRenderStateOption).
396 *
397 * @param state The render state handle (NULL returns GHOSTTY_INVALID_VALUE)
398 * @param option The option to set
399 * @param[in] value Pointer to the value to set (NULL returns
400 * GHOSTTY_INVALID_VALUE)
401 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if `state` or
402 * `value` is NULL
403 *
404 * @ingroup render
405 */
406GHOSTTY_API GhosttyResult ghostty_render_state_set(GhosttyRenderState state,
407 GhosttyRenderStateOption option,
408 const void* value);
409
410/**
411 * Get the current color information from a render state.
412 *
413 * This writes as many fields as fit in the caller-provided sized struct.
414 * `out_colors->size` must be set by the caller (typically via
415 * GHOSTTY_INIT_SIZED(GhosttyRenderStateColors)).
416 *
417 * @param state The render state handle (NULL returns GHOSTTY_INVALID_VALUE)
418 * @param[out] out_colors Sized output struct to receive render-state colors
419 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if `state` or
420 * `out_colors` is NULL, or if `out_colors->size` is smaller than
421 * `sizeof(size_t)`
422 *
423 * @ingroup render
424 */
425GHOSTTY_API GhosttyResult ghostty_render_state_colors_get(GhosttyRenderState state,
426 GhosttyRenderStateColors* out_colors);
427
428/**
429 * Create a new row iterator instance.
430 *
431 * All fields except the allocator are left undefined until populated
432 * via ghostty_render_state_get() with
433 * GHOSTTY_RENDER_STATE_DATA_ROW_ITERATOR.
434 *
435 * @param allocator Pointer to allocator, or NULL to use the default allocator
436 * @param[out] out_iterator On success, receives the created iterator handle
437 * @return GHOSTTY_SUCCESS on success, GHOSTTY_OUT_OF_MEMORY on allocation
438 * failure
439 *
440 * @ingroup render
441 */
442GHOSTTY_API GhosttyResult ghostty_render_state_row_iterator_new(
443 const GhosttyAllocator* allocator,
444 GhosttyRenderStateRowIterator* out_iterator);
445
446/**
447 * Free a render-state row iterator.
448 *
449 * @param iterator The iterator handle to free (may be NULL)
450 *
451 * @ingroup render
452 */
453GHOSTTY_API void ghostty_render_state_row_iterator_free(GhosttyRenderStateRowIterator iterator);
454
455/**
456 * Move a render-state row iterator to the next row.
457 *
458 * Returns true if the iterator moved successfully and row data is
459 * available to read at the new position.
460 *
461 * @param iterator The iterator handle to advance (may be NULL)
462 * @return true if advanced to the next row, false if `iterator` is
463 * NULL or if the iterator has reached the end
464 *
465 * @ingroup render
466 */
467GHOSTTY_API bool ghostty_render_state_row_iterator_next(GhosttyRenderStateRowIterator iterator);
468
469/**
470 * Get a value from the current row in a render-state row iterator.
471 *
472 * The `out` pointer must point to a value of the type corresponding to the
473 * requested data kind (see GhosttyRenderStateRowData).
474 * Call ghostty_render_state_row_iterator_next() at least once before
475 * calling this function.
476 *
477 * @param iterator The iterator handle to query (NULL returns GHOSTTY_INVALID_VALUE)
478 * @param data The data kind to query
479 * @param[out] out Pointer to receive the queried value
480 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if
481 * `iterator` is NULL or the iterator is not positioned on a row
482 *
483 * @ingroup render
484 */
485GHOSTTY_API GhosttyResult ghostty_render_state_row_get(
486 GhosttyRenderStateRowIterator iterator,
487 GhosttyRenderStateRowData data,
488 void* out);
489
490/**
491 * Get multiple data fields from the current row in a single call.
492 *
493 * Each element in the keys array specifies a data kind, and the
494 * corresponding element in the values array receives the result.
495 *
496 * Processing stops at the first error; on success out_written
497 * is set to count, on error it is set to the index of the
498 * failing key (i.e. the number of values successfully written).
499 *
500 * @param iterator The iterator handle (NULL returns GHOSTTY_INVALID_VALUE)
501 * @param count Number of key/value pairs
502 * @param keys Array of data kinds to query
503 * @param values Array of output pointers (types must match each key's
504 * documented output type)
505 * @param[out] out_written On return, receives the number of values
506 * successfully written (may be NULL)
507 * @return GHOSTTY_SUCCESS if all queries succeed
508 *
509 * @ingroup render
510 */
511GHOSTTY_API GhosttyResult ghostty_render_state_row_get_multi(
512 GhosttyRenderStateRowIterator iterator,
513 size_t count,
514 const GhosttyRenderStateRowData* keys,
515 void** values,
516 size_t* out_written);
517
518/**
519 * Set an option on the current row in a render-state row iterator.
520 *
521 * The `value` pointer must point to a value of the type corresponding to the
522 * requested option kind (see GhosttyRenderStateRowOption).
523 * Call ghostty_render_state_row_iterator_next() at least once before
524 * calling this function.
525 *
526 * @param iterator The iterator handle to update (NULL returns GHOSTTY_INVALID_VALUE)
527 * @param option The option to set
528 * @param[in] value Pointer to the value to set (NULL returns
529 * GHOSTTY_INVALID_VALUE)
530 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if
531 * `iterator` is NULL or the iterator is not positioned on a row
532 *
533 * @ingroup render
534 */
535GHOSTTY_API GhosttyResult ghostty_render_state_row_set(
536 GhosttyRenderStateRowIterator iterator,
537 GhosttyRenderStateRowOption option,
538 const void* value);
539
540/**
541 * Create a new row cells instance.
542 *
543 * All fields except the allocator are left undefined until populated
544 * via ghostty_render_state_row_get() with
545 * GHOSTTY_RENDER_STATE_ROW_DATA_CELLS.
546 *
547 * You can reuse this value repeatedly with ghostty_render_state_row_get() to
548 * avoid allocating a new cells container for every row.
549 *
550 * @param allocator Pointer to allocator, or NULL to use the default allocator
551 * @param[out] out_cells On success, receives the created row cells handle
552 * @return GHOSTTY_SUCCESS on success, GHOSTTY_OUT_OF_MEMORY on allocation
553 * failure
554 *
555 * @ingroup render
556 */
557GHOSTTY_API GhosttyResult ghostty_render_state_row_cells_new(
558 const GhosttyAllocator* allocator,
559 GhosttyRenderStateRowCells* out_cells);
560
561/**
562 * Queryable data kinds for ghostty_render_state_row_cells_get().
563 *
564 * @ingroup render
565 */
566typedef enum GHOSTTY_ENUM_TYPED {
567 /** Invalid / sentinel value. */
568 GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_INVALID = 0,
569
570 /** The raw cell value (GhosttyCell). */
571 GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_RAW = 1,
572
573 /** The style for the current cell (GhosttyStyle). */
574 GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_STYLE = 2,
575
576 /** The total number of grapheme codepoints including the base codepoint
577 * (uint32_t). Returns 0 if the cell has no text. */
578 GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_GRAPHEMES_LEN = 3,
579
580 /** Write grapheme codepoints into a caller-provided buffer (uint32_t*).
581 * The buffer must be at least graphemes_len elements. The base codepoint
582 * is written first, followed by any extra codepoints. */
583 GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_GRAPHEMES_BUF = 4,
584
585 /** The resolved background color of the cell (GhosttyColorRgb).
586 * Flattens the three possible sources: content-tag bg_color_rgb,
587 * content-tag bg_color_palette (looked up in the palette), or the
588 * style's bg_color. Returns GHOSTTY_INVALID_VALUE if the cell has
589 * no background color, in which case the caller should use whatever
590 * default background color it wants (e.g. the terminal background). */
591 GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_BG_COLOR = 5,
592
593 /** The resolved foreground color of the cell (GhosttyColorRgb).
594 * Resolves palette indices through the palette. Bold color handling
595 * is not applied; the caller should handle bold styling separately.
596 * Returns GHOSTTY_INVALID_VALUE if the cell has no explicit foreground
597 * color, in which case the caller should use whatever default foreground
598 * color it wants (e.g. the terminal foreground). */
599 GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_FG_COLOR = 6,
600
601 /** Whether the cell is contained within the current selection (bool).
602 * This returns true when the cell's column is within the current row's
603 * row-local selection range, and false otherwise. Rendering policy for
604 * selected cells (colors, inversion, etc.) is left to the caller.
605 *
606 * Renderers that can draw cells in spans may be more efficient querying
607 * GHOSTTY_RENDER_STATE_ROW_DATA_SELECTION once per row and applying that
608 * range directly, avoiding one C API call per cell for selection state. */
609 GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_SELECTED = 7,
610
611 /** Whether the cell has any explicit styling (bool).
612 * This is equivalent to querying the raw cell's
613 * GHOSTTY_CELL_DATA_HAS_STYLING value, but avoids materializing the raw
614 * GhosttyCell for renderers that only need to know whether fetching the
615 * full style is necessary. */
616 GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_HAS_STYLING = 8,
617
618 /**
619 * Encode the current cell's full grapheme cluster as UTF-8 into a
620 * caller-provided buffer (GhosttyBuffer).
621 *
622 * The base codepoint is encoded first, followed by any extra grapheme
623 * codepoints. Returns GHOSTTY_SUCCESS with len=0 when the cell has no text.
624 *
625 * If ptr is NULL or cap is too small for a non-empty cell, returns
626 * GHOSTTY_OUT_OF_SPACE without writing any bytes and sets len to the required
627 * buffer size in bytes.
628 */
629 GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_GRAPHEMES_UTF8 = 9,
630 GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
631} GhosttyRenderStateRowCellsData;
632
633/**
634 * Move a render-state row cells iterator to the next cell.
635 *
636 * Returns true if the iterator moved successfully and cell data is
637 * available to read at the new position.
638 *
639 * @param cells The row cells handle to advance (may be NULL)
640 * @return true if advanced to the next cell, false if `cells` is
641 * NULL or if the iterator has reached the end
642 *
643 * @ingroup render
644 */
645GHOSTTY_API bool ghostty_render_state_row_cells_next(GhosttyRenderStateRowCells cells);
646
647/**
648 * Move a render-state row cells iterator to a specific column.
649 *
650 * Positions the iterator at the given x (column) index so that
651 * subsequent reads return data for that cell.
652 *
653 * @param cells The row cells handle to reposition (NULL returns
654 * GHOSTTY_INVALID_VALUE)
655 * @param x The zero-based column index to select
656 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if `cells`
657 * is NULL or `x` is out of range
658 *
659 * @ingroup render
660 */
661GHOSTTY_API GhosttyResult ghostty_render_state_row_cells_select(
662 GhosttyRenderStateRowCells cells, uint16_t x);
663
664/**
665 * Get a value from the current cell in a render-state row cells iterator.
666 *
667 * The `out` pointer must point to a value of the type corresponding to the
668 * requested data kind (see GhosttyRenderStateRowCellsData).
669 * Call ghostty_render_state_row_cells_next() or
670 * ghostty_render_state_row_cells_select() at least once before
671 * calling this function.
672 *
673 * @param cells The row cells handle to query (NULL returns GHOSTTY_INVALID_VALUE)
674 * @param data The data kind to query
675 * @param[out] out Pointer to receive the queried value
676 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if
677 * `cells` is NULL or the iterator is not positioned on a cell
678 *
679 * @ingroup render
680 */
681GHOSTTY_API GhosttyResult ghostty_render_state_row_cells_get(
682 GhosttyRenderStateRowCells cells,
683 GhosttyRenderStateRowCellsData data,
684 void* out);
685
686/**
687 * Get multiple data fields from the current cell in a single call.
688 *
689 * Each element in the keys array specifies a data kind, and the
690 * corresponding element in the values array receives the result.
691 *
692 * Processing stops at the first error; on success out_written
693 * is set to count, on error it is set to the index of the
694 * failing key (i.e. the number of values successfully written).
695 *
696 * @param cells The row cells handle (NULL returns GHOSTTY_INVALID_VALUE)
697 * @param count Number of key/value pairs
698 * @param keys Array of data kinds to query
699 * @param values Array of output pointers (types must match each key's
700 * documented output type)
701 * @param[out] out_written On return, receives the number of values
702 * successfully written (may be NULL)
703 * @return GHOSTTY_SUCCESS if all queries succeed
704 *
705 * @ingroup render
706 */
707GHOSTTY_API GhosttyResult ghostty_render_state_row_cells_get_multi(
708 GhosttyRenderStateRowCells cells,
709 size_t count,
710 const GhosttyRenderStateRowCellsData* keys,
711 void** values,
712 size_t* out_written);
713
714/**
715 * Free a row cells instance.
716 *
717 * @param cells The row cells handle to free (may be NULL)
718 *
719 * @ingroup render
720 */
721GHOSTTY_API void ghostty_render_state_row_cells_free(GhosttyRenderStateRowCells cells);
722
723/** @} */
724
725#ifdef __cplusplus
726}
727#endif
728
729#endif /* GHOSTTY_VT_RENDER_H */
apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/screen.h deleted-400
......@@ -1,400 +0,0 @@
1/**
2 * @file screen.h
3 *
4 * Terminal screen cell and row types.
5 */
6
7#ifndef GHOSTTY_VT_SCREEN_H
8#define GHOSTTY_VT_SCREEN_H
9
10#include <stdbool.h>
11#include <stdint.h>
12#include <ghostty/vt/color.h>
13#include <ghostty/vt/types.h>
14
15#ifdef __cplusplus
16extern "C" {
17#endif
18
19/** @defgroup screen Screen
20 *
21 * Terminal screen cell and row types.
22 *
23 * These types represent the contents of a terminal screen. A GhosttyCell
24 * is a single grid cell and a GhosttyRow is a single row. Both are opaque
25 * values whose fields are accessed via ghostty_cell_get() and
26 * ghostty_row_get() respectively.
27 *
28 * @{
29 */
30
31/**
32 * Opaque cell value.
33 *
34 * Represents a single terminal cell. The internal layout is opaque and
35 * must be queried via ghostty_cell_get(). Obtain cell values from
36 * terminal query APIs.
37 *
38 * @ingroup screen
39 */
40typedef uint64_t GhosttyCell;
41
42/**
43 * Opaque row value.
44 *
45 * Represents a single terminal row. The internal layout is opaque and
46 * must be queried via ghostty_row_get(). Obtain row values from
47 * terminal query APIs.
48 *
49 * @ingroup screen
50 */
51typedef uint64_t GhosttyRow;
52
53/**
54 * Cell content tag.
55 *
56 * Describes what kind of content a cell holds.
57 *
58 * @ingroup screen
59 */
60typedef enum GHOSTTY_ENUM_TYPED {
61 /** A single codepoint (may be zero for empty). */
62 GHOSTTY_CELL_CONTENT_CODEPOINT = 0,
63
64 /** A codepoint that is part of a multi-codepoint grapheme cluster. */
65 GHOSTTY_CELL_CONTENT_CODEPOINT_GRAPHEME = 1,
66
67 /** No text; background color from palette. */
68 GHOSTTY_CELL_CONTENT_BG_COLOR_PALETTE = 2,
69
70 /** No text; background color as RGB. */
71 GHOSTTY_CELL_CONTENT_BG_COLOR_RGB = 3,
72 GHOSTTY_CELL_CONTENT_TAG_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
73} GhosttyCellContentTag;
74
75/**
76 * Cell wide property.
77 *
78 * Describes the width behavior of a cell.
79 *
80 * @ingroup screen
81 */
82typedef enum GHOSTTY_ENUM_TYPED {
83 /** Not a wide character, cell width 1. */
84 GHOSTTY_CELL_WIDE_NARROW = 0,
85
86 /** Wide character, cell width 2. */
87 GHOSTTY_CELL_WIDE_WIDE = 1,
88
89 /** Spacer after wide character. Do not render. */
90 GHOSTTY_CELL_WIDE_SPACER_TAIL = 2,
91
92 /** Spacer at end of soft-wrapped line for a wide character. */
93 GHOSTTY_CELL_WIDE_SPACER_HEAD = 3,
94 GHOSTTY_CELL_WIDE_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
95} GhosttyCellWide;
96
97/**
98 * Semantic content type of a cell.
99 *
100 * Set by semantic prompt sequences (OSC 133) to distinguish between
101 * command output, user input, and shell prompt text.
102 *
103 * @ingroup screen
104 */
105typedef enum GHOSTTY_ENUM_TYPED {
106 /** Regular output content, such as command output. */
107 GHOSTTY_CELL_SEMANTIC_OUTPUT = 0,
108
109 /** Content that is part of user input. */
110 GHOSTTY_CELL_SEMANTIC_INPUT = 1,
111
112 /** Content that is part of a shell prompt. */
113 GHOSTTY_CELL_SEMANTIC_PROMPT = 2,
114 GHOSTTY_CELL_SEMANTIC_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
115} GhosttyCellSemanticContent;
116
117/**
118 * Cell data types.
119 *
120 * These values specify what type of data to extract from a cell
121 * using `ghostty_cell_get`.
122 *
123 * @ingroup screen
124 */
125typedef enum GHOSTTY_ENUM_TYPED {
126 /** Invalid data type. Never results in any data extraction. */
127 GHOSTTY_CELL_DATA_INVALID = 0,
128
129 /**
130 * The codepoint of the cell (0 if empty or bg-color-only).
131 *
132 * Output type: uint32_t *
133 */
134 GHOSTTY_CELL_DATA_CODEPOINT = 1,
135
136 /**
137 * The content tag describing what kind of content is in the cell.
138 *
139 * Output type: GhosttyCellContentTag *
140 */
141 GHOSTTY_CELL_DATA_CONTENT_TAG = 2,
142
143 /**
144 * The wide property of the cell.
145 *
146 * Output type: GhosttyCellWide *
147 */
148 GHOSTTY_CELL_DATA_WIDE = 3,
149
150 /**
151 * Whether the cell has text to render.
152 *
153 * Output type: bool *
154 */
155 GHOSTTY_CELL_DATA_HAS_TEXT = 4,
156
157 /**
158 * Whether the cell has non-default styling.
159 *
160 * Output type: bool *
161 */
162 GHOSTTY_CELL_DATA_HAS_STYLING = 5,
163
164 /**
165 * The style ID for the cell (for use with style lookups).
166 *
167 * Output type: uint16_t *
168 */
169 GHOSTTY_CELL_DATA_STYLE_ID = 6,
170
171 /**
172 * Whether the cell has a hyperlink.
173 *
174 * Output type: bool *
175 */
176 GHOSTTY_CELL_DATA_HAS_HYPERLINK = 7,
177
178 /**
179 * Whether the cell is protected.
180 *
181 * Output type: bool *
182 */
183 GHOSTTY_CELL_DATA_PROTECTED = 8,
184
185 /**
186 * The semantic content type of the cell (from OSC 133).
187 *
188 * Output type: GhosttyCellSemanticContent *
189 */
190 GHOSTTY_CELL_DATA_SEMANTIC_CONTENT = 9,
191
192 /**
193 * The palette index for the cell's background color.
194 * Only valid when content_tag is GHOSTTY_CELL_CONTENT_BG_COLOR_PALETTE.
195 *
196 * Output type: GhosttyColorPaletteIndex *
197 */
198 GHOSTTY_CELL_DATA_COLOR_PALETTE = 10,
199
200 /**
201 * The RGB value for the cell's background color.
202 * Only valid when content_tag is GHOSTTY_CELL_CONTENT_BG_COLOR_RGB.
203 *
204 * Output type: GhosttyColorRgb *
205 */
206 GHOSTTY_CELL_DATA_COLOR_RGB = 11,
207 GHOSTTY_CELL_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
208} GhosttyCellData;
209
210/**
211 * Row semantic prompt state.
212 *
213 * Indicates whether any cells in a row are part of a shell prompt,
214 * as reported by OSC 133 sequences.
215 *
216 * @ingroup screen
217 */
218typedef enum GHOSTTY_ENUM_TYPED {
219 /** No prompt cells in this row. */
220 GHOSTTY_ROW_SEMANTIC_NONE = 0,
221
222 /** Prompt cells exist and this is a primary prompt line. */
223 GHOSTTY_ROW_SEMANTIC_PROMPT = 1,
224
225 /** Prompt cells exist and this is a continuation line. */
226 GHOSTTY_ROW_SEMANTIC_PROMPT_CONTINUATION = 2,
227 GHOSTTY_ROW_SEMANTIC_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
228} GhosttyRowSemanticPrompt;
229
230/**
231 * Row data types.
232 *
233 * These values specify what type of data to extract from a row
234 * using `ghostty_row_get`.
235 *
236 * @ingroup screen
237 */
238typedef enum GHOSTTY_ENUM_TYPED {
239 /** Invalid data type. Never results in any data extraction. */
240 GHOSTTY_ROW_DATA_INVALID = 0,
241
242 /**
243 * Whether this row is soft-wrapped.
244 *
245 * Output type: bool *
246 */
247 GHOSTTY_ROW_DATA_WRAP = 1,
248
249 /**
250 * Whether this row is a continuation of a soft-wrapped row.
251 *
252 * Output type: bool *
253 */
254 GHOSTTY_ROW_DATA_WRAP_CONTINUATION = 2,
255
256 /**
257 * Whether any cells in this row have grapheme clusters.
258 *
259 * Output type: bool *
260 */
261 GHOSTTY_ROW_DATA_GRAPHEME = 3,
262
263 /**
264 * Whether any cells in this row have styling (may have false positives).
265 *
266 * Output type: bool *
267 */
268 GHOSTTY_ROW_DATA_STYLED = 4,
269
270 /**
271 * Whether any cells in this row have hyperlinks (may have false positives).
272 *
273 * Output type: bool *
274 */
275 GHOSTTY_ROW_DATA_HYPERLINK = 5,
276
277 /**
278 * The semantic prompt state of this row.
279 *
280 * Output type: GhosttyRowSemanticPrompt *
281 */
282 GHOSTTY_ROW_DATA_SEMANTIC_PROMPT = 6,
283
284 /**
285 * Whether this row contains a Kitty virtual placeholder.
286 *
287 * Output type: bool *
288 */
289 GHOSTTY_ROW_DATA_KITTY_VIRTUAL_PLACEHOLDER = 7,
290
291 /**
292 * Whether this row is dirty and requires a redraw.
293 *
294 * Output type: bool *
295 */
296 GHOSTTY_ROW_DATA_DIRTY = 8,
297 GHOSTTY_ROW_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
298} GhosttyRowData;
299
300/**
301 * Get data from a cell.
302 *
303 * Extracts typed data from the given cell based on the specified
304 * data type. The output pointer must be of the appropriate type for the
305 * requested data kind. Valid data types and output types are documented
306 * in the `GhosttyCellData` enum.
307 *
308 * @param cell The cell value
309 * @param data The type of data to extract
310 * @param out Pointer to store the extracted data (type depends on data parameter)
311 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the
312 * data type is invalid
313 *
314 * @ingroup screen
315 */
316GHOSTTY_API GhosttyResult ghostty_cell_get(GhosttyCell cell,
317 GhosttyCellData data,
318 void *out);
319
320/**
321 * Get multiple data fields from a cell in a single call.
322 *
323 * Each element in the keys array specifies a data kind, and the
324 * corresponding element in the values array receives the result.
325 *
326 * Processing stops at the first error; on success out_written
327 * is set to count, on error it is set to the index of the
328 * failing key (i.e. the number of values successfully written).
329 *
330 * @param cell The cell value
331 * @param count Number of key/value pairs
332 * @param keys Array of data kinds to query
333 * @param values Array of output pointers (types must match each key's
334 * documented output type)
335 * @param[out] out_written On return, receives the number of values
336 * successfully written (may be NULL)
337 * @return GHOSTTY_SUCCESS if all queries succeed
338 *
339 * @ingroup screen
340 */
341GHOSTTY_API GhosttyResult ghostty_cell_get_multi(GhosttyCell cell,
342 size_t count,
343 const GhosttyCellData* keys,
344 void** values,
345 size_t* out_written);
346
347/**
348 * Get data from a row.
349 *
350 * Extracts typed data from the given row based on the specified
351 * data type. The output pointer must be of the appropriate type for the
352 * requested data kind. Valid data types and output types are documented
353 * in the `GhosttyRowData` enum.
354 *
355 * @param row The row value
356 * @param data The type of data to extract
357 * @param out Pointer to store the extracted data (type depends on data parameter)
358 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the
359 * data type is invalid
360 *
361 * @ingroup screen
362 */
363GHOSTTY_API GhosttyResult ghostty_row_get(GhosttyRow row,
364 GhosttyRowData data,
365 void *out);
366
367/**
368 * Get multiple data fields from a row in a single call.
369 *
370 * Each element in the keys array specifies a data kind, and the
371 * corresponding element in the values array receives the result.
372 *
373 * Processing stops at the first error; on success out_written
374 * is set to count, on error it is set to the index of the
375 * failing key (i.e. the number of values successfully written).
376 *
377 * @param row The row value
378 * @param count Number of key/value pairs
379 * @param keys Array of data kinds to query
380 * @param values Array of output pointers (types must match each key's
381 * documented output type)
382 * @param[out] out_written On return, receives the number of values
383 * successfully written (may be NULL)
384 * @return GHOSTTY_SUCCESS if all queries succeed
385 *
386 * @ingroup screen
387 */
388GHOSTTY_API GhosttyResult ghostty_row_get_multi(GhosttyRow row,
389 size_t count,
390 const GhosttyRowData* keys,
391 void** values,
392 size_t* out_written);
393
394/** @} */
395
396#ifdef __cplusplus
397}
398#endif
399
400#endif /* GHOSTTY_VT_SCREEN_H */
apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/selection.h deleted-1061
......@@ -1,1061 +0,0 @@
1/**
2 * @file selection.h
3 *
4 * Selection range type for specifying a region of terminal content.
5 */
6
7#ifndef GHOSTTY_VT_SELECTION_H
8#define GHOSTTY_VT_SELECTION_H
9
10#include <stdbool.h>
11#include <stddef.h>
12#include <stdint.h>
13#include <ghostty/vt/allocator.h>
14#include <ghostty/vt/grid_ref.h>
15#include <ghostty/vt/point.h>
16#include <ghostty/vt/types.h>
17
18#ifdef __cplusplus
19extern "C" {
20#endif
21
22/** @defgroup selection Selection
23 *
24 * A snapshot selection range defined by two grid references that identifies
25 * a contiguous or rectangular region of terminal content.
26 *
27 * The start and end values are GhosttyGridRef values. They are therefore
28 * untracked grid references and inherit the same lifetime rules: they are
29 * only safe to use until the next mutating operation on the terminal that
30 * produced them, including freeing the terminal. To keep a selection valid
31 * across terminal mutations, callers must maintain tracked grid references
32 * for the endpoints and reconstruct a GhosttySelection from fresh snapshots
33 * when needed.
34 *
35 * Selection gestures provide a reusable state machine for turning UI pointer
36 * interactions into selection snapshots. A caller creates one
37 * GhosttySelectionGesture per active gesture stream, reuses typed
38 * GhosttySelectionGestureEvent objects for synthetic press, drag, release,
39 * autoscroll tick, and deep-press events, and applies each event with
40 * ghostty_selection_gesture_event(). The returned GhosttySelection is a
41 * snapshot; the embedder decides whether to render it, format/copy it, or
42 * install it as the terminal's active selection.
43 *
44 * ## Examples
45 *
46 * @snippet c-vt-selection/src/main.c selection-main
47 * @snippet c-vt-selection-gesture/src/main.c selection-gesture-main
48 *
49 * @{
50 */
51
52/**
53 * Opaque handle to state for interpreting terminal selection gestures.
54 *
55 * The gesture owns only the state required to interpret pointer events. Calls
56 * that use a gesture are not concurrency-safe and must be serialized with
57 * terminal mutations.
58 *
59 * @ingroup selection
60 */
61typedef struct GhosttySelectionGestureImpl* GhosttySelectionGesture;
62
63/**
64 * Opaque handle to reusable input data for selection gesture operations.
65 *
66 * Event options are set with ghostty_selection_gesture_event_set(). Individual
67 * gesture operations document which options are required or optional.
68 *
69 * @ingroup selection
70 */
71typedef struct GhosttySelectionGestureEventImpl* GhosttySelectionGestureEvent;
72
73/**
74 * A snapshot selection range defined by two grid references.
75 *
76 * Both endpoints are inclusive. The endpoints preserve selection direction
77 * and may be reversed; callers must not assume that start is the top-left
78 * endpoint or that end is the bottom-right endpoint.
79 *
80 * When rectangle is false, the endpoints describe a linear selection. When
81 * rectangle is true, the same endpoints are interpreted as opposite corners
82 * of a rectangular/block selection.
83 *
84 * The start and end values are untracked GhosttyGridRef snapshots and are
85 * only valid until the next mutating operation on the terminal that produced
86 * them unless the selection is reconstructed from tracked references.
87 *
88 * This is a sized struct. Use GHOSTTY_INIT_SIZED() to initialize it.
89 *
90 * @ingroup selection
91 */
92typedef struct {
93 /** Size of this struct in bytes. Must be set to sizeof(GhosttySelection). */
94 size_t size;
95
96 /**
97 * Start of the selection range (inclusive).
98 *
99 * This may be after end in terminal order. It is an untracked
100 * GhosttyGridRef snapshot and follows untracked grid-ref lifetime rules.
101 */
102 GhosttyGridRef start;
103
104 /**
105 * End of the selection range (inclusive).
106 *
107 * This may be before start in terminal order. It is an untracked
108 * GhosttyGridRef snapshot and follows untracked grid-ref lifetime rules.
109 */
110 GhosttyGridRef end;
111
112 /**
113 * Whether the endpoints are interpreted as a rectangular/block selection
114 * rather than a linear selection.
115 */
116 bool rectangle;
117} GhosttySelection;
118
119/**
120 * Options for deriving a word selection from a terminal grid reference.
121 *
122 * This is a sized struct. Use GHOSTTY_INIT_SIZED() to initialize it.
123 * If boundary_codepoints is NULL and boundary_codepoints_len is 0, Ghostty's
124 * default word-boundary codepoints are used. If boundary_codepoints_len is
125 * non-zero, boundary_codepoints must not be NULL.
126 *
127 * @ingroup selection
128 */
129typedef struct {
130 /** Size of this struct in bytes. Must be set to sizeof(GhosttyTerminalSelectWordOptions). */
131 size_t size;
132
133 /** Grid reference under which to derive the word selection. */
134 GhosttyGridRef ref;
135
136 /** Optional word-boundary codepoints as uint32_t scalar values. */
137 const uint32_t* boundary_codepoints;
138
139 /** Number of entries in boundary_codepoints. */
140 size_t boundary_codepoints_len;
141} GhosttyTerminalSelectWordOptions;
142
143/**
144 * Options for deriving the nearest word selection between two grid references.
145 *
146 * This is a sized struct. Use GHOSTTY_INIT_SIZED() to initialize it.
147 * If boundary_codepoints is NULL and boundary_codepoints_len is 0, Ghostty's
148 * default word-boundary codepoints are used. If boundary_codepoints_len is
149 * non-zero, boundary_codepoints must not be NULL.
150 *
151 * @ingroup selection
152 */
153typedef struct {
154 /** Size of this struct in bytes. Must be set to sizeof(GhosttyTerminalSelectWordBetweenOptions). */
155 size_t size;
156
157 /** Starting grid reference for the inclusive search range. */
158 GhosttyGridRef start;
159
160 /** Ending grid reference for the inclusive search range. */
161 GhosttyGridRef end;
162
163 /** Optional word-boundary codepoints as uint32_t scalar values. */
164 const uint32_t* boundary_codepoints;
165
166 /** Number of entries in boundary_codepoints. */
167 size_t boundary_codepoints_len;
168} GhosttyTerminalSelectWordBetweenOptions;
169
170/**
171 * Options for deriving a line selection from a terminal grid reference.
172 *
173 * This is a sized struct. Use GHOSTTY_INIT_SIZED() to initialize it.
174 * If whitespace is NULL and whitespace_len is 0, Ghostty's default line-trim
175 * whitespace codepoints are used. If whitespace_len is non-zero, whitespace
176 * must not be NULL.
177 *
178 * @ingroup selection
179 */
180typedef struct {
181 /** Size of this struct in bytes. Must be set to sizeof(GhosttyTerminalSelectLineOptions). */
182 size_t size;
183
184 /** Grid reference under which to derive the line selection. */
185 GhosttyGridRef ref;
186
187 /** Optional codepoints to trim from the start and end of the line. */
188 const uint32_t* whitespace;
189
190 /** Number of entries in whitespace. */
191 size_t whitespace_len;
192
193 /** Whether semantic prompt state changes should bound the line selection. */
194 bool semantic_prompt_boundary;
195} GhosttyTerminalSelectLineOptions;
196
197/**
198 * Options for one-shot formatting of a terminal selection.
199 *
200 * This is a sized struct. Use GHOSTTY_INIT_SIZED() to initialize it.
201 *
202 * If selection is NULL, the terminal's current active selection is used.
203 * If selection is non-NULL, that caller-provided snapshot selection is used.
204 *
205 * The selection is formatted from the terminal's active screen using the same
206 * formatting semantics as GhosttyFormatter. For copy/clipboard behavior
207 * matching Ghostty's Screen.selectionString(), use plain output with unwrap
208 * and trim both set to true.
209 *
210 * @ingroup selection
211 */
212typedef struct {
213 /** Size of this struct in bytes. Must be set to sizeof(GhosttyTerminalSelectionFormatOptions). */
214 size_t size;
215
216 /** Output format to emit. */
217 GhosttyFormatterFormat emit;
218
219 /** Whether to unwrap soft-wrapped lines. */
220 bool unwrap;
221
222 /** Whether to trim trailing whitespace on non-blank lines. */
223 bool trim;
224
225 /**
226 * Optional selection to format.
227 *
228 * If NULL, the terminal's current active selection is used. If the terminal
229 * has no active selection, formatting returns GHOSTTY_NO_VALUE.
230 *
231 * If non-NULL, the pointed-to selection must be a valid snapshot selection
232 * for this terminal and must obey GhosttySelection lifetime rules.
233 */
234 const GhosttySelection *selection;
235} GhosttyTerminalSelectionFormatOptions;
236
237/**
238 * Ordering of a selection's endpoints in terminal coordinates.
239 *
240 * Mirrored orders are only produced by rectangular selections whose start
241 * and end endpoints are on opposite diagonal corners that are not simple
242 * top-left-to-bottom-right or bottom-right-to-top-left orderings.
243 *
244 * @ingroup selection
245 */
246typedef enum GHOSTTY_ENUM_TYPED {
247 /** Start is before end in top-left to bottom-right order. */
248 GHOSTTY_SELECTION_ORDER_FORWARD = 0,
249
250 /** End is before start in top-left to bottom-right order. */
251 GHOSTTY_SELECTION_ORDER_REVERSE = 1,
252
253 /** Rectangular selection from top-right to bottom-left. */
254 GHOSTTY_SELECTION_ORDER_MIRRORED_FORWARD = 2,
255
256 /** Rectangular selection from bottom-left to top-right. */
257 GHOSTTY_SELECTION_ORDER_MIRRORED_REVERSE = 3,
258
259 GHOSTTY_SELECTION_ORDER_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
260} GhosttySelectionOrder;
261
262/**
263 * Operation used to adjust a selection endpoint.
264 *
265 * Adjustment mutates the selection's logical end endpoint, not whichever
266 * endpoint is visually bottom/right. This preserves keyboard and drag
267 * behavior for both forward and reversed selections.
268 *
269 * @ingroup selection
270 */
271typedef enum GHOSTTY_ENUM_TYPED {
272 /** Move left to the previous non-empty cell, wrapping upward. */
273 GHOSTTY_SELECTION_ADJUST_LEFT = 0,
274
275 /** Move right to the next non-empty cell, wrapping downward. */
276 GHOSTTY_SELECTION_ADJUST_RIGHT = 1,
277
278 /**
279 * Move up one row at the current column, or to the beginning of the
280 * line if already at the top.
281 */
282 GHOSTTY_SELECTION_ADJUST_UP = 2,
283
284 /**
285 * Move down to the next non-blank row at the current column, or to the
286 * end of the line if none exists.
287 */
288 GHOSTTY_SELECTION_ADJUST_DOWN = 3,
289
290 /** Move to the top-left cell of the screen. */
291 GHOSTTY_SELECTION_ADJUST_HOME = 4,
292
293 /** Move to the right edge of the last non-blank row on the screen. */
294 GHOSTTY_SELECTION_ADJUST_END = 5,
295
296 /**
297 * Move up by one terminal page height, or to home if that would move
298 * past the top.
299 */
300 GHOSTTY_SELECTION_ADJUST_PAGE_UP = 6,
301
302 /**
303 * Move down by one terminal page height, or to end if that would move
304 * past the bottom.
305 */
306 GHOSTTY_SELECTION_ADJUST_PAGE_DOWN = 7,
307
308 /** Move to the left edge of the current line. */
309 GHOSTTY_SELECTION_ADJUST_BEGINNING_OF_LINE = 8,
310
311 /** Move to the right edge of the current line. */
312 GHOSTTY_SELECTION_ADJUST_END_OF_LINE = 9,
313
314 GHOSTTY_SELECTION_ADJUST_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
315} GhosttySelectionAdjust;
316
317/**
318 * Selection behavior chosen for a gesture's click sequence.
319 *
320 * @ingroup selection
321 */
322typedef enum GHOSTTY_ENUM_TYPED {
323 /** Cell-granular drag selection. */
324 GHOSTTY_SELECTION_GESTURE_BEHAVIOR_CELL = 0,
325
326 /** Word selection on press and word-granular drag selection. */
327 GHOSTTY_SELECTION_GESTURE_BEHAVIOR_WORD = 1,
328
329 /** Line selection on press and line-granular drag selection. */
330 GHOSTTY_SELECTION_GESTURE_BEHAVIOR_LINE = 2,
331
332 /** Semantic command output selection on press and drag. */
333 GHOSTTY_SELECTION_GESTURE_BEHAVIOR_OUTPUT = 3,
334
335 GHOSTTY_SELECTION_GESTURE_BEHAVIOR_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
336} GhosttySelectionGestureBehavior;
337
338/**
339 * Selection behaviors for single-, double-, and triple-click gestures.
340 *
341 * @ingroup selection
342 */
343typedef struct {
344 /** Behavior for single-click selection gestures. */
345 GhosttySelectionGestureBehavior single_click;
346
347 /** Behavior for double-click selection gestures. */
348 GhosttySelectionGestureBehavior double_click;
349
350 /** Behavior for triple-click selection gestures. */
351 GhosttySelectionGestureBehavior triple_click;
352} GhosttySelectionGestureBehaviors;
353
354/**
355 * Display geometry used to interpret selection gesture drag events.
356 *
357 * @ingroup selection
358 */
359typedef struct {
360 /** Number of columns in the rendered terminal grid. Must be non-zero. */
361 uint32_t columns;
362
363 /** Width of one terminal cell in surface pixels. Must be non-zero. */
364 uint32_t cell_width;
365
366 /** Left padding before the terminal grid begins in surface pixels. */
367 uint32_t padding_left;
368
369 /** Height of the rendered terminal surface in surface pixels. Must be non-zero. */
370 uint32_t screen_height;
371} GhosttySelectionGestureGeometry;
372
373/**
374 * Current autoscroll direction for an active selection drag gesture.
375 *
376 * @ingroup selection
377 */
378typedef enum GHOSTTY_ENUM_TYPED {
379 /** No selection autoscroll is requested. */
380 GHOSTTY_SELECTION_GESTURE_AUTOSCROLL_NONE = 0,
381
382 /** Selection dragging should autoscroll the viewport upward. */
383 GHOSTTY_SELECTION_GESTURE_AUTOSCROLL_UP = 1,
384
385 /** Selection dragging should autoscroll the viewport downward. */
386 GHOSTTY_SELECTION_GESTURE_AUTOSCROLL_DOWN = 2,
387
388 GHOSTTY_SELECTION_GESTURE_AUTOSCROLL_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
389} GhosttySelectionGestureAutoscroll;
390
391/**
392 * Data fields readable from a selection gesture with
393 * ghostty_selection_gesture_get().
394 *
395 * @ingroup selection
396 */
397typedef enum GHOSTTY_ENUM_TYPED {
398 /** Current click count: uint8_t*. 0 means inactive. */
399 GHOSTTY_SELECTION_GESTURE_DATA_CLICK_COUNT = 0,
400
401 /** Whether the current/last left-click gesture has dragged: bool*. */
402 GHOSTTY_SELECTION_GESTURE_DATA_DRAGGED = 1,
403
404 /** Current autoscroll request: GhosttySelectionGestureAutoscroll*. */
405 GHOSTTY_SELECTION_GESTURE_DATA_AUTOSCROLL = 2,
406
407 /** Current gesture behavior: GhosttySelectionGestureBehavior*. */
408 GHOSTTY_SELECTION_GESTURE_DATA_BEHAVIOR = 3,
409
410 /**
411 * Current left-click anchor: GhosttyGridRef*.
412 *
413 * Returns GHOSTTY_NO_VALUE if there is no valid active anchor. On success,
414 * writes an untracked GhosttyGridRef snapshot with normal GhosttyGridRef
415 * lifetime rules.
416 */
417 GHOSTTY_SELECTION_GESTURE_DATA_ANCHOR = 4,
418
419 GHOSTTY_SELECTION_GESTURE_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
420} GhosttySelectionGestureData;
421
422/**
423 * Selection gesture event type.
424 *
425 * The event type is fixed when the event is created. Each event type documents
426 * which options are valid and which options are required by gesture operations.
427 *
428 * @ingroup selection
429 */
430typedef enum GHOSTTY_ENUM_TYPED {
431 /** Press event for ghostty_selection_gesture_event(). */
432 GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_PRESS = 0,
433
434 /** Release event for ghostty_selection_gesture_event(). */
435 GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_RELEASE = 1,
436
437 /** Drag event for ghostty_selection_gesture_event(). */
438 GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_DRAG = 2,
439
440 /** Autoscroll tick event for ghostty_selection_gesture_event(). */
441 GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_AUTOSCROLL_TICK = 3,
442
443 /** Deep press event for ghostty_selection_gesture_event(). */
444 GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_DEEP_PRESS = 4,
445
446 GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
447} GhosttySelectionGestureEventType;
448
449/**
450 * Options stored on a reusable selection gesture event.
451 *
452 * Passing NULL as the value to ghostty_selection_gesture_event_set() clears the
453 * corresponding option.
454 *
455 * @ingroup selection
456 */
457typedef enum GHOSTTY_ENUM_TYPED {
458 /**
459 * Grid reference under the pointer: GhosttyGridRef*.
460 *
461 * Required for PRESS and DRAG events. Optional for RELEASE events; when unset
462 * or cleared, release records that the pointer did not map to a valid cell.
463 */
464 GHOSTTY_SELECTION_GESTURE_EVENT_OPT_REF = 0,
465
466 /**
467 * Surface-space pointer position: GhosttySurfacePosition*.
468 *
469 * Valid for PRESS, DRAG, and AUTOSCROLL_TICK.
470 */
471 GHOSTTY_SELECTION_GESTURE_EVENT_OPT_POSITION = 1,
472
473 /** Maximum repeat-click distance in pixels: double*. */
474 GHOSTTY_SELECTION_GESTURE_EVENT_OPT_REPEAT_DISTANCE = 2,
475
476 /**
477 * Optional monotonic event time in nanoseconds: uint64_t*.
478 *
479 * If unset, press treats the event as untimed and only single-click behavior
480 * is available.
481 */
482 GHOSTTY_SELECTION_GESTURE_EVENT_OPT_TIME_NS = 3,
483
484 /** Maximum interval between repeat clicks in nanoseconds: uint64_t*. */
485 GHOSTTY_SELECTION_GESTURE_EVENT_OPT_REPEAT_INTERVAL_NS = 4,
486
487 /**
488 * Word-boundary codepoints: GhosttyCodepoints*.
489 *
490 * The codepoints are copied into event-owned storage when set. If unset,
491 * operations that need word boundaries use Ghostty's defaults.
492 *
493 * Valid for PRESS, DRAG, AUTOSCROLL_TICK, and DEEP_PRESS.
494 */
495 GHOSTTY_SELECTION_GESTURE_EVENT_OPT_WORD_BOUNDARY_CODEPOINTS = 5,
496
497 /**
498 * Selection behavior table: GhosttySelectionGestureBehaviors*.
499 *
500 * If unset, press uses the default behavior table: cell, word, line.
501 */
502 GHOSTTY_SELECTION_GESTURE_EVENT_OPT_BEHAVIORS = 6,
503
504 /** Whether a drag or autoscroll tick should produce a rectangular selection: bool*. */
505 GHOSTTY_SELECTION_GESTURE_EVENT_OPT_RECTANGLE = 7,
506
507 /** Drag display geometry: GhosttySelectionGestureGeometry*. Required for DRAG and AUTOSCROLL_TICK. */
508 GHOSTTY_SELECTION_GESTURE_EVENT_OPT_GEOMETRY = 8,
509
510 /** Viewport coordinate for an autoscroll tick: GhosttyPointCoordinate*. Required for AUTOSCROLL_TICK. */
511 GHOSTTY_SELECTION_GESTURE_EVENT_OPT_VIEWPORT = 9,
512
513 GHOSTTY_SELECTION_GESTURE_EVENT_OPT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
514} GhosttySelectionGestureEventOption;
515
516/**
517 * Create a reusable selection gesture event object.
518 *
519 * @param allocator Allocator, or NULL for the default allocator
520 * @param out_event Receives the created event handle
521 * @param type Event type. This is fixed for the lifetime of the event.
522 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if out_event is
523 * NULL or type is invalid, or GHOSTTY_OUT_OF_MEMORY if allocation fails
524 *
525 * @ingroup selection
526 */
527GHOSTTY_API GhosttyResult ghostty_selection_gesture_event_new(
528 const GhosttyAllocator* allocator,
529 GhosttySelectionGestureEvent* out_event,
530 GhosttySelectionGestureEventType type);
531
532/**
533 * Free a selection gesture event object.
534 *
535 * Passing NULL is allowed and is a no-op.
536 *
537 * @param event Selection gesture event handle to free
538 *
539 * @ingroup selection
540 */
541GHOSTTY_API void ghostty_selection_gesture_event_free(
542 GhosttySelectionGestureEvent event);
543
544/**
545 * Set or clear an option on a selection gesture event.
546 *
547 * The value type depends on option and is documented by
548 * GhosttySelectionGestureEventOption. Passing NULL for value clears the option.
549 *
550 * @param event Selection gesture event handle (NULL returns GHOSTTY_INVALID_VALUE)
551 * @param option Event option to set or clear
552 * @param value Pointer to the input value for option, or NULL to clear
553 * @return GHOSTTY_SUCCESS on success, GHOSTTY_OUT_OF_MEMORY if copying
554 * event-owned data fails, or GHOSTTY_INVALID_VALUE if event, option, or
555 * value is invalid
556 *
557 * @ingroup selection
558 */
559GHOSTTY_API GhosttyResult ghostty_selection_gesture_event_set(
560 GhosttySelectionGestureEvent event,
561 GhosttySelectionGestureEventOption option,
562 const void* value);
563
564/**
565 * Apply a selection gesture event and return the resulting selection snapshot.
566 *
567 * This dispatches to the gesture operation matching the event's fixed type.
568 * For GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_PRESS, the event must have
569 * GHOSTTY_SELECTION_GESTURE_EVENT_OPT_REF set before calling this function.
570 * All other press options use their initialized defaults when unset or cleared.
571 *
572 * For GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_RELEASE, only
573 * GHOSTTY_SELECTION_GESTURE_EVENT_OPT_REF is valid. It is optional; if unset or
574 * cleared, release records that the pointer did not map to a valid cell. Release
575 * events update gesture state but do not produce a selection, so this function
576 * returns GHOSTTY_NO_VALUE after applying them.
577 *
578 * For GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_DRAG,
579 * GHOSTTY_SELECTION_GESTURE_EVENT_OPT_REF and
580 * GHOSTTY_SELECTION_GESTURE_EVENT_OPT_GEOMETRY are required. Position,
581 * rectangle, and word-boundary codepoints are optional and use initialized
582 * defaults when unset or cleared.
583 *
584 * For GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_AUTOSCROLL_TICK,
585 * GHOSTTY_SELECTION_GESTURE_EVENT_OPT_VIEWPORT and
586 * GHOSTTY_SELECTION_GESTURE_EVENT_OPT_GEOMETRY are required. Position,
587 * rectangle, and word-boundary codepoints are optional and use initialized
588 * defaults when unset or cleared.
589 *
590 * For GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_DEEP_PRESS, only
591 * GHOSTTY_SELECTION_GESTURE_EVENT_OPT_WORD_BOUNDARY_CODEPOINTS is valid. It is
592 * optional and uses initialized defaults when unset or cleared.
593 *
594 * The returned selection is not installed as the terminal's current selection.
595 * It is a snapshot with the same lifetime rules as GhosttySelection.
596 *
597 * @param gesture Selection gesture handle (NULL returns GHOSTTY_INVALID_VALUE)
598 * @param terminal Terminal used to interpret and update gesture state
599 * @param event Selection gesture event handle (NULL returns GHOSTTY_INVALID_VALUE)
600 * @param[out] out_selection On success, receives the resulting selection. May
601 * be NULL to apply the event and discard the selection result.
602 * @return GHOSTTY_SUCCESS on success, GHOSTTY_NO_VALUE if the event does not
603 * currently produce a selection, GHOSTTY_OUT_OF_MEMORY if tracking
604 * gesture state fails, or GHOSTTY_INVALID_VALUE if gesture, terminal,
605 * event, or required event data is invalid
606 *
607 * @ingroup selection
608 */
609GHOSTTY_API GhosttyResult ghostty_selection_gesture_event(
610 GhosttySelectionGesture gesture,
611 GhosttyTerminal terminal,
612 GhosttySelectionGestureEvent event,
613 GhosttySelection* out_selection);
614
615/**
616 * Create a selection gesture object.
617 *
618 * The gesture stores mutable state for terminal text selection gestures. The
619 * gesture is not bound to a terminal at creation time; terminal-dependent APIs
620 * take the terminal explicitly.
621 *
622 * @param allocator Allocator, or NULL for the default allocator
623 * @param out_gesture Receives the created gesture handle
624 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if out_gesture is
625 * NULL, or GHOSTTY_OUT_OF_MEMORY if allocation fails
626 *
627 * @ingroup selection
628 */
629GHOSTTY_API GhosttyResult ghostty_selection_gesture_new(
630 const GhosttyAllocator* allocator,
631 GhosttySelectionGesture* out_gesture);
632
633/**
634 * Free a selection gesture object.
635 *
636 * This releases any tracked terminal references owned by the gesture using the
637 * provided terminal, then frees the gesture object. Passing NULL for gesture is
638 * allowed and is a no-op.
639 *
640 * If the terminal is still alive, pass the terminal most recently used with the
641 * gesture so any tracked terminal references can be released correctly. If the
642 * terminal has already been freed, pass NULL for terminal; the terminal's page
643 * storage has already released the underlying tracked references, so the
644 * gesture wrapper can be safely discarded without touching the stale terminal
645 * state.
646 *
647 * @param gesture Selection gesture handle to free
648 * @param terminal Terminal used to release tracked gesture state, or NULL if
649 * the terminal has already been freed
650 *
651 * @ingroup selection
652 */
653GHOSTTY_API void ghostty_selection_gesture_free(
654 GhosttySelectionGesture gesture,
655 GhosttyTerminal terminal);
656
657/**
658 * Reset any active selection gesture state.
659 *
660 * This cancels the active click sequence and releases any tracked terminal
661 * references owned by the gesture without freeing the gesture object.
662 * Passing NULL is allowed and is a no-op.
663 *
664 * @param gesture Selection gesture handle to reset
665 * @param terminal Terminal used to release tracked gesture state
666 *
667 * @ingroup selection
668 */
669GHOSTTY_API void ghostty_selection_gesture_reset(
670 GhosttySelectionGesture gesture,
671 GhosttyTerminal terminal);
672
673/**
674 * Read data from a selection gesture.
675 *
676 * The type of value depends on data and is documented by
677 * GhosttySelectionGestureData. For GHOSTTY_SELECTION_GESTURE_DATA_ANCHOR,
678 * the returned GhosttyGridRef is an untracked snapshot with normal grid-ref
679 * lifetime rules.
680 *
681 * @param gesture Selection gesture handle (NULL returns GHOSTTY_INVALID_VALUE)
682 * @param terminal Terminal used to validate terminal-backed gesture state
683 * @param data Data field to read
684 * @param value Output pointer whose type depends on data
685 * @return GHOSTTY_SUCCESS on success, GHOSTTY_NO_VALUE if the requested data
686 * has no value, or GHOSTTY_INVALID_VALUE if gesture, terminal, data, or
687 * value is invalid
688 *
689 * @ingroup selection
690 */
691GHOSTTY_API GhosttyResult ghostty_selection_gesture_get(
692 GhosttySelectionGesture gesture,
693 GhosttyTerminal terminal,
694 GhosttySelectionGestureData data,
695 void* value);
696
697/**
698 * Read multiple data fields from a selection gesture in a single call.
699 *
700 * This is an optimization over calling ghostty_selection_gesture_get() multiple
701 * times. Each entry in values must point to storage of the type documented by
702 * the corresponding GhosttySelectionGestureData key.
703 *
704 * If any individual read fails, the function returns that error and writes the
705 * index of the failing key to out_written when out_written is non-NULL. On
706 * success, out_written receives count when non-NULL.
707 *
708 * @param gesture Selection gesture handle (NULL returns GHOSTTY_INVALID_VALUE)
709 * @param terminal Terminal used to validate terminal-backed gesture state
710 * @param count Number of data fields to read
711 * @param keys Data fields to read (must not be NULL)
712 * @param values Output pointers corresponding to keys (must not be NULL)
713 * @param out_written Optional number of fields read, or failing index on error
714 * @return GHOSTTY_SUCCESS on success, GHOSTTY_NO_VALUE if a requested data
715 * field has no value, or GHOSTTY_INVALID_VALUE if gesture, terminal,
716 * keys, values, or a value pointer is invalid
717 *
718 * @ingroup selection
719 */
720GHOSTTY_API GhosttyResult ghostty_selection_gesture_get_multi(
721 GhosttySelectionGesture gesture,
722 GhosttyTerminal terminal,
723 size_t count,
724 const GhosttySelectionGestureData* keys,
725 void** values,
726 size_t* out_written);
727
728/**
729 * Derive a word selection snapshot from a terminal grid reference.
730 *
731 * The returned selection is not installed as the terminal's current
732 * selection. It is a snapshot with the same lifetime rules as GhosttySelection.
733 *
734 * @param terminal The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
735 * @param options Word-selection options
736 * @param[out] out_selection On success, receives the derived selection
737 * @return GHOSTTY_SUCCESS on success, GHOSTTY_NO_VALUE if the valid ref has
738 * no selectable word content, or GHOSTTY_INVALID_VALUE if the
739 * terminal, options, ref, codepoint pointer, or output pointer are
740 * invalid.
741 *
742 * @ingroup selection
743 */
744GHOSTTY_API GhosttyResult ghostty_terminal_select_word(
745 GhosttyTerminal terminal,
746 const GhosttyTerminalSelectWordOptions* options,
747 GhosttySelection* out_selection);
748
749/**
750 * Derive the nearest word selection snapshot between two terminal grid refs.
751 *
752 * Starting at options->start, this searches toward options->end (inclusive)
753 * and returns the first selectable word found using Ghostty's word-selection
754 * rules.
755 *
756 * This is useful for implementing double-click-and-drag selection in a UI. If
757 * a user double-clicks one word and drags across spaces or punctuation toward
758 * another word, selecting only the word directly under the current pointer can
759 * flicker or collapse when the pointer is between words. Instead, ask for the
760 * nearest word between the original click and the drag point, ask again in the
761 * reverse direction, and combine the two word bounds into the drag selection.
762 *
763 * @snippet c-vt-selection/src/main.c selection-word-between
764 *
765 * The returned selection is not installed as the terminal's current
766 * selection. It is a snapshot with the same lifetime rules as GhosttySelection.
767 *
768 * @param terminal The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
769 * @param options Word-between-selection options
770 * @param[out] out_selection On success, receives the derived selection
771 * @return GHOSTTY_SUCCESS on success, GHOSTTY_NO_VALUE if there is no
772 * selectable word content between the valid refs, or
773 * GHOSTTY_INVALID_VALUE if the terminal, options, refs, codepoint
774 * pointer, or output pointer are invalid.
775 *
776 * @ingroup selection
777 */
778GHOSTTY_API GhosttyResult ghostty_terminal_select_word_between(
779 GhosttyTerminal terminal,
780 const GhosttyTerminalSelectWordBetweenOptions* options,
781 GhosttySelection* out_selection);
782
783/**
784 * Derive a line selection snapshot from a terminal grid reference.
785 *
786 * The returned selection is not installed as the terminal's current
787 * selection. It is a snapshot with the same lifetime rules as GhosttySelection.
788 *
789 * @param terminal The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
790 * @param options Line-selection options
791 * @param[out] out_selection On success, receives the derived selection
792 * @return GHOSTTY_SUCCESS on success, GHOSTTY_NO_VALUE if the valid ref has
793 * no selectable line content, or GHOSTTY_INVALID_VALUE if the
794 * terminal, options, ref, codepoint pointer, or output pointer are
795 * invalid.
796 *
797 * @ingroup selection
798 */
799GHOSTTY_API GhosttyResult ghostty_terminal_select_line(
800 GhosttyTerminal terminal,
801 const GhosttyTerminalSelectLineOptions* options,
802 GhosttySelection* out_selection);
803
804/**
805 * Derive a selection snapshot covering all selectable terminal content.
806 *
807 * The returned selection is not installed as the terminal's current
808 * selection. It is a snapshot with the same lifetime rules as GhosttySelection.
809 *
810 * @param terminal The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
811 * @param[out] out_selection On success, receives the derived selection
812 * @return GHOSTTY_SUCCESS on success, GHOSTTY_NO_VALUE if there is no
813 * selectable content, or GHOSTTY_INVALID_VALUE if the terminal or
814 * output pointer is invalid.
815 *
816 * @ingroup selection
817 */
818GHOSTTY_API GhosttyResult ghostty_terminal_select_all(
819 GhosttyTerminal terminal,
820 GhosttySelection* out_selection);
821
822/**
823 * Derive a command-output selection snapshot from a terminal grid reference.
824 *
825 * The returned selection is not installed as the terminal's current
826 * selection. It is a snapshot with the same lifetime rules as GhosttySelection.
827 *
828 * @param terminal The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
829 * @param ref Grid reference within command output to select
830 * @param[out] out_selection On success, receives the derived selection
831 * @return GHOSTTY_SUCCESS on success, GHOSTTY_NO_VALUE if the valid ref is
832 * not selectable command output, or GHOSTTY_INVALID_VALUE if the
833 * terminal, ref, or output pointer is invalid.
834 *
835 * @ingroup selection
836 */
837GHOSTTY_API GhosttyResult ghostty_terminal_select_output(
838 GhosttyTerminal terminal,
839 GhosttyGridRef ref,
840 GhosttySelection* out_selection);
841
842/**
843 * Format a terminal selection into a caller-provided buffer.
844 *
845 * This is a one-shot convenience API for formatting either the terminal's
846 * active selection or a caller-provided GhosttySelection without explicitly
847 * creating a GhosttyFormatter.
848 *
849 * Pass NULL for buf to query the required output size. In that case,
850 * out_written receives the required size and the function returns
851 * GHOSTTY_OUT_OF_SPACE.
852 *
853 * If buf is too small, the function returns GHOSTTY_OUT_OF_SPACE and writes
854 * the required size to out_written. The caller can then retry with a larger
855 * buffer.
856 *
857 * If options.selection is NULL and the terminal has no active selection, the
858 * function returns GHOSTTY_NO_VALUE.
859 *
860 * @param terminal The terminal to read from (must not be NULL)
861 * @param options Selection formatting options
862 * @param buf Output buffer, or NULL to query required size
863 * @param buf_len Length of buf in bytes
864 * @param out_written Number of bytes written, or required size on
865 * GHOSTTY_OUT_OF_SPACE (must not be NULL)
866 * @return GHOSTTY_SUCCESS on success, or an error code on failure
867 *
868 * @ingroup selection
869 */
870GHOSTTY_API GhosttyResult ghostty_terminal_selection_format_buf(
871 GhosttyTerminal terminal,
872 GhosttyTerminalSelectionFormatOptions options,
873 uint8_t* buf,
874 size_t buf_len,
875 size_t* out_written);
876
877/**
878 * Format a terminal selection into an allocated buffer.
879 *
880 * This is a one-shot convenience API for formatting either the terminal's
881 * active selection or a caller-provided GhosttySelection without explicitly
882 * creating a GhosttyFormatter.
883 *
884 * The returned buffer is allocated using allocator, or the default allocator
885 * if NULL is passed. The caller owns the returned buffer and must free it with
886 * ghostty_free(), passing the same allocator and returned length.
887 *
888 * The returned bytes are not NUL-terminated. This supports plain text, VT, and
889 * HTML uniformly as byte output.
890 *
891 * If options.selection is NULL and the terminal has no active selection, the
892 * function returns GHOSTTY_NO_VALUE and leaves out_ptr as NULL and out_len as 0.
893 *
894 * @param terminal The terminal to read from (must not be NULL)
895 * @param allocator Allocator used for the returned buffer, or NULL for the default allocator
896 * @param options Selection formatting options
897 * @param out_ptr Receives the allocated output buffer (must not be NULL)
898 * @param out_len Receives the output length in bytes (must not be NULL)
899 * @return GHOSTTY_SUCCESS on success, or an error code on failure
900 *
901 * @ingroup selection
902 */
903GHOSTTY_API GhosttyResult ghostty_terminal_selection_format_alloc(
904 GhosttyTerminal terminal,
905 const GhosttyAllocator* allocator,
906 GhosttyTerminalSelectionFormatOptions options,
907 uint8_t** out_ptr,
908 size_t* out_len);
909
910/**
911 * Adjust a selection snapshot using terminal selection semantics.
912 *
913 * This mutates the caller-provided GhosttySelection in place. The logical end
914 * endpoint is always moved, regardless of whether the selection is forward or
915 * reversed visually. The input selection remains a snapshot: after adjustment,
916 * call ghostty_terminal_set() with GHOSTTY_TERMINAL_OPT_SELECTION to install it
917 * as the terminal-owned selection if desired.
918 *
919 * The selection's start and end grid refs must both be valid untracked
920 * snapshots for the given terminal's currently active screen. In practice,
921 * they must come from that terminal and screen, and no mutating terminal call
922 * may have occurred since the refs were produced or reconstructed from
923 * tracked refs. Passing refs from another terminal, another screen, or stale
924 * refs violates this precondition.
925 *
926 * @param terminal The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
927 * @param selection Selection snapshot to adjust in place
928 * @param adjustment The adjustment operation to apply
929 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the terminal,
930 * selection, or adjustment are invalid. Selection reference validity
931 * is a precondition and is not checked.
932 *
933 * @ingroup selection
934 */
935GHOSTTY_API GhosttyResult ghostty_terminal_selection_adjust(
936 GhosttyTerminal terminal,
937 GhosttySelection* selection,
938 GhosttySelectionAdjust adjustment);
939
940/**
941 * Get the current endpoint ordering of a selection snapshot.
942 *
943 * The selection's start and end grid refs must both be valid untracked
944 * snapshots for the given terminal's currently active screen. In practice,
945 * they must come from that terminal and screen, and no mutating terminal call
946 * may have occurred since the refs were produced or reconstructed from
947 * tracked refs. Passing refs from another terminal, another screen, or stale
948 * refs violates this precondition.
949 *
950 * @param terminal The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
951 * @param selection Selection snapshot to inspect
952 * @param[out] out_order On success, receives the selection order
953 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the terminal,
954 * selection, or output pointer are invalid. Selection reference
955 * validity is a precondition and is not checked.
956 *
957 * @ingroup selection
958 */
959GHOSTTY_API GhosttyResult ghostty_terminal_selection_order(
960 GhosttyTerminal terminal,
961 const GhosttySelection* selection,
962 GhosttySelectionOrder* out_order);
963
964/**
965 * Return a selection snapshot with endpoints ordered as requested.
966 *
967 * Use GHOSTTY_SELECTION_ORDER_FORWARD to get top-left to bottom-right bounds,
968 * and GHOSTTY_SELECTION_ORDER_REVERSE to get bottom-right to top-left bounds.
969 * Mirrored desired orders are accepted but normalized the same as forward.
970 * The output selection is a fresh untracked snapshot and is not installed as
971 * the terminal's current selection.
972 *
973 * The selection's start and end grid refs must both be valid untracked
974 * snapshots for the given terminal's currently active screen. In practice,
975 * they must come from that terminal and screen, and no mutating terminal call
976 * may have occurred since the refs were produced or reconstructed from
977 * tracked refs. Passing refs from another terminal, another screen, or stale
978 * refs violates this precondition.
979 *
980 * @param terminal The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
981 * @param selection Selection snapshot to order
982 * @param desired Desired endpoint order
983 * @param[out] out_selection On success, receives the ordered selection
984 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the terminal,
985 * selection, desired order, or output pointer are invalid. Selection
986 * reference validity is a precondition and is not checked.
987 *
988 * @ingroup selection
989 */
990GHOSTTY_API GhosttyResult ghostty_terminal_selection_ordered(
991 GhosttyTerminal terminal,
992 const GhosttySelection* selection,
993 GhosttySelectionOrder desired,
994 GhosttySelection* out_selection);
995
996/**
997 * Test whether a terminal point is inside a selection snapshot.
998 *
999 * This uses the same selection semantics as the terminal, including
1000 * rectangular/block selections and linear selections spanning multiple rows.
1001 *
1002 * The selection's start and end grid refs must both be valid untracked
1003 * snapshots for the given terminal's currently active screen. In practice,
1004 * they must come from that terminal and screen, and no mutating terminal call
1005 * may have occurred since the refs were produced or reconstructed from
1006 * tracked refs. Passing refs from another terminal, another screen, or stale
1007 * refs violates this precondition.
1008 *
1009 * @param terminal The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
1010 * @param selection Selection snapshot to inspect
1011 * @param point Point to test for containment
1012 * @param[out] out_contains On success, receives whether point is inside selection
1013 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the terminal,
1014 * selection, point, or output pointer are invalid. Selection reference
1015 * validity is a precondition and is not checked.
1016 *
1017 * @ingroup selection
1018 */
1019GHOSTTY_API GhosttyResult ghostty_terminal_selection_contains(
1020 GhosttyTerminal terminal,
1021 const GhosttySelection* selection,
1022 GhosttyPoint point,
1023 bool* out_contains);
1024
1025/**
1026 * Test whether two selection snapshots are equal.
1027 *
1028 * Equality uses the terminal's internal selection semantics: both endpoint
1029 * pins must match and both selections must have the same rectangular/block
1030 * state. This avoids requiring callers to compare raw GhosttyGridRef internals.
1031 *
1032 * Both selections' start and end grid refs must be valid untracked snapshots
1033 * for the given terminal's currently active screen. In practice, they must
1034 * come from that terminal and screen, and no mutating terminal call may have
1035 * occurred since the refs were produced or reconstructed from tracked refs.
1036 * Passing refs from another terminal, another screen, or stale refs violates
1037 * this precondition.
1038 *
1039 * @param terminal The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
1040 * @param a First selection snapshot to compare
1041 * @param b Second selection snapshot to compare
1042 * @param[out] out_equal On success, receives whether the selections are equal
1043 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the terminal,
1044 * selections, or output pointer are invalid. Selection reference
1045 * validity is a precondition and is not checked.
1046 *
1047 * @ingroup selection
1048 */
1049GHOSTTY_API GhosttyResult ghostty_terminal_selection_equal(
1050 GhosttyTerminal terminal,
1051 const GhosttySelection* a,
1052 const GhosttySelection* b,
1053 bool* out_equal);
1054
1055/** @} */
1056
1057#ifdef __cplusplus
1058}
1059#endif
1060
1061#endif /* GHOSTTY_VT_SELECTION_H */
apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/sgr.h deleted-350
......@@ -1,350 +0,0 @@
1/**
2 * @file sgr.h
3 *
4 * SGR (Select Graphic Rendition) attribute parsing and handling.
5 */
6
7#ifndef GHOSTTY_VT_SGR_H
8#define GHOSTTY_VT_SGR_H
9
10/** @defgroup sgr SGR Parser
11 *
12 * SGR (Select Graphic Rendition) attribute parser.
13 *
14 * SGR sequences are the syntax used to set styling attributes such as
15 * bold, italic, underline, and colors for text in terminal emulators.
16 * For example, you may be familiar with sequences like `ESC[1;31m`. The
17 * `1;31` is the SGR attribute list.
18 *
19 * The parser processes SGR parameters from CSI sequences (e.g., `ESC[1;31m`)
20 * and returns individual text attributes like bold, italic, colors, etc.
21 * It supports both semicolon (`;`) and colon (`:`) separators, possibly mixed,
22 * and handles various color formats including 8-color, 16-color, 256-color,
23 * X11 named colors, and RGB in multiple formats.
24 *
25 * ## Basic Usage
26 *
27 * 1. Create a parser instance with ghostty_sgr_new()
28 * 2. Set SGR parameters with ghostty_sgr_set_params()
29 * 3. Iterate through attributes using ghostty_sgr_next()
30 * 4. Free the parser with ghostty_sgr_free() when done
31 *
32 * ## Example
33 *
34 * @snippet c-vt-sgr/src/main.c sgr-basic
35 *
36 * @{
37 */
38
39#include <ghostty/vt/allocator.h>
40#include <ghostty/vt/color.h>
41#include <ghostty/vt/types.h>
42#include <stdbool.h>
43#include <stddef.h>
44#include <stdint.h>
45
46#ifdef __cplusplus
47extern "C" {
48#endif
49
50/**
51 * SGR attribute tags.
52 *
53 * These values identify the type of an SGR attribute in a tagged union.
54 * Use the tag to determine which field in the attribute value union to access.
55 *
56 * @ingroup sgr
57 */
58typedef enum GHOSTTY_ENUM_TYPED {
59 GHOSTTY_SGR_ATTR_UNSET = 0,
60 GHOSTTY_SGR_ATTR_UNKNOWN = 1,
61 GHOSTTY_SGR_ATTR_BOLD = 2,
62 GHOSTTY_SGR_ATTR_RESET_BOLD = 3,
63 GHOSTTY_SGR_ATTR_ITALIC = 4,
64 GHOSTTY_SGR_ATTR_RESET_ITALIC = 5,
65 GHOSTTY_SGR_ATTR_FAINT = 6,
66 GHOSTTY_SGR_ATTR_UNDERLINE = 7,
67 GHOSTTY_SGR_ATTR_UNDERLINE_COLOR = 8,
68 GHOSTTY_SGR_ATTR_UNDERLINE_COLOR_256 = 9,
69 GHOSTTY_SGR_ATTR_RESET_UNDERLINE_COLOR = 10,
70 GHOSTTY_SGR_ATTR_OVERLINE = 11,
71 GHOSTTY_SGR_ATTR_RESET_OVERLINE = 12,
72 GHOSTTY_SGR_ATTR_BLINK = 13,
73 GHOSTTY_SGR_ATTR_RESET_BLINK = 14,
74 GHOSTTY_SGR_ATTR_INVERSE = 15,
75 GHOSTTY_SGR_ATTR_RESET_INVERSE = 16,
76 GHOSTTY_SGR_ATTR_INVISIBLE = 17,
77 GHOSTTY_SGR_ATTR_RESET_INVISIBLE = 18,
78 GHOSTTY_SGR_ATTR_STRIKETHROUGH = 19,
79 GHOSTTY_SGR_ATTR_RESET_STRIKETHROUGH = 20,
80 GHOSTTY_SGR_ATTR_DIRECT_COLOR_FG = 21,
81 GHOSTTY_SGR_ATTR_DIRECT_COLOR_BG = 22,
82 GHOSTTY_SGR_ATTR_BG_8 = 23,
83 GHOSTTY_SGR_ATTR_FG_8 = 24,
84 GHOSTTY_SGR_ATTR_RESET_FG = 25,
85 GHOSTTY_SGR_ATTR_RESET_BG = 26,
86 GHOSTTY_SGR_ATTR_BRIGHT_BG_8 = 27,
87 GHOSTTY_SGR_ATTR_BRIGHT_FG_8 = 28,
88 GHOSTTY_SGR_ATTR_BG_256 = 29,
89 GHOSTTY_SGR_ATTR_FG_256 = 30,
90 GHOSTTY_SGR_ATTR_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
91} GhosttySgrAttributeTag;
92
93/**
94 * Underline style types.
95 *
96 * @ingroup sgr
97 */
98typedef enum GHOSTTY_ENUM_TYPED {
99 GHOSTTY_SGR_UNDERLINE_NONE = 0,
100 GHOSTTY_SGR_UNDERLINE_SINGLE = 1,
101 GHOSTTY_SGR_UNDERLINE_DOUBLE = 2,
102 GHOSTTY_SGR_UNDERLINE_CURLY = 3,
103 GHOSTTY_SGR_UNDERLINE_DOTTED = 4,
104 GHOSTTY_SGR_UNDERLINE_DASHED = 5,
105 GHOSTTY_SGR_UNDERLINE_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
106} GhosttySgrUnderline;
107
108/**
109 * Unknown SGR attribute data.
110 *
111 * Contains the full parameter list and the partial list where parsing
112 * encountered an unknown or invalid sequence.
113 *
114 * @ingroup sgr
115 */
116typedef struct {
117 const uint16_t* full_ptr;
118 size_t full_len;
119 const uint16_t* partial_ptr;
120 size_t partial_len;
121} GhosttySgrUnknown;
122
123/**
124 * SGR attribute value union.
125 *
126 * This union contains all possible attribute values. Use the tag field
127 * to determine which union member is active. Attributes without associated
128 * data (like bold, italic) don't use the union value.
129 *
130 * @ingroup sgr
131 */
132typedef union {
133 GhosttySgrUnknown unknown;
134 GhosttySgrUnderline underline;
135 GhosttyColorRgb underline_color;
136 GhosttyColorPaletteIndex underline_color_256;
137 GhosttyColorRgb direct_color_fg;
138 GhosttyColorRgb direct_color_bg;
139 GhosttyColorPaletteIndex bg_8;
140 GhosttyColorPaletteIndex fg_8;
141 GhosttyColorPaletteIndex bright_bg_8;
142 GhosttyColorPaletteIndex bright_fg_8;
143 GhosttyColorPaletteIndex bg_256;
144 GhosttyColorPaletteIndex fg_256;
145 uint64_t _padding[8];
146} GhosttySgrAttributeValue;
147
148/**
149 * SGR attribute (tagged union).
150 *
151 * A complete SGR attribute with both its type tag and associated value.
152 * Always check the tag field to determine which value union member is valid.
153 *
154 * Attributes without associated data (e.g., GHOSTTY_SGR_ATTR_BOLD) can be
155 * identified by tag alone; the value union is not used for these and
156 * the memory in the value field is undefined.
157 *
158 * @ingroup sgr
159 */
160typedef struct {
161 GhosttySgrAttributeTag tag;
162 GhosttySgrAttributeValue value;
163} GhosttySgrAttribute;
164
165/**
166 * Create a new SGR parser instance.
167 *
168 * Creates a new SGR (Select Graphic Rendition) parser using the provided
169 * allocator. The parser must be freed using ghostty_sgr_free() when
170 * no longer needed.
171 *
172 * @param allocator Pointer to the allocator to use for memory management, or
173 * NULL to use the default allocator
174 * @param parser Pointer to store the created parser handle
175 * @return GHOSTTY_SUCCESS on success, or an error code on failure
176 *
177 * @ingroup sgr
178 */
179GHOSTTY_API GhosttyResult ghostty_sgr_new(const GhosttyAllocator* allocator,
180 GhosttySgrParser* parser);
181
182/**
183 * Free an SGR parser instance.
184 *
185 * Releases all resources associated with the SGR parser. After this call,
186 * the parser handle becomes invalid and must not be used. This includes
187 * any attributes previously returned by ghostty_sgr_next().
188 *
189 * @param parser The parser handle to free (may be NULL)
190 *
191 * @ingroup sgr
192 */
193GHOSTTY_API void ghostty_sgr_free(GhosttySgrParser parser);
194
195/**
196 * Reset an SGR parser instance to the beginning of the parameter list.
197 *
198 * Resets the parser's iteration state without clearing the parameters.
199 * After calling this, ghostty_sgr_next() will start from the beginning
200 * of the parameter list again.
201 *
202 * @param parser The parser handle to reset, must not be NULL
203 *
204 * @ingroup sgr
205 */
206GHOSTTY_API void ghostty_sgr_reset(GhosttySgrParser parser);
207
208/**
209 * Set SGR parameters for parsing.
210 *
211 * Sets the SGR parameter list to parse. Parameters are the numeric values
212 * from a CSI SGR sequence (e.g., for `ESC[1;31m`, params would be {1, 31}).
213 *
214 * The separators array optionally specifies the separator type for each
215 * parameter position. Each byte should be either ';' for semicolon or ':'
216 * for colon. This is needed for certain color formats that use colon
217 * separators (e.g., `ESC[4:3m` for curly underline). Any invalid separator
218 * values are treated as semicolons. The separators array must have the same
219 * length as the params array, if it is not NULL.
220 *
221 * If separators is NULL, all parameters are assumed to be semicolon-separated.
222 *
223 * This function makes an internal copy of the parameter and separator data,
224 * so the caller can safely free or modify the input arrays after this call.
225 *
226 * After calling this function, the parser is automatically reset and ready
227 * to iterate from the beginning.
228 *
229 * @param parser The parser handle, must not be NULL
230 * @param params Array of SGR parameter values
231 * @param separators Optional array of separator characters (';' or ':'), or
232 * NULL
233 * @param len Number of parameters (and separators if provided)
234 * @return GHOSTTY_SUCCESS on success, or an error code on failure
235 *
236 * @ingroup sgr
237 */
238GHOSTTY_API GhosttyResult ghostty_sgr_set_params(GhosttySgrParser parser,
239 const uint16_t* params,
240 const char* separators,
241 size_t len);
242
243/**
244 * Get the next SGR attribute.
245 *
246 * Parses and returns the next attribute from the parameter list.
247 * Call this function repeatedly until it returns false to process
248 * all attributes in the sequence.
249 *
250 * @param parser The parser handle, must not be NULL
251 * @param attr Pointer to store the next attribute
252 * @return true if an attribute was returned, false if no more attributes
253 *
254 * @ingroup sgr
255 */
256GHOSTTY_API bool ghostty_sgr_next(GhosttySgrParser parser, GhosttySgrAttribute* attr);
257
258/**
259 * Get the full parameter list from an unknown SGR attribute.
260 *
261 * This function retrieves the full parameter list that was provided to the
262 * parser when an unknown attribute was encountered. Primarily useful in
263 * WebAssembly environments where accessing struct fields directly is difficult.
264 *
265 * @param unknown The unknown attribute data
266 * @param ptr Pointer to store the pointer to the parameter array (may be NULL)
267 * @return The length of the full parameter array
268 *
269 * @ingroup sgr
270 */
271GHOSTTY_API size_t ghostty_sgr_unknown_full(GhosttySgrUnknown unknown,
272 const uint16_t** ptr);
273
274/**
275 * Get the partial parameter list from an unknown SGR attribute.
276 *
277 * This function retrieves the partial parameter list where parsing stopped
278 * when an unknown attribute was encountered. Primarily useful in WebAssembly
279 * environments where accessing struct fields directly is difficult.
280 *
281 * @param unknown The unknown attribute data
282 * @param ptr Pointer to store the pointer to the parameter array (may be NULL)
283 * @return The length of the partial parameter array
284 *
285 * @ingroup sgr
286 */
287GHOSTTY_API size_t ghostty_sgr_unknown_partial(GhosttySgrUnknown unknown,
288 const uint16_t** ptr);
289
290/**
291 * Get the tag from an SGR attribute.
292 *
293 * This function extracts the tag that identifies which type of attribute
294 * this is. Primarily useful in WebAssembly environments where accessing
295 * struct fields directly is difficult.
296 *
297 * @param attr The SGR attribute
298 * @return The attribute tag
299 *
300 * @ingroup sgr
301 */
302GHOSTTY_API GhosttySgrAttributeTag ghostty_sgr_attribute_tag(GhosttySgrAttribute attr);
303
304/**
305 * Get the value from an SGR attribute.
306 *
307 * This function returns a pointer to the value union from an SGR attribute. Use
308 * the tag to determine which field of the union is valid. Primarily useful in
309 * WebAssembly environments where accessing struct fields directly is difficult.
310 *
311 * @param attr Pointer to the SGR attribute
312 * @return Pointer to the attribute value union
313 *
314 * @ingroup sgr
315 */
316GHOSTTY_API GhosttySgrAttributeValue* ghostty_sgr_attribute_value(
317 GhosttySgrAttribute* attr);
318
319#ifdef __wasm__
320/**
321 * Allocate memory for an SGR attribute (WebAssembly only).
322 *
323 * This is a convenience function for WebAssembly environments to allocate
324 * memory for an SGR attribute structure that can be passed to ghostty_sgr_next.
325 *
326 * @return Pointer to the allocated attribute structure
327 *
328 * @ingroup wasm
329 */
330GHOSTTY_API GhosttySgrAttribute* ghostty_wasm_alloc_sgr_attribute(void);
331
332/**
333 * Free memory for an SGR attribute (WebAssembly only).
334 *
335 * Frees memory allocated by ghostty_wasm_alloc_sgr_attribute.
336 *
337 * @param attr Pointer to the attribute structure to free
338 *
339 * @ingroup wasm
340 */
341GHOSTTY_API void ghostty_wasm_free_sgr_attribute(GhosttySgrAttribute* attr);
342#endif
343
344#ifdef __cplusplus
345}
346#endif
347
348/** @} */
349
350#endif /* GHOSTTY_VT_SGR_H */
apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/size_report.h deleted-101
......@@ -1,101 +0,0 @@
1/**
2 * @file size_report.h
3 *
4 * Size report encoding - encode terminal size reports into escape sequences.
5 */
6
7#ifndef GHOSTTY_VT_SIZE_REPORT_H
8#define GHOSTTY_VT_SIZE_REPORT_H
9
10/** @defgroup size_report Size Report Encoding
11 *
12 * Utilities for encoding terminal size reports into escape sequences,
13 * supporting in-band size reports (mode 2048) and XTWINOPS responses
14 * (CSI 14 t, CSI 16 t, CSI 18 t).
15 *
16 * ## Basic Usage
17 *
18 * Use ghostty_size_report_encode() to encode a size report into a
19 * caller-provided buffer. If the buffer is too small, the function
20 * returns GHOSTTY_OUT_OF_SPACE and sets the required size in the
21 * output parameter.
22 *
23 * ## Example
24 *
25 * @snippet c-vt-size-report/src/main.c size-report-encode
26 *
27 * @{
28 */
29
30#include <stddef.h>
31#include <stdint.h>
32#include <ghostty/vt/types.h>
33
34#ifdef __cplusplus
35extern "C" {
36#endif
37
38/**
39 * Size report style.
40 *
41 * Determines the output format for the terminal size report.
42 */
43typedef enum GHOSTTY_ENUM_TYPED {
44 /** In-band size report (mode 2048): ESC [ 48 ; rows ; cols ; height ; width t */
45 GHOSTTY_SIZE_REPORT_MODE_2048 = 0,
46 /** XTWINOPS text area size in pixels: ESC [ 4 ; height ; width t */
47 GHOSTTY_SIZE_REPORT_CSI_14_T = 1,
48 /** XTWINOPS cell size in pixels: ESC [ 6 ; height ; width t */
49 GHOSTTY_SIZE_REPORT_CSI_16_T = 2,
50 /** XTWINOPS text area size in characters: ESC [ 8 ; rows ; cols t */
51 GHOSTTY_SIZE_REPORT_CSI_18_T = 3,
52 GHOSTTY_SIZE_REPORT_STYLE_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
53} GhosttySizeReportStyle;
54
55/**
56 * Terminal size information for encoding size reports.
57 */
58typedef struct {
59 /** Terminal row count in cells. */
60 uint16_t rows;
61 /** Terminal column count in cells. */
62 uint16_t columns;
63 /** Width of a single terminal cell in pixels. */
64 uint32_t cell_width;
65 /** Height of a single terminal cell in pixels. */
66 uint32_t cell_height;
67} GhosttySizeReportSize;
68
69/**
70 * Encode a terminal size report into an escape sequence.
71 *
72 * Encodes a size report in the format specified by @p style into the
73 * provided buffer.
74 *
75 * If the buffer is too small, the function returns GHOSTTY_OUT_OF_SPACE
76 * and writes the required buffer size to @p out_written. The caller can
77 * then retry with a sufficiently sized buffer.
78 *
79 * @param style The size report format to encode
80 * @param size Terminal size information
81 * @param buf Output buffer to write the encoded sequence into (may be NULL)
82 * @param buf_len Size of the output buffer in bytes
83 * @param[out] out_written On success, the number of bytes written. On
84 * GHOSTTY_OUT_OF_SPACE, the required buffer size.
85 * @return GHOSTTY_SUCCESS on success, GHOSTTY_OUT_OF_SPACE if the buffer
86 * is too small
87 */
88GHOSTTY_API GhosttyResult ghostty_size_report_encode(
89 GhosttySizeReportStyle style,
90 GhosttySizeReportSize size,
91 char* buf,
92 size_t buf_len,
93 size_t* out_written);
94
95#ifdef __cplusplus
96}
97#endif
98
99/** @} */
100
101#endif /* GHOSTTY_VT_SIZE_REPORT_H */
apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/style.h deleted-139
......@@ -1,139 +0,0 @@
1/**
2 * @file style.h
3 *
4 * Terminal cell style types.
5 */
6
7#ifndef GHOSTTY_VT_STYLE_H
8#define GHOSTTY_VT_STYLE_H
9
10#include <ghostty/vt/color.h>
11#include <ghostty/vt/types.h>
12#include <stdbool.h>
13#include <stddef.h>
14#include <stdint.h>
15
16#ifdef __cplusplus
17extern "C" {
18#endif
19
20/** @defgroup style Style
21 *
22 * Terminal cell style attributes.
23 *
24 * A style describes the visual attributes of a terminal cell, including
25 * foreground, background, and underline colors, as well as flags for
26 * bold, italic, underline, and other text decorations.
27 *
28 * @{
29 */
30
31/**
32 * Style identifier type.
33 *
34 * Used to look up the full style from a grid reference.
35 * Obtain this from a cell via GHOSTTY_CELL_DATA_STYLE_ID.
36 *
37 * @ingroup style
38 */
39typedef uint16_t GhosttyStyleId;
40
41/**
42 * Style color tags.
43 *
44 * These values identify the type of color in a style color.
45 * Use the tag to determine which field in the color value union to access.
46 *
47 * @ingroup style
48 */
49typedef enum GHOSTTY_ENUM_TYPED {
50 GHOSTTY_STYLE_COLOR_NONE = 0,
51 GHOSTTY_STYLE_COLOR_PALETTE = 1,
52 GHOSTTY_STYLE_COLOR_RGB = 2,
53 GHOSTTY_STYLE_COLOR_TAG_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
54 } GhosttyStyleColorTag;
55
56/**
57 * Style color value union.
58 *
59 * Use the tag to determine which field is active.
60 *
61 * @ingroup style
62 */
63typedef union {
64 GhosttyColorPaletteIndex palette;
65 GhosttyColorRgb rgb;
66 uint64_t _padding;
67} GhosttyStyleColorValue;
68
69/**
70 * Style color (tagged union).
71 *
72 * A color used in a style attribute. Can be unset (none), a palette
73 * index, or a direct RGB value.
74 *
75 * @ingroup style
76 */
77typedef struct {
78 GhosttyStyleColorTag tag;
79 GhosttyStyleColorValue value;
80} GhosttyStyleColor;
81
82/**
83 * Terminal cell style.
84 *
85 * Describes the complete visual style for a terminal cell, including
86 * foreground, background, and underline colors, as well as text
87 * decoration flags. The underline field uses the same values as
88 * GhosttySgrUnderline.
89 *
90 * This is a sized struct. Use GHOSTTY_INIT_SIZED() to initialize it.
91 *
92 * @ingroup style
93 */
94typedef struct {
95 size_t size;
96 GhosttyStyleColor fg_color;
97 GhosttyStyleColor bg_color;
98 GhosttyStyleColor underline_color;
99 bool bold;
100 bool italic;
101 bool faint;
102 bool blink;
103 bool inverse;
104 bool invisible;
105 bool strikethrough;
106 bool overline;
107 int underline; /**< One of GHOSTTY_SGR_UNDERLINE_* values */
108} GhosttyStyle;
109
110/**
111 * Get the default style.
112 *
113 * Initializes the style to the default values (no colors, no flags).
114 *
115 * @param style Pointer to the style to initialize
116 *
117 * @ingroup style
118 */
119GHOSTTY_API void ghostty_style_default(GhosttyStyle* style);
120
121/**
122 * Check if a style is the default style.
123 *
124 * Returns true if all colors are unset and all flags are off.
125 *
126 * @param style Pointer to the style to check
127 * @return true if the style is the default style
128 *
129 * @ingroup style
130 */
131GHOSTTY_API bool ghostty_style_is_default(const GhosttyStyle* style);
132
133#ifdef __cplusplus
134}
135#endif
136
137/** @} */
138
139#endif /* GHOSTTY_VT_STYLE_H */
apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/sys.h deleted-210
......@@ -1,210 +0,0 @@
1/**
2 * @file sys.h
3 *
4 * System interface - runtime-swappable implementations for external dependencies.
5 */
6
7#ifndef GHOSTTY_VT_SYS_H
8#define GHOSTTY_VT_SYS_H
9
10#include <stdbool.h>
11#include <stddef.h>
12#include <stdint.h>
13#include <ghostty/vt/types.h>
14#include <ghostty/vt/allocator.h>
15
16/** @defgroup sys System Interface
17 *
18 * Runtime-swappable function pointers for operations that depend on
19 * external implementations (e.g. image decoding).
20 *
21 * These are process-global settings that must be configured at startup
22 * before any terminal functionality that depends on them is used.
23 * Setting these enables various optional features of the terminal. For
24 * example, setting a PNG decoder enables PNG image support in the Kitty
25 * Graphics Protocol.
26 *
27 * Use ghostty_sys_set() with a `GhosttySysOption` to install or clear
28 * an implementation. Passing NULL as the value clears the implementation
29 * and disables the corresponding feature.
30 *
31 * ## Example
32 *
33 * ### Defining a PNG decode callback
34 * @snippet c-vt-kitty-graphics/src/main.c kitty-graphics-decode-png
35 *
36 * ### Installing the callback and sending a PNG image
37 * @snippet c-vt-kitty-graphics/src/main.c kitty-graphics-main
38 *
39 * @{
40 */
41
42#ifdef __cplusplus
43extern "C" {
44#endif
45
46/**
47 * Result of decoding an image.
48 *
49 * The `data` buffer must be allocated through the allocator provided to
50 * the decode callback. The library takes ownership and will free it
51 * with the same allocator.
52 */
53typedef struct {
54 /** Image width in pixels. */
55 uint32_t width;
56
57 /** Image height in pixels. */
58 uint32_t height;
59
60 /** Pointer to the decoded RGBA pixel data. */
61 uint8_t* data;
62
63 /** Length of the pixel data in bytes. */
64 size_t data_len;
65} GhosttySysImage;
66
67/**
68 * Log severity levels for the log callback.
69 */
70typedef enum GHOSTTY_ENUM_TYPED {
71 GHOSTTY_SYS_LOG_LEVEL_ERROR = 0,
72 GHOSTTY_SYS_LOG_LEVEL_WARNING = 1,
73 GHOSTTY_SYS_LOG_LEVEL_INFO = 2,
74 GHOSTTY_SYS_LOG_LEVEL_DEBUG = 3,
75 GHOSTTY_SYS_LOG_LEVEL_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
76} GhosttySysLogLevel;
77
78/**
79 * Callback type for logging.
80 *
81 * When installed, internal library log messages are delivered through
82 * this callback instead of being discarded. The embedder is responsible
83 * for formatting and routing log output.
84 *
85 * @p scope is the log scope name as UTF-8 bytes (e.g. "osc", "kitty").
86 * When the log is unscoped (default scope), @p scope_len is 0.
87 *
88 * All pointer arguments are only valid for the duration of the callback.
89 * The callback must be safe to call from any thread.
90 *
91 * @param userdata The userdata pointer set via GHOSTTY_SYS_OPT_USERDATA
92 * @param level The severity level of the log message
93 * @param scope Pointer to the scope name bytes
94 * @param scope_len Length of the scope name in bytes
95 * @param message Pointer to the log message bytes
96 * @param message_len Length of the log message in bytes
97 */
98typedef void (*GhosttySysLogFn)(
99 void* userdata,
100 GhosttySysLogLevel level,
101 const uint8_t* scope,
102 size_t scope_len,
103 const uint8_t* message,
104 size_t message_len);
105
106/**
107 * Callback type for PNG decoding.
108 *
109 * Decodes raw PNG data into RGBA pixels. The output pixel data must be
110 * allocated through the provided allocator. The library takes ownership
111 * of the buffer and will free it with the same allocator.
112 *
113 * @param userdata The userdata pointer set via GHOSTTY_SYS_OPT_USERDATA
114 * @param allocator The allocator to use for the output pixel buffer
115 * @param data Pointer to the raw PNG data
116 * @param data_len Length of the raw PNG data in bytes
117 * @param[out] out On success, filled with the decoded image
118 * @return true on success, false on failure
119 */
120typedef bool (*GhosttySysDecodePngFn)(
121 void* userdata,
122 const GhosttyAllocator* allocator,
123 const uint8_t* data,
124 size_t data_len,
125 GhosttySysImage* out);
126
127/**
128 * System option identifiers for ghostty_sys_set().
129 */
130typedef enum GHOSTTY_ENUM_TYPED {
131 /**
132 * Set the userdata pointer passed to all sys callbacks.
133 *
134 * Input type: void* (or NULL)
135 */
136 GHOSTTY_SYS_OPT_USERDATA = 0,
137
138 /**
139 * Set the PNG decode function.
140 *
141 * When set, the terminal can accept PNG images via the Kitty
142 * Graphics Protocol. When cleared (NULL value), PNG decoding is
143 * unsupported and PNG image data will be rejected.
144 *
145 * Input type: GhosttySysDecodePngFn (function pointer, or NULL)
146 */
147 GHOSTTY_SYS_OPT_DECODE_PNG = 1,
148
149 /**
150 * Set the log callback.
151 *
152 * When set, internal library log messages are delivered to this
153 * callback. When cleared (NULL value), log messages are silently
154 * discarded.
155 *
156 * Use ghostty_sys_log_stderr as a convenience callback that
157 * writes formatted messages to stderr.
158 *
159 * Which log levels are emitted depends on the build mode of the
160 * library and is not configurable at runtime. Debug builds emit
161 * all levels (debug and above). Release builds emit info and
162 * above; debug-level messages are compiled out entirely and will
163 * never reach the callback.
164 *
165 * Input type: GhosttySysLogFn (function pointer, or NULL)
166 */
167 GHOSTTY_SYS_OPT_LOG = 2,
168 GHOSTTY_SYS_OPT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
169} GhosttySysOption;
170
171/**
172 * Set a system-level option.
173 *
174 * Configures a process-global implementation function. These should be
175 * set once at startup before using any terminal functionality that
176 * depends on them.
177 *
178 * @param option The option to set
179 * @param value Pointer to the value (type depends on the option),
180 * or NULL to clear it
181 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the
182 * option is not recognized
183 */
184GHOSTTY_API GhosttyResult ghostty_sys_set(GhosttySysOption option,
185 const void* value);
186
187/**
188 * Built-in log callback that writes to stderr.
189 *
190 * Formats each message as "[level](scope): message\n".
191 * Can be passed directly to ghostty_sys_set():
192 *
193 * @code
194 * ghostty_sys_set(GHOSTTY_SYS_OPT_LOG, &ghostty_sys_log_stderr);
195 * @endcode
196 */
197GHOSTTY_API void ghostty_sys_log_stderr(void* userdata,
198 GhosttySysLogLevel level,
199 const uint8_t* scope,
200 size_t scope_len,
201 const uint8_t* message,
202 size_t message_len);
203
204#ifdef __cplusplus
205}
206#endif
207
208/** @} */
209
210#endif /* GHOSTTY_VT_SYS_H */
apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/terminal.h deleted-1322
......@@ -1,1322 +0,0 @@
1/**
2 * @file terminal.h
3 *
4 * Complete terminal emulator state and rendering.
5 */
6
7#ifndef GHOSTTY_VT_TERMINAL_H
8#define GHOSTTY_VT_TERMINAL_H
9
10#include <stdbool.h>
11#include <stddef.h>
12#include <stdint.h>
13#include <ghostty/vt/types.h>
14#include <ghostty/vt/allocator.h>
15#include <ghostty/vt/device.h>
16#include <ghostty/vt/modes.h>
17#include <ghostty/vt/size_report.h>
18#include <ghostty/vt/grid_ref.h>
19#include <ghostty/vt/kitty_graphics.h>
20#include <ghostty/vt/screen.h>
21#include <ghostty/vt/point.h>
22#include <ghostty/vt/selection.h>
23#include <ghostty/vt/style.h>
24
25#ifdef __cplusplus
26extern "C" {
27#endif
28
29/** @defgroup terminal Terminal
30 *
31 * Complete terminal emulator state and rendering.
32 *
33 * A terminal instance manages the full emulator state including the screen,
34 * scrollback, cursor, styles, modes, and VT stream processing.
35 *
36 * Once a terminal session is up and running, you can configure a key encoder
37 * to write keyboard input via ghostty_key_encoder_setopt_from_terminal().
38 *
39 * ### Example: VT stream processing
40 * @snippet c-vt-stream/src/main.c vt-stream-init
41 * @snippet c-vt-stream/src/main.c vt-stream-write
42 *
43 * ## Effects
44 *
45 * By default, the terminal sequence processing with ghostty_terminal_vt_write()
46 * only process sequences that directly affect terminal state and
47 * ignores sequences that have side effect behavior or require responses.
48 * These sequences include things like bell characters, title changes, device
49 * attributes queries, and more. To handle these sequences, the embedder
50 * must configure "effects."
51 *
52 * Effects are callbacks that the terminal invokes in response to VT
53 * sequences processed during ghostty_terminal_vt_write(). They let the
54 * embedding application react to terminal-initiated events such as bell
55 * characters, title changes, device status report responses, and more.
56 *
57 * Each effect is registered with ghostty_terminal_set() using the
58 * corresponding `GhosttyTerminalOption` identifier. A `NULL` value
59 * pointer clears the callback and disables the effect.
60 *
61 * A userdata pointer can be attached via `GHOSTTY_TERMINAL_OPT_USERDATA`
62 * and is passed to every callback, allowing callers to route events
63 * back to their own application state without global variables.
64 * You cannot specify different userdata for different callbacks.
65 *
66 * All callbacks are invoked synchronously during
67 * ghostty_terminal_vt_write(). Callbacks **must not** call
68 * ghostty_terminal_vt_write() on the same terminal (no reentrancy).
69 * And callbacks must be very careful to not block for too long or perform
70 * expensive operations, since they are blocking further IO processing.
71 *
72 * The available effects are:
73 *
74 * | Option | Callback Type | Trigger |
75 * |-----------------------------------------|-----------------------------------|-------------------------------------------|
76 * | `GHOSTTY_TERMINAL_OPT_WRITE_PTY` | `GhosttyTerminalWritePtyFn` | Query responses written back to the pty |
77 * | `GHOSTTY_TERMINAL_OPT_BELL` | `GhosttyTerminalBellFn` | BEL character (0x07) |
78 * | `GHOSTTY_TERMINAL_OPT_TITLE_CHANGED` | `GhosttyTerminalTitleChangedFn` | Title change via OSC 0 / OSC 2 |
79 * | `GHOSTTY_TERMINAL_OPT_PWD_CHANGED` | `GhosttyTerminalPwdChangedFn` | Pwd change via OSC 7 / OSC 9 / OSC 1337 |
80 * | `GHOSTTY_TERMINAL_OPT_ENQUIRY` | `GhosttyTerminalEnquiryFn` | ENQ character (0x05) |
81 * | `GHOSTTY_TERMINAL_OPT_XTVERSION` | `GhosttyTerminalXtversionFn` | XTVERSION query (CSI > q) |
82 * | `GHOSTTY_TERMINAL_OPT_SIZE` | `GhosttyTerminalSizeFn` | XTWINOPS size query (CSI 14/16/18 t) |
83 * | `GHOSTTY_TERMINAL_OPT_COLOR_SCHEME` | `GhosttyTerminalColorSchemeFn` | Color scheme query (CSI ? 996 n) |
84 * | `GHOSTTY_TERMINAL_OPT_DEVICE_ATTRIBUTES`| `GhosttyTerminalDeviceAttributesFn`| Device attributes query (CSI c / > c / = c)|
85 *
86 * ### Defining a write_pty callback
87 * @snippet c-vt-effects/src/main.c effects-write-pty
88 *
89 * ### Defining a bell callback
90 * @snippet c-vt-effects/src/main.c effects-bell
91 *
92 * ### Defining a title_changed callback
93 * @snippet c-vt-effects/src/main.c effects-title-changed
94 *
95 * ### Registering effects and processing VT data
96 * @snippet c-vt-effects/src/main.c effects-register
97 *
98 * ## Color Theme
99 *
100 * The terminal maintains a set of colors used for rendering: a foreground
101 * color, a background color, a cursor color, and a 256-color palette. Each
102 * of these has two layers: a **default** value set by the embedder, and an
103 * **override** value that programs running in the terminal can set via OSC
104 * escape sequences (e.g. OSC 10/11/12 for foreground/background/cursor,
105 * OSC 4 for individual palette entries).
106 *
107 * ### Default Colors
108 *
109 * Use ghostty_terminal_set() with the color options to configure the
110 * default colors. These represent the theme or configuration chosen by
111 * the embedder. Passing `NULL` clears the default, leaving the color
112 * unset.
113 *
114 * | Option | Input Type | Description |
115 * |-----------------------------------------|-------------------------|--------------------------------------|
116 * | `GHOSTTY_TERMINAL_OPT_COLOR_FOREGROUND` | `GhosttyColorRgb*` | Default foreground color |
117 * | `GHOSTTY_TERMINAL_OPT_COLOR_BACKGROUND` | `GhosttyColorRgb*` | Default background color |
118 * | `GHOSTTY_TERMINAL_OPT_COLOR_CURSOR` | `GhosttyColorRgb*` | Default cursor color |
119 * | `GHOSTTY_TERMINAL_OPT_COLOR_PALETTE` | `GhosttyColorRgb[256]*` | Default 256-color palette |
120 *
121 * For the palette, passing `NULL` resets to the built-in default palette.
122 * The palette set operation preserves any per-index OSC overrides that
123 * programs have applied; only unmodified indices are updated.
124 *
125 * ### Reading colors
126 *
127 * Use ghostty_terminal_get() to read colors. There are two variants for
128 * each color: the **effective** value (which returns the OSC override if
129 * one is active, otherwise the default) and the **default** value (which
130 * ignores any OSC overrides).
131 *
132 * | Data | Output Type | Description |
133 * |---------------------------------------------------|-------------------------|------------------------------------------------|
134 * | `GHOSTTY_TERMINAL_DATA_COLOR_FOREGROUND` | `GhosttyColorRgb*` | Effective foreground (override or default) |
135 * | `GHOSTTY_TERMINAL_DATA_COLOR_BACKGROUND` | `GhosttyColorRgb*` | Effective background (override or default) |
136 * | `GHOSTTY_TERMINAL_DATA_COLOR_CURSOR` | `GhosttyColorRgb*` | Effective cursor (override or default) |
137 * | `GHOSTTY_TERMINAL_DATA_COLOR_PALETTE` | `GhosttyColorRgb[256]*` | Current palette (with any OSC overrides) |
138 * | `GHOSTTY_TERMINAL_DATA_COLOR_FOREGROUND_DEFAULT` | `GhosttyColorRgb*` | Default foreground only (ignores OSC override) |
139 * | `GHOSTTY_TERMINAL_DATA_COLOR_BACKGROUND_DEFAULT` | `GhosttyColorRgb*` | Default background only (ignores OSC override) |
140 * | `GHOSTTY_TERMINAL_DATA_COLOR_CURSOR_DEFAULT` | `GhosttyColorRgb*` | Default cursor only (ignores OSC override) |
141 * | `GHOSTTY_TERMINAL_DATA_COLOR_PALETTE_DEFAULT` | `GhosttyColorRgb[256]*` | Default palette only (ignores OSC overrides) |
142 *
143 * For foreground, background, and cursor colors, the getters return
144 * `GHOSTTY_NO_VALUE` if no color is configured (neither a default nor an
145 * OSC override). The palette getters always succeed since the palette
146 * always has a value (the built-in default if nothing else is set).
147 *
148 * ### Setting a color theme
149 * @snippet c-vt-colors/src/main.c colors-set-defaults
150 *
151 * ### Reading effective and default colors
152 * @snippet c-vt-colors/src/main.c colors-read
153 *
154 * ### Full example with OSC overrides
155 * @snippet c-vt-colors/src/main.c colors-main
156 *
157 * @{
158 */
159
160/**
161 * Terminal initialization options.
162 *
163 * @ingroup terminal
164 */
165typedef struct {
166 /** Terminal width in cells. Must be greater than zero. */
167 uint16_t cols;
168
169 /** Terminal height in cells. Must be greater than zero. */
170 uint16_t rows;
171
172 /** Maximum number of lines to keep in scrollback history. */
173 size_t max_scrollback;
174
175 // TODO: Consider ABI compatibility implications of this struct.
176 // We may want to artificially pad it significantly to support
177 // future options.
178} GhosttyTerminalOptions;
179
180/**
181 * Scroll viewport behavior tag.
182 *
183 * @ingroup terminal
184 */
185typedef enum GHOSTTY_ENUM_TYPED {
186 /** Scroll to the top of the scrollback. */
187 GHOSTTY_SCROLL_VIEWPORT_TOP,
188
189 /** Scroll to the bottom (active area). */
190 GHOSTTY_SCROLL_VIEWPORT_BOTTOM,
191
192 /** Scroll by a delta amount (up is negative). */
193 GHOSTTY_SCROLL_VIEWPORT_DELTA,
194 GHOSTTY_SCROLL_VIEWPORT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
195} GhosttyTerminalScrollViewportTag;
196
197/**
198 * Scroll viewport value.
199 *
200 * @ingroup terminal
201 */
202typedef union {
203 /** Scroll delta (only used with GHOSTTY_SCROLL_VIEWPORT_DELTA). Up is negative. */
204 intptr_t delta;
205
206 /** Padding for ABI compatibility. Do not use. */
207 uint64_t _padding[2];
208} GhosttyTerminalScrollViewportValue;
209
210/**
211 * Tagged union for scroll viewport behavior.
212 *
213 * @ingroup terminal
214 */
215typedef struct {
216 GhosttyTerminalScrollViewportTag tag;
217 GhosttyTerminalScrollViewportValue value;
218} GhosttyTerminalScrollViewport;
219
220/**
221 * Terminal screen identifier.
222 *
223 * Identifies which screen buffer is active in the terminal.
224 *
225 * @ingroup terminal
226 */
227typedef enum GHOSTTY_ENUM_TYPED {
228 /** The primary (normal) screen. */
229 GHOSTTY_TERMINAL_SCREEN_PRIMARY = 0,
230
231 /** The alternate screen. */
232 GHOSTTY_TERMINAL_SCREEN_ALTERNATE = 1,
233 GHOSTTY_TERMINAL_SCREEN_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
234} GhosttyTerminalScreen;
235
236/**
237 * Visual style of the terminal cursor.
238 *
239 * @ingroup terminal
240 */
241typedef enum GHOSTTY_ENUM_TYPED {
242 /** Bar cursor (DECSCUSR 5, 6). */
243 GHOSTTY_TERMINAL_CURSOR_STYLE_BAR = 0,
244
245 /** Block cursor (DECSCUSR 1, 2). */
246 GHOSTTY_TERMINAL_CURSOR_STYLE_BLOCK = 1,
247
248 /** Underline cursor (DECSCUSR 3, 4). */
249 GHOSTTY_TERMINAL_CURSOR_STYLE_UNDERLINE = 2,
250
251 /** Hollow block cursor. */
252 GHOSTTY_TERMINAL_CURSOR_STYLE_BLOCK_HOLLOW = 3,
253 GHOSTTY_TERMINAL_CURSOR_STYLE_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
254} GhosttyTerminalCursorStyle;
255
256/**
257 * Scrollbar state for the terminal viewport.
258 *
259 * Represents the scrollable area dimensions needed to render a scrollbar.
260 *
261 * @ingroup terminal
262 */
263typedef struct {
264 /** Total size of the scrollable area in rows. */
265 uint64_t total;
266
267 /** Offset into the total area that the viewport is at. */
268 uint64_t offset;
269
270 /** Length of the visible area in rows. */
271 uint64_t len;
272} GhosttyTerminalScrollbar;
273
274/**
275 * Callback function type for bell.
276 *
277 * Called when the terminal receives a BEL character (0x07).
278 *
279 * @param terminal The terminal handle
280 * @param userdata The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
281 *
282 * @ingroup terminal
283 */
284typedef void (*GhosttyTerminalBellFn)(GhosttyTerminal terminal,
285 void* userdata);
286
287/**
288 * Callback function type for color scheme queries (CSI ? 996 n).
289 *
290 * Called when the terminal receives a color scheme device status report
291 * query. Return true and fill *out_scheme with the current color scheme,
292 * or return false to silently ignore the query.
293 *
294 * @param terminal The terminal handle
295 * @param userdata The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
296 * @param[out] out_scheme Pointer to store the current color scheme
297 * @return true if the color scheme was filled, false to ignore the query
298 *
299 * @ingroup terminal
300 */
301typedef bool (*GhosttyTerminalColorSchemeFn)(GhosttyTerminal terminal,
302 void* userdata,
303 GhosttyColorScheme* out_scheme);
304
305/**
306 * Callback function type for device attributes queries (DA1/DA2/DA3).
307 *
308 * Called when the terminal receives a device attributes query (CSI c,
309 * CSI > c, or CSI = c). Return true and fill *out_attrs with the
310 * response data, or return false to silently ignore the query.
311 *
312 * The terminal uses whichever sub-struct (primary, secondary, tertiary)
313 * matches the request type, but all three should be filled for simplicity.
314 *
315 * @param terminal The terminal handle
316 * @param userdata The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
317 * @param[out] out_attrs Pointer to store the device attributes response
318 * @return true if attributes were filled, false to ignore the query
319 *
320 * @ingroup terminal
321 */
322typedef bool (*GhosttyTerminalDeviceAttributesFn)(GhosttyTerminal terminal,
323 void* userdata,
324 GhosttyDeviceAttributes* out_attrs);
325
326/**
327 * Callback function type for enquiry (ENQ, 0x05).
328 *
329 * Called when the terminal receives an ENQ character. Return the
330 * response bytes as a GhosttyString. The memory must remain valid
331 * until the callback returns. Return a zero-length string to send
332 * no response.
333 *
334 * @param terminal The terminal handle
335 * @param userdata The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
336 * @return The response bytes to write back to the pty
337 *
338 * @ingroup terminal
339 */
340typedef GhosttyString (*GhosttyTerminalEnquiryFn)(GhosttyTerminal terminal,
341 void* userdata);
342
343/**
344 * Callback function type for size queries (XTWINOPS).
345 *
346 * Called in response to XTWINOPS size queries (CSI 14/16/18 t).
347 * Return true and fill *out_size with the current terminal geometry,
348 * or return false to silently ignore the query.
349 *
350 * @param terminal The terminal handle
351 * @param userdata The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
352 * @param[out] out_size Pointer to store the terminal size information
353 * @return true if size was filled, false to ignore the query
354 *
355 * @ingroup terminal
356 */
357typedef bool (*GhosttyTerminalSizeFn)(GhosttyTerminal terminal,
358 void* userdata,
359 GhosttySizeReportSize* out_size);
360
361/**
362 * Callback function type for title_changed.
363 *
364 * Called when the terminal title changes via escape sequences
365 * (e.g. OSC 0 or OSC 2). The new title can be queried from the
366 * terminal after the callback returns.
367 *
368 * @param terminal The terminal handle
369 * @param userdata The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
370 *
371 * @ingroup terminal
372 */
373typedef void (*GhosttyTerminalTitleChangedFn)(GhosttyTerminal terminal,
374 void* userdata);
375
376/**
377 * Callback function type for pwd_changed.
378 *
379 * Called when the terminal pwd (current working directory) changes via
380 * escape sequences: OSC 7 (file:// URI), OSC 9 (ConEmu CurrentDir), or
381 * OSC 1337 CurrentDir (iTerm2). Use ghostty_terminal_get() with
382 * GHOSTTY_TERMINAL_DATA_PWD inside the callback to read the new value.
383 *
384 * The terminal stores whatever bytes the shell emitted, without parsing.
385 * That means for OSC 7 the value is the raw URI (typically file://...);
386 * for OSC 9/OSC 1337 it is typically a bare path. The embedder is
387 * responsible for decoding any URI scheme or host if it cares about them.
388 *
389 * The callback also fires when the shell clears the pwd (e.g. an empty
390 * OSC 7). In that case GHOSTTY_TERMINAL_DATA_PWD returns a zero-length
391 * string.
392 *
393 * @param terminal The terminal handle
394 * @param userdata The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
395 *
396 * @ingroup terminal
397 */
398typedef void (*GhosttyTerminalPwdChangedFn)(GhosttyTerminal terminal,
399 void* userdata);
400
401/**
402 * Callback function type for write_pty.
403 *
404 * Called when the terminal needs to write data back to the pty, for
405 * example in response to a device status report or mode query. The
406 * data is only valid for the duration of the call; callers must copy
407 * it if it needs to persist.
408 *
409 * @param terminal The terminal handle
410 * @param userdata The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
411 * @param data Pointer to the response bytes
412 * @param len Length of the response in bytes
413 *
414 * @ingroup terminal
415 */
416typedef void (*GhosttyTerminalWritePtyFn)(GhosttyTerminal terminal,
417 void* userdata,
418 const uint8_t* data,
419 size_t len);
420
421/**
422 * Callback function type for XTVERSION.
423 *
424 * Called when the terminal receives an XTVERSION query (CSI > q).
425 * Return the version string (e.g. "myterm 1.0") as a GhosttyString.
426 * The memory must remain valid until the callback returns. Return a
427 * zero-length string to report the default "libghostty" version.
428 *
429 * @param terminal The terminal handle
430 * @param userdata The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
431 * @return The version string to report
432 *
433 * @ingroup terminal
434 */
435typedef GhosttyString (*GhosttyTerminalXtversionFn)(GhosttyTerminal terminal,
436 void* userdata);
437
438/**
439 * Terminal option identifiers.
440 *
441 * These values are used with ghostty_terminal_set() to configure
442 * terminal callbacks and associated state.
443 *
444 * @ingroup terminal
445 */
446typedef enum GHOSTTY_ENUM_TYPED {
447 /**
448 * Opaque userdata pointer passed to all callbacks.
449 *
450 * Input type: void*
451 */
452 GHOSTTY_TERMINAL_OPT_USERDATA = 0,
453
454 /**
455 * Callback invoked when the terminal needs to write data back
456 * to the pty (e.g. in response to a DECRQM query or device
457 * status report). Set to NULL to ignore such sequences.
458 *
459 * Input type: GhosttyTerminalWritePtyFn
460 */
461 GHOSTTY_TERMINAL_OPT_WRITE_PTY = 1,
462
463 /**
464 * Callback invoked when the terminal receives a BEL character
465 * (0x07). Set to NULL to ignore bell events.
466 *
467 * Input type: GhosttyTerminalBellFn
468 */
469 GHOSTTY_TERMINAL_OPT_BELL = 2,
470
471 /**
472 * Callback invoked when the terminal receives an ENQ character
473 * (0x05). Set to NULL to send no response.
474 *
475 * Input type: GhosttyTerminalEnquiryFn
476 */
477 GHOSTTY_TERMINAL_OPT_ENQUIRY = 3,
478
479 /**
480 * Callback invoked when the terminal receives an XTVERSION query
481 * (CSI > q). Set to NULL to report the default "libghostty" string.
482 *
483 * Input type: GhosttyTerminalXtversionFn
484 */
485 GHOSTTY_TERMINAL_OPT_XTVERSION = 4,
486
487 /**
488 * Callback invoked when the terminal title changes via escape
489 * sequences (e.g. OSC 0 or OSC 2). Set to NULL to ignore title
490 * change events.
491 *
492 * Input type: GhosttyTerminalTitleChangedFn
493 */
494 GHOSTTY_TERMINAL_OPT_TITLE_CHANGED = 5,
495
496 /**
497 * Callback invoked in response to XTWINOPS size queries
498 * (CSI 14/16/18 t). Set to NULL to silently ignore size queries.
499 *
500 * Input type: GhosttyTerminalSizeFn
501 */
502 GHOSTTY_TERMINAL_OPT_SIZE = 6,
503
504 /**
505 * Callback invoked in response to a color scheme device status
506 * report query (CSI ? 996 n). Return true and fill the out pointer
507 * to report the current scheme, or return false to silently ignore.
508 * Set to NULL to ignore color scheme queries.
509 *
510 * Input type: GhosttyTerminalColorSchemeFn
511 */
512 GHOSTTY_TERMINAL_OPT_COLOR_SCHEME = 7,
513
514 /**
515 * Callback invoked in response to a device attributes query
516 * (CSI c, CSI > c, or CSI = c). Return true and fill the out
517 * pointer with response data, or return false to silently ignore.
518 * Set to NULL to ignore device attributes queries.
519 *
520 * Input type: GhosttyTerminalDeviceAttributesFn
521 */
522 GHOSTTY_TERMINAL_OPT_DEVICE_ATTRIBUTES = 8,
523
524 /**
525 * Set the terminal title manually.
526 *
527 * The string data is copied into the terminal. A NULL value pointer
528 * clears the title (equivalent to setting an empty string).
529 *
530 * Input type: GhosttyString*
531 */
532 GHOSTTY_TERMINAL_OPT_TITLE = 9,
533
534 /**
535 * Set the terminal working directory manually.
536 *
537 * The string data is copied into the terminal. A NULL value pointer
538 * clears the pwd (equivalent to setting an empty string).
539 *
540 * Input type: GhosttyString*
541 */
542 GHOSTTY_TERMINAL_OPT_PWD = 10,
543
544 /**
545 * Set the default foreground color.
546 *
547 * A NULL value pointer clears the default (unset).
548 *
549 * Input type: GhosttyColorRgb*
550 */
551 GHOSTTY_TERMINAL_OPT_COLOR_FOREGROUND = 11,
552
553 /**
554 * Set the default background color.
555 *
556 * A NULL value pointer clears the default (unset).
557 *
558 * Input type: GhosttyColorRgb*
559 */
560 GHOSTTY_TERMINAL_OPT_COLOR_BACKGROUND = 12,
561
562 /**
563 * Set the default cursor color.
564 *
565 * A NULL value pointer clears the default (unset).
566 *
567 * Input type: GhosttyColorRgb*
568 */
569 GHOSTTY_TERMINAL_OPT_COLOR_CURSOR = 13,
570
571 /**
572 * Set the default 256-color palette.
573 *
574 * The value must point to an array of exactly 256 GhosttyColorRgb values.
575 * A NULL value pointer resets to the built-in default palette.
576 *
577 * Input type: GhosttyColorRgb[256]*
578 */
579 GHOSTTY_TERMINAL_OPT_COLOR_PALETTE = 14,
580
581 /**
582 * Set the Kitty image storage limit in bytes.
583 *
584 * Applied to all initialized screens (primary and alternate).
585 * A value of zero disables the Kitty graphics protocol entirely,
586 * deleting all stored images and placements. A NULL value pointer
587 * is equivalent to zero (disables). Has no effect when Kitty graphics
588 * are disabled at build time.
589 *
590 * Input type: uint64_t*
591 */
592 GHOSTTY_TERMINAL_OPT_KITTY_IMAGE_STORAGE_LIMIT = 15,
593
594 /**
595 * Enable or disable Kitty image loading via the file medium.
596 *
597 * A NULL value pointer is a no-op. Has no effect when Kitty graphics
598 * are disabled at build time.
599 *
600 * Input type: bool*
601 */
602 GHOSTTY_TERMINAL_OPT_KITTY_IMAGE_MEDIUM_FILE = 16,
603
604 /**
605 * Enable or disable Kitty image loading via the temporary file medium.
606 *
607 * A NULL value pointer is a no-op. Has no effect when Kitty graphics
608 * are disabled at build time.
609 *
610 * Input type: bool*
611 */
612 GHOSTTY_TERMINAL_OPT_KITTY_IMAGE_MEDIUM_TEMP_FILE = 17,
613
614 /**
615 * Enable or disable Kitty image loading via the shared memory medium.
616 *
617 * A NULL value pointer is a no-op. Has no effect when Kitty graphics
618 * are disabled at build time.
619 *
620 * Input type: bool*
621 */
622 GHOSTTY_TERMINAL_OPT_KITTY_IMAGE_MEDIUM_SHARED_MEM = 18,
623
624 /**
625 * Set the maximum bytes the APC handler will buffer for all protocols.
626 * This prevents malicious input from causing unbounded memory allocation.
627 * A NULL value pointer removes all overrides, reverting to the built-in
628 * defaults.
629 *
630 * Input type: size_t*
631 */
632 GHOSTTY_TERMINAL_OPT_APC_MAX_BYTES = 19,
633
634 /**
635 * Set the maximum bytes the APC handler will buffer for Kitty graphics
636 * protocol data. A NULL value pointer removes the override, reverting
637 * to the built-in default.
638 *
639 * Input type: size_t*
640 */
641 GHOSTTY_TERMINAL_OPT_APC_MAX_BYTES_KITTY = 20,
642
643 /**
644 * Set the active screen selection.
645 *
646 * The value must point to a GhosttySelection whose grid references are
647 * valid for this terminal's active screen at the time of the call. The
648 * terminal copies the selection immediately and converts it to
649 * terminal-owned tracked state, so the GhosttySelection struct and its
650 * untracked grid references do not need to outlive this call.
651 *
652 * Passing NULL clears the active screen selection.
653 *
654 * Input type: GhosttySelection*
655 */
656 GHOSTTY_TERMINAL_OPT_SELECTION = 21,
657
658 /**
659 * Set the default cursor style used by DECSCUSR reset (CSI 0 q).
660 *
661 * A NULL value pointer resets to the built-in default block cursor.
662 *
663 * Input type: GhosttyTerminalCursorStyle*
664 */
665 GHOSTTY_TERMINAL_OPT_DEFAULT_CURSOR_STYLE = 22,
666
667 /**
668 * Set whether the default cursor should blink when reset by DECSCUSR
669 * (CSI 0 q).
670 *
671 * A NULL value pointer resets to the built-in default of not blinking.
672 *
673 * Input type: bool*
674 */
675 GHOSTTY_TERMINAL_OPT_DEFAULT_CURSOR_BLINK = 23,
676
677 /**
678 * Enable or disable Glyph Protocol APC handling.
679 *
680 * When disabled, Glyph Protocol APC sequences are ignored and no
681 * support/query/register/clear responses are emitted. Disabling also clears
682 * the terminal session's glyph glossary. A NULL value pointer is a no-op.
683 *
684 * Input type: bool*
685 */
686 GHOSTTY_TERMINAL_OPT_GLYPH_PROTOCOL = 24,
687
688 /**
689 * Callback invoked when the terminal pwd changes via escape
690 * sequences (OSC 7, OSC 9, or OSC 1337 CurrentDir). Set to NULL
691 * to ignore pwd change events.
692 *
693 * Input type: GhosttyTerminalPwdChangedFn
694 */
695 GHOSTTY_TERMINAL_OPT_PWD_CHANGED = 25,
696 GHOSTTY_TERMINAL_OPT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
697} GhosttyTerminalOption;
698
699/**
700 * Terminal data types.
701 *
702 * These values specify what type of data to extract from a terminal
703 * using `ghostty_terminal_get`.
704 *
705 * @ingroup terminal
706 */
707typedef enum GHOSTTY_ENUM_TYPED {
708 /** Invalid data type. Never results in any data extraction. */
709 GHOSTTY_TERMINAL_DATA_INVALID = 0,
710
711 /**
712 * Terminal width in cells.
713 *
714 * Output type: uint16_t *
715 */
716 GHOSTTY_TERMINAL_DATA_COLS = 1,
717
718 /**
719 * Terminal height in cells.
720 *
721 * Output type: uint16_t *
722 */
723 GHOSTTY_TERMINAL_DATA_ROWS = 2,
724
725 /**
726 * Cursor column position (0-indexed).
727 *
728 * Output type: uint16_t *
729 */
730 GHOSTTY_TERMINAL_DATA_CURSOR_X = 3,
731
732 /**
733 * Cursor row position within the active area (0-indexed).
734 *
735 * Output type: uint16_t *
736 */
737 GHOSTTY_TERMINAL_DATA_CURSOR_Y = 4,
738
739 /**
740 * Whether the cursor has a pending wrap (next print will soft-wrap).
741 *
742 * Output type: bool *
743 */
744 GHOSTTY_TERMINAL_DATA_CURSOR_PENDING_WRAP = 5,
745
746 /**
747 * The currently active screen.
748 *
749 * Output type: GhosttyTerminalScreen *
750 */
751 GHOSTTY_TERMINAL_DATA_ACTIVE_SCREEN = 6,
752
753 /**
754 * Whether the cursor is visible (DEC mode 25).
755 *
756 * Output type: bool *
757 */
758 GHOSTTY_TERMINAL_DATA_CURSOR_VISIBLE = 7,
759
760 /**
761 * Current Kitty keyboard protocol flags.
762 *
763 * Output type: GhosttyKittyKeyFlags * (uint8_t *)
764 */
765 GHOSTTY_TERMINAL_DATA_KITTY_KEYBOARD_FLAGS = 8,
766
767 /**
768 * Scrollbar state for the terminal viewport.
769 *
770 * This may be expensive to calculate depending on where the viewport
771 * is (arbitrary pins are expensive). The caller should take care to only
772 * call this as needed and not too frequently.
773 *
774 * Output type: GhosttyTerminalScrollbar *
775 */
776 GHOSTTY_TERMINAL_DATA_SCROLLBAR = 9,
777
778 /**
779 * The current SGR style of the cursor.
780 *
781 * This is the style that will be applied to newly printed characters.
782 *
783 * Output type: GhosttyStyle *
784 */
785 GHOSTTY_TERMINAL_DATA_CURSOR_STYLE = 10,
786
787 /**
788 * Whether any mouse tracking mode is active.
789 *
790 * Returns true if any of the mouse tracking modes (X10, normal, button,
791 * or any-event) are enabled.
792 *
793 * Output type: bool *
794 */
795 GHOSTTY_TERMINAL_DATA_MOUSE_TRACKING = 11,
796
797 /**
798 * The terminal title as set by escape sequences (e.g. OSC 0/2).
799 *
800 * Returns a borrowed string. The pointer is valid until the next call
801 * to ghostty_terminal_vt_write() or ghostty_terminal_reset(). An empty
802 * string (len=0) is returned when no title has been set.
803 *
804 * Output type: GhosttyString *
805 */
806 GHOSTTY_TERMINAL_DATA_TITLE = 12,
807
808 /**
809 * The terminal's current working directory as set by escape sequences
810 * (e.g. OSC 7).
811 *
812 * Returns a borrowed string. The pointer is valid until the next call
813 * to ghostty_terminal_vt_write() or ghostty_terminal_reset(). An empty
814 * string (len=0) is returned when no pwd has been set.
815 *
816 * Output type: GhosttyString *
817 */
818 GHOSTTY_TERMINAL_DATA_PWD = 13,
819
820 /**
821 * The total number of rows in the active screen including scrollback.
822 *
823 * Output type: size_t *
824 */
825 GHOSTTY_TERMINAL_DATA_TOTAL_ROWS = 14,
826
827 /**
828 * The number of scrollback rows (total rows minus viewport rows).
829 *
830 * Output type: size_t *
831 */
832 GHOSTTY_TERMINAL_DATA_SCROLLBACK_ROWS = 15,
833
834 /**
835 * The total width of the terminal in pixels.
836 *
837 * This is cols * cell_width_px as set by ghostty_terminal_resize().
838 *
839 * Output type: uint32_t *
840 */
841 GHOSTTY_TERMINAL_DATA_WIDTH_PX = 16,
842
843 /**
844 * The total height of the terminal in pixels.
845 *
846 * This is rows * cell_height_px as set by ghostty_terminal_resize().
847 *
848 * Output type: uint32_t *
849 */
850 GHOSTTY_TERMINAL_DATA_HEIGHT_PX = 17,
851
852 /**
853 * The effective foreground color (override or default).
854 *
855 * Returns GHOSTTY_NO_VALUE if no foreground color is set.
856 *
857 * Output type: GhosttyColorRgb *
858 */
859 GHOSTTY_TERMINAL_DATA_COLOR_FOREGROUND = 18,
860
861 /**
862 * The effective background color (override or default).
863 *
864 * Returns GHOSTTY_NO_VALUE if no background color is set.
865 *
866 * Output type: GhosttyColorRgb *
867 */
868 GHOSTTY_TERMINAL_DATA_COLOR_BACKGROUND = 19,
869
870 /**
871 * The effective cursor color (override or default).
872 *
873 * Returns GHOSTTY_NO_VALUE if no cursor color is set.
874 *
875 * Output type: GhosttyColorRgb *
876 */
877 GHOSTTY_TERMINAL_DATA_COLOR_CURSOR = 20,
878
879 /**
880 * The current 256-color palette.
881 *
882 * Output type: GhosttyColorRgb[256] *
883 */
884 GHOSTTY_TERMINAL_DATA_COLOR_PALETTE = 21,
885
886 /**
887 * The default foreground color (ignoring any OSC override).
888 *
889 * Returns GHOSTTY_NO_VALUE if no default foreground color is set.
890 *
891 * Output type: GhosttyColorRgb *
892 */
893 GHOSTTY_TERMINAL_DATA_COLOR_FOREGROUND_DEFAULT = 22,
894
895 /**
896 * The default background color (ignoring any OSC override).
897 *
898 * Returns GHOSTTY_NO_VALUE if no default background color is set.
899 *
900 * Output type: GhosttyColorRgb *
901 */
902 GHOSTTY_TERMINAL_DATA_COLOR_BACKGROUND_DEFAULT = 23,
903
904 /**
905 * The default cursor color (ignoring any OSC override).
906 *
907 * Returns GHOSTTY_NO_VALUE if no default cursor color is set.
908 *
909 * Output type: GhosttyColorRgb *
910 */
911 GHOSTTY_TERMINAL_DATA_COLOR_CURSOR_DEFAULT = 24,
912
913 /**
914 * The default 256-color palette (ignoring any OSC overrides).
915 *
916 * Output type: GhosttyColorRgb[256] *
917 */
918 GHOSTTY_TERMINAL_DATA_COLOR_PALETTE_DEFAULT = 25,
919
920 /**
921 * The Kitty image storage limit in bytes for the active screen.
922 *
923 * A value of zero means the Kitty graphics protocol is disabled.
924 * Returns GHOSTTY_NO_VALUE when Kitty graphics are disabled at build time.
925 *
926 * Output type: uint64_t *
927 */
928 GHOSTTY_TERMINAL_DATA_KITTY_IMAGE_STORAGE_LIMIT = 26,
929
930 /**
931 * Whether the file medium is enabled for Kitty image loading on the
932 * active screen.
933 *
934 * Returns GHOSTTY_NO_VALUE when Kitty graphics are disabled at build time.
935 *
936 * Output type: bool *
937 */
938 GHOSTTY_TERMINAL_DATA_KITTY_IMAGE_MEDIUM_FILE = 27,
939
940 /**
941 * Whether the temporary file medium is enabled for Kitty image loading
942 * on the active screen.
943 *
944 * Returns GHOSTTY_NO_VALUE when Kitty graphics are disabled at build time.
945 *
946 * Output type: bool *
947 */
948 GHOSTTY_TERMINAL_DATA_KITTY_IMAGE_MEDIUM_TEMP_FILE = 28,
949
950 /**
951 * Whether the shared memory medium is enabled for Kitty image loading
952 * on the active screen.
953 *
954 * Returns GHOSTTY_NO_VALUE when Kitty graphics are disabled at build time.
955 *
956 * Output type: bool *
957 */
958 GHOSTTY_TERMINAL_DATA_KITTY_IMAGE_MEDIUM_SHARED_MEM = 29,
959
960 /**
961 * The Kitty graphics image storage for the active screen.
962 *
963 * Returns a borrowed pointer to the image storage. The pointer is valid
964 * until the next mutating terminal call (e.g. ghostty_terminal_vt_write()
965 * or ghostty_terminal_reset()).
966 *
967 * Returns GHOSTTY_NO_VALUE when Kitty graphics are disabled at build time.
968 *
969 * Output type: GhosttyKittyGraphics *
970 */
971 GHOSTTY_TERMINAL_DATA_KITTY_GRAPHICS = 30,
972
973 /**
974 * The active screen's current selection.
975 *
976 * On success, writes an untracked snapshot of the terminal-owned selection
977 * to the caller-provided GhosttySelection. The GhosttySelection struct is
978 * caller-owned and may be kept, but the grid references inside it are
979 * untracked borrowed references into the active screen. They are only valid
980 * until the next mutating terminal call, such as ghostty_terminal_set(),
981 * ghostty_terminal_vt_write(), ghostty_terminal_resize(), or
982 * ghostty_terminal_reset().
983 *
984 * Returns GHOSTTY_NO_VALUE when there is no active selection.
985 *
986 * Output type: GhosttySelection *
987 */
988 GHOSTTY_TERMINAL_DATA_SELECTION = 31,
989
990 /**
991 * Whether the viewport is currently pinned to the active area.
992 *
993 * This is true when the viewport is following the active terminal area,
994 * and false when the user has scrolled into history.
995 *
996 * Output type: bool *
997 */
998 GHOSTTY_TERMINAL_DATA_VIEWPORT_ACTIVE = 32,
999 GHOSTTY_TERMINAL_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
1000} GhosttyTerminalData;
1001
1002/**
1003 * Create a new terminal instance.
1004 *
1005 * @param allocator Pointer to allocator, or NULL to use the default allocator
1006 * @param terminal Pointer to store the created terminal handle
1007 * @param options Terminal initialization options
1008 * @return GHOSTTY_SUCCESS on success, or an error code on failure
1009 *
1010 * @ingroup terminal
1011 */
1012GHOSTTY_API GhosttyResult ghostty_terminal_new(const GhosttyAllocator* allocator,
1013 GhosttyTerminal* terminal,
1014 GhosttyTerminalOptions options);
1015
1016/**
1017 * Free a terminal instance.
1018 *
1019 * Releases all resources associated with the terminal. After this call,
1020 * the terminal handle becomes invalid and must not be used.
1021 *
1022 * @param terminal The terminal handle to free (may be NULL)
1023 *
1024 * @ingroup terminal
1025 */
1026GHOSTTY_API void ghostty_terminal_free(GhosttyTerminal terminal);
1027
1028/**
1029 * Perform a full reset of the terminal (RIS).
1030 *
1031 * Resets all terminal state back to its initial configuration, including
1032 * modes, scrollback, scrolling region, and screen contents. The terminal
1033 * dimensions are preserved.
1034 *
1035 * @param terminal The terminal handle (may be NULL, in which case this is a no-op)
1036 *
1037 * @ingroup terminal
1038 */
1039GHOSTTY_API void ghostty_terminal_reset(GhosttyTerminal terminal);
1040
1041/**
1042 * Resize the terminal to the given dimensions.
1043 *
1044 * Changes the number of columns and rows in the terminal. The primary
1045 * screen will reflow content if wraparound mode is enabled; the alternate
1046 * screen does not reflow. If the dimensions are unchanged, this is a no-op.
1047 *
1048 * This also updates the terminal's pixel dimensions (used for image
1049 * protocols and size reports), disables synchronized output mode (allowed
1050 * by the spec so that resize results are shown immediately), and sends an
1051 * in-band size report if mode 2048 is enabled.
1052 *
1053 * @param terminal The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
1054 * @param cols New width in cells (must be greater than zero)
1055 * @param rows New height in cells (must be greater than zero)
1056 * @param cell_width_px Width of a single cell in pixels
1057 * @param cell_height_px Height of a single cell in pixels
1058 * @return GHOSTTY_SUCCESS on success, or an error code on failure
1059 *
1060 * @ingroup terminal
1061 */
1062GHOSTTY_API GhosttyResult ghostty_terminal_resize(GhosttyTerminal terminal,
1063 uint16_t cols,
1064 uint16_t rows,
1065 uint32_t cell_width_px,
1066 uint32_t cell_height_px);
1067
1068/**
1069 * Set an option on the terminal.
1070 *
1071 * Configures terminal callbacks and associated state such as the
1072 * write_pty callback and userdata pointer. The value is passed
1073 * directly for pointer types (callbacks, userdata) or as a pointer
1074 * to the value for non-pointer types (e.g. GhosttyString*).
1075 * NULL clears the option to its default.
1076 *
1077 * Callbacks are invoked synchronously during ghostty_terminal_vt_write().
1078 * Callbacks must not call ghostty_terminal_vt_write() on the same
1079 * terminal (no reentrancy).
1080 *
1081 * @param terminal The terminal handle (may be NULL, in which case this is a no-op)
1082 * @param option The option to set
1083 * @param value Pointer to the value to set (type depends on the option),
1084 * or NULL to clear the option
1085 *
1086 * @ingroup terminal
1087 */
1088GHOSTTY_API GhosttyResult ghostty_terminal_set(GhosttyTerminal terminal,
1089 GhosttyTerminalOption option,
1090 const void* value);
1091
1092/**
1093 * Write VT-encoded data to the terminal for processing.
1094 *
1095 * Feeds raw bytes through the terminal's VT stream parser, updating
1096 * terminal state accordingly. By default, sequences that require output
1097 * (queries, device status reports) are silently ignored. Use
1098 * ghostty_terminal_set() with GHOSTTY_TERMINAL_OPT_WRITE_PTY to install
1099 * a callback that receives response data.
1100 *
1101 * This never fails. Any erroneous input or errors in processing the
1102 * input are logged internally but do not cause this function to fail
1103 * because this input is assumed to be untrusted and from an external
1104 * source; so the primary goal is to keep the terminal state consistent and
1105 * not allow malformed input to corrupt or crash.
1106 *
1107 * @param terminal The terminal handle
1108 * @param data Pointer to the data to write
1109 * @param len Length of the data in bytes
1110 *
1111 * @ingroup terminal
1112 */
1113GHOSTTY_API void ghostty_terminal_vt_write(GhosttyTerminal terminal,
1114 const uint8_t* data,
1115 size_t len);
1116
1117/**
1118 * Scroll the terminal viewport.
1119 *
1120 * Scrolls the terminal's viewport according to the given behavior.
1121 * When using GHOSTTY_SCROLL_VIEWPORT_DELTA, set the delta field in
1122 * the value union to specify the number of rows to scroll (negative
1123 * for up, positive for down). For other behaviors, the value is ignored.
1124 *
1125 * @param terminal The terminal handle (may be NULL, in which case this is a no-op)
1126 * @param behavior The scroll behavior as a tagged union
1127 *
1128 * @ingroup terminal
1129 */
1130GHOSTTY_API void ghostty_terminal_scroll_viewport(GhosttyTerminal terminal,
1131 GhosttyTerminalScrollViewport behavior);
1132
1133/**
1134 * Get the current value of a terminal mode.
1135 *
1136 * Returns the value of the mode identified by the given mode.
1137 *
1138 * @param terminal The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
1139 * @param mode The mode identifying the mode to query
1140 * @param[out] out_value On success, set to true if the mode is set, false
1141 * if it is reset
1142 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the terminal
1143 * is NULL or the mode does not correspond to a known mode
1144 *
1145 * @ingroup terminal
1146 */
1147GHOSTTY_API GhosttyResult ghostty_terminal_mode_get(GhosttyTerminal terminal,
1148 GhosttyMode mode,
1149 bool* out_value);
1150
1151/**
1152 * Set the value of a terminal mode.
1153 *
1154 * Sets the mode identified by the given mode to the specified value.
1155 *
1156 * @param terminal The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
1157 * @param mode The mode identifying the mode to set
1158 * @param value true to set the mode, false to reset it
1159 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the terminal
1160 * is NULL or the mode does not correspond to a known mode
1161 *
1162 * @ingroup terminal
1163 */
1164GHOSTTY_API GhosttyResult ghostty_terminal_mode_set(GhosttyTerminal terminal,
1165 GhosttyMode mode,
1166 bool value);
1167
1168/**
1169 * Get data from a terminal instance.
1170 *
1171 * Extracts typed data from the given terminal based on the specified
1172 * data type. The output pointer must be of the appropriate type for the
1173 * requested data kind. Valid data types and output types are documented
1174 * in the `GhosttyTerminalData` enum.
1175 *
1176 * @param terminal The terminal handle (may be NULL)
1177 * @param data The type of data to extract
1178 * @param out Pointer to store the extracted data (type depends on data parameter)
1179 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the terminal
1180 * is NULL or the data type is invalid
1181 *
1182 * @ingroup terminal
1183 */
1184GHOSTTY_API GhosttyResult ghostty_terminal_get(GhosttyTerminal terminal,
1185 GhosttyTerminalData data,
1186 void *out);
1187
1188/**
1189 * Get multiple data fields from a terminal in a single call.
1190 *
1191 * This is an optimization over calling ghostty_terminal_get()
1192 * repeatedly, particularly useful in environments with high per-call
1193 * overhead such as FFI or Cgo.
1194 *
1195 * Each element in the keys array specifies a data kind, and the
1196 * corresponding element in the values array receives the result.
1197 * The type of each values[i] pointer must match the output type
1198 * documented for keys[i].
1199 *
1200 * Processing stops at the first error; on success out_written
1201 * is set to count, on error it is set to the index of the
1202 * failing key (i.e. the number of values successfully written).
1203 *
1204 * @param terminal The terminal handle (may be NULL)
1205 * @param count Number of key/value pairs
1206 * @param keys Array of data kinds to query
1207 * @param values Array of output pointers (types must match each key's
1208 * documented output type)
1209 * @param[out] out_written On return, receives the number of values
1210 * successfully written (may be NULL)
1211 * @return GHOSTTY_SUCCESS if all queries succeed
1212 *
1213 * @ingroup terminal
1214 */
1215GHOSTTY_API GhosttyResult ghostty_terminal_get_multi(GhosttyTerminal terminal,
1216 size_t count,
1217 const GhosttyTerminalData* keys,
1218 void** values,
1219 size_t* out_written);
1220
1221/**
1222 * Resolve a point in the terminal grid to a grid reference.
1223 *
1224 * Resolves the given point (which can be in active, viewport, screen,
1225 * or history coordinates) to a grid reference for that location. Use
1226 * ghostty_grid_ref_cell() and ghostty_grid_ref_row() to extract the cell
1227 * and row.
1228 *
1229 * Lookups using the `active` and `viewport` tags are fast. The `screen`
1230 * and `history` tags may require traversing the full scrollback page list
1231 * to resolve the y coordinate, so they can be expensive for large
1232 * scrollback buffers.
1233 *
1234 * This function isn't meant to be used as the core of render loop. It
1235 * isn't built to sustain the framerates needed for rendering large screens.
1236 * Use the render state API for that. This API is instead meant for less
1237 * strictly performance-sensitive use cases.
1238 *
1239 * @param terminal The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
1240 * @param point The point specifying which cell to look up
1241 * @param[out] out_ref On success, set to the grid reference at the given point (may be NULL)
1242 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the terminal
1243 * is NULL or the point is out of bounds
1244 *
1245 * @ingroup terminal
1246 */
1247GHOSTTY_API GhosttyResult ghostty_terminal_grid_ref(GhosttyTerminal terminal,
1248 GhosttyPoint point,
1249 GhosttyGridRef *out_ref);
1250
1251/**
1252 * Create an owned tracked grid reference for a terminal point.
1253 *
1254 * This is the tracked variant of ghostty_terminal_grid_ref(). The returned
1255 * handle follows the referenced cell as the terminal's page list is modified:
1256 * scrolling, pruning, resize/reflow, and other page-list operations update the
1257 * tracked reference automatically.
1258 *
1259 * The reference is attached to the terminal screen/page-list that is active at
1260 * creation time.
1261 *
1262 * If the point is outside the requested coordinate space, this returns
1263 * GHOSTTY_INVALID_VALUE and writes NULL to out_ref.
1264 *
1265 * The returned handle must be freed with ghostty_tracked_grid_ref_free(). If
1266 * the terminal is freed first, the handle remains valid only for
1267 * tracked-grid-ref APIs: it reports no value and can still be freed.
1268 *
1269 * @param terminal Terminal instance.
1270 * @param point Point to track.
1271 * @param[out] out_ref On success, receives the tracked reference handle.
1272 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if terminal,
1273 * point, or out_ref is invalid, or GHOSTTY_OUT_OF_MEMORY if allocation
1274 * fails.
1275 *
1276 * @ingroup terminal
1277 */
1278GHOSTTY_API GhosttyResult ghostty_terminal_grid_ref_track(
1279 GhosttyTerminal terminal,
1280 GhosttyPoint point,
1281 GhosttyTrackedGridRef *out_ref);
1282
1283/**
1284 * Convert a grid reference back to a point in the given coordinate system.
1285 *
1286 * This is the inverse of ghostty_terminal_grid_ref(): given a grid reference,
1287 * it returns the x/y coordinates in the requested coordinate system (active,
1288 * viewport, screen, or history).
1289 *
1290 * The grid reference must have been obtained from the same terminal instance.
1291 * Like all grid references, it is only valid until the next mutating terminal
1292 * call.
1293 *
1294 * Not every grid reference is representable in every coordinate system. For
1295 * example, a cell in scrollback history cannot be expressed in active
1296 * coordinates, and a cell that has scrolled off the visible area cannot be
1297 * expressed in viewport coordinates. In these cases, the function returns
1298 * GHOSTTY_NO_VALUE.
1299 *
1300 * @param terminal The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
1301 * @param ref Pointer to the grid reference to convert
1302 * @param tag The target coordinate system
1303 * @param[out] out On success, set to the coordinate in the requested system (may be NULL)
1304 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the terminal
1305 * or ref is NULL/invalid, GHOSTTY_NO_VALUE if the ref falls outside
1306 * the requested coordinate system
1307 *
1308 * @ingroup terminal
1309 */
1310GHOSTTY_API GhosttyResult ghostty_terminal_point_from_grid_ref(
1311 GhosttyTerminal terminal,
1312 const GhosttyGridRef *ref,
1313 GhosttyPointTag tag,
1314 GhosttyPointCoordinate *out);
1315
1316/** @} */
1317
1318#ifdef __cplusplus
1319}
1320#endif
1321
1322#endif /* GHOSTTY_VT_TERMINAL_H */
apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/types.h deleted-335
......@@ -1,335 +0,0 @@
1/**
2 * @file types.h
3 *
4 * Common types, macros, and utilities for libghostty-vt.
5 */
6
7#ifndef GHOSTTY_VT_TYPES_H
8#define GHOSTTY_VT_TYPES_H
9
10#include <limits.h>
11#include <stddef.h>
12#include <stdint.h>
13
14// Symbol visibility for shared library builds. On Windows, functions
15// are exported from the DLL when building and imported when consuming.
16// On other platforms with GCC/Clang, functions are marked with default
17// visibility so they remain accessible when the library is built with
18// -fvisibility=hidden. For static library builds, define GHOSTTY_STATIC
19// before including this header to make this a no-op.
20#ifndef GHOSTTY_API
21#if defined(GHOSTTY_STATIC)
22 #define GHOSTTY_API
23#elif defined(_WIN32) || defined(_WIN64)
24 #ifdef GHOSTTY_BUILD_SHARED
25 #define GHOSTTY_API __declspec(dllexport)
26 #else
27 #define GHOSTTY_API __declspec(dllimport)
28 #endif
29#elif defined(__GNUC__) && __GNUC__ >= 4
30 #define GHOSTTY_API __attribute__((visibility("default")))
31#else
32 #define GHOSTTY_API
33#endif
34#endif
35
36/**
37 * Enum int-sizing helpers.
38 *
39 * The Zig side backs all C enums with c_int, so the C declarations
40 * must use int as their underlying type to maintain ABI compatibility.
41 *
42 * C23 (detected via __STDC_VERSION__ >= 202311L) supports explicit
43 * enum underlying types with `enum : int { ... }`. For pre-C23
44 * compilers, which are free to choose any type that can represent
45 * all values (C11 §6.7.2.2), we add an INT_MAX sentinel as the last
46 * entry to force the compiler to use int.
47 *
48 * INT_MAX is used rather than a fixed constant like 0xFFFFFFFF
49 * because enum constants must have type int (which is signed).
50 * Values above INT_MAX overflow signed int and are a constraint
51 * violation in standard C; compilers that accept them interpret them
52 * as negative values via two's complement, which can collide with
53 * legitimate negative enum values.
54 *
55 * Usage:
56 * @code
57 * typedef enum GHOSTTY_ENUM_TYPED {
58 * FOO_A = 0,
59 * FOO_B = 1,
60 * FOO_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
61 * } Foo;
62 * @endcode
63 */
64#if defined(__STDC_VERSION__) && __STDC_VERSION__ >= 202311L
65#define GHOSTTY_ENUM_TYPED : int
66#else
67#define GHOSTTY_ENUM_TYPED
68#endif
69#define GHOSTTY_ENUM_MAX_VALUE INT_MAX
70
71/**
72 * Result codes for libghostty-vt operations.
73 */
74typedef enum GHOSTTY_ENUM_TYPED {
75 /** Operation completed successfully */
76 GHOSTTY_SUCCESS = 0,
77 /** Operation failed due to failed allocation */
78 GHOSTTY_OUT_OF_MEMORY = -1,
79 /** Operation failed due to invalid value */
80 GHOSTTY_INVALID_VALUE = -2,
81 /** Operation failed because the provided buffer was too small */
82 GHOSTTY_OUT_OF_SPACE = -3,
83 /** The requested value has no value */
84 GHOSTTY_NO_VALUE = -4,
85 GHOSTTY_RESULT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
86} GhosttyResult;
87
88/* ---- Opaque handles ---- */
89
90/**
91 * Opaque handle to a terminal instance.
92 *
93 * @ingroup terminal
94 */
95typedef struct GhosttyTerminalImpl* GhosttyTerminal;
96
97/**
98 * Opaque handle to a tracked grid reference.
99 *
100 * A tracked grid reference is owned by the caller and must be freed with
101 * ghostty_tracked_grid_ref_free(). If the terminal that created it is freed
102 * first, the handle remains valid only for tracked-grid-ref APIs: it reports no
103 * value and can still be freed.
104 *
105 * @ingroup grid_ref
106 */
107typedef struct GhosttyTrackedGridRefImpl* GhosttyTrackedGridRef;
108
109/**
110 * Opaque handle to a Kitty graphics image storage.
111 *
112 * Obtained via ghostty_terminal_get() with
113 * GHOSTTY_TERMINAL_DATA_KITTY_GRAPHICS. The pointer is borrowed from
114 * the terminal and remains valid until the next mutating terminal call
115 * (e.g. ghostty_terminal_vt_write() or ghostty_terminal_reset()).
116 *
117 * @ingroup kitty_graphics
118 */
119typedef struct GhosttyKittyGraphicsImpl* GhosttyKittyGraphics;
120
121/**
122 * Opaque handle to a Kitty graphics image.
123 *
124 * Obtained via ghostty_kitty_graphics_image() with an image ID. The
125 * pointer is borrowed from the storage and remains valid until the next
126 * mutating terminal call.
127 *
128 * @ingroup kitty_graphics
129 */
130typedef const struct GhosttyKittyGraphicsImageImpl* GhosttyKittyGraphicsImage;
131
132/**
133 * Opaque handle to a Kitty graphics placement iterator.
134 *
135 * @ingroup kitty_graphics
136 */
137typedef struct GhosttyKittyGraphicsPlacementIteratorImpl* GhosttyKittyGraphicsPlacementIterator;
138
139/**
140 * Opaque handle to a render state instance.
141 *
142 * @ingroup render
143 */
144typedef struct GhosttyRenderStateImpl* GhosttyRenderState;
145
146/**
147 * Opaque handle to a render-state row iterator.
148 *
149 * @ingroup render
150 */
151typedef struct GhosttyRenderStateRowIteratorImpl* GhosttyRenderStateRowIterator;
152
153/**
154 * Opaque handle to render-state row cells.
155 *
156 * @ingroup render
157 */
158typedef struct GhosttyRenderStateRowCellsImpl* GhosttyRenderStateRowCells;
159
160/**
161 * Opaque handle to an SGR parser instance.
162 *
163 * This handle represents an SGR (Select Graphic Rendition) parser that can
164 * be used to parse SGR sequences and extract individual text attributes.
165 *
166 * @ingroup sgr
167 */
168typedef struct GhosttySgrParserImpl* GhosttySgrParser;
169
170/**
171 * Opaque handle to a formatter instance.
172 *
173 * @ingroup formatter
174 */
175typedef struct GhosttyFormatterImpl* GhosttyFormatter;
176
177/**
178 * Opaque handle to an OSC parser instance.
179 *
180 * This handle represents an OSC (Operating System Command) parser that can
181 * be used to parse the contents of OSC sequences.
182 *
183 * @ingroup osc
184 */
185typedef struct GhosttyOscParserImpl* GhosttyOscParser;
186
187/**
188 * Opaque handle to a single OSC command.
189 *
190 * This handle represents a parsed OSC (Operating System Command) command.
191 * The command can be queried for its type and associated data.
192 *
193 * @ingroup osc
194 */
195typedef struct GhosttyOscCommandImpl* GhosttyOscCommand;
196
197/* ---- Common value types ---- */
198
199/**
200 * Terminal content output format.
201 *
202 * @ingroup formatter
203 */
204typedef enum GHOSTTY_ENUM_TYPED {
205 /** Plain text (no escape sequences). */
206 GHOSTTY_FORMATTER_FORMAT_PLAIN,
207
208 /** VT sequences preserving colors, styles, URLs, etc. */
209 GHOSTTY_FORMATTER_FORMAT_VT,
210
211 /** HTML with inline styles. */
212 GHOSTTY_FORMATTER_FORMAT_HTML,
213 GHOSTTY_FORMATTER_FORMAT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
214} GhosttyFormatterFormat;
215
216/**
217 * A borrowed byte string (pointer + length).
218 *
219 * The memory is not owned by this struct. The pointer is only valid
220 * for the lifetime documented by the API that produces or consumes it.
221 */
222typedef struct {
223 /** Pointer to the string bytes. */
224 const uint8_t* ptr;
225
226 /** Length of the string in bytes. */
227 size_t len;
228} GhosttyString;
229
230/**
231 * A caller-provided byte buffer.
232 *
233 * APIs that write to this type use `len` for the number of bytes written on
234 * GHOSTTY_SUCCESS and the required byte capacity on GHOSTTY_OUT_OF_SPACE.
235 */
236typedef struct {
237 /** Destination buffer for bytes. May be NULL when cap is 0 to query required size. */
238 uint8_t* ptr;
239
240 /** Capacity of ptr in bytes. */
241 size_t cap;
242
243 /** Bytes written on success, or required byte capacity on GHOSTTY_OUT_OF_SPACE. */
244 size_t len;
245} GhosttyBuffer;
246
247/**
248 * A surface-space position in pixels.
249 *
250 * This is not a terminal grid coordinate. It represents an x/y position in the
251 * rendered surface coordinate space, with (0, 0) at the top-left of the
252 * surface.
253 */
254typedef struct {
255 /** X position in surface pixels. */
256 double x;
257
258 /** Y position in surface pixels. */
259 double y;
260} GhosttySurfacePosition;
261
262/**
263 * A borrowed list of Unicode scalar values.
264 *
265 * Values are encoded as uint32_t scalar values. The memory is not owned by this
266 * struct. The pointer is only valid for the lifetime documented by the API that
267 * consumes or produces it.
268 *
269 * APIs may document special handling for NULL + len 0, such as “use defaults”.
270 */
271typedef struct {
272 /** Pointer to Unicode scalar values. */
273 const uint32_t* ptr;
274
275 /** Number of entries in ptr. */
276 size_t len;
277} GhosttyCodepoints;
278
279/**
280 * Initialize a sized struct to zero and set its size field.
281 *
282 * Sized structs use a `size` field as the first member for ABI
283 * compatibility. This macro zero-initializes the struct and sets the
284 * size field to `sizeof(type)`, which allows the library to detect
285 * which version of the struct the caller was compiled against.
286 *
287 * @param type The struct type to initialize
288 * @return A zero-initialized struct with the size field set
289 *
290 * Example:
291 * @code
292 * GhosttyFormatterTerminalOptions opts = GHOSTTY_INIT_SIZED(GhosttyFormatterTerminalOptions);
293 * opts.emit = GHOSTTY_FORMATTER_FORMAT_PLAIN;
294 * opts.trim = true;
295 * @endcode
296 */
297#define GHOSTTY_INIT_SIZED(type) \
298 ((type){ .size = sizeof(type) })
299
300/**
301 * Return a pointer to a null-terminated JSON string describing the
302 * layout of every C API struct for the current target.
303 *
304 * This is primarily useful for language bindings that can't easily
305 * set C struct fields and need to do so via byte offsets. For example,
306 * WebAssembly modules can't share struct definitions with the host.
307 *
308 * Example (abbreviated):
309 * @code{.json}
310 * {
311 * "GhosttyMouseEncoderSize": {
312 * "size": 40,
313 * "align": 8,
314 * "fields": {
315 * "size": { "offset": 0, "size": 8, "type": "u64" },
316 * "screen_width": { "offset": 8, "size": 4, "type": "u32" },
317 * "screen_height": { "offset": 12, "size": 4, "type": "u32" },
318 * "cell_width": { "offset": 16, "size": 4, "type": "u32" },
319 * "cell_height": { "offset": 20, "size": 4, "type": "u32" },
320 * "padding_top": { "offset": 24, "size": 4, "type": "u32" },
321 * "padding_bottom": { "offset": 28, "size": 4, "type": "u32" },
322 * "padding_right": { "offset": 32, "size": 4, "type": "u32" },
323 * "padding_left": { "offset": 36, "size": 4, "type": "u32" }
324 * }
325 * }
326 * }
327 * @endcode
328 *
329 * The returned pointer is valid for the lifetime of the process.
330 *
331 * @return Pointer to the null-terminated JSON string.
332 */
333GHOSTTY_API const char *ghostty_type_json(void);
334
335#endif /* GHOSTTY_VT_TYPES_H */
apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/wasm.h deleted-160
......@@ -1,160 +0,0 @@
1/**
2 * @file wasm.h
3 *
4 * WebAssembly utility functions for libghostty-vt.
5 */
6
7#ifndef GHOSTTY_VT_WASM_H
8#define GHOSTTY_VT_WASM_H
9
10#ifdef __wasm__
11
12#include <stddef.h>
13#include <stdint.h>
14#include <ghostty/vt/types.h>
15
16/** @defgroup wasm WebAssembly Utilities
17 *
18 * Convenience functions for allocating various types in WebAssembly builds.
19 * **These are only available the libghostty-vt wasm module.**
20 *
21 * Ghostty relies on pointers to various types for ABI compatibility, and
22 * creating those pointers in Wasm can be tedious. These functions provide
23 * a purely additive set of utilities that simplify memory management in
24 * Wasm environments without changing the core C library API.
25 *
26 * @note These functions always use the default allocator. If you need
27 * custom allocation strategies, you should allocate types manually using
28 * your custom allocator. This is a very rare use case in the WebAssembly
29 * world so these are optimized for simplicity.
30 *
31 * ## Example Usage
32 *
33 * Here's a simple example of using the Wasm utilities with the key encoder:
34 *
35 * @code
36 * const { exports } = wasmInstance;
37 * const view = new DataView(wasmMemory.buffer);
38 *
39 * // Create key encoder
40 * const encoderPtr = exports.ghostty_wasm_alloc_opaque();
41 * exports.ghostty_key_encoder_new(null, encoderPtr);
42 * const encoder = view.getUint32(encoder, true);
43 *
44 * // Configure encoder with Kitty protocol flags
45 * const flagsPtr = exports.ghostty_wasm_alloc_u8();
46 * view.setUint8(flagsPtr, 0x1F);
47 * exports.ghostty_key_encoder_setopt(encoder, 5, flagsPtr);
48 *
49 * // Allocate output buffer and size pointer
50 * const bufferSize = 32;
51 * const bufPtr = exports.ghostty_wasm_alloc_u8_array(bufferSize);
52 * const writtenPtr = exports.ghostty_wasm_alloc_usize();
53 *
54 * // Encode the key event
55 * exports.ghostty_key_encoder_encode(
56 * encoder, eventPtr, bufPtr, bufferSize, writtenPtr
57 * );
58 *
59 * // Read encoded output
60 * const bytesWritten = view.getUint32(writtenPtr, true);
61 * const encoded = new Uint8Array(wasmMemory.buffer, bufPtr, bytesWritten);
62 * @endcode
63 *
64 * @remark The code above is pretty ugly! This is the lowest level interface
65 * to the libghostty-vt Wasm module. In practice, this should be wrapped
66 * in a higher-level API that abstracts away all this.
67 *
68 * @{
69 */
70
71/**
72 * Allocate an opaque pointer. This can be used for any opaque pointer
73 * types such as GhosttyKeyEncoder, GhosttyKeyEvent, etc.
74 *
75 * @return Pointer to allocated opaque pointer, or NULL if allocation failed
76 * @ingroup wasm
77 */
78GHOSTTY_API void** ghostty_wasm_alloc_opaque(void);
79
80/**
81 * Free an opaque pointer allocated by ghostty_wasm_alloc_opaque().
82 *
83 * @param ptr Pointer to free, or NULL (NULL is safely ignored)
84 * @ingroup wasm
85 */
86GHOSTTY_API void ghostty_wasm_free_opaque(void **ptr);
87
88/**
89 * Allocate an array of uint8_t values.
90 *
91 * @param len Number of uint8_t elements to allocate
92 * @return Pointer to allocated array, or NULL if allocation failed
93 * @ingroup wasm
94 */
95GHOSTTY_API uint8_t* ghostty_wasm_alloc_u8_array(size_t len);
96
97/**
98 * Free an array allocated by ghostty_wasm_alloc_u8_array().
99 *
100 * @param ptr Pointer to the array to free, or NULL (NULL is safely ignored)
101 * @param len Length of the array (must match the length passed to alloc)
102 * @ingroup wasm
103 */
104GHOSTTY_API void ghostty_wasm_free_u8_array(uint8_t *ptr, size_t len);
105
106/**
107 * Allocate an array of uint16_t values.
108 *
109 * @param len Number of uint16_t elements to allocate
110 * @return Pointer to allocated array, or NULL if allocation failed
111 * @ingroup wasm
112 */
113GHOSTTY_API uint16_t* ghostty_wasm_alloc_u16_array(size_t len);
114
115/**
116 * Free an array allocated by ghostty_wasm_alloc_u16_array().
117 *
118 * @param ptr Pointer to the array to free, or NULL (NULL is safely ignored)
119 * @param len Length of the array (must match the length passed to alloc)
120 * @ingroup wasm
121 */
122GHOSTTY_API void ghostty_wasm_free_u16_array(uint16_t *ptr, size_t len);
123
124/**
125 * Allocate a single uint8_t value.
126 *
127 * @return Pointer to allocated uint8_t, or NULL if allocation failed
128 * @ingroup wasm
129 */
130GHOSTTY_API uint8_t* ghostty_wasm_alloc_u8(void);
131
132/**
133 * Free a uint8_t allocated by ghostty_wasm_alloc_u8().
134 *
135 * @param ptr Pointer to free, or NULL (NULL is safely ignored)
136 * @ingroup wasm
137 */
138GHOSTTY_API void ghostty_wasm_free_u8(uint8_t *ptr);
139
140/**
141 * Allocate a single size_t value.
142 *
143 * @return Pointer to allocated size_t, or NULL if allocation failed
144 * @ingroup wasm
145 */
146GHOSTTY_API size_t* ghostty_wasm_alloc_usize(void);
147
148/**
149 * Free a size_t allocated by ghostty_wasm_alloc_usize().
150 *
151 * @param ptr Pointer to free, or NULL (NULL is safely ignored)
152 * @ingroup wasm
153 */
154GHOSTTY_API void ghostty_wasm_free_usize(size_t *ptr);
155
156/** @} */
157
158#endif /* __wasm__ */
159
160#endif /* GHOSTTY_VT_WASM_H */
apps/mobile/modules/t3-terminal/android/src/main/cpp/CMakeLists.txt+1-1
......@@ -13,7 +13,7 @@ add_library(t3terminal SHARED t3_terminal_jni.cpp)
1313
1414target_include_directories(
1515 t3terminal
16 PRIVATE "${CMAKE_CURRENT_SOURCE_DIR}/../../../../Vendor/libghostty-vt/include"
16 PRIVATE "${CMAKE_CURRENT_SOURCE_DIR}/../../../../../../../../native/libghostty-vt/include"
1717)
1818
1919target_link_options(
apps/mobile/modules/t3-terminal/scripts/build-libghostty-android.sh+1-1
......@@ -4,7 +4,7 @@ set -euo pipefail
44
55SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
66MODULE_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
7VENDOR_DIR="${MODULE_DIR}/Vendor/libghostty-vt"
7VENDOR_DIR="${MODULE_DIR}/../../../../native/libghostty-vt"
88PATCH_DIR="${SCRIPT_DIR}/libghostty-android-patches"
99
1010GHOSTTY_REVISION="${GHOSTTY_REVISION:-9f62873bf195e4d8a762d768a1405a5f2f7b1697}"
apps/web/scripts/build-libghostty-wasm.sh+2-2
......@@ -5,10 +5,10 @@ set -euo pipefail
55SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
66WEB_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
77REPO_DIR="$(cd "${WEB_DIR}/../.." && pwd)"
8MOBILE_VENDOR_DIR="${REPO_DIR}/apps/mobile/modules/t3-terminal/Vendor/libghostty-vt"
8CANONICAL_VENDOR_DIR="${REPO_DIR}/native/libghostty-vt"
99VENDOR_DIR="${WEB_DIR}/src/terminal/ghostty/vendor"
1010
11GHOSTTY_REVISION="$(tr -d '[:space:]' < "${MOBILE_VENDOR_DIR}/VERSION")"
11GHOSTTY_REVISION="$(tr -d '[:space:]' < "${CANONICAL_VENDOR_DIR}/VERSION")"
1212GHOSTTY_SOURCE_DIR="${GHOSTTY_SOURCE_DIR:-${HOME}/.cache/t3code/ghostty-${GHOSTTY_REVISION:0:8}}"
1313GHOSTTY_ZIG_VERSION="${GHOSTTY_ZIG_VERSION:-0.15.2}"
1414GHOSTTY_ZIG="${GHOSTTY_ZIG:-}"
apps/web/src/terminal/ghostty/README.md+1-1
......@@ -12,7 +12,7 @@ It is intentionally not an xterm compatibility layer.
1212 prompt glyphs render without a locally installed Nerd Font.
1313- `vendor/` holds only the artifacts, reproducibly generated by
1414 `apps/web/scripts/build-libghostty-wasm.sh`. The upstream pin and license live once, at
15 `apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/`; the wasm embeds the pinned revision
15 `native/libghostty-vt/` at the repository root; the wasm embeds the pinned revision
1616 in its build info and the ABI test verifies it against mobile's `VERSION`.
1717
1818Keep browser behavior here and terminal transport in the existing client runtime. Do not add React
apps/web/src/terminal/ghostty/runtimeAbi.test.ts+5-5
......@@ -2,7 +2,7 @@ import { describe, expect, it } from "vite-plus/test";
22
33import wasmDataUrl from "./vendor/ghostty-vt.wasm?inline";
44import writePtyWasmDataUrl from "./vendor/ghostty-write-pty.wasm?inline";
5import mobileVersion from "../../../../mobile/modules/t3-terminal/Vendor/libghostty-vt/VERSION?raw";
5import pinnedVersion from "../../../../../native/libghostty-vt/VERSION?raw";
66import { ghosttyKeyForCode } from "./keyCodes";
77
88type WasmFunction = (...args: number[]) => number;
......@@ -14,13 +14,13 @@ function decodeWasmDataUrl(dataUrl: string): Uint8Array {
1414}
1515
1616describe("vendored libghostty-vt WebAssembly", () => {
17 it("stays pinned to mobile's canonical revision and size budget", async () => {
17 it("stays pinned to the canonical revision and size budget", async () => {
1818 const wasm = decodeWasmDataUrl(wasmDataUrl);
1919 expect(wasm.byteLength).toBeLessThan(750_000);
2020
2121 // The artifact carries its own provenance: the build embeds the pinned
22 // revision as semver build metadata, so mobile's VERSION file is the
23 // single source of truth and drift is caught here without a copy.
22 // revision as semver build metadata, so the repository's canonical VERSION
23 // file is the single source of truth and drift is caught here without a copy.
2424 const result = await WebAssembly.instantiate(wasm.buffer as ArrayBuffer, {
2525 env: { log: () => {} },
2626 });
......@@ -35,7 +35,7 @@ describe("vendored libghostty-vt WebAssembly", () => {
3535 new Uint8Array(memory.buffer, view.getUint32(0, true), view.getUint32(4, true)),
3636 );
3737 call("ghostty_wasm_free_u8_array", out, 8);
38 expect(embeddedRevision).toBe(mobileVersion.trim());
38 expect(embeddedRevision).toBe(pinnedVersion.trim());
3939 });
4040
4141 it("creates, writes multi-codepoint graphemes, and frees repeated terminals", async () => {
docs/architecture/terminal-renderers.md+1-1
......@@ -12,7 +12,7 @@ boundaries, keyboard encoding, selection, and scrollback:
1212- Android links the native shared library and converts render state into a compact JNI snapshot.
1313- Web loads a separately cached WebAssembly build and reads render state into a Canvas 2D surface.
1414- Both artifacts are built from the revision in
15 `apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/VERSION`.
15 `native/libghostty-vt/VERSION`.
1616
1717The platform adapters deliberately own only platform behavior. Android owns its Kotlin Canvas and
1818touch integration. Web owns browser font shaping, the hidden IME textarea, clipboard and DOM input,
native/libghostty-vt/LICENSE created+21
......@@ -0,0 +1,21 @@
1MIT License
2
3Copyright (c) 2024 Mitchell Hashimoto, Ghostty contributors
4
5Permission is hereby granted, free of charge, to any person obtaining a copy
6of this software and associated documentation files (the "Software"), to deal
7in the Software without restriction, including without limitation the rights
8to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9copies of the Software, and to permit persons to whom the Software is
10furnished to do so, subject to the following conditions:
11
12The above copyright notice and this permission notice shall be included in all
13copies or substantial portions of the Software.
14
15THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21SOFTWARE.
native/libghostty-vt/VERSION created+1
......@@ -0,0 +1 @@
19f62873bf195e4d8a762d768a1405a5f2f7b1697
native/libghostty-vt/include/ghostty/vt.h created+154
......@@ -0,0 +1,154 @@
1/**
2 * @file vt.h
3 *
4 * libghostty-vt - Virtual terminal emulator library
5 *
6 * This library provides functionality for parsing and handling terminal
7 * escape sequences as well as maintaining terminal state such as styles,
8 * cursor position, screen, scrollback, and more.
9 *
10 * WARNING: This is an incomplete, work-in-progress API. It is not yet
11 * stable and is definitely going to change.
12 */
13
14/**
15 * @mainpage libghostty-vt - Virtual Terminal Emulator Library
16 *
17 * libghostty-vt is a C library which implements a modern terminal emulator,
18 * extracted from the [Ghostty](https://ghostty.org) terminal emulator.
19 *
20 * libghostty-vt contains the logic for handling the core parts of a terminal
21 * emulator: parsing terminal escape sequences, maintaining terminal state,
22 * encoding input events, etc. It can handle scrollback, line wrapping,
23 * reflow on resize, and more.
24 *
25 * @warning This library is currently in development and the API is not yet stable.
26 * Breaking changes are expected in future versions. Use with caution in production code.
27 *
28 * @section groups_sec API Reference
29 *
30 * The API is organized into the following groups:
31 * - @ref terminal "Terminal" - Complete terminal emulator state and rendering
32 * - @ref render "Render State" - Incremental render state updates for custom renderers
33 * - @ref formatter "Formatter" - Format terminal content as plain text, VT sequences, or HTML
34 * - @ref osc "OSC Parser" - Parse OSC (Operating System Command) sequences
35 * - @ref sgr "SGR Parser" - Parse SGR (Select Graphic Rendition) sequences
36 * - @ref paste "Paste Utilities" - Validate paste data safety
37 * - @ref build_info "Build Info" - Query compile-time build configuration
38 * - @ref allocator "Memory Management" - Memory management and custom allocators
39 * - @ref wasm "WebAssembly Utilities" - WebAssembly convenience functions
40 *
41 * Encoding related APIs:
42 * - @ref focus "Focus Encoding" - Encode focus in/out events into terminal sequences
43 * - @ref key "Key Encoding" - Encode key events into terminal sequences
44 * - @ref mouse "Mouse Encoding" - Encode mouse events into terminal sequences
45 *
46 * @section examples_sec Examples
47 *
48 * Complete working examples:
49 * - @ref c-vt-build-info/src/main.c - Build info query example
50 * - @ref c-vt/src/main.c - OSC parser example
51 * - @ref c-vt-encode-key/src/main.c - Key encoding example
52 * - @ref c-vt-encode-mouse/src/main.c - Mouse encoding example
53 * - @ref c-vt-paste/src/main.c - Paste safety check example
54 * - @ref c-vt-sgr/src/main.c - SGR parser example
55 * - @ref c-vt-formatter/src/main.c - Terminal formatter example
56 * - @ref c-vt-grid-traverse/src/main.c - Grid traversal example using grid refs
57 * - @ref c-vt-grid-ref-tracked/src/main.c - Tracked grid ref example
58 *
59 */
60
61/** @example c-vt-build-info/src/main.c
62 * This example demonstrates how to query compile-time build configuration
63 * such as SIMD support, Kitty graphics, and tmux control mode availability.
64 */
65
66/** @example c-vt/src/main.c
67 * This example demonstrates how to use the OSC parser to parse an OSC sequence,
68 * extract command information, and retrieve command-specific data like window titles.
69 */
70
71/** @example c-vt-encode-key/src/main.c
72 * This example demonstrates how to use the key encoder to convert key events
73 * into terminal escape sequences using the Kitty keyboard protocol.
74 */
75
76/** @example c-vt-encode-mouse/src/main.c
77 * This example demonstrates how to use the mouse encoder to convert mouse events
78 * into terminal escape sequences using the SGR mouse format.
79 */
80
81/** @example c-vt-paste/src/main.c
82 * This example demonstrates how to use the paste utilities to check if
83 * paste data is safe before sending it to the terminal.
84 */
85
86/** @example c-vt-sgr/src/main.c
87 * This example demonstrates how to use the SGR parser to parse terminal
88 * styling sequences and extract text attributes like colors and underline styles.
89 */
90
91/** @example c-vt-formatter/src/main.c
92 * This example demonstrates how to use the terminal and formatter APIs to
93 * create a terminal, write VT-encoded content into it, and format the screen
94 * contents as plain text.
95 */
96
97/** @example c-vt-grid-traverse/src/main.c
98 * This example demonstrates how to traverse the entire terminal grid using
99 * grid refs to inspect cell codepoints, row wrap state, and cell styles.
100 */
101
102/** @example c-vt-grid-ref-tracked/src/main.c
103 * This example demonstrates how to track a grid ref as the terminal scrolls,
104 * detect when it loses its value, and move it to a new point.
105 */
106
107/** @example c-vt-selection-gesture/src/main.c
108 * This example demonstrates how to use synthetic selection gesture events to
109 * derive drag and deep-press selection snapshots.
110 */
111
112/** @example c-vt-kitty-graphics/src/main.c
113 * This example demonstrates how to use the system interface to install a
114 * PNG decoder callback and send a Kitty Graphics Protocol image.
115 */
116
117#ifndef GHOSTTY_VT_H
118#define GHOSTTY_VT_H
119
120#ifdef __cplusplus
121extern "C" {
122#endif
123
124#include <ghostty/vt/types.h>
125#include <ghostty/vt/allocator.h>
126#include <ghostty/vt/build_info.h>
127#include <ghostty/vt/color.h>
128#include <ghostty/vt/device.h>
129#include <ghostty/vt/focus.h>
130#include <ghostty/vt/formatter.h>
131#include <ghostty/vt/render.h>
132#include <ghostty/vt/terminal.h>
133#include <ghostty/vt/grid_ref.h>
134#include <ghostty/vt/grid_ref_tracked.h>
135#include <ghostty/vt/osc.h>
136#include <ghostty/vt/sgr.h>
137#include <ghostty/vt/style.h>
138#include <ghostty/vt/sys.h>
139#include <ghostty/vt/key.h>
140#include <ghostty/vt/kitty_graphics.h>
141#include <ghostty/vt/modes.h>
142#include <ghostty/vt/mouse.h>
143#include <ghostty/vt/paste.h>
144#include <ghostty/vt/point.h>
145#include <ghostty/vt/screen.h>
146#include <ghostty/vt/selection.h>
147#include <ghostty/vt/size_report.h>
148#include <ghostty/vt/wasm.h>
149
150#ifdef __cplusplus
151}
152#endif
153
154#endif /* GHOSTTY_VT_H */
native/libghostty-vt/include/ghostty/vt/allocator.h created+255
......@@ -0,0 +1,255 @@
1/**
2 * @file allocator.h
3 *
4 * Memory management interface for libghostty-vt.
5 */
6
7#ifndef GHOSTTY_VT_ALLOCATOR_H
8#define GHOSTTY_VT_ALLOCATOR_H
9
10#include <stdbool.h>
11#include <stddef.h>
12#include <stdint.h>
13#include <ghostty/vt/types.h>
14
15/** @defgroup allocator Memory Management
16 *
17 * libghostty-vt does require memory allocation for various operations,
18 * but is resilient to allocation failures and will gracefully handle
19 * out-of-memory situations by returning error codes.
20 *
21 * The exact memory management semantics are documented in the relevant
22 * functions and data structures.
23 *
24 * libghostty-vt uses explicit memory allocation via an allocator
25 * interface provided by GhosttyAllocator. The interface is based on the
26 * [Zig](https://ziglang.org) allocator interface, since this has been
27 * shown to be a flexible and powerful interface in practice and enables
28 * a wide variety of allocation strategies.
29 *
30 * **For the common case, you can pass NULL as the allocator for any
31 * function that accepts one,** and libghostty will use a default allocator.
32 * The default allocator will be libc malloc/free if libc is linked.
33 * Otherwise, a custom allocator is used (currently Zig's SMP allocator)
34 * that doesn't require any external dependencies.
35 *
36 * ## Basic Usage
37 *
38 * For simple use cases, you can ignore this interface entirely by passing NULL
39 * as the allocator parameter to functions that accept one. This will use the
40 * default allocator (typically libc malloc/free, if libc is linked, but
41 * we provide our own default allocator if libc isn't linked).
42 *
43 * To use a custom allocator:
44 * 1. Implement the GhosttyAllocatorVtable function pointers
45 * 2. Create a GhosttyAllocator struct with your vtable and context
46 * 3. Pass the allocator to functions that accept one
47 *
48 * ## Alloc/Free Helpers
49 *
50 * ghostty_alloc() and ghostty_free() provide a simple malloc/free-style
51 * interface for allocating and freeing byte buffers through the library's
52 * allocator. These are useful when:
53 *
54 * - You need to allocate a buffer to pass into a libghostty-vt function
55 * (e.g. preparing input data for ghostty_terminal_vt_write()).
56 * - You need to free a buffer returned by a libghostty-vt function
57 * (e.g. the output of ghostty_formatter_format_alloc()).
58 * - You are on a platform where the library's internal allocator differs
59 * from the consumer's C runtime (e.g. Windows, where Zig's libc and
60 * MSVC's CRT maintain separate heaps), so calling the standard C
61 * free() on library-allocated memory would be undefined behavior.
62 *
63 * Always use the same allocator (or NULL) for both the allocation and
64 * the corresponding free.
65 *
66 * @{
67 */
68
69/**
70 * Function table for custom memory allocator operations.
71 *
72 * This vtable defines the interface for a custom memory allocator. All
73 * function pointers must be valid and non-NULL.
74 *
75 * @ingroup allocator
76 *
77 * If you're not going to use a custom allocator, you can ignore all of
78 * this. All functions that take an allocator pointer allow NULL to use a
79 * default allocator.
80 *
81 * The interface is based on the Zig allocator interface. I'll say up front
82 * that it is easy to look at this interface and think "wow, this is really
83 * overcomplicated". The reason for this complexity is well thought out by
84 * the Zig folks, and it enables a diverse set of allocation strategies
85 * as shown by the Zig ecosystem. As a consolation, please note that many
86 * of the arguments are only needed for advanced use cases and can be
87 * safely ignored in simple implementations. For example, if you look at
88 * the Zig implementation of the libc allocator in `lib/std/heap.zig`
89 * (search for CAllocator), you'll see it is very simple.
90 *
91 * We chose to align with the Zig allocator interface because:
92 *
93 * 1. It is a proven interface that serves a wide variety of use cases
94 * in the real world via the Zig ecosystem. It's shown to work.
95 *
96 * 2. Our core implementation itself is Zig, and this lets us very
97 * cheaply and easily convert between C and Zig allocators.
98 *
99 * NOTE(mitchellh): In the future, we can have default implementations of
100 * resize/remap and allow those to be null.
101 */
102typedef struct {
103 /**
104 * Return a pointer to `len` bytes with specified `alignment`, or return
105 * `NULL` indicating the allocation failed.
106 *
107 * @param ctx The allocator context
108 * @param len Number of bytes to allocate
109 * @param alignment Required alignment for the allocation. Guaranteed to
110 * be a power of two between 1 and 16 inclusive.
111 * @param ret_addr First return address of the allocation call stack (0 if not provided)
112 * @return Pointer to allocated memory, or NULL if allocation failed
113 */
114 void* (*alloc)(void *ctx, size_t len, uint8_t alignment, uintptr_t ret_addr);
115
116 /**
117 * Attempt to expand or shrink memory in place.
118 *
119 * `memory_len` must equal the length requested from the most recent
120 * successful call to `alloc`, `resize`, or `remap`. `alignment` must
121 * equal the same value that was passed as the `alignment` parameter to
122 * the original `alloc` call.
123 *
124 * `new_len` must be greater than zero.
125 *
126 * @param ctx The allocator context
127 * @param memory Pointer to the memory block to resize
128 * @param memory_len Current size of the memory block
129 * @param alignment Alignment (must match original allocation)
130 * @param new_len New requested size
131 * @param ret_addr First return address of the allocation call stack (0 if not provided)
132 * @return true if resize was successful in-place, false if relocation would be required
133 */
134 bool (*resize)(void *ctx, void *memory, size_t memory_len, uint8_t alignment, size_t new_len, uintptr_t ret_addr);
135
136 /**
137 * Attempt to expand or shrink memory, allowing relocation.
138 *
139 * `memory_len` must equal the length requested from the most recent
140 * successful call to `alloc`, `resize`, or `remap`. `alignment` must
141 * equal the same value that was passed as the `alignment` parameter to
142 * the original `alloc` call.
143 *
144 * A non-`NULL` return value indicates the resize was successful. The
145 * allocation may have same address, or may have been relocated. In either
146 * case, the allocation now has size of `new_len`. A `NULL` return value
147 * indicates that the resize would be equivalent to allocating new memory,
148 * copying the bytes from the old memory, and then freeing the old memory.
149 * In such case, it is more efficient for the caller to perform the copy.
150 *
151 * `new_len` must be greater than zero.
152 *
153 * @param ctx The allocator context
154 * @param memory Pointer to the memory block to remap
155 * @param memory_len Current size of the memory block
156 * @param alignment Alignment (must match original allocation)
157 * @param new_len New requested size
158 * @param ret_addr First return address of the allocation call stack (0 if not provided)
159 * @return Pointer to resized memory (may be relocated), or NULL if manual copy is needed
160 */
161 void* (*remap)(void *ctx, void *memory, size_t memory_len, uint8_t alignment, size_t new_len, uintptr_t ret_addr);
162
163 /**
164 * Free and invalidate a region of memory.
165 *
166 * `memory_len` must equal the length requested from the most recent
167 * successful call to `alloc`, `resize`, or `remap`. `alignment` must
168 * equal the same value that was passed as the `alignment` parameter to
169 * the original `alloc` call.
170 *
171 * @param ctx The allocator context
172 * @param memory Pointer to the memory block to free
173 * @param memory_len Size of the memory block
174 * @param alignment Alignment (must match original allocation)
175 * @param ret_addr First return address of the allocation call stack (0 if not provided)
176 */
177 void (*free)(void *ctx, void *memory, size_t memory_len, uint8_t alignment, uintptr_t ret_addr);
178} GhosttyAllocatorVtable;
179
180/**
181 * Custom memory allocator.
182 *
183 * For functions that take an allocator pointer, a NULL pointer indicates
184 * that the default allocator should be used. The default allocator will
185 * be libc malloc/free if we're linking to libc. If libc isn't linked,
186 * a custom allocator is used (currently Zig's SMP allocator).
187 *
188 * @ingroup allocator
189 *
190 * Usage example:
191 * @code
192 * GhosttyAllocator allocator = {
193 * .vtable = &my_allocator_vtable,
194 * .ctx = my_allocator_state
195 * };
196 * @endcode
197 */
198typedef struct GhosttyAllocator {
199 /**
200 * Opaque context pointer passed to all vtable functions.
201 * This allows the allocator implementation to maintain state
202 * or reference external resources needed for memory management.
203 */
204 void *ctx;
205
206 /**
207 * Pointer to the allocator's vtable containing function pointers
208 * for memory operations (alloc, resize, remap, free).
209 */
210 const GhosttyAllocatorVtable *vtable;
211} GhosttyAllocator;
212
213/**
214 * Allocate a buffer of `len` bytes.
215 *
216 * Uses the provided allocator, or the default allocator if NULL is passed.
217 * The returned buffer must be freed with ghostty_free() using the same
218 * allocator.
219 *
220 * @param allocator Pointer to the allocator to use, or NULL for the default
221 * @param len Number of bytes to allocate
222 * @return Pointer to the allocated buffer, or NULL if allocation failed
223 *
224 * @ingroup allocator
225 */
226GHOSTTY_API uint8_t* ghostty_alloc(const GhosttyAllocator* allocator, size_t len);
227
228/**
229 * Free memory that was allocated by a libghostty-vt function.
230 *
231 * Use this to free buffers returned by functions such as
232 * ghostty_formatter_format_alloc(). Pass the same allocator that was
233 * used for the allocation, or NULL if the default allocator was used.
234 *
235 * On platforms where the library's internal allocator differs from the
236 * consumer's C runtime (e.g. Windows, where Zig's libc and MSVC's CRT
237 * maintain separate heaps), calling the standard C free() on memory
238 * allocated by the library causes undefined behavior. This function
239 * guarantees the correct allocator is used regardless of platform.
240 *
241 * It is safe to pass a NULL pointer; the call is a no-op in that case.
242 *
243 * @param allocator Pointer to the allocator that was used to allocate the
244 * memory, or NULL if the default allocator was used
245 * @param ptr Pointer to the memory to free (may be NULL)
246 * @param len Length of the allocation in bytes (must match the original
247 * allocation size)
248 *
249 * @ingroup allocator
250 */
251GHOSTTY_API void ghostty_free(const GhosttyAllocator* allocator, uint8_t* ptr, size_t len);
252
253/** @} */
254
255#endif /* GHOSTTY_VT_ALLOCATOR_H */
native/libghostty-vt/include/ghostty/vt/build_info.h created+150
......@@ -0,0 +1,150 @@
1/**
2 * @file build_info.h
3 *
4 * Build info - query compile-time build configuration of libghostty-vt.
5 */
6
7#ifndef GHOSTTY_VT_BUILD_INFO_H
8#define GHOSTTY_VT_BUILD_INFO_H
9
10/** @defgroup build_info Build Info
11 *
12 * Query compile-time build configuration of libghostty-vt.
13 *
14 * These values reflect the options the library was built with and are
15 * constant for the lifetime of the process.
16 *
17 * ## Basic Usage
18 *
19 * Use ghostty_build_info() to query individual build options:
20 *
21 * @snippet c-vt-build-info/src/main.c build-info-query
22 *
23 * @{
24 */
25
26#include <stddef.h>
27#include <stdbool.h>
28
29#include <ghostty/vt/types.h>
30
31#ifdef __cplusplus
32extern "C" {
33#endif
34
35/**
36 * Build optimization mode.
37 */
38typedef enum GHOSTTY_ENUM_TYPED {
39 GHOSTTY_OPTIMIZE_DEBUG = 0,
40 GHOSTTY_OPTIMIZE_RELEASE_SAFE = 1,
41 GHOSTTY_OPTIMIZE_RELEASE_SMALL = 2,
42 GHOSTTY_OPTIMIZE_RELEASE_FAST = 3,
43 GHOSTTY_OPTIMIZE_MODE_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
44} GhosttyOptimizeMode;
45
46/**
47 * Build info data types that can be queried.
48 *
49 * Each variant documents the expected output pointer type.
50 */
51typedef enum GHOSTTY_ENUM_TYPED {
52 /** Invalid data type. Never results in any data extraction. */
53 GHOSTTY_BUILD_INFO_INVALID = 0,
54
55 /**
56 * Whether SIMD-accelerated code paths are enabled.
57 *
58 * Output type: bool *
59 */
60 GHOSTTY_BUILD_INFO_SIMD = 1,
61
62 /**
63 * Whether Kitty graphics protocol support is available.
64 *
65 * Output type: bool *
66 */
67 GHOSTTY_BUILD_INFO_KITTY_GRAPHICS = 2,
68
69 /**
70 * Whether tmux control mode support is available.
71 *
72 * Output type: bool *
73 */
74 GHOSTTY_BUILD_INFO_TMUX_CONTROL_MODE = 3,
75
76 /**
77 * The optimization mode the library was built with.
78 *
79 * Output type: GhosttyOptimizeMode *
80 */
81 GHOSTTY_BUILD_INFO_OPTIMIZE = 4,
82
83 /**
84 * The full version string (e.g. "1.2.3" or "1.2.3-dev+abcdef").
85 *
86 * Output type: GhosttyString *
87 */
88 GHOSTTY_BUILD_INFO_VERSION_STRING = 5,
89
90 /**
91 * The major version number.
92 *
93 * Output type: size_t *
94 */
95 GHOSTTY_BUILD_INFO_VERSION_MAJOR = 6,
96
97 /**
98 * The minor version number.
99 *
100 * Output type: size_t *
101 */
102 GHOSTTY_BUILD_INFO_VERSION_MINOR = 7,
103
104 /**
105 * The patch version number.
106 *
107 * Output type: size_t *
108 */
109 GHOSTTY_BUILD_INFO_VERSION_PATCH = 8,
110
111 /**
112 * The pre metadata string (e.g. "alpha", "beta", "dev"). Has zero length if
113 * no pre metadata is present.
114 *
115 * Output type: GhosttyString *
116 */
117 GHOSTTY_BUILD_INFO_VERSION_PRE = 9,
118
119 /**
120 * The build metadata string (e.g. commit hash). Has zero length if
121 * no build metadata is present.
122 *
123 * Output type: GhosttyString *
124 */
125 GHOSTTY_BUILD_INFO_VERSION_BUILD = 10,
126 GHOSTTY_BUILD_INFO_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
127} GhosttyBuildInfo;
128
129/**
130 * Query a compile-time build configuration value.
131 *
132 * The caller must pass a pointer to the correct output type for the
133 * requested data (see GhosttyBuildInfo variants for types).
134 *
135 * @param data The build info field to query
136 * @param out Pointer to store the result (type depends on data parameter)
137 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the
138 * data type is invalid
139 *
140 * @ingroup build_info
141 */
142GHOSTTY_API GhosttyResult ghostty_build_info(GhosttyBuildInfo data, void *out);
143
144#ifdef __cplusplus
145}
146#endif
147
148/** @} */
149
150#endif /* GHOSTTY_VT_BUILD_INFO_H */
native/libghostty-vt/include/ghostty/vt/color.h created+97
......@@ -0,0 +1,97 @@
1/**
2 * @file color.h
3 *
4 * Color types and utilities.
5 */
6
7#ifndef GHOSTTY_VT_COLOR_H
8#define GHOSTTY_VT_COLOR_H
9
10#include <stdint.h>
11#include <ghostty/vt/types.h>
12
13#ifdef __cplusplus
14extern "C" {
15#endif
16
17/**
18 * RGB color value.
19 *
20 * @ingroup sgr
21 */
22typedef struct {
23 uint8_t r; /**< Red component (0-255) */
24 uint8_t g; /**< Green component (0-255) */
25 uint8_t b; /**< Blue component (0-255) */
26} GhosttyColorRgb;
27
28/**
29 * Palette color index (0-255).
30 *
31 * @ingroup sgr
32 */
33typedef uint8_t GhosttyColorPaletteIndex;
34
35/** @addtogroup sgr
36 * @{
37 */
38
39/** Black color (0) @ingroup sgr */
40#define GHOSTTY_COLOR_NAMED_BLACK 0
41/** Red color (1) @ingroup sgr */
42#define GHOSTTY_COLOR_NAMED_RED 1
43/** Green color (2) @ingroup sgr */
44#define GHOSTTY_COLOR_NAMED_GREEN 2
45/** Yellow color (3) @ingroup sgr */
46#define GHOSTTY_COLOR_NAMED_YELLOW 3
47/** Blue color (4) @ingroup sgr */
48#define GHOSTTY_COLOR_NAMED_BLUE 4
49/** Magenta color (5) @ingroup sgr */
50#define GHOSTTY_COLOR_NAMED_MAGENTA 5
51/** Cyan color (6) @ingroup sgr */
52#define GHOSTTY_COLOR_NAMED_CYAN 6
53/** White color (7) @ingroup sgr */
54#define GHOSTTY_COLOR_NAMED_WHITE 7
55/** Bright black color (8) @ingroup sgr */
56#define GHOSTTY_COLOR_NAMED_BRIGHT_BLACK 8
57/** Bright red color (9) @ingroup sgr */
58#define GHOSTTY_COLOR_NAMED_BRIGHT_RED 9
59/** Bright green color (10) @ingroup sgr */
60#define GHOSTTY_COLOR_NAMED_BRIGHT_GREEN 10
61/** Bright yellow color (11) @ingroup sgr */
62#define GHOSTTY_COLOR_NAMED_BRIGHT_YELLOW 11
63/** Bright blue color (12) @ingroup sgr */
64#define GHOSTTY_COLOR_NAMED_BRIGHT_BLUE 12
65/** Bright magenta color (13) @ingroup sgr */
66#define GHOSTTY_COLOR_NAMED_BRIGHT_MAGENTA 13
67/** Bright cyan color (14) @ingroup sgr */
68#define GHOSTTY_COLOR_NAMED_BRIGHT_CYAN 14
69/** Bright white color (15) @ingroup sgr */
70#define GHOSTTY_COLOR_NAMED_BRIGHT_WHITE 15
71
72/** @} */
73
74/**
75 * Get the RGB color components.
76 *
77 * This function extracts the individual red, green, and blue components
78 * from a GhosttyColorRgb value. Primarily useful in WebAssembly environments
79 * where accessing struct fields directly is difficult.
80 *
81 * @param color The RGB color value
82 * @param r Pointer to store the red component (0-255)
83 * @param g Pointer to store the green component (0-255)
84 * @param b Pointer to store the blue component (0-255)
85 *
86 * @ingroup sgr
87 */
88GHOSTTY_API void ghostty_color_rgb_get(GhosttyColorRgb color,
89 uint8_t* r,
90 uint8_t* g,
91 uint8_t* b);
92
93#ifdef __cplusplus
94}
95#endif
96
97#endif /* GHOSTTY_VT_COLOR_H */
native/libghostty-vt/include/ghostty/vt/device.h created+151
......@@ -0,0 +1,151 @@
1/**
2 * @file device.h
3 *
4 * Device types used by the terminal for device status and device attribute
5 * queries.
6 */
7
8#ifndef GHOSTTY_VT_DEVICE_H
9#define GHOSTTY_VT_DEVICE_H
10
11#include <stddef.h>
12#include <stdint.h>
13
14/* DA1 conformance levels (Pp parameter). */
15#define GHOSTTY_DA_CONFORMANCE_VT100 1
16#define GHOSTTY_DA_CONFORMANCE_VT101 1
17#define GHOSTTY_DA_CONFORMANCE_VT102 6
18#define GHOSTTY_DA_CONFORMANCE_VT125 12
19#define GHOSTTY_DA_CONFORMANCE_VT131 7
20#define GHOSTTY_DA_CONFORMANCE_VT132 4
21#define GHOSTTY_DA_CONFORMANCE_VT220 62
22#define GHOSTTY_DA_CONFORMANCE_VT240 62
23#define GHOSTTY_DA_CONFORMANCE_VT320 63
24#define GHOSTTY_DA_CONFORMANCE_VT340 63
25#define GHOSTTY_DA_CONFORMANCE_VT420 64
26#define GHOSTTY_DA_CONFORMANCE_VT510 65
27#define GHOSTTY_DA_CONFORMANCE_VT520 65
28#define GHOSTTY_DA_CONFORMANCE_VT525 65
29#define GHOSTTY_DA_CONFORMANCE_LEVEL_2 62
30#define GHOSTTY_DA_CONFORMANCE_LEVEL_3 63
31#define GHOSTTY_DA_CONFORMANCE_LEVEL_4 64
32#define GHOSTTY_DA_CONFORMANCE_LEVEL_5 65
33
34/* DA1 feature codes (Ps parameters). */
35#define GHOSTTY_DA_FEATURE_COLUMNS_132 1
36#define GHOSTTY_DA_FEATURE_PRINTER 2
37#define GHOSTTY_DA_FEATURE_REGIS 3
38#define GHOSTTY_DA_FEATURE_SIXEL 4
39#define GHOSTTY_DA_FEATURE_SELECTIVE_ERASE 6
40#define GHOSTTY_DA_FEATURE_USER_DEFINED_KEYS 8
41#define GHOSTTY_DA_FEATURE_NATIONAL_REPLACEMENT 9
42#define GHOSTTY_DA_FEATURE_TECHNICAL_CHARACTERS 15
43#define GHOSTTY_DA_FEATURE_LOCATOR 16
44#define GHOSTTY_DA_FEATURE_TERMINAL_STATE 17
45#define GHOSTTY_DA_FEATURE_WINDOWING 18
46#define GHOSTTY_DA_FEATURE_HORIZONTAL_SCROLLING 21
47#define GHOSTTY_DA_FEATURE_ANSI_COLOR 22
48#define GHOSTTY_DA_FEATURE_RECTANGULAR_EDITING 28
49#define GHOSTTY_DA_FEATURE_ANSI_TEXT_LOCATOR 29
50#define GHOSTTY_DA_FEATURE_CLIPBOARD 52
51
52/* DA2 device type identifiers (Pp parameter). */
53#define GHOSTTY_DA_DEVICE_TYPE_VT100 0
54#define GHOSTTY_DA_DEVICE_TYPE_VT220 1
55#define GHOSTTY_DA_DEVICE_TYPE_VT240 2
56#define GHOSTTY_DA_DEVICE_TYPE_VT330 18
57#define GHOSTTY_DA_DEVICE_TYPE_VT340 19
58#define GHOSTTY_DA_DEVICE_TYPE_VT320 24
59#define GHOSTTY_DA_DEVICE_TYPE_VT382 32
60#define GHOSTTY_DA_DEVICE_TYPE_VT420 41
61#define GHOSTTY_DA_DEVICE_TYPE_VT510 61
62#define GHOSTTY_DA_DEVICE_TYPE_VT520 64
63#define GHOSTTY_DA_DEVICE_TYPE_VT525 65
64
65#ifdef __cplusplus
66extern "C" {
67#endif
68
69/**
70 * Color scheme reported in response to a CSI ? 996 n query.
71 *
72 * @ingroup terminal
73 */
74typedef enum GHOSTTY_ENUM_TYPED {
75 GHOSTTY_COLOR_SCHEME_LIGHT = 0,
76 GHOSTTY_COLOR_SCHEME_DARK = 1,
77 GHOSTTY_COLOR_SCHEME_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
78} GhosttyColorScheme;
79
80/**
81 * Primary device attributes (DA1) response data.
82 *
83 * Returned as part of GhosttyDeviceAttributes in response to a CSI c query.
84 * The conformance_level is the Pp parameter and features contains the Ps
85 * feature codes.
86 *
87 * @ingroup terminal
88 */
89typedef struct {
90 /** Conformance level (Pp parameter). E.g. 62 for VT220. */
91 uint16_t conformance_level;
92
93 /** DA1 feature codes. Only the first num_features entries are valid. */
94 uint16_t features[64];
95
96 /** Number of valid entries in the features array. */
97 size_t num_features;
98} GhosttyDeviceAttributesPrimary;
99
100/**
101 * Secondary device attributes (DA2) response data.
102 *
103 * Returned as part of GhosttyDeviceAttributes in response to a CSI > c query.
104 * Response format: CSI > Pp ; Pv ; Pc c
105 *
106 * @ingroup terminal
107 */
108typedef struct {
109 /** Terminal type identifier (Pp). E.g. 1 for VT220. */
110 uint16_t device_type;
111
112 /** Firmware/patch version number (Pv). */
113 uint16_t firmware_version;
114
115 /** ROM cartridge registration number (Pc). Always 0 for emulators. */
116 uint16_t rom_cartridge;
117} GhosttyDeviceAttributesSecondary;
118
119/**
120 * Tertiary device attributes (DA3) response data.
121 *
122 * Returned as part of GhosttyDeviceAttributes in response to a CSI = c query.
123 * Response format: DCS ! | D...D ST (DECRPTUI).
124 *
125 * @ingroup terminal
126 */
127typedef struct {
128 /** Unit ID encoded as 8 uppercase hex digits in the response. */
129 uint32_t unit_id;
130} GhosttyDeviceAttributesTertiary;
131
132/**
133 * Device attributes response data for all three DA levels.
134 *
135 * Filled by the device_attributes callback in response to CSI c,
136 * CSI > c, or CSI = c queries. The terminal uses whichever sub-struct
137 * matches the request type.
138 *
139 * @ingroup terminal
140 */
141typedef struct {
142 GhosttyDeviceAttributesPrimary primary;
143 GhosttyDeviceAttributesSecondary secondary;
144 GhosttyDeviceAttributesTertiary tertiary;
145} GhosttyDeviceAttributes;
146
147#ifdef __cplusplus
148}
149#endif
150
151#endif /* GHOSTTY_VT_DEVICE_H */
native/libghostty-vt/include/ghostty/vt/focus.h created+76
......@@ -0,0 +1,76 @@
1/**
2 * @file focus.h
3 *
4 * Focus encoding - encode focus in/out events into terminal escape sequences.
5 */
6
7#ifndef GHOSTTY_VT_FOCUS_H
8#define GHOSTTY_VT_FOCUS_H
9
10/** @defgroup focus Focus Encoding
11 *
12 * Utilities for encoding focus gained/lost events into terminal escape
13 * sequences (CSI I / CSI O) for focus reporting mode (mode 1004).
14 *
15 * ## Basic Usage
16 *
17 * Use ghostty_focus_encode() to encode a focus event into a caller-provided
18 * buffer. If the buffer is too small, the function returns
19 * GHOSTTY_OUT_OF_SPACE and sets the required size in the output parameter.
20 *
21 * ## Example
22 *
23 * @snippet c-vt-encode-focus/src/main.c focus-encode
24 *
25 * @{
26 */
27
28#include <stddef.h>
29#include <ghostty/vt/types.h>
30
31#ifdef __cplusplus
32extern "C" {
33#endif
34
35/**
36 * Focus event types for focus reporting mode (mode 1004).
37 */
38typedef enum GHOSTTY_ENUM_TYPED {
39 /** Terminal window gained focus */
40 GHOSTTY_FOCUS_GAINED = 0,
41 /** Terminal window lost focus */
42 GHOSTTY_FOCUS_LOST = 1,
43 GHOSTTY_FOCUS_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
44} GhosttyFocusEvent;
45
46/**
47 * Encode a focus event into a terminal escape sequence.
48 *
49 * Encodes a focus gained (CSI I) or focus lost (CSI O) report into the
50 * provided buffer.
51 *
52 * If the buffer is too small, the function returns GHOSTTY_OUT_OF_SPACE
53 * and writes the required buffer size to @p out_written. The caller can
54 * then retry with a sufficiently sized buffer.
55 *
56 * @param event The focus event to encode
57 * @param buf Output buffer to write the encoded sequence into (may be NULL)
58 * @param buf_len Size of the output buffer in bytes
59 * @param[out] out_written On success, the number of bytes written. On
60 * GHOSTTY_OUT_OF_SPACE, the required buffer size.
61 * @return GHOSTTY_SUCCESS on success, GHOSTTY_OUT_OF_SPACE if the buffer
62 * is too small
63 */
64GHOSTTY_API GhosttyResult ghostty_focus_encode(
65 GhosttyFocusEvent event,
66 char* buf,
67 size_t buf_len,
68 size_t* out_written);
69
70#ifdef __cplusplus
71}
72#endif
73
74/** @} */
75
76#endif /* GHOSTTY_VT_FOCUS_H */
native/libghostty-vt/include/ghostty/vt/formatter.h created+207
......@@ -0,0 +1,207 @@
1/**
2 * @file formatter.h
3 *
4 * Format terminal content as plain text, VT sequences, or HTML.
5 */
6
7#ifndef GHOSTTY_VT_FORMATTER_H
8#define GHOSTTY_VT_FORMATTER_H
9
10#include <stdbool.h>
11#include <stddef.h>
12#include <stdint.h>
13#include <ghostty/vt/allocator.h>
14#include <ghostty/vt/selection.h>
15#include <ghostty/vt/types.h>
16#include <ghostty/vt/terminal.h>
17
18#ifdef __cplusplus
19extern "C" {
20#endif
21
22/** @defgroup formatter Formatter
23 *
24 * Format terminal content as plain text, VT sequences, or HTML.
25 *
26 * A formatter captures a reference to a terminal and formatting options.
27 * It can be used repeatedly to produce output that reflects the current
28 * terminal state at the time of each format call.
29 *
30 * The terminal must outlive the formatter.
31 *
32 * @{
33 */
34
35/**
36 * Extra screen state to include in styled output.
37 *
38 * @ingroup formatter
39 */
40typedef struct {
41 /** Size of this struct in bytes. Must be set to sizeof(GhosttyFormatterScreenExtra). */
42 size_t size;
43
44 /** Emit cursor position using CUP (CSI H). */
45 bool cursor;
46
47 /** Emit current SGR style state based on the cursor's active style_id. */
48 bool style;
49
50 /** Emit current hyperlink state using OSC 8 sequences. */
51 bool hyperlink;
52
53 /** Emit character protection mode using DECSCA. */
54 bool protection;
55
56 /** Emit Kitty keyboard protocol state using CSI > u and CSI = sequences. */
57 bool kitty_keyboard;
58
59 /** Emit character set designations and invocations. */
60 bool charsets;
61} GhosttyFormatterScreenExtra;
62
63/**
64 * Extra terminal state to include in styled output.
65 *
66 * @ingroup formatter
67 */
68typedef struct {
69 /** Size of this struct in bytes. Must be set to sizeof(GhosttyFormatterTerminalExtra). */
70 size_t size;
71
72 /** Emit the palette using OSC 4 sequences. */
73 bool palette;
74
75 /** Emit terminal modes that differ from their defaults using CSI h/l. */
76 bool modes;
77
78 /** Emit scrolling region state using DECSTBM and DECSLRM sequences. */
79 bool scrolling_region;
80
81 /** Emit tabstop positions by clearing all tabs and setting each one. */
82 bool tabstops;
83
84 /** Emit the present working directory using OSC 7. */
85 bool pwd;
86
87 /** Emit keyboard modes such as ModifyOtherKeys. */
88 bool keyboard;
89
90 /** Screen-level extras. */
91 GhosttyFormatterScreenExtra screen;
92} GhosttyFormatterTerminalExtra;
93
94/**
95 * Options for creating a terminal formatter.
96 *
97 * @ingroup formatter
98 */
99typedef struct {
100 /** Size of this struct in bytes. Must be set to sizeof(GhosttyFormatterTerminalOptions). */
101 size_t size;
102
103 /** Output format to emit. */
104 GhosttyFormatterFormat emit;
105
106 /** Whether to unwrap soft-wrapped lines. */
107 bool unwrap;
108
109 /** Whether to trim trailing whitespace on non-blank lines. */
110 bool trim;
111
112 /** Extra terminal state to include in styled output. */
113 GhosttyFormatterTerminalExtra extra;
114
115 /** Optional selection to restrict output to a range.
116 * If NULL, the entire screen is formatted. */
117 const GhosttySelection *selection;
118} GhosttyFormatterTerminalOptions;
119
120/**
121 * Create a formatter for a terminal's active screen.
122 *
123 * The terminal must outlive the formatter. The formatter stores a borrowed
124 * reference to the terminal and reads its current state on each format call.
125 *
126 * @param allocator Pointer to allocator, or NULL to use the default allocator
127 * @param formatter Pointer to store the created formatter handle
128 * @param terminal The terminal to format (must not be NULL)
129 * @param options Formatting options
130 * @return GHOSTTY_SUCCESS on success, or an error code on failure
131 *
132 * @ingroup formatter
133 */
134GHOSTTY_API GhosttyResult ghostty_formatter_terminal_new(
135 const GhosttyAllocator* allocator,
136 GhosttyFormatter* formatter,
137 GhosttyTerminal terminal,
138 GhosttyFormatterTerminalOptions options);
139
140/**
141 * Run the formatter and produce output into the caller-provided buffer.
142 *
143 * Each call formats the current terminal state. Pass NULL for buf to
144 * query the required buffer size without writing any output; in that case
145 * out_written receives the required size and the return value is
146 * GHOSTTY_OUT_OF_SPACE.
147 *
148 * If the buffer is too small, returns GHOSTTY_OUT_OF_SPACE and sets
149 * out_written to the required size. The caller can then retry with a
150 * larger buffer.
151 *
152 * @param formatter The formatter handle (must not be NULL)
153 * @param buf Pointer to the output buffer, or NULL to query size
154 * @param buf_len Length of the output buffer in bytes
155 * @param out_written Pointer to receive the number of bytes written,
156 * or the required size on failure
157 * @return GHOSTTY_SUCCESS on success, or an error code on failure
158 *
159 * @ingroup formatter
160 */
161GHOSTTY_API GhosttyResult ghostty_formatter_format_buf(GhosttyFormatter formatter,
162 uint8_t* buf,
163 size_t buf_len,
164 size_t* out_written);
165
166/**
167 * Run the formatter and return an allocated buffer with the output.
168 *
169 * Each call formats the current terminal state. The buffer is allocated
170 * using the provided allocator (or the default allocator if NULL).
171 * The caller is responsible for freeing the returned buffer with
172 * ghostty_free(), passing the same allocator (or NULL for the default)
173 * that was used for the allocation.
174 *
175 * @param formatter The formatter handle (must not be NULL)
176 * @param allocator Pointer to allocator, or NULL to use the default allocator
177 * @param out_ptr Pointer to receive the allocated buffer
178 * @param out_len Pointer to receive the length of the output in bytes
179 * @return GHOSTTY_SUCCESS on success, GHOSTTY_OUT_OF_MEMORY on allocation
180 * failure
181 *
182 * @ingroup formatter
183 */
184GHOSTTY_API GhosttyResult ghostty_formatter_format_alloc(GhosttyFormatter formatter,
185 const GhosttyAllocator* allocator,
186 uint8_t** out_ptr,
187 size_t* out_len);
188
189/**
190 * Free a formatter instance.
191 *
192 * Releases all resources associated with the formatter. After this call,
193 * the formatter handle becomes invalid.
194 *
195 * @param formatter The formatter handle to free (may be NULL)
196 *
197 * @ingroup formatter
198 */
199GHOSTTY_API void ghostty_formatter_free(GhosttyFormatter formatter);
200
201/** @} */
202
203#ifdef __cplusplus
204}
205#endif
206
207#endif /* GHOSTTY_VT_FORMATTER_H */
native/libghostty-vt/include/ghostty/vt/grid_ref.h created+212
......@@ -0,0 +1,212 @@
1/**
2 * @file grid_ref.h
3 *
4 * Terminal grid reference type for referencing a resolved position in the
5 * terminal grid.
6 */
7
8#ifndef GHOSTTY_VT_GRID_REF_H
9#define GHOSTTY_VT_GRID_REF_H
10
11#include <stddef.h>
12#include <stdint.h>
13#include <ghostty/vt/types.h>
14#include <ghostty/vt/screen.h>
15#include <ghostty/vt/style.h>
16
17#ifdef __cplusplus
18extern "C" {
19#endif
20
21/** @defgroup grid_ref Grid Reference
22 *
23 * A grid reference is a reference to a specific cell position in the
24 * terminal. Obtain a grid reference from `ghostty_terminal_grid_ref`
25 * for untracked or `ghostty_terminal_grid_ref_track` for tracked. Untracked
26 * vs tracked is explained next.
27 *
28 * Important: The grid reference APIs are not meant to be used as the core of a render
29 * loop. They are not built to sustain the framerates needed for rendering large
30 * screens. Use the render state API for that.
31 *
32 * ## Untracked vs Tracked References
33 *
34 * ### Untracked Reference
35 *
36 * An untracked grid reference is a value type that snapshots a specific
37 * cell. It is only valid until the next update to the terminal instance.
38 * There is no guarantee that it will remain valid after any operation,
39 * even if a seemingly unrelated part of the grid is changed. These are meant
40 * to be read and have their values cached immediately after obtaining it.
41 *
42 * An untracked grid reference has a performance cost in its initial lookup,
43 * but doesn't affect the ongoing performance of the terminal in any way,
44 * since it is a one-time snapshot.
45 *
46 * ### Tracked Reference
47 *
48 * A tracked grid reference follows its cell across normal screen operations.
49 * For example scrolling, scrollback pruning, resize/reflow, and other
50 * terminal mutations update the tracked reference automatically.
51 *
52 * A tracked reference can still lose its original semantic location. This can
53 * happen when the underlying grid is reset, pruned, or otherwise discarded in a
54 * way that cannot be mapped to a meaningful new cell. In that state,
55 * ghostty_tracked_grid_ref_has_value() returns false and
56 * ghostty_tracked_grid_ref_snapshot() / ghostty_tracked_grid_ref_point() return
57 * GHOSTTY_NO_VALUE. The handle remains valid, and callers may move it to a new
58 * point with ghostty_tracked_grid_ref_set().
59 *
60 * To read cell data from a tracked reference, first snapshot it with
61 * ghostty_tracked_grid_ref_snapshot(). The returned `GhosttyGridRef` is again
62 * an untracked reference and follows the same short lifetime rules as any other
63 * untracked grid reference.
64 *
65 * A tracked reference belongs to the terminal screen/page-list that was active
66 * when it was created or last set. Converting it to a point uses that owning
67 * screen/page-list, even if the terminal has since switched between primary and
68 * alternate screens. Calling ghostty_tracked_grid_ref_set() resolves the new
69 * point against the terminal's currently active screen/page-list and may move
70 * the tracked reference between screens.
71 *
72 * Tracked references are owned by the caller and must be freed with
73 * ghostty_tracked_grid_ref_free(). If the terminal that created a tracked
74 * reference is freed first, the handle remains valid only for tracked-grid-ref
75 * APIs: it reports no value and can still be freed.
76 *
77 * Each tracked reference adds bookkeeping to terminal mutations. Use them
78 * sparingly for long-lived anchors such as selections, search state, marks,
79 * or application-side bookmarks.
80 *
81 * ## Lifetime
82 *
83 * An untracked reference is a snapshot. It doesn't need to be freed.
84 * The safety of accessing the value is documented explicitly above: it
85 * is only safe to access any data until the next terminal mutating
86 * operation (including free).
87 *
88 * A tracked reference is allocated and must be freed when it is no
89 * longer needed. A tracked reference may outlive the terminal that created it;
90 * after terminal free, it reports no value and can still be freed.
91 *
92 * ## Examples
93 *
94 * @snippet c-vt-grid-traverse/src/main.c grid-ref-traverse
95 * @snippet c-vt-grid-ref-tracked/src/main.c grid-ref-tracked
96 *
97 * @{
98 */
99
100/**
101 * A resolved reference to a terminal cell position.
102 *
103 * This is a sized struct. Use GHOSTTY_INIT_SIZED() to initialize it.
104 *
105 * @ingroup grid_ref
106 */
107typedef struct {
108 size_t size;
109 void *node;
110 uint16_t x;
111 uint16_t y;
112} GhosttyGridRef;
113
114/**
115 * Get the cell from a grid reference.
116 *
117 * @param ref Pointer to the grid reference
118 * @param[out] out_cell On success, set to the cell at the ref's position (may be NULL)
119 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the ref's
120 * node is NULL
121 *
122 * @ingroup grid_ref
123 */
124GHOSTTY_API GhosttyResult ghostty_grid_ref_cell(const GhosttyGridRef *ref,
125 GhosttyCell *out_cell);
126
127/**
128 * Get the row from a grid reference.
129 *
130 * @param ref Pointer to the grid reference
131 * @param[out] out_row On success, set to the row at the ref's position (may be NULL)
132 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the ref's
133 * node is NULL
134 *
135 * @ingroup grid_ref
136 */
137GHOSTTY_API GhosttyResult ghostty_grid_ref_row(const GhosttyGridRef *ref,
138 GhosttyRow *out_row);
139
140/**
141 * Get the grapheme cluster codepoints for the cell at the grid reference's
142 * position.
143 *
144 * Writes the full grapheme cluster (the cell's primary codepoint followed by
145 * any combining codepoints) into the provided buffer. If the cell has no text,
146 * out_len is set to 0 and GHOSTTY_SUCCESS is returned.
147 *
148 * If the buffer is too small (or NULL), the function returns
149 * GHOSTTY_OUT_OF_SPACE and writes the required number of codepoints to
150 * out_len. The caller can then retry with a sufficiently sized buffer.
151 *
152 * @param ref Pointer to the grid reference
153 * @param buf Output buffer of uint32_t codepoints (may be NULL)
154 * @param buf_len Number of uint32_t elements in the buffer
155 * @param[out] out_len On success, the number of codepoints written. On
156 * GHOSTTY_OUT_OF_SPACE, the required buffer size in codepoints.
157 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the ref's
158 * node is NULL, GHOSTTY_OUT_OF_SPACE if the buffer is too small
159 *
160 * @ingroup grid_ref
161 */
162GHOSTTY_API GhosttyResult ghostty_grid_ref_graphemes(const GhosttyGridRef *ref,
163 uint32_t *buf,
164 size_t buf_len,
165 size_t *out_len);
166
167/**
168 * Get the hyperlink URI for the cell at the grid reference's position.
169 *
170 * Writes the URI bytes into the provided buffer. If the cell has no
171 * hyperlink, out_len is set to 0 and GHOSTTY_SUCCESS is returned.
172 *
173 * If the buffer is too small (or NULL), the function returns
174 * GHOSTTY_OUT_OF_SPACE and writes the required number of bytes to
175 * out_len. The caller can then retry with a sufficiently sized buffer.
176 *
177 * @param ref Pointer to the grid reference
178 * @param buf Output buffer for the URI bytes (may be NULL)
179 * @param buf_len Size of the output buffer in bytes
180 * @param[out] out_len On success, the number of bytes written. On
181 * GHOSTTY_OUT_OF_SPACE, the required buffer size in bytes.
182 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the ref's
183 * node is NULL, GHOSTTY_OUT_OF_SPACE if the buffer is too small
184 *
185 * @ingroup grid_ref
186 */
187GHOSTTY_API GhosttyResult ghostty_grid_ref_hyperlink_uri(
188 const GhosttyGridRef *ref,
189 uint8_t *buf,
190 size_t buf_len,
191 size_t *out_len);
192
193/**
194 * Get the style of the cell at the grid reference's position.
195 *
196 * @param ref Pointer to the grid reference
197 * @param[out] out_style On success, set to the cell's style (may be NULL)
198 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the ref's
199 * node is NULL
200 *
201 * @ingroup grid_ref
202 */
203GHOSTTY_API GhosttyResult ghostty_grid_ref_style(const GhosttyGridRef *ref,
204 GhosttyStyle *out_style);
205
206/** @} */
207
208#ifdef __cplusplus
209}
210#endif
211
212#endif /* GHOSTTY_VT_GRID_REF_H */
native/libghostty-vt/include/ghostty/vt/grid_ref_tracked.h created+139
......@@ -0,0 +1,139 @@
1/**
2 * @file grid_ref_tracked.h
3 *
4 * Tracked terminal grid references.
5 */
6
7#ifndef GHOSTTY_VT_GRID_REF_TRACKED_H
8#define GHOSTTY_VT_GRID_REF_TRACKED_H
9
10#include <stdbool.h>
11#include <ghostty/vt/types.h>
12#include <ghostty/vt/grid_ref.h>
13#include <ghostty/vt/point.h>
14
15#ifdef __cplusplus
16extern "C" {
17#endif
18
19/**
20 * Tracked grid references are owned grid references that move with the
21 * terminal. See @ref grid_ref for the full overview of tracked and untracked
22 * grid reference behavior.
23 *
24 * @ingroup grid_ref
25 */
26
27/**
28 * Free a tracked grid reference.
29 *
30 * Passing NULL is allowed and has no effect. A tracked reference may be freed
31 * after the terminal that created it is freed.
32 *
33 * @param ref Tracked grid reference to free.
34 *
35 * @ingroup grid_ref
36 */
37GHOSTTY_API void ghostty_tracked_grid_ref_free(GhosttyTrackedGridRef ref);
38
39/**
40 * Return whether a tracked grid reference currently has a meaningful value.
41 *
42 * If the terminal that created the tracked reference has been freed, this
43 * returns false.
44 *
45 * @param ref Tracked grid reference.
46 * @return true if the reference currently has a meaningful value.
47 *
48 * @ingroup grid_ref
49 */
50GHOSTTY_API bool ghostty_tracked_grid_ref_has_value(
51 GhosttyTrackedGridRef ref);
52
53/**
54 * Convert a tracked grid reference to a point in the requested coordinate
55 * space.
56 *
57 * This is the tracked equivalent of ghostty_terminal_point_from_grid_ref().
58 * Unlike snapshotting, this does not expose an intermediate untracked
59 * GhosttyGridRef.
60 *
61 * A tracked reference is resolved against the terminal screen/page-list that
62 * currently owns the reference. If the terminal has switched between primary
63 * and alternate screens since the reference was created or last set, this may
64 * be different from the terminal's currently active screen.
65 *
66 * If the tracked reference no longer has a meaningful value, this returns
67 * GHOSTTY_NO_VALUE. GHOSTTY_NO_VALUE is also returned when the reference cannot
68 * be represented in the requested coordinate space, including after the
69 * terminal that created the tracked reference has been freed.
70 *
71 * @param ref Tracked grid reference.
72 * @param tag Coordinate space to convert into.
73 * @param[out] out_point On success, receives the coordinate. May be NULL.
74 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if ref is invalid,
75 * or GHOSTTY_NO_VALUE if there is no representable value.
76 *
77 * @ingroup grid_ref
78 */
79GHOSTTY_API GhosttyResult ghostty_tracked_grid_ref_point(
80 GhosttyTrackedGridRef ref,
81 GhosttyPointTag tag,
82 GhosttyPointCoordinate *out_point);
83
84/**
85 * Move an existing tracked grid reference to a new terminal point.
86 *
87 * On success, the tracked reference begins tracking the new point and any prior
88 * "no value" state is cleared. On GHOSTTY_OUT_OF_MEMORY, the original tracked
89 * reference is left unchanged.
90 *
91 * The terminal must be the same terminal that created the tracked reference.
92 * The point is resolved against the terminal screen/page-list that is active at
93 * the time this function is called. If the terminal has switched between
94 * primary and alternate screens, this may move the tracked reference from one
95 * screen/page-list to the other.
96 *
97 * @param ref Tracked grid reference.
98 * @param terminal Terminal instance that owns the reference.
99 * @param point New point to track.
100 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if ref, terminal,
101 * or point is invalid, or GHOSTTY_OUT_OF_MEMORY if allocation fails.
102 *
103 * @ingroup grid_ref
104 */
105GHOSTTY_API GhosttyResult ghostty_tracked_grid_ref_set(
106 GhosttyTrackedGridRef ref,
107 GhosttyTerminal terminal,
108 GhosttyPoint point);
109
110/**
111 * Snapshot a tracked grid reference into a regular GhosttyGridRef.
112 *
113 * The returned GhosttyGridRef is an untracked snapshot and has the same
114 * lifetime rules as ghostty_terminal_grid_ref(): it is only valid until the
115 * next terminal update. Snapshot immediately before calling
116 * ghostty_grid_ref_cell(), ghostty_grid_ref_row(),
117 * ghostty_grid_ref_graphemes(), ghostty_grid_ref_hyperlink_uri(), or
118 * ghostty_grid_ref_style().
119 *
120 * If the tracked reference no longer has a meaningful value, this returns
121 * GHOSTTY_NO_VALUE. This includes references whose owning terminal has been
122 * freed.
123 *
124 * @param ref Tracked grid reference.
125 * @param[out] out_ref On success, receives an untracked snapshot. May be NULL.
126 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if ref is invalid,
127 * or GHOSTTY_NO_VALUE if the tracked location was discarded.
128 *
129 * @ingroup grid_ref
130 */
131GHOSTTY_API GhosttyResult ghostty_tracked_grid_ref_snapshot(
132 GhosttyTrackedGridRef ref,
133 GhosttyGridRef *out_ref);
134
135#ifdef __cplusplus
136}
137#endif
138
139#endif /* GHOSTTY_VT_GRID_REF_TRACKED_H */
native/libghostty-vt/include/ghostty/vt/key.h created+73
......@@ -0,0 +1,73 @@
1/**
2 * @file key.h
3 *
4 * Key encoding module - encode key events into terminal escape sequences.
5 */
6
7#ifndef GHOSTTY_VT_KEY_H
8#define GHOSTTY_VT_KEY_H
9
10/** @defgroup key Key Encoding
11 *
12 * Utilities for encoding key events into terminal escape sequences,
13 * supporting both legacy encoding as well as Kitty Keyboard Protocol.
14 *
15 * ## Basic Usage
16 *
17 * 1. Create an encoder instance with ghostty_key_encoder_new()
18 * 2. Configure encoder options with ghostty_key_encoder_setopt()
19 * or ghostty_key_encoder_setopt_from_terminal() if you have a
20 * GhosttyTerminal.
21 * 3. For each key event:
22 * - Create a key event with ghostty_key_event_new()
23 * - Set event properties (action, key, modifiers, etc.)
24 * - Encode with ghostty_key_encoder_encode()
25 * - Free the event with ghostty_key_event_free()
26 * - Note: You can also reuse the same key event multiple times by
27 * changing its properties.
28 * 4. Free the encoder with ghostty_key_encoder_free() when done
29 *
30 * For a complete working example, see example/c-vt-encode-key in the
31 * repository.
32 *
33 * ## Example
34 *
35 * @snippet c-vt-encode-key/src/main.c key-encode
36 *
37 * ## Example: Encoding with Terminal State
38 *
39 * When you have a GhosttyTerminal, you can sync its modes (cursor key
40 * application, Kitty flags, etc.) into the encoder automatically:
41 *
42 * @code{.c}
43 * // Create a terminal and feed it some VT data that changes modes
44 * GhosttyTerminal terminal;
45 * ghostty_terminal_new(NULL, &terminal,
46 * (GhosttyTerminalOptions){.cols = 80, .rows = 24, .max_scrollback = 0});
47 *
48 * // Application might write data that enables Kitty keyboard protocol, etc.
49 * ghostty_terminal_vt_write(terminal, vt_data, vt_len);
50 *
51 * // Create an encoder and sync its options from the terminal
52 * GhosttyKeyEncoder encoder;
53 * ghostty_key_encoder_new(NULL, &encoder);
54 * ghostty_key_encoder_setopt_from_terminal(encoder, terminal);
55 *
56 * // Encode a key event using the terminal-derived options
57 * char buf[128];
58 * size_t written = 0;
59 * ghostty_key_encoder_encode(encoder, event, buf, sizeof(buf), &written);
60 *
61 * ghostty_key_encoder_free(encoder);
62 * ghostty_terminal_free(terminal);
63 * @endcode
64 *
65 * @{
66 */
67
68#include <ghostty/vt/key/event.h>
69#include <ghostty/vt/key/encoder.h>
70
71/** @} */
72
73#endif /* GHOSTTY_VT_KEY_H */
native/libghostty-vt/include/ghostty/vt/key/encoder.h created+255
......@@ -0,0 +1,255 @@
1/**
2 * @file encoder.h
3 *
4 * Key event encoding to terminal escape sequences.
5 */
6
7#ifndef GHOSTTY_VT_KEY_ENCODER_H
8#define GHOSTTY_VT_KEY_ENCODER_H
9
10#include <stddef.h>
11#include <stdint.h>
12#include <ghostty/vt/types.h>
13#include <ghostty/vt/allocator.h>
14#include <ghostty/vt/terminal.h>
15#include <ghostty/vt/key/event.h>
16
17/**
18 * Opaque handle to a key encoder instance.
19 *
20 * This handle represents a key encoder that converts key events into terminal
21 * escape sequences.
22 *
23 * @ingroup key
24 */
25typedef struct GhosttyKeyEncoderImpl *GhosttyKeyEncoder;
26
27/**
28 * Kitty keyboard protocol flags.
29 *
30 * Bitflags representing the various modes of the Kitty keyboard protocol.
31 * These can be combined using bitwise OR operations. Valid values all
32 * start with `GHOSTTY_KITTY_KEY_`.
33 *
34 * @ingroup key
35 */
36typedef uint8_t GhosttyKittyKeyFlags;
37
38/** Kitty keyboard protocol disabled (all flags off) */
39#define GHOSTTY_KITTY_KEY_DISABLED 0
40
41/** Disambiguate escape codes */
42#define GHOSTTY_KITTY_KEY_DISAMBIGUATE (1 << 0)
43
44/** Report key press and release events */
45#define GHOSTTY_KITTY_KEY_REPORT_EVENTS (1 << 1)
46
47/** Report alternate key codes */
48#define GHOSTTY_KITTY_KEY_REPORT_ALTERNATES (1 << 2)
49
50/** Report all key events including those normally handled by the terminal */
51#define GHOSTTY_KITTY_KEY_REPORT_ALL (1 << 3)
52
53/** Report associated text with key events */
54#define GHOSTTY_KITTY_KEY_REPORT_ASSOCIATED (1 << 4)
55
56/** All Kitty keyboard protocol flags enabled */
57#define GHOSTTY_KITTY_KEY_ALL (GHOSTTY_KITTY_KEY_DISAMBIGUATE | GHOSTTY_KITTY_KEY_REPORT_EVENTS | GHOSTTY_KITTY_KEY_REPORT_ALTERNATES | GHOSTTY_KITTY_KEY_REPORT_ALL | GHOSTTY_KITTY_KEY_REPORT_ASSOCIATED)
58
59/**
60 * macOS option key behavior.
61 *
62 * Determines whether the "option" key on macOS is treated as "alt" or not.
63 * See the Ghostty `macos-option-as-alt` configuration option for more details.
64 *
65 * @ingroup key
66 */
67typedef enum GHOSTTY_ENUM_TYPED {
68 /** Option key is not treated as alt */
69 GHOSTTY_OPTION_AS_ALT_FALSE = 0,
70 /** Option key is treated as alt */
71 GHOSTTY_OPTION_AS_ALT_TRUE = 1,
72 /** Only left option key is treated as alt */
73 GHOSTTY_OPTION_AS_ALT_LEFT = 2,
74 /** Only right option key is treated as alt */
75 GHOSTTY_OPTION_AS_ALT_RIGHT = 3,
76 GHOSTTY_OPTION_AS_ALT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
77} GhosttyOptionAsAlt;
78
79/**
80 * Key encoder option identifiers.
81 *
82 * These values are used with ghostty_key_encoder_setopt() to configure
83 * the behavior of the key encoder.
84 *
85 * @ingroup key
86 */
87typedef enum GHOSTTY_ENUM_TYPED {
88 /** Terminal DEC mode 1: cursor key application mode (value: bool) */
89 GHOSTTY_KEY_ENCODER_OPT_CURSOR_KEY_APPLICATION = 0,
90
91 /** Terminal DEC mode 66: keypad key application mode (value: bool) */
92 GHOSTTY_KEY_ENCODER_OPT_KEYPAD_KEY_APPLICATION = 1,
93
94 /** Terminal DEC mode 1035: ignore keypad with numlock (value: bool) */
95 GHOSTTY_KEY_ENCODER_OPT_IGNORE_KEYPAD_WITH_NUMLOCK = 2,
96
97 /** Terminal DEC mode 1036: alt sends escape prefix (value: bool) */
98 GHOSTTY_KEY_ENCODER_OPT_ALT_ESC_PREFIX = 3,
99
100 /** xterm modifyOtherKeys mode 2 (value: bool) */
101 GHOSTTY_KEY_ENCODER_OPT_MODIFY_OTHER_KEYS_STATE_2 = 4,
102
103 /** Kitty keyboard protocol flags (value: GhosttyKittyKeyFlags bitmask) */
104 GHOSTTY_KEY_ENCODER_OPT_KITTY_FLAGS = 5,
105
106 /** macOS option-as-alt setting (value: GhosttyOptionAsAlt) */
107 GHOSTTY_KEY_ENCODER_OPT_MACOS_OPTION_AS_ALT = 6,
108
109 /** Backarrow key mode (value: bool)
110 * See https://vt100.net/dec/ek-vt3xx-tp-002.pdf page 170
111 * If `false` (the default), `backspace` emits 0x7f
112 * If `true`, `backspace` emits 0x08
113 */
114 GHOSTTY_KEY_ENCODER_OPT_BACKARROW_KEY_MODE = 7,
115
116 GHOSTTY_KEY_ENCODER_OPT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
117} GhosttyKeyEncoderOption;
118
119/**
120 * Create a new key encoder instance.
121 *
122 * Creates a new key encoder with default options. The encoder can be configured
123 * using ghostty_key_encoder_setopt() and must be freed using
124 * ghostty_key_encoder_free() when no longer needed.
125 *
126 * @param allocator Pointer to the allocator to use for memory management, or NULL to use the default allocator
127 * @param encoder Pointer to store the created encoder handle
128 * @return GHOSTTY_SUCCESS on success, or an error code on failure
129 *
130 * @ingroup key
131 */
132GHOSTTY_API GhosttyResult ghostty_key_encoder_new(const GhosttyAllocator *allocator, GhosttyKeyEncoder *encoder);
133
134/**
135 * Free a key encoder instance.
136 *
137 * Releases all resources associated with the key encoder. After this call,
138 * the encoder handle becomes invalid and must not be used.
139 *
140 * @param encoder The encoder handle to free (may be NULL)
141 *
142 * @ingroup key
143 */
144GHOSTTY_API void ghostty_key_encoder_free(GhosttyKeyEncoder encoder);
145
146/**
147 * Set an option on the key encoder.
148 *
149 * Configures the behavior of the key encoder. Options control various aspects
150 * of encoding such as terminal modes (cursor key application mode, keypad mode),
151 * protocol selection (Kitty keyboard protocol flags), and platform-specific
152 * behaviors (macOS option-as-alt).
153 *
154 * If you are using a terminal instance, you can set the key encoding
155 * options based on the active terminal state (e.g. legacy vs Kitty mode
156 * and associated flags) with ghostty_key_encoder_setopt_from_terminal().
157 *
158 * A null pointer value does nothing. It does not reset the value to the
159 * default. The setopt call will do nothing.
160 *
161 * @param encoder The encoder handle, must not be NULL
162 * @param option The option to set
163 * @param value Pointer to the value to set (type depends on the option)
164 *
165 * @ingroup key
166 */
167GHOSTTY_API void ghostty_key_encoder_setopt(GhosttyKeyEncoder encoder, GhosttyKeyEncoderOption option, const void *value);
168
169/**
170 * Set encoder options from a terminal's current state.
171 *
172 * Reads the terminal's current modes and flags and applies them to the
173 * encoder's options. This sets cursor key application mode, keypad mode,
174 * alt escape prefix, modifyOtherKeys state, and Kitty keyboard protocol
175 * flags from the terminal state.
176 *
177 * Note that the `macos_option_as_alt` option cannot be determined from
178 * terminal state and is reset to `GHOSTTY_OPTION_AS_ALT_FALSE` by this
179 * call. Use ghostty_key_encoder_setopt() to set it afterward if needed.
180 *
181 * @param encoder The encoder handle, must not be NULL
182 * @param terminal The terminal handle, must not be NULL
183 *
184 * @ingroup key
185 */
186GHOSTTY_API void ghostty_key_encoder_setopt_from_terminal(GhosttyKeyEncoder encoder, GhosttyTerminal terminal);
187
188/**
189 * Encode a key event into a terminal escape sequence.
190 *
191 * Converts a key event into the appropriate terminal escape sequence based on
192 * the encoder's current options. The sequence is written to the provided buffer.
193 *
194 * Not all key events produce output. For example, unmodified modifier keys
195 * typically don't generate escape sequences. Check the out_len parameter to
196 * determine if any data was written.
197 *
198 * If the output buffer is too small, this function returns GHOSTTY_OUT_OF_SPACE
199 * and out_len will contain the required buffer size. The caller can then
200 * allocate a larger buffer and call the function again.
201 *
202 * @param encoder The encoder handle, must not be NULL
203 * @param event The key event to encode, must not be NULL
204 * @param out_buf Buffer to write the encoded sequence to
205 * @param out_buf_size Size of the output buffer in bytes
206 * @param out_len Pointer to store the number of bytes written (may be NULL)
207 * @return GHOSTTY_SUCCESS on success, GHOSTTY_OUT_OF_SPACE if buffer too small, or other error code
208 *
209 * ## Example: Calculate required buffer size
210 *
211 * @code{.c}
212 * // Query the required size with a NULL buffer (always returns OUT_OF_SPACE)
213 * size_t required = 0;
214 * GhosttyResult result = ghostty_key_encoder_encode(encoder, event, NULL, 0, &required);
215 * assert(result == GHOSTTY_OUT_OF_SPACE);
216 *
217 * // Allocate buffer of required size
218 * char *buf = malloc(required);
219 *
220 * // Encode with properly sized buffer
221 * size_t written = 0;
222 * result = ghostty_key_encoder_encode(encoder, event, buf, required, &written);
223 * assert(result == GHOSTTY_SUCCESS);
224 *
225 * // Use the encoded sequence...
226 *
227 * free(buf);
228 * @endcode
229 *
230 * ## Example: Direct encoding with static buffer
231 *
232 * @code{.c}
233 * // Most escape sequences are short, so a static buffer often suffices
234 * char buf[128];
235 * size_t written = 0;
236 * GhosttyResult result = ghostty_key_encoder_encode(encoder, event, buf, sizeof(buf), &written);
237 *
238 * if (result == GHOSTTY_SUCCESS) {
239 * // Write the encoded sequence to the terminal
240 * write(pty_fd, buf, written);
241 * } else if (result == GHOSTTY_OUT_OF_SPACE) {
242 * // Buffer too small, written contains required size
243 * char *dynamic_buf = malloc(written);
244 * result = ghostty_key_encoder_encode(encoder, event, dynamic_buf, written, &written);
245 * assert(result == GHOSTTY_SUCCESS);
246 * write(pty_fd, dynamic_buf, written);
247 * free(dynamic_buf);
248 * }
249 * @endcode
250 *
251 * @ingroup key
252 */
253GHOSTTY_API GhosttyResult ghostty_key_encoder_encode(GhosttyKeyEncoder encoder, GhosttyKeyEvent event, char *out_buf, size_t out_buf_size, size_t *out_len);
254
255#endif /* GHOSTTY_VT_KEY_ENCODER_H */
native/libghostty-vt/include/ghostty/vt/key/event.h created+482
......@@ -0,0 +1,482 @@
1/**
2 * @file event.h
3 *
4 * Key event representation and manipulation.
5 */
6
7#ifndef GHOSTTY_VT_KEY_EVENT_H
8#define GHOSTTY_VT_KEY_EVENT_H
9
10#include <stdbool.h>
11#include <stddef.h>
12#include <stdint.h>
13#include <ghostty/vt/types.h>
14#include <ghostty/vt/allocator.h>
15
16/**
17 * Opaque handle to a key event.
18 *
19 * This handle represents a keyboard input event containing information about
20 * the physical key pressed, modifiers, and generated text.
21 *
22 * @ingroup key
23 */
24typedef struct GhosttyKeyEventImpl *GhosttyKeyEvent;
25
26/**
27 * Keyboard input event types.
28 *
29 * @ingroup key
30 */
31typedef enum GHOSTTY_ENUM_TYPED {
32 /** Key was released */
33 GHOSTTY_KEY_ACTION_RELEASE = 0,
34 /** Key was pressed */
35 GHOSTTY_KEY_ACTION_PRESS = 1,
36 /** Key is being repeated (held down) */
37 GHOSTTY_KEY_ACTION_REPEAT = 2,
38 GHOSTTY_KEY_ACTION_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
39} GhosttyKeyAction;
40
41/**
42 * Keyboard modifier keys bitmask.
43 *
44 * A bitmask representing all keyboard modifiers. This tracks which modifier keys
45 * are pressed and, where supported by the platform, which side (left or right)
46 * of each modifier is active.
47 *
48 * Use the GHOSTTY_MODS_* constants to test and set individual modifiers.
49 *
50 * Modifier side bits are only meaningful when the corresponding modifier bit is set.
51 * Not all platforms support distinguishing between left and right modifier
52 * keys and Ghostty is built to expect that some platforms may not provide this
53 * information.
54 *
55 * @ingroup key
56 */
57typedef uint16_t GhosttyMods;
58
59/** Shift key is pressed */
60#define GHOSTTY_MODS_SHIFT (1 << 0)
61/** Control key is pressed */
62#define GHOSTTY_MODS_CTRL (1 << 1)
63/** Alt/Option key is pressed */
64#define GHOSTTY_MODS_ALT (1 << 2)
65/** Super/Command/Windows key is pressed */
66#define GHOSTTY_MODS_SUPER (1 << 3)
67/** Caps Lock is active */
68#define GHOSTTY_MODS_CAPS_LOCK (1 << 4)
69/** Num Lock is active */
70#define GHOSTTY_MODS_NUM_LOCK (1 << 5)
71
72/**
73 * Right shift is pressed (0 = left, 1 = right).
74 * Only meaningful when GHOSTTY_MODS_SHIFT is set.
75 */
76#define GHOSTTY_MODS_SHIFT_SIDE (1 << 6)
77/**
78 * Right ctrl is pressed (0 = left, 1 = right).
79 * Only meaningful when GHOSTTY_MODS_CTRL is set.
80 */
81#define GHOSTTY_MODS_CTRL_SIDE (1 << 7)
82/**
83 * Right alt is pressed (0 = left, 1 = right).
84 * Only meaningful when GHOSTTY_MODS_ALT is set.
85 */
86#define GHOSTTY_MODS_ALT_SIDE (1 << 8)
87/**
88 * Right super is pressed (0 = left, 1 = right).
89 * Only meaningful when GHOSTTY_MODS_SUPER is set.
90 */
91#define GHOSTTY_MODS_SUPER_SIDE (1 << 9)
92
93/**
94 * Physical key codes.
95 *
96 * The set of key codes that Ghostty is aware of. These represent physical keys
97 * on the keyboard and are layout-independent. For example, the "a" key on a US
98 * keyboard is the same as the "ф" key on a Russian keyboard, but both will
99 * report the same key_a value.
100 *
101 * Layout-dependent strings are provided separately as UTF-8 text and are produced
102 * by the platform. These values are based on the W3C UI Events KeyboardEvent code
103 * standard. See: https://www.w3.org/TR/uievents-code
104 *
105 * @ingroup key
106 */
107typedef enum GHOSTTY_ENUM_TYPED {
108 GHOSTTY_KEY_UNIDENTIFIED = 0,
109
110 // Writing System Keys (W3C § 3.1.1)
111 GHOSTTY_KEY_BACKQUOTE,
112 GHOSTTY_KEY_BACKSLASH,
113 GHOSTTY_KEY_BRACKET_LEFT,
114 GHOSTTY_KEY_BRACKET_RIGHT,
115 GHOSTTY_KEY_COMMA,
116 GHOSTTY_KEY_DIGIT_0,
117 GHOSTTY_KEY_DIGIT_1,
118 GHOSTTY_KEY_DIGIT_2,
119 GHOSTTY_KEY_DIGIT_3,
120 GHOSTTY_KEY_DIGIT_4,
121 GHOSTTY_KEY_DIGIT_5,
122 GHOSTTY_KEY_DIGIT_6,
123 GHOSTTY_KEY_DIGIT_7,
124 GHOSTTY_KEY_DIGIT_8,
125 GHOSTTY_KEY_DIGIT_9,
126 GHOSTTY_KEY_EQUAL,
127 GHOSTTY_KEY_INTL_BACKSLASH,
128 GHOSTTY_KEY_INTL_RO,
129 GHOSTTY_KEY_INTL_YEN,
130 GHOSTTY_KEY_A,
131 GHOSTTY_KEY_B,
132 GHOSTTY_KEY_C,
133 GHOSTTY_KEY_D,
134 GHOSTTY_KEY_E,
135 GHOSTTY_KEY_F,
136 GHOSTTY_KEY_G,
137 GHOSTTY_KEY_H,
138 GHOSTTY_KEY_I,
139 GHOSTTY_KEY_J,
140 GHOSTTY_KEY_K,
141 GHOSTTY_KEY_L,
142 GHOSTTY_KEY_M,
143 GHOSTTY_KEY_N,
144 GHOSTTY_KEY_O,
145 GHOSTTY_KEY_P,
146 GHOSTTY_KEY_Q,
147 GHOSTTY_KEY_R,
148 GHOSTTY_KEY_S,
149 GHOSTTY_KEY_T,
150 GHOSTTY_KEY_U,
151 GHOSTTY_KEY_V,
152 GHOSTTY_KEY_W,
153 GHOSTTY_KEY_X,
154 GHOSTTY_KEY_Y,
155 GHOSTTY_KEY_Z,
156 GHOSTTY_KEY_MINUS,
157 GHOSTTY_KEY_PERIOD,
158 GHOSTTY_KEY_QUOTE,
159 GHOSTTY_KEY_SEMICOLON,
160 GHOSTTY_KEY_SLASH,
161
162 // Functional Keys (W3C § 3.1.2)
163 GHOSTTY_KEY_ALT_LEFT,
164 GHOSTTY_KEY_ALT_RIGHT,
165 GHOSTTY_KEY_BACKSPACE,
166 GHOSTTY_KEY_CAPS_LOCK,
167 GHOSTTY_KEY_CONTEXT_MENU,
168 GHOSTTY_KEY_CONTROL_LEFT,
169 GHOSTTY_KEY_CONTROL_RIGHT,
170 GHOSTTY_KEY_ENTER,
171 GHOSTTY_KEY_META_LEFT,
172 GHOSTTY_KEY_META_RIGHT,
173 GHOSTTY_KEY_SHIFT_LEFT,
174 GHOSTTY_KEY_SHIFT_RIGHT,
175 GHOSTTY_KEY_SPACE,
176 GHOSTTY_KEY_TAB,
177 GHOSTTY_KEY_CONVERT,
178 GHOSTTY_KEY_KANA_MODE,
179 GHOSTTY_KEY_NON_CONVERT,
180
181 // Control Pad Section (W3C § 3.2)
182 GHOSTTY_KEY_DELETE,
183 GHOSTTY_KEY_END,
184 GHOSTTY_KEY_HELP,
185 GHOSTTY_KEY_HOME,
186 GHOSTTY_KEY_INSERT,
187 GHOSTTY_KEY_PAGE_DOWN,
188 GHOSTTY_KEY_PAGE_UP,
189
190 // Arrow Pad Section (W3C § 3.3)
191 GHOSTTY_KEY_ARROW_DOWN,
192 GHOSTTY_KEY_ARROW_LEFT,
193 GHOSTTY_KEY_ARROW_RIGHT,
194 GHOSTTY_KEY_ARROW_UP,
195
196 // Numpad Section (W3C § 3.4)
197 GHOSTTY_KEY_NUM_LOCK,
198 GHOSTTY_KEY_NUMPAD_0,
199 GHOSTTY_KEY_NUMPAD_1,
200 GHOSTTY_KEY_NUMPAD_2,
201 GHOSTTY_KEY_NUMPAD_3,
202 GHOSTTY_KEY_NUMPAD_4,
203 GHOSTTY_KEY_NUMPAD_5,
204 GHOSTTY_KEY_NUMPAD_6,
205 GHOSTTY_KEY_NUMPAD_7,
206 GHOSTTY_KEY_NUMPAD_8,
207 GHOSTTY_KEY_NUMPAD_9,
208 GHOSTTY_KEY_NUMPAD_ADD,
209 GHOSTTY_KEY_NUMPAD_BACKSPACE,
210 GHOSTTY_KEY_NUMPAD_CLEAR,
211 GHOSTTY_KEY_NUMPAD_CLEAR_ENTRY,
212 GHOSTTY_KEY_NUMPAD_COMMA,
213 GHOSTTY_KEY_NUMPAD_DECIMAL,
214 GHOSTTY_KEY_NUMPAD_DIVIDE,
215 GHOSTTY_KEY_NUMPAD_ENTER,
216 GHOSTTY_KEY_NUMPAD_EQUAL,
217 GHOSTTY_KEY_NUMPAD_MEMORY_ADD,
218 GHOSTTY_KEY_NUMPAD_MEMORY_CLEAR,
219 GHOSTTY_KEY_NUMPAD_MEMORY_RECALL,
220 GHOSTTY_KEY_NUMPAD_MEMORY_STORE,
221 GHOSTTY_KEY_NUMPAD_MEMORY_SUBTRACT,
222 GHOSTTY_KEY_NUMPAD_MULTIPLY,
223 GHOSTTY_KEY_NUMPAD_PAREN_LEFT,
224 GHOSTTY_KEY_NUMPAD_PAREN_RIGHT,
225 GHOSTTY_KEY_NUMPAD_SUBTRACT,
226 GHOSTTY_KEY_NUMPAD_SEPARATOR,
227 GHOSTTY_KEY_NUMPAD_UP,
228 GHOSTTY_KEY_NUMPAD_DOWN,
229 GHOSTTY_KEY_NUMPAD_RIGHT,
230 GHOSTTY_KEY_NUMPAD_LEFT,
231 GHOSTTY_KEY_NUMPAD_BEGIN,
232 GHOSTTY_KEY_NUMPAD_HOME,
233 GHOSTTY_KEY_NUMPAD_END,
234 GHOSTTY_KEY_NUMPAD_INSERT,
235 GHOSTTY_KEY_NUMPAD_DELETE,
236 GHOSTTY_KEY_NUMPAD_PAGE_UP,
237 GHOSTTY_KEY_NUMPAD_PAGE_DOWN,
238
239 // Function Section (W3C § 3.5)
240 GHOSTTY_KEY_ESCAPE,
241 GHOSTTY_KEY_F1,
242 GHOSTTY_KEY_F2,
243 GHOSTTY_KEY_F3,
244 GHOSTTY_KEY_F4,
245 GHOSTTY_KEY_F5,
246 GHOSTTY_KEY_F6,
247 GHOSTTY_KEY_F7,
248 GHOSTTY_KEY_F8,
249 GHOSTTY_KEY_F9,
250 GHOSTTY_KEY_F10,
251 GHOSTTY_KEY_F11,
252 GHOSTTY_KEY_F12,
253 GHOSTTY_KEY_F13,
254 GHOSTTY_KEY_F14,
255 GHOSTTY_KEY_F15,
256 GHOSTTY_KEY_F16,
257 GHOSTTY_KEY_F17,
258 GHOSTTY_KEY_F18,
259 GHOSTTY_KEY_F19,
260 GHOSTTY_KEY_F20,
261 GHOSTTY_KEY_F21,
262 GHOSTTY_KEY_F22,
263 GHOSTTY_KEY_F23,
264 GHOSTTY_KEY_F24,
265 GHOSTTY_KEY_F25,
266 GHOSTTY_KEY_FN,
267 GHOSTTY_KEY_FN_LOCK,
268 GHOSTTY_KEY_PRINT_SCREEN,
269 GHOSTTY_KEY_SCROLL_LOCK,
270 GHOSTTY_KEY_PAUSE,
271
272 // Media Keys (W3C § 3.6)
273 GHOSTTY_KEY_BROWSER_BACK,
274 GHOSTTY_KEY_BROWSER_FAVORITES,
275 GHOSTTY_KEY_BROWSER_FORWARD,
276 GHOSTTY_KEY_BROWSER_HOME,
277 GHOSTTY_KEY_BROWSER_REFRESH,
278 GHOSTTY_KEY_BROWSER_SEARCH,
279 GHOSTTY_KEY_BROWSER_STOP,
280 GHOSTTY_KEY_EJECT,
281 GHOSTTY_KEY_LAUNCH_APP_1,
282 GHOSTTY_KEY_LAUNCH_APP_2,
283 GHOSTTY_KEY_LAUNCH_MAIL,
284 GHOSTTY_KEY_MEDIA_PLAY_PAUSE,
285 GHOSTTY_KEY_MEDIA_SELECT,
286 GHOSTTY_KEY_MEDIA_STOP,
287 GHOSTTY_KEY_MEDIA_TRACK_NEXT,
288 GHOSTTY_KEY_MEDIA_TRACK_PREVIOUS,
289 GHOSTTY_KEY_POWER,
290 GHOSTTY_KEY_SLEEP,
291 GHOSTTY_KEY_AUDIO_VOLUME_DOWN,
292 GHOSTTY_KEY_AUDIO_VOLUME_MUTE,
293 GHOSTTY_KEY_AUDIO_VOLUME_UP,
294 GHOSTTY_KEY_WAKE_UP,
295
296 // Legacy, Non-standard, and Special Keys (W3C § 3.7)
297 GHOSTTY_KEY_COPY,
298 GHOSTTY_KEY_CUT,
299 GHOSTTY_KEY_PASTE,
300 GHOSTTY_KEY_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
301} GhosttyKey;
302
303/**
304 * Create a new key event instance.
305 *
306 * Creates a new key event with default values. The event must be freed using
307 * ghostty_key_event_free() when no longer needed.
308 *
309 * @param allocator Pointer to the allocator to use for memory management, or NULL to use the default allocator
310 * @param event Pointer to store the created key event handle
311 * @return GHOSTTY_SUCCESS on success, or an error code on failure
312 *
313 * @ingroup key
314 */
315GHOSTTY_API GhosttyResult ghostty_key_event_new(const GhosttyAllocator *allocator, GhosttyKeyEvent *event);
316
317/**
318 * Free a key event instance.
319 *
320 * Releases all resources associated with the key event. After this call,
321 * the event handle becomes invalid and must not be used.
322 *
323 * @param event The key event handle to free (may be NULL)
324 *
325 * @ingroup key
326 */
327GHOSTTY_API void ghostty_key_event_free(GhosttyKeyEvent event);
328
329/**
330 * Set the key action (press, release, repeat).
331 *
332 * @param event The key event handle, must not be NULL
333 * @param action The action to set
334 *
335 * @ingroup key
336 */
337GHOSTTY_API void ghostty_key_event_set_action(GhosttyKeyEvent event, GhosttyKeyAction action);
338
339/**
340 * Get the key action (press, release, repeat).
341 *
342 * @param event The key event handle, must not be NULL
343 * @return The key action
344 *
345 * @ingroup key
346 */
347GHOSTTY_API GhosttyKeyAction ghostty_key_event_get_action(GhosttyKeyEvent event);
348
349/**
350 * Set the physical key code.
351 *
352 * @param event The key event handle, must not be NULL
353 * @param key The physical key code to set
354 *
355 * @ingroup key
356 */
357GHOSTTY_API void ghostty_key_event_set_key(GhosttyKeyEvent event, GhosttyKey key);
358
359/**
360 * Get the physical key code.
361 *
362 * @param event The key event handle, must not be NULL
363 * @return The physical key code
364 *
365 * @ingroup key
366 */
367GHOSTTY_API GhosttyKey ghostty_key_event_get_key(GhosttyKeyEvent event);
368
369/**
370 * Set the modifier keys bitmask.
371 *
372 * @param event The key event handle, must not be NULL
373 * @param mods The modifier keys bitmask to set
374 *
375 * @ingroup key
376 */
377GHOSTTY_API void ghostty_key_event_set_mods(GhosttyKeyEvent event, GhosttyMods mods);
378
379/**
380 * Get the modifier keys bitmask.
381 *
382 * @param event The key event handle, must not be NULL
383 * @return The modifier keys bitmask
384 *
385 * @ingroup key
386 */
387GHOSTTY_API GhosttyMods ghostty_key_event_get_mods(GhosttyKeyEvent event);
388
389/**
390 * Set the consumed modifiers bitmask.
391 *
392 * @param event The key event handle, must not be NULL
393 * @param consumed_mods The consumed modifiers bitmask to set
394 *
395 * @ingroup key
396 */
397GHOSTTY_API void ghostty_key_event_set_consumed_mods(GhosttyKeyEvent event, GhosttyMods consumed_mods);
398
399/**
400 * Get the consumed modifiers bitmask.
401 *
402 * @param event The key event handle, must not be NULL
403 * @return The consumed modifiers bitmask
404 *
405 * @ingroup key
406 */
407GHOSTTY_API GhosttyMods ghostty_key_event_get_consumed_mods(GhosttyKeyEvent event);
408
409/**
410 * Set whether the key event is part of a composition sequence.
411 *
412 * @param event The key event handle, must not be NULL
413 * @param composing Whether the key event is part of a composition sequence
414 *
415 * @ingroup key
416 */
417GHOSTTY_API void ghostty_key_event_set_composing(GhosttyKeyEvent event, bool composing);
418
419/**
420 * Get whether the key event is part of a composition sequence.
421 *
422 * @param event The key event handle, must not be NULL
423 * @return Whether the key event is part of a composition sequence
424 *
425 * @ingroup key
426 */
427GHOSTTY_API bool ghostty_key_event_get_composing(GhosttyKeyEvent event);
428
429/**
430 * Set the UTF-8 text generated by the key for the current keyboard layout.
431 *
432 * Must contain the unmodified character before any Ctrl/Meta transformations.
433 * The encoder derives modifier sequences from the logical key and mods
434 * bitmask, not from this text. Do not pass C0 control characters
435 * (U+0000-U+001F, U+007F) or platform function key codes (e.g. macOS PUA
436 * U+F700-U+F8FF); pass NULL instead and let the encoder use the logical key.
437 *
438 * The key event does NOT take ownership of the text pointer. The caller
439 * must ensure the string remains valid for the lifetime needed by the event.
440 *
441 * @param event The key event handle, must not be NULL
442 * @param utf8 The UTF-8 text to set (or NULL for empty)
443 * @param len Length of the UTF-8 text in bytes
444 *
445 * @ingroup key
446 */
447GHOSTTY_API void ghostty_key_event_set_utf8(GhosttyKeyEvent event, const char *utf8, size_t len);
448
449/**
450 * Get the UTF-8 text generated by the key event.
451 *
452 * The returned pointer is valid until the event is freed or the UTF-8 text is modified.
453 *
454 * @param event The key event handle, must not be NULL
455 * @param len Pointer to store the length of the UTF-8 text in bytes (may be NULL)
456 * @return The UTF-8 text (or NULL for empty)
457 *
458 * @ingroup key
459 */
460GHOSTTY_API const char *ghostty_key_event_get_utf8(GhosttyKeyEvent event, size_t *len);
461
462/**
463 * Set the unshifted Unicode codepoint.
464 *
465 * @param event The key event handle, must not be NULL
466 * @param codepoint The unshifted Unicode codepoint to set
467 *
468 * @ingroup key
469 */
470GHOSTTY_API void ghostty_key_event_set_unshifted_codepoint(GhosttyKeyEvent event, uint32_t codepoint);
471
472/**
473 * Get the unshifted Unicode codepoint.
474 *
475 * @param event The key event handle, must not be NULL
476 * @return The unshifted Unicode codepoint
477 *
478 * @ingroup key
479 */
480GHOSTTY_API uint32_t ghostty_key_event_get_unshifted_codepoint(GhosttyKeyEvent event);
481
482#endif /* GHOSTTY_VT_KEY_EVENT_H */
native/libghostty-vt/include/ghostty/vt/kitty_graphics.h created+775
......@@ -0,0 +1,775 @@
1/**
2 * @file kitty_graphics.h
3 *
4 * Kitty graphics protocol
5 *
6 * See @ref kitty_graphics for a full usage guide.
7 */
8
9#ifndef GHOSTTY_VT_KITTY_GRAPHICS_H
10#define GHOSTTY_VT_KITTY_GRAPHICS_H
11
12#include <stdbool.h>
13#include <stdint.h>
14#include <ghostty/vt/allocator.h>
15#include <ghostty/vt/selection.h>
16#include <ghostty/vt/types.h>
17
18#ifdef __cplusplus
19extern "C" {
20#endif
21
22/** @defgroup kitty_graphics Kitty Graphics
23 *
24 * API for inspecting images and placements stored via the
25 * [Kitty graphics protocol](https://sw.kovidgoyal.net/kitty/graphics-protocol/).
26 *
27 * The central object is @ref GhosttyKittyGraphics, an opaque handle to
28 * the image storage associated with a terminal's active screen. From it
29 * you can iterate over placements and look up individual images.
30 *
31 * ## Obtaining a KittyGraphics Handle
32 *
33 * A @ref GhosttyKittyGraphics handle is obtained from a terminal via
34 * ghostty_terminal_get() with @ref GHOSTTY_TERMINAL_DATA_KITTY_GRAPHICS.
35 * The handle is borrowed from the terminal and remains valid until the
36 * next mutating terminal call (e.g. ghostty_terminal_vt_write() or
37 * ghostty_terminal_reset()).
38 *
39 * Before images can be stored, Kitty graphics must be enabled on the
40 * terminal by setting a non-zero storage limit with
41 * @ref GHOSTTY_TERMINAL_OPT_KITTY_IMAGE_STORAGE_LIMIT, and a PNG
42 * decoder callback must be installed via ghostty_sys_set() with
43 * @ref GHOSTTY_SYS_OPT_DECODE_PNG.
44 *
45 * @snippet c-vt-kitty-graphics/src/main.c kitty-graphics-decode-png
46 *
47 * ## Iterating Placements
48 *
49 * Placements are inspected through a @ref GhosttyKittyGraphicsPlacementIterator.
50 * The typical workflow is:
51 *
52 * 1. Create an iterator with ghostty_kitty_graphics_placement_iterator_new().
53 * 2. Populate it from the storage with ghostty_kitty_graphics_get() using
54 * @ref GHOSTTY_KITTY_GRAPHICS_DATA_PLACEMENT_ITERATOR.
55 * 3. Optionally filter by z-layer with
56 * ghostty_kitty_graphics_placement_iterator_set().
57 * 4. Advance with ghostty_kitty_graphics_placement_next() and read
58 * per-placement data with ghostty_kitty_graphics_placement_get().
59 * 5. For each placement, look up its image with
60 * ghostty_kitty_graphics_image() to access pixel data and dimensions.
61 * 6. Free the iterator with ghostty_kitty_graphics_placement_iterator_free().
62 *
63 * ## Looking Up Images
64 *
65 * Given an image ID (obtained from a placement via
66 * @ref GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_IMAGE_ID), call
67 * ghostty_kitty_graphics_image() to get a @ref GhosttyKittyGraphicsImage
68 * handle. From this handle, ghostty_kitty_graphics_image_get() provides
69 * the image dimensions, pixel format, compression, and a borrowed pointer
70 * to the raw pixel data.
71 *
72 * ## Rendering Helpers
73 *
74 * Several functions assist with rendering a placement:
75 *
76 * - ghostty_kitty_graphics_placement_pixel_size() — rendered pixel
77 * dimensions accounting for source rect and aspect ratio.
78 * - ghostty_kitty_graphics_placement_grid_size() — number of grid
79 * columns and rows the placement occupies.
80 * - ghostty_kitty_graphics_placement_viewport_pos() — viewport-relative
81 * grid position (may be negative for partially scrolled placements).
82 * - ghostty_kitty_graphics_placement_source_rect() — resolved source
83 * rectangle in pixels, clamped to image bounds.
84 * - ghostty_kitty_graphics_placement_rect() — bounding rectangle as a
85 * @ref GhosttySelection.
86 *
87 * ## Lifetime and Thread Safety
88 *
89 * All handles borrowed from the terminal (GhosttyKittyGraphics,
90 * GhosttyKittyGraphicsImage) are invalidated by any mutating terminal
91 * call. The placement iterator is independently owned and must be freed
92 * by the caller, but the data it yields is only valid while the
93 * underlying terminal is not mutated.
94 *
95 * ## Example
96 *
97 * The following example creates a terminal, sends a Kitty graphics
98 * image, then iterates placements and prints image metadata:
99 *
100 * @snippet c-vt-kitty-graphics/src/main.c kitty-graphics-main
101 *
102 * @{
103 */
104
105/**
106 * Queryable data kinds for ghostty_kitty_graphics_get().
107 *
108 * @ingroup kitty_graphics
109 */
110typedef enum GHOSTTY_ENUM_TYPED {
111 /** Invalid / sentinel value. */
112 GHOSTTY_KITTY_GRAPHICS_DATA_INVALID = 0,
113
114 /**
115 * Populate a pre-allocated placement iterator with placement data from
116 * the storage. Iterator data is only valid as long as the underlying
117 * terminal is not mutated.
118 *
119 * Output type: GhosttyKittyGraphicsPlacementIterator *
120 */
121 GHOSTTY_KITTY_GRAPHICS_DATA_PLACEMENT_ITERATOR = 1,
122 GHOSTTY_KITTY_GRAPHICS_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
123} GhosttyKittyGraphicsData;
124
125/**
126 * Queryable data kinds for ghostty_kitty_graphics_placement_get().
127 *
128 * @ingroup kitty_graphics
129 */
130typedef enum GHOSTTY_ENUM_TYPED {
131 /** Invalid / sentinel value. */
132 GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_INVALID = 0,
133
134 /**
135 * The image ID this placement belongs to.
136 *
137 * Output type: uint32_t *
138 */
139 GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_IMAGE_ID = 1,
140
141 /**
142 * The placement ID.
143 *
144 * Output type: uint32_t *
145 */
146 GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_PLACEMENT_ID = 2,
147
148 /**
149 * Whether this is a virtual placement (unicode placeholder).
150 *
151 * Output type: bool *
152 */
153 GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_IS_VIRTUAL = 3,
154
155 /**
156 * Pixel offset from the left edge of the cell.
157 *
158 * Output type: uint32_t *
159 */
160 GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_X_OFFSET = 4,
161
162 /**
163 * Pixel offset from the top edge of the cell.
164 *
165 * Output type: uint32_t *
166 */
167 GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_Y_OFFSET = 5,
168
169 /**
170 * Source rectangle x origin in pixels.
171 *
172 * Output type: uint32_t *
173 */
174 GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_SOURCE_X = 6,
175
176 /**
177 * Source rectangle y origin in pixels.
178 *
179 * Output type: uint32_t *
180 */
181 GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_SOURCE_Y = 7,
182
183 /**
184 * Source rectangle width in pixels (0 = full image width).
185 *
186 * Output type: uint32_t *
187 */
188 GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_SOURCE_WIDTH = 8,
189
190 /**
191 * Source rectangle height in pixels (0 = full image height).
192 *
193 * Output type: uint32_t *
194 */
195 GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_SOURCE_HEIGHT = 9,
196
197 /**
198 * Number of columns this placement occupies.
199 *
200 * Output type: uint32_t *
201 */
202 GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_COLUMNS = 10,
203
204 /**
205 * Number of rows this placement occupies.
206 *
207 * Output type: uint32_t *
208 */
209 GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_ROWS = 11,
210
211 /**
212 * Z-index for this placement.
213 *
214 * Output type: int32_t *
215 */
216 GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_Z = 12,
217
218 GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
219} GhosttyKittyGraphicsPlacementData;
220
221/**
222 * Z-layer classification for kitty graphics placements.
223 *
224 * Based on the kitty protocol z-index conventions:
225 * - BELOW_BG: z < INT32_MIN/2 (drawn below cell background)
226 * - BELOW_TEXT: INT32_MIN/2 <= z < 0 (above background, below text)
227 * - ABOVE_TEXT: z >= 0 (above text)
228 * - ALL: no filtering (current behavior)
229 *
230 * @ingroup kitty_graphics
231 */
232typedef enum GHOSTTY_ENUM_TYPED {
233 GHOSTTY_KITTY_PLACEMENT_LAYER_ALL = 0,
234 GHOSTTY_KITTY_PLACEMENT_LAYER_BELOW_BG = 1,
235 GHOSTTY_KITTY_PLACEMENT_LAYER_BELOW_TEXT = 2,
236 GHOSTTY_KITTY_PLACEMENT_LAYER_ABOVE_TEXT = 3,
237 GHOSTTY_KITTY_PLACEMENT_LAYER_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
238} GhosttyKittyPlacementLayer;
239
240/**
241 * Settable options for ghostty_kitty_graphics_placement_iterator_set().
242 *
243 * @ingroup kitty_graphics
244 */
245typedef enum GHOSTTY_ENUM_TYPED {
246 /**
247 * Set the z-layer filter for the iterator.
248 *
249 * Input type: GhosttyKittyPlacementLayer *
250 */
251 GHOSTTY_KITTY_GRAPHICS_PLACEMENT_ITERATOR_OPTION_LAYER = 0,
252 GHOSTTY_KITTY_GRAPHICS_PLACEMENT_ITERATOR_OPTION_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
253} GhosttyKittyGraphicsPlacementIteratorOption;
254
255/**
256 * Pixel format of a Kitty graphics image.
257 *
258 * @ingroup kitty_graphics
259 */
260typedef enum GHOSTTY_ENUM_TYPED {
261 GHOSTTY_KITTY_IMAGE_FORMAT_RGB = 0,
262 GHOSTTY_KITTY_IMAGE_FORMAT_RGBA = 1,
263 GHOSTTY_KITTY_IMAGE_FORMAT_PNG = 2,
264 GHOSTTY_KITTY_IMAGE_FORMAT_GRAY_ALPHA = 3,
265 GHOSTTY_KITTY_IMAGE_FORMAT_GRAY = 4,
266 GHOSTTY_KITTY_IMAGE_FORMAT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
267} GhosttyKittyImageFormat;
268
269/**
270 * Compression of a Kitty graphics image.
271 *
272 * @ingroup kitty_graphics
273 */
274typedef enum GHOSTTY_ENUM_TYPED {
275 GHOSTTY_KITTY_IMAGE_COMPRESSION_NONE = 0,
276 GHOSTTY_KITTY_IMAGE_COMPRESSION_ZLIB_DEFLATE = 1,
277 GHOSTTY_KITTY_IMAGE_COMPRESSION_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
278} GhosttyKittyImageCompression;
279
280/**
281 * Queryable data kinds for ghostty_kitty_graphics_image_get().
282 *
283 * @ingroup kitty_graphics
284 */
285typedef enum GHOSTTY_ENUM_TYPED {
286 /** Invalid / sentinel value. */
287 GHOSTTY_KITTY_IMAGE_DATA_INVALID = 0,
288
289 /**
290 * The image ID.
291 *
292 * Output type: uint32_t *
293 */
294 GHOSTTY_KITTY_IMAGE_DATA_ID = 1,
295
296 /**
297 * The image number.
298 *
299 * Output type: uint32_t *
300 */
301 GHOSTTY_KITTY_IMAGE_DATA_NUMBER = 2,
302
303 /**
304 * Image width in pixels.
305 *
306 * Output type: uint32_t *
307 */
308 GHOSTTY_KITTY_IMAGE_DATA_WIDTH = 3,
309
310 /**
311 * Image height in pixels.
312 *
313 * Output type: uint32_t *
314 */
315 GHOSTTY_KITTY_IMAGE_DATA_HEIGHT = 4,
316
317 /**
318 * Pixel format of the image.
319 *
320 * Output type: GhosttyKittyImageFormat *
321 */
322 GHOSTTY_KITTY_IMAGE_DATA_FORMAT = 5,
323
324 /**
325 * Compression of the image.
326 *
327 * Output type: GhosttyKittyImageCompression *
328 */
329 GHOSTTY_KITTY_IMAGE_DATA_COMPRESSION = 6,
330
331 /**
332 * Borrowed pointer to the raw pixel data. Valid as long as the
333 * underlying terminal is not mutated.
334 *
335 * Output type: const uint8_t **
336 */
337 GHOSTTY_KITTY_IMAGE_DATA_DATA_PTR = 7,
338
339 /**
340 * Length of the raw pixel data in bytes.
341 *
342 * Output type: size_t *
343 */
344 GHOSTTY_KITTY_IMAGE_DATA_DATA_LEN = 8,
345
346 GHOSTTY_KITTY_IMAGE_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
347} GhosttyKittyGraphicsImageData;
348
349/**
350 * Combined rendering geometry for a placement in a single sized struct.
351 *
352 * Combines the results of ghostty_kitty_graphics_placement_pixel_size(),
353 * ghostty_kitty_graphics_placement_grid_size(),
354 * ghostty_kitty_graphics_placement_viewport_pos(), and
355 * ghostty_kitty_graphics_placement_source_rect() into one call. This is
356 * an optimization over calling those four functions individually,
357 * particularly useful in environments with high per-call overhead such
358 * as FFI or Cgo.
359 *
360 * This struct uses the sized-struct ABI pattern. Initialize with
361 * GHOSTTY_INIT_SIZED(GhosttyKittyGraphicsPlacementRenderInfo) before calling
362 * ghostty_kitty_graphics_placement_render_info().
363 *
364 * @ingroup kitty_graphics
365 */
366typedef struct {
367 /** Size of this struct in bytes. Must be set to sizeof(GhosttyKittyGraphicsPlacementRenderInfo). */
368 size_t size;
369 /** Rendered width in pixels. */
370 uint32_t pixel_width;
371 /** Rendered height in pixels. */
372 uint32_t pixel_height;
373 /** Number of grid columns the placement occupies. */
374 uint32_t grid_cols;
375 /** Number of grid rows the placement occupies. */
376 uint32_t grid_rows;
377 /** Viewport-relative column (may be negative for partially visible placements). */
378 int32_t viewport_col;
379 /** Viewport-relative row (may be negative for partially visible placements). */
380 int32_t viewport_row;
381 /** False when the placement is fully off-screen or virtual. */
382 bool viewport_visible;
383 /** Resolved source rectangle x origin in pixels. */
384 uint32_t source_x;
385 /** Resolved source rectangle y origin in pixels. */
386 uint32_t source_y;
387 /** Resolved source rectangle width in pixels. */
388 uint32_t source_width;
389 /** Resolved source rectangle height in pixels. */
390 uint32_t source_height;
391} GhosttyKittyGraphicsPlacementRenderInfo;
392
393/**
394 * Get data from a kitty graphics storage instance.
395 *
396 * The output pointer must be of the appropriate type for the requested
397 * data kind.
398 *
399 * Returns GHOSTTY_NO_VALUE when Kitty graphics are disabled at build time.
400 *
401 * @param graphics The kitty graphics handle
402 * @param data The type of data to extract
403 * @param[out] out Pointer to store the extracted data
404 * @return GHOSTTY_SUCCESS on success
405 *
406 * @ingroup kitty_graphics
407 */
408GHOSTTY_API GhosttyResult ghostty_kitty_graphics_get(
409 GhosttyKittyGraphics graphics,
410 GhosttyKittyGraphicsData data,
411 void* out);
412
413/**
414 * Look up a Kitty graphics image by its image ID.
415 *
416 * Returns NULL if no image with the given ID exists or if Kitty graphics
417 * are disabled at build time.
418 *
419 * @param graphics The kitty graphics handle
420 * @param image_id The image ID to look up
421 * @return An opaque image handle, or NULL if not found
422 *
423 * @ingroup kitty_graphics
424 */
425GHOSTTY_API GhosttyKittyGraphicsImage ghostty_kitty_graphics_image(
426 GhosttyKittyGraphics graphics,
427 uint32_t image_id);
428
429/**
430 * Get data from a Kitty graphics image.
431 *
432 * The output pointer must be of the appropriate type for the requested
433 * data kind.
434 *
435 * @param image The image handle (NULL returns GHOSTTY_INVALID_VALUE)
436 * @param data The data kind to query
437 * @param[out] out Pointer to receive the queried value
438 * @return GHOSTTY_SUCCESS on success
439 *
440 * @ingroup kitty_graphics
441 */
442GHOSTTY_API GhosttyResult ghostty_kitty_graphics_image_get(
443 GhosttyKittyGraphicsImage image,
444 GhosttyKittyGraphicsImageData data,
445 void* out);
446
447/**
448 * Get multiple data fields from a Kitty graphics image in a single call.
449 *
450 * This is an optimization over calling ghostty_kitty_graphics_image_get()
451 * repeatedly, particularly useful in environments with high per-call
452 * overhead such as FFI or Cgo.
453 *
454 * Each element in the keys array specifies a data kind, and the
455 * corresponding element in the values array receives the result.
456 * The type of each values[i] pointer must match the output type
457 * documented for keys[i].
458 *
459 * Processing stops at the first error; on success out_written
460 * is set to count, on error it is set to the index of the
461 * failing key (i.e. the number of values successfully written).
462 *
463 * @param image The image handle (NULL returns GHOSTTY_INVALID_VALUE)
464 * @param count Number of key/value pairs
465 * @param keys Array of data kinds to query
466 * @param values Array of output pointers (types must match each key's
467 * documented output type)
468 * @param[out] out_written On return, receives the number of values
469 * successfully written (may be NULL)
470 * @return GHOSTTY_SUCCESS if all queries succeed
471 *
472 * @ingroup kitty_graphics
473 */
474GHOSTTY_API GhosttyResult ghostty_kitty_graphics_image_get_multi(
475 GhosttyKittyGraphicsImage image,
476 size_t count,
477 const GhosttyKittyGraphicsImageData* keys,
478 void** values,
479 size_t* out_written);
480
481/**
482 * Create a new placement iterator instance.
483 *
484 * All fields except the allocator are left undefined until populated
485 * via ghostty_kitty_graphics_get() with
486 * GHOSTTY_KITTY_GRAPHICS_DATA_PLACEMENT_ITERATOR.
487 *
488 * @param allocator Pointer to allocator, or NULL to use the default allocator
489 * @param[out] out_iterator On success, receives the created iterator handle
490 * @return GHOSTTY_SUCCESS on success, GHOSTTY_OUT_OF_MEMORY on allocation
491 * failure
492 *
493 * @ingroup kitty_graphics
494 */
495GHOSTTY_API GhosttyResult ghostty_kitty_graphics_placement_iterator_new(
496 const GhosttyAllocator* allocator,
497 GhosttyKittyGraphicsPlacementIterator* out_iterator);
498
499/**
500 * Free a placement iterator.
501 *
502 * @param iterator The iterator handle to free (may be NULL)
503 *
504 * @ingroup kitty_graphics
505 */
506GHOSTTY_API void ghostty_kitty_graphics_placement_iterator_free(
507 GhosttyKittyGraphicsPlacementIterator iterator);
508
509/**
510 * Set an option on a placement iterator.
511 *
512 * Use GHOSTTY_KITTY_GRAPHICS_PLACEMENT_ITERATOR_OPTION_LAYER with a
513 * GhosttyKittyPlacementLayer value to filter placements by z-layer.
514 * The filter is applied during iteration: ghostty_kitty_graphics_placement_next()
515 * will skip placements that do not match the configured layer.
516 *
517 * The default layer is GHOSTTY_KITTY_PLACEMENT_LAYER_ALL (no filtering).
518 *
519 * @param iterator The iterator handle (NULL returns GHOSTTY_INVALID_VALUE)
520 * @param option The option to set
521 * @param value Pointer to the value (type depends on option; NULL returns
522 * GHOSTTY_INVALID_VALUE)
523 * @return GHOSTTY_SUCCESS on success
524 *
525 * @ingroup kitty_graphics
526 */
527GHOSTTY_API GhosttyResult ghostty_kitty_graphics_placement_iterator_set(
528 GhosttyKittyGraphicsPlacementIterator iterator,
529 GhosttyKittyGraphicsPlacementIteratorOption option,
530 const void* value);
531
532/**
533 * Advance the placement iterator to the next placement.
534 *
535 * If a layer filter has been set via
536 * ghostty_kitty_graphics_placement_iterator_set(), only placements
537 * matching that layer are returned.
538 *
539 * @param iterator The iterator handle (may be NULL)
540 * @return true if advanced to the next placement, false if at the end
541 *
542 * @ingroup kitty_graphics
543 */
544GHOSTTY_API bool ghostty_kitty_graphics_placement_next(
545 GhosttyKittyGraphicsPlacementIterator iterator);
546
547/**
548 * Get data from the current placement in a placement iterator.
549 *
550 * Call ghostty_kitty_graphics_placement_next() at least once before
551 * calling this function.
552 *
553 * @param iterator The iterator handle (NULL returns GHOSTTY_INVALID_VALUE)
554 * @param data The data kind to query
555 * @param[out] out Pointer to receive the queried value
556 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the
557 * iterator is NULL or not positioned on a placement
558 *
559 * @ingroup kitty_graphics
560 */
561GHOSTTY_API GhosttyResult ghostty_kitty_graphics_placement_get(
562 GhosttyKittyGraphicsPlacementIterator iterator,
563 GhosttyKittyGraphicsPlacementData data,
564 void* out);
565
566/**
567 * Get multiple data fields from the current placement in a single call.
568 *
569 * This is an optimization over calling ghostty_kitty_graphics_placement_get()
570 * repeatedly, particularly useful in environments with high per-call
571 * overhead such as FFI or Cgo.
572 *
573 * Each element in the keys array specifies a data kind, and the
574 * corresponding element in the values array receives the result.
575 * The type of each values[i] pointer must match the output type
576 * documented for keys[i].
577 *
578 * Processing stops at the first error; on success out_written
579 * is set to count, on error it is set to the index of the
580 * failing key (i.e. the number of values successfully written).
581 *
582 * @param iterator The iterator handle (NULL returns GHOSTTY_INVALID_VALUE)
583 * @param count Number of key/value pairs
584 * @param keys Array of data kinds to query
585 * @param values Array of output pointers (types must match each key's
586 * documented output type)
587 * @param[out] out_written On return, receives the number of values
588 * successfully written (may be NULL)
589 * @return GHOSTTY_SUCCESS if all queries succeed
590 *
591 * @ingroup kitty_graphics
592 */
593GHOSTTY_API GhosttyResult ghostty_kitty_graphics_placement_get_multi(
594 GhosttyKittyGraphicsPlacementIterator iterator,
595 size_t count,
596 const GhosttyKittyGraphicsPlacementData* keys,
597 void** values,
598 size_t* out_written);
599
600/**
601 * Compute the grid rectangle occupied by the current placement.
602 *
603 * Uses the placement's pin, the image dimensions, and the terminal's
604 * cell/pixel geometry to calculate the bounding rectangle. Virtual
605 * placements (unicode placeholders) return GHOSTTY_NO_VALUE.
606 *
607 * @param terminal The terminal handle
608 * @param image The image handle for this placement's image
609 * @param iterator The placement iterator positioned on a placement
610 * @param[out] out_selection On success, receives the bounding rectangle
611 * as a selection with rectangle=true
612 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if any handle
613 * is NULL or the iterator is not positioned, GHOSTTY_NO_VALUE for
614 * virtual placements or when Kitty graphics are disabled
615 *
616 * @ingroup kitty_graphics
617 */
618GHOSTTY_API GhosttyResult ghostty_kitty_graphics_placement_rect(
619 GhosttyKittyGraphicsPlacementIterator iterator,
620 GhosttyKittyGraphicsImage image,
621 GhosttyTerminal terminal,
622 GhosttySelection* out_selection);
623
624/**
625 * Compute the rendered pixel size of the current placement.
626 *
627 * Takes into account the placement's source rectangle, specified
628 * columns/rows, and aspect ratio to calculate the final rendered
629 * pixel dimensions.
630 *
631 * @param iterator The placement iterator positioned on a placement
632 * @param image The image handle for this placement's image
633 * @param terminal The terminal handle
634 * @param[out] out_width On success, receives the width in pixels
635 * @param[out] out_height On success, receives the height in pixels
636 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if any handle
637 * is NULL or the iterator is not positioned, GHOSTTY_NO_VALUE when
638 * Kitty graphics are disabled
639 *
640 * @ingroup kitty_graphics
641 */
642GHOSTTY_API GhosttyResult ghostty_kitty_graphics_placement_pixel_size(
643 GhosttyKittyGraphicsPlacementIterator iterator,
644 GhosttyKittyGraphicsImage image,
645 GhosttyTerminal terminal,
646 uint32_t* out_width,
647 uint32_t* out_height);
648
649/**
650 * Compute the grid cell size of the current placement.
651 *
652 * Returns the number of columns and rows that the placement occupies
653 * in the terminal grid. If the placement specifies explicit columns
654 * and rows, those are returned directly; otherwise they are calculated
655 * from the pixel size and cell dimensions.
656 *
657 * @param iterator The placement iterator positioned on a placement
658 * @param image The image handle for this placement's image
659 * @param terminal The terminal handle
660 * @param[out] out_cols On success, receives the number of columns
661 * @param[out] out_rows On success, receives the number of rows
662 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if any handle
663 * is NULL or the iterator is not positioned, GHOSTTY_NO_VALUE when
664 * Kitty graphics are disabled
665 *
666 * @ingroup kitty_graphics
667 */
668GHOSTTY_API GhosttyResult ghostty_kitty_graphics_placement_grid_size(
669 GhosttyKittyGraphicsPlacementIterator iterator,
670 GhosttyKittyGraphicsImage image,
671 GhosttyTerminal terminal,
672 uint32_t* out_cols,
673 uint32_t* out_rows);
674
675/**
676 * Get the viewport-relative grid position of the current placement.
677 *
678 * Converts the placement's internal pin to viewport-relative column and
679 * row coordinates. The returned coordinates represent the top-left
680 * corner of the placement in the viewport's grid coordinate space.
681 *
682 * The row value can be negative when the placement's origin has
683 * scrolled above the top of the viewport. For example, a 4-row
684 * image that has scrolled up by 2 rows returns row=-2, meaning
685 * its top 2 rows are above the visible area but its bottom 2 rows
686 * are still on screen. Embedders should use these coordinates
687 * directly when computing the destination rectangle for rendering;
688 * the embedder is responsible for clipping the portion of the image
689 * that falls outside the viewport.
690 *
691 * Returns GHOSTTY_SUCCESS for any placement that is at least
692 * partially visible in the viewport. Returns GHOSTTY_NO_VALUE when
693 * the placement is completely outside the viewport (its bottom edge
694 * is above the viewport or its top edge is at or below the last
695 * viewport row), or when the placement is a virtual (unicode
696 * placeholder) placement.
697 *
698 * @param iterator The placement iterator positioned on a placement
699 * @param image The image handle for this placement's image
700 * @param terminal The terminal handle
701 * @param[out] out_col On success, receives the viewport-relative column
702 * @param[out] out_row On success, receives the viewport-relative row
703 * (may be negative for partially visible placements)
704 * @return GHOSTTY_SUCCESS on success, GHOSTTY_NO_VALUE if fully
705 * off-screen or virtual, GHOSTTY_INVALID_VALUE if any handle
706 * is NULL or the iterator is not positioned
707 *
708 * @ingroup kitty_graphics
709 */
710GHOSTTY_API GhosttyResult ghostty_kitty_graphics_placement_viewport_pos(
711 GhosttyKittyGraphicsPlacementIterator iterator,
712 GhosttyKittyGraphicsImage image,
713 GhosttyTerminal terminal,
714 int32_t* out_col,
715 int32_t* out_row);
716
717/**
718 * Get the resolved source rectangle for the current placement.
719 *
720 * Applies kitty protocol semantics: a width or height of 0 in the
721 * placement means "use the full image dimension", and the resulting
722 * rectangle is clamped to the actual image bounds. The returned
723 * values are in pixels and are ready to use for texture sampling.
724 *
725 * @param iterator The placement iterator positioned on a placement
726 * @param image The image handle for this placement's image
727 * @param[out] out_x Source rect x origin in pixels
728 * @param[out] out_y Source rect y origin in pixels
729 * @param[out] out_width Source rect width in pixels
730 * @param[out] out_height Source rect height in pixels
731 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if any
732 * handle is NULL or the iterator is not positioned
733 *
734 * @ingroup kitty_graphics
735 */
736GHOSTTY_API GhosttyResult ghostty_kitty_graphics_placement_source_rect(
737 GhosttyKittyGraphicsPlacementIterator iterator,
738 GhosttyKittyGraphicsImage image,
739 uint32_t* out_x,
740 uint32_t* out_y,
741 uint32_t* out_width,
742 uint32_t* out_height);
743
744/**
745 * Get all rendering geometry for a placement in a single call.
746 *
747 * Combines pixel size, grid size, viewport position, and source
748 * rectangle into one struct. Initialize with
749 * GHOSTTY_INIT_SIZED(GhosttyKittyGraphicsPlacementRenderInfo).
750 *
751 * When viewport_visible is false, the placement is fully off-screen
752 * or is a virtual placement; viewport_col and viewport_row may
753 * contain meaningless values in that case.
754 *
755 * @param iterator The iterator positioned on a placement
756 * @param image The image handle for this placement's image
757 * @param terminal The terminal handle
758 * @param[out] out_info Pointer to receive the rendering geometry
759 * @return GHOSTTY_SUCCESS on success
760 *
761 * @ingroup kitty_graphics
762 */
763GHOSTTY_API GhosttyResult ghostty_kitty_graphics_placement_render_info(
764 GhosttyKittyGraphicsPlacementIterator iterator,
765 GhosttyKittyGraphicsImage image,
766 GhosttyTerminal terminal,
767 GhosttyKittyGraphicsPlacementRenderInfo* out_info);
768
769/** @} */
770
771#ifdef __cplusplus
772}
773#endif
774
775#endif /* GHOSTTY_VT_KITTY_GRAPHICS_H */
native/libghostty-vt/include/ghostty/vt/modes.h created+198
......@@ -0,0 +1,198 @@
1/**
2 * @file modes.h
3 *
4 * Terminal mode utilities - pack and unpack ANSI/DEC mode identifiers.
5 */
6
7#ifndef GHOSTTY_VT_MODES_H
8#define GHOSTTY_VT_MODES_H
9
10/** @defgroup modes Mode Utilities
11 *
12 * Utilities for working with terminal modes. A mode is a compact
13 * 16-bit representation of a terminal mode identifier that encodes both
14 * the numeric mode value (up to 15 bits) and whether the mode is an ANSI
15 * mode or a DEC private mode (?-prefixed).
16 *
17 * The packed layout (least-significant bit first) is:
18 * - Bits 0–14: mode value (u15)
19 * - Bit 15: ANSI flag (0 = DEC private mode, 1 = ANSI mode)
20 *
21 * ## Example
22 *
23 * @snippet c-vt-modes/src/main.c modes-pack-unpack
24 *
25 * ## DECRPM Report Encoding
26 *
27 * Use ghostty_mode_report_encode() to encode a DECRPM response into a
28 * caller-provided buffer:
29 *
30 * @snippet c-vt-modes/src/main.c modes-decrpm
31 *
32 * @{
33 */
34
35#include <stdbool.h>
36#include <stddef.h>
37#include <stdint.h>
38
39#include <ghostty/vt/types.h>
40
41#ifdef __cplusplus
42extern "C" {
43#endif
44
45/** @name ANSI Modes
46 * Modes for standard ANSI modes.
47 * @{
48 */
49#define GHOSTTY_MODE_KAM (ghostty_mode_new(2, true)) /**< Keyboard action (disable keyboard) */
50#define GHOSTTY_MODE_INSERT (ghostty_mode_new(4, true)) /**< Insert mode */
51#define GHOSTTY_MODE_SRM (ghostty_mode_new(12, true)) /**< Send/receive mode */
52#define GHOSTTY_MODE_LINEFEED (ghostty_mode_new(20, true)) /**< Linefeed/new line mode */
53/** @} */
54
55/** @name DEC Private Modes
56 * Modes for DEC private modes (?-prefixed).
57 * @{
58 */
59#define GHOSTTY_MODE_DECCKM (ghostty_mode_new(1, false)) /**< Cursor keys */
60#define GHOSTTY_MODE_132_COLUMN (ghostty_mode_new(3, false)) /**< 132/80 column mode */
61#define GHOSTTY_MODE_SLOW_SCROLL (ghostty_mode_new(4, false)) /**< Slow scroll */
62#define GHOSTTY_MODE_REVERSE_COLORS (ghostty_mode_new(5, false)) /**< Reverse video */
63#define GHOSTTY_MODE_ORIGIN (ghostty_mode_new(6, false)) /**< Origin mode */
64#define GHOSTTY_MODE_WRAPAROUND (ghostty_mode_new(7, false)) /**< Auto-wrap mode */
65#define GHOSTTY_MODE_AUTOREPEAT (ghostty_mode_new(8, false)) /**< Auto-repeat keys */
66#define GHOSTTY_MODE_X10_MOUSE (ghostty_mode_new(9, false)) /**< X10 mouse reporting */
67#define GHOSTTY_MODE_CURSOR_BLINKING (ghostty_mode_new(12, false)) /**< Cursor blink */
68#define GHOSTTY_MODE_CURSOR_VISIBLE (ghostty_mode_new(25, false)) /**< Cursor visible (DECTCEM) */
69#define GHOSTTY_MODE_ENABLE_MODE_3 (ghostty_mode_new(40, false)) /**< Allow 132 column mode */
70#define GHOSTTY_MODE_REVERSE_WRAP (ghostty_mode_new(45, false)) /**< Reverse wrap */
71#define GHOSTTY_MODE_ALT_SCREEN_LEGACY (ghostty_mode_new(47, false)) /**< Alternate screen (legacy) */
72#define GHOSTTY_MODE_KEYPAD_KEYS (ghostty_mode_new(66, false)) /**< Application keypad */
73#define GHOSTTY_MODE_BACKARROW_KEY_MODE (ghostty_mode_new(67, false)) /**< Backarrow key mode (DECBKM) */
74#define GHOSTTY_MODE_LEFT_RIGHT_MARGIN (ghostty_mode_new(69, false)) /**< Left/right margin mode */
75#define GHOSTTY_MODE_NORMAL_MOUSE (ghostty_mode_new(1000, false)) /**< Normal mouse tracking */
76#define GHOSTTY_MODE_BUTTON_MOUSE (ghostty_mode_new(1002, false)) /**< Button-event mouse tracking */
77#define GHOSTTY_MODE_ANY_MOUSE (ghostty_mode_new(1003, false)) /**< Any-event mouse tracking */
78#define GHOSTTY_MODE_FOCUS_EVENT (ghostty_mode_new(1004, false)) /**< Focus in/out events */
79#define GHOSTTY_MODE_UTF8_MOUSE (ghostty_mode_new(1005, false)) /**< UTF-8 mouse format */
80#define GHOSTTY_MODE_SGR_MOUSE (ghostty_mode_new(1006, false)) /**< SGR mouse format */
81#define GHOSTTY_MODE_ALT_SCROLL (ghostty_mode_new(1007, false)) /**< Alternate scroll mode */
82#define GHOSTTY_MODE_URXVT_MOUSE (ghostty_mode_new(1015, false)) /**< URxvt mouse format */
83#define GHOSTTY_MODE_SGR_PIXELS_MOUSE (ghostty_mode_new(1016, false)) /**< SGR-Pixels mouse format */
84#define GHOSTTY_MODE_NUMLOCK_KEYPAD (ghostty_mode_new(1035, false)) /**< Ignore keypad with NumLock */
85#define GHOSTTY_MODE_ALT_ESC_PREFIX (ghostty_mode_new(1036, false)) /**< Alt key sends ESC prefix */
86#define GHOSTTY_MODE_ALT_SENDS_ESC (ghostty_mode_new(1039, false)) /**< Alt sends escape */
87#define GHOSTTY_MODE_REVERSE_WRAP_EXT (ghostty_mode_new(1045, false)) /**< Extended reverse wrap */
88#define GHOSTTY_MODE_ALT_SCREEN (ghostty_mode_new(1047, false)) /**< Alternate screen */
89#define GHOSTTY_MODE_SAVE_CURSOR (ghostty_mode_new(1048, false)) /**< Save cursor (DECSC) */
90#define GHOSTTY_MODE_ALT_SCREEN_SAVE (ghostty_mode_new(1049, false)) /**< Alt screen + save cursor + clear */
91#define GHOSTTY_MODE_BRACKETED_PASTE (ghostty_mode_new(2004, false)) /**< Bracketed paste mode */
92#define GHOSTTY_MODE_SYNC_OUTPUT (ghostty_mode_new(2026, false)) /**< Synchronized output */
93#define GHOSTTY_MODE_GRAPHEME_CLUSTER (ghostty_mode_new(2027, false)) /**< Grapheme cluster mode */
94#define GHOSTTY_MODE_COLOR_SCHEME_REPORT (ghostty_mode_new(2031, false)) /**< Report color scheme */
95#define GHOSTTY_MODE_IN_BAND_RESIZE (ghostty_mode_new(2048, false)) /**< In-band size reports */
96/** @} */
97
98/**
99 * A packed 16-bit terminal mode.
100 *
101 * Encodes a mode value (bits 0–14) and an ANSI flag (bit 15) into a
102 * single 16-bit integer. Use the inline helper functions to construct
103 * and inspect modes rather than manipulating bits directly.
104 */
105typedef uint16_t GhosttyMode;
106
107/**
108 * Create a mode from a mode value and ANSI flag.
109 *
110 * @param value The numeric mode value (0–32767)
111 * @param ansi true for an ANSI mode, false for a DEC private mode
112 * @return The packed mode
113 *
114 * @ingroup modes
115 */
116static inline GhosttyMode ghostty_mode_new(uint16_t value, bool ansi) {
117 return (GhosttyMode)((value & 0x7FFF) | ((uint16_t)ansi << 15));
118}
119
120/**
121 * Extract the numeric mode value from a mode.
122 *
123 * @param mode The mode
124 * @return The mode value (0–32767)
125 *
126 * @ingroup modes
127 */
128static inline uint16_t ghostty_mode_value(GhosttyMode mode) {
129 return mode & 0x7FFF;
130}
131
132/**
133 * Check whether a mode represents an ANSI mode.
134 *
135 * @param mode The mode
136 * @return true if this is an ANSI mode, false if it is a DEC private mode
137 *
138 * @ingroup modes
139 */
140static inline bool ghostty_mode_ansi(GhosttyMode mode) {
141 return (mode >> 15) != 0;
142}
143
144/**
145 * DECRPM report state values.
146 *
147 * These correspond to the Ps2 parameter in a DECRPM response
148 * sequence (CSI ? Ps1 ; Ps2 $ y).
149 */
150typedef enum GHOSTTY_ENUM_TYPED {
151 /** Mode is not recognized */
152 GHOSTTY_MODE_REPORT_NOT_RECOGNIZED = 0,
153 /** Mode is set (enabled) */
154 GHOSTTY_MODE_REPORT_SET = 1,
155 /** Mode is reset (disabled) */
156 GHOSTTY_MODE_REPORT_RESET = 2,
157 /** Mode is permanently set */
158 GHOSTTY_MODE_REPORT_PERMANENTLY_SET = 3,
159 /** Mode is permanently reset */
160 GHOSTTY_MODE_REPORT_PERMANENTLY_RESET = 4,
161 GHOSTTY_MODE_REPORT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
162} GhosttyModeReportState;
163
164/**
165 * Encode a DECRPM (DEC Private Mode Report) response sequence.
166 *
167 * Writes a mode report escape sequence into the provided buffer.
168 * The generated sequence has the form:
169 * - DEC private mode: CSI ? Ps1 ; Ps2 $ y
170 * - ANSI mode: CSI Ps1 ; Ps2 $ y
171 *
172 * If the buffer is too small, the function returns GHOSTTY_OUT_OF_SPACE
173 * and writes the required buffer size to @p out_written. The caller can
174 * then retry with a sufficiently sized buffer.
175 *
176 * @param mode The mode identifying the mode to report on
177 * @param state The report state for this mode
178 * @param buf Output buffer to write the encoded sequence into (may be NULL)
179 * @param buf_len Size of the output buffer in bytes
180 * @param[out] out_written On success, the number of bytes written. On
181 * GHOSTTY_OUT_OF_SPACE, the required buffer size.
182 * @return GHOSTTY_SUCCESS on success, GHOSTTY_OUT_OF_SPACE if the buffer
183 * is too small
184 */
185GHOSTTY_API GhosttyResult ghostty_mode_report_encode(
186 GhosttyMode mode,
187 GhosttyModeReportState state,
188 char* buf,
189 size_t buf_len,
190 size_t* out_written);
191
192#ifdef __cplusplus
193}
194#endif
195
196/** @} */
197
198#endif /* GHOSTTY_VT_MODES_H */
native/libghostty-vt/include/ghostty/vt/mouse.h created+70
......@@ -0,0 +1,70 @@
1/**
2 * @file mouse.h
3 *
4 * Mouse encoding module - encode mouse events into terminal escape sequences.
5 */
6
7#ifndef GHOSTTY_VT_MOUSE_H
8#define GHOSTTY_VT_MOUSE_H
9
10/** @defgroup mouse Mouse Encoding
11 *
12 * Utilities for encoding mouse events into terminal escape sequences,
13 * supporting X10, UTF-8, SGR, URxvt, and SGR-Pixels mouse protocols.
14 *
15 * ## Basic Usage
16 *
17 * 1. Create an encoder instance with ghostty_mouse_encoder_new().
18 * 2. Configure encoder options with ghostty_mouse_encoder_setopt() or
19 * ghostty_mouse_encoder_setopt_from_terminal().
20 * 3. For each mouse event:
21 * - Create a mouse event with ghostty_mouse_event_new().
22 * - Set event properties (action, button, modifiers, position).
23 * - Encode with ghostty_mouse_encoder_encode().
24 * - Free the event with ghostty_mouse_event_free() or reuse it.
25 * 4. Free the encoder with ghostty_mouse_encoder_free() when done.
26 *
27 * For a complete working example, see example/c-vt-encode-mouse in the
28 * repository.
29 *
30 * ## Example
31 *
32 * @snippet c-vt-encode-mouse/src/main.c mouse-encode
33 *
34 * ## Example: Encoding with Terminal State
35 *
36 * When you have a GhosttyTerminal, you can sync its tracking mode and
37 * output format into the encoder automatically:
38 *
39 * @code{.c}
40 * // Create a terminal and feed it some VT data that enables mouse tracking
41 * GhosttyTerminal terminal;
42 * ghostty_terminal_new(NULL, &terminal,
43 * (GhosttyTerminalOptions){.cols = 80, .rows = 24, .max_scrollback = 0});
44 *
45 * // Application might write data that enables mouse reporting, etc.
46 * ghostty_terminal_vt_write(terminal, vt_data, vt_len);
47 *
48 * // Create an encoder and sync its options from the terminal
49 * GhosttyMouseEncoder encoder;
50 * ghostty_mouse_encoder_new(NULL, &encoder);
51 * ghostty_mouse_encoder_setopt_from_terminal(encoder, terminal);
52 *
53 * // Encode a mouse event using the terminal-derived options
54 * char buf[128];
55 * size_t written = 0;
56 * ghostty_mouse_encoder_encode(encoder, event, buf, sizeof(buf), &written);
57 *
58 * ghostty_mouse_encoder_free(encoder);
59 * ghostty_terminal_free(terminal);
60 * @endcode
61 *
62 * @{
63 */
64
65#include <ghostty/vt/mouse/event.h>
66#include <ghostty/vt/mouse/encoder.h>
67
68/** @} */
69
70#endif /* GHOSTTY_VT_MOUSE_H */
native/libghostty-vt/include/ghostty/vt/mouse/encoder.h created+214
......@@ -0,0 +1,214 @@
1/**
2 * @file encoder.h
3 *
4 * Mouse event encoding to terminal escape sequences.
5 */
6
7#ifndef GHOSTTY_VT_MOUSE_ENCODER_H
8#define GHOSTTY_VT_MOUSE_ENCODER_H
9
10#include <stdbool.h>
11#include <stddef.h>
12#include <stdint.h>
13#include <ghostty/vt/allocator.h>
14#include <ghostty/vt/mouse/event.h>
15#include <ghostty/vt/terminal.h>
16#include <ghostty/vt/types.h>
17
18/**
19 * Opaque handle to a mouse encoder instance.
20 *
21 * This handle represents a mouse encoder that converts normalized
22 * mouse events into terminal escape sequences.
23 *
24 * @ingroup mouse
25 */
26typedef struct GhosttyMouseEncoderImpl *GhosttyMouseEncoder;
27
28/**
29 * Mouse tracking mode.
30 *
31 * @ingroup mouse
32 */
33typedef enum GHOSTTY_ENUM_TYPED {
34 /** Mouse reporting disabled. */
35 GHOSTTY_MOUSE_TRACKING_NONE = 0,
36
37 /** X10 mouse mode. */
38 GHOSTTY_MOUSE_TRACKING_X10 = 1,
39
40 /** Normal mouse mode (button press/release only). */
41 GHOSTTY_MOUSE_TRACKING_NORMAL = 2,
42
43 /** Button-event tracking mode. */
44 GHOSTTY_MOUSE_TRACKING_BUTTON = 3,
45
46 /** Any-event tracking mode. */
47 GHOSTTY_MOUSE_TRACKING_ANY = 4,
48 GHOSTTY_MOUSE_TRACKING_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
49} GhosttyMouseTrackingMode;
50
51/**
52 * Mouse output format.
53 *
54 * @ingroup mouse
55 */
56typedef enum GHOSTTY_ENUM_TYPED {
57 GHOSTTY_MOUSE_FORMAT_X10 = 0,
58 GHOSTTY_MOUSE_FORMAT_UTF8 = 1,
59 GHOSTTY_MOUSE_FORMAT_SGR = 2,
60 GHOSTTY_MOUSE_FORMAT_URXVT = 3,
61 GHOSTTY_MOUSE_FORMAT_SGR_PIXELS = 4,
62 GHOSTTY_MOUSE_FORMAT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
63} GhosttyMouseFormat;
64
65/**
66 * Mouse encoder size and geometry context.
67 *
68 * This describes the rendered terminal geometry used to convert
69 * surface-space positions into encoded coordinates.
70 *
71 * @ingroup mouse
72 */
73typedef struct {
74 /** Size of this struct in bytes. Must be set to sizeof(GhosttyMouseEncoderSize). */
75 size_t size;
76
77 /** Full screen width in pixels. */
78 uint32_t screen_width;
79
80 /** Full screen height in pixels. */
81 uint32_t screen_height;
82
83 /** Cell width in pixels. Must be non-zero. */
84 uint32_t cell_width;
85
86 /** Cell height in pixels. Must be non-zero. */
87 uint32_t cell_height;
88
89 /** Top padding in pixels. */
90 uint32_t padding_top;
91
92 /** Bottom padding in pixels. */
93 uint32_t padding_bottom;
94
95 /** Right padding in pixels. */
96 uint32_t padding_right;
97
98 /** Left padding in pixels. */
99 uint32_t padding_left;
100} GhosttyMouseEncoderSize;
101
102/**
103 * Mouse encoder option identifiers.
104 *
105 * These values are used with ghostty_mouse_encoder_setopt() to configure
106 * the behavior of the mouse encoder.
107 *
108 * @ingroup mouse
109 */
110typedef enum GHOSTTY_ENUM_TYPED {
111 /** Mouse tracking mode (value: GhosttyMouseTrackingMode). */
112 GHOSTTY_MOUSE_ENCODER_OPT_EVENT = 0,
113
114 /** Mouse output format (value: GhosttyMouseFormat). */
115 GHOSTTY_MOUSE_ENCODER_OPT_FORMAT = 1,
116
117 /** Renderer size context (value: GhosttyMouseEncoderSize). */
118 GHOSTTY_MOUSE_ENCODER_OPT_SIZE = 2,
119
120 /** Whether any mouse button is currently pressed (value: bool). */
121 GHOSTTY_MOUSE_ENCODER_OPT_ANY_BUTTON_PRESSED = 3,
122
123 /** Whether to enable motion deduplication by last cell (value: bool). */
124 GHOSTTY_MOUSE_ENCODER_OPT_TRACK_LAST_CELL = 4,
125 GHOSTTY_MOUSE_ENCODER_OPT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
126} GhosttyMouseEncoderOption;
127
128/**
129 * Create a new mouse encoder instance.
130 *
131 * @param allocator Pointer to allocator, or NULL to use the default allocator
132 * @param encoder Pointer to store the created encoder handle
133 * @return GHOSTTY_SUCCESS on success, or an error code on failure
134 *
135 * @ingroup mouse
136 */
137GHOSTTY_API GhosttyResult ghostty_mouse_encoder_new(const GhosttyAllocator *allocator,
138 GhosttyMouseEncoder *encoder);
139
140/**
141 * Free a mouse encoder instance.
142 *
143 * @param encoder The encoder handle to free (may be NULL)
144 *
145 * @ingroup mouse
146 */
147GHOSTTY_API void ghostty_mouse_encoder_free(GhosttyMouseEncoder encoder);
148
149/**
150 * Set an option on the mouse encoder.
151 *
152 * A null pointer value does nothing. It does not reset to defaults.
153 *
154 * @param encoder The encoder handle, must not be NULL
155 * @param option The option to set
156 * @param value Pointer to option value (type depends on option)
157 *
158 * @ingroup mouse
159 */
160GHOSTTY_API void ghostty_mouse_encoder_setopt(GhosttyMouseEncoder encoder,
161 GhosttyMouseEncoderOption option,
162 const void *value);
163
164/**
165 * Set encoder options from a terminal's current state.
166 *
167 * This sets tracking mode and output format from terminal state.
168 * It does not modify size or any-button state.
169 *
170 * @param encoder The encoder handle, must not be NULL
171 * @param terminal The terminal handle, must not be NULL
172 *
173 * @ingroup mouse
174 */
175GHOSTTY_API void ghostty_mouse_encoder_setopt_from_terminal(GhosttyMouseEncoder encoder,
176 GhosttyTerminal terminal);
177
178/**
179 * Reset internal encoder state.
180 *
181 * This clears motion deduplication state (last tracked cell).
182 *
183 * @param encoder The encoder handle (may be NULL)
184 *
185 * @ingroup mouse
186 */
187GHOSTTY_API void ghostty_mouse_encoder_reset(GhosttyMouseEncoder encoder);
188
189/**
190 * Encode a mouse event into a terminal escape sequence.
191 *
192 * Not all mouse events produce output. In such cases this returns
193 * GHOSTTY_SUCCESS with out_len set to 0.
194 *
195 * If the output buffer is too small, this returns GHOSTTY_OUT_OF_SPACE
196 * and out_len contains the required size.
197 *
198 * @param encoder The encoder handle, must not be NULL
199 * @param event The mouse event to encode, must not be NULL
200 * @param out_buf Buffer to write encoded bytes to, or NULL to query required size
201 * @param out_buf_size Size of out_buf in bytes
202 * @param out_len Pointer to store bytes written (or required bytes on failure)
203 * @return GHOSTTY_SUCCESS on success, GHOSTTY_OUT_OF_SPACE if buffer is too small,
204 * or another error code
205 *
206 * @ingroup mouse
207 */
208GHOSTTY_API GhosttyResult ghostty_mouse_encoder_encode(GhosttyMouseEncoder encoder,
209 GhosttyMouseEvent event,
210 char *out_buf,
211 size_t out_buf_size,
212 size_t *out_len);
213
214#endif /* GHOSTTY_VT_MOUSE_ENCODER_H */
native/libghostty-vt/include/ghostty/vt/mouse/event.h created+195
......@@ -0,0 +1,195 @@
1/**
2 * @file event.h
3 *
4 * Mouse event representation and manipulation.
5 */
6
7#ifndef GHOSTTY_VT_MOUSE_EVENT_H
8#define GHOSTTY_VT_MOUSE_EVENT_H
9
10#include <stdbool.h>
11#include <ghostty/vt/allocator.h>
12#include <ghostty/vt/key/event.h>
13#include <ghostty/vt/types.h>
14
15/**
16 * Opaque handle to a mouse event.
17 *
18 * This handle represents a normalized mouse input event containing
19 * action, button, modifiers, and surface-space position.
20 *
21 * @ingroup mouse
22 */
23typedef struct GhosttyMouseEventImpl *GhosttyMouseEvent;
24
25/**
26 * Mouse event action type.
27 *
28 * @ingroup mouse
29 */
30typedef enum GHOSTTY_ENUM_TYPED {
31 /** Mouse button was pressed. */
32 GHOSTTY_MOUSE_ACTION_PRESS = 0,
33
34 /** Mouse button was released. */
35 GHOSTTY_MOUSE_ACTION_RELEASE = 1,
36
37 /** Mouse moved. */
38 GHOSTTY_MOUSE_ACTION_MOTION = 2,
39 GHOSTTY_MOUSE_ACTION_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
40} GhosttyMouseAction;
41
42/**
43 * Mouse button identity.
44 *
45 * @ingroup mouse
46 */
47typedef enum GHOSTTY_ENUM_TYPED {
48 GHOSTTY_MOUSE_BUTTON_UNKNOWN = 0,
49 GHOSTTY_MOUSE_BUTTON_LEFT = 1,
50 GHOSTTY_MOUSE_BUTTON_RIGHT = 2,
51 GHOSTTY_MOUSE_BUTTON_MIDDLE = 3,
52 GHOSTTY_MOUSE_BUTTON_FOUR = 4,
53 GHOSTTY_MOUSE_BUTTON_FIVE = 5,
54 GHOSTTY_MOUSE_BUTTON_SIX = 6,
55 GHOSTTY_MOUSE_BUTTON_SEVEN = 7,
56 GHOSTTY_MOUSE_BUTTON_EIGHT = 8,
57 GHOSTTY_MOUSE_BUTTON_NINE = 9,
58 GHOSTTY_MOUSE_BUTTON_TEN = 10,
59 GHOSTTY_MOUSE_BUTTON_ELEVEN = 11,
60 GHOSTTY_MOUSE_BUTTON_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
61} GhosttyMouseButton;
62
63/**
64 * Mouse position in surface-space pixels.
65 *
66 * @ingroup mouse
67 */
68typedef struct {
69 float x;
70 float y;
71} GhosttyMousePosition;
72
73/**
74 * Create a new mouse event instance.
75 *
76 * @param allocator Pointer to allocator, or NULL to use the default allocator
77 * @param event Pointer to store the created event handle
78 * @return GHOSTTY_SUCCESS on success, or an error code on failure
79 *
80 * @ingroup mouse
81 */
82GHOSTTY_API GhosttyResult ghostty_mouse_event_new(const GhosttyAllocator *allocator,
83 GhosttyMouseEvent *event);
84
85/**
86 * Free a mouse event instance.
87 *
88 * @param event The mouse event handle to free (may be NULL)
89 *
90 * @ingroup mouse
91 */
92GHOSTTY_API void ghostty_mouse_event_free(GhosttyMouseEvent event);
93
94/**
95 * Set the event action.
96 *
97 * @param event The event handle, must not be NULL
98 * @param action The action to set
99 *
100 * @ingroup mouse
101 */
102GHOSTTY_API void ghostty_mouse_event_set_action(GhosttyMouseEvent event,
103 GhosttyMouseAction action);
104
105/**
106 * Get the event action.
107 *
108 * @param event The event handle, must not be NULL
109 * @return The event action
110 *
111 * @ingroup mouse
112 */
113GHOSTTY_API GhosttyMouseAction ghostty_mouse_event_get_action(GhosttyMouseEvent event);
114
115/**
116 * Set the event button.
117 *
118 * This sets a concrete button identity for the event.
119 * To represent "no button" (for motion events), use
120 * ghostty_mouse_event_clear_button().
121 *
122 * @param event The event handle, must not be NULL
123 * @param button The button to set
124 *
125 * @ingroup mouse
126 */
127GHOSTTY_API void ghostty_mouse_event_set_button(GhosttyMouseEvent event,
128 GhosttyMouseButton button);
129
130/**
131 * Clear the event button.
132 *
133 * This sets the event button to "none".
134 *
135 * @param event The event handle, must not be NULL
136 *
137 * @ingroup mouse
138 */
139GHOSTTY_API void ghostty_mouse_event_clear_button(GhosttyMouseEvent event);
140
141/**
142 * Get the event button.
143 *
144 * @param event The event handle, must not be NULL
145 * @param out_button Output pointer for the button value (may be NULL)
146 * @return true if a button is set, false if no button is set
147 *
148 * @ingroup mouse
149 */
150GHOSTTY_API bool ghostty_mouse_event_get_button(GhosttyMouseEvent event,
151 GhosttyMouseButton *out_button);
152
153/**
154 * Set keyboard modifiers held during the event.
155 *
156 * @param event The event handle, must not be NULL
157 * @param mods Modifier bitmask
158 *
159 * @ingroup mouse
160 */
161GHOSTTY_API void ghostty_mouse_event_set_mods(GhosttyMouseEvent event,
162 GhosttyMods mods);
163
164/**
165 * Get keyboard modifiers held during the event.
166 *
167 * @param event The event handle, must not be NULL
168 * @return Modifier bitmask
169 *
170 * @ingroup mouse
171 */
172GHOSTTY_API GhosttyMods ghostty_mouse_event_get_mods(GhosttyMouseEvent event);
173
174/**
175 * Set the event position in surface-space pixels.
176 *
177 * @param event The event handle, must not be NULL
178 * @param position The position to set
179 *
180 * @ingroup mouse
181 */
182GHOSTTY_API void ghostty_mouse_event_set_position(GhosttyMouseEvent event,
183 GhosttyMousePosition position);
184
185/**
186 * Get the event position in surface-space pixels.
187 *
188 * @param event The event handle, must not be NULL
189 * @return The current event position
190 *
191 * @ingroup mouse
192 */
193GHOSTTY_API GhosttyMousePosition ghostty_mouse_event_get_position(GhosttyMouseEvent event);
194
195#endif /* GHOSTTY_VT_MOUSE_EVENT_H */
native/libghostty-vt/include/ghostty/vt/osc.h created+215
......@@ -0,0 +1,215 @@
1/**
2 * @file osc.h
3 *
4 * OSC (Operating System Command) sequence parser and command handling.
5 */
6
7#ifndef GHOSTTY_VT_OSC_H
8#define GHOSTTY_VT_OSC_H
9
10#include <stdbool.h>
11#include <stddef.h>
12#include <stdint.h>
13#include <ghostty/vt/types.h>
14#include <ghostty/vt/allocator.h>
15
16/** @defgroup osc OSC Parser
17 *
18 * OSC (Operating System Command) sequence parser and command handling.
19 *
20 * The parser operates in a streaming fashion, processing input byte-by-byte
21 * to handle OSC sequences that may arrive in fragments across multiple reads.
22 * This interface makes it easy to integrate into most environments and avoids
23 * over-allocating buffers.
24 *
25 * ## Basic Usage
26 *
27 * 1. Create a parser instance with ghostty_osc_new()
28 * 2. Feed bytes to the parser using ghostty_osc_next()
29 * 3. Finalize parsing with ghostty_osc_end() to get the command
30 * 4. Query command type and extract data using ghostty_osc_command_type()
31 * and ghostty_osc_command_data()
32 * 5. Free the parser with ghostty_osc_free() when done
33 *
34 * @{
35 */
36
37/**
38 * OSC command types.
39 *
40 * @ingroup osc
41 */
42typedef enum GHOSTTY_ENUM_TYPED {
43 GHOSTTY_OSC_COMMAND_INVALID = 0,
44 GHOSTTY_OSC_COMMAND_CHANGE_WINDOW_TITLE = 1,
45 GHOSTTY_OSC_COMMAND_CHANGE_WINDOW_ICON = 2,
46 GHOSTTY_OSC_COMMAND_SEMANTIC_PROMPT = 3,
47 GHOSTTY_OSC_COMMAND_CLIPBOARD_CONTENTS = 4,
48 GHOSTTY_OSC_COMMAND_REPORT_PWD = 5,
49 GHOSTTY_OSC_COMMAND_MOUSE_SHAPE = 6,
50 GHOSTTY_OSC_COMMAND_COLOR_OPERATION = 7,
51 GHOSTTY_OSC_COMMAND_KITTY_COLOR_PROTOCOL = 8,
52 GHOSTTY_OSC_COMMAND_SHOW_DESKTOP_NOTIFICATION = 9,
53 GHOSTTY_OSC_COMMAND_HYPERLINK_START = 10,
54 GHOSTTY_OSC_COMMAND_HYPERLINK_END = 11,
55 GHOSTTY_OSC_COMMAND_CONEMU_SLEEP = 12,
56 GHOSTTY_OSC_COMMAND_CONEMU_SHOW_MESSAGE_BOX = 13,
57 GHOSTTY_OSC_COMMAND_CONEMU_CHANGE_TAB_TITLE = 14,
58 GHOSTTY_OSC_COMMAND_CONEMU_PROGRESS_REPORT = 15,
59 GHOSTTY_OSC_COMMAND_CONEMU_WAIT_INPUT = 16,
60 GHOSTTY_OSC_COMMAND_CONEMU_GUIMACRO = 17,
61 GHOSTTY_OSC_COMMAND_CONEMU_RUN_PROCESS = 18,
62 GHOSTTY_OSC_COMMAND_CONEMU_OUTPUT_ENVIRONMENT_VARIABLE = 19,
63 GHOSTTY_OSC_COMMAND_CONEMU_XTERM_EMULATION = 20,
64 GHOSTTY_OSC_COMMAND_CONEMU_COMMENT = 21,
65 GHOSTTY_OSC_COMMAND_KITTY_TEXT_SIZING = 22,
66 GHOSTTY_OSC_COMMAND_TYPE_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
67} GhosttyOscCommandType;
68
69/**
70 * OSC command data types.
71 *
72 * These values specify what type of data to extract from an OSC command
73 * using `ghostty_osc_command_data`.
74 *
75 * @ingroup osc
76 */
77typedef enum GHOSTTY_ENUM_TYPED {
78 /** Invalid data type. Never results in any data extraction. */
79 GHOSTTY_OSC_DATA_INVALID = 0,
80
81 /**
82 * Window title string data.
83 *
84 * Valid for: GHOSTTY_OSC_COMMAND_CHANGE_WINDOW_TITLE
85 *
86 * Output type: const char ** (pointer to null-terminated string)
87 *
88 * Lifetime: Valid until the next call to any ghostty_osc_* function with
89 * the same parser instance. Memory is owned by the parser.
90 */
91 GHOSTTY_OSC_DATA_CHANGE_WINDOW_TITLE_STR = 1,
92 GHOSTTY_OSC_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
93} GhosttyOscCommandData;
94
95/**
96 * Create a new OSC parser instance.
97 *
98 * Creates a new OSC (Operating System Command) parser using the provided
99 * allocator. The parser must be freed using ghostty_vt_osc_free() when
100 * no longer needed.
101 *
102 * @param allocator Pointer to the allocator to use for memory management, or NULL to use the default allocator
103 * @param parser Pointer to store the created parser handle
104 * @return GHOSTTY_SUCCESS on success, or an error code on failure
105 *
106 * @ingroup osc
107 */
108GHOSTTY_API GhosttyResult ghostty_osc_new(const GhosttyAllocator *allocator, GhosttyOscParser *parser);
109
110/**
111 * Free an OSC parser instance.
112 *
113 * Releases all resources associated with the OSC parser. After this call,
114 * the parser handle becomes invalid and must not be used.
115 *
116 * @param parser The parser handle to free (may be NULL)
117 *
118 * @ingroup osc
119 */
120GHOSTTY_API void ghostty_osc_free(GhosttyOscParser parser);
121
122/**
123 * Reset an OSC parser instance to its initial state.
124 *
125 * Resets the parser state, clearing any partially parsed OSC sequences
126 * and returning the parser to its initial state. This is useful for
127 * reusing a parser instance or recovering from parse errors.
128 *
129 * @param parser The parser handle to reset, must not be null.
130 *
131 * @ingroup osc
132 */
133GHOSTTY_API void ghostty_osc_reset(GhosttyOscParser parser);
134
135/**
136 * Parse the next byte in an OSC sequence.
137 *
138 * Processes a single byte as part of an OSC sequence. The parser maintains
139 * internal state to track the progress through the sequence. Call this
140 * function for each byte in the sequence data.
141 *
142 * When finished pumping the parser with bytes, call ghostty_osc_end
143 * to get the final result.
144 *
145 * @param parser The parser handle, must not be null.
146 * @param byte The next byte to parse
147 *
148 * @ingroup osc
149 */
150GHOSTTY_API void ghostty_osc_next(GhosttyOscParser parser, uint8_t byte);
151
152/**
153 * Finalize OSC parsing and retrieve the parsed command.
154 *
155 * Call this function after feeding all bytes of an OSC sequence to the parser
156 * using ghostty_osc_next() with the exception of the terminating character
157 * (ESC or ST). This function finalizes the parsing process and returns the
158 * parsed OSC command.
159 *
160 * The return value is never NULL. Invalid commands will return a command
161 * with type GHOSTTY_OSC_COMMAND_INVALID.
162 *
163 * The terminator parameter specifies the byte that terminated the OSC sequence
164 * (typically 0x07 for BEL or 0x5C for ST after ESC). This information is
165 * preserved in the parsed command so that responses can use the same terminator
166 * format for better compatibility with the calling program. For commands that
167 * do not require a response, this parameter is ignored and the resulting
168 * command will not retain the terminator information.
169 *
170 * The returned command handle is valid until the next call to any
171 * `ghostty_osc_*` function with the same parser instance with the exception
172 * of command introspection functions such as `ghostty_osc_command_type`.
173 *
174 * @param parser The parser handle, must not be null.
175 * @param terminator The terminating byte of the OSC sequence (0x07 for BEL, 0x5C for ST)
176 * @return Handle to the parsed OSC command
177 *
178 * @ingroup osc
179 */
180GHOSTTY_API GhosttyOscCommand ghostty_osc_end(GhosttyOscParser parser, uint8_t terminator);
181
182/**
183 * Get the type of an OSC command.
184 *
185 * Returns the type identifier for the given OSC command. This can be used
186 * to determine what kind of command was parsed and what data might be
187 * available from it.
188 *
189 * @param command The OSC command handle to query (may be NULL)
190 * @return The command type, or GHOSTTY_OSC_COMMAND_INVALID if command is NULL
191 *
192 * @ingroup osc
193 */
194GHOSTTY_API GhosttyOscCommandType ghostty_osc_command_type(GhosttyOscCommand command);
195
196/**
197 * Extract data from an OSC command.
198 *
199 * Extracts typed data from the given OSC command based on the specified
200 * data type. The output pointer must be of the appropriate type for the
201 * requested data kind. Valid command types, output types, and memory
202 * safety information are documented in the `GhosttyOscCommandData` enum.
203 *
204 * @param command The OSC command handle to query (may be NULL)
205 * @param data The type of data to extract
206 * @param out Pointer to store the extracted data (type depends on data parameter)
207 * @return true if data extraction was successful, false otherwise
208 *
209 * @ingroup osc
210 */
211GHOSTTY_API bool ghostty_osc_command_data(GhosttyOscCommand command, GhosttyOscCommandData data, void *out);
212
213/** @} */
214
215#endif /* GHOSTTY_VT_OSC_H */
native/libghostty-vt/include/ghostty/vt/paste.h created+101
......@@ -0,0 +1,101 @@
1/**
2 * @file paste.h
3 *
4 * Paste utilities - validate and encode paste data for terminal input.
5 */
6
7#ifndef GHOSTTY_VT_PASTE_H
8#define GHOSTTY_VT_PASTE_H
9
10/** @defgroup paste Paste Utilities
11 *
12 * Utilities for validating and encoding paste data for terminal input.
13 *
14 * ## Basic Usage
15 *
16 * Use ghostty_paste_is_safe() to check if paste data contains potentially
17 * dangerous sequences before sending it to the terminal.
18 *
19 * Use ghostty_paste_encode() to encode paste data for writing to the pty,
20 * including bracketed paste wrapping and unsafe byte stripping.
21 *
22 * ## Examples
23 *
24 * ### Safety Check
25 *
26 * @snippet c-vt-paste/src/main.c paste-safety
27 *
28 * ### Encoding
29 *
30 * @snippet c-vt-paste/src/main.c paste-encode
31 *
32 * @{
33 */
34
35#include <stdbool.h>
36#include <stddef.h>
37#include <ghostty/vt/types.h>
38
39#ifdef __cplusplus
40extern "C" {
41#endif
42
43/**
44 * Check if paste data is safe to paste into the terminal.
45 *
46 * Data is considered unsafe if it contains:
47 * - Newlines (`\n`) which can inject commands
48 * - The bracketed paste end sequence (`\x1b[201~`) which can be used
49 * to exit bracketed paste mode and inject commands
50 *
51 * This check is conservative and considers data unsafe regardless of
52 * current terminal state.
53 *
54 * @param data The paste data to check (must not be NULL)
55 * @param len The length of the data in bytes
56 * @return true if the data is safe to paste, false otherwise
57 */
58GHOSTTY_API bool ghostty_paste_is_safe(const char* data, size_t len);
59
60/**
61 * Encode paste data for writing to the terminal pty.
62 *
63 * This function prepares paste data for terminal input by:
64 * - Stripping unsafe control bytes (NUL, ESC, DEL, etc.) by replacing
65 * them with spaces
66 * - Wrapping the data in bracketed paste sequences if @p bracketed is true
67 * - Replacing newlines with carriage returns if @p bracketed is false
68 *
69 * The input @p data buffer is modified in place during encoding. The
70 * encoded result (potentially with bracketed paste prefix/suffix) is
71 * written to the output buffer.
72 *
73 * If the output buffer is too small, the function returns
74 * GHOSTTY_OUT_OF_SPACE and sets the required size in @p out_written.
75 * The caller can then retry with a sufficiently sized buffer.
76 *
77 * @param data The paste data to encode (modified in place, may be NULL)
78 * @param data_len The length of the input data in bytes
79 * @param bracketed Whether bracketed paste mode is active
80 * @param buf Output buffer to write the encoded result into (may be NULL)
81 * @param buf_len Size of the output buffer in bytes
82 * @param[out] out_written On success, the number of bytes written. On
83 * GHOSTTY_OUT_OF_SPACE, the required buffer size.
84 * @return GHOSTTY_SUCCESS on success, GHOSTTY_OUT_OF_SPACE if the buffer
85 * is too small
86 */
87GHOSTTY_API GhosttyResult ghostty_paste_encode(
88 char* data,
89 size_t data_len,
90 bool bracketed,
91 char* buf,
92 size_t buf_len,
93 size_t* out_written);
94
95#ifdef __cplusplus
96}
97#endif
98
99/** @} */
100
101#endif /* GHOSTTY_VT_PASTE_H */
native/libghostty-vt/include/ghostty/vt/point.h created+89
......@@ -0,0 +1,89 @@
1/**
2 * @file point.h
3 *
4 * Terminal point types for referencing locations in the terminal grid.
5 */
6
7#ifndef GHOSTTY_VT_POINT_H
8#define GHOSTTY_VT_POINT_H
9
10#include <stdint.h>
11
12#ifdef __cplusplus
13extern "C" {
14#endif
15
16/** @defgroup point Point
17 *
18 * Types for referencing x/y positions in the terminal grid under
19 * different coordinate systems (active area, viewport, full screen,
20 * scrollback history).
21 *
22 * @{
23 */
24
25/**
26 * A coordinate in the terminal grid.
27 *
28 * @ingroup point
29 */
30typedef struct {
31 /** Column (0-indexed). */
32 uint16_t x;
33
34 /** Row (0-indexed). May exceed page size for screen/history tags. */
35 uint32_t y;
36} GhosttyPointCoordinate;
37
38/**
39 * Point reference tag.
40 *
41 * Determines which coordinate system a point uses.
42 *
43 * @ingroup point
44 */
45typedef enum GHOSTTY_ENUM_TYPED {
46 /** Active area where the cursor can move. */
47 GHOSTTY_POINT_TAG_ACTIVE = 0,
48
49 /** Visible viewport (changes when scrolled). */
50 GHOSTTY_POINT_TAG_VIEWPORT = 1,
51
52 /** Full screen including scrollback. */
53 GHOSTTY_POINT_TAG_SCREEN = 2,
54
55 /** Scrollback history only (before active area). */
56 GHOSTTY_POINT_TAG_HISTORY = 3,
57 GHOSTTY_POINT_TAG_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
58 } GhosttyPointTag;
59
60/**
61 * Point value union.
62 *
63 * @ingroup point
64 */
65typedef union {
66 /** Coordinate (used for all tag variants). */
67 GhosttyPointCoordinate coordinate;
68
69 /** Padding for ABI compatibility. Do not use. */
70 uint64_t _padding[2];
71} GhosttyPointValue;
72
73/**
74 * Tagged union for a point in the terminal grid.
75 *
76 * @ingroup point
77 */
78typedef struct {
79 GhosttyPointTag tag;
80 GhosttyPointValue value;
81} GhosttyPoint;
82
83/** @} */
84
85#ifdef __cplusplus
86}
87#endif
88
89#endif /* GHOSTTY_VT_POINT_H */
native/libghostty-vt/include/ghostty/vt/render.h created+729
......@@ -0,0 +1,729 @@
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
19extern "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 * ## Dirty Tracking
43 *
44 * Dirty tracking is a key feature of the render state that allows renderers
45 * to efficiently determine what parts of the screen have changed and only
46 * redraw changed regions.
47 *
48 * The render state API keeps track of dirty state at two independent layers:
49 * a global dirty state that indicates whether the entire frame is clean,
50 * partially dirty, or fully dirty, and a per-row dirty state that allows
51 * tracking which rows in a partially dirty frame have changed.
52 *
53 * The user of the render state API is expected to unset both of these.
54 * The `update` call does not unset dirty state, it only updates it.
55 *
56 * An extremely important detail: setting one dirty state doesn't unset
57 * the other. For example, setting the global dirty state to false does not
58 * reset the row-level dirty flags. So, the caller of the render state API must
59 * be careful to manage both layers of dirty state correctly.
60 *
61 * ## Examples
62 *
63 * ### Creating and updating render state
64 * @snippet c-vt-render/src/main.c render-state-update
65 *
66 * ### Checking dirty state
67 * @snippet c-vt-render/src/main.c render-dirty-check
68 *
69 * ### Reading colors
70 * @snippet c-vt-render/src/main.c render-colors
71 *
72 * ### Reading cursor state
73 * @snippet c-vt-render/src/main.c render-cursor
74 *
75 * ### Iterating rows and cells
76 * @snippet c-vt-render/src/main.c render-row-iterate
77 *
78 * ### Resetting dirty state after rendering
79 * @snippet c-vt-render/src/main.c render-dirty-reset
80 *
81 * @{
82 */
83
84/**
85 * Dirty state of a render state after update.
86 *
87 * @ingroup render
88 */
89typedef enum GHOSTTY_ENUM_TYPED {
90 /** Not dirty at all; rendering can be skipped. */
91 GHOSTTY_RENDER_STATE_DIRTY_FALSE = 0,
92
93 /** Some rows changed; renderer can redraw incrementally. */
94 GHOSTTY_RENDER_STATE_DIRTY_PARTIAL = 1,
95
96 /** Global state changed; renderer should redraw everything. */
97 GHOSTTY_RENDER_STATE_DIRTY_FULL = 2,
98 GHOSTTY_RENDER_STATE_DIRTY_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
99} GhosttyRenderStateDirty;
100
101/**
102 * Visual style of the cursor.
103 *
104 * @ingroup render
105 */
106typedef enum GHOSTTY_ENUM_TYPED {
107 /** Bar cursor (DECSCUSR 5, 6). */
108 GHOSTTY_RENDER_STATE_CURSOR_VISUAL_STYLE_BAR = 0,
109
110 /** Block cursor (DECSCUSR 1, 2). */
111 GHOSTTY_RENDER_STATE_CURSOR_VISUAL_STYLE_BLOCK = 1,
112
113 /** Underline cursor (DECSCUSR 3, 4). */
114 GHOSTTY_RENDER_STATE_CURSOR_VISUAL_STYLE_UNDERLINE = 2,
115
116 /** Hollow block cursor. */
117 GHOSTTY_RENDER_STATE_CURSOR_VISUAL_STYLE_BLOCK_HOLLOW = 3,
118 GHOSTTY_RENDER_STATE_CURSOR_VISUAL_STYLE_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
119} GhosttyRenderStateCursorVisualStyle;
120
121/**
122 * Queryable data kinds for ghostty_render_state_get().
123 *
124 * @ingroup render
125 */
126typedef enum GHOSTTY_ENUM_TYPED {
127 /** Invalid / sentinel value. */
128 GHOSTTY_RENDER_STATE_DATA_INVALID = 0,
129
130 /** Viewport width in cells (uint16_t). */
131 GHOSTTY_RENDER_STATE_DATA_COLS = 1,
132
133 /** Viewport height in cells (uint16_t). */
134 GHOSTTY_RENDER_STATE_DATA_ROWS = 2,
135
136 /** Current dirty state (GhosttyRenderStateDirty). */
137 GHOSTTY_RENDER_STATE_DATA_DIRTY = 3,
138
139 /** Populate a pre-allocated GhosttyRenderStateRowIterator with row data
140 * from the render state (GhosttyRenderStateRowIterator). Row data is
141 * only valid as long as the underlying render state is not updated.
142 * It is unsafe to use row data after updating the render state.
143 * */
144 GHOSTTY_RENDER_STATE_DATA_ROW_ITERATOR = 4,
145
146 /** Default/current background color (GhosttyColorRgb). */
147 GHOSTTY_RENDER_STATE_DATA_COLOR_BACKGROUND = 5,
148
149 /** Default/current foreground color (GhosttyColorRgb). */
150 GHOSTTY_RENDER_STATE_DATA_COLOR_FOREGROUND = 6,
151
152 /** Cursor color when explicitly set by terminal state (GhosttyColorRgb).
153 * Returns GHOSTTY_INVALID_VALUE if no explicit cursor color is set;
154 * use COLOR_CURSOR_HAS_VALUE to check first. */
155 GHOSTTY_RENDER_STATE_DATA_COLOR_CURSOR = 7,
156
157 /** Whether an explicit cursor color is set (bool). */
158 GHOSTTY_RENDER_STATE_DATA_COLOR_CURSOR_HAS_VALUE = 8,
159
160 /** The active 256-color palette (GhosttyColorRgb[256]). */
161 GHOSTTY_RENDER_STATE_DATA_COLOR_PALETTE = 9,
162
163 /** The visual style of the cursor (GhosttyRenderStateCursorVisualStyle). */
164 GHOSTTY_RENDER_STATE_DATA_CURSOR_VISUAL_STYLE = 10,
165
166 /** Whether the cursor is visible based on terminal modes (bool). */
167 GHOSTTY_RENDER_STATE_DATA_CURSOR_VISIBLE = 11,
168
169 /** Whether the cursor should blink based on terminal modes (bool). */
170 GHOSTTY_RENDER_STATE_DATA_CURSOR_BLINKING = 12,
171
172 /** Whether the cursor is at a password input field (bool). */
173 GHOSTTY_RENDER_STATE_DATA_CURSOR_PASSWORD_INPUT = 13,
174
175 /** Whether the cursor is visible within the viewport (bool).
176 * If false, the cursor viewport position values are undefined. */
177 GHOSTTY_RENDER_STATE_DATA_CURSOR_VIEWPORT_HAS_VALUE = 14,
178
179 /** Cursor viewport x position in cells (uint16_t).
180 * Only valid when CURSOR_VIEWPORT_HAS_VALUE is true. */
181 GHOSTTY_RENDER_STATE_DATA_CURSOR_VIEWPORT_X = 15,
182
183 /** Cursor viewport y position in cells (uint16_t).
184 * Only valid when CURSOR_VIEWPORT_HAS_VALUE is true. */
185 GHOSTTY_RENDER_STATE_DATA_CURSOR_VIEWPORT_Y = 16,
186
187 /** Whether the cursor is on the tail of a wide character (bool).
188 * Only valid when CURSOR_VIEWPORT_HAS_VALUE is true. */
189 GHOSTTY_RENDER_STATE_DATA_CURSOR_VIEWPORT_WIDE_TAIL = 17,
190 GHOSTTY_RENDER_STATE_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
191} GhosttyRenderStateData;
192
193/**
194 * Settable options for ghostty_render_state_set().
195 *
196 * @ingroup render
197 */
198typedef enum GHOSTTY_ENUM_TYPED {
199 /** Set dirty state (GhosttyRenderStateDirty). */
200 GHOSTTY_RENDER_STATE_OPTION_DIRTY = 0,
201 GHOSTTY_RENDER_STATE_OPTION_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
202} GhosttyRenderStateOption;
203
204/**
205 * Queryable data kinds for ghostty_render_state_row_get().
206 *
207 * @ingroup render
208 */
209typedef enum GHOSTTY_ENUM_TYPED {
210 /** Invalid / sentinel value. */
211 GHOSTTY_RENDER_STATE_ROW_DATA_INVALID = 0,
212
213 /** Whether the current row is dirty (bool). */
214 GHOSTTY_RENDER_STATE_ROW_DATA_DIRTY = 1,
215
216 /** The raw row value (GhosttyRow). */
217 GHOSTTY_RENDER_STATE_ROW_DATA_RAW = 2,
218
219 /** Populate a pre-allocated GhosttyRenderStateRowCells with cell data for
220 * the current row (GhosttyRenderStateRowCells). Cell data is only
221 * valid as long as the underlying render state is not updated.
222 * It is unsafe to use cell data after updating the render state. */
223 GHOSTTY_RENDER_STATE_ROW_DATA_CELLS = 3,
224
225 /** Row-local selected cell range (GhosttyRenderStateRowSelection). */
226 GHOSTTY_RENDER_STATE_ROW_DATA_SELECTION = 4,
227 GHOSTTY_RENDER_STATE_ROW_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
228} GhosttyRenderStateRowData;
229
230/**
231 * Settable options for ghostty_render_state_row_set().
232 *
233 * @ingroup render
234 */
235typedef enum GHOSTTY_ENUM_TYPED {
236 /** Set dirty state for the current row (bool). */
237 GHOSTTY_RENDER_STATE_ROW_OPTION_DIRTY = 0,
238 GHOSTTY_RENDER_STATE_ROW_OPTION_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
239} GhosttyRenderStateRowOption;
240
241/**
242 * Row-local selection range.
243 *
244 * This struct uses the sized-struct ABI pattern. Initialize with
245 * GHOSTTY_INIT_SIZED(GhosttyRenderStateRowSelection) before querying
246 * GHOSTTY_RENDER_STATE_ROW_DATA_SELECTION.
247 *
248 * Querying GHOSTTY_RENDER_STATE_ROW_DATA_SELECTION returns GHOSTTY_NO_VALUE
249 * if the current row does not intersect the current selection.
250 *
251 * @ingroup render
252 */
253typedef struct {
254 /** Size of this struct in bytes. Must be set to sizeof(GhosttyRenderStateRowSelection). */
255 size_t size;
256
257 /** Start column of the row-local selection range, inclusive. */
258 uint16_t start_x;
259
260 /** End column of the row-local selection range, inclusive. */
261 uint16_t end_x;
262} GhosttyRenderStateRowSelection;
263
264/**
265 * Render-state color information.
266 *
267 * This struct uses the sized-struct ABI pattern. Initialize with
268 * GHOSTTY_INIT_SIZED(GhosttyRenderStateColors) before calling
269 * ghostty_render_state_colors_get().
270 *
271 * Example:
272 * @code
273 * GhosttyRenderStateColors colors = GHOSTTY_INIT_SIZED(GhosttyRenderStateColors);
274 * GhosttyResult result = ghostty_render_state_colors_get(state, &colors);
275 * @endcode
276 *
277 * @ingroup render
278 */
279typedef struct {
280 /** Size of this struct in bytes. Must be set to sizeof(GhosttyRenderStateColors). */
281 size_t size;
282
283 /** The default/current background color for the render state. */
284 GhosttyColorRgb background;
285
286 /** The default/current foreground color for the render state. */
287 GhosttyColorRgb foreground;
288
289 /** The cursor color when explicitly set by terminal state. */
290 GhosttyColorRgb cursor;
291
292 /**
293 * True when cursor contains a valid explicit cursor color value.
294 * If this is false, the cursor color should be ignored; it will
295 * contain undefined data.
296 * */
297 bool cursor_has_value;
298
299 /** The active 256-color palette for this render state. */
300 GhosttyColorRgb palette[256];
301} GhosttyRenderStateColors;
302
303/**
304 * Create a new render state instance.
305 *
306 * @param allocator Pointer to allocator, or NULL to use the default allocator
307 * @param state Pointer to store the created render state handle
308 * @return GHOSTTY_SUCCESS on success, GHOSTTY_OUT_OF_MEMORY on allocation
309 * failure
310 *
311 * @ingroup render
312 */
313GHOSTTY_API GhosttyResult ghostty_render_state_new(const GhosttyAllocator* allocator,
314 GhosttyRenderState* state);
315
316/**
317 * Free a render state instance.
318 *
319 * Releases all resources associated with the render state. After this call,
320 * the render state handle becomes invalid.
321 *
322 * @param state The render state handle to free (may be NULL)
323 *
324 * @ingroup render
325 */
326GHOSTTY_API void ghostty_render_state_free(GhosttyRenderState state);
327
328/**
329 * Update a render state instance from a terminal.
330 *
331 * This consumes terminal/screen dirty state in the same way as the internal
332 * render state update path.
333 *
334 * @param state The render state handle (NULL returns GHOSTTY_INVALID_VALUE)
335 * @param terminal The terminal handle to read from (NULL returns GHOSTTY_INVALID_VALUE)
336 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if `state` or
337 * `terminal` is NULL, GHOSTTY_OUT_OF_MEMORY if updating the state requires
338 * allocation and that allocation fails
339 *
340 * @ingroup render
341 */
342GHOSTTY_API GhosttyResult ghostty_render_state_update(GhosttyRenderState state,
343 GhosttyTerminal terminal);
344
345/**
346 * Get a value from a render state.
347 *
348 * The `out` pointer must point to a value of the type corresponding to the
349 * requested data kind (see GhosttyRenderStateData).
350 *
351 * @param state The render state handle (NULL returns GHOSTTY_INVALID_VALUE)
352 * @param data The data kind to query
353 * @param[out] out Pointer to receive the queried value
354 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if `state` is
355 * NULL or `data` is not a recognized enum value
356 *
357 * @ingroup render
358 */
359GHOSTTY_API GhosttyResult ghostty_render_state_get(GhosttyRenderState state,
360 GhosttyRenderStateData data,
361 void* out);
362
363/**
364 * Get multiple data fields from a render state in a single call.
365 *
366 * Each element in the keys array specifies a data kind, and the
367 * corresponding element in the values array receives the result.
368 *
369 * Processing stops at the first error; on success out_written
370 * is set to count, on error it is set to the index of the
371 * failing key (i.e. the number of values successfully written).
372 *
373 * @param state The render state handle (NULL returns GHOSTTY_INVALID_VALUE)
374 * @param count Number of key/value pairs
375 * @param keys Array of data kinds to query
376 * @param values Array of output pointers (types must match each key's
377 * documented output type)
378 * @param[out] out_written On return, receives the number of values
379 * successfully written (may be NULL)
380 * @return GHOSTTY_SUCCESS if all queries succeed
381 *
382 * @ingroup render
383 */
384GHOSTTY_API GhosttyResult ghostty_render_state_get_multi(
385 GhosttyRenderState state,
386 size_t count,
387 const GhosttyRenderStateData* keys,
388 void** values,
389 size_t* out_written);
390
391/**
392 * Set an option on a render state.
393 *
394 * The `value` pointer must point to a value of the type corresponding to the
395 * requested option kind (see GhosttyRenderStateOption).
396 *
397 * @param state The render state handle (NULL returns GHOSTTY_INVALID_VALUE)
398 * @param option The option to set
399 * @param[in] value Pointer to the value to set (NULL returns
400 * GHOSTTY_INVALID_VALUE)
401 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if `state` or
402 * `value` is NULL
403 *
404 * @ingroup render
405 */
406GHOSTTY_API GhosttyResult ghostty_render_state_set(GhosttyRenderState state,
407 GhosttyRenderStateOption option,
408 const void* value);
409
410/**
411 * Get the current color information from a render state.
412 *
413 * This writes as many fields as fit in the caller-provided sized struct.
414 * `out_colors->size` must be set by the caller (typically via
415 * GHOSTTY_INIT_SIZED(GhosttyRenderStateColors)).
416 *
417 * @param state The render state handle (NULL returns GHOSTTY_INVALID_VALUE)
418 * @param[out] out_colors Sized output struct to receive render-state colors
419 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if `state` or
420 * `out_colors` is NULL, or if `out_colors->size` is smaller than
421 * `sizeof(size_t)`
422 *
423 * @ingroup render
424 */
425GHOSTTY_API GhosttyResult ghostty_render_state_colors_get(GhosttyRenderState state,
426 GhosttyRenderStateColors* out_colors);
427
428/**
429 * Create a new row iterator instance.
430 *
431 * All fields except the allocator are left undefined until populated
432 * via ghostty_render_state_get() with
433 * GHOSTTY_RENDER_STATE_DATA_ROW_ITERATOR.
434 *
435 * @param allocator Pointer to allocator, or NULL to use the default allocator
436 * @param[out] out_iterator On success, receives the created iterator handle
437 * @return GHOSTTY_SUCCESS on success, GHOSTTY_OUT_OF_MEMORY on allocation
438 * failure
439 *
440 * @ingroup render
441 */
442GHOSTTY_API GhosttyResult ghostty_render_state_row_iterator_new(
443 const GhosttyAllocator* allocator,
444 GhosttyRenderStateRowIterator* out_iterator);
445
446/**
447 * Free a render-state row iterator.
448 *
449 * @param iterator The iterator handle to free (may be NULL)
450 *
451 * @ingroup render
452 */
453GHOSTTY_API void ghostty_render_state_row_iterator_free(GhosttyRenderStateRowIterator iterator);
454
455/**
456 * Move a render-state row iterator to the next row.
457 *
458 * Returns true if the iterator moved successfully and row data is
459 * available to read at the new position.
460 *
461 * @param iterator The iterator handle to advance (may be NULL)
462 * @return true if advanced to the next row, false if `iterator` is
463 * NULL or if the iterator has reached the end
464 *
465 * @ingroup render
466 */
467GHOSTTY_API bool ghostty_render_state_row_iterator_next(GhosttyRenderStateRowIterator iterator);
468
469/**
470 * Get a value from the current row in a render-state row iterator.
471 *
472 * The `out` pointer must point to a value of the type corresponding to the
473 * requested data kind (see GhosttyRenderStateRowData).
474 * Call ghostty_render_state_row_iterator_next() at least once before
475 * calling this function.
476 *
477 * @param iterator The iterator handle to query (NULL returns GHOSTTY_INVALID_VALUE)
478 * @param data The data kind to query
479 * @param[out] out Pointer to receive the queried value
480 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if
481 * `iterator` is NULL or the iterator is not positioned on a row
482 *
483 * @ingroup render
484 */
485GHOSTTY_API GhosttyResult ghostty_render_state_row_get(
486 GhosttyRenderStateRowIterator iterator,
487 GhosttyRenderStateRowData data,
488 void* out);
489
490/**
491 * Get multiple data fields from the current row in a single call.
492 *
493 * Each element in the keys array specifies a data kind, and the
494 * corresponding element in the values array receives the result.
495 *
496 * Processing stops at the first error; on success out_written
497 * is set to count, on error it is set to the index of the
498 * failing key (i.e. the number of values successfully written).
499 *
500 * @param iterator The iterator handle (NULL returns GHOSTTY_INVALID_VALUE)
501 * @param count Number of key/value pairs
502 * @param keys Array of data kinds to query
503 * @param values Array of output pointers (types must match each key's
504 * documented output type)
505 * @param[out] out_written On return, receives the number of values
506 * successfully written (may be NULL)
507 * @return GHOSTTY_SUCCESS if all queries succeed
508 *
509 * @ingroup render
510 */
511GHOSTTY_API GhosttyResult ghostty_render_state_row_get_multi(
512 GhosttyRenderStateRowIterator iterator,
513 size_t count,
514 const GhosttyRenderStateRowData* keys,
515 void** values,
516 size_t* out_written);
517
518/**
519 * Set an option on the current row in a render-state row iterator.
520 *
521 * The `value` pointer must point to a value of the type corresponding to the
522 * requested option kind (see GhosttyRenderStateRowOption).
523 * Call ghostty_render_state_row_iterator_next() at least once before
524 * calling this function.
525 *
526 * @param iterator The iterator handle to update (NULL returns GHOSTTY_INVALID_VALUE)
527 * @param option The option to set
528 * @param[in] value Pointer to the value to set (NULL returns
529 * GHOSTTY_INVALID_VALUE)
530 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if
531 * `iterator` is NULL or the iterator is not positioned on a row
532 *
533 * @ingroup render
534 */
535GHOSTTY_API GhosttyResult ghostty_render_state_row_set(
536 GhosttyRenderStateRowIterator iterator,
537 GhosttyRenderStateRowOption option,
538 const void* value);
539
540/**
541 * Create a new row cells instance.
542 *
543 * All fields except the allocator are left undefined until populated
544 * via ghostty_render_state_row_get() with
545 * GHOSTTY_RENDER_STATE_ROW_DATA_CELLS.
546 *
547 * You can reuse this value repeatedly with ghostty_render_state_row_get() to
548 * avoid allocating a new cells container for every row.
549 *
550 * @param allocator Pointer to allocator, or NULL to use the default allocator
551 * @param[out] out_cells On success, receives the created row cells handle
552 * @return GHOSTTY_SUCCESS on success, GHOSTTY_OUT_OF_MEMORY on allocation
553 * failure
554 *
555 * @ingroup render
556 */
557GHOSTTY_API GhosttyResult ghostty_render_state_row_cells_new(
558 const GhosttyAllocator* allocator,
559 GhosttyRenderStateRowCells* out_cells);
560
561/**
562 * Queryable data kinds for ghostty_render_state_row_cells_get().
563 *
564 * @ingroup render
565 */
566typedef enum GHOSTTY_ENUM_TYPED {
567 /** Invalid / sentinel value. */
568 GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_INVALID = 0,
569
570 /** The raw cell value (GhosttyCell). */
571 GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_RAW = 1,
572
573 /** The style for the current cell (GhosttyStyle). */
574 GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_STYLE = 2,
575
576 /** The total number of grapheme codepoints including the base codepoint
577 * (uint32_t). Returns 0 if the cell has no text. */
578 GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_GRAPHEMES_LEN = 3,
579
580 /** Write grapheme codepoints into a caller-provided buffer (uint32_t*).
581 * The buffer must be at least graphemes_len elements. The base codepoint
582 * is written first, followed by any extra codepoints. */
583 GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_GRAPHEMES_BUF = 4,
584
585 /** The resolved background color of the cell (GhosttyColorRgb).
586 * Flattens the three possible sources: content-tag bg_color_rgb,
587 * content-tag bg_color_palette (looked up in the palette), or the
588 * style's bg_color. Returns GHOSTTY_INVALID_VALUE if the cell has
589 * no background color, in which case the caller should use whatever
590 * default background color it wants (e.g. the terminal background). */
591 GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_BG_COLOR = 5,
592
593 /** The resolved foreground color of the cell (GhosttyColorRgb).
594 * Resolves palette indices through the palette. Bold color handling
595 * is not applied; the caller should handle bold styling separately.
596 * Returns GHOSTTY_INVALID_VALUE if the cell has no explicit foreground
597 * color, in which case the caller should use whatever default foreground
598 * color it wants (e.g. the terminal foreground). */
599 GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_FG_COLOR = 6,
600
601 /** Whether the cell is contained within the current selection (bool).
602 * This returns true when the cell's column is within the current row's
603 * row-local selection range, and false otherwise. Rendering policy for
604 * selected cells (colors, inversion, etc.) is left to the caller.
605 *
606 * Renderers that can draw cells in spans may be more efficient querying
607 * GHOSTTY_RENDER_STATE_ROW_DATA_SELECTION once per row and applying that
608 * range directly, avoiding one C API call per cell for selection state. */
609 GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_SELECTED = 7,
610
611 /** Whether the cell has any explicit styling (bool).
612 * This is equivalent to querying the raw cell's
613 * GHOSTTY_CELL_DATA_HAS_STYLING value, but avoids materializing the raw
614 * GhosttyCell for renderers that only need to know whether fetching the
615 * full style is necessary. */
616 GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_HAS_STYLING = 8,
617
618 /**
619 * Encode the current cell's full grapheme cluster as UTF-8 into a
620 * caller-provided buffer (GhosttyBuffer).
621 *
622 * The base codepoint is encoded first, followed by any extra grapheme
623 * codepoints. Returns GHOSTTY_SUCCESS with len=0 when the cell has no text.
624 *
625 * If ptr is NULL or cap is too small for a non-empty cell, returns
626 * GHOSTTY_OUT_OF_SPACE without writing any bytes and sets len to the required
627 * buffer size in bytes.
628 */
629 GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_GRAPHEMES_UTF8 = 9,
630 GHOSTTY_RENDER_STATE_ROW_CELLS_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
631} GhosttyRenderStateRowCellsData;
632
633/**
634 * Move a render-state row cells iterator to the next cell.
635 *
636 * Returns true if the iterator moved successfully and cell data is
637 * available to read at the new position.
638 *
639 * @param cells The row cells handle to advance (may be NULL)
640 * @return true if advanced to the next cell, false if `cells` is
641 * NULL or if the iterator has reached the end
642 *
643 * @ingroup render
644 */
645GHOSTTY_API bool ghostty_render_state_row_cells_next(GhosttyRenderStateRowCells cells);
646
647/**
648 * Move a render-state row cells iterator to a specific column.
649 *
650 * Positions the iterator at the given x (column) index so that
651 * subsequent reads return data for that cell.
652 *
653 * @param cells The row cells handle to reposition (NULL returns
654 * GHOSTTY_INVALID_VALUE)
655 * @param x The zero-based column index to select
656 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if `cells`
657 * is NULL or `x` is out of range
658 *
659 * @ingroup render
660 */
661GHOSTTY_API GhosttyResult ghostty_render_state_row_cells_select(
662 GhosttyRenderStateRowCells cells, uint16_t x);
663
664/**
665 * Get a value from the current cell in a render-state row cells iterator.
666 *
667 * The `out` pointer must point to a value of the type corresponding to the
668 * requested data kind (see GhosttyRenderStateRowCellsData).
669 * Call ghostty_render_state_row_cells_next() or
670 * ghostty_render_state_row_cells_select() at least once before
671 * calling this function.
672 *
673 * @param cells The row cells handle to query (NULL returns GHOSTTY_INVALID_VALUE)
674 * @param data The data kind to query
675 * @param[out] out Pointer to receive the queried value
676 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if
677 * `cells` is NULL or the iterator is not positioned on a cell
678 *
679 * @ingroup render
680 */
681GHOSTTY_API GhosttyResult ghostty_render_state_row_cells_get(
682 GhosttyRenderStateRowCells cells,
683 GhosttyRenderStateRowCellsData data,
684 void* out);
685
686/**
687 * Get multiple data fields from the current cell in a single call.
688 *
689 * Each element in the keys array specifies a data kind, and the
690 * corresponding element in the values array receives the result.
691 *
692 * Processing stops at the first error; on success out_written
693 * is set to count, on error it is set to the index of the
694 * failing key (i.e. the number of values successfully written).
695 *
696 * @param cells The row cells handle (NULL returns GHOSTTY_INVALID_VALUE)
697 * @param count Number of key/value pairs
698 * @param keys Array of data kinds to query
699 * @param values Array of output pointers (types must match each key's
700 * documented output type)
701 * @param[out] out_written On return, receives the number of values
702 * successfully written (may be NULL)
703 * @return GHOSTTY_SUCCESS if all queries succeed
704 *
705 * @ingroup render
706 */
707GHOSTTY_API GhosttyResult ghostty_render_state_row_cells_get_multi(
708 GhosttyRenderStateRowCells cells,
709 size_t count,
710 const GhosttyRenderStateRowCellsData* keys,
711 void** values,
712 size_t* out_written);
713
714/**
715 * Free a row cells instance.
716 *
717 * @param cells The row cells handle to free (may be NULL)
718 *
719 * @ingroup render
720 */
721GHOSTTY_API void ghostty_render_state_row_cells_free(GhosttyRenderStateRowCells cells);
722
723/** @} */
724
725#ifdef __cplusplus
726}
727#endif
728
729#endif /* GHOSTTY_VT_RENDER_H */
native/libghostty-vt/include/ghostty/vt/screen.h created+400
......@@ -0,0 +1,400 @@
1/**
2 * @file screen.h
3 *
4 * Terminal screen cell and row types.
5 */
6
7#ifndef GHOSTTY_VT_SCREEN_H
8#define GHOSTTY_VT_SCREEN_H
9
10#include <stdbool.h>
11#include <stdint.h>
12#include <ghostty/vt/color.h>
13#include <ghostty/vt/types.h>
14
15#ifdef __cplusplus
16extern "C" {
17#endif
18
19/** @defgroup screen Screen
20 *
21 * Terminal screen cell and row types.
22 *
23 * These types represent the contents of a terminal screen. A GhosttyCell
24 * is a single grid cell and a GhosttyRow is a single row. Both are opaque
25 * values whose fields are accessed via ghostty_cell_get() and
26 * ghostty_row_get() respectively.
27 *
28 * @{
29 */
30
31/**
32 * Opaque cell value.
33 *
34 * Represents a single terminal cell. The internal layout is opaque and
35 * must be queried via ghostty_cell_get(). Obtain cell values from
36 * terminal query APIs.
37 *
38 * @ingroup screen
39 */
40typedef uint64_t GhosttyCell;
41
42/**
43 * Opaque row value.
44 *
45 * Represents a single terminal row. The internal layout is opaque and
46 * must be queried via ghostty_row_get(). Obtain row values from
47 * terminal query APIs.
48 *
49 * @ingroup screen
50 */
51typedef uint64_t GhosttyRow;
52
53/**
54 * Cell content tag.
55 *
56 * Describes what kind of content a cell holds.
57 *
58 * @ingroup screen
59 */
60typedef enum GHOSTTY_ENUM_TYPED {
61 /** A single codepoint (may be zero for empty). */
62 GHOSTTY_CELL_CONTENT_CODEPOINT = 0,
63
64 /** A codepoint that is part of a multi-codepoint grapheme cluster. */
65 GHOSTTY_CELL_CONTENT_CODEPOINT_GRAPHEME = 1,
66
67 /** No text; background color from palette. */
68 GHOSTTY_CELL_CONTENT_BG_COLOR_PALETTE = 2,
69
70 /** No text; background color as RGB. */
71 GHOSTTY_CELL_CONTENT_BG_COLOR_RGB = 3,
72 GHOSTTY_CELL_CONTENT_TAG_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
73} GhosttyCellContentTag;
74
75/**
76 * Cell wide property.
77 *
78 * Describes the width behavior of a cell.
79 *
80 * @ingroup screen
81 */
82typedef enum GHOSTTY_ENUM_TYPED {
83 /** Not a wide character, cell width 1. */
84 GHOSTTY_CELL_WIDE_NARROW = 0,
85
86 /** Wide character, cell width 2. */
87 GHOSTTY_CELL_WIDE_WIDE = 1,
88
89 /** Spacer after wide character. Do not render. */
90 GHOSTTY_CELL_WIDE_SPACER_TAIL = 2,
91
92 /** Spacer at end of soft-wrapped line for a wide character. */
93 GHOSTTY_CELL_WIDE_SPACER_HEAD = 3,
94 GHOSTTY_CELL_WIDE_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
95} GhosttyCellWide;
96
97/**
98 * Semantic content type of a cell.
99 *
100 * Set by semantic prompt sequences (OSC 133) to distinguish between
101 * command output, user input, and shell prompt text.
102 *
103 * @ingroup screen
104 */
105typedef enum GHOSTTY_ENUM_TYPED {
106 /** Regular output content, such as command output. */
107 GHOSTTY_CELL_SEMANTIC_OUTPUT = 0,
108
109 /** Content that is part of user input. */
110 GHOSTTY_CELL_SEMANTIC_INPUT = 1,
111
112 /** Content that is part of a shell prompt. */
113 GHOSTTY_CELL_SEMANTIC_PROMPT = 2,
114 GHOSTTY_CELL_SEMANTIC_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
115} GhosttyCellSemanticContent;
116
117/**
118 * Cell data types.
119 *
120 * These values specify what type of data to extract from a cell
121 * using `ghostty_cell_get`.
122 *
123 * @ingroup screen
124 */
125typedef enum GHOSTTY_ENUM_TYPED {
126 /** Invalid data type. Never results in any data extraction. */
127 GHOSTTY_CELL_DATA_INVALID = 0,
128
129 /**
130 * The codepoint of the cell (0 if empty or bg-color-only).
131 *
132 * Output type: uint32_t *
133 */
134 GHOSTTY_CELL_DATA_CODEPOINT = 1,
135
136 /**
137 * The content tag describing what kind of content is in the cell.
138 *
139 * Output type: GhosttyCellContentTag *
140 */
141 GHOSTTY_CELL_DATA_CONTENT_TAG = 2,
142
143 /**
144 * The wide property of the cell.
145 *
146 * Output type: GhosttyCellWide *
147 */
148 GHOSTTY_CELL_DATA_WIDE = 3,
149
150 /**
151 * Whether the cell has text to render.
152 *
153 * Output type: bool *
154 */
155 GHOSTTY_CELL_DATA_HAS_TEXT = 4,
156
157 /**
158 * Whether the cell has non-default styling.
159 *
160 * Output type: bool *
161 */
162 GHOSTTY_CELL_DATA_HAS_STYLING = 5,
163
164 /**
165 * The style ID for the cell (for use with style lookups).
166 *
167 * Output type: uint16_t *
168 */
169 GHOSTTY_CELL_DATA_STYLE_ID = 6,
170
171 /**
172 * Whether the cell has a hyperlink.
173 *
174 * Output type: bool *
175 */
176 GHOSTTY_CELL_DATA_HAS_HYPERLINK = 7,
177
178 /**
179 * Whether the cell is protected.
180 *
181 * Output type: bool *
182 */
183 GHOSTTY_CELL_DATA_PROTECTED = 8,
184
185 /**
186 * The semantic content type of the cell (from OSC 133).
187 *
188 * Output type: GhosttyCellSemanticContent *
189 */
190 GHOSTTY_CELL_DATA_SEMANTIC_CONTENT = 9,
191
192 /**
193 * The palette index for the cell's background color.
194 * Only valid when content_tag is GHOSTTY_CELL_CONTENT_BG_COLOR_PALETTE.
195 *
196 * Output type: GhosttyColorPaletteIndex *
197 */
198 GHOSTTY_CELL_DATA_COLOR_PALETTE = 10,
199
200 /**
201 * The RGB value for the cell's background color.
202 * Only valid when content_tag is GHOSTTY_CELL_CONTENT_BG_COLOR_RGB.
203 *
204 * Output type: GhosttyColorRgb *
205 */
206 GHOSTTY_CELL_DATA_COLOR_RGB = 11,
207 GHOSTTY_CELL_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
208} GhosttyCellData;
209
210/**
211 * Row semantic prompt state.
212 *
213 * Indicates whether any cells in a row are part of a shell prompt,
214 * as reported by OSC 133 sequences.
215 *
216 * @ingroup screen
217 */
218typedef enum GHOSTTY_ENUM_TYPED {
219 /** No prompt cells in this row. */
220 GHOSTTY_ROW_SEMANTIC_NONE = 0,
221
222 /** Prompt cells exist and this is a primary prompt line. */
223 GHOSTTY_ROW_SEMANTIC_PROMPT = 1,
224
225 /** Prompt cells exist and this is a continuation line. */
226 GHOSTTY_ROW_SEMANTIC_PROMPT_CONTINUATION = 2,
227 GHOSTTY_ROW_SEMANTIC_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
228} GhosttyRowSemanticPrompt;
229
230/**
231 * Row data types.
232 *
233 * These values specify what type of data to extract from a row
234 * using `ghostty_row_get`.
235 *
236 * @ingroup screen
237 */
238typedef enum GHOSTTY_ENUM_TYPED {
239 /** Invalid data type. Never results in any data extraction. */
240 GHOSTTY_ROW_DATA_INVALID = 0,
241
242 /**
243 * Whether this row is soft-wrapped.
244 *
245 * Output type: bool *
246 */
247 GHOSTTY_ROW_DATA_WRAP = 1,
248
249 /**
250 * Whether this row is a continuation of a soft-wrapped row.
251 *
252 * Output type: bool *
253 */
254 GHOSTTY_ROW_DATA_WRAP_CONTINUATION = 2,
255
256 /**
257 * Whether any cells in this row have grapheme clusters.
258 *
259 * Output type: bool *
260 */
261 GHOSTTY_ROW_DATA_GRAPHEME = 3,
262
263 /**
264 * Whether any cells in this row have styling (may have false positives).
265 *
266 * Output type: bool *
267 */
268 GHOSTTY_ROW_DATA_STYLED = 4,
269
270 /**
271 * Whether any cells in this row have hyperlinks (may have false positives).
272 *
273 * Output type: bool *
274 */
275 GHOSTTY_ROW_DATA_HYPERLINK = 5,
276
277 /**
278 * The semantic prompt state of this row.
279 *
280 * Output type: GhosttyRowSemanticPrompt *
281 */
282 GHOSTTY_ROW_DATA_SEMANTIC_PROMPT = 6,
283
284 /**
285 * Whether this row contains a Kitty virtual placeholder.
286 *
287 * Output type: bool *
288 */
289 GHOSTTY_ROW_DATA_KITTY_VIRTUAL_PLACEHOLDER = 7,
290
291 /**
292 * Whether this row is dirty and requires a redraw.
293 *
294 * Output type: bool *
295 */
296 GHOSTTY_ROW_DATA_DIRTY = 8,
297 GHOSTTY_ROW_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
298} GhosttyRowData;
299
300/**
301 * Get data from a cell.
302 *
303 * Extracts typed data from the given cell based on the specified
304 * data type. The output pointer must be of the appropriate type for the
305 * requested data kind. Valid data types and output types are documented
306 * in the `GhosttyCellData` enum.
307 *
308 * @param cell The cell value
309 * @param data The type of data to extract
310 * @param out Pointer to store the extracted data (type depends on data parameter)
311 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the
312 * data type is invalid
313 *
314 * @ingroup screen
315 */
316GHOSTTY_API GhosttyResult ghostty_cell_get(GhosttyCell cell,
317 GhosttyCellData data,
318 void *out);
319
320/**
321 * Get multiple data fields from a cell in a single call.
322 *
323 * Each element in the keys array specifies a data kind, and the
324 * corresponding element in the values array receives the result.
325 *
326 * Processing stops at the first error; on success out_written
327 * is set to count, on error it is set to the index of the
328 * failing key (i.e. the number of values successfully written).
329 *
330 * @param cell The cell value
331 * @param count Number of key/value pairs
332 * @param keys Array of data kinds to query
333 * @param values Array of output pointers (types must match each key's
334 * documented output type)
335 * @param[out] out_written On return, receives the number of values
336 * successfully written (may be NULL)
337 * @return GHOSTTY_SUCCESS if all queries succeed
338 *
339 * @ingroup screen
340 */
341GHOSTTY_API GhosttyResult ghostty_cell_get_multi(GhosttyCell cell,
342 size_t count,
343 const GhosttyCellData* keys,
344 void** values,
345 size_t* out_written);
346
347/**
348 * Get data from a row.
349 *
350 * Extracts typed data from the given row based on the specified
351 * data type. The output pointer must be of the appropriate type for the
352 * requested data kind. Valid data types and output types are documented
353 * in the `GhosttyRowData` enum.
354 *
355 * @param row The row value
356 * @param data The type of data to extract
357 * @param out Pointer to store the extracted data (type depends on data parameter)
358 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the
359 * data type is invalid
360 *
361 * @ingroup screen
362 */
363GHOSTTY_API GhosttyResult ghostty_row_get(GhosttyRow row,
364 GhosttyRowData data,
365 void *out);
366
367/**
368 * Get multiple data fields from a row in a single call.
369 *
370 * Each element in the keys array specifies a data kind, and the
371 * corresponding element in the values array receives the result.
372 *
373 * Processing stops at the first error; on success out_written
374 * is set to count, on error it is set to the index of the
375 * failing key (i.e. the number of values successfully written).
376 *
377 * @param row The row value
378 * @param count Number of key/value pairs
379 * @param keys Array of data kinds to query
380 * @param values Array of output pointers (types must match each key's
381 * documented output type)
382 * @param[out] out_written On return, receives the number of values
383 * successfully written (may be NULL)
384 * @return GHOSTTY_SUCCESS if all queries succeed
385 *
386 * @ingroup screen
387 */
388GHOSTTY_API GhosttyResult ghostty_row_get_multi(GhosttyRow row,
389 size_t count,
390 const GhosttyRowData* keys,
391 void** values,
392 size_t* out_written);
393
394/** @} */
395
396#ifdef __cplusplus
397}
398#endif
399
400#endif /* GHOSTTY_VT_SCREEN_H */
native/libghostty-vt/include/ghostty/vt/selection.h created+1061
......@@ -0,0 +1,1061 @@
1/**
2 * @file selection.h
3 *
4 * Selection range type for specifying a region of terminal content.
5 */
6
7#ifndef GHOSTTY_VT_SELECTION_H
8#define GHOSTTY_VT_SELECTION_H
9
10#include <stdbool.h>
11#include <stddef.h>
12#include <stdint.h>
13#include <ghostty/vt/allocator.h>
14#include <ghostty/vt/grid_ref.h>
15#include <ghostty/vt/point.h>
16#include <ghostty/vt/types.h>
17
18#ifdef __cplusplus
19extern "C" {
20#endif
21
22/** @defgroup selection Selection
23 *
24 * A snapshot selection range defined by two grid references that identifies
25 * a contiguous or rectangular region of terminal content.
26 *
27 * The start and end values are GhosttyGridRef values. They are therefore
28 * untracked grid references and inherit the same lifetime rules: they are
29 * only safe to use until the next mutating operation on the terminal that
30 * produced them, including freeing the terminal. To keep a selection valid
31 * across terminal mutations, callers must maintain tracked grid references
32 * for the endpoints and reconstruct a GhosttySelection from fresh snapshots
33 * when needed.
34 *
35 * Selection gestures provide a reusable state machine for turning UI pointer
36 * interactions into selection snapshots. A caller creates one
37 * GhosttySelectionGesture per active gesture stream, reuses typed
38 * GhosttySelectionGestureEvent objects for synthetic press, drag, release,
39 * autoscroll tick, and deep-press events, and applies each event with
40 * ghostty_selection_gesture_event(). The returned GhosttySelection is a
41 * snapshot; the embedder decides whether to render it, format/copy it, or
42 * install it as the terminal's active selection.
43 *
44 * ## Examples
45 *
46 * @snippet c-vt-selection/src/main.c selection-main
47 * @snippet c-vt-selection-gesture/src/main.c selection-gesture-main
48 *
49 * @{
50 */
51
52/**
53 * Opaque handle to state for interpreting terminal selection gestures.
54 *
55 * The gesture owns only the state required to interpret pointer events. Calls
56 * that use a gesture are not concurrency-safe and must be serialized with
57 * terminal mutations.
58 *
59 * @ingroup selection
60 */
61typedef struct GhosttySelectionGestureImpl* GhosttySelectionGesture;
62
63/**
64 * Opaque handle to reusable input data for selection gesture operations.
65 *
66 * Event options are set with ghostty_selection_gesture_event_set(). Individual
67 * gesture operations document which options are required or optional.
68 *
69 * @ingroup selection
70 */
71typedef struct GhosttySelectionGestureEventImpl* GhosttySelectionGestureEvent;
72
73/**
74 * A snapshot selection range defined by two grid references.
75 *
76 * Both endpoints are inclusive. The endpoints preserve selection direction
77 * and may be reversed; callers must not assume that start is the top-left
78 * endpoint or that end is the bottom-right endpoint.
79 *
80 * When rectangle is false, the endpoints describe a linear selection. When
81 * rectangle is true, the same endpoints are interpreted as opposite corners
82 * of a rectangular/block selection.
83 *
84 * The start and end values are untracked GhosttyGridRef snapshots and are
85 * only valid until the next mutating operation on the terminal that produced
86 * them unless the selection is reconstructed from tracked references.
87 *
88 * This is a sized struct. Use GHOSTTY_INIT_SIZED() to initialize it.
89 *
90 * @ingroup selection
91 */
92typedef struct {
93 /** Size of this struct in bytes. Must be set to sizeof(GhosttySelection). */
94 size_t size;
95
96 /**
97 * Start of the selection range (inclusive).
98 *
99 * This may be after end in terminal order. It is an untracked
100 * GhosttyGridRef snapshot and follows untracked grid-ref lifetime rules.
101 */
102 GhosttyGridRef start;
103
104 /**
105 * End of the selection range (inclusive).
106 *
107 * This may be before start in terminal order. It is an untracked
108 * GhosttyGridRef snapshot and follows untracked grid-ref lifetime rules.
109 */
110 GhosttyGridRef end;
111
112 /**
113 * Whether the endpoints are interpreted as a rectangular/block selection
114 * rather than a linear selection.
115 */
116 bool rectangle;
117} GhosttySelection;
118
119/**
120 * Options for deriving a word selection from a terminal grid reference.
121 *
122 * This is a sized struct. Use GHOSTTY_INIT_SIZED() to initialize it.
123 * If boundary_codepoints is NULL and boundary_codepoints_len is 0, Ghostty's
124 * default word-boundary codepoints are used. If boundary_codepoints_len is
125 * non-zero, boundary_codepoints must not be NULL.
126 *
127 * @ingroup selection
128 */
129typedef struct {
130 /** Size of this struct in bytes. Must be set to sizeof(GhosttyTerminalSelectWordOptions). */
131 size_t size;
132
133 /** Grid reference under which to derive the word selection. */
134 GhosttyGridRef ref;
135
136 /** Optional word-boundary codepoints as uint32_t scalar values. */
137 const uint32_t* boundary_codepoints;
138
139 /** Number of entries in boundary_codepoints. */
140 size_t boundary_codepoints_len;
141} GhosttyTerminalSelectWordOptions;
142
143/**
144 * Options for deriving the nearest word selection between two grid references.
145 *
146 * This is a sized struct. Use GHOSTTY_INIT_SIZED() to initialize it.
147 * If boundary_codepoints is NULL and boundary_codepoints_len is 0, Ghostty's
148 * default word-boundary codepoints are used. If boundary_codepoints_len is
149 * non-zero, boundary_codepoints must not be NULL.
150 *
151 * @ingroup selection
152 */
153typedef struct {
154 /** Size of this struct in bytes. Must be set to sizeof(GhosttyTerminalSelectWordBetweenOptions). */
155 size_t size;
156
157 /** Starting grid reference for the inclusive search range. */
158 GhosttyGridRef start;
159
160 /** Ending grid reference for the inclusive search range. */
161 GhosttyGridRef end;
162
163 /** Optional word-boundary codepoints as uint32_t scalar values. */
164 const uint32_t* boundary_codepoints;
165
166 /** Number of entries in boundary_codepoints. */
167 size_t boundary_codepoints_len;
168} GhosttyTerminalSelectWordBetweenOptions;
169
170/**
171 * Options for deriving a line selection from a terminal grid reference.
172 *
173 * This is a sized struct. Use GHOSTTY_INIT_SIZED() to initialize it.
174 * If whitespace is NULL and whitespace_len is 0, Ghostty's default line-trim
175 * whitespace codepoints are used. If whitespace_len is non-zero, whitespace
176 * must not be NULL.
177 *
178 * @ingroup selection
179 */
180typedef struct {
181 /** Size of this struct in bytes. Must be set to sizeof(GhosttyTerminalSelectLineOptions). */
182 size_t size;
183
184 /** Grid reference under which to derive the line selection. */
185 GhosttyGridRef ref;
186
187 /** Optional codepoints to trim from the start and end of the line. */
188 const uint32_t* whitespace;
189
190 /** Number of entries in whitespace. */
191 size_t whitespace_len;
192
193 /** Whether semantic prompt state changes should bound the line selection. */
194 bool semantic_prompt_boundary;
195} GhosttyTerminalSelectLineOptions;
196
197/**
198 * Options for one-shot formatting of a terminal selection.
199 *
200 * This is a sized struct. Use GHOSTTY_INIT_SIZED() to initialize it.
201 *
202 * If selection is NULL, the terminal's current active selection is used.
203 * If selection is non-NULL, that caller-provided snapshot selection is used.
204 *
205 * The selection is formatted from the terminal's active screen using the same
206 * formatting semantics as GhosttyFormatter. For copy/clipboard behavior
207 * matching Ghostty's Screen.selectionString(), use plain output with unwrap
208 * and trim both set to true.
209 *
210 * @ingroup selection
211 */
212typedef struct {
213 /** Size of this struct in bytes. Must be set to sizeof(GhosttyTerminalSelectionFormatOptions). */
214 size_t size;
215
216 /** Output format to emit. */
217 GhosttyFormatterFormat emit;
218
219 /** Whether to unwrap soft-wrapped lines. */
220 bool unwrap;
221
222 /** Whether to trim trailing whitespace on non-blank lines. */
223 bool trim;
224
225 /**
226 * Optional selection to format.
227 *
228 * If NULL, the terminal's current active selection is used. If the terminal
229 * has no active selection, formatting returns GHOSTTY_NO_VALUE.
230 *
231 * If non-NULL, the pointed-to selection must be a valid snapshot selection
232 * for this terminal and must obey GhosttySelection lifetime rules.
233 */
234 const GhosttySelection *selection;
235} GhosttyTerminalSelectionFormatOptions;
236
237/**
238 * Ordering of a selection's endpoints in terminal coordinates.
239 *
240 * Mirrored orders are only produced by rectangular selections whose start
241 * and end endpoints are on opposite diagonal corners that are not simple
242 * top-left-to-bottom-right or bottom-right-to-top-left orderings.
243 *
244 * @ingroup selection
245 */
246typedef enum GHOSTTY_ENUM_TYPED {
247 /** Start is before end in top-left to bottom-right order. */
248 GHOSTTY_SELECTION_ORDER_FORWARD = 0,
249
250 /** End is before start in top-left to bottom-right order. */
251 GHOSTTY_SELECTION_ORDER_REVERSE = 1,
252
253 /** Rectangular selection from top-right to bottom-left. */
254 GHOSTTY_SELECTION_ORDER_MIRRORED_FORWARD = 2,
255
256 /** Rectangular selection from bottom-left to top-right. */
257 GHOSTTY_SELECTION_ORDER_MIRRORED_REVERSE = 3,
258
259 GHOSTTY_SELECTION_ORDER_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
260} GhosttySelectionOrder;
261
262/**
263 * Operation used to adjust a selection endpoint.
264 *
265 * Adjustment mutates the selection's logical end endpoint, not whichever
266 * endpoint is visually bottom/right. This preserves keyboard and drag
267 * behavior for both forward and reversed selections.
268 *
269 * @ingroup selection
270 */
271typedef enum GHOSTTY_ENUM_TYPED {
272 /** Move left to the previous non-empty cell, wrapping upward. */
273 GHOSTTY_SELECTION_ADJUST_LEFT = 0,
274
275 /** Move right to the next non-empty cell, wrapping downward. */
276 GHOSTTY_SELECTION_ADJUST_RIGHT = 1,
277
278 /**
279 * Move up one row at the current column, or to the beginning of the
280 * line if already at the top.
281 */
282 GHOSTTY_SELECTION_ADJUST_UP = 2,
283
284 /**
285 * Move down to the next non-blank row at the current column, or to the
286 * end of the line if none exists.
287 */
288 GHOSTTY_SELECTION_ADJUST_DOWN = 3,
289
290 /** Move to the top-left cell of the screen. */
291 GHOSTTY_SELECTION_ADJUST_HOME = 4,
292
293 /** Move to the right edge of the last non-blank row on the screen. */
294 GHOSTTY_SELECTION_ADJUST_END = 5,
295
296 /**
297 * Move up by one terminal page height, or to home if that would move
298 * past the top.
299 */
300 GHOSTTY_SELECTION_ADJUST_PAGE_UP = 6,
301
302 /**
303 * Move down by one terminal page height, or to end if that would move
304 * past the bottom.
305 */
306 GHOSTTY_SELECTION_ADJUST_PAGE_DOWN = 7,
307
308 /** Move to the left edge of the current line. */
309 GHOSTTY_SELECTION_ADJUST_BEGINNING_OF_LINE = 8,
310
311 /** Move to the right edge of the current line. */
312 GHOSTTY_SELECTION_ADJUST_END_OF_LINE = 9,
313
314 GHOSTTY_SELECTION_ADJUST_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
315} GhosttySelectionAdjust;
316
317/**
318 * Selection behavior chosen for a gesture's click sequence.
319 *
320 * @ingroup selection
321 */
322typedef enum GHOSTTY_ENUM_TYPED {
323 /** Cell-granular drag selection. */
324 GHOSTTY_SELECTION_GESTURE_BEHAVIOR_CELL = 0,
325
326 /** Word selection on press and word-granular drag selection. */
327 GHOSTTY_SELECTION_GESTURE_BEHAVIOR_WORD = 1,
328
329 /** Line selection on press and line-granular drag selection. */
330 GHOSTTY_SELECTION_GESTURE_BEHAVIOR_LINE = 2,
331
332 /** Semantic command output selection on press and drag. */
333 GHOSTTY_SELECTION_GESTURE_BEHAVIOR_OUTPUT = 3,
334
335 GHOSTTY_SELECTION_GESTURE_BEHAVIOR_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
336} GhosttySelectionGestureBehavior;
337
338/**
339 * Selection behaviors for single-, double-, and triple-click gestures.
340 *
341 * @ingroup selection
342 */
343typedef struct {
344 /** Behavior for single-click selection gestures. */
345 GhosttySelectionGestureBehavior single_click;
346
347 /** Behavior for double-click selection gestures. */
348 GhosttySelectionGestureBehavior double_click;
349
350 /** Behavior for triple-click selection gestures. */
351 GhosttySelectionGestureBehavior triple_click;
352} GhosttySelectionGestureBehaviors;
353
354/**
355 * Display geometry used to interpret selection gesture drag events.
356 *
357 * @ingroup selection
358 */
359typedef struct {
360 /** Number of columns in the rendered terminal grid. Must be non-zero. */
361 uint32_t columns;
362
363 /** Width of one terminal cell in surface pixels. Must be non-zero. */
364 uint32_t cell_width;
365
366 /** Left padding before the terminal grid begins in surface pixels. */
367 uint32_t padding_left;
368
369 /** Height of the rendered terminal surface in surface pixels. Must be non-zero. */
370 uint32_t screen_height;
371} GhosttySelectionGestureGeometry;
372
373/**
374 * Current autoscroll direction for an active selection drag gesture.
375 *
376 * @ingroup selection
377 */
378typedef enum GHOSTTY_ENUM_TYPED {
379 /** No selection autoscroll is requested. */
380 GHOSTTY_SELECTION_GESTURE_AUTOSCROLL_NONE = 0,
381
382 /** Selection dragging should autoscroll the viewport upward. */
383 GHOSTTY_SELECTION_GESTURE_AUTOSCROLL_UP = 1,
384
385 /** Selection dragging should autoscroll the viewport downward. */
386 GHOSTTY_SELECTION_GESTURE_AUTOSCROLL_DOWN = 2,
387
388 GHOSTTY_SELECTION_GESTURE_AUTOSCROLL_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
389} GhosttySelectionGestureAutoscroll;
390
391/**
392 * Data fields readable from a selection gesture with
393 * ghostty_selection_gesture_get().
394 *
395 * @ingroup selection
396 */
397typedef enum GHOSTTY_ENUM_TYPED {
398 /** Current click count: uint8_t*. 0 means inactive. */
399 GHOSTTY_SELECTION_GESTURE_DATA_CLICK_COUNT = 0,
400
401 /** Whether the current/last left-click gesture has dragged: bool*. */
402 GHOSTTY_SELECTION_GESTURE_DATA_DRAGGED = 1,
403
404 /** Current autoscroll request: GhosttySelectionGestureAutoscroll*. */
405 GHOSTTY_SELECTION_GESTURE_DATA_AUTOSCROLL = 2,
406
407 /** Current gesture behavior: GhosttySelectionGestureBehavior*. */
408 GHOSTTY_SELECTION_GESTURE_DATA_BEHAVIOR = 3,
409
410 /**
411 * Current left-click anchor: GhosttyGridRef*.
412 *
413 * Returns GHOSTTY_NO_VALUE if there is no valid active anchor. On success,
414 * writes an untracked GhosttyGridRef snapshot with normal GhosttyGridRef
415 * lifetime rules.
416 */
417 GHOSTTY_SELECTION_GESTURE_DATA_ANCHOR = 4,
418
419 GHOSTTY_SELECTION_GESTURE_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
420} GhosttySelectionGestureData;
421
422/**
423 * Selection gesture event type.
424 *
425 * The event type is fixed when the event is created. Each event type documents
426 * which options are valid and which options are required by gesture operations.
427 *
428 * @ingroup selection
429 */
430typedef enum GHOSTTY_ENUM_TYPED {
431 /** Press event for ghostty_selection_gesture_event(). */
432 GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_PRESS = 0,
433
434 /** Release event for ghostty_selection_gesture_event(). */
435 GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_RELEASE = 1,
436
437 /** Drag event for ghostty_selection_gesture_event(). */
438 GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_DRAG = 2,
439
440 /** Autoscroll tick event for ghostty_selection_gesture_event(). */
441 GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_AUTOSCROLL_TICK = 3,
442
443 /** Deep press event for ghostty_selection_gesture_event(). */
444 GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_DEEP_PRESS = 4,
445
446 GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
447} GhosttySelectionGestureEventType;
448
449/**
450 * Options stored on a reusable selection gesture event.
451 *
452 * Passing NULL as the value to ghostty_selection_gesture_event_set() clears the
453 * corresponding option.
454 *
455 * @ingroup selection
456 */
457typedef enum GHOSTTY_ENUM_TYPED {
458 /**
459 * Grid reference under the pointer: GhosttyGridRef*.
460 *
461 * Required for PRESS and DRAG events. Optional for RELEASE events; when unset
462 * or cleared, release records that the pointer did not map to a valid cell.
463 */
464 GHOSTTY_SELECTION_GESTURE_EVENT_OPT_REF = 0,
465
466 /**
467 * Surface-space pointer position: GhosttySurfacePosition*.
468 *
469 * Valid for PRESS, DRAG, and AUTOSCROLL_TICK.
470 */
471 GHOSTTY_SELECTION_GESTURE_EVENT_OPT_POSITION = 1,
472
473 /** Maximum repeat-click distance in pixels: double*. */
474 GHOSTTY_SELECTION_GESTURE_EVENT_OPT_REPEAT_DISTANCE = 2,
475
476 /**
477 * Optional monotonic event time in nanoseconds: uint64_t*.
478 *
479 * If unset, press treats the event as untimed and only single-click behavior
480 * is available.
481 */
482 GHOSTTY_SELECTION_GESTURE_EVENT_OPT_TIME_NS = 3,
483
484 /** Maximum interval between repeat clicks in nanoseconds: uint64_t*. */
485 GHOSTTY_SELECTION_GESTURE_EVENT_OPT_REPEAT_INTERVAL_NS = 4,
486
487 /**
488 * Word-boundary codepoints: GhosttyCodepoints*.
489 *
490 * The codepoints are copied into event-owned storage when set. If unset,
491 * operations that need word boundaries use Ghostty's defaults.
492 *
493 * Valid for PRESS, DRAG, AUTOSCROLL_TICK, and DEEP_PRESS.
494 */
495 GHOSTTY_SELECTION_GESTURE_EVENT_OPT_WORD_BOUNDARY_CODEPOINTS = 5,
496
497 /**
498 * Selection behavior table: GhosttySelectionGestureBehaviors*.
499 *
500 * If unset, press uses the default behavior table: cell, word, line.
501 */
502 GHOSTTY_SELECTION_GESTURE_EVENT_OPT_BEHAVIORS = 6,
503
504 /** Whether a drag or autoscroll tick should produce a rectangular selection: bool*. */
505 GHOSTTY_SELECTION_GESTURE_EVENT_OPT_RECTANGLE = 7,
506
507 /** Drag display geometry: GhosttySelectionGestureGeometry*. Required for DRAG and AUTOSCROLL_TICK. */
508 GHOSTTY_SELECTION_GESTURE_EVENT_OPT_GEOMETRY = 8,
509
510 /** Viewport coordinate for an autoscroll tick: GhosttyPointCoordinate*. Required for AUTOSCROLL_TICK. */
511 GHOSTTY_SELECTION_GESTURE_EVENT_OPT_VIEWPORT = 9,
512
513 GHOSTTY_SELECTION_GESTURE_EVENT_OPT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
514} GhosttySelectionGestureEventOption;
515
516/**
517 * Create a reusable selection gesture event object.
518 *
519 * @param allocator Allocator, or NULL for the default allocator
520 * @param out_event Receives the created event handle
521 * @param type Event type. This is fixed for the lifetime of the event.
522 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if out_event is
523 * NULL or type is invalid, or GHOSTTY_OUT_OF_MEMORY if allocation fails
524 *
525 * @ingroup selection
526 */
527GHOSTTY_API GhosttyResult ghostty_selection_gesture_event_new(
528 const GhosttyAllocator* allocator,
529 GhosttySelectionGestureEvent* out_event,
530 GhosttySelectionGestureEventType type);
531
532/**
533 * Free a selection gesture event object.
534 *
535 * Passing NULL is allowed and is a no-op.
536 *
537 * @param event Selection gesture event handle to free
538 *
539 * @ingroup selection
540 */
541GHOSTTY_API void ghostty_selection_gesture_event_free(
542 GhosttySelectionGestureEvent event);
543
544/**
545 * Set or clear an option on a selection gesture event.
546 *
547 * The value type depends on option and is documented by
548 * GhosttySelectionGestureEventOption. Passing NULL for value clears the option.
549 *
550 * @param event Selection gesture event handle (NULL returns GHOSTTY_INVALID_VALUE)
551 * @param option Event option to set or clear
552 * @param value Pointer to the input value for option, or NULL to clear
553 * @return GHOSTTY_SUCCESS on success, GHOSTTY_OUT_OF_MEMORY if copying
554 * event-owned data fails, or GHOSTTY_INVALID_VALUE if event, option, or
555 * value is invalid
556 *
557 * @ingroup selection
558 */
559GHOSTTY_API GhosttyResult ghostty_selection_gesture_event_set(
560 GhosttySelectionGestureEvent event,
561 GhosttySelectionGestureEventOption option,
562 const void* value);
563
564/**
565 * Apply a selection gesture event and return the resulting selection snapshot.
566 *
567 * This dispatches to the gesture operation matching the event's fixed type.
568 * For GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_PRESS, the event must have
569 * GHOSTTY_SELECTION_GESTURE_EVENT_OPT_REF set before calling this function.
570 * All other press options use their initialized defaults when unset or cleared.
571 *
572 * For GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_RELEASE, only
573 * GHOSTTY_SELECTION_GESTURE_EVENT_OPT_REF is valid. It is optional; if unset or
574 * cleared, release records that the pointer did not map to a valid cell. Release
575 * events update gesture state but do not produce a selection, so this function
576 * returns GHOSTTY_NO_VALUE after applying them.
577 *
578 * For GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_DRAG,
579 * GHOSTTY_SELECTION_GESTURE_EVENT_OPT_REF and
580 * GHOSTTY_SELECTION_GESTURE_EVENT_OPT_GEOMETRY are required. Position,
581 * rectangle, and word-boundary codepoints are optional and use initialized
582 * defaults when unset or cleared.
583 *
584 * For GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_AUTOSCROLL_TICK,
585 * GHOSTTY_SELECTION_GESTURE_EVENT_OPT_VIEWPORT and
586 * GHOSTTY_SELECTION_GESTURE_EVENT_OPT_GEOMETRY are required. Position,
587 * rectangle, and word-boundary codepoints are optional and use initialized
588 * defaults when unset or cleared.
589 *
590 * For GHOSTTY_SELECTION_GESTURE_EVENT_TYPE_DEEP_PRESS, only
591 * GHOSTTY_SELECTION_GESTURE_EVENT_OPT_WORD_BOUNDARY_CODEPOINTS is valid. It is
592 * optional and uses initialized defaults when unset or cleared.
593 *
594 * The returned selection is not installed as the terminal's current selection.
595 * It is a snapshot with the same lifetime rules as GhosttySelection.
596 *
597 * @param gesture Selection gesture handle (NULL returns GHOSTTY_INVALID_VALUE)
598 * @param terminal Terminal used to interpret and update gesture state
599 * @param event Selection gesture event handle (NULL returns GHOSTTY_INVALID_VALUE)
600 * @param[out] out_selection On success, receives the resulting selection. May
601 * be NULL to apply the event and discard the selection result.
602 * @return GHOSTTY_SUCCESS on success, GHOSTTY_NO_VALUE if the event does not
603 * currently produce a selection, GHOSTTY_OUT_OF_MEMORY if tracking
604 * gesture state fails, or GHOSTTY_INVALID_VALUE if gesture, terminal,
605 * event, or required event data is invalid
606 *
607 * @ingroup selection
608 */
609GHOSTTY_API GhosttyResult ghostty_selection_gesture_event(
610 GhosttySelectionGesture gesture,
611 GhosttyTerminal terminal,
612 GhosttySelectionGestureEvent event,
613 GhosttySelection* out_selection);
614
615/**
616 * Create a selection gesture object.
617 *
618 * The gesture stores mutable state for terminal text selection gestures. The
619 * gesture is not bound to a terminal at creation time; terminal-dependent APIs
620 * take the terminal explicitly.
621 *
622 * @param allocator Allocator, or NULL for the default allocator
623 * @param out_gesture Receives the created gesture handle
624 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if out_gesture is
625 * NULL, or GHOSTTY_OUT_OF_MEMORY if allocation fails
626 *
627 * @ingroup selection
628 */
629GHOSTTY_API GhosttyResult ghostty_selection_gesture_new(
630 const GhosttyAllocator* allocator,
631 GhosttySelectionGesture* out_gesture);
632
633/**
634 * Free a selection gesture object.
635 *
636 * This releases any tracked terminal references owned by the gesture using the
637 * provided terminal, then frees the gesture object. Passing NULL for gesture is
638 * allowed and is a no-op.
639 *
640 * If the terminal is still alive, pass the terminal most recently used with the
641 * gesture so any tracked terminal references can be released correctly. If the
642 * terminal has already been freed, pass NULL for terminal; the terminal's page
643 * storage has already released the underlying tracked references, so the
644 * gesture wrapper can be safely discarded without touching the stale terminal
645 * state.
646 *
647 * @param gesture Selection gesture handle to free
648 * @param terminal Terminal used to release tracked gesture state, or NULL if
649 * the terminal has already been freed
650 *
651 * @ingroup selection
652 */
653GHOSTTY_API void ghostty_selection_gesture_free(
654 GhosttySelectionGesture gesture,
655 GhosttyTerminal terminal);
656
657/**
658 * Reset any active selection gesture state.
659 *
660 * This cancels the active click sequence and releases any tracked terminal
661 * references owned by the gesture without freeing the gesture object.
662 * Passing NULL is allowed and is a no-op.
663 *
664 * @param gesture Selection gesture handle to reset
665 * @param terminal Terminal used to release tracked gesture state
666 *
667 * @ingroup selection
668 */
669GHOSTTY_API void ghostty_selection_gesture_reset(
670 GhosttySelectionGesture gesture,
671 GhosttyTerminal terminal);
672
673/**
674 * Read data from a selection gesture.
675 *
676 * The type of value depends on data and is documented by
677 * GhosttySelectionGestureData. For GHOSTTY_SELECTION_GESTURE_DATA_ANCHOR,
678 * the returned GhosttyGridRef is an untracked snapshot with normal grid-ref
679 * lifetime rules.
680 *
681 * @param gesture Selection gesture handle (NULL returns GHOSTTY_INVALID_VALUE)
682 * @param terminal Terminal used to validate terminal-backed gesture state
683 * @param data Data field to read
684 * @param value Output pointer whose type depends on data
685 * @return GHOSTTY_SUCCESS on success, GHOSTTY_NO_VALUE if the requested data
686 * has no value, or GHOSTTY_INVALID_VALUE if gesture, terminal, data, or
687 * value is invalid
688 *
689 * @ingroup selection
690 */
691GHOSTTY_API GhosttyResult ghostty_selection_gesture_get(
692 GhosttySelectionGesture gesture,
693 GhosttyTerminal terminal,
694 GhosttySelectionGestureData data,
695 void* value);
696
697/**
698 * Read multiple data fields from a selection gesture in a single call.
699 *
700 * This is an optimization over calling ghostty_selection_gesture_get() multiple
701 * times. Each entry in values must point to storage of the type documented by
702 * the corresponding GhosttySelectionGestureData key.
703 *
704 * If any individual read fails, the function returns that error and writes the
705 * index of the failing key to out_written when out_written is non-NULL. On
706 * success, out_written receives count when non-NULL.
707 *
708 * @param gesture Selection gesture handle (NULL returns GHOSTTY_INVALID_VALUE)
709 * @param terminal Terminal used to validate terminal-backed gesture state
710 * @param count Number of data fields to read
711 * @param keys Data fields to read (must not be NULL)
712 * @param values Output pointers corresponding to keys (must not be NULL)
713 * @param out_written Optional number of fields read, or failing index on error
714 * @return GHOSTTY_SUCCESS on success, GHOSTTY_NO_VALUE if a requested data
715 * field has no value, or GHOSTTY_INVALID_VALUE if gesture, terminal,
716 * keys, values, or a value pointer is invalid
717 *
718 * @ingroup selection
719 */
720GHOSTTY_API GhosttyResult ghostty_selection_gesture_get_multi(
721 GhosttySelectionGesture gesture,
722 GhosttyTerminal terminal,
723 size_t count,
724 const GhosttySelectionGestureData* keys,
725 void** values,
726 size_t* out_written);
727
728/**
729 * Derive a word selection snapshot from a terminal grid reference.
730 *
731 * The returned selection is not installed as the terminal's current
732 * selection. It is a snapshot with the same lifetime rules as GhosttySelection.
733 *
734 * @param terminal The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
735 * @param options Word-selection options
736 * @param[out] out_selection On success, receives the derived selection
737 * @return GHOSTTY_SUCCESS on success, GHOSTTY_NO_VALUE if the valid ref has
738 * no selectable word content, or GHOSTTY_INVALID_VALUE if the
739 * terminal, options, ref, codepoint pointer, or output pointer are
740 * invalid.
741 *
742 * @ingroup selection
743 */
744GHOSTTY_API GhosttyResult ghostty_terminal_select_word(
745 GhosttyTerminal terminal,
746 const GhosttyTerminalSelectWordOptions* options,
747 GhosttySelection* out_selection);
748
749/**
750 * Derive the nearest word selection snapshot between two terminal grid refs.
751 *
752 * Starting at options->start, this searches toward options->end (inclusive)
753 * and returns the first selectable word found using Ghostty's word-selection
754 * rules.
755 *
756 * This is useful for implementing double-click-and-drag selection in a UI. If
757 * a user double-clicks one word and drags across spaces or punctuation toward
758 * another word, selecting only the word directly under the current pointer can
759 * flicker or collapse when the pointer is between words. Instead, ask for the
760 * nearest word between the original click and the drag point, ask again in the
761 * reverse direction, and combine the two word bounds into the drag selection.
762 *
763 * @snippet c-vt-selection/src/main.c selection-word-between
764 *
765 * The returned selection is not installed as the terminal's current
766 * selection. It is a snapshot with the same lifetime rules as GhosttySelection.
767 *
768 * @param terminal The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
769 * @param options Word-between-selection options
770 * @param[out] out_selection On success, receives the derived selection
771 * @return GHOSTTY_SUCCESS on success, GHOSTTY_NO_VALUE if there is no
772 * selectable word content between the valid refs, or
773 * GHOSTTY_INVALID_VALUE if the terminal, options, refs, codepoint
774 * pointer, or output pointer are invalid.
775 *
776 * @ingroup selection
777 */
778GHOSTTY_API GhosttyResult ghostty_terminal_select_word_between(
779 GhosttyTerminal terminal,
780 const GhosttyTerminalSelectWordBetweenOptions* options,
781 GhosttySelection* out_selection);
782
783/**
784 * Derive a line selection snapshot from a terminal grid reference.
785 *
786 * The returned selection is not installed as the terminal's current
787 * selection. It is a snapshot with the same lifetime rules as GhosttySelection.
788 *
789 * @param terminal The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
790 * @param options Line-selection options
791 * @param[out] out_selection On success, receives the derived selection
792 * @return GHOSTTY_SUCCESS on success, GHOSTTY_NO_VALUE if the valid ref has
793 * no selectable line content, or GHOSTTY_INVALID_VALUE if the
794 * terminal, options, ref, codepoint pointer, or output pointer are
795 * invalid.
796 *
797 * @ingroup selection
798 */
799GHOSTTY_API GhosttyResult ghostty_terminal_select_line(
800 GhosttyTerminal terminal,
801 const GhosttyTerminalSelectLineOptions* options,
802 GhosttySelection* out_selection);
803
804/**
805 * Derive a selection snapshot covering all selectable terminal content.
806 *
807 * The returned selection is not installed as the terminal's current
808 * selection. It is a snapshot with the same lifetime rules as GhosttySelection.
809 *
810 * @param terminal The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
811 * @param[out] out_selection On success, receives the derived selection
812 * @return GHOSTTY_SUCCESS on success, GHOSTTY_NO_VALUE if there is no
813 * selectable content, or GHOSTTY_INVALID_VALUE if the terminal or
814 * output pointer is invalid.
815 *
816 * @ingroup selection
817 */
818GHOSTTY_API GhosttyResult ghostty_terminal_select_all(
819 GhosttyTerminal terminal,
820 GhosttySelection* out_selection);
821
822/**
823 * Derive a command-output selection snapshot from a terminal grid reference.
824 *
825 * The returned selection is not installed as the terminal's current
826 * selection. It is a snapshot with the same lifetime rules as GhosttySelection.
827 *
828 * @param terminal The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
829 * @param ref Grid reference within command output to select
830 * @param[out] out_selection On success, receives the derived selection
831 * @return GHOSTTY_SUCCESS on success, GHOSTTY_NO_VALUE if the valid ref is
832 * not selectable command output, or GHOSTTY_INVALID_VALUE if the
833 * terminal, ref, or output pointer is invalid.
834 *
835 * @ingroup selection
836 */
837GHOSTTY_API GhosttyResult ghostty_terminal_select_output(
838 GhosttyTerminal terminal,
839 GhosttyGridRef ref,
840 GhosttySelection* out_selection);
841
842/**
843 * Format a terminal selection into a caller-provided buffer.
844 *
845 * This is a one-shot convenience API for formatting either the terminal's
846 * active selection or a caller-provided GhosttySelection without explicitly
847 * creating a GhosttyFormatter.
848 *
849 * Pass NULL for buf to query the required output size. In that case,
850 * out_written receives the required size and the function returns
851 * GHOSTTY_OUT_OF_SPACE.
852 *
853 * If buf is too small, the function returns GHOSTTY_OUT_OF_SPACE and writes
854 * the required size to out_written. The caller can then retry with a larger
855 * buffer.
856 *
857 * If options.selection is NULL and the terminal has no active selection, the
858 * function returns GHOSTTY_NO_VALUE.
859 *
860 * @param terminal The terminal to read from (must not be NULL)
861 * @param options Selection formatting options
862 * @param buf Output buffer, or NULL to query required size
863 * @param buf_len Length of buf in bytes
864 * @param out_written Number of bytes written, or required size on
865 * GHOSTTY_OUT_OF_SPACE (must not be NULL)
866 * @return GHOSTTY_SUCCESS on success, or an error code on failure
867 *
868 * @ingroup selection
869 */
870GHOSTTY_API GhosttyResult ghostty_terminal_selection_format_buf(
871 GhosttyTerminal terminal,
872 GhosttyTerminalSelectionFormatOptions options,
873 uint8_t* buf,
874 size_t buf_len,
875 size_t* out_written);
876
877/**
878 * Format a terminal selection into an allocated buffer.
879 *
880 * This is a one-shot convenience API for formatting either the terminal's
881 * active selection or a caller-provided GhosttySelection without explicitly
882 * creating a GhosttyFormatter.
883 *
884 * The returned buffer is allocated using allocator, or the default allocator
885 * if NULL is passed. The caller owns the returned buffer and must free it with
886 * ghostty_free(), passing the same allocator and returned length.
887 *
888 * The returned bytes are not NUL-terminated. This supports plain text, VT, and
889 * HTML uniformly as byte output.
890 *
891 * If options.selection is NULL and the terminal has no active selection, the
892 * function returns GHOSTTY_NO_VALUE and leaves out_ptr as NULL and out_len as 0.
893 *
894 * @param terminal The terminal to read from (must not be NULL)
895 * @param allocator Allocator used for the returned buffer, or NULL for the default allocator
896 * @param options Selection formatting options
897 * @param out_ptr Receives the allocated output buffer (must not be NULL)
898 * @param out_len Receives the output length in bytes (must not be NULL)
899 * @return GHOSTTY_SUCCESS on success, or an error code on failure
900 *
901 * @ingroup selection
902 */
903GHOSTTY_API GhosttyResult ghostty_terminal_selection_format_alloc(
904 GhosttyTerminal terminal,
905 const GhosttyAllocator* allocator,
906 GhosttyTerminalSelectionFormatOptions options,
907 uint8_t** out_ptr,
908 size_t* out_len);
909
910/**
911 * Adjust a selection snapshot using terminal selection semantics.
912 *
913 * This mutates the caller-provided GhosttySelection in place. The logical end
914 * endpoint is always moved, regardless of whether the selection is forward or
915 * reversed visually. The input selection remains a snapshot: after adjustment,
916 * call ghostty_terminal_set() with GHOSTTY_TERMINAL_OPT_SELECTION to install it
917 * as the terminal-owned selection if desired.
918 *
919 * The selection's start and end grid refs must both be valid untracked
920 * snapshots for the given terminal's currently active screen. In practice,
921 * they must come from that terminal and screen, and no mutating terminal call
922 * may have occurred since the refs were produced or reconstructed from
923 * tracked refs. Passing refs from another terminal, another screen, or stale
924 * refs violates this precondition.
925 *
926 * @param terminal The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
927 * @param selection Selection snapshot to adjust in place
928 * @param adjustment The adjustment operation to apply
929 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the terminal,
930 * selection, or adjustment are invalid. Selection reference validity
931 * is a precondition and is not checked.
932 *
933 * @ingroup selection
934 */
935GHOSTTY_API GhosttyResult ghostty_terminal_selection_adjust(
936 GhosttyTerminal terminal,
937 GhosttySelection* selection,
938 GhosttySelectionAdjust adjustment);
939
940/**
941 * Get the current endpoint ordering of a selection snapshot.
942 *
943 * The selection's start and end grid refs must both be valid untracked
944 * snapshots for the given terminal's currently active screen. In practice,
945 * they must come from that terminal and screen, and no mutating terminal call
946 * may have occurred since the refs were produced or reconstructed from
947 * tracked refs. Passing refs from another terminal, another screen, or stale
948 * refs violates this precondition.
949 *
950 * @param terminal The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
951 * @param selection Selection snapshot to inspect
952 * @param[out] out_order On success, receives the selection order
953 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the terminal,
954 * selection, or output pointer are invalid. Selection reference
955 * validity is a precondition and is not checked.
956 *
957 * @ingroup selection
958 */
959GHOSTTY_API GhosttyResult ghostty_terminal_selection_order(
960 GhosttyTerminal terminal,
961 const GhosttySelection* selection,
962 GhosttySelectionOrder* out_order);
963
964/**
965 * Return a selection snapshot with endpoints ordered as requested.
966 *
967 * Use GHOSTTY_SELECTION_ORDER_FORWARD to get top-left to bottom-right bounds,
968 * and GHOSTTY_SELECTION_ORDER_REVERSE to get bottom-right to top-left bounds.
969 * Mirrored desired orders are accepted but normalized the same as forward.
970 * The output selection is a fresh untracked snapshot and is not installed as
971 * the terminal's current selection.
972 *
973 * The selection's start and end grid refs must both be valid untracked
974 * snapshots for the given terminal's currently active screen. In practice,
975 * they must come from that terminal and screen, and no mutating terminal call
976 * may have occurred since the refs were produced or reconstructed from
977 * tracked refs. Passing refs from another terminal, another screen, or stale
978 * refs violates this precondition.
979 *
980 * @param terminal The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
981 * @param selection Selection snapshot to order
982 * @param desired Desired endpoint order
983 * @param[out] out_selection On success, receives the ordered selection
984 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the terminal,
985 * selection, desired order, or output pointer are invalid. Selection
986 * reference validity is a precondition and is not checked.
987 *
988 * @ingroup selection
989 */
990GHOSTTY_API GhosttyResult ghostty_terminal_selection_ordered(
991 GhosttyTerminal terminal,
992 const GhosttySelection* selection,
993 GhosttySelectionOrder desired,
994 GhosttySelection* out_selection);
995
996/**
997 * Test whether a terminal point is inside a selection snapshot.
998 *
999 * This uses the same selection semantics as the terminal, including
1000 * rectangular/block selections and linear selections spanning multiple rows.
1001 *
1002 * The selection's start and end grid refs must both be valid untracked
1003 * snapshots for the given terminal's currently active screen. In practice,
1004 * they must come from that terminal and screen, and no mutating terminal call
1005 * may have occurred since the refs were produced or reconstructed from
1006 * tracked refs. Passing refs from another terminal, another screen, or stale
1007 * refs violates this precondition.
1008 *
1009 * @param terminal The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
1010 * @param selection Selection snapshot to inspect
1011 * @param point Point to test for containment
1012 * @param[out] out_contains On success, receives whether point is inside selection
1013 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the terminal,
1014 * selection, point, or output pointer are invalid. Selection reference
1015 * validity is a precondition and is not checked.
1016 *
1017 * @ingroup selection
1018 */
1019GHOSTTY_API GhosttyResult ghostty_terminal_selection_contains(
1020 GhosttyTerminal terminal,
1021 const GhosttySelection* selection,
1022 GhosttyPoint point,
1023 bool* out_contains);
1024
1025/**
1026 * Test whether two selection snapshots are equal.
1027 *
1028 * Equality uses the terminal's internal selection semantics: both endpoint
1029 * pins must match and both selections must have the same rectangular/block
1030 * state. This avoids requiring callers to compare raw GhosttyGridRef internals.
1031 *
1032 * Both selections' start and end grid refs must be valid untracked snapshots
1033 * for the given terminal's currently active screen. In practice, they must
1034 * come from that terminal and screen, and no mutating terminal call may have
1035 * occurred since the refs were produced or reconstructed from tracked refs.
1036 * Passing refs from another terminal, another screen, or stale refs violates
1037 * this precondition.
1038 *
1039 * @param terminal The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
1040 * @param a First selection snapshot to compare
1041 * @param b Second selection snapshot to compare
1042 * @param[out] out_equal On success, receives whether the selections are equal
1043 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the terminal,
1044 * selections, or output pointer are invalid. Selection reference
1045 * validity is a precondition and is not checked.
1046 *
1047 * @ingroup selection
1048 */
1049GHOSTTY_API GhosttyResult ghostty_terminal_selection_equal(
1050 GhosttyTerminal terminal,
1051 const GhosttySelection* a,
1052 const GhosttySelection* b,
1053 bool* out_equal);
1054
1055/** @} */
1056
1057#ifdef __cplusplus
1058}
1059#endif
1060
1061#endif /* GHOSTTY_VT_SELECTION_H */
native/libghostty-vt/include/ghostty/vt/sgr.h created+350
......@@ -0,0 +1,350 @@
1/**
2 * @file sgr.h
3 *
4 * SGR (Select Graphic Rendition) attribute parsing and handling.
5 */
6
7#ifndef GHOSTTY_VT_SGR_H
8#define GHOSTTY_VT_SGR_H
9
10/** @defgroup sgr SGR Parser
11 *
12 * SGR (Select Graphic Rendition) attribute parser.
13 *
14 * SGR sequences are the syntax used to set styling attributes such as
15 * bold, italic, underline, and colors for text in terminal emulators.
16 * For example, you may be familiar with sequences like `ESC[1;31m`. The
17 * `1;31` is the SGR attribute list.
18 *
19 * The parser processes SGR parameters from CSI sequences (e.g., `ESC[1;31m`)
20 * and returns individual text attributes like bold, italic, colors, etc.
21 * It supports both semicolon (`;`) and colon (`:`) separators, possibly mixed,
22 * and handles various color formats including 8-color, 16-color, 256-color,
23 * X11 named colors, and RGB in multiple formats.
24 *
25 * ## Basic Usage
26 *
27 * 1. Create a parser instance with ghostty_sgr_new()
28 * 2. Set SGR parameters with ghostty_sgr_set_params()
29 * 3. Iterate through attributes using ghostty_sgr_next()
30 * 4. Free the parser with ghostty_sgr_free() when done
31 *
32 * ## Example
33 *
34 * @snippet c-vt-sgr/src/main.c sgr-basic
35 *
36 * @{
37 */
38
39#include <ghostty/vt/allocator.h>
40#include <ghostty/vt/color.h>
41#include <ghostty/vt/types.h>
42#include <stdbool.h>
43#include <stddef.h>
44#include <stdint.h>
45
46#ifdef __cplusplus
47extern "C" {
48#endif
49
50/**
51 * SGR attribute tags.
52 *
53 * These values identify the type of an SGR attribute in a tagged union.
54 * Use the tag to determine which field in the attribute value union to access.
55 *
56 * @ingroup sgr
57 */
58typedef enum GHOSTTY_ENUM_TYPED {
59 GHOSTTY_SGR_ATTR_UNSET = 0,
60 GHOSTTY_SGR_ATTR_UNKNOWN = 1,
61 GHOSTTY_SGR_ATTR_BOLD = 2,
62 GHOSTTY_SGR_ATTR_RESET_BOLD = 3,
63 GHOSTTY_SGR_ATTR_ITALIC = 4,
64 GHOSTTY_SGR_ATTR_RESET_ITALIC = 5,
65 GHOSTTY_SGR_ATTR_FAINT = 6,
66 GHOSTTY_SGR_ATTR_UNDERLINE = 7,
67 GHOSTTY_SGR_ATTR_UNDERLINE_COLOR = 8,
68 GHOSTTY_SGR_ATTR_UNDERLINE_COLOR_256 = 9,
69 GHOSTTY_SGR_ATTR_RESET_UNDERLINE_COLOR = 10,
70 GHOSTTY_SGR_ATTR_OVERLINE = 11,
71 GHOSTTY_SGR_ATTR_RESET_OVERLINE = 12,
72 GHOSTTY_SGR_ATTR_BLINK = 13,
73 GHOSTTY_SGR_ATTR_RESET_BLINK = 14,
74 GHOSTTY_SGR_ATTR_INVERSE = 15,
75 GHOSTTY_SGR_ATTR_RESET_INVERSE = 16,
76 GHOSTTY_SGR_ATTR_INVISIBLE = 17,
77 GHOSTTY_SGR_ATTR_RESET_INVISIBLE = 18,
78 GHOSTTY_SGR_ATTR_STRIKETHROUGH = 19,
79 GHOSTTY_SGR_ATTR_RESET_STRIKETHROUGH = 20,
80 GHOSTTY_SGR_ATTR_DIRECT_COLOR_FG = 21,
81 GHOSTTY_SGR_ATTR_DIRECT_COLOR_BG = 22,
82 GHOSTTY_SGR_ATTR_BG_8 = 23,
83 GHOSTTY_SGR_ATTR_FG_8 = 24,
84 GHOSTTY_SGR_ATTR_RESET_FG = 25,
85 GHOSTTY_SGR_ATTR_RESET_BG = 26,
86 GHOSTTY_SGR_ATTR_BRIGHT_BG_8 = 27,
87 GHOSTTY_SGR_ATTR_BRIGHT_FG_8 = 28,
88 GHOSTTY_SGR_ATTR_BG_256 = 29,
89 GHOSTTY_SGR_ATTR_FG_256 = 30,
90 GHOSTTY_SGR_ATTR_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
91} GhosttySgrAttributeTag;
92
93/**
94 * Underline style types.
95 *
96 * @ingroup sgr
97 */
98typedef enum GHOSTTY_ENUM_TYPED {
99 GHOSTTY_SGR_UNDERLINE_NONE = 0,
100 GHOSTTY_SGR_UNDERLINE_SINGLE = 1,
101 GHOSTTY_SGR_UNDERLINE_DOUBLE = 2,
102 GHOSTTY_SGR_UNDERLINE_CURLY = 3,
103 GHOSTTY_SGR_UNDERLINE_DOTTED = 4,
104 GHOSTTY_SGR_UNDERLINE_DASHED = 5,
105 GHOSTTY_SGR_UNDERLINE_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
106} GhosttySgrUnderline;
107
108/**
109 * Unknown SGR attribute data.
110 *
111 * Contains the full parameter list and the partial list where parsing
112 * encountered an unknown or invalid sequence.
113 *
114 * @ingroup sgr
115 */
116typedef struct {
117 const uint16_t* full_ptr;
118 size_t full_len;
119 const uint16_t* partial_ptr;
120 size_t partial_len;
121} GhosttySgrUnknown;
122
123/**
124 * SGR attribute value union.
125 *
126 * This union contains all possible attribute values. Use the tag field
127 * to determine which union member is active. Attributes without associated
128 * data (like bold, italic) don't use the union value.
129 *
130 * @ingroup sgr
131 */
132typedef union {
133 GhosttySgrUnknown unknown;
134 GhosttySgrUnderline underline;
135 GhosttyColorRgb underline_color;
136 GhosttyColorPaletteIndex underline_color_256;
137 GhosttyColorRgb direct_color_fg;
138 GhosttyColorRgb direct_color_bg;
139 GhosttyColorPaletteIndex bg_8;
140 GhosttyColorPaletteIndex fg_8;
141 GhosttyColorPaletteIndex bright_bg_8;
142 GhosttyColorPaletteIndex bright_fg_8;
143 GhosttyColorPaletteIndex bg_256;
144 GhosttyColorPaletteIndex fg_256;
145 uint64_t _padding[8];
146} GhosttySgrAttributeValue;
147
148/**
149 * SGR attribute (tagged union).
150 *
151 * A complete SGR attribute with both its type tag and associated value.
152 * Always check the tag field to determine which value union member is valid.
153 *
154 * Attributes without associated data (e.g., GHOSTTY_SGR_ATTR_BOLD) can be
155 * identified by tag alone; the value union is not used for these and
156 * the memory in the value field is undefined.
157 *
158 * @ingroup sgr
159 */
160typedef struct {
161 GhosttySgrAttributeTag tag;
162 GhosttySgrAttributeValue value;
163} GhosttySgrAttribute;
164
165/**
166 * Create a new SGR parser instance.
167 *
168 * Creates a new SGR (Select Graphic Rendition) parser using the provided
169 * allocator. The parser must be freed using ghostty_sgr_free() when
170 * no longer needed.
171 *
172 * @param allocator Pointer to the allocator to use for memory management, or
173 * NULL to use the default allocator
174 * @param parser Pointer to store the created parser handle
175 * @return GHOSTTY_SUCCESS on success, or an error code on failure
176 *
177 * @ingroup sgr
178 */
179GHOSTTY_API GhosttyResult ghostty_sgr_new(const GhosttyAllocator* allocator,
180 GhosttySgrParser* parser);
181
182/**
183 * Free an SGR parser instance.
184 *
185 * Releases all resources associated with the SGR parser. After this call,
186 * the parser handle becomes invalid and must not be used. This includes
187 * any attributes previously returned by ghostty_sgr_next().
188 *
189 * @param parser The parser handle to free (may be NULL)
190 *
191 * @ingroup sgr
192 */
193GHOSTTY_API void ghostty_sgr_free(GhosttySgrParser parser);
194
195/**
196 * Reset an SGR parser instance to the beginning of the parameter list.
197 *
198 * Resets the parser's iteration state without clearing the parameters.
199 * After calling this, ghostty_sgr_next() will start from the beginning
200 * of the parameter list again.
201 *
202 * @param parser The parser handle to reset, must not be NULL
203 *
204 * @ingroup sgr
205 */
206GHOSTTY_API void ghostty_sgr_reset(GhosttySgrParser parser);
207
208/**
209 * Set SGR parameters for parsing.
210 *
211 * Sets the SGR parameter list to parse. Parameters are the numeric values
212 * from a CSI SGR sequence (e.g., for `ESC[1;31m`, params would be {1, 31}).
213 *
214 * The separators array optionally specifies the separator type for each
215 * parameter position. Each byte should be either ';' for semicolon or ':'
216 * for colon. This is needed for certain color formats that use colon
217 * separators (e.g., `ESC[4:3m` for curly underline). Any invalid separator
218 * values are treated as semicolons. The separators array must have the same
219 * length as the params array, if it is not NULL.
220 *
221 * If separators is NULL, all parameters are assumed to be semicolon-separated.
222 *
223 * This function makes an internal copy of the parameter and separator data,
224 * so the caller can safely free or modify the input arrays after this call.
225 *
226 * After calling this function, the parser is automatically reset and ready
227 * to iterate from the beginning.
228 *
229 * @param parser The parser handle, must not be NULL
230 * @param params Array of SGR parameter values
231 * @param separators Optional array of separator characters (';' or ':'), or
232 * NULL
233 * @param len Number of parameters (and separators if provided)
234 * @return GHOSTTY_SUCCESS on success, or an error code on failure
235 *
236 * @ingroup sgr
237 */
238GHOSTTY_API GhosttyResult ghostty_sgr_set_params(GhosttySgrParser parser,
239 const uint16_t* params,
240 const char* separators,
241 size_t len);
242
243/**
244 * Get the next SGR attribute.
245 *
246 * Parses and returns the next attribute from the parameter list.
247 * Call this function repeatedly until it returns false to process
248 * all attributes in the sequence.
249 *
250 * @param parser The parser handle, must not be NULL
251 * @param attr Pointer to store the next attribute
252 * @return true if an attribute was returned, false if no more attributes
253 *
254 * @ingroup sgr
255 */
256GHOSTTY_API bool ghostty_sgr_next(GhosttySgrParser parser, GhosttySgrAttribute* attr);
257
258/**
259 * Get the full parameter list from an unknown SGR attribute.
260 *
261 * This function retrieves the full parameter list that was provided to the
262 * parser when an unknown attribute was encountered. Primarily useful in
263 * WebAssembly environments where accessing struct fields directly is difficult.
264 *
265 * @param unknown The unknown attribute data
266 * @param ptr Pointer to store the pointer to the parameter array (may be NULL)
267 * @return The length of the full parameter array
268 *
269 * @ingroup sgr
270 */
271GHOSTTY_API size_t ghostty_sgr_unknown_full(GhosttySgrUnknown unknown,
272 const uint16_t** ptr);
273
274/**
275 * Get the partial parameter list from an unknown SGR attribute.
276 *
277 * This function retrieves the partial parameter list where parsing stopped
278 * when an unknown attribute was encountered. Primarily useful in WebAssembly
279 * environments where accessing struct fields directly is difficult.
280 *
281 * @param unknown The unknown attribute data
282 * @param ptr Pointer to store the pointer to the parameter array (may be NULL)
283 * @return The length of the partial parameter array
284 *
285 * @ingroup sgr
286 */
287GHOSTTY_API size_t ghostty_sgr_unknown_partial(GhosttySgrUnknown unknown,
288 const uint16_t** ptr);
289
290/**
291 * Get the tag from an SGR attribute.
292 *
293 * This function extracts the tag that identifies which type of attribute
294 * this is. Primarily useful in WebAssembly environments where accessing
295 * struct fields directly is difficult.
296 *
297 * @param attr The SGR attribute
298 * @return The attribute tag
299 *
300 * @ingroup sgr
301 */
302GHOSTTY_API GhosttySgrAttributeTag ghostty_sgr_attribute_tag(GhosttySgrAttribute attr);
303
304/**
305 * Get the value from an SGR attribute.
306 *
307 * This function returns a pointer to the value union from an SGR attribute. Use
308 * the tag to determine which field of the union is valid. Primarily useful in
309 * WebAssembly environments where accessing struct fields directly is difficult.
310 *
311 * @param attr Pointer to the SGR attribute
312 * @return Pointer to the attribute value union
313 *
314 * @ingroup sgr
315 */
316GHOSTTY_API GhosttySgrAttributeValue* ghostty_sgr_attribute_value(
317 GhosttySgrAttribute* attr);
318
319#ifdef __wasm__
320/**
321 * Allocate memory for an SGR attribute (WebAssembly only).
322 *
323 * This is a convenience function for WebAssembly environments to allocate
324 * memory for an SGR attribute structure that can be passed to ghostty_sgr_next.
325 *
326 * @return Pointer to the allocated attribute structure
327 *
328 * @ingroup wasm
329 */
330GHOSTTY_API GhosttySgrAttribute* ghostty_wasm_alloc_sgr_attribute(void);
331
332/**
333 * Free memory for an SGR attribute (WebAssembly only).
334 *
335 * Frees memory allocated by ghostty_wasm_alloc_sgr_attribute.
336 *
337 * @param attr Pointer to the attribute structure to free
338 *
339 * @ingroup wasm
340 */
341GHOSTTY_API void ghostty_wasm_free_sgr_attribute(GhosttySgrAttribute* attr);
342#endif
343
344#ifdef __cplusplus
345}
346#endif
347
348/** @} */
349
350#endif /* GHOSTTY_VT_SGR_H */
native/libghostty-vt/include/ghostty/vt/size_report.h created+101
......@@ -0,0 +1,101 @@
1/**
2 * @file size_report.h
3 *
4 * Size report encoding - encode terminal size reports into escape sequences.
5 */
6
7#ifndef GHOSTTY_VT_SIZE_REPORT_H
8#define GHOSTTY_VT_SIZE_REPORT_H
9
10/** @defgroup size_report Size Report Encoding
11 *
12 * Utilities for encoding terminal size reports into escape sequences,
13 * supporting in-band size reports (mode 2048) and XTWINOPS responses
14 * (CSI 14 t, CSI 16 t, CSI 18 t).
15 *
16 * ## Basic Usage
17 *
18 * Use ghostty_size_report_encode() to encode a size report into a
19 * caller-provided buffer. If the buffer is too small, the function
20 * returns GHOSTTY_OUT_OF_SPACE and sets the required size in the
21 * output parameter.
22 *
23 * ## Example
24 *
25 * @snippet c-vt-size-report/src/main.c size-report-encode
26 *
27 * @{
28 */
29
30#include <stddef.h>
31#include <stdint.h>
32#include <ghostty/vt/types.h>
33
34#ifdef __cplusplus
35extern "C" {
36#endif
37
38/**
39 * Size report style.
40 *
41 * Determines the output format for the terminal size report.
42 */
43typedef enum GHOSTTY_ENUM_TYPED {
44 /** In-band size report (mode 2048): ESC [ 48 ; rows ; cols ; height ; width t */
45 GHOSTTY_SIZE_REPORT_MODE_2048 = 0,
46 /** XTWINOPS text area size in pixels: ESC [ 4 ; height ; width t */
47 GHOSTTY_SIZE_REPORT_CSI_14_T = 1,
48 /** XTWINOPS cell size in pixels: ESC [ 6 ; height ; width t */
49 GHOSTTY_SIZE_REPORT_CSI_16_T = 2,
50 /** XTWINOPS text area size in characters: ESC [ 8 ; rows ; cols t */
51 GHOSTTY_SIZE_REPORT_CSI_18_T = 3,
52 GHOSTTY_SIZE_REPORT_STYLE_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
53} GhosttySizeReportStyle;
54
55/**
56 * Terminal size information for encoding size reports.
57 */
58typedef struct {
59 /** Terminal row count in cells. */
60 uint16_t rows;
61 /** Terminal column count in cells. */
62 uint16_t columns;
63 /** Width of a single terminal cell in pixels. */
64 uint32_t cell_width;
65 /** Height of a single terminal cell in pixels. */
66 uint32_t cell_height;
67} GhosttySizeReportSize;
68
69/**
70 * Encode a terminal size report into an escape sequence.
71 *
72 * Encodes a size report in the format specified by @p style into the
73 * provided buffer.
74 *
75 * If the buffer is too small, the function returns GHOSTTY_OUT_OF_SPACE
76 * and writes the required buffer size to @p out_written. The caller can
77 * then retry with a sufficiently sized buffer.
78 *
79 * @param style The size report format to encode
80 * @param size Terminal size information
81 * @param buf Output buffer to write the encoded sequence into (may be NULL)
82 * @param buf_len Size of the output buffer in bytes
83 * @param[out] out_written On success, the number of bytes written. On
84 * GHOSTTY_OUT_OF_SPACE, the required buffer size.
85 * @return GHOSTTY_SUCCESS on success, GHOSTTY_OUT_OF_SPACE if the buffer
86 * is too small
87 */
88GHOSTTY_API GhosttyResult ghostty_size_report_encode(
89 GhosttySizeReportStyle style,
90 GhosttySizeReportSize size,
91 char* buf,
92 size_t buf_len,
93 size_t* out_written);
94
95#ifdef __cplusplus
96}
97#endif
98
99/** @} */
100
101#endif /* GHOSTTY_VT_SIZE_REPORT_H */
native/libghostty-vt/include/ghostty/vt/style.h created+139
......@@ -0,0 +1,139 @@
1/**
2 * @file style.h
3 *
4 * Terminal cell style types.
5 */
6
7#ifndef GHOSTTY_VT_STYLE_H
8#define GHOSTTY_VT_STYLE_H
9
10#include <ghostty/vt/color.h>
11#include <ghostty/vt/types.h>
12#include <stdbool.h>
13#include <stddef.h>
14#include <stdint.h>
15
16#ifdef __cplusplus
17extern "C" {
18#endif
19
20/** @defgroup style Style
21 *
22 * Terminal cell style attributes.
23 *
24 * A style describes the visual attributes of a terminal cell, including
25 * foreground, background, and underline colors, as well as flags for
26 * bold, italic, underline, and other text decorations.
27 *
28 * @{
29 */
30
31/**
32 * Style identifier type.
33 *
34 * Used to look up the full style from a grid reference.
35 * Obtain this from a cell via GHOSTTY_CELL_DATA_STYLE_ID.
36 *
37 * @ingroup style
38 */
39typedef uint16_t GhosttyStyleId;
40
41/**
42 * Style color tags.
43 *
44 * These values identify the type of color in a style color.
45 * Use the tag to determine which field in the color value union to access.
46 *
47 * @ingroup style
48 */
49typedef enum GHOSTTY_ENUM_TYPED {
50 GHOSTTY_STYLE_COLOR_NONE = 0,
51 GHOSTTY_STYLE_COLOR_PALETTE = 1,
52 GHOSTTY_STYLE_COLOR_RGB = 2,
53 GHOSTTY_STYLE_COLOR_TAG_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
54 } GhosttyStyleColorTag;
55
56/**
57 * Style color value union.
58 *
59 * Use the tag to determine which field is active.
60 *
61 * @ingroup style
62 */
63typedef union {
64 GhosttyColorPaletteIndex palette;
65 GhosttyColorRgb rgb;
66 uint64_t _padding;
67} GhosttyStyleColorValue;
68
69/**
70 * Style color (tagged union).
71 *
72 * A color used in a style attribute. Can be unset (none), a palette
73 * index, or a direct RGB value.
74 *
75 * @ingroup style
76 */
77typedef struct {
78 GhosttyStyleColorTag tag;
79 GhosttyStyleColorValue value;
80} GhosttyStyleColor;
81
82/**
83 * Terminal cell style.
84 *
85 * Describes the complete visual style for a terminal cell, including
86 * foreground, background, and underline colors, as well as text
87 * decoration flags. The underline field uses the same values as
88 * GhosttySgrUnderline.
89 *
90 * This is a sized struct. Use GHOSTTY_INIT_SIZED() to initialize it.
91 *
92 * @ingroup style
93 */
94typedef struct {
95 size_t size;
96 GhosttyStyleColor fg_color;
97 GhosttyStyleColor bg_color;
98 GhosttyStyleColor underline_color;
99 bool bold;
100 bool italic;
101 bool faint;
102 bool blink;
103 bool inverse;
104 bool invisible;
105 bool strikethrough;
106 bool overline;
107 int underline; /**< One of GHOSTTY_SGR_UNDERLINE_* values */
108} GhosttyStyle;
109
110/**
111 * Get the default style.
112 *
113 * Initializes the style to the default values (no colors, no flags).
114 *
115 * @param style Pointer to the style to initialize
116 *
117 * @ingroup style
118 */
119GHOSTTY_API void ghostty_style_default(GhosttyStyle* style);
120
121/**
122 * Check if a style is the default style.
123 *
124 * Returns true if all colors are unset and all flags are off.
125 *
126 * @param style Pointer to the style to check
127 * @return true if the style is the default style
128 *
129 * @ingroup style
130 */
131GHOSTTY_API bool ghostty_style_is_default(const GhosttyStyle* style);
132
133#ifdef __cplusplus
134}
135#endif
136
137/** @} */
138
139#endif /* GHOSTTY_VT_STYLE_H */
native/libghostty-vt/include/ghostty/vt/sys.h created+210
......@@ -0,0 +1,210 @@
1/**
2 * @file sys.h
3 *
4 * System interface - runtime-swappable implementations for external dependencies.
5 */
6
7#ifndef GHOSTTY_VT_SYS_H
8#define GHOSTTY_VT_SYS_H
9
10#include <stdbool.h>
11#include <stddef.h>
12#include <stdint.h>
13#include <ghostty/vt/types.h>
14#include <ghostty/vt/allocator.h>
15
16/** @defgroup sys System Interface
17 *
18 * Runtime-swappable function pointers for operations that depend on
19 * external implementations (e.g. image decoding).
20 *
21 * These are process-global settings that must be configured at startup
22 * before any terminal functionality that depends on them is used.
23 * Setting these enables various optional features of the terminal. For
24 * example, setting a PNG decoder enables PNG image support in the Kitty
25 * Graphics Protocol.
26 *
27 * Use ghostty_sys_set() with a `GhosttySysOption` to install or clear
28 * an implementation. Passing NULL as the value clears the implementation
29 * and disables the corresponding feature.
30 *
31 * ## Example
32 *
33 * ### Defining a PNG decode callback
34 * @snippet c-vt-kitty-graphics/src/main.c kitty-graphics-decode-png
35 *
36 * ### Installing the callback and sending a PNG image
37 * @snippet c-vt-kitty-graphics/src/main.c kitty-graphics-main
38 *
39 * @{
40 */
41
42#ifdef __cplusplus
43extern "C" {
44#endif
45
46/**
47 * Result of decoding an image.
48 *
49 * The `data` buffer must be allocated through the allocator provided to
50 * the decode callback. The library takes ownership and will free it
51 * with the same allocator.
52 */
53typedef struct {
54 /** Image width in pixels. */
55 uint32_t width;
56
57 /** Image height in pixels. */
58 uint32_t height;
59
60 /** Pointer to the decoded RGBA pixel data. */
61 uint8_t* data;
62
63 /** Length of the pixel data in bytes. */
64 size_t data_len;
65} GhosttySysImage;
66
67/**
68 * Log severity levels for the log callback.
69 */
70typedef enum GHOSTTY_ENUM_TYPED {
71 GHOSTTY_SYS_LOG_LEVEL_ERROR = 0,
72 GHOSTTY_SYS_LOG_LEVEL_WARNING = 1,
73 GHOSTTY_SYS_LOG_LEVEL_INFO = 2,
74 GHOSTTY_SYS_LOG_LEVEL_DEBUG = 3,
75 GHOSTTY_SYS_LOG_LEVEL_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
76} GhosttySysLogLevel;
77
78/**
79 * Callback type for logging.
80 *
81 * When installed, internal library log messages are delivered through
82 * this callback instead of being discarded. The embedder is responsible
83 * for formatting and routing log output.
84 *
85 * @p scope is the log scope name as UTF-8 bytes (e.g. "osc", "kitty").
86 * When the log is unscoped (default scope), @p scope_len is 0.
87 *
88 * All pointer arguments are only valid for the duration of the callback.
89 * The callback must be safe to call from any thread.
90 *
91 * @param userdata The userdata pointer set via GHOSTTY_SYS_OPT_USERDATA
92 * @param level The severity level of the log message
93 * @param scope Pointer to the scope name bytes
94 * @param scope_len Length of the scope name in bytes
95 * @param message Pointer to the log message bytes
96 * @param message_len Length of the log message in bytes
97 */
98typedef void (*GhosttySysLogFn)(
99 void* userdata,
100 GhosttySysLogLevel level,
101 const uint8_t* scope,
102 size_t scope_len,
103 const uint8_t* message,
104 size_t message_len);
105
106/**
107 * Callback type for PNG decoding.
108 *
109 * Decodes raw PNG data into RGBA pixels. The output pixel data must be
110 * allocated through the provided allocator. The library takes ownership
111 * of the buffer and will free it with the same allocator.
112 *
113 * @param userdata The userdata pointer set via GHOSTTY_SYS_OPT_USERDATA
114 * @param allocator The allocator to use for the output pixel buffer
115 * @param data Pointer to the raw PNG data
116 * @param data_len Length of the raw PNG data in bytes
117 * @param[out] out On success, filled with the decoded image
118 * @return true on success, false on failure
119 */
120typedef bool (*GhosttySysDecodePngFn)(
121 void* userdata,
122 const GhosttyAllocator* allocator,
123 const uint8_t* data,
124 size_t data_len,
125 GhosttySysImage* out);
126
127/**
128 * System option identifiers for ghostty_sys_set().
129 */
130typedef enum GHOSTTY_ENUM_TYPED {
131 /**
132 * Set the userdata pointer passed to all sys callbacks.
133 *
134 * Input type: void* (or NULL)
135 */
136 GHOSTTY_SYS_OPT_USERDATA = 0,
137
138 /**
139 * Set the PNG decode function.
140 *
141 * When set, the terminal can accept PNG images via the Kitty
142 * Graphics Protocol. When cleared (NULL value), PNG decoding is
143 * unsupported and PNG image data will be rejected.
144 *
145 * Input type: GhosttySysDecodePngFn (function pointer, or NULL)
146 */
147 GHOSTTY_SYS_OPT_DECODE_PNG = 1,
148
149 /**
150 * Set the log callback.
151 *
152 * When set, internal library log messages are delivered to this
153 * callback. When cleared (NULL value), log messages are silently
154 * discarded.
155 *
156 * Use ghostty_sys_log_stderr as a convenience callback that
157 * writes formatted messages to stderr.
158 *
159 * Which log levels are emitted depends on the build mode of the
160 * library and is not configurable at runtime. Debug builds emit
161 * all levels (debug and above). Release builds emit info and
162 * above; debug-level messages are compiled out entirely and will
163 * never reach the callback.
164 *
165 * Input type: GhosttySysLogFn (function pointer, or NULL)
166 */
167 GHOSTTY_SYS_OPT_LOG = 2,
168 GHOSTTY_SYS_OPT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
169} GhosttySysOption;
170
171/**
172 * Set a system-level option.
173 *
174 * Configures a process-global implementation function. These should be
175 * set once at startup before using any terminal functionality that
176 * depends on them.
177 *
178 * @param option The option to set
179 * @param value Pointer to the value (type depends on the option),
180 * or NULL to clear it
181 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the
182 * option is not recognized
183 */
184GHOSTTY_API GhosttyResult ghostty_sys_set(GhosttySysOption option,
185 const void* value);
186
187/**
188 * Built-in log callback that writes to stderr.
189 *
190 * Formats each message as "[level](scope): message\n".
191 * Can be passed directly to ghostty_sys_set():
192 *
193 * @code
194 * ghostty_sys_set(GHOSTTY_SYS_OPT_LOG, &ghostty_sys_log_stderr);
195 * @endcode
196 */
197GHOSTTY_API void ghostty_sys_log_stderr(void* userdata,
198 GhosttySysLogLevel level,
199 const uint8_t* scope,
200 size_t scope_len,
201 const uint8_t* message,
202 size_t message_len);
203
204#ifdef __cplusplus
205}
206#endif
207
208/** @} */
209
210#endif /* GHOSTTY_VT_SYS_H */
native/libghostty-vt/include/ghostty/vt/terminal.h created+1322
......@@ -0,0 +1,1322 @@
1/**
2 * @file terminal.h
3 *
4 * Complete terminal emulator state and rendering.
5 */
6
7#ifndef GHOSTTY_VT_TERMINAL_H
8#define GHOSTTY_VT_TERMINAL_H
9
10#include <stdbool.h>
11#include <stddef.h>
12#include <stdint.h>
13#include <ghostty/vt/types.h>
14#include <ghostty/vt/allocator.h>
15#include <ghostty/vt/device.h>
16#include <ghostty/vt/modes.h>
17#include <ghostty/vt/size_report.h>
18#include <ghostty/vt/grid_ref.h>
19#include <ghostty/vt/kitty_graphics.h>
20#include <ghostty/vt/screen.h>
21#include <ghostty/vt/point.h>
22#include <ghostty/vt/selection.h>
23#include <ghostty/vt/style.h>
24
25#ifdef __cplusplus
26extern "C" {
27#endif
28
29/** @defgroup terminal Terminal
30 *
31 * Complete terminal emulator state and rendering.
32 *
33 * A terminal instance manages the full emulator state including the screen,
34 * scrollback, cursor, styles, modes, and VT stream processing.
35 *
36 * Once a terminal session is up and running, you can configure a key encoder
37 * to write keyboard input via ghostty_key_encoder_setopt_from_terminal().
38 *
39 * ### Example: VT stream processing
40 * @snippet c-vt-stream/src/main.c vt-stream-init
41 * @snippet c-vt-stream/src/main.c vt-stream-write
42 *
43 * ## Effects
44 *
45 * By default, the terminal sequence processing with ghostty_terminal_vt_write()
46 * only process sequences that directly affect terminal state and
47 * ignores sequences that have side effect behavior or require responses.
48 * These sequences include things like bell characters, title changes, device
49 * attributes queries, and more. To handle these sequences, the embedder
50 * must configure "effects."
51 *
52 * Effects are callbacks that the terminal invokes in response to VT
53 * sequences processed during ghostty_terminal_vt_write(). They let the
54 * embedding application react to terminal-initiated events such as bell
55 * characters, title changes, device status report responses, and more.
56 *
57 * Each effect is registered with ghostty_terminal_set() using the
58 * corresponding `GhosttyTerminalOption` identifier. A `NULL` value
59 * pointer clears the callback and disables the effect.
60 *
61 * A userdata pointer can be attached via `GHOSTTY_TERMINAL_OPT_USERDATA`
62 * and is passed to every callback, allowing callers to route events
63 * back to their own application state without global variables.
64 * You cannot specify different userdata for different callbacks.
65 *
66 * All callbacks are invoked synchronously during
67 * ghostty_terminal_vt_write(). Callbacks **must not** call
68 * ghostty_terminal_vt_write() on the same terminal (no reentrancy).
69 * And callbacks must be very careful to not block for too long or perform
70 * expensive operations, since they are blocking further IO processing.
71 *
72 * The available effects are:
73 *
74 * | Option | Callback Type | Trigger |
75 * |-----------------------------------------|-----------------------------------|-------------------------------------------|
76 * | `GHOSTTY_TERMINAL_OPT_WRITE_PTY` | `GhosttyTerminalWritePtyFn` | Query responses written back to the pty |
77 * | `GHOSTTY_TERMINAL_OPT_BELL` | `GhosttyTerminalBellFn` | BEL character (0x07) |
78 * | `GHOSTTY_TERMINAL_OPT_TITLE_CHANGED` | `GhosttyTerminalTitleChangedFn` | Title change via OSC 0 / OSC 2 |
79 * | `GHOSTTY_TERMINAL_OPT_PWD_CHANGED` | `GhosttyTerminalPwdChangedFn` | Pwd change via OSC 7 / OSC 9 / OSC 1337 |
80 * | `GHOSTTY_TERMINAL_OPT_ENQUIRY` | `GhosttyTerminalEnquiryFn` | ENQ character (0x05) |
81 * | `GHOSTTY_TERMINAL_OPT_XTVERSION` | `GhosttyTerminalXtversionFn` | XTVERSION query (CSI > q) |
82 * | `GHOSTTY_TERMINAL_OPT_SIZE` | `GhosttyTerminalSizeFn` | XTWINOPS size query (CSI 14/16/18 t) |
83 * | `GHOSTTY_TERMINAL_OPT_COLOR_SCHEME` | `GhosttyTerminalColorSchemeFn` | Color scheme query (CSI ? 996 n) |
84 * | `GHOSTTY_TERMINAL_OPT_DEVICE_ATTRIBUTES`| `GhosttyTerminalDeviceAttributesFn`| Device attributes query (CSI c / > c / = c)|
85 *
86 * ### Defining a write_pty callback
87 * @snippet c-vt-effects/src/main.c effects-write-pty
88 *
89 * ### Defining a bell callback
90 * @snippet c-vt-effects/src/main.c effects-bell
91 *
92 * ### Defining a title_changed callback
93 * @snippet c-vt-effects/src/main.c effects-title-changed
94 *
95 * ### Registering effects and processing VT data
96 * @snippet c-vt-effects/src/main.c effects-register
97 *
98 * ## Color Theme
99 *
100 * The terminal maintains a set of colors used for rendering: a foreground
101 * color, a background color, a cursor color, and a 256-color palette. Each
102 * of these has two layers: a **default** value set by the embedder, and an
103 * **override** value that programs running in the terminal can set via OSC
104 * escape sequences (e.g. OSC 10/11/12 for foreground/background/cursor,
105 * OSC 4 for individual palette entries).
106 *
107 * ### Default Colors
108 *
109 * Use ghostty_terminal_set() with the color options to configure the
110 * default colors. These represent the theme or configuration chosen by
111 * the embedder. Passing `NULL` clears the default, leaving the color
112 * unset.
113 *
114 * | Option | Input Type | Description |
115 * |-----------------------------------------|-------------------------|--------------------------------------|
116 * | `GHOSTTY_TERMINAL_OPT_COLOR_FOREGROUND` | `GhosttyColorRgb*` | Default foreground color |
117 * | `GHOSTTY_TERMINAL_OPT_COLOR_BACKGROUND` | `GhosttyColorRgb*` | Default background color |
118 * | `GHOSTTY_TERMINAL_OPT_COLOR_CURSOR` | `GhosttyColorRgb*` | Default cursor color |
119 * | `GHOSTTY_TERMINAL_OPT_COLOR_PALETTE` | `GhosttyColorRgb[256]*` | Default 256-color palette |
120 *
121 * For the palette, passing `NULL` resets to the built-in default palette.
122 * The palette set operation preserves any per-index OSC overrides that
123 * programs have applied; only unmodified indices are updated.
124 *
125 * ### Reading colors
126 *
127 * Use ghostty_terminal_get() to read colors. There are two variants for
128 * each color: the **effective** value (which returns the OSC override if
129 * one is active, otherwise the default) and the **default** value (which
130 * ignores any OSC overrides).
131 *
132 * | Data | Output Type | Description |
133 * |---------------------------------------------------|-------------------------|------------------------------------------------|
134 * | `GHOSTTY_TERMINAL_DATA_COLOR_FOREGROUND` | `GhosttyColorRgb*` | Effective foreground (override or default) |
135 * | `GHOSTTY_TERMINAL_DATA_COLOR_BACKGROUND` | `GhosttyColorRgb*` | Effective background (override or default) |
136 * | `GHOSTTY_TERMINAL_DATA_COLOR_CURSOR` | `GhosttyColorRgb*` | Effective cursor (override or default) |
137 * | `GHOSTTY_TERMINAL_DATA_COLOR_PALETTE` | `GhosttyColorRgb[256]*` | Current palette (with any OSC overrides) |
138 * | `GHOSTTY_TERMINAL_DATA_COLOR_FOREGROUND_DEFAULT` | `GhosttyColorRgb*` | Default foreground only (ignores OSC override) |
139 * | `GHOSTTY_TERMINAL_DATA_COLOR_BACKGROUND_DEFAULT` | `GhosttyColorRgb*` | Default background only (ignores OSC override) |
140 * | `GHOSTTY_TERMINAL_DATA_COLOR_CURSOR_DEFAULT` | `GhosttyColorRgb*` | Default cursor only (ignores OSC override) |
141 * | `GHOSTTY_TERMINAL_DATA_COLOR_PALETTE_DEFAULT` | `GhosttyColorRgb[256]*` | Default palette only (ignores OSC overrides) |
142 *
143 * For foreground, background, and cursor colors, the getters return
144 * `GHOSTTY_NO_VALUE` if no color is configured (neither a default nor an
145 * OSC override). The palette getters always succeed since the palette
146 * always has a value (the built-in default if nothing else is set).
147 *
148 * ### Setting a color theme
149 * @snippet c-vt-colors/src/main.c colors-set-defaults
150 *
151 * ### Reading effective and default colors
152 * @snippet c-vt-colors/src/main.c colors-read
153 *
154 * ### Full example with OSC overrides
155 * @snippet c-vt-colors/src/main.c colors-main
156 *
157 * @{
158 */
159
160/**
161 * Terminal initialization options.
162 *
163 * @ingroup terminal
164 */
165typedef struct {
166 /** Terminal width in cells. Must be greater than zero. */
167 uint16_t cols;
168
169 /** Terminal height in cells. Must be greater than zero. */
170 uint16_t rows;
171
172 /** Maximum number of lines to keep in scrollback history. */
173 size_t max_scrollback;
174
175 // TODO: Consider ABI compatibility implications of this struct.
176 // We may want to artificially pad it significantly to support
177 // future options.
178} GhosttyTerminalOptions;
179
180/**
181 * Scroll viewport behavior tag.
182 *
183 * @ingroup terminal
184 */
185typedef enum GHOSTTY_ENUM_TYPED {
186 /** Scroll to the top of the scrollback. */
187 GHOSTTY_SCROLL_VIEWPORT_TOP,
188
189 /** Scroll to the bottom (active area). */
190 GHOSTTY_SCROLL_VIEWPORT_BOTTOM,
191
192 /** Scroll by a delta amount (up is negative). */
193 GHOSTTY_SCROLL_VIEWPORT_DELTA,
194 GHOSTTY_SCROLL_VIEWPORT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
195} GhosttyTerminalScrollViewportTag;
196
197/**
198 * Scroll viewport value.
199 *
200 * @ingroup terminal
201 */
202typedef union {
203 /** Scroll delta (only used with GHOSTTY_SCROLL_VIEWPORT_DELTA). Up is negative. */
204 intptr_t delta;
205
206 /** Padding for ABI compatibility. Do not use. */
207 uint64_t _padding[2];
208} GhosttyTerminalScrollViewportValue;
209
210/**
211 * Tagged union for scroll viewport behavior.
212 *
213 * @ingroup terminal
214 */
215typedef struct {
216 GhosttyTerminalScrollViewportTag tag;
217 GhosttyTerminalScrollViewportValue value;
218} GhosttyTerminalScrollViewport;
219
220/**
221 * Terminal screen identifier.
222 *
223 * Identifies which screen buffer is active in the terminal.
224 *
225 * @ingroup terminal
226 */
227typedef enum GHOSTTY_ENUM_TYPED {
228 /** The primary (normal) screen. */
229 GHOSTTY_TERMINAL_SCREEN_PRIMARY = 0,
230
231 /** The alternate screen. */
232 GHOSTTY_TERMINAL_SCREEN_ALTERNATE = 1,
233 GHOSTTY_TERMINAL_SCREEN_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
234} GhosttyTerminalScreen;
235
236/**
237 * Visual style of the terminal cursor.
238 *
239 * @ingroup terminal
240 */
241typedef enum GHOSTTY_ENUM_TYPED {
242 /** Bar cursor (DECSCUSR 5, 6). */
243 GHOSTTY_TERMINAL_CURSOR_STYLE_BAR = 0,
244
245 /** Block cursor (DECSCUSR 1, 2). */
246 GHOSTTY_TERMINAL_CURSOR_STYLE_BLOCK = 1,
247
248 /** Underline cursor (DECSCUSR 3, 4). */
249 GHOSTTY_TERMINAL_CURSOR_STYLE_UNDERLINE = 2,
250
251 /** Hollow block cursor. */
252 GHOSTTY_TERMINAL_CURSOR_STYLE_BLOCK_HOLLOW = 3,
253 GHOSTTY_TERMINAL_CURSOR_STYLE_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
254} GhosttyTerminalCursorStyle;
255
256/**
257 * Scrollbar state for the terminal viewport.
258 *
259 * Represents the scrollable area dimensions needed to render a scrollbar.
260 *
261 * @ingroup terminal
262 */
263typedef struct {
264 /** Total size of the scrollable area in rows. */
265 uint64_t total;
266
267 /** Offset into the total area that the viewport is at. */
268 uint64_t offset;
269
270 /** Length of the visible area in rows. */
271 uint64_t len;
272} GhosttyTerminalScrollbar;
273
274/**
275 * Callback function type for bell.
276 *
277 * Called when the terminal receives a BEL character (0x07).
278 *
279 * @param terminal The terminal handle
280 * @param userdata The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
281 *
282 * @ingroup terminal
283 */
284typedef void (*GhosttyTerminalBellFn)(GhosttyTerminal terminal,
285 void* userdata);
286
287/**
288 * Callback function type for color scheme queries (CSI ? 996 n).
289 *
290 * Called when the terminal receives a color scheme device status report
291 * query. Return true and fill *out_scheme with the current color scheme,
292 * or return false to silently ignore the query.
293 *
294 * @param terminal The terminal handle
295 * @param userdata The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
296 * @param[out] out_scheme Pointer to store the current color scheme
297 * @return true if the color scheme was filled, false to ignore the query
298 *
299 * @ingroup terminal
300 */
301typedef bool (*GhosttyTerminalColorSchemeFn)(GhosttyTerminal terminal,
302 void* userdata,
303 GhosttyColorScheme* out_scheme);
304
305/**
306 * Callback function type for device attributes queries (DA1/DA2/DA3).
307 *
308 * Called when the terminal receives a device attributes query (CSI c,
309 * CSI > c, or CSI = c). Return true and fill *out_attrs with the
310 * response data, or return false to silently ignore the query.
311 *
312 * The terminal uses whichever sub-struct (primary, secondary, tertiary)
313 * matches the request type, but all three should be filled for simplicity.
314 *
315 * @param terminal The terminal handle
316 * @param userdata The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
317 * @param[out] out_attrs Pointer to store the device attributes response
318 * @return true if attributes were filled, false to ignore the query
319 *
320 * @ingroup terminal
321 */
322typedef bool (*GhosttyTerminalDeviceAttributesFn)(GhosttyTerminal terminal,
323 void* userdata,
324 GhosttyDeviceAttributes* out_attrs);
325
326/**
327 * Callback function type for enquiry (ENQ, 0x05).
328 *
329 * Called when the terminal receives an ENQ character. Return the
330 * response bytes as a GhosttyString. The memory must remain valid
331 * until the callback returns. Return a zero-length string to send
332 * no response.
333 *
334 * @param terminal The terminal handle
335 * @param userdata The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
336 * @return The response bytes to write back to the pty
337 *
338 * @ingroup terminal
339 */
340typedef GhosttyString (*GhosttyTerminalEnquiryFn)(GhosttyTerminal terminal,
341 void* userdata);
342
343/**
344 * Callback function type for size queries (XTWINOPS).
345 *
346 * Called in response to XTWINOPS size queries (CSI 14/16/18 t).
347 * Return true and fill *out_size with the current terminal geometry,
348 * or return false to silently ignore the query.
349 *
350 * @param terminal The terminal handle
351 * @param userdata The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
352 * @param[out] out_size Pointer to store the terminal size information
353 * @return true if size was filled, false to ignore the query
354 *
355 * @ingroup terminal
356 */
357typedef bool (*GhosttyTerminalSizeFn)(GhosttyTerminal terminal,
358 void* userdata,
359 GhosttySizeReportSize* out_size);
360
361/**
362 * Callback function type for title_changed.
363 *
364 * Called when the terminal title changes via escape sequences
365 * (e.g. OSC 0 or OSC 2). The new title can be queried from the
366 * terminal after the callback returns.
367 *
368 * @param terminal The terminal handle
369 * @param userdata The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
370 *
371 * @ingroup terminal
372 */
373typedef void (*GhosttyTerminalTitleChangedFn)(GhosttyTerminal terminal,
374 void* userdata);
375
376/**
377 * Callback function type for pwd_changed.
378 *
379 * Called when the terminal pwd (current working directory) changes via
380 * escape sequences: OSC 7 (file:// URI), OSC 9 (ConEmu CurrentDir), or
381 * OSC 1337 CurrentDir (iTerm2). Use ghostty_terminal_get() with
382 * GHOSTTY_TERMINAL_DATA_PWD inside the callback to read the new value.
383 *
384 * The terminal stores whatever bytes the shell emitted, without parsing.
385 * That means for OSC 7 the value is the raw URI (typically file://...);
386 * for OSC 9/OSC 1337 it is typically a bare path. The embedder is
387 * responsible for decoding any URI scheme or host if it cares about them.
388 *
389 * The callback also fires when the shell clears the pwd (e.g. an empty
390 * OSC 7). In that case GHOSTTY_TERMINAL_DATA_PWD returns a zero-length
391 * string.
392 *
393 * @param terminal The terminal handle
394 * @param userdata The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
395 *
396 * @ingroup terminal
397 */
398typedef void (*GhosttyTerminalPwdChangedFn)(GhosttyTerminal terminal,
399 void* userdata);
400
401/**
402 * Callback function type for write_pty.
403 *
404 * Called when the terminal needs to write data back to the pty, for
405 * example in response to a device status report or mode query. The
406 * data is only valid for the duration of the call; callers must copy
407 * it if it needs to persist.
408 *
409 * @param terminal The terminal handle
410 * @param userdata The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
411 * @param data Pointer to the response bytes
412 * @param len Length of the response in bytes
413 *
414 * @ingroup terminal
415 */
416typedef void (*GhosttyTerminalWritePtyFn)(GhosttyTerminal terminal,
417 void* userdata,
418 const uint8_t* data,
419 size_t len);
420
421/**
422 * Callback function type for XTVERSION.
423 *
424 * Called when the terminal receives an XTVERSION query (CSI > q).
425 * Return the version string (e.g. "myterm 1.0") as a GhosttyString.
426 * The memory must remain valid until the callback returns. Return a
427 * zero-length string to report the default "libghostty" version.
428 *
429 * @param terminal The terminal handle
430 * @param userdata The userdata pointer set via GHOSTTY_TERMINAL_OPT_USERDATA
431 * @return The version string to report
432 *
433 * @ingroup terminal
434 */
435typedef GhosttyString (*GhosttyTerminalXtversionFn)(GhosttyTerminal terminal,
436 void* userdata);
437
438/**
439 * Terminal option identifiers.
440 *
441 * These values are used with ghostty_terminal_set() to configure
442 * terminal callbacks and associated state.
443 *
444 * @ingroup terminal
445 */
446typedef enum GHOSTTY_ENUM_TYPED {
447 /**
448 * Opaque userdata pointer passed to all callbacks.
449 *
450 * Input type: void*
451 */
452 GHOSTTY_TERMINAL_OPT_USERDATA = 0,
453
454 /**
455 * Callback invoked when the terminal needs to write data back
456 * to the pty (e.g. in response to a DECRQM query or device
457 * status report). Set to NULL to ignore such sequences.
458 *
459 * Input type: GhosttyTerminalWritePtyFn
460 */
461 GHOSTTY_TERMINAL_OPT_WRITE_PTY = 1,
462
463 /**
464 * Callback invoked when the terminal receives a BEL character
465 * (0x07). Set to NULL to ignore bell events.
466 *
467 * Input type: GhosttyTerminalBellFn
468 */
469 GHOSTTY_TERMINAL_OPT_BELL = 2,
470
471 /**
472 * Callback invoked when the terminal receives an ENQ character
473 * (0x05). Set to NULL to send no response.
474 *
475 * Input type: GhosttyTerminalEnquiryFn
476 */
477 GHOSTTY_TERMINAL_OPT_ENQUIRY = 3,
478
479 /**
480 * Callback invoked when the terminal receives an XTVERSION query
481 * (CSI > q). Set to NULL to report the default "libghostty" string.
482 *
483 * Input type: GhosttyTerminalXtversionFn
484 */
485 GHOSTTY_TERMINAL_OPT_XTVERSION = 4,
486
487 /**
488 * Callback invoked when the terminal title changes via escape
489 * sequences (e.g. OSC 0 or OSC 2). Set to NULL to ignore title
490 * change events.
491 *
492 * Input type: GhosttyTerminalTitleChangedFn
493 */
494 GHOSTTY_TERMINAL_OPT_TITLE_CHANGED = 5,
495
496 /**
497 * Callback invoked in response to XTWINOPS size queries
498 * (CSI 14/16/18 t). Set to NULL to silently ignore size queries.
499 *
500 * Input type: GhosttyTerminalSizeFn
501 */
502 GHOSTTY_TERMINAL_OPT_SIZE = 6,
503
504 /**
505 * Callback invoked in response to a color scheme device status
506 * report query (CSI ? 996 n). Return true and fill the out pointer
507 * to report the current scheme, or return false to silently ignore.
508 * Set to NULL to ignore color scheme queries.
509 *
510 * Input type: GhosttyTerminalColorSchemeFn
511 */
512 GHOSTTY_TERMINAL_OPT_COLOR_SCHEME = 7,
513
514 /**
515 * Callback invoked in response to a device attributes query
516 * (CSI c, CSI > c, or CSI = c). Return true and fill the out
517 * pointer with response data, or return false to silently ignore.
518 * Set to NULL to ignore device attributes queries.
519 *
520 * Input type: GhosttyTerminalDeviceAttributesFn
521 */
522 GHOSTTY_TERMINAL_OPT_DEVICE_ATTRIBUTES = 8,
523
524 /**
525 * Set the terminal title manually.
526 *
527 * The string data is copied into the terminal. A NULL value pointer
528 * clears the title (equivalent to setting an empty string).
529 *
530 * Input type: GhosttyString*
531 */
532 GHOSTTY_TERMINAL_OPT_TITLE = 9,
533
534 /**
535 * Set the terminal working directory manually.
536 *
537 * The string data is copied into the terminal. A NULL value pointer
538 * clears the pwd (equivalent to setting an empty string).
539 *
540 * Input type: GhosttyString*
541 */
542 GHOSTTY_TERMINAL_OPT_PWD = 10,
543
544 /**
545 * Set the default foreground color.
546 *
547 * A NULL value pointer clears the default (unset).
548 *
549 * Input type: GhosttyColorRgb*
550 */
551 GHOSTTY_TERMINAL_OPT_COLOR_FOREGROUND = 11,
552
553 /**
554 * Set the default background color.
555 *
556 * A NULL value pointer clears the default (unset).
557 *
558 * Input type: GhosttyColorRgb*
559 */
560 GHOSTTY_TERMINAL_OPT_COLOR_BACKGROUND = 12,
561
562 /**
563 * Set the default cursor color.
564 *
565 * A NULL value pointer clears the default (unset).
566 *
567 * Input type: GhosttyColorRgb*
568 */
569 GHOSTTY_TERMINAL_OPT_COLOR_CURSOR = 13,
570
571 /**
572 * Set the default 256-color palette.
573 *
574 * The value must point to an array of exactly 256 GhosttyColorRgb values.
575 * A NULL value pointer resets to the built-in default palette.
576 *
577 * Input type: GhosttyColorRgb[256]*
578 */
579 GHOSTTY_TERMINAL_OPT_COLOR_PALETTE = 14,
580
581 /**
582 * Set the Kitty image storage limit in bytes.
583 *
584 * Applied to all initialized screens (primary and alternate).
585 * A value of zero disables the Kitty graphics protocol entirely,
586 * deleting all stored images and placements. A NULL value pointer
587 * is equivalent to zero (disables). Has no effect when Kitty graphics
588 * are disabled at build time.
589 *
590 * Input type: uint64_t*
591 */
592 GHOSTTY_TERMINAL_OPT_KITTY_IMAGE_STORAGE_LIMIT = 15,
593
594 /**
595 * Enable or disable Kitty image loading via the file medium.
596 *
597 * A NULL value pointer is a no-op. Has no effect when Kitty graphics
598 * are disabled at build time.
599 *
600 * Input type: bool*
601 */
602 GHOSTTY_TERMINAL_OPT_KITTY_IMAGE_MEDIUM_FILE = 16,
603
604 /**
605 * Enable or disable Kitty image loading via the temporary file medium.
606 *
607 * A NULL value pointer is a no-op. Has no effect when Kitty graphics
608 * are disabled at build time.
609 *
610 * Input type: bool*
611 */
612 GHOSTTY_TERMINAL_OPT_KITTY_IMAGE_MEDIUM_TEMP_FILE = 17,
613
614 /**
615 * Enable or disable Kitty image loading via the shared memory medium.
616 *
617 * A NULL value pointer is a no-op. Has no effect when Kitty graphics
618 * are disabled at build time.
619 *
620 * Input type: bool*
621 */
622 GHOSTTY_TERMINAL_OPT_KITTY_IMAGE_MEDIUM_SHARED_MEM = 18,
623
624 /**
625 * Set the maximum bytes the APC handler will buffer for all protocols.
626 * This prevents malicious input from causing unbounded memory allocation.
627 * A NULL value pointer removes all overrides, reverting to the built-in
628 * defaults.
629 *
630 * Input type: size_t*
631 */
632 GHOSTTY_TERMINAL_OPT_APC_MAX_BYTES = 19,
633
634 /**
635 * Set the maximum bytes the APC handler will buffer for Kitty graphics
636 * protocol data. A NULL value pointer removes the override, reverting
637 * to the built-in default.
638 *
639 * Input type: size_t*
640 */
641 GHOSTTY_TERMINAL_OPT_APC_MAX_BYTES_KITTY = 20,
642
643 /**
644 * Set the active screen selection.
645 *
646 * The value must point to a GhosttySelection whose grid references are
647 * valid for this terminal's active screen at the time of the call. The
648 * terminal copies the selection immediately and converts it to
649 * terminal-owned tracked state, so the GhosttySelection struct and its
650 * untracked grid references do not need to outlive this call.
651 *
652 * Passing NULL clears the active screen selection.
653 *
654 * Input type: GhosttySelection*
655 */
656 GHOSTTY_TERMINAL_OPT_SELECTION = 21,
657
658 /**
659 * Set the default cursor style used by DECSCUSR reset (CSI 0 q).
660 *
661 * A NULL value pointer resets to the built-in default block cursor.
662 *
663 * Input type: GhosttyTerminalCursorStyle*
664 */
665 GHOSTTY_TERMINAL_OPT_DEFAULT_CURSOR_STYLE = 22,
666
667 /**
668 * Set whether the default cursor should blink when reset by DECSCUSR
669 * (CSI 0 q).
670 *
671 * A NULL value pointer resets to the built-in default of not blinking.
672 *
673 * Input type: bool*
674 */
675 GHOSTTY_TERMINAL_OPT_DEFAULT_CURSOR_BLINK = 23,
676
677 /**
678 * Enable or disable Glyph Protocol APC handling.
679 *
680 * When disabled, Glyph Protocol APC sequences are ignored and no
681 * support/query/register/clear responses are emitted. Disabling also clears
682 * the terminal session's glyph glossary. A NULL value pointer is a no-op.
683 *
684 * Input type: bool*
685 */
686 GHOSTTY_TERMINAL_OPT_GLYPH_PROTOCOL = 24,
687
688 /**
689 * Callback invoked when the terminal pwd changes via escape
690 * sequences (OSC 7, OSC 9, or OSC 1337 CurrentDir). Set to NULL
691 * to ignore pwd change events.
692 *
693 * Input type: GhosttyTerminalPwdChangedFn
694 */
695 GHOSTTY_TERMINAL_OPT_PWD_CHANGED = 25,
696 GHOSTTY_TERMINAL_OPT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
697} GhosttyTerminalOption;
698
699/**
700 * Terminal data types.
701 *
702 * These values specify what type of data to extract from a terminal
703 * using `ghostty_terminal_get`.
704 *
705 * @ingroup terminal
706 */
707typedef enum GHOSTTY_ENUM_TYPED {
708 /** Invalid data type. Never results in any data extraction. */
709 GHOSTTY_TERMINAL_DATA_INVALID = 0,
710
711 /**
712 * Terminal width in cells.
713 *
714 * Output type: uint16_t *
715 */
716 GHOSTTY_TERMINAL_DATA_COLS = 1,
717
718 /**
719 * Terminal height in cells.
720 *
721 * Output type: uint16_t *
722 */
723 GHOSTTY_TERMINAL_DATA_ROWS = 2,
724
725 /**
726 * Cursor column position (0-indexed).
727 *
728 * Output type: uint16_t *
729 */
730 GHOSTTY_TERMINAL_DATA_CURSOR_X = 3,
731
732 /**
733 * Cursor row position within the active area (0-indexed).
734 *
735 * Output type: uint16_t *
736 */
737 GHOSTTY_TERMINAL_DATA_CURSOR_Y = 4,
738
739 /**
740 * Whether the cursor has a pending wrap (next print will soft-wrap).
741 *
742 * Output type: bool *
743 */
744 GHOSTTY_TERMINAL_DATA_CURSOR_PENDING_WRAP = 5,
745
746 /**
747 * The currently active screen.
748 *
749 * Output type: GhosttyTerminalScreen *
750 */
751 GHOSTTY_TERMINAL_DATA_ACTIVE_SCREEN = 6,
752
753 /**
754 * Whether the cursor is visible (DEC mode 25).
755 *
756 * Output type: bool *
757 */
758 GHOSTTY_TERMINAL_DATA_CURSOR_VISIBLE = 7,
759
760 /**
761 * Current Kitty keyboard protocol flags.
762 *
763 * Output type: GhosttyKittyKeyFlags * (uint8_t *)
764 */
765 GHOSTTY_TERMINAL_DATA_KITTY_KEYBOARD_FLAGS = 8,
766
767 /**
768 * Scrollbar state for the terminal viewport.
769 *
770 * This may be expensive to calculate depending on where the viewport
771 * is (arbitrary pins are expensive). The caller should take care to only
772 * call this as needed and not too frequently.
773 *
774 * Output type: GhosttyTerminalScrollbar *
775 */
776 GHOSTTY_TERMINAL_DATA_SCROLLBAR = 9,
777
778 /**
779 * The current SGR style of the cursor.
780 *
781 * This is the style that will be applied to newly printed characters.
782 *
783 * Output type: GhosttyStyle *
784 */
785 GHOSTTY_TERMINAL_DATA_CURSOR_STYLE = 10,
786
787 /**
788 * Whether any mouse tracking mode is active.
789 *
790 * Returns true if any of the mouse tracking modes (X10, normal, button,
791 * or any-event) are enabled.
792 *
793 * Output type: bool *
794 */
795 GHOSTTY_TERMINAL_DATA_MOUSE_TRACKING = 11,
796
797 /**
798 * The terminal title as set by escape sequences (e.g. OSC 0/2).
799 *
800 * Returns a borrowed string. The pointer is valid until the next call
801 * to ghostty_terminal_vt_write() or ghostty_terminal_reset(). An empty
802 * string (len=0) is returned when no title has been set.
803 *
804 * Output type: GhosttyString *
805 */
806 GHOSTTY_TERMINAL_DATA_TITLE = 12,
807
808 /**
809 * The terminal's current working directory as set by escape sequences
810 * (e.g. OSC 7).
811 *
812 * Returns a borrowed string. The pointer is valid until the next call
813 * to ghostty_terminal_vt_write() or ghostty_terminal_reset(). An empty
814 * string (len=0) is returned when no pwd has been set.
815 *
816 * Output type: GhosttyString *
817 */
818 GHOSTTY_TERMINAL_DATA_PWD = 13,
819
820 /**
821 * The total number of rows in the active screen including scrollback.
822 *
823 * Output type: size_t *
824 */
825 GHOSTTY_TERMINAL_DATA_TOTAL_ROWS = 14,
826
827 /**
828 * The number of scrollback rows (total rows minus viewport rows).
829 *
830 * Output type: size_t *
831 */
832 GHOSTTY_TERMINAL_DATA_SCROLLBACK_ROWS = 15,
833
834 /**
835 * The total width of the terminal in pixels.
836 *
837 * This is cols * cell_width_px as set by ghostty_terminal_resize().
838 *
839 * Output type: uint32_t *
840 */
841 GHOSTTY_TERMINAL_DATA_WIDTH_PX = 16,
842
843 /**
844 * The total height of the terminal in pixels.
845 *
846 * This is rows * cell_height_px as set by ghostty_terminal_resize().
847 *
848 * Output type: uint32_t *
849 */
850 GHOSTTY_TERMINAL_DATA_HEIGHT_PX = 17,
851
852 /**
853 * The effective foreground color (override or default).
854 *
855 * Returns GHOSTTY_NO_VALUE if no foreground color is set.
856 *
857 * Output type: GhosttyColorRgb *
858 */
859 GHOSTTY_TERMINAL_DATA_COLOR_FOREGROUND = 18,
860
861 /**
862 * The effective background color (override or default).
863 *
864 * Returns GHOSTTY_NO_VALUE if no background color is set.
865 *
866 * Output type: GhosttyColorRgb *
867 */
868 GHOSTTY_TERMINAL_DATA_COLOR_BACKGROUND = 19,
869
870 /**
871 * The effective cursor color (override or default).
872 *
873 * Returns GHOSTTY_NO_VALUE if no cursor color is set.
874 *
875 * Output type: GhosttyColorRgb *
876 */
877 GHOSTTY_TERMINAL_DATA_COLOR_CURSOR = 20,
878
879 /**
880 * The current 256-color palette.
881 *
882 * Output type: GhosttyColorRgb[256] *
883 */
884 GHOSTTY_TERMINAL_DATA_COLOR_PALETTE = 21,
885
886 /**
887 * The default foreground color (ignoring any OSC override).
888 *
889 * Returns GHOSTTY_NO_VALUE if no default foreground color is set.
890 *
891 * Output type: GhosttyColorRgb *
892 */
893 GHOSTTY_TERMINAL_DATA_COLOR_FOREGROUND_DEFAULT = 22,
894
895 /**
896 * The default background color (ignoring any OSC override).
897 *
898 * Returns GHOSTTY_NO_VALUE if no default background color is set.
899 *
900 * Output type: GhosttyColorRgb *
901 */
902 GHOSTTY_TERMINAL_DATA_COLOR_BACKGROUND_DEFAULT = 23,
903
904 /**
905 * The default cursor color (ignoring any OSC override).
906 *
907 * Returns GHOSTTY_NO_VALUE if no default cursor color is set.
908 *
909 * Output type: GhosttyColorRgb *
910 */
911 GHOSTTY_TERMINAL_DATA_COLOR_CURSOR_DEFAULT = 24,
912
913 /**
914 * The default 256-color palette (ignoring any OSC overrides).
915 *
916 * Output type: GhosttyColorRgb[256] *
917 */
918 GHOSTTY_TERMINAL_DATA_COLOR_PALETTE_DEFAULT = 25,
919
920 /**
921 * The Kitty image storage limit in bytes for the active screen.
922 *
923 * A value of zero means the Kitty graphics protocol is disabled.
924 * Returns GHOSTTY_NO_VALUE when Kitty graphics are disabled at build time.
925 *
926 * Output type: uint64_t *
927 */
928 GHOSTTY_TERMINAL_DATA_KITTY_IMAGE_STORAGE_LIMIT = 26,
929
930 /**
931 * Whether the file medium is enabled for Kitty image loading on the
932 * active screen.
933 *
934 * Returns GHOSTTY_NO_VALUE when Kitty graphics are disabled at build time.
935 *
936 * Output type: bool *
937 */
938 GHOSTTY_TERMINAL_DATA_KITTY_IMAGE_MEDIUM_FILE = 27,
939
940 /**
941 * Whether the temporary file medium is enabled for Kitty image loading
942 * on the active screen.
943 *
944 * Returns GHOSTTY_NO_VALUE when Kitty graphics are disabled at build time.
945 *
946 * Output type: bool *
947 */
948 GHOSTTY_TERMINAL_DATA_KITTY_IMAGE_MEDIUM_TEMP_FILE = 28,
949
950 /**
951 * Whether the shared memory medium is enabled for Kitty image loading
952 * on the active screen.
953 *
954 * Returns GHOSTTY_NO_VALUE when Kitty graphics are disabled at build time.
955 *
956 * Output type: bool *
957 */
958 GHOSTTY_TERMINAL_DATA_KITTY_IMAGE_MEDIUM_SHARED_MEM = 29,
959
960 /**
961 * The Kitty graphics image storage for the active screen.
962 *
963 * Returns a borrowed pointer to the image storage. The pointer is valid
964 * until the next mutating terminal call (e.g. ghostty_terminal_vt_write()
965 * or ghostty_terminal_reset()).
966 *
967 * Returns GHOSTTY_NO_VALUE when Kitty graphics are disabled at build time.
968 *
969 * Output type: GhosttyKittyGraphics *
970 */
971 GHOSTTY_TERMINAL_DATA_KITTY_GRAPHICS = 30,
972
973 /**
974 * The active screen's current selection.
975 *
976 * On success, writes an untracked snapshot of the terminal-owned selection
977 * to the caller-provided GhosttySelection. The GhosttySelection struct is
978 * caller-owned and may be kept, but the grid references inside it are
979 * untracked borrowed references into the active screen. They are only valid
980 * until the next mutating terminal call, such as ghostty_terminal_set(),
981 * ghostty_terminal_vt_write(), ghostty_terminal_resize(), or
982 * ghostty_terminal_reset().
983 *
984 * Returns GHOSTTY_NO_VALUE when there is no active selection.
985 *
986 * Output type: GhosttySelection *
987 */
988 GHOSTTY_TERMINAL_DATA_SELECTION = 31,
989
990 /**
991 * Whether the viewport is currently pinned to the active area.
992 *
993 * This is true when the viewport is following the active terminal area,
994 * and false when the user has scrolled into history.
995 *
996 * Output type: bool *
997 */
998 GHOSTTY_TERMINAL_DATA_VIEWPORT_ACTIVE = 32,
999 GHOSTTY_TERMINAL_DATA_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
1000} GhosttyTerminalData;
1001
1002/**
1003 * Create a new terminal instance.
1004 *
1005 * @param allocator Pointer to allocator, or NULL to use the default allocator
1006 * @param terminal Pointer to store the created terminal handle
1007 * @param options Terminal initialization options
1008 * @return GHOSTTY_SUCCESS on success, or an error code on failure
1009 *
1010 * @ingroup terminal
1011 */
1012GHOSTTY_API GhosttyResult ghostty_terminal_new(const GhosttyAllocator* allocator,
1013 GhosttyTerminal* terminal,
1014 GhosttyTerminalOptions options);
1015
1016/**
1017 * Free a terminal instance.
1018 *
1019 * Releases all resources associated with the terminal. After this call,
1020 * the terminal handle becomes invalid and must not be used.
1021 *
1022 * @param terminal The terminal handle to free (may be NULL)
1023 *
1024 * @ingroup terminal
1025 */
1026GHOSTTY_API void ghostty_terminal_free(GhosttyTerminal terminal);
1027
1028/**
1029 * Perform a full reset of the terminal (RIS).
1030 *
1031 * Resets all terminal state back to its initial configuration, including
1032 * modes, scrollback, scrolling region, and screen contents. The terminal
1033 * dimensions are preserved.
1034 *
1035 * @param terminal The terminal handle (may be NULL, in which case this is a no-op)
1036 *
1037 * @ingroup terminal
1038 */
1039GHOSTTY_API void ghostty_terminal_reset(GhosttyTerminal terminal);
1040
1041/**
1042 * Resize the terminal to the given dimensions.
1043 *
1044 * Changes the number of columns and rows in the terminal. The primary
1045 * screen will reflow content if wraparound mode is enabled; the alternate
1046 * screen does not reflow. If the dimensions are unchanged, this is a no-op.
1047 *
1048 * This also updates the terminal's pixel dimensions (used for image
1049 * protocols and size reports), disables synchronized output mode (allowed
1050 * by the spec so that resize results are shown immediately), and sends an
1051 * in-band size report if mode 2048 is enabled.
1052 *
1053 * @param terminal The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
1054 * @param cols New width in cells (must be greater than zero)
1055 * @param rows New height in cells (must be greater than zero)
1056 * @param cell_width_px Width of a single cell in pixels
1057 * @param cell_height_px Height of a single cell in pixels
1058 * @return GHOSTTY_SUCCESS on success, or an error code on failure
1059 *
1060 * @ingroup terminal
1061 */
1062GHOSTTY_API GhosttyResult ghostty_terminal_resize(GhosttyTerminal terminal,
1063 uint16_t cols,
1064 uint16_t rows,
1065 uint32_t cell_width_px,
1066 uint32_t cell_height_px);
1067
1068/**
1069 * Set an option on the terminal.
1070 *
1071 * Configures terminal callbacks and associated state such as the
1072 * write_pty callback and userdata pointer. The value is passed
1073 * directly for pointer types (callbacks, userdata) or as a pointer
1074 * to the value for non-pointer types (e.g. GhosttyString*).
1075 * NULL clears the option to its default.
1076 *
1077 * Callbacks are invoked synchronously during ghostty_terminal_vt_write().
1078 * Callbacks must not call ghostty_terminal_vt_write() on the same
1079 * terminal (no reentrancy).
1080 *
1081 * @param terminal The terminal handle (may be NULL, in which case this is a no-op)
1082 * @param option The option to set
1083 * @param value Pointer to the value to set (type depends on the option),
1084 * or NULL to clear the option
1085 *
1086 * @ingroup terminal
1087 */
1088GHOSTTY_API GhosttyResult ghostty_terminal_set(GhosttyTerminal terminal,
1089 GhosttyTerminalOption option,
1090 const void* value);
1091
1092/**
1093 * Write VT-encoded data to the terminal for processing.
1094 *
1095 * Feeds raw bytes through the terminal's VT stream parser, updating
1096 * terminal state accordingly. By default, sequences that require output
1097 * (queries, device status reports) are silently ignored. Use
1098 * ghostty_terminal_set() with GHOSTTY_TERMINAL_OPT_WRITE_PTY to install
1099 * a callback that receives response data.
1100 *
1101 * This never fails. Any erroneous input or errors in processing the
1102 * input are logged internally but do not cause this function to fail
1103 * because this input is assumed to be untrusted and from an external
1104 * source; so the primary goal is to keep the terminal state consistent and
1105 * not allow malformed input to corrupt or crash.
1106 *
1107 * @param terminal The terminal handle
1108 * @param data Pointer to the data to write
1109 * @param len Length of the data in bytes
1110 *
1111 * @ingroup terminal
1112 */
1113GHOSTTY_API void ghostty_terminal_vt_write(GhosttyTerminal terminal,
1114 const uint8_t* data,
1115 size_t len);
1116
1117/**
1118 * Scroll the terminal viewport.
1119 *
1120 * Scrolls the terminal's viewport according to the given behavior.
1121 * When using GHOSTTY_SCROLL_VIEWPORT_DELTA, set the delta field in
1122 * the value union to specify the number of rows to scroll (negative
1123 * for up, positive for down). For other behaviors, the value is ignored.
1124 *
1125 * @param terminal The terminal handle (may be NULL, in which case this is a no-op)
1126 * @param behavior The scroll behavior as a tagged union
1127 *
1128 * @ingroup terminal
1129 */
1130GHOSTTY_API void ghostty_terminal_scroll_viewport(GhosttyTerminal terminal,
1131 GhosttyTerminalScrollViewport behavior);
1132
1133/**
1134 * Get the current value of a terminal mode.
1135 *
1136 * Returns the value of the mode identified by the given mode.
1137 *
1138 * @param terminal The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
1139 * @param mode The mode identifying the mode to query
1140 * @param[out] out_value On success, set to true if the mode is set, false
1141 * if it is reset
1142 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the terminal
1143 * is NULL or the mode does not correspond to a known mode
1144 *
1145 * @ingroup terminal
1146 */
1147GHOSTTY_API GhosttyResult ghostty_terminal_mode_get(GhosttyTerminal terminal,
1148 GhosttyMode mode,
1149 bool* out_value);
1150
1151/**
1152 * Set the value of a terminal mode.
1153 *
1154 * Sets the mode identified by the given mode to the specified value.
1155 *
1156 * @param terminal The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
1157 * @param mode The mode identifying the mode to set
1158 * @param value true to set the mode, false to reset it
1159 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the terminal
1160 * is NULL or the mode does not correspond to a known mode
1161 *
1162 * @ingroup terminal
1163 */
1164GHOSTTY_API GhosttyResult ghostty_terminal_mode_set(GhosttyTerminal terminal,
1165 GhosttyMode mode,
1166 bool value);
1167
1168/**
1169 * Get data from a terminal instance.
1170 *
1171 * Extracts typed data from the given terminal based on the specified
1172 * data type. The output pointer must be of the appropriate type for the
1173 * requested data kind. Valid data types and output types are documented
1174 * in the `GhosttyTerminalData` enum.
1175 *
1176 * @param terminal The terminal handle (may be NULL)
1177 * @param data The type of data to extract
1178 * @param out Pointer to store the extracted data (type depends on data parameter)
1179 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the terminal
1180 * is NULL or the data type is invalid
1181 *
1182 * @ingroup terminal
1183 */
1184GHOSTTY_API GhosttyResult ghostty_terminal_get(GhosttyTerminal terminal,
1185 GhosttyTerminalData data,
1186 void *out);
1187
1188/**
1189 * Get multiple data fields from a terminal in a single call.
1190 *
1191 * This is an optimization over calling ghostty_terminal_get()
1192 * repeatedly, particularly useful in environments with high per-call
1193 * overhead such as FFI or Cgo.
1194 *
1195 * Each element in the keys array specifies a data kind, and the
1196 * corresponding element in the values array receives the result.
1197 * The type of each values[i] pointer must match the output type
1198 * documented for keys[i].
1199 *
1200 * Processing stops at the first error; on success out_written
1201 * is set to count, on error it is set to the index of the
1202 * failing key (i.e. the number of values successfully written).
1203 *
1204 * @param terminal The terminal handle (may be NULL)
1205 * @param count Number of key/value pairs
1206 * @param keys Array of data kinds to query
1207 * @param values Array of output pointers (types must match each key's
1208 * documented output type)
1209 * @param[out] out_written On return, receives the number of values
1210 * successfully written (may be NULL)
1211 * @return GHOSTTY_SUCCESS if all queries succeed
1212 *
1213 * @ingroup terminal
1214 */
1215GHOSTTY_API GhosttyResult ghostty_terminal_get_multi(GhosttyTerminal terminal,
1216 size_t count,
1217 const GhosttyTerminalData* keys,
1218 void** values,
1219 size_t* out_written);
1220
1221/**
1222 * Resolve a point in the terminal grid to a grid reference.
1223 *
1224 * Resolves the given point (which can be in active, viewport, screen,
1225 * or history coordinates) to a grid reference for that location. Use
1226 * ghostty_grid_ref_cell() and ghostty_grid_ref_row() to extract the cell
1227 * and row.
1228 *
1229 * Lookups using the `active` and `viewport` tags are fast. The `screen`
1230 * and `history` tags may require traversing the full scrollback page list
1231 * to resolve the y coordinate, so they can be expensive for large
1232 * scrollback buffers.
1233 *
1234 * This function isn't meant to be used as the core of render loop. It
1235 * isn't built to sustain the framerates needed for rendering large screens.
1236 * Use the render state API for that. This API is instead meant for less
1237 * strictly performance-sensitive use cases.
1238 *
1239 * @param terminal The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
1240 * @param point The point specifying which cell to look up
1241 * @param[out] out_ref On success, set to the grid reference at the given point (may be NULL)
1242 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the terminal
1243 * is NULL or the point is out of bounds
1244 *
1245 * @ingroup terminal
1246 */
1247GHOSTTY_API GhosttyResult ghostty_terminal_grid_ref(GhosttyTerminal terminal,
1248 GhosttyPoint point,
1249 GhosttyGridRef *out_ref);
1250
1251/**
1252 * Create an owned tracked grid reference for a terminal point.
1253 *
1254 * This is the tracked variant of ghostty_terminal_grid_ref(). The returned
1255 * handle follows the referenced cell as the terminal's page list is modified:
1256 * scrolling, pruning, resize/reflow, and other page-list operations update the
1257 * tracked reference automatically.
1258 *
1259 * The reference is attached to the terminal screen/page-list that is active at
1260 * creation time.
1261 *
1262 * If the point is outside the requested coordinate space, this returns
1263 * GHOSTTY_INVALID_VALUE and writes NULL to out_ref.
1264 *
1265 * The returned handle must be freed with ghostty_tracked_grid_ref_free(). If
1266 * the terminal is freed first, the handle remains valid only for
1267 * tracked-grid-ref APIs: it reports no value and can still be freed.
1268 *
1269 * @param terminal Terminal instance.
1270 * @param point Point to track.
1271 * @param[out] out_ref On success, receives the tracked reference handle.
1272 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if terminal,
1273 * point, or out_ref is invalid, or GHOSTTY_OUT_OF_MEMORY if allocation
1274 * fails.
1275 *
1276 * @ingroup terminal
1277 */
1278GHOSTTY_API GhosttyResult ghostty_terminal_grid_ref_track(
1279 GhosttyTerminal terminal,
1280 GhosttyPoint point,
1281 GhosttyTrackedGridRef *out_ref);
1282
1283/**
1284 * Convert a grid reference back to a point in the given coordinate system.
1285 *
1286 * This is the inverse of ghostty_terminal_grid_ref(): given a grid reference,
1287 * it returns the x/y coordinates in the requested coordinate system (active,
1288 * viewport, screen, or history).
1289 *
1290 * The grid reference must have been obtained from the same terminal instance.
1291 * Like all grid references, it is only valid until the next mutating terminal
1292 * call.
1293 *
1294 * Not every grid reference is representable in every coordinate system. For
1295 * example, a cell in scrollback history cannot be expressed in active
1296 * coordinates, and a cell that has scrolled off the visible area cannot be
1297 * expressed in viewport coordinates. In these cases, the function returns
1298 * GHOSTTY_NO_VALUE.
1299 *
1300 * @param terminal The terminal handle (NULL returns GHOSTTY_INVALID_VALUE)
1301 * @param ref Pointer to the grid reference to convert
1302 * @param tag The target coordinate system
1303 * @param[out] out On success, set to the coordinate in the requested system (may be NULL)
1304 * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the terminal
1305 * or ref is NULL/invalid, GHOSTTY_NO_VALUE if the ref falls outside
1306 * the requested coordinate system
1307 *
1308 * @ingroup terminal
1309 */
1310GHOSTTY_API GhosttyResult ghostty_terminal_point_from_grid_ref(
1311 GhosttyTerminal terminal,
1312 const GhosttyGridRef *ref,
1313 GhosttyPointTag tag,
1314 GhosttyPointCoordinate *out);
1315
1316/** @} */
1317
1318#ifdef __cplusplus
1319}
1320#endif
1321
1322#endif /* GHOSTTY_VT_TERMINAL_H */
native/libghostty-vt/include/ghostty/vt/types.h created+335
......@@ -0,0 +1,335 @@
1/**
2 * @file types.h
3 *
4 * Common types, macros, and utilities for libghostty-vt.
5 */
6
7#ifndef GHOSTTY_VT_TYPES_H
8#define GHOSTTY_VT_TYPES_H
9
10#include <limits.h>
11#include <stddef.h>
12#include <stdint.h>
13
14// Symbol visibility for shared library builds. On Windows, functions
15// are exported from the DLL when building and imported when consuming.
16// On other platforms with GCC/Clang, functions are marked with default
17// visibility so they remain accessible when the library is built with
18// -fvisibility=hidden. For static library builds, define GHOSTTY_STATIC
19// before including this header to make this a no-op.
20#ifndef GHOSTTY_API
21#if defined(GHOSTTY_STATIC)
22 #define GHOSTTY_API
23#elif defined(_WIN32) || defined(_WIN64)
24 #ifdef GHOSTTY_BUILD_SHARED
25 #define GHOSTTY_API __declspec(dllexport)
26 #else
27 #define GHOSTTY_API __declspec(dllimport)
28 #endif
29#elif defined(__GNUC__) && __GNUC__ >= 4
30 #define GHOSTTY_API __attribute__((visibility("default")))
31#else
32 #define GHOSTTY_API
33#endif
34#endif
35
36/**
37 * Enum int-sizing helpers.
38 *
39 * The Zig side backs all C enums with c_int, so the C declarations
40 * must use int as their underlying type to maintain ABI compatibility.
41 *
42 * C23 (detected via __STDC_VERSION__ >= 202311L) supports explicit
43 * enum underlying types with `enum : int { ... }`. For pre-C23
44 * compilers, which are free to choose any type that can represent
45 * all values (C11 §6.7.2.2), we add an INT_MAX sentinel as the last
46 * entry to force the compiler to use int.
47 *
48 * INT_MAX is used rather than a fixed constant like 0xFFFFFFFF
49 * because enum constants must have type int (which is signed).
50 * Values above INT_MAX overflow signed int and are a constraint
51 * violation in standard C; compilers that accept them interpret them
52 * as negative values via two's complement, which can collide with
53 * legitimate negative enum values.
54 *
55 * Usage:
56 * @code
57 * typedef enum GHOSTTY_ENUM_TYPED {
58 * FOO_A = 0,
59 * FOO_B = 1,
60 * FOO_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
61 * } Foo;
62 * @endcode
63 */
64#if defined(__STDC_VERSION__) && __STDC_VERSION__ >= 202311L
65#define GHOSTTY_ENUM_TYPED : int
66#else
67#define GHOSTTY_ENUM_TYPED
68#endif
69#define GHOSTTY_ENUM_MAX_VALUE INT_MAX
70
71/**
72 * Result codes for libghostty-vt operations.
73 */
74typedef enum GHOSTTY_ENUM_TYPED {
75 /** Operation completed successfully */
76 GHOSTTY_SUCCESS = 0,
77 /** Operation failed due to failed allocation */
78 GHOSTTY_OUT_OF_MEMORY = -1,
79 /** Operation failed due to invalid value */
80 GHOSTTY_INVALID_VALUE = -2,
81 /** Operation failed because the provided buffer was too small */
82 GHOSTTY_OUT_OF_SPACE = -3,
83 /** The requested value has no value */
84 GHOSTTY_NO_VALUE = -4,
85 GHOSTTY_RESULT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
86} GhosttyResult;
87
88/* ---- Opaque handles ---- */
89
90/**
91 * Opaque handle to a terminal instance.
92 *
93 * @ingroup terminal
94 */
95typedef struct GhosttyTerminalImpl* GhosttyTerminal;
96
97/**
98 * Opaque handle to a tracked grid reference.
99 *
100 * A tracked grid reference is owned by the caller and must be freed with
101 * ghostty_tracked_grid_ref_free(). If the terminal that created it is freed
102 * first, the handle remains valid only for tracked-grid-ref APIs: it reports no
103 * value and can still be freed.
104 *
105 * @ingroup grid_ref
106 */
107typedef struct GhosttyTrackedGridRefImpl* GhosttyTrackedGridRef;
108
109/**
110 * Opaque handle to a Kitty graphics image storage.
111 *
112 * Obtained via ghostty_terminal_get() with
113 * GHOSTTY_TERMINAL_DATA_KITTY_GRAPHICS. The pointer is borrowed from
114 * the terminal and remains valid until the next mutating terminal call
115 * (e.g. ghostty_terminal_vt_write() or ghostty_terminal_reset()).
116 *
117 * @ingroup kitty_graphics
118 */
119typedef struct GhosttyKittyGraphicsImpl* GhosttyKittyGraphics;
120
121/**
122 * Opaque handle to a Kitty graphics image.
123 *
124 * Obtained via ghostty_kitty_graphics_image() with an image ID. The
125 * pointer is borrowed from the storage and remains valid until the next
126 * mutating terminal call.
127 *
128 * @ingroup kitty_graphics
129 */
130typedef const struct GhosttyKittyGraphicsImageImpl* GhosttyKittyGraphicsImage;
131
132/**
133 * Opaque handle to a Kitty graphics placement iterator.
134 *
135 * @ingroup kitty_graphics
136 */
137typedef struct GhosttyKittyGraphicsPlacementIteratorImpl* GhosttyKittyGraphicsPlacementIterator;
138
139/**
140 * Opaque handle to a render state instance.
141 *
142 * @ingroup render
143 */
144typedef struct GhosttyRenderStateImpl* GhosttyRenderState;
145
146/**
147 * Opaque handle to a render-state row iterator.
148 *
149 * @ingroup render
150 */
151typedef struct GhosttyRenderStateRowIteratorImpl* GhosttyRenderStateRowIterator;
152
153/**
154 * Opaque handle to render-state row cells.
155 *
156 * @ingroup render
157 */
158typedef struct GhosttyRenderStateRowCellsImpl* GhosttyRenderStateRowCells;
159
160/**
161 * Opaque handle to an SGR parser instance.
162 *
163 * This handle represents an SGR (Select Graphic Rendition) parser that can
164 * be used to parse SGR sequences and extract individual text attributes.
165 *
166 * @ingroup sgr
167 */
168typedef struct GhosttySgrParserImpl* GhosttySgrParser;
169
170/**
171 * Opaque handle to a formatter instance.
172 *
173 * @ingroup formatter
174 */
175typedef struct GhosttyFormatterImpl* GhosttyFormatter;
176
177/**
178 * Opaque handle to an OSC parser instance.
179 *
180 * This handle represents an OSC (Operating System Command) parser that can
181 * be used to parse the contents of OSC sequences.
182 *
183 * @ingroup osc
184 */
185typedef struct GhosttyOscParserImpl* GhosttyOscParser;
186
187/**
188 * Opaque handle to a single OSC command.
189 *
190 * This handle represents a parsed OSC (Operating System Command) command.
191 * The command can be queried for its type and associated data.
192 *
193 * @ingroup osc
194 */
195typedef struct GhosttyOscCommandImpl* GhosttyOscCommand;
196
197/* ---- Common value types ---- */
198
199/**
200 * Terminal content output format.
201 *
202 * @ingroup formatter
203 */
204typedef enum GHOSTTY_ENUM_TYPED {
205 /** Plain text (no escape sequences). */
206 GHOSTTY_FORMATTER_FORMAT_PLAIN,
207
208 /** VT sequences preserving colors, styles, URLs, etc. */
209 GHOSTTY_FORMATTER_FORMAT_VT,
210
211 /** HTML with inline styles. */
212 GHOSTTY_FORMATTER_FORMAT_HTML,
213 GHOSTTY_FORMATTER_FORMAT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
214} GhosttyFormatterFormat;
215
216/**
217 * A borrowed byte string (pointer + length).
218 *
219 * The memory is not owned by this struct. The pointer is only valid
220 * for the lifetime documented by the API that produces or consumes it.
221 */
222typedef struct {
223 /** Pointer to the string bytes. */
224 const uint8_t* ptr;
225
226 /** Length of the string in bytes. */
227 size_t len;
228} GhosttyString;
229
230/**
231 * A caller-provided byte buffer.
232 *
233 * APIs that write to this type use `len` for the number of bytes written on
234 * GHOSTTY_SUCCESS and the required byte capacity on GHOSTTY_OUT_OF_SPACE.
235 */
236typedef struct {
237 /** Destination buffer for bytes. May be NULL when cap is 0 to query required size. */
238 uint8_t* ptr;
239
240 /** Capacity of ptr in bytes. */
241 size_t cap;
242
243 /** Bytes written on success, or required byte capacity on GHOSTTY_OUT_OF_SPACE. */
244 size_t len;
245} GhosttyBuffer;
246
247/**
248 * A surface-space position in pixels.
249 *
250 * This is not a terminal grid coordinate. It represents an x/y position in the
251 * rendered surface coordinate space, with (0, 0) at the top-left of the
252 * surface.
253 */
254typedef struct {
255 /** X position in surface pixels. */
256 double x;
257
258 /** Y position in surface pixels. */
259 double y;
260} GhosttySurfacePosition;
261
262/**
263 * A borrowed list of Unicode scalar values.
264 *
265 * Values are encoded as uint32_t scalar values. The memory is not owned by this
266 * struct. The pointer is only valid for the lifetime documented by the API that
267 * consumes or produces it.
268 *
269 * APIs may document special handling for NULL + len 0, such as “use defaults”.
270 */
271typedef struct {
272 /** Pointer to Unicode scalar values. */
273 const uint32_t* ptr;
274
275 /** Number of entries in ptr. */
276 size_t len;
277} GhosttyCodepoints;
278
279/**
280 * Initialize a sized struct to zero and set its size field.
281 *
282 * Sized structs use a `size` field as the first member for ABI
283 * compatibility. This macro zero-initializes the struct and sets the
284 * size field to `sizeof(type)`, which allows the library to detect
285 * which version of the struct the caller was compiled against.
286 *
287 * @param type The struct type to initialize
288 * @return A zero-initialized struct with the size field set
289 *
290 * Example:
291 * @code
292 * GhosttyFormatterTerminalOptions opts = GHOSTTY_INIT_SIZED(GhosttyFormatterTerminalOptions);
293 * opts.emit = GHOSTTY_FORMATTER_FORMAT_PLAIN;
294 * opts.trim = true;
295 * @endcode
296 */
297#define GHOSTTY_INIT_SIZED(type) \
298 ((type){ .size = sizeof(type) })
299
300/**
301 * Return a pointer to a null-terminated JSON string describing the
302 * layout of every C API struct for the current target.
303 *
304 * This is primarily useful for language bindings that can't easily
305 * set C struct fields and need to do so via byte offsets. For example,
306 * WebAssembly modules can't share struct definitions with the host.
307 *
308 * Example (abbreviated):
309 * @code{.json}
310 * {
311 * "GhosttyMouseEncoderSize": {
312 * "size": 40,
313 * "align": 8,
314 * "fields": {
315 * "size": { "offset": 0, "size": 8, "type": "u64" },
316 * "screen_width": { "offset": 8, "size": 4, "type": "u32" },
317 * "screen_height": { "offset": 12, "size": 4, "type": "u32" },
318 * "cell_width": { "offset": 16, "size": 4, "type": "u32" },
319 * "cell_height": { "offset": 20, "size": 4, "type": "u32" },
320 * "padding_top": { "offset": 24, "size": 4, "type": "u32" },
321 * "padding_bottom": { "offset": 28, "size": 4, "type": "u32" },
322 * "padding_right": { "offset": 32, "size": 4, "type": "u32" },
323 * "padding_left": { "offset": 36, "size": 4, "type": "u32" }
324 * }
325 * }
326 * }
327 * @endcode
328 *
329 * The returned pointer is valid for the lifetime of the process.
330 *
331 * @return Pointer to the null-terminated JSON string.
332 */
333GHOSTTY_API const char *ghostty_type_json(void);
334
335#endif /* GHOSTTY_VT_TYPES_H */
native/libghostty-vt/include/ghostty/vt/wasm.h created+160
......@@ -0,0 +1,160 @@
1/**
2 * @file wasm.h
3 *
4 * WebAssembly utility functions for libghostty-vt.
5 */
6
7#ifndef GHOSTTY_VT_WASM_H
8#define GHOSTTY_VT_WASM_H
9
10#ifdef __wasm__
11
12#include <stddef.h>
13#include <stdint.h>
14#include <ghostty/vt/types.h>
15
16/** @defgroup wasm WebAssembly Utilities
17 *
18 * Convenience functions for allocating various types in WebAssembly builds.
19 * **These are only available the libghostty-vt wasm module.**
20 *
21 * Ghostty relies on pointers to various types for ABI compatibility, and
22 * creating those pointers in Wasm can be tedious. These functions provide
23 * a purely additive set of utilities that simplify memory management in
24 * Wasm environments without changing the core C library API.
25 *
26 * @note These functions always use the default allocator. If you need
27 * custom allocation strategies, you should allocate types manually using
28 * your custom allocator. This is a very rare use case in the WebAssembly
29 * world so these are optimized for simplicity.
30 *
31 * ## Example Usage
32 *
33 * Here's a simple example of using the Wasm utilities with the key encoder:
34 *
35 * @code
36 * const { exports } = wasmInstance;
37 * const view = new DataView(wasmMemory.buffer);
38 *
39 * // Create key encoder
40 * const encoderPtr = exports.ghostty_wasm_alloc_opaque();
41 * exports.ghostty_key_encoder_new(null, encoderPtr);
42 * const encoder = view.getUint32(encoder, true);
43 *
44 * // Configure encoder with Kitty protocol flags
45 * const flagsPtr = exports.ghostty_wasm_alloc_u8();
46 * view.setUint8(flagsPtr, 0x1F);
47 * exports.ghostty_key_encoder_setopt(encoder, 5, flagsPtr);
48 *
49 * // Allocate output buffer and size pointer
50 * const bufferSize = 32;
51 * const bufPtr = exports.ghostty_wasm_alloc_u8_array(bufferSize);
52 * const writtenPtr = exports.ghostty_wasm_alloc_usize();
53 *
54 * // Encode the key event
55 * exports.ghostty_key_encoder_encode(
56 * encoder, eventPtr, bufPtr, bufferSize, writtenPtr
57 * );
58 *
59 * // Read encoded output
60 * const bytesWritten = view.getUint32(writtenPtr, true);
61 * const encoded = new Uint8Array(wasmMemory.buffer, bufPtr, bytesWritten);
62 * @endcode
63 *
64 * @remark The code above is pretty ugly! This is the lowest level interface
65 * to the libghostty-vt Wasm module. In practice, this should be wrapped
66 * in a higher-level API that abstracts away all this.
67 *
68 * @{
69 */
70
71/**
72 * Allocate an opaque pointer. This can be used for any opaque pointer
73 * types such as GhosttyKeyEncoder, GhosttyKeyEvent, etc.
74 *
75 * @return Pointer to allocated opaque pointer, or NULL if allocation failed
76 * @ingroup wasm
77 */
78GHOSTTY_API void** ghostty_wasm_alloc_opaque(void);
79
80/**
81 * Free an opaque pointer allocated by ghostty_wasm_alloc_opaque().
82 *
83 * @param ptr Pointer to free, or NULL (NULL is safely ignored)
84 * @ingroup wasm
85 */
86GHOSTTY_API void ghostty_wasm_free_opaque(void **ptr);
87
88/**
89 * Allocate an array of uint8_t values.
90 *
91 * @param len Number of uint8_t elements to allocate
92 * @return Pointer to allocated array, or NULL if allocation failed
93 * @ingroup wasm
94 */
95GHOSTTY_API uint8_t* ghostty_wasm_alloc_u8_array(size_t len);
96
97/**
98 * Free an array allocated by ghostty_wasm_alloc_u8_array().
99 *
100 * @param ptr Pointer to the array to free, or NULL (NULL is safely ignored)
101 * @param len Length of the array (must match the length passed to alloc)
102 * @ingroup wasm
103 */
104GHOSTTY_API void ghostty_wasm_free_u8_array(uint8_t *ptr, size_t len);
105
106/**
107 * Allocate an array of uint16_t values.
108 *
109 * @param len Number of uint16_t elements to allocate
110 * @return Pointer to allocated array, or NULL if allocation failed
111 * @ingroup wasm
112 */
113GHOSTTY_API uint16_t* ghostty_wasm_alloc_u16_array(size_t len);
114
115/**
116 * Free an array allocated by ghostty_wasm_alloc_u16_array().
117 *
118 * @param ptr Pointer to the array to free, or NULL (NULL is safely ignored)
119 * @param len Length of the array (must match the length passed to alloc)
120 * @ingroup wasm
121 */
122GHOSTTY_API void ghostty_wasm_free_u16_array(uint16_t *ptr, size_t len);
123
124/**
125 * Allocate a single uint8_t value.
126 *
127 * @return Pointer to allocated uint8_t, or NULL if allocation failed
128 * @ingroup wasm
129 */
130GHOSTTY_API uint8_t* ghostty_wasm_alloc_u8(void);
131
132/**
133 * Free a uint8_t allocated by ghostty_wasm_alloc_u8().
134 *
135 * @param ptr Pointer to free, or NULL (NULL is safely ignored)
136 * @ingroup wasm
137 */
138GHOSTTY_API void ghostty_wasm_free_u8(uint8_t *ptr);
139
140/**
141 * Allocate a single size_t value.
142 *
143 * @return Pointer to allocated size_t, or NULL if allocation failed
144 * @ingroup wasm
145 */
146GHOSTTY_API size_t* ghostty_wasm_alloc_usize(void);
147
148/**
149 * Free a size_t allocated by ghostty_wasm_alloc_usize().
150 *
151 * @param ptr Pointer to free, or NULL (NULL is safely ignored)
152 * @ingroup wasm
153 */
154GHOSTTY_API void ghostty_wasm_free_usize(size_t *ptr);
155
156/** @} */
157
158#endif /* __wasm__ */
159
160#endif /* GHOSTTY_VT_WASM_H */