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