aboutsummaryrefslogtreecommitdiff
path: root/vendor/libghostty-vt/include/ghostty/vt/sys.h
diff options
context:
space:
mode:
authorOgulcan Celik <ogulcancelik@gmail.com>2026-05-07 18:29:21 +0300
committerOgulcan Celik <ogulcancelik@gmail.com>2026-05-07 18:29:21 +0300
commitdcfe11a7588fcd42471159453810abc9b7720a57 (patch)
treec32a77266028e73ca2382b96c96f8438a5fcd621 /vendor/libghostty-vt/include/ghostty/vt/sys.h
parent2dfed860103c4e4505ac7f25def9fe37da1e1e6a (diff)
build: update libghostty-vt vendor
vendor ghostty 063ac3e and remove the musl libc++ link workaround. expose the new selection formatter and hyperlink uri apis for follow-up rendering work. add manual artifact validation for static linux builds.
Diffstat (limited to 'vendor/libghostty-vt/include/ghostty/vt/sys.h')
-rw-r--r--vendor/libghostty-vt/include/ghostty/vt/sys.h210
1 files changed, 210 insertions, 0 deletions
diff --git a/vendor/libghostty-vt/include/ghostty/vt/sys.h b/vendor/libghostty-vt/include/ghostty/vt/sys.h
new file mode 100644
index 00000000..ae905969
--- /dev/null
+++ b/vendor/libghostty-vt/include/ghostty/vt/sys.h
@@ -0,0 +1,210 @@
+/**
+ * @file sys.h
+ *
+ * System interface - runtime-swappable implementations for external dependencies.
+ */
+
+#ifndef GHOSTTY_VT_SYS_H
+#define GHOSTTY_VT_SYS_H
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <ghostty/vt/types.h>
+#include <ghostty/vt/allocator.h>
+
+/** @defgroup sys System Interface
+ *
+ * Runtime-swappable function pointers for operations that depend on
+ * external implementations (e.g. image decoding).
+ *
+ * These are process-global settings that must be configured at startup
+ * before any terminal functionality that depends on them is used.
+ * Setting these enables various optional features of the terminal. For
+ * example, setting a PNG decoder enables PNG image support in the Kitty
+ * Graphics Protocol.
+ *
+ * Use ghostty_sys_set() with a `GhosttySysOption` to install or clear
+ * an implementation. Passing NULL as the value clears the implementation
+ * and disables the corresponding feature.
+ *
+ * ## Example
+ *
+ * ### Defining a PNG decode callback
+ * @snippet c-vt-kitty-graphics/src/main.c kitty-graphics-decode-png
+ *
+ * ### Installing the callback and sending a PNG image
+ * @snippet c-vt-kitty-graphics/src/main.c kitty-graphics-main
+ *
+ * @{
+ */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * Result of decoding an image.
+ *
+ * The `data` buffer must be allocated through the allocator provided to
+ * the decode callback. The library takes ownership and will free it
+ * with the same allocator.
+ */
+typedef struct {
+ /** Image width in pixels. */
+ uint32_t width;
+
+ /** Image height in pixels. */
+ uint32_t height;
+
+ /** Pointer to the decoded RGBA pixel data. */
+ uint8_t* data;
+
+ /** Length of the pixel data in bytes. */
+ size_t data_len;
+} GhosttySysImage;
+
+/**
+ * Log severity levels for the log callback.
+ */
+typedef enum GHOSTTY_ENUM_TYPED {
+ GHOSTTY_SYS_LOG_LEVEL_ERROR = 0,
+ GHOSTTY_SYS_LOG_LEVEL_WARNING = 1,
+ GHOSTTY_SYS_LOG_LEVEL_INFO = 2,
+ GHOSTTY_SYS_LOG_LEVEL_DEBUG = 3,
+ GHOSTTY_SYS_LOG_LEVEL_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
+} GhosttySysLogLevel;
+
+/**
+ * Callback type for logging.
+ *
+ * When installed, internal library log messages are delivered through
+ * this callback instead of being discarded. The embedder is responsible
+ * for formatting and routing log output.
+ *
+ * @p scope is the log scope name as UTF-8 bytes (e.g. "osc", "kitty").
+ * When the log is unscoped (default scope), @p scope_len is 0.
+ *
+ * All pointer arguments are only valid for the duration of the callback.
+ * The callback must be safe to call from any thread.
+ *
+ * @param userdata The userdata pointer set via GHOSTTY_SYS_OPT_USERDATA
+ * @param level The severity level of the log message
+ * @param scope Pointer to the scope name bytes
+ * @param scope_len Length of the scope name in bytes
+ * @param message Pointer to the log message bytes
+ * @param message_len Length of the log message in bytes
+ */
+typedef void (*GhosttySysLogFn)(
+ void* userdata,
+ GhosttySysLogLevel level,
+ const uint8_t* scope,
+ size_t scope_len,
+ const uint8_t* message,
+ size_t message_len);
+
+/**
+ * Callback type for PNG decoding.
+ *
+ * Decodes raw PNG data into RGBA pixels. The output pixel data must be
+ * allocated through the provided allocator. The library takes ownership
+ * of the buffer and will free it with the same allocator.
+ *
+ * @param userdata The userdata pointer set via GHOSTTY_SYS_OPT_USERDATA
+ * @param allocator The allocator to use for the output pixel buffer
+ * @param data Pointer to the raw PNG data
+ * @param data_len Length of the raw PNG data in bytes
+ * @param[out] out On success, filled with the decoded image
+ * @return true on success, false on failure
+ */
+typedef bool (*GhosttySysDecodePngFn)(
+ void* userdata,
+ const GhosttyAllocator* allocator,
+ const uint8_t* data,
+ size_t data_len,
+ GhosttySysImage* out);
+
+/**
+ * System option identifiers for ghostty_sys_set().
+ */
+typedef enum GHOSTTY_ENUM_TYPED {
+ /**
+ * Set the userdata pointer passed to all sys callbacks.
+ *
+ * Input type: void* (or NULL)
+ */
+ GHOSTTY_SYS_OPT_USERDATA = 0,
+
+ /**
+ * Set the PNG decode function.
+ *
+ * When set, the terminal can accept PNG images via the Kitty
+ * Graphics Protocol. When cleared (NULL value), PNG decoding is
+ * unsupported and PNG image data will be rejected.
+ *
+ * Input type: GhosttySysDecodePngFn (function pointer, or NULL)
+ */
+ GHOSTTY_SYS_OPT_DECODE_PNG = 1,
+
+ /**
+ * Set the log callback.
+ *
+ * When set, internal library log messages are delivered to this
+ * callback. When cleared (NULL value), log messages are silently
+ * discarded.
+ *
+ * Use ghostty_sys_log_stderr as a convenience callback that
+ * writes formatted messages to stderr.
+ *
+ * Which log levels are emitted depends on the build mode of the
+ * library and is not configurable at runtime. Debug builds emit
+ * all levels (debug and above). Release builds emit info and
+ * above; debug-level messages are compiled out entirely and will
+ * never reach the callback.
+ *
+ * Input type: GhosttySysLogFn (function pointer, or NULL)
+ */
+ GHOSTTY_SYS_OPT_LOG = 2,
+ GHOSTTY_SYS_OPT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
+} GhosttySysOption;
+
+/**
+ * Set a system-level option.
+ *
+ * Configures a process-global implementation function. These should be
+ * set once at startup before using any terminal functionality that
+ * depends on them.
+ *
+ * @param option The option to set
+ * @param value Pointer to the value (type depends on the option),
+ * or NULL to clear it
+ * @return GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the
+ * option is not recognized
+ */
+GHOSTTY_API GhosttyResult ghostty_sys_set(GhosttySysOption option,
+ const void* value);
+
+/**
+ * Built-in log callback that writes to stderr.
+ *
+ * Formats each message as "[level](scope): message\n".
+ * Can be passed directly to ghostty_sys_set():
+ *
+ * @code
+ * ghostty_sys_set(GHOSTTY_SYS_OPT_LOG, &ghostty_sys_log_stderr);
+ * @endcode
+ */
+GHOSTTY_API void ghostty_sys_log_stderr(void* userdata,
+ GhosttySysLogLevel level,
+ const uint8_t* scope,
+ size_t scope_len,
+ const uint8_t* message,
+ size_t message_len);
+
+#ifdef __cplusplus
+}
+#endif
+
+/** @} */
+
+#endif /* GHOSTTY_VT_SYS_H */