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