diff options
Diffstat (limited to 'include')
| -rw-r--r-- | include/wsap_vtcore/wsap_vtcore.h | 91 | ||||
| -rw-r--r-- | include/wsap_vtcore/wsap_vtcore_input.h | 6 |
2 files changed, 53 insertions, 44 deletions
diff --git a/include/wsap_vtcore/wsap_vtcore.h b/include/wsap_vtcore/wsap_vtcore.h index d72a55b..ffa7149 100644 --- a/include/wsap_vtcore/wsap_vtcore.h +++ b/include/wsap_vtcore/wsap_vtcore.h @@ -4,22 +4,23 @@ /* * Terminal emulator core. * - * A struct wsap_vtcore parses the bytes that a program writes and keeps - * the screen, the history, and the modes. The application feeds bytes with - * wsap_vtcore_feed() and reads state with the getters below. A renderer - * never reads the terminal directly: it copies the viewport into a - * struct wsap_vtcore_snapshot and paints from that copy. + * A struct wsap_vtcore parses the bytes that a program writes and keeps the + * screen, the history, and the modes. The application feeds bytes with + * wsap_vtcore_feed() and reads state with the getters below. A renderer never + * reads the terminal directly: it copies the viewport into a struct + * wsap_vtcore_snapshot and paints from that copy. * - * All functions take the terminal as the first argument. Functions that take - * a const struct wsap_vtcore do not change what it shows. Selection, history, link, - * directory, and pointer-shape queries return owned strings; release them - * with wsap_vtcore_text_free(). + * All functions take the terminal as the first argument. Functions that take a + * const struct wsap_vtcore do not change what it shows. Selection, history, + * link, directory, and pointer-shape queries return owned strings; release + * them with wsap_vtcore_text_free(). * - * Threads. Any thread can call any function. Each call that reads or changes - * a terminal enters its writer section, so calls on one terminal run one at a + * Threads. Any thread can call any function. Each call that reads or changes a + * terminal enters its writer section, so calls on one terminal run one at a * time. A thread that waits for the section sleeps. On POSIX the section is a * mutex with priority inheritance where the platform has it. A snapshot - * belongs to one thread at a time. wsap_vtcore_free() is the last call on a terminal. + * belongs to one thread at a time. wsap_vtcore_free() is the last call on a + * terminal. */ #include <stdbool.h> @@ -54,8 +55,8 @@ struct wsap_vtcore_snapshot; #define WSAP_VTCORE_VERSION_CODE WSAP_VTCORE_VERSION(WSAP_VTCORE_VERSION_MAJOR, WSAP_VTCORE_VERSION_MINOR, WSAP_VTCORE_VERSION_PATCH) /* - * Colors. A wsap_vtcore_color is either a direct color (alpha 0xFF, then RGB) or a - * palette slot: an index 0-255, the default foreground, or the default + * Colors. A wsap_vtcore_color is either a direct color (alpha 0xFF, then RGB) + * or a palette slot: an index 0-255, the default foreground, or the default * background. A slot resolves when a snapshot is painted, so a theme change * recolors text that is already on screen. */ @@ -125,9 +126,9 @@ enum wsap_vtcore_mouse_encoding { }; /* - * Callbacks. They run inside wsap_vtcore_feed() and wsap_vtcore_focus(), on the thread - * that calls those functions. A callback must not call back into the - * terminal. String arguments are valid only during the call. + * Callbacks. They run inside wsap_vtcore_feed() and wsap_vtcore_focus(), on + * the thread that calls those functions. A callback must not call back into + * the terminal. String arguments are valid only during the call. */ struct wsap_vtcore_callbacks { void *ud; @@ -153,11 +154,11 @@ struct wsap_vtcore_callbacks { }; /* - * Options for wsap_vtcore_new(). An all-zero value is valid. A size component of 0 - * selects 80 columns or 24 rows. A negative component, or columns above - * WSAP_VTCORE_MAX_COLS, makes wsap_vtcore_new() fail. A scrollback below 0 or above - * WSAP_VTCORE_SCROLLBACK_MAX fails too. - * cursor_style must be a value of enum wsap_vtcore_cursor_style. + * Options for wsap_vtcore_new(). An all-zero value is valid. A size component + * of 0 selects 80 columns or 24 rows. A negative component, or columns above + * WSAP_VTCORE_MAX_COLS, makes wsap_vtcore_new() fail. A scrollback below 0 or + * above WSAP_VTCORE_SCROLLBACK_MAX fails too. cursor_style must be a value of + * enum wsap_vtcore_cursor_style. */ struct wsap_vtcore_options { struct wsap_vtcore_vector2i size; /* columns and rows */ @@ -189,9 +190,9 @@ WSAP_VTCORE_API unsigned wsap_vtcore_version(void); * skip shaping for it. Any thread can call it. */ WSAP_VTCORE_API size_t wsap_vtcore_scan_printable_span(const char *buf, size_t len, unsigned char hi); -/* The instruction set level of the running code: "base", "avx2", "avx512", - * or "neon". On x86-64, the first wsap_vtcore_new() picks the highest level the CPU - * supports. Set WSAP_VTCORE_ISA to a lower level to force it, for tests +/* The instruction set level of the running code: "base", "avx2", "avx512", or + * "neon". On x86-64, the first wsap_vtcore_new() picks the highest level the + * CPU supports. Set WSAP_VTCORE_ISA to a lower level to force it, for tests * and comparisons. */ WSAP_VTCORE_API const char *wsap_vtcore_isa(void); @@ -202,8 +203,8 @@ WSAP_VTCORE_API void wsap_vtcore_free(struct wsap_vtcore *t); /* Hold the writer section across several calls, so that no other thread * changes the terminal between them. The section is a mutex, and a waiting * thread sleeps. Keep it short. The thread that holds it can call every - * function, and it can enter the section again. Each wsap_vtcore_lock() needs one - * wsap_vtcore_unlock(). */ + * function, and it can enter the section again. Each wsap_vtcore_lock() needs + * one wsap_vtcore_unlock(). */ WSAP_VTCORE_API void wsap_vtcore_lock(struct wsap_vtcore *t); WSAP_VTCORE_API void wsap_vtcore_unlock(struct wsap_vtcore *t); @@ -222,9 +223,9 @@ WSAP_VTCORE_API void wsap_vtcore_set_cursor_default(struct wsap_vtcore *t, enum /* * Bytes from the program. * - * WSAP_VTCORE_FEED_ONLCR: a line feed also returns the cursor to column 0, as a tty - * with OPOST and ONLCR does. Set it when the bytes did not pass through the - * tty output processing (for example the fast pipe). + * WSAP_VTCORE_FEED_ONLCR: a line feed also returns the cursor to column 0, as + * a tty with OPOST and ONLCR does. Set it when the bytes did not pass through + * the tty output processing (for example the fast pipe). */ enum wsap_vtcore_feed_flags { WSAP_VTCORE_FEED_ONLCR = 1u << 0, @@ -268,8 +269,8 @@ WSAP_VTCORE_API struct wsap_vtcore_modes wsap_vtcore_modes(const struct wsap_vtc /* * Encode an input event as the bytes the program expects. Get modes from - * wsap_vtcore_modes(). Record ev in keyboard with wsap_vtcore_keyboard_update() first. Send - * the bytes to the program yourself. + * wsap_vtcore_modes(). Record ev in keyboard with + * wsap_vtcore_keyboard_update() first. Send the bytes to the program yourself. */ WSAP_VTCORE_API struct wsap_vtcore_input_result wsap_vtcore_input_encode_key( const struct wsap_vtcore_keyboard_state *keyboard, @@ -291,8 +292,8 @@ WSAP_VTCORE_API struct wsap_vtcore_input_result wsap_vtcore_input_encode_mouse( * Encode pasted text. Drop control characters and bidi controls, so the * program sees only what the user saw. Send a line break as CR. Add the * bracketed-paste markers when the program asked for them. A buffer of - * len + WSAP_VTCORE_PASTE_EXTRA bytes is always large enough. Text that is empty - * after the filter gives WSAP_VTCORE_INPUT_CONSUMED. + * len + WSAP_VTCORE_PASTE_EXTRA bytes is always large enough. Text that is + * empty after the filter gives WSAP_VTCORE_INPUT_CONSUMED. */ WSAP_VTCORE_API struct wsap_vtcore_input_result wsap_vtcore_input_encode_paste( const struct wsap_vtcore_modes *modes, @@ -350,12 +351,13 @@ WSAP_VTCORE_API bool wsap_vtcore_has_selection(const struct wsap_vtcore *t); * string. Capture is atomic with respect to other calls on t. Release the * result with wsap_vtcore_text_free(). */ WSAP_VTCORE_API char *wsap_vtcore_selection_text(const struct wsap_vtcore *t); -/* Owned OSC 8 link or detected URL at a viewport cell. NULL when there is - * no link or allocation fails. Release the result with wsap_vtcore_text_free(). */ +/* Owned OSC 8 link or detected URL at a viewport cell. NULL when there is no + * link or allocation fails. Release the result with wsap_vtcore_text_free(). */ WSAP_VTCORE_API char *wsap_vtcore_link_at(const struct wsap_vtcore *t, struct wsap_vtcore_vector2i cell); /* Cell attributes share the write core's bit layout. Underline styles are - * mutually exclusive flags, not a shifted enum; use wsap_vtcore_attr_underline(). */ + * mutually exclusive flags, not a shifted enum; use + * wsap_vtcore_attr_underline(). */ enum wsap_vtcore_attr { WSAP_VTCORE_ATTR_BOLD = 1u << 0, WSAP_VTCORE_ATTR_ITALIC = 1u << 1, @@ -394,7 +396,8 @@ static inline enum wsap_vtcore_underline wsap_vtcore_attr_underline(uint16_t att return attrs & WSAP_VTCORE_ATTR_UNDERLINE ? WSAP_VTCORE_UNDERLINE_SINGLE : WSAP_VTCORE_UNDERLINE_NONE; } -/* text refers to a grapheme cluster in the snapshot; see wsap_vtcore_snapshot_cluster(). */ +/* text refers to a grapheme cluster in the snapshot; see + * wsap_vtcore_snapshot_cluster(). */ #define WSAP_VTCORE_TEXT_CLUSTER 0x80000000u /* One cell as a snapshot shows it. */ @@ -422,10 +425,12 @@ WSAP_VTCORE_API void wsap_vtcore_snapshot_free(struct wsap_vtcore_snapshot *s); /* Copy the viewport of t into s. Keep rows with unchanged content keys. * Update the history view index and refine counts for visible wide lines. - * Return false when memory runs out. The snapshot then keeps its previous content. */ + * Return false when memory runs out. The snapshot then keeps its previous + * content. */ WSAP_VTCORE_API bool wsap_vtcore_snapshot_update(struct wsap_vtcore_snapshot *s, struct wsap_vtcore *t); -/* Palette entries of struct wsap_vtcore_view.palette after the 256 indexed colors. */ +/* Palette entries of struct wsap_vtcore_view.palette after the 256 indexed + * colors. */ enum { WSAP_VTCORE_PALETTE_FG = 256, WSAP_VTCORE_PALETTE_BG = 257, @@ -449,11 +454,13 @@ struct wsap_vtcore_view { }; /* The view of s, NULL for a NULL s. The view and view->palette keep their - * address until wsap_vtcore_snapshot_free(); their contents change on each update. */ + * address until wsap_vtcore_snapshot_free(); their contents change on each + * update. */ WSAP_VTCORE_API const struct wsap_vtcore_view *wsap_vtcore_snapshot_view(const struct wsap_vtcore_snapshot *s); /* The cells of viewport row y: view->size.x entries. NULL when y is outside * the viewport or s is NULL. An update can move the cells, so the pointer is - * valid only until the next wsap_vtcore_snapshot_update() or wsap_vtcore_snapshot_free() of s. */ + * valid only until the next wsap_vtcore_snapshot_update() or + * wsap_vtcore_snapshot_free() of s. */ WSAP_VTCORE_API const struct wsap_vtcore_cell *wsap_vtcore_snapshot_row(const struct wsap_vtcore_snapshot *s, int y); /* An identity for the content of row y. Two rows with the same key hold the * same cells, also when the content moved to another row. 0 when y is outside diff --git a/include/wsap_vtcore/wsap_vtcore_input.h b/include/wsap_vtcore/wsap_vtcore_input.h index 337a292..fd236a5 100644 --- a/include/wsap_vtcore/wsap_vtcore_input.h +++ b/include/wsap_vtcore/wsap_vtcore_input.h @@ -154,8 +154,10 @@ struct wsap_vtcore_mouse_event { struct wsap_vtcore_vector2i pixel; /* Absolute pixel position in terminal grid */ /* * Button identifier: - * - Press and release: the button that changed state (WSAP_VTCORE_MOUSE_BUTTON_*). - * - Motion: the held button for drag events, or WSAP_VTCORE_MOUSE_BUTTON_NONE for hover. + * - Press and release: the button that changed state + * (WSAP_VTCORE_MOUSE_BUTTON_*). + * - Motion: the held button for drag events, or + * WSAP_VTCORE_MOUSE_BUTTON_NONE for hover. * - Scroll: the wheel direction (WSAP_VTCORE_MOUSE_WHEEL_*). */ int button; |