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 */