ghostty-org--ghostty/include/ghostty/vt/wasm.h

/**
 * @file wasm.h
 *
 * WebAssembly utility functions for libghostty-vt.
 */

#ifndef GHOSTTY_VT_WASM_H
#define GHOSTTY_VT_WASM_H

#ifdef __wasm__

#include <stddef.h>
#include <stdint.h>
#include <ghostty/vt/types.h>

/** @defgroup wasm WebAssembly Utilities
 *
 * Convenience functions for allocating various types in WebAssembly builds.
 * **These are only available the libghostty-vt wasm module.**
 *
 * Ghostty relies on pointers to various types for ABI compatibility, and
 * creating those pointers in Wasm can be tedious. These functions provide
 * a purely additive set of utilities that simplify memory management in
 * Wasm environments without changing the core C library API.
 *
 * @note These functions always use the default allocator. If you need
 * custom allocation strategies, you should allocate types manually using
 * your custom allocator. This is a very rare use case in the WebAssembly
 * world so these are optimized for simplicity.
 *
 * ## Example Usage
 *
 * Here's a simple example of using the Wasm utilities with the key encoder:
 *
 * @code
 * const { exports } = wasmInstance;
 * const view = new DataView(wasmMemory.buffer);
 *
 * // Create key encoder
 * const encoderPtr = exports.ghostty_wasm_alloc_opaque();
 * exports.ghostty_key_encoder_new(null, encoderPtr);
 * const encoder = view.getUint32(encoder, true);
 *
 * // Configure encoder with Kitty protocol flags
 * const flagsPtr = exports.ghostty_wasm_alloc_u8();
 * view.setUint8(flagsPtr, 0x1F);
 * exports.ghostty_key_encoder_setopt(encoder, 5, flagsPtr);
 *
 * // Allocate output buffer and size pointer
 * const bufferSize = 32;
 * const bufPtr = exports.ghostty_wasm_alloc_u8_array(bufferSize);
 * const writtenPtr = exports.ghostty_wasm_alloc_usize();
 *
 * // Encode the key event
 * exports.ghostty_key_encoder_encode(
 *     encoder, eventPtr, bufPtr, bufferSize, writtenPtr
 * );
 *
 * // Read encoded output
 * const bytesWritten = view.getUint32(writtenPtr, true);
 * const encoded = new Uint8Array(wasmMemory.buffer, bufPtr, bytesWritten);
 * @endcode
 *
 * @remark The code above is pretty ugly! This is the lowest level interface
 * to the libghostty-vt Wasm module. In practice, this should be wrapped
 * in a higher-level API that abstracts away all this.
 *
 * @{
 */

/**
 * Allocate an opaque pointer. This can be used for any opaque pointer
 * types such as GhosttyKeyEncoder, GhosttyKeyEvent, etc.
 *
 * @return Pointer to allocated opaque pointer, or NULL if allocation failed
 * @ingroup wasm
 */
GHOSTTY_API void** ghostty_wasm_alloc_opaque(void);

/**
 * Free an opaque pointer allocated by ghostty_wasm_alloc_opaque().
 *
 * @param ptr Pointer to free, or NULL (NULL is safely ignored)
 * @ingroup wasm
 */
GHOSTTY_API void ghostty_wasm_free_opaque(void **ptr);

/**
 * Allocate an array of uint8_t values.
 *
 * @param len Number of uint8_t elements to allocate
 * @return Pointer to allocated array, or NULL if allocation failed
 * @ingroup wasm
 */
GHOSTTY_API uint8_t* ghostty_wasm_alloc_u8_array(size_t len);

/**
 * Free an array allocated by ghostty_wasm_alloc_u8_array().
 *
 * @param ptr Pointer to the array to free, or NULL (NULL is safely ignored)
 * @param len Length of the array (must match the length passed to alloc)
 * @ingroup wasm
 */
GHOSTTY_API void ghostty_wasm_free_u8_array(uint8_t *ptr, size_t len);

/**
 * Allocate an array of uint16_t values.
 *
 * @param len Number of uint16_t elements to allocate
 * @return Pointer to allocated array, or NULL if allocation failed
 * @ingroup wasm
 */
GHOSTTY_API uint16_t* ghostty_wasm_alloc_u16_array(size_t len);

/**
 * Free an array allocated by ghostty_wasm_alloc_u16_array().
 *
 * @param ptr Pointer to the array to free, or NULL (NULL is safely ignored)
 * @param len Length of the array (must match the length passed to alloc)
 * @ingroup wasm
 */
GHOSTTY_API void ghostty_wasm_free_u16_array(uint16_t *ptr, size_t len);

/**
 * Allocate a single uint8_t value.
 *
 * @return Pointer to allocated uint8_t, or NULL if allocation failed
 * @ingroup wasm
 */
GHOSTTY_API uint8_t* ghostty_wasm_alloc_u8(void);

/**
 * Free a uint8_t allocated by ghostty_wasm_alloc_u8().
 *
 * @param ptr Pointer to free, or NULL (NULL is safely ignored)
 * @ingroup wasm
 */
GHOSTTY_API void ghostty_wasm_free_u8(uint8_t *ptr);

/**
 * Allocate a single size_t value.
 *
 * @return Pointer to allocated size_t, or NULL if allocation failed
 * @ingroup wasm
 */
GHOSTTY_API size_t* ghostty_wasm_alloc_usize(void);

/**
 * Free a size_t allocated by ghostty_wasm_alloc_usize().
 *
 * @param ptr Pointer to free, or NULL (NULL is safely ignored)
 * @ingroup wasm
 */
GHOSTTY_API void ghostty_wasm_free_usize(size_t *ptr);

/** @} */

#endif /* __wasm__ */

#endif /* GHOSTTY_VT_WASM_H */