added Linux arm64 SDK

2026-06-11 14:07:38 +12:00
parent c0395a49bd
commit cbf3f085d0
2160 changed files with 1 additions and 542 deletions
@@ -0,0 +1,150 @@
+/**************************************************************************************************
+ *  This file is a part of Ultralight, an ultra-portable web-browser engine.                      *
+ *                                                                                                *
+ *  See <https://ultralig.ht> for licensing and more.                                             *
+ *                                                                                                *
+ *  (C) 2024 Ultralight, Inc.                                                                     *
+ **************************************************************************************************/
+
+///
+/// @file CAPI_Bitmap.h
+///
+/// A thread-safe container for pixel data.
+///
+/// `#include <Ultralight/CAPI/CAPI_Bitmap.h>`
+///
+/// The bitmap class is used to store pixel data in a variety of formats. It intelligently manages
+/// the lifetime of the pixel buffer and provides thread-safe access to the pixel data.
+///
+/// ## Accessing Pixel Data
+///
+/// To access the pixel data, you must first lock the pixels using ulBitmapLockPixels(). This will
+/// return a pointer to the pixel buffer. An example follows:
+///
+/// ```
+/// void* pixels = ulBitmapLockPixels(bitmap);
+/// if (pixels) {
+///   // Zero out the pixel buffer
+///   memset(pixels, 0, ulBitmapGetSize(bitmap));
+/// }
+///
+/// // Unlock the pixels when you're done.
+/// ulBitmapUnlockPixels(bitmap);
+/// ```
+///
+#ifndef ULTRALIGHT_CAPI_BITMAP_H
+#define ULTRALIGHT_CAPI_BITMAP_H
+
+#include <Ultralight/CAPI/CAPI_Defines.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/******************************************************************************
+ * Bitmap
+ *****************************************************************************/
+
+///
+/// Create empty bitmap.
+///
+ULExport ULBitmap ulCreateEmptyBitmap();
+
+///
+/// Create bitmap with certain dimensions and pixel format.
+///
+ULExport ULBitmap ulCreateBitmap(unsigned int width, unsigned int height, ULBitmapFormat format);
+
+///
+/// Create bitmap from existing pixel buffer. @see Bitmap for help using this function.
+///
+ULExport ULBitmap ulCreateBitmapFromPixels(unsigned int width, unsigned int height,
+                                           ULBitmapFormat format, unsigned int row_bytes,
+                                           const void* pixels, size_t size, bool should_copy);
+
+///
+/// Create bitmap from copy.
+///
+ULExport ULBitmap ulCreateBitmapFromCopy(ULBitmap existing_bitmap);
+
+///
+/// Destroy a bitmap (you should only destroy Bitmaps you have explicitly created via one of the
+/// creation functions above.
+///
+ULExport void ulDestroyBitmap(ULBitmap bitmap);
+
+///
+/// Get the width in pixels.
+///
+ULExport unsigned int ulBitmapGetWidth(ULBitmap bitmap);
+
+///
+/// Get the height in pixels.
+///
+ULExport unsigned int ulBitmapGetHeight(ULBitmap bitmap);
+
+///
+/// Get the pixel format.
+///
+ULExport ULBitmapFormat ulBitmapGetFormat(ULBitmap bitmap);
+
+///
+/// Get the bytes per pixel.
+///
+ULExport unsigned int ulBitmapGetBpp(ULBitmap bitmap);
+
+///
+/// Get the number of bytes per row.
+///
+ULExport unsigned int ulBitmapGetRowBytes(ULBitmap bitmap);
+
+///
+/// Get the size in bytes of the underlying pixel buffer.
+///
+ULExport size_t ulBitmapGetSize(ULBitmap bitmap);
+
+///
+/// Whether or not this bitmap owns its own pixel buffer.
+///
+ULExport bool ulBitmapOwnsPixels(ULBitmap bitmap);
+
+///
+/// Lock pixels for reading/writing, returns pointer to pixel buffer.
+///
+ULExport void* ulBitmapLockPixels(ULBitmap bitmap);
+
+///
+/// Unlock pixels after locking.
+///
+ULExport void ulBitmapUnlockPixels(ULBitmap bitmap);
+
+///
+/// Get raw pixel buffer-- you should only call this if Bitmap is already locked.
+///
+ULExport void* ulBitmapRawPixels(ULBitmap bitmap);
+
+///
+/// Whether or not this bitmap is empty.
+///
+ULExport bool ulBitmapIsEmpty(ULBitmap bitmap);
+
+///
+/// Reset bitmap pixels to 0.
+///
+ULExport void ulBitmapErase(ULBitmap bitmap);
+
+///
+/// Write bitmap to a PNG on disk.
+///
+ULExport bool ulBitmapWritePNG(ULBitmap bitmap, const char* path);
+
+///
+/// This converts a BGRA bitmap to RGBA bitmap and vice-versa by swapping the red and blue channels.
+///
+ULExport void ulBitmapSwapRedBlueChannels(ULBitmap bitmap);
+
+#ifdef __cplusplus
+} // extern "C"
+#endif
+
+#endif // ULTRALIGHT_CAPI_BITMAP_H
@@ -0,0 +1,84 @@
+/**************************************************************************************************
+ *  This file is a part of Ultralight, an ultra-portable web-browser engine.                      *
+ *                                                                                                *
+ *  See <https://ultralig.ht> for licensing and more.                                             *
+ *                                                                                                *
+ *  (C) 2024 Ultralight, Inc.                                                                     *
+ **************************************************************************************************/
+
+///
+/// @file CAPI_Buffer.h
+///
+/// A fixed-size container for raw byte data.
+///
+/// `#include <Ultralight/CAPI/CAPI_Buffer.h>`
+///
+/// This class is used to represent raw data buffers in Ultralight. It intelligently manages the
+/// lifetime of the data and can optionally call a user-supplied callback to deallocate the data
+/// when the Buffer is destroyed.
+///
+#ifndef ULTRALIGHT_CAPI_BUFFER_H
+#define ULTRALIGHT_CAPI_BUFFER_H
+
+#include <Ultralight/CAPI/CAPI_Defines.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef void (*ulDestroyBufferCallback)(void* user_data, void* data);
+
+///
+/// Create a Buffer from existing, user-owned data without any copies. An optional, user-supplied
+/// callback will be called to deallocate data upon destruction.
+///
+/// @param  data                  A pointer to the data.
+///
+/// @param  size                  Size of the data in bytes.
+///
+/// @param  user_data             Optional user data that will be passed to destruction_callback
+///                               when the returned Buffer is destroyed.
+///
+/// @param  destruction_callback  Optional callback that will be called upon destruction. Pass a
+///                               null pointer if you don't want to be informed of destruction.
+///
+ULExport ULBuffer ulCreateBuffer(void* data, size_t size, void* user_data,
+                                 ulDestroyBufferCallback destruction_callback);
+
+///
+/// Create a Buffer from existing data, a deep copy of data will be made.
+///
+ULExport ULBuffer ulCreateBufferFromCopy(const void* data, size_t size);
+
+///
+/// Destroy buffer (you should destroy any buffers you explicitly Create).
+///
+ULExport void ulDestroyBuffer(ULBuffer buffer);
+
+///
+/// Get a pointer to the raw byte data.
+///
+ULExport void* ulBufferGetData(ULBuffer buffer);
+
+///
+/// Get the size in bytes.
+///
+ULExport size_t ulBufferGetSize(ULBuffer buffer);
+
+///
+/// Get the user data associated with this Buffer, if any.
+///
+ULExport void* ulBufferGetUserData(ULBuffer buffer);
+
+///
+/// Check whether this Buffer owns its own data (Buffer was created via ulCreateBufferFromCopy).
+/// If this is false, Buffer will call the user-supplied destruction callback to deallocate data
+/// when this Buffer instance is destroyed.
+///
+ULExport bool ulBufferOwnsData(ULBuffer buffer);
+
+#ifdef __cplusplus
+} // extern "C"
+#endif
+
+#endif // ULTRALIGHT_CAPI_BUFFER_H
@@ -0,0 +1,66 @@
+/**************************************************************************************************
+ *  This file is a part of Ultralight, an ultra-portable web-browser engine.                      *
+ *                                                                                                *
+ *  See <https://ultralig.ht> for licensing and more.                                             *
+ *                                                                                                *
+ *  (C) 2024 Ultralight, Inc.                                                                     *
+ **************************************************************************************************/
+
+///
+/// @file CAPI_Clipboard.h
+///
+/// User-defined clipboard interface.
+///
+/// `#include <Ultralight/CAPI/CAPI_Clipboard.h>`
+///
+/// The library uses this to read and write data to the system's clipboard.
+///
+/// @see ulPlatformSetClipboard()
+///
+#ifndef ULTRALIGHT_CAPI_CLIPBOARD_H
+#define ULTRALIGHT_CAPI_CLIPBOARD_H
+
+#include <Ultralight/CAPI/CAPI_Defines.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/******************************************************************************
+ * Clipboard
+ *****************************************************************************/
+
+///
+/// The callback invoked when the library wants to clear the system's clipboard.
+///
+typedef void (*ULClipboardClearCallback)();
+
+///
+/// The callback invoked when the library wants to read from the system's clipboard.
+///
+/// You should store the result (if any) in 'result'.
+///
+typedef void (*ULClipboardReadPlainTextCallback)(ULString result);
+
+///
+/// The callback invoked when the library wants to write to the system's clipboard.
+///
+typedef void (*ULClipboardWritePlainTextCallback)(ULString text);
+
+///
+/// User-defined clipboard interface.
+///
+/// You should implement each of these callbacks, then pass an instance of this struct containing
+/// your callbacks to ulPlatformSetClipboard().
+///
+typedef struct {
+  ULClipboardClearCallback clear;
+  ULClipboardReadPlainTextCallback read_plain_text;
+  ULClipboardWritePlainTextCallback write_plain_text;
+} ULClipboard;
+
+#ifdef __cplusplus
+} // extern "C"
+#endif
+
+#endif // ULTRALIGHT_CAPI_CLIPBOARD_H
@@ -0,0 +1,235 @@
+/**************************************************************************************************
+ *  This file is a part of Ultralight, an ultra-portable web-browser engine.                      *
+ *                                                                                                *
+ *  See <https://ultralig.ht> for licensing and more.                                             *
+ *                                                                                                *
+ *  (C) 2024 Ultralight, Inc.                                                                     *
+ **************************************************************************************************/
+
+///
+/// @file CAPI_Config.h
+///
+/// Core configuration for the renderer.
+///
+/// `#include <Ultralight/CAPI/CAPI_Config.h>`
+///
+/// These are various configuration options that can be used to customize the behavior of the
+/// library. These options can only be set once before creating the Renderer.
+///
+#ifndef ULTRALIGHT_CAPI_CONFIG_H
+#define ULTRALIGHT_CAPI_CONFIG_H
+
+#include <Ultralight/CAPI/CAPI_Defines.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/******************************************************************************
+ * Config
+ *****************************************************************************/
+
+///
+/// Create config with default values (see <Ultralight/platform/Config.h>).
+///
+ULExport ULConfig ulCreateConfig();
+
+///
+/// Destroy config.
+///
+ULExport void ulDestroyConfig(ULConfig config);
+
+///
+/// A writable OS file path to store persistent Session data in.
+///
+/// This data may include cookies, cached network resources, indexed DB, etc.
+///
+/// @note Files are only written to the path when using a persistent Session.
+///
+ULExport void ulConfigSetCachePath(ULConfig config, ULString cache_path);
+
+///
+/// The relative path to the resources folder (loaded via the FileSystem API).
+///
+/// The library loads certain resources (SSL certs, ICU data, etc.) from the FileSystem API
+/// during runtime (eg, `file:///resources/cacert.pem`).
+///
+/// You can customize the relative file path to the resources folder by modifying this setting.
+///
+/// (Default = "resources/")
+///
+ULExport void ulConfigSetResourcePathPrefix(ULConfig config, ULString resource_path_prefix);
+
+///
+/// The winding order for front-facing triangles.
+///
+/// @pre Only used when GPU rendering is enabled for the View.
+///
+/// (Default = kFaceWinding_CounterClockwise)
+///
+ULExport void ulConfigSetFaceWinding(ULConfig config, ULFaceWinding winding);
+
+///
+/// The hinting algorithm to use when rendering fonts. (Default = kFontHinting_Normal)
+/// 
+/// @see ULFontHinting
+///
+ULExport void ulConfigSetFontHinting(ULConfig config, ULFontHinting font_hinting);
+
+///
+/// The gamma to use when compositing font glyphs, change this value to adjust contrast (Adobe and
+/// Apple prefer 1.8, others may prefer 2.2). (Default = 1.8)
+///
+ULExport void ulConfigSetFontGamma(ULConfig config, double font_gamma);
+
+///
+/// Global user-defined CSS string (included before any CSS on the page).
+///
+/// You can use this to override default styles for various elements on the page.
+///
+/// @note This is an actual string of CSS, not a file path.
+///
+ULExport void ulConfigSetUserStylesheet(ULConfig config, ULString css_string);
+
+///
+/// Whether or not to continuously repaint any Views, regardless if they are dirty.
+///
+/// This is mainly used to diagnose painting/shader issues and profile performance.
+/// 
+/// (Default = False)
+///
+ULExport void ulConfigSetForceRepaint(ULConfig config, bool enabled);
+
+///
+/// The delay (in seconds) between every tick of a CSS animation.
+///
+/// (Default = 1.0 / 60.0)
+///
+ULExport void ulConfigSetAnimationTimerDelay(ULConfig config, double delay);
+
+///
+/// The delay (in seconds) between every tick of a smooth scroll animation.
+///
+/// (Default = 1.0 / 60.0)
+///
+ULExport void ulConfigSetScrollTimerDelay(ULConfig config, double delay);
+
+///
+/// The delay (in seconds) between every call to the recycler.
+///
+/// The library attempts to reclaim excess memory during calls to the internal recycler. You can
+/// change how often this is run by modifying this value.
+/// 
+/// (Default = 4.0)
+///
+ULExport void ulConfigSetRecycleDelay(ULConfig config, double delay);
+
+///
+/// The size of WebCore's memory cache in bytes.
+///
+/// @note  You should increase this if you anticipate handling pages with large resources, Safari
+///        typically uses 128+ MiB for its cache.
+///
+/// (Default = 64 * 1024 * 1024)
+///
+ULExport void ulConfigSetMemoryCacheSize(ULConfig config, unsigned int size);
+
+///
+/// The number of pages to keep in the cache. (Default: 0, none)
+///
+/// @note
+/// \parblock
+///
+/// Safari typically caches about 5 pages and maintains an on-disk cache to support typical
+/// web-browsing activities.
+///
+/// If you increase this, you should probably increase the memory cache size as well.
+///
+/// \endparblock
+///
+/// (Default = 0)
+///
+ULExport void ulConfigSetPageCacheSize(ULConfig config, unsigned int size);
+
+///
+/// The system's physical RAM size in bytes.
+///
+/// JavaScriptCore tries to detect the system's physical RAM size to set reasonable allocation
+/// limits. Set this to anything other than 0 to override the detected value. Size is in bytes.
+///
+/// This can be used to force JavaScriptCore to be more conservative with its allocation strategy
+/// (at the cost of some performance).
+///
+ULExport void ulConfigSetOverrideRAMSize(ULConfig config, unsigned int size);
+
+///
+/// The minimum size of large VM heaps in JavaScriptCore.
+///
+/// Set this to a lower value to make these heaps start with a smaller initial value.
+///
+/// (Default = 32 * 1024 * 1024)
+///
+ULExport void ulConfigSetMinLargeHeapSize(ULConfig config, unsigned int size);
+
+///
+/// The minimum size of small VM heaps in JavaScriptCore.
+///
+/// Set this to a lower value to make these heaps start with a smaller initial value.
+///
+/// (Default = 1 * 1024 * 1024)
+/// 
+ULExport void ulConfigSetMinSmallHeapSize(ULConfig config, unsigned int size);
+
+///
+/// The number of threads to use in the Renderer (for parallel painting on the CPU, etc.).
+///
+/// You can set this to a certain number to limit the number of threads to spawn.
+///
+/// @note
+/// \parblock
+///
+/// If this value is 0, the number of threads will be determined at runtime using the following
+/// formula:
+///
+///   ```
+///   max(PhysicalProcessorCount() - 1, 1)
+///   ```
+///
+/// \endparblock
+///
+ULExport void ulConfigSetNumRendererThreads(ULConfig config, unsigned int num_renderer_threads);
+
+///
+/// The max amount of time (in seconds) to allow repeating timers to run during each call to
+/// Renderer::Update.
+///
+/// The library will attempt to throttle timers if this time budget is exceeded.
+/// 
+/// (Default = 1.0 / 200.0)
+///
+ULExport void ulConfigSetMaxUpdateTime(ULConfig config, double max_update_time);
+
+///
+/// The alignment (in bytes) of the BitmapSurface when using the CPU renderer.
+///
+/// The underlying bitmap associated with each BitmapSurface will have row_bytes padded to reach
+/// this alignment.
+///
+/// Aligning the bitmap helps improve performance when using the CPU renderer. Determining the
+/// proper value to use depends on the CPU architecture and max SIMD instruction set used.
+///
+/// We generally target the 128-bit SSE2 instruction set across most PC platforms so '16' is a safe
+/// value to use.
+///
+/// You can set this to '0' to perform no padding (row_bytes will always be width * 4) at a slight
+/// cost to performance.
+///
+/// (Default = 16)
+///
+ULExport void ulConfigSetBitmapAlignment(ULConfig config, unsigned int bitmap_alignment);
+
+#ifdef __cplusplus
+} // extern "C"
+#endif
+
+#endif // ULTRALIGHT_CAPI_CONFIG_H
@@ -0,0 +1,318 @@
+/**************************************************************************************************
+ *  This file is a part of Ultralight, an ultra-portable web-browser engine.                      *
+ *                                                                                                *
+ *  See <https://ultralig.ht> for licensing and more.                                             *
+ *                                                                                                *
+ *  (C) 2024 Ultralight, Inc.                                                                     *
+ **************************************************************************************************/
+
+///
+/// @file CAPI_Defines.h
+///
+/// Various defines and utility functions for the C API.
+///
+/// `#include <Ultralight/CAPI/CAPI_Defines.h>`
+///
+/// This file contains various defines, structures, and utility functions for the C API.
+///
+#ifndef ULTRALIGHT_CAPI_DEFINES_H
+#define ULTRALIGHT_CAPI_DEFINES_H
+
+#include <stddef.h>
+#include <stdint.h>
+#include <JavaScriptCore/JavaScript.h>
+#ifdef __OBJC__
+#import <AppKit/NSEvent.h>
+#endif
+
+#if defined(ULTRALIGHT_STATIC_BUILD)
+#define ULExport
+#else
+#if defined(__WIN32__) || defined(_WIN32)
+#if defined(ULTRALIGHT_IMPLEMENTATION)
+#define ULExport __declspec(dllexport)
+#else
+#define ULExport __declspec(dllimport)
+#endif
+#else
+#define ULExport __attribute__((visibility("default")))
+#endif
+#endif
+
+#if defined(__WIN32__) || defined(_WIN32)
+#define _thread_local __declspec(thread)
+#ifndef _NATIVE_WCHAR_T_DEFINED
+#define DISABLE_NATIVE_WCHAR_T
+typedef unsigned short ULChar16;
+#else
+typedef wchar_t ULChar16;
+#endif
+#else
+#define _thread_local __thread
+typedef unsigned short ULChar16;
+#endif
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef struct C_Config* ULConfig;
+typedef struct C_Renderer* ULRenderer;
+typedef struct C_Session* ULSession;
+typedef struct C_ViewConfig* ULViewConfig;
+typedef struct C_View* ULView;
+typedef struct C_Bitmap* ULBitmap;
+typedef struct C_String* ULString;
+typedef struct C_Buffer* ULBuffer;
+typedef struct C_KeyEvent* ULKeyEvent;
+typedef struct C_MouseEvent* ULMouseEvent;
+typedef struct C_ScrollEvent* ULScrollEvent;
+typedef struct C_GamepadEvent* ULGamepadEvent;
+typedef struct C_GamepadAxisEvent* ULGamepadAxisEvent;
+typedef struct C_GamepadButtonEvent* ULGamepadButtonEvent;
+typedef struct C_Surface* ULSurface;
+typedef struct C_Surface* ULBitmapSurface;
+typedef struct C_FontFile* ULFontFile;
+typedef struct C_ImageSource* ULImageSource;
+
+typedef enum {
+  kMessageSource_XML = 0,
+  kMessageSource_JS,
+  kMessageSource_Network,
+  kMessageSource_ConsoleAPI,
+  kMessageSource_Storage,
+  kMessageSource_AppCache,
+  kMessageSource_Rendering,
+  kMessageSource_CSS,
+  kMessageSource_Security,
+  kMessageSource_ContentBlocker,
+  kMessageSource_Media,
+  kMessageSource_MediaSource,
+  kMessageSource_WebRTC,
+  kMessageSource_ITPDebug,
+  kMessageSource_PrivateClickMeasurement,
+  kMessageSource_PaymentRequest,
+  kMessageSource_Other,
+} ULMessageSource;
+
+typedef enum {
+  kMessageLevel_Log = 0,
+  kMessageLevel_Warning,
+  kMessageLevel_Error,
+  kMessageLevel_Debug,
+  kMessageLevel_Info,
+} ULMessageLevel;
+
+typedef enum {
+  kCursor_Pointer = 0,
+  kCursor_Cross,
+  kCursor_Hand,
+  kCursor_IBeam,
+  kCursor_Wait,
+  kCursor_Help,
+  kCursor_EastResize,
+  kCursor_NorthResize,
+  kCursor_NorthEastResize,
+  kCursor_NorthWestResize,
+  kCursor_SouthResize,
+  kCursor_SouthEastResize,
+  kCursor_SouthWestResize,
+  kCursor_WestResize,
+  kCursor_NorthSouthResize,
+  kCursor_EastWestResize,
+  kCursor_NorthEastSouthWestResize,
+  kCursor_NorthWestSouthEastResize,
+  kCursor_ColumnResize,
+  kCursor_RowResize,
+  kCursor_MiddlePanning,
+  kCursor_EastPanning,
+  kCursor_NorthPanning,
+  kCursor_NorthEastPanning,
+  kCursor_NorthWestPanning,
+  kCursor_SouthPanning,
+  kCursor_SouthEastPanning,
+  kCursor_SouthWestPanning,
+  kCursor_WestPanning,
+  kCursor_Move,
+  kCursor_VerticalText,
+  kCursor_Cell,
+  kCursor_ContextMenu,
+  kCursor_Alias,
+  kCursor_Progress,
+  kCursor_NoDrop,
+  kCursor_Copy,
+  kCursor_None,
+  kCursor_NotAllowed,
+  kCursor_ZoomIn,
+  kCursor_ZoomOut,
+  kCursor_Grab,
+  kCursor_Grabbing,
+  kCursor_Custom
+} ULCursor;
+
+typedef enum {
+  ///
+  /// Alpha channel only, 8-bits per pixel.
+  ///
+  /// Encoding: 8-bits per channel, unsigned normalized.
+  ///
+  /// Color-space: Linear (no gamma), alpha-coverage only.
+  ///
+  kBitmapFormat_A8_UNORM,
+
+  ///
+  /// Blue Green Red Alpha channels, 32-bits per pixel.
+  ///
+  /// Encoding: 8-bits per channel, unsigned normalized.
+  ///
+  /// Color-space: sRGB gamma with premultiplied linear alpha channel.
+  ///
+  kBitmapFormat_BGRA8_UNORM_SRGB
+} ULBitmapFormat;
+
+typedef enum {
+  ///
+  /// Key-Down event type. This type does **not** trigger accelerator commands in WebCore (eg, 
+  /// Ctrl+C for copy is an accelerator command).
+  ///
+  /// @warning  You should probably use kKeyEventType_RawKeyDown instead. This type is only here for
+  ///           historic compatibility with WebCore's key event types.
+  ///
+  kKeyEventType_KeyDown,
+
+  ///
+  /// Key-Up event type. Use this when a physical key is released.
+  ///
+  kKeyEventType_KeyUp,
+
+  ///
+  /// Raw Key-Down type. Use this when a physical key is pressed.
+  ///
+  kKeyEventType_RawKeyDown,
+
+  ///
+  /// Character input event type. Use this when the OS generates text from
+  /// a physical key being pressed (eg, WM_CHAR on Windows).
+  ///
+  kKeyEventType_Char,
+} ULKeyEventType;
+
+typedef enum {
+  kMouseEventType_MouseMoved,
+  kMouseEventType_MouseDown,
+  kMouseEventType_MouseUp,
+} ULMouseEventType;
+
+typedef enum {
+  kMouseButton_None = 0,
+  kMouseButton_Left,
+  kMouseButton_Middle,
+  kMouseButton_Right,
+} ULMouseButton;
+
+typedef enum {
+  kScrollEventType_ScrollByPixel,
+  kScrollEventType_ScrollByPage,
+} ULScrollEventType;
+
+typedef enum {
+  kGamepadEventType_Connected,
+  kGamepadEventType_Disconnected,
+} ULGamepadEventType;
+
+typedef enum {
+  kFaceWinding_Clockwise,
+  kFaceWinding_CounterClockwise,
+} ULFaceWinding;
+
+typedef enum {
+  ///
+  /// Lighter hinting algorithm-- glyphs are slightly fuzzier but better
+  /// resemble their original shape. This is achieved by snapping glyphs to the
+  /// pixel grid only vertically which better preserves inter-glyph spacing.
+  ///
+  kFontHinting_Smooth,
+
+  ///
+  /// Default hinting algorithm-- offers a good balance between sharpness and
+  /// shape at smaller font sizes.
+  ///
+  kFontHinting_Normal,
+
+  ///
+  /// Strongest hinting algorithm-- outputs only black/white glyphs. The result
+  /// is usually unpleasant if the underlying TTF does not contain hints for
+  /// this type of rendering.
+  ///
+  kFontHinting_Monochrome,
+} ULFontHinting;
+
+typedef struct {
+  float left;
+  float top;
+  float right;
+  float bottom;
+} ULRect;
+
+typedef struct {
+  int left;
+  int top;
+  int right;
+  int bottom;
+} ULIntRect;
+
+///
+/// Offscreen render target, used when rendering Views via the GPU renderer.
+///
+/// When a View is rendered via the GPU renderer (see ulViewIsAccelerated()), it will be rendered to
+/// an offscreen render target (ulViewGetRenderTarget()) that you can display in your application.
+///
+/// This is intended to be used with a custom ULGPUDriver implementation in a game or similar 
+/// application (ulPlatformSetGPUDriver()).
+///
+typedef struct {
+  bool is_empty;
+  unsigned int width;
+  unsigned int height;
+  unsigned int texture_id;
+  unsigned int texture_width;
+  unsigned int texture_height;
+  ULBitmapFormat texture_format;
+  ULRect uv_coords;
+  unsigned int render_buffer_id;
+} ULRenderTarget;
+
+/******************************************************************************
+ * Version
+ *****************************************************************************/
+
+///
+/// Get the version string of the library in MAJOR.MINOR.PATCH format.
+///
+ULExport const char* ulVersionString();
+
+///
+/// Get the numeric major version of the library.
+///
+ULExport unsigned int ulVersionMajor();
+
+///
+/// Get the numeric minor version of the library.
+///
+ULExport unsigned int ulVersionMinor();
+
+///
+/// Get the numeric patch version of the library.
+///
+ULExport unsigned int ulVersionPatch();
+
+///
+/// Get the full WebKit version string.
+/// 
+ULExport const char* ulWebKitVersionString();
+
+#ifdef __cplusplus
+} // extern "C"
+#endif
+
+#endif // ULTRALIGHT_CAPI_DEFINES_H
@@ -0,0 +1,94 @@
+/**************************************************************************************************
+ *  This file is a part of Ultralight, an ultra-portable web-browser engine.                      *
+ *                                                                                                *
+ *  See <https://ultralig.ht> for licensing and more.                                             *
+ *                                                                                                *
+ *  (C) 2024 Ultralight, Inc.                                                                     *
+ **************************************************************************************************/
+
+///
+/// @file CAPI_FileSystem.h
+///
+/// User-defined file system interface.
+///
+/// `#include <Ultralight/CAPI/CAPI_FileSystem.h>`
+///
+/// The library uses this to load file data (ie, raw file bytes) for a given file URL 
+/// (eg, `file:///page.html`) .
+///
+/// You can provide the library with your own FileSystem implementation (ULFileSystem) so that file
+/// data is provided directly by your application (eg, from memory, from a virtual file system,
+/// etc).
+///
+/// @see ulPlatformSetFileSystem
+/// 
+#ifndef ULTRALIGHT_CAPI_FILESYSTEM_H
+#define ULTRALIGHT_CAPI_FILESYSTEM_H
+
+#include <Ultralight/CAPI/CAPI_Defines.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/******************************************************************************
+ * File System
+ *****************************************************************************/
+
+///
+/// The callback invoked when the FileSystem wants to check if a file path exists, return true if it
+/// exists.
+///
+typedef bool (*ULFileSystemFileExistsCallback)(ULString path);
+
+///
+/// Get the mime-type of the file (eg "text/html").
+///
+/// This is usually determined by analyzing the file extension.
+///
+/// If a mime-type cannot be determined, you should return "application/unknown" for this value.
+/// 
+/// The library will consume the result and call ulDestroyString() after this call returns.
+///
+typedef ULString (*ULFileSystemGetFileMimeTypeCallback)(ULString path);
+
+///
+/// Get the charset / encoding of the file (eg "utf-8").
+///
+/// This is only important for text-based files and is usually determined by analyzing the
+/// contents of the file.
+///
+/// If a charset cannot be determined, it's usually safe to return "utf-8" for this value.
+/// 
+/// The library will consume the result and call ulDestroyString() after this call returns.
+///
+typedef ULString (*ULFileSystemGetFileCharsetCallback)(ULString path);
+
+///
+/// Open file for reading and map it to a Buffer.
+///
+/// To minimize copies, you should map the requested file into memory and use ulCreateBuffer()
+/// to wrap the data pointer (unmapping should be performed in the destruction callback).
+///
+/// If the file was unable to be opened, you should return NULL for this value.
+///
+typedef ULBuffer (*ULFileSystemOpenFileCallback)(ULString path);
+
+/// 
+/// User-defined file system interface.
+///
+/// You should implement each of these callbacks, then pass an instance of this struct containing
+/// your callbacks to ulPlatformSetFileSystem().
+///
+typedef struct {
+  ULFileSystemFileExistsCallback file_exists;
+  ULFileSystemGetFileMimeTypeCallback get_file_mime_type;
+  ULFileSystemGetFileCharsetCallback get_file_charset;
+  ULFileSystemOpenFileCallback open_file;
+} ULFileSystem;
+
+#ifdef __cplusplus
+} // extern "C"
+#endif
+
+#endif // ULTRALIGHT_CAPI_FILESYSTEM_H
@@ -0,0 +1,52 @@
+/**************************************************************************************************
+ *  This file is a part of Ultralight, an ultra-portable web-browser engine.                      *
+ *                                                                                                *
+ *  See <https://ultralig.ht> for licensing and more.                                             *
+ *                                                                                                *
+ *  (C) 2024 Ultralight, Inc.                                                                     *
+ **************************************************************************************************/
+
+///
+/// @file CAPI_FontFile.h
+///
+/// Font file interface.
+///
+/// `#include <Ultralight/CAPI/CAPI_FontFile.h>`
+///
+/// The font file interface represents a font file: either on-disk path or in-memory file contents.
+///
+/// @see ULFontLoader
+///
+#ifndef ULTRALIGHT_CAPI_FONTFILE_H
+#define ULTRALIGHT_CAPI_FONTFILE_H
+
+#include <Ultralight/CAPI/CAPI_Defines.h>
+#include <Ultralight/CAPI/CAPI_String.h>
+#include <Ultralight/CAPI/CAPI_Buffer.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+///
+/// Create a font file from an on-disk file path.
+///
+/// @note  The file path should already exist.
+///
+ULExport ULFontFile ulFontFileCreateFromFilePath(ULString file_path);
+
+///
+/// Create a font file from an in-memory buffer.
+///
+ULExport ULFontFile ulFontFileCreateFromBuffer(ULBuffer buffer);
+
+///
+/// Destroy font file
+///
+ULExport void ulDestroyFontFile(ULFontFile font_file);
+
+#ifdef __cplusplus
+} // extern "C"
+#endif
+
+#endif // ULTRALIGHT_CAPI_FONTFILE_H
@@ -0,0 +1,99 @@
+/**************************************************************************************************
+ *  This file is a part of Ultralight, an ultra-portable web-browser engine.                      *
+ *                                                                                                *
+ *  See <https://ultralig.ht> for licensing and more.                                             *
+ *                                                                                                *
+ *  (C) 2024 Ultralight, Inc.                                                                     *
+ **************************************************************************************************/
+
+///
+/// @file CAPI_FontLoader.h
+///
+/// User-defined font loader interface.
+///
+/// `#include <Ultralight/CAPI/CAPI_FontLoader.h>`
+///
+/// The library uses this to load a font file (eg, `Arial.ttf`) for a given font description (eg, 
+/// `font-family: Arial;`).
+///
+/// Every OS has its own library of installed system fonts. The FontLoader interface is used to
+/// lookup these fonts and fetch the actual font data (raw TTF/OTF file data) for a given font
+/// description.
+///
+/// You can provide the library with your own font loader implementation so that you can bundle
+/// fonts with your application rather than relying on the system's installed fonts.
+///
+/// @see ulPlatformSetFontLoader
+/// 
+#ifndef ULTRALIGHT_CAPI_FONTLOADER_H
+#define ULTRALIGHT_CAPI_FONTLOADER_H
+
+#include <Ultralight/CAPI/CAPI_Defines.h>
+#include <Ultralight/CAPI/CAPI_FontFile.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/******************************************************************************
+ * Font Loader
+ *****************************************************************************/
+
+///
+/// Fallback font family name. Will be used if all other fonts fail to load.
+///
+/// @note  This font should be guaranteed to exist (eg, ULFontLoader::load should not fail when
+///        when passed this font family name).
+/// 
+/// @note  The returned ULString instance will be consumed (ulDestroyString will be called on it).
+///
+typedef ULString (*ULFontLoaderGetFallbackFont)();
+
+///
+/// Fallback font family name that can render the specified characters. This is mainly used to
+/// support CJK (Chinese, Japanese, Korean) text display.
+///
+/// @param  characters  One or more UTF-16 characters. This is almost always a single character.
+///
+/// @param  weight      Font weight.
+///
+/// @param  italic      Whether or not italic is requested.
+///
+/// @return  Should return a font family name that can render the text. The returned ULString
+///          instance will be consumed (ulDestroyString will be called on it).
+///
+typedef ULString (*ULFontLoaderGetFallbackFontForCharacters)(ULString characters, int weight,
+	                                                         bool italic);
+
+///
+/// Get the actual font file data (TTF/OTF) for a given font description.
+///
+/// @param  family  Font family name.
+///
+/// @param  weight  Font weight.
+///
+/// @param  italic  Whether or not italic is requested.
+///
+/// @return  A font file matching the given description (either an on-disk font filepath or an
+///          in-memory file buffer). You can return NULL here and the loader will fallback to
+///          another font.
+///
+typedef ULFontFile (*ULFontLoaderLoad)(ULString family, int weight, bool italic);
+
+/// 
+/// User-defined font loader interface.
+///
+/// You should implement each of these callbacks, then pass an instance of this struct containing
+/// your callbacks to ulPlatformSetFontLoader().
+///
+typedef struct {
+  ULFontLoaderGetFallbackFont get_fallback_font;
+  ULFontLoaderGetFallbackFontForCharacters get_fallback_font_for_characters;
+  ULFontLoaderLoad load;
+} ULFontLoader;
+
+#ifdef __cplusplus
+} // extern "C"
+#endif
+
+#endif // ULTRALIGHT_CAPI_FONTLOADER_H
@@ -0,0 +1,478 @@
+/**************************************************************************************************
+ *  This file is a part of Ultralight, an ultra-portable web-browser engine.                      *
+ *                                                                                                *
+ *  See <https://ultralig.ht> for licensing and more.                                             *
+ *                                                                                                *
+ *  (C) 2024 Ultralight, Inc.                                                                     *
+ **************************************************************************************************/
+
+// clang-format off
+
+///
+/// @file CAPI_GPUDriver.h
+///
+/// User-defined GPU driver interface.
+///
+/// `#include <Ultralight/CAPI/CAPI_GPUDriver.h>`
+///
+/// The library uses this to optionally render Views on the GPU (see ulViewIsAccelerated()).
+///
+/// You can provide the library with your own GPU driver implementation so that all rendering is
+/// performed using an existing GPU context (useful for game engines).
+///
+/// When a View is rendered on the GPU, you can retrieve the backing texture ID via
+/// ulViewGetRenderTarget().
+///
+/// @see ulPlatformSetGPUDriver()
+///
+#ifndef ULTRALIGHT_CAPI_GPUDRIVER_H
+#define ULTRALIGHT_CAPI_GPUDRIVER_H
+
+#include <Ultralight/CAPI/CAPI_Defines.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/******************************************************************************
+ * GPUDriver
+ *****************************************************************************/
+
+///
+/// Render buffer description.
+///
+/// This structure describes a render buffer that can be used as a target for drawing commands.
+///
+typedef struct {
+  unsigned int texture_id; ///< The backing texture for this RenderBuffer
+  unsigned int width;      ///< The width of the RenderBuffer texture
+  unsigned int height;     ///< The height of the RenderBuffer texture
+  bool has_stencil_buffer; ///< Currently unused, always false.
+  bool has_depth_buffer;   ///< Currently unsued, always false.
+} ULRenderBuffer;
+
+/// \cond ignore
+///   This pragma pack(push, 1) command is important! 
+///   GPU structs should not be padded with any bytes.
+/// \endcond
+#pragma pack(push, 1)
+
+///
+/// Vertex layout for path vertices.
+///
+/// This struct is the in-memory layout for each path vertex (useful for synthesizing or modifying
+/// your own vertex data).
+///
+typedef struct {
+  float pos[2];
+  unsigned char color[4];
+  float obj[2];
+} ULVertex_2f_4ub_2f;
+
+///
+/// Vertex layout for quad vertices.
+///
+/// This struct is the in-memory layout for each quad vertex (useful for synthesizing or modifying
+/// your own vertex data).
+///
+typedef struct {
+  float pos[2];
+  unsigned char color[4];
+  float tex[2];
+  float obj[2];
+  float data0[4];
+  float data1[4];
+  float data2[4];
+  float data3[4];
+  float data4[4];
+  float data5[4];
+  float data6[4];
+} ULVertex_2f_4ub_2f_2f_28f;
+
+///
+/// End single-byte alignment.
+///
+#pragma pack(pop)
+
+///
+/// Vertex buffer formats.
+///
+/// This enumeration describes the format of a vertex buffer.
+///
+typedef enum {
+  kVertexBufferFormat_2f_4ub_2f,        ///< Vertex_2f_4ub_2f (used for path rendering)
+  kVertexBufferFormat_2f_4ub_2f_2f_28f, ///< Vertex_2f_4ub_2f_2f_28f (used for quad rendering)
+} ULVertexBufferFormat;
+
+///
+/// Vertex buffer description.
+///
+/// @see ULGPUDriver::create_geometry
+///
+typedef struct {
+  ULVertexBufferFormat format; ///< The format of the vertex buffer.
+  unsigned int size;           ///< The size of the vertex buffer in bytes.
+  unsigned char* data;         ///< The raw vertex buffer data.
+} ULVertexBuffer;
+
+///
+/// Vertex index type.
+///
+typedef unsigned int ULIndexType;
+
+///
+/// Index buffer description.
+///
+/// This structure describes an index buffer that can be used to index into a vertex buffer.
+///
+/// @note The index buffer is a simple array of IndexType values.
+///
+typedef struct {
+  unsigned int size;   ///< The size of the index buffer in bytes.
+  unsigned char* data; ///< The raw index buffer data.
+} ULIndexBuffer;
+
+///
+/// Shader program types, used with ULGPUState::shader_type
+///
+/// Each of these correspond to a vertex/pixel shader pair. You can find stock shader code for these
+/// in the `shaders` folder of the AppCore repo.
+///
+typedef enum {
+  kShaderType_Fill,     ///< Shader program for filling quad geometry.
+  kShaderType_FillPath, ///< Shader program for filling tesselated path geometry.
+} ULShaderType;
+
+///
+/// Raw 4x4 matrix as an array of floats in column-major order.
+///
+typedef struct {
+  float data[16];
+} ULMatrix4x4;
+
+///
+/// 4-component float vector
+///
+typedef struct {
+  float value[4];
+} ULvec4;
+
+///
+/// The state of the GPU for a given draw command.
+///
+/// This structure describes the current state of the GPU for a given draw command.
+///
+typedef struct {
+  /// Viewport width in pixels
+  unsigned int viewport_width;
+
+  /// Viewport height in pixels
+  unsigned int viewport_height;
+
+  /// Transform matrix-- you should multiply this with the screen-space orthographic projection
+  /// matrix then pass to the vertex shader.
+  ULMatrix4x4 transform;
+
+  /// Whether or not we should enable texturing for the current draw command.
+  bool enable_texturing;
+
+  /// Whether or not we should enable blending for the current draw command. If blending is
+  /// disabled, any drawn pixels should overwrite existing. Mainly used so we can modify alpha
+  /// values of the RenderBuffer during scissored clears.
+  bool enable_blend;
+
+  /// The vertex/pixel shader program pair to use for the current draw command. You should cast this
+  /// to ShaderType to get the corresponding enum.
+  unsigned char shader_type;
+
+  /// The render buffer to use for the current draw command.
+  unsigned int render_buffer_id;
+
+  /// The texture id to bind to slot #1. (Will be 0 if none)
+  unsigned int texture_1_id;
+
+  /// The texture id to bind to slot #2. (Will be 0 if none)
+  unsigned int texture_2_id;
+
+  /// The texture id to bind to slot #3. (Will be 0 if none)
+  unsigned int texture_3_id;
+
+  /// The uniform scalars (passed to the pixel shader via uniforms).
+  float uniform_scalar[8];
+
+  /// The uniform vectors (passed to the pixel shader via uniforms).
+  ULvec4 uniform_vector[8];
+
+  /// The clip size (passed to the pixel shader via uniforms).
+  unsigned char clip_size;
+
+  /// The clip stack (passed to the pixel shader via uniforms).
+  ULMatrix4x4 clip[8];
+
+  /// Whether or not scissor testing should be used for the current draw command.
+  bool enable_scissor;
+
+  /// The scissor rect to use for scissor testing (units in pixels)
+  ULIntRect scissor_rect;
+} ULGPUState;
+
+///
+/// The types of commands.
+///
+/// This enumeration describes the type of command to execute on the GPU. Used with
+/// ULCommand::command_type
+///
+typedef enum {
+  kCommandType_ClearRenderBuffer, ///< Clear the specified render buffer.
+  kCommandType_DrawGeometry,      ///< Draw the specified geometry to the specified render buffer.
+} ULCommandType;
+
+///
+/// A command to execute on the GPU.
+///
+/// This structure describes a command to be executed on the GPU.
+///
+/// Commands are dispatched to the GPU driver asynchronously via ULGPUDriver::update_command_list,
+/// the GPU driver should consume these commands and execute them at an appropriate time.
+///
+/// @see ULCommandList
+///
+typedef struct {
+  unsigned char command_type;  ///< The type of command to dispatch.
+  ULGPUState gpu_state;        ///< The current GPU state.
+  unsigned int geometry_id;    ///< The geometry ID to bind. (used with kCommandType_DrawGeometry)
+  unsigned int indices_count;  ///< The number of indices.   (used with kCommandType_DrawGeometry)
+  unsigned int indices_offset; ///< The index to start from. (used with kCommandType_DrawGeometry)
+} ULCommand;
+
+///
+/// List of commands to execute on the GPU.
+///
+/// @see ULGPUDriver::update_command_list
+///
+typedef struct {
+  unsigned int size;   ///< The number of commands in the list.
+  ULCommand* commands; ///< The raw command list data.
+} ULCommandList;
+
+///
+/// Callback for users to implement ULGPUDriver::begin_synchronize.
+///
+/// Called before any state (eg, create_texture(), update_texture(), destroy_texture(), etc.) is
+/// updated during a call to ulRender().
+///
+/// This is a good time to prepare the GPU for any state updates.
+///
+typedef void (*ULGPUDriverBeginSynchronizeCallback)();
+
+///
+/// Callback for users to implement ULGPUDriver::end_synchronize.
+///
+/// Called after all state has been updated during a call to ulRender().
+///
+typedef void (*ULGPUDriverEndSynchronizeCallback)();
+
+///
+/// Callback for users to implement ULGPUDriver::next_texture_id.
+///
+/// Get the next available texture ID.
+///
+/// This is used to generate a unique texture ID for each texture created by the library. The
+/// GPU driver implementation is responsible for mapping these IDs to a native ID.
+///
+/// @note Numbering should start at 1, 0 is reserved for "no texture".
+///
+/// @return Returns the next available texture ID.
+///
+typedef unsigned int (*ULGPUDriverNextTextureIdCallback)();
+
+///
+/// Callback for users to implement ULGPUDriver::create_texture.
+///
+/// Create a texture with a certain ID and optional bitmap.
+///
+/// @param texture_id  The texture ID to use for the new texture.
+///
+/// @param bitmap      The bitmap to initialize the texture with (can be empty).
+///
+/// @note If the Bitmap is empty (ulBitmapIsEmpty()), then a RTT Texture should be created instead.
+///       This will be used as a backing texture for a new RenderBuffer.
+///
+/// @warning A deep copy of the bitmap data should be made if you are uploading it to the GPU
+///          asynchronously, it will not persist beyond this call.
+///
+typedef void (*ULGPUDriverCreateTextureCallback)(unsigned int texture_id, ULBitmap bitmap);
+
+///
+/// Callback for users to implement ULGPUDriver::update_texture.
+///
+/// Update an existing non-RTT texture with new bitmap data.
+///
+/// @param texture_id  The texture to update.
+///
+/// @param bitmap      The new bitmap data.
+///
+/// @warning A deep copy of the bitmap data should be made if you are uploading it to the GPU
+///          asynchronously, it will not persist beyond this call.
+///
+typedef void (*ULGPUDriverUpdateTextureCallback)(unsigned int texture_id, ULBitmap bitmap);
+
+///
+/// Callback for users to implement ULGPUDriver::destroy_texture.
+///
+/// Destroy a texture.
+///
+/// @param texture_id  The texture to destroy.
+///
+typedef void (*ULGPUDriverDestroyTextureCallback)(unsigned int texture_id);
+
+///
+/// Callback for users to implement ULGPUDriver::next_render_buffer_id.
+///
+/// Get the next available render buffer ID.
+///
+/// This is used to generate a unique render buffer ID for each render buffer created by the
+/// library. The GPU driver implementation is responsible for mapping these IDs to a native ID.
+///
+/// @note Numbering should start at 1, 0 is reserved for "no render buffer".
+///
+/// @return Returns the next available render buffer ID.
+///
+typedef unsigned int (*ULGPUDriverNextRenderBufferIdCallback)();
+
+///
+/// Callback for users to implement ULGPUDriver::create_render_buffer.
+///
+/// Create a render buffer with certain ID and buffer description.
+///
+/// @param render_buffer_id  The render buffer ID to use for the new render buffer.
+///
+/// @param buffer           The render buffer description.
+///
+typedef void (*ULGPUDriverCreateRenderBufferCallback)(unsigned int render_buffer_id,
+                                                      ULRenderBuffer buffer);
+
+///
+/// Callback for users to implement ULGPUDriver::destroy_render_buffer.
+///
+/// Destroy a render buffer.
+///
+/// @param render_buffer_id  The render buffer to destroy.
+///
+typedef void (*ULGPUDriverDestroyRenderBufferCallback)(unsigned int render_buffer_id);
+
+///
+/// Callback for users to implement ULGPUDriver::next_geometry_id.
+///
+/// Get the next available geometry ID.
+///
+/// This is used to generate a unique geometry ID for each geometry created by the library. The
+/// GPU driver implementation is responsible for mapping these IDs to a native ID.
+///
+/// @note Numbering should start at 1, 0 is reserved for "no geometry".
+///
+/// @return Returns the next available geometry ID.
+///
+typedef unsigned int (*ULGPUDriverNextGeometryIdCallback)();
+
+///
+/// Callback for users to implement ULGPUDriver::create_geometry.
+///
+/// Create geometry with certain ID and vertex/index data.
+///
+/// @param geometry_id  The geometry ID to use for the new geometry.
+///
+/// @param vertices     The vertex buffer data.
+///
+/// @param indices      The index buffer data.
+///
+/// @warning A deep copy of the vertex/index data should be made if you are uploading it to the
+///          GPU asynchronously, it will not persist beyond this call.
+///
+typedef void (*ULGPUDriverCreateGeometryCallback)(unsigned int geometry_id, ULVertexBuffer vertices,
+                                                  ULIndexBuffer indices);
+
+///
+/// Callback for users to implement ULGPUDriver::update_geometry.
+///
+/// Update existing geometry with new vertex/index data.
+///
+/// @param geometry_id  The geometry to update.
+///
+/// @param vertices     The new vertex buffer data.
+///
+/// @param indices      The new index buffer data.
+///
+/// @warning A deep copy of the vertex/index data should be made if you are uploading it to the
+///          GPU asynchronously, it will not persist beyond this call.
+///
+typedef void (*ULGPUDriverUpdateGeometryCallback)(unsigned int geometry_id, ULVertexBuffer vertices,
+                                                  ULIndexBuffer indices);
+
+///
+/// Callback for users to implement ULGPUDriver::destroy_geometry.
+///
+/// Destroy geometry.
+///
+/// @param geometry_id  The geometry to destroy.
+///
+typedef void (*ULGPUDriverDestroyGeometryCallback)(unsigned int geometry_id);
+
+///
+/// Callback for users to implement ULGPUDriver::update_command_list.
+///
+/// Update the pending command list with commands to execute on the GPU.
+///
+/// Commands are dispatched to the GPU driver asynchronously via this method. The GPU driver
+/// implementation should consume these commands and execute them at an appropriate time.
+///
+/// @param list  The list of commands to execute.
+///
+/// @warning Implementations should make a deep copy of the command list, it will not persist
+///          beyond this call.
+///
+typedef void (*ULGPUDriverUpdateCommandListCallback)(ULCommandList list);
+
+/// 
+/// User-defined GPU driver interface.
+///
+/// You should implement each of these callbacks, then pass an instance of this struct containing
+/// your callbacks to ulPlatformSetGPUDriver().
+///
+typedef struct {
+  ULGPUDriverBeginSynchronizeCallback begin_synchronize;
+  ULGPUDriverEndSynchronizeCallback end_synchronize;
+  ULGPUDriverNextTextureIdCallback next_texture_id;
+  ULGPUDriverCreateTextureCallback create_texture;
+  ULGPUDriverUpdateTextureCallback update_texture;
+  ULGPUDriverDestroyTextureCallback destroy_texture;
+  ULGPUDriverNextRenderBufferIdCallback next_render_buffer_id;
+  ULGPUDriverCreateRenderBufferCallback create_render_buffer;
+  ULGPUDriverDestroyRenderBufferCallback destroy_render_buffer;
+  ULGPUDriverNextGeometryIdCallback next_geometry_id;
+  ULGPUDriverCreateGeometryCallback create_geometry;
+  ULGPUDriverUpdateGeometryCallback update_geometry;
+  ULGPUDriverDestroyGeometryCallback destroy_geometry;
+  ULGPUDriverUpdateCommandListCallback update_command_list;
+} ULGPUDriver;
+
+///
+/// Sets up an orthographic projection matrix with a certain viewport width and height, multiplies
+/// it by 'transform', and returns the result.
+///
+/// This should be used to calculate the model-view projection matrix for the vertex shaders using
+/// the current ULGPUState.
+///
+/// The 'flip_y' can be optionally used to flip the Y coordinate-space. (Usually flip_y == true for
+/// OpenGL)
+///
+ULExport ULMatrix4x4 ulApplyProjection(ULMatrix4x4 transform, float viewport_width,
+                                       float viewport_height, bool flip_y);
+
+#ifdef __cplusplus
+} // extern "C"
+#endif
+
+#endif // ULTRALIGHT_CAPI_GPUDRIVER_H
+
+// clang-format on
@@ -0,0 +1,77 @@
+/**************************************************************************************************
+ *  This file is a part of Ultralight, an ultra-portable web-browser engine.                      *
+ *                                                                                                *
+ *  See <https://ultralig.ht> for licensing and more.                                             *
+ *                                                                                                *
+ *  (C) 2024 Ultralight, Inc.                                                                     *
+ **************************************************************************************************/
+
+///
+/// @file CAPI_GamepadEvent.h
+///
+/// Gamepad event interface.
+///
+/// `#include <Ultralight/CAPI/CAPI_GamepadEvent.h>`
+///
+/// This file defines the C API for gamepad events.
+///
+/// @see ulFireGamepadEvent
+///
+#ifndef ULTRALIGHT_CAPI_GAMEPADEVENT_H
+#define ULTRALIGHT_CAPI_GAMEPADEVENT_H
+
+#include <Ultralight/CAPI/CAPI_Defines.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/******************************************************************************
+ * Gamepad Event
+ *****************************************************************************/
+
+///
+/// Create a gamepad event, see GamepadEvent for help using this function.
+///
+ULExport ULGamepadEvent ulCreateGamepadEvent(unsigned int index, ULGamepadEventType type);
+
+///
+/// Destroy a gamepad event.
+///
+ULExport void ulDestroyGamepadEvent(ULGamepadEvent evt);
+
+/******************************************************************************
+ * Gamepad Axis Event
+ *****************************************************************************/
+
+///
+/// Create a gamepad axis event, see GamepadAxisEvent for help using this function.
+///
+ULExport ULGamepadAxisEvent ulCreateGamepadAxisEvent(unsigned int index, unsigned int axis_index,
+                                                     double value);
+
+///
+/// Destroy a gamepad axis event.
+///
+ULExport void ulDestroyGamepadAxisEvent(ULGamepadAxisEvent evt);
+
+/******************************************************************************
+ * Gamepad Button Event
+ *****************************************************************************/
+
+///
+/// Create a gamepad button event, see GamepadButtonEvent for help using this function.
+///
+ULExport ULGamepadButtonEvent ulCreateGamepadButtonEvent(unsigned int index,
+                                                         unsigned int button_index, double value);
+
+///
+/// Destroy a gamepad button event.
+///
+ULExport void ulDestroyGamepadButtonEvent(ULGamepadButtonEvent evt);
+
+#ifdef __cplusplus
+} // extern "C"
+#endif
+
+#endif // ULTRALIGHT_CAPI_GAMEPADEVENT_H
@@ -0,0 +1,59 @@
+/**************************************************************************************************
+ *  This file is a part of Ultralight, an ultra-portable web-browser engine.                      *
+ *                                                                                                *
+ *  See <https://ultralig.ht> for licensing and more.                                             *
+ *                                                                                                *
+ *  (C) 2024 Ultralight, Inc.                                                                     *
+ **************************************************************************************************/
+
+///
+/// @file CAPI_Geometry.h
+///
+/// Geometry utilities.
+///
+/// `#include <Ultralight/CAPI/CAPI_Geometry.h>`
+///
+/// This file defines the C API for various geometry utilities.
+///
+#ifndef ULTRALIGHT_CAPI_GEOMETRY_H
+#define ULTRALIGHT_CAPI_GEOMETRY_H
+
+#include <Ultralight/CAPI/CAPI_Defines.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/******************************************************************************
+ * Rect
+ *****************************************************************************/
+
+///
+/// Whether or not a ULRect is empty (all members equal to 0)
+///
+ULExport bool ulRectIsEmpty(ULRect rect);
+
+///
+/// Create an empty ULRect (all members equal to 0)
+///
+ULExport ULRect ulRectMakeEmpty();
+
+/******************************************************************************
+ * IntRect
+ *****************************************************************************/
+
+///
+/// Whether or not a ULIntRect is empty (all members equal to 0)
+///
+ULExport bool ulIntRectIsEmpty(ULIntRect rect);
+
+///
+/// Create an empty ULIntRect (all members equal to 0)
+///
+ULExport ULIntRect ulIntRectMakeEmpty();
+
+#ifdef __cplusplus
+} // extern "C"
+#endif
+
+#endif // ULTRALIGHT_CAPI_GEOMETRY_H
@@ -0,0 +1,147 @@
+/**************************************************************************************************
+ *  This file is a part of Ultralight, an ultra-portable web-browser engine.                      *
+ *                                                                                                *
+ *  See <https://ultralig.ht> for licensing and more.                                             *
+ *                                                                                                *
+ *  (C) 2024 Ultralight, Inc.                                                                     *
+ **************************************************************************************************/
+
+///
+/// @file CAPI_ImageSource.h
+///
+/// User-defined image source to display custom images on a web-page.
+///
+/// `#include <Ultralight/CAPI/CAPI_ImageSource.h>`
+///
+/// This API allows you to composite your own images into a web-page. This is useful for displaying
+/// in-game textures, external image assets, or other custom content.
+///
+/// ## ImageSource File Format
+///
+/// To use an ImageSource, you must first create an `.imgsrc` file containing a string identifying
+/// the image source. This string will be used to lookup the ImageSource from ImageSourceProvider
+/// when it is loaded on a web-page.
+///
+/// The file format is as follows:
+///
+/// ```
+/// IMGSRC-V1
+/// <identifier>
+/// ```
+///
+/// You can use the `.imgsrc` file anywhere in your web-page that typically accepts an image URL.
+/// For example:
+///
+/// ```html
+/// <img src="my_custom_image.imgsrc" />
+/// ```
+///
+/// ## Creating from a GPU Texture
+///
+/// To composite your own GPU texture on a web-page, you should first reserve a texture ID from
+/// ULGPUDriver::next_texture_id and then create an ImageSource from that texture ID. Next, you
+/// should register the ImageSource with ImageSourceProvider using the identifier from the `.imgsrc`
+/// file.
+///
+/// When the image element is drawn on the web-page, the library will draw geometry using the
+/// specified texture ID and UV coordinates. You should bind your own texture when the specified
+/// texture ID is used.
+///
+/// If the GPU renderer is not enabled for the View or pixel data is needed for other purposes, the
+/// library will sample the backing bitmap instead.
+///
+/// ## Creating from a Bitmap
+///
+/// To composite your own bitmap on a web-page, you should create an ImageSource from a Bitmap.
+/// Next, you should register the ImageSource with ImageSourceProvider using the identifier from
+/// the `.imgsrc` file.
+///
+/// When the image element is drawn on the web-page, the library will sample this bitmap directly.
+///
+/// ## Invalidating Images
+///
+/// If you modify the texture or bitmap after creating the ImageSource, you should call
+/// ulImageSourceInvalidate() to notify the library that the image should be redrawn.
+///
+#ifndef ULTRALIGHT_CAPI_IMAGESOURCE_H
+#define ULTRALIGHT_CAPI_IMAGESOURCE_H
+
+#include <Ultralight/CAPI/CAPI_Defines.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/******************************************************************************
+ * ImageSource
+ *****************************************************************************/
+
+///
+/// Create an image source from a GPU texture with optional backing bitmap.
+///
+/// @param  width  The width of the image in pixels (used for layout).
+///
+/// @param  height  The height of the image in pixels (used for layout).
+///
+/// @param  texture_id  The GPU texture identifier to bind when drawing the quad for this image.
+///                     This should be non-zero and obtained from ULGPUDriver::next_texture_id.
+///
+/// @param  texture_uv  The UV coordinates of the texture.
+///
+/// @param  bitmap  Optional backing bitmap for this image source. This is used when drawing
+///                 the image using the CPU renderer or when pixel data is needed for other
+///                 purposes. You should update this bitmap when the texture changes.
+///
+/// @return  A new image source instance.
+///
+ULExport ULImageSource ulCreateImageSourceFromTexture(unsigned int width, unsigned int height,
+                                                      unsigned int texture_id, ULRect texture_uv,
+                                                      ULBitmap bitmap);
+
+///
+/// Create an image source from a bitmap.
+///
+/// @param  bitmap  The backing bitmap for this image source.
+///
+/// @return  A new image source instance.
+///
+ULExport ULImageSource ulCreateImageSourceFromBitmap(ULBitmap bitmap);
+
+///
+/// Destroy an image source.
+///
+/// @param  image_source  The image source to destroy.
+///
+ULExport void ulDestroyImageSource(ULImageSource image_source);
+
+///
+/// Invalidate the image source, notifying the library that the image has changed
+/// and should be redrawn.
+///
+ULExport void ulImageSourceInvalidate(ULImageSource image_source);
+
+/******************************************************************************
+ * ImageSourceProvider
+ *****************************************************************************/
+
+///
+/// Add an image source to the provider.
+///
+/// @param  id  The identifier of the image source.
+///
+/// @param  image_source  The image source to add.
+///
+ULExport void ulImageSourceProviderAddImageSource(ULString id, ULImageSource image_source);
+
+///
+/// Remove an image source from the provider.
+///
+/// @param  id  The identifier of the image source.
+///
+ULExport void ulImageSourceProviderRemoveImageSource(ULString id);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif // ULTRALIGHT_CAPI_IMAGESOURCE_H
@@ -0,0 +1,63 @@
+/**************************************************************************************************
+ *  This file is a part of Ultralight, an ultra-portable web-browser engine.                      *
+ *                                                                                                *
+ *  See <https://ultralig.ht> for licensing and more.                                             *
+ *                                                                                                *
+ *  (C) 2024 Ultralight, Inc.                                                                     *
+ **************************************************************************************************/
+
+///
+/// @file CAPI_KeyEvent.h
+///
+/// Key event interface.
+///
+/// `#include <Ultralight/CAPI/CAPI_KeyEvent.h>`
+///
+/// This file defines the C API for various key events.
+///
+#ifndef ULTRALIGHT_CAPI_KEYEVENT_H
+#define ULTRALIGHT_CAPI_KEYEVENT_H
+
+#include <Ultralight/CAPI/CAPI_Defines.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/******************************************************************************
+ * Key Event
+ ******************************************************************************/
+
+///
+/// Create a key event, see KeyEvent in the C++ API for help with the parameters.
+///
+ULExport ULKeyEvent ulCreateKeyEvent(ULKeyEventType type, unsigned int modifiers,
+                                     int virtual_key_code, int native_key_code, ULString text,
+                                     ULString unmodified_text, bool is_keypad, bool is_auto_repeat,
+                                     bool is_system_key);
+
+#ifdef _WIN32
+///
+/// Create a key event from native Windows event.
+///
+ULExport ULKeyEvent ulCreateKeyEventWindows(ULKeyEventType type, uintptr_t wparam, intptr_t lparam,
+                                            bool is_system_key);
+#endif
+
+#ifdef __OBJC__
+///
+/// Create a key event from native macOS event.
+///
+ULExport ULKeyEvent ulCreateKeyEventMacOS(NSEvent* evt);
+#endif
+
+///
+/// Destroy a key event.
+///
+ULExport void ulDestroyKeyEvent(ULKeyEvent evt);
+
+#ifdef __cplusplus
+} // extern "C"
+#endif
+
+#endif // ULTRALIGHT_CAPI_KEYEVENT_H
@@ -0,0 +1,50 @@
+/**************************************************************************************************
+ *  This file is a part of Ultralight, an ultra-portable web-browser engine.                      *
+ *                                                                                                *
+ *  See <https://ultralig.ht> for licensing and more.                                             *
+ *                                                                                                *
+ *  (C) 2024 Ultralight, Inc.                                                                     *
+ **************************************************************************************************/
+
+///
+/// @file CAPI_Logger.h
+///
+/// User-defined logging interface.
+///
+/// `#include <Ultralight/CAPI/CAPI_Logger.h>`
+///   
+/// The library uses this to display log messages for debugging during development.
+///
+/// This is intended to be implemented by users and defined before creating the Renderer. 
+/// 
+/// @see ulPlatformSetLogger()
+///
+#ifndef ULTRALIGHT_CAPI_LOGGER_H
+#define ULTRALIGHT_CAPI_LOGGER_H
+
+#include <Ultralight/CAPI/CAPI_Defines.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/******************************************************************************
+ * Logger
+ *****************************************************************************/
+
+typedef enum { kLogLevel_Error = 0, kLogLevel_Warning, kLogLevel_Info } ULLogLevel;
+
+///
+/// The callback invoked when the library wants to print a message to the log.
+///
+typedef void (*ULLoggerLogMessageCallback)(ULLogLevel log_level, ULString message);
+
+typedef struct {
+  ULLoggerLogMessageCallback log_message;
+} ULLogger;
+
+#ifdef __cplusplus
+} // extern "C"
+#endif
+
+#endif // ULTRALIGHT_CAPI_LOGGER_H
@@ -0,0 +1,45 @@
+/**************************************************************************************************
+ *  This file is a part of Ultralight, an ultra-portable web-browser engine.                      *
+ *                                                                                                *
+ *  See <https://ultralig.ht> for licensing and more.                                             *
+ *                                                                                                *
+ *  (C) 2024 Ultralight, Inc.                                                                     *
+ **************************************************************************************************/
+
+///
+/// @file CAPI_MouseEvent.h
+///
+/// Mouse event interface.
+///
+/// `#include <Ultralight/CAPI/CAPI_MouseEvent.h>`
+///
+/// This file defines the C API for mouse events.
+///
+#ifndef ULTRALIGHT_CAPI_MOUSEEVENT_H
+#define ULTRALIGHT_CAPI_MOUSEEVENT_H
+
+#include <Ultralight/CAPI/CAPI_Defines.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/******************************************************************************
+ * Mouse Event
+ *****************************************************************************/
+
+///
+/// Create a mouse event, see MouseEvent in the C++ API for help using this function.
+///
+ULExport ULMouseEvent ulCreateMouseEvent(ULMouseEventType type, int x, int y, ULMouseButton button);
+
+///
+/// Destroy a mouse event.
+///
+ULExport void ulDestroyMouseEvent(ULMouseEvent evt);
+
+#ifdef __cplusplus
+} // extern "C"
+#endif
+
+#endif // ULTRALIGHT_CAPI_MOUSEEVENT_H
@@ -0,0 +1,168 @@
+/**************************************************************************************************
+ *  This file is a part of Ultralight, an ultra-portable web-browser engine.                      *
+ *                                                                                                *
+ *  See <https://ultralig.ht> for licensing and more.                                             *
+ *                                                                                                *
+ *  (C) 2024 Ultralight, Inc.                                                                     *
+ **************************************************************************************************/
+
+///
+/// @file CAPI_Platform.h
+/// 
+/// Global platform singleton, manages user-defined platform handlers..
+///
+/// `#include <Ultralight/CAPI/CAPI_Platform.h>`
+///
+/// The library uses the Platform API for most platform-specific operations (eg, file access,
+/// clipboard, font loading, GPU access, pixel buffer transport, etc.).
+///
+/// ## Motivation
+///
+/// Ultralight is designed to work in as many platforms and environments as possible. To achieve
+/// this, we've factored out most platform-specific code into a set of interfaces that you can
+/// implement and set on the Platform singleton.
+///
+/// ## Default Implementations
+///
+/// We provide a number of default implementations for desktop platforms (eg, Windows, macOS, Linux)
+/// for you when you call ulCreateApp(). These implementations are defined in the 
+/// [AppCore repository](https://github.com/ultralight-ux/AppCore/tree/master/src), we recommend
+/// using their source code as a starting point for your own implementations.
+///
+/// ## Required Handlers
+///
+/// When using ulCreateRenderer() directly, you'll need to provide your own implementations for
+/// ULFileSystem and ULFontLoader at a minimum.
+/// 
+/// @par Overview of which platform handlers are required / optional / provided:
+/// 
+/// |                     | ulCreateRenderer() | ulCreateApp() |
+/// |---------------------|--------------------|---------------|
+/// | ULFileSystem        | **Required**       | *Provided*    |
+/// | ULFontLoader        | **Required**       | *Provided*    |
+/// | ULClipboard         |  *Optional*        | *Provided*    |
+/// | ULGPUDriver         |  *Optional*        | *Provided*    |
+/// | ULLogger            |  *Optional*        | *Provided*    |
+/// | ULSurfaceDefinition |  *Provided*        | *Provided*    |
+/// 
+/// @note  This singleton should be set up before creating the Renderer or App.
+///
+#ifndef ULTRALIGHT_CAPI_PLATFORM_H
+#define ULTRALIGHT_CAPI_PLATFORM_H
+
+#include <Ultralight/CAPI/CAPI_Defines.h>
+#include <Ultralight/CAPI/CAPI_Logger.h>
+#include <Ultralight/CAPI/CAPI_FileSystem.h>
+#include <Ultralight/CAPI/CAPI_FontLoader.h>
+#include <Ultralight/CAPI/CAPI_Surface.h>
+#include <Ultralight/CAPI/CAPI_GPUDriver.h>
+#include <Ultralight/CAPI/CAPI_Clipboard.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/******************************************************************************
+ * Platform
+ *****************************************************************************/
+
+///
+/// Set a custom Logger implementation.
+///
+/// This is used to log debug messages to the console or to a log file.
+///
+/// You should call this before ulCreateRenderer() or ulCreateApp().
+///
+/// @note  ulCreateApp() will use the default logger if you never call this.
+///
+/// @note  If you're not using ulCreateApp(), (eg, using ulCreateRenderer()) you can still use the
+///        default logger by calling ulEnableDefaultLogger() (@see <AppCore/CAPI.h>)
+///
+ULExport void ulPlatformSetLogger(ULLogger logger);
+
+///
+/// Set a custom FileSystem implementation.
+///
+/// The library uses this to load all file URLs (eg, <file:///page.html>).
+///
+/// You can provide the library with your own FileSystem implementation so that file assets are
+/// loaded from your own pipeline.
+///
+/// You should call this before ulCreateRenderer() or ulCreateApp().
+/// 
+/// @warning This is required to be defined before calling ulCreateRenderer()
+///
+/// @note  ulCreateApp() will use the default platform file system if you never call this.
+///
+/// @note  If you're not using ulCreateApp(), (eg, using ulCreateRenderer()) you can still use the
+///        default platform file system by calling ulEnablePlatformFileSystem()'
+///        (@see <AppCore/CAPI.h>)
+///
+ULExport void ulPlatformSetFileSystem(ULFileSystem file_system);
+
+///
+/// Set a custom FontLoader implementation.
+/// 
+/// The library uses this to load all system fonts.
+///
+/// Every operating system has its own library of installed system fonts. The FontLoader interface
+/// is used to lookup these fonts and fetch the actual font data (raw TTF/OTF file data) for a given
+/// given font description.
+/// 
+/// You should call this before ulCreateRenderer() or ulCreateApp().
+/// 
+/// @warning This is required to be defined before calling ulCreateRenderer()
+/// 
+/// @note  ulCreateApp() will use the default platform font loader if you never call this.
+///
+/// @note  If you're not using ulCreateApp(), (eg, using ulCreateRenderer()) you can still use the
+///        default platform font loader by calling ulEnablePlatformFontLoader()'
+///        (@see <AppCore/CAPI.h>)
+///
+ULExport void ulPlatformSetFontLoader(ULFontLoader font_loader);
+
+///
+/// Set a custom Surface implementation.
+///
+/// This can be used to wrap a platform-specific GPU texture, Windows DIB, macOS CGImage, or any
+/// other pixel buffer target for display on screen.
+///
+/// By default, the library uses a bitmap surface for all surfaces but you can override this by
+/// providing your own surface definition here.
+///
+/// You should call this before ulCreateRenderer() or ulCreateApp().
+///
+ULExport void ulPlatformSetSurfaceDefinition(ULSurfaceDefinition surface_definition);
+
+///
+/// Set a custom GPUDriver implementation.
+///
+/// This should be used if you have enabled the GPU renderer in the Config and are using
+/// ulCreateRenderer() (which does not provide its own GPUDriver implementation).
+///
+/// The GPUDriver interface is used by the library to dispatch GPU calls to your native GPU context
+/// (eg, D3D11, Metal, OpenGL, Vulkan, etc.) There are reference implementations for this interface
+/// in the AppCore repo.
+///
+/// You should call this before ulCreateRenderer().
+///
+ULExport void ulPlatformSetGPUDriver(ULGPUDriver gpu_driver);
+
+///
+/// Set a custom Clipboard implementation.
+///
+/// This should be used if you are using ulCreateRenderer() (which does not provide its own
+/// clipboard implementation).
+///
+/// The Clipboard interface is used by the library to make calls to the system's native clipboard
+/// (eg, cut, copy, paste).
+///
+/// You should call this before ulCreateRenderer().
+///
+ULExport void ulPlatformSetClipboard(ULClipboard clipboard);
+
+#ifdef __cplusplus
+} // extern "C"
+#endif
+
+#endif // ULTRALIGHT_CAPI_PLATFORM_H
@@ -0,0 +1,278 @@
+/**************************************************************************************************
+ *  This file is a part of Ultralight, an ultra-portable web-browser engine.                      *
+ *                                                                                                *
+ *  See <https://ultralig.ht> for licensing and more.                                             *
+ *                                                                                                *
+ *  (C) 2024 Ultralight, Inc.                                                                     *
+ **************************************************************************************************/
+
+///
+/// @file CAPI_Renderer.h
+///
+/// Core renderer singleton for the library, coordinates all library functions.
+///
+/// `#include <Ultralight/CAPI/CAPI_Renderer.h>`
+/// 
+/// The Renderer class is responsible for creating and painting Views, managing Sessions, as well
+/// as coordinating network requests, events, JavaScript execution, and more.
+/// 
+/// ## Creating the Renderer
+///
+/// @note A Renderer will be created for you automatically when you call ulCreateApp (access it
+///       via ulAppGetRenderer()).
+///
+/// @note ulCreateApp() is part of the AppCore API and automatically manages window creation, run
+///       loop, input, painting, and most platform-specific functionality. (Available on desktop
+///       platforms only)
+/// \endparblock
+///
+/// ### Defining Platform Handlers
+///
+/// Before creating the Renderer, you should define your platform handlers via the Platform
+/// singleton (see CAPI_Platform.h). This can be used to customize file loading, font loading,
+/// clipboard access, and other functionality typically provided by the OS.
+///
+/// Default implementations for most platform handlers are available in the 
+/// [AppCore repo](https://github.com/ultralight-ux/AppCore/tree/master/src). You can use these
+/// stock implementations by copying the code into your project, or you can write your own.
+///
+/// At a minimum, you should provide a ULFileSystem and ULFontLoader otherwise Renderer creation will
+/// fail.
+/// 
+/// ### Creating the Renderer
+///
+/// Once you've set up the Platform handlers you can create the Renderer by calling
+/// `ulCreateRenderer()`.
+///
+/// @par Example creation code
+/// ```
+///  // Setup our config.
+///  ULConfig config = ulCreateConfig();
+///
+///  // Use AppCore's font loader.
+///  ulEnablePlatformFontLoader();
+///
+///  // Use AppCore's file system to load file:/// URLs from the OS.
+///  ULString base_dir = ulCreateString("./assets/");
+///  ulEnablePlatformFileSystem(base_dir);
+///  ulDestroyString(base_dir);
+///
+///  // Create the renderer.
+///  ULRenderer renderer = ulCreateRenderer(config);
+///
+///  // Destroy the config.
+///  ulDestroyConfig(config);
+///
+///  // Set up Views here...
+/// ```
+/// 
+/// ## Updating Renderer Logic
+/// 
+/// You should call ulUpdate() from your main update loop as often as possible to give the
+/// library an opportunity to dispatch events and timers:
+/// 
+/// @par Example update code
+/// ```
+/// void mainLoop()
+/// {
+///   while(true)
+///   {  
+///     // Update program logic here
+///     ulUpdate(renderer);
+///   }
+/// }
+/// ```
+/// 
+/// ## Rendering Each Frame
+/// 
+/// When your program is ready to display a new frame (usually in synchrony with the monitor
+/// refresh rate), you should call `ulRefreshDisplay()` and `ulRender` so the
+/// library can render all active Views as needed.
+/// 
+/// @par Example per-frame render code
+/// ```
+/// void displayFrame()
+/// {
+///     // Notify the renderer that the main display has refreshed. This will update animations,
+///     // smooth scroll, and window.requestAnimationFrame() for all Views matching the display id.
+///     ulRefreshDisplay(renderer, 0);
+///
+///     // Render all Views as needed
+///     ulRender(renderer);
+/// 
+///     // Each View will render to a
+///     //   - Pixel-Buffer Surface (ulViewGetSurface())
+///     //     or
+///     //   - GPU texture (ulViewGetRenderTarget())
+///     // based on whether CPU or GPU rendering is used.
+///     //
+///     // You will need to display the image data here as needed.
+///   }
+/// }
+/// ```
+/// 
+#ifndef ULTRALIGHT_CAPI_RENDERER_H
+#define ULTRALIGHT_CAPI_RENDERER_H
+
+#include <Ultralight/CAPI/CAPI_Defines.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+///
+/// Create the core renderer singleton for the library.
+///
+/// You should set up the Platform singleton (see CAPI_Platform.h) before calling this function.
+/// 
+/// @note You do not need to the call this if you're using ulCreateApp() from AppCore.
+///
+/// \parblock
+/// @warning You'll need to define a ULFontLoader and ULFileSystem within the Platform singleton
+///         or else this call will fail.
+/// \endparblock
+/// 
+/// \parblock
+/// @warning You should only create one Renderer during the lifetime of your program.
+/// \endparblock
+///
+/// @param  config  The configuration to use for the renderer.
+///
+/// @return  Returns the new renderer instance.
+///
+ULExport ULRenderer ulCreateRenderer(ULConfig config);
+
+///
+/// Destroy the renderer.
+///
+/// @param renderer  The renderer instance to destroy.
+///
+ULExport void ulDestroyRenderer(ULRenderer renderer);
+
+///
+/// Update timers and dispatch internal callbacks (JavaScript and network).
+///
+/// @param  renderer  The active renderer instance.
+///
+ULExport void ulUpdate(ULRenderer renderer);
+
+///
+/// Notify the renderer that a display has refreshed (you should call this after vsync).
+///
+/// This updates animations, smooth scroll, and window.requestAnimationFrame() for all Views
+/// matching the display id.
+///
+/// @param  renderer  The active renderer instance.
+///
+/// @param  display_id  The display ID to refresh (0 by default).
+///
+ULExport void ulRefreshDisplay(ULRenderer renderer, unsigned int display_id);
+
+///
+/// Render all active Views to their respective surfaces and render targets.
+///
+/// @param  renderer  The active renderer instance.
+///
+ULExport void ulRender(ULRenderer renderer);
+
+///
+/// Attempt to release as much memory as possible. Don't call this from any callbacks or driver
+/// code.
+///
+/// @param  renderer  The active renderer instance.
+///
+ULExport void ulPurgeMemory(ULRenderer renderer);
+
+///
+/// Print detailed memory usage statistics to the log. (@see ulPlatformSetLogger)
+///
+/// @param  renderer  The active renderer instance.
+///
+ULExport void ulLogMemoryUsage(ULRenderer renderer);
+
+///
+/// Start the remote inspector server.
+///
+/// While the remote inspector is active, Views that are loaded into this renderer
+/// will be able to be remotely inspected from another Ultralight instance either locally
+/// (another app on same machine) or remotely (over the network) by navigating a View to:
+///
+/// \code
+///   inspector://<ADDRESS>:<PORT>
+/// \endcode
+///
+/// @param renderer  The active renderer instance.
+///
+/// @param address   The address for the server to listen on (eg, "127.0.0.1")
+///
+/// @param port      The port for the server to listen on (eg, 9222)
+///
+/// @return  Returns whether the server started successfully or not.
+///
+ULExport bool ulStartRemoteInspectorServer(ULRenderer renderer, const char* address,
+                                           unsigned short port);
+
+///
+/// Describe the details of a gamepad, to be used with ulFireGamepadEvent and related
+/// events below. This can be called multiple times with the same index if the details change.
+/// 
+/// @param  renderer  The active renderer instance.
+///
+/// @param  index   The unique index (or "connection slot") of the gamepad. For example,
+///                 controller #1 would be "1", controller #2 would be "2" and so on.
+///
+/// @param  id      A string ID representing the device, this will be made available
+///                 in JavaScript as gamepad.id
+///
+/// @param  axis_count  The number of axes on the device.
+///
+/// @param  button_count  The number of buttons on the device.
+///
+ULExport void ulSetGamepadDetails(ULRenderer renderer, unsigned int index, ULString id,
+                                  unsigned int axis_count, unsigned int button_count);
+
+///
+/// Fire a gamepad event (connection / disconnection).
+///
+/// @note  The gamepad should first be described via ulSetGamepadDetails before calling this
+///        function.
+///
+/// @param renderer  The active renderer instance.
+///
+/// @param evt       The event to fire.
+///
+/// @see <https://developer.mozilla.org/en-US/docs/Web/API/Gamepad>
+///
+ULExport void ulFireGamepadEvent(ULRenderer renderer, ULGamepadEvent evt);
+
+///
+/// Fire a gamepad axis event (to be called when an axis value is changed).
+///
+/// @note  The gamepad should be connected via a previous call to ulFireGamepadEvent.
+///
+/// @param renderer  The active renderer instance.
+///
+/// @param evt       The event to fire.
+///
+/// @see <https://developer.mozilla.org/en-US/docs/Web/API/Gamepad/axes>
+///
+ULExport void ulFireGamepadAxisEvent(ULRenderer renderer, ULGamepadAxisEvent evt);
+
+///
+/// Fire a gamepad button event (to be called when a button value is changed).
+///
+/// @note  The gamepad should be connected via a previous call to ulFireGamepadEvent.
+///
+/// @param renderer  The active renderer instance.
+///
+/// @param evt       The event to fire.
+///
+/// @see <https://developer.mozilla.org/en-US/docs/Web/API/Gamepad/buttons>
+///
+ULExport void ulFireGamepadButtonEvent(ULRenderer renderer, ULGamepadButtonEvent evt);
+
+#ifdef __cplusplus
+} // extern "C"
+#endif
+
+#endif // ULTRALIGHT_CAPI_RENDERER_H
@@ -0,0 +1,45 @@
+/**************************************************************************************************
+ *  This file is a part of Ultralight, an ultra-portable web-browser engine.                      *
+ *                                                                                                *
+ *  See <https://ultralig.ht> for licensing and more.                                             *
+ *                                                                                                *
+ *  (C) 2024 Ultralight, Inc.                                                                     *
+ **************************************************************************************************/
+
+///
+/// @file CAPI_ScrollEvent.h
+///
+/// Scroll event interface.
+///
+/// `#include <Ultralight/CAPI/CAPI_ScrollEvent.h>`
+///
+/// This file defines the C API for scroll events.
+///
+#ifndef ULTRALIGHT_CAPI_SCROLLEVENT_H
+#define ULTRALIGHT_CAPI_SCROLLEVENT_H
+
+#include <Ultralight/CAPI/CAPI_Defines.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/******************************************************************************
+ * Scroll Event
+ *****************************************************************************/
+
+///
+/// Create a scroll event, see ScrollEvent in the C++ API for help using this function.
+///
+ULExport ULScrollEvent ulCreateScrollEvent(ULScrollEventType type, int delta_x, int delta_y);
+
+///
+/// Destroy a scroll event.
+///
+ULExport void ulDestroyScrollEvent(ULScrollEvent evt);
+
+#ifdef __cplusplus
+} // extern "C"
+#endif
+
+#endif // ULTRALIGHT_CAPI_SCROLLEVENT_H
@@ -0,0 +1,84 @@
+/**************************************************************************************************
+ *  This file is a part of Ultralight, an ultra-portable web-browser engine.                      *
+ *                                                                                                *
+ *  See <https://ultralig.ht> for licensing and more.                                             *
+ *                                                                                                *
+ *  (C) 2024 Ultralight, Inc.                                                                     *
+ **************************************************************************************************/
+
+///
+/// @file CAPI_Session.h
+///
+/// Storage for a browsing session (cookies, local storage, etc.).
+///
+/// `#include <Ultralight/CAPI/CAPI_Session.h>`
+///
+/// This class stores data for a unique browsing session (cookies, local storage, application cache,
+/// indexed db. etc.). You can create multiple sessions to isolate data between different browsing
+/// contexts.
+///
+/// ## Default Session
+///
+/// The library has a default session named "default" that is used if no session is specified when
+/// when creating a View.
+///
+/// ## Session Lifetime
+///
+/// Sessions can be either temporary (in-memory only) or persistent (backed to disk).
+///
+#ifndef ULTRALIGHT_CAPI_SESSION_H
+#define ULTRALIGHT_CAPI_SESSION_H
+
+#include <Ultralight/CAPI/CAPI_Defines.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/******************************************************************************
+ * Session
+ *****************************************************************************/
+
+///
+/// Create a Session to store local data in (such as cookies, local storage, application cache,
+/// indexed db, etc).
+///
+ULExport ULSession ulCreateSession(ULRenderer renderer, bool is_persistent, ULString name);
+
+///
+/// Destroy a Session.
+///
+ULExport void ulDestroySession(ULSession session);
+
+///
+/// Get the default session (persistent session named "default").
+///
+/// @note  This session is owned by the Renderer, you shouldn't destroy it.
+///
+ULExport ULSession ulDefaultSession(ULRenderer renderer);
+
+///
+/// Whether or not is persistent (backed to disk).
+///
+ULExport bool ulSessionIsPersistent(ULSession session);
+
+///
+/// Unique name identifying the session (used for unique disk path).
+///
+ULExport ULString ulSessionGetName(ULSession session);
+
+///
+/// Unique numeric Id for the session.
+///
+ULExport unsigned long long ulSessionGetId(ULSession session);
+
+///
+/// The disk path to write to (used by persistent sessions only).
+///
+ULExport ULString ulSessionGetDiskPath(ULSession session);
+
+#ifdef __cplusplus
+} // extern "C"
+#endif
+
+#endif // ULTRALIGHT_CAPI_SESSION_H
@@ -0,0 +1,86 @@
+/**************************************************************************************************
+ *  This file is a part of Ultralight, an ultra-portable web-browser engine.                      *
+ *                                                                                                *
+ *  See <https://ultralig.ht> for licensing and more.                                             *
+ *                                                                                                *
+ *  (C) 2024 Ultralight, Inc.                                                                     *
+ **************************************************************************************************/
+
+///
+/// @file CAPI_String.h
+///
+/// Unicode string container (natively UTF-8).
+///
+/// `#include <Ultralight/CAPI/CAPI_String.h>`
+///
+/// This class is used to represent strings in Ultralight. It can be created from a variety of
+/// string types (ASCII, UTF-8, UTF-16) and accessed as a null-terminated UTF-8 buffer.
+///
+#ifndef ULTRALIGHT_CAPI_STRING_H
+#define ULTRALIGHT_CAPI_STRING_H
+
+#include <Ultralight/CAPI/CAPI_Defines.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/******************************************************************************
+ * String
+ *****************************************************************************/
+
+///
+/// Create string from null-terminated ASCII C-string.
+///
+ULExport ULString ulCreateString(const char* str);
+
+///
+/// Create string from UTF-8 buffer.
+///
+ULExport ULString ulCreateStringUTF8(const char* str, size_t len);
+
+///
+/// Create string from UTF-16 buffer.
+///
+ULExport ULString ulCreateStringUTF16(ULChar16* str, size_t len);
+
+///
+/// Create string from copy of existing string.
+///
+ULExport ULString ulCreateStringFromCopy(ULString str);
+
+///
+/// Destroy string (you should destroy any strings you explicitly Create).
+///
+ULExport void ulDestroyString(ULString str);
+
+///
+/// Get native UTF-8 buffer data (always null-terminated).
+///
+ULExport char* ulStringGetData(ULString str);
+
+///
+/// Get length (in bytes) of the UTF-8 buffer data, not including null terminator.
+///
+ULExport size_t ulStringGetLength(ULString str);
+
+///
+/// Whether this string is empty or not.
+///
+ULExport bool ulStringIsEmpty(ULString str);
+
+///
+/// Replaces the contents of 'str' with the contents of 'new_str'
+///
+ULExport void ulStringAssignString(ULString str, ULString new_str);
+
+///
+/// Replaces the contents of 'str' with the contents of a C-string.
+///
+ULExport void ulStringAssignCString(ULString str, const char* c_str);
+
+#ifdef __cplusplus
+} // extern "C"
+#endif
+
+#endif // ULTRALIGHT_CAPI_STRING_H
@@ -0,0 +1,250 @@
+/**************************************************************************************************
+ *  This file is a part of Ultralight, an ultra-portable web-browser engine.                      *
+ *                                                                                                *
+ *  See <https://ultralig.ht> for licensing and more.                                             *
+ *                                                                                                *
+ *  (C) 2024 Ultralight, Inc.                                                                     *
+ **************************************************************************************************/
+
+///
+/// @file CAPI_Surface.h
+///
+/// User-defined pixel buffer surface. 
+///
+/// `#include <Ultralight/CAPI/CAPI_Surface.h>`
+///
+/// The library uses this to store pixel data when rendering Views on the CPU (see
+/// ulViewIsAccelerated()).
+///
+/// You can provide the library with your own Surface implementation to reduce the latency of
+/// displaying pixels in your application (Views will be drawn directly to a block of memory
+/// controlled by you).
+///
+/// When a View is rendered on the CPU, you can retrieve the backing Surface via ulViewGetSurface().
+///
+/// @pre This is automatically managed for you when using ulCreateApp(), if you want to override
+///      ULSurfaceDefinition, you'll need to use ulCreateRenderer() instead.
+///
+/// ## Default Implementation
+///
+/// A default Surface implementation, BitmapSurface, is automatically provided by the library when
+/// you call ulCreateRenderer() without defining a custom ULSurfaceDefinition.
+///
+/// You should cast the ULSurface to a ULBitmapSurface and call ulBitmapSurfaceGetBitmap() to access
+/// the underlying Bitmap.
+///
+/// ## Setting the Surface Implementation
+///
+/// To define your own implementation, you should implement the ULSurfaceDefinition callbacks,
+/// and then pass an instance of ULSurfaceDefinition containing your callbacks to 
+/// ulPlatformSetSurfaceDefinition() before calling ulCreateRenderer().
+///
+#ifndef ULTRALIGHT_CAPI_SURFACE_H
+#define ULTRALIGHT_CAPI_SURFACE_H
+
+#include <Ultralight/CAPI/CAPI_Defines.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/******************************************************************************
+ * Surface
+ *****************************************************************************/
+
+///
+/// Width (in pixels).
+///
+ULExport unsigned int ulSurfaceGetWidth(ULSurface surface);
+
+///
+/// Height (in pixels).
+///
+ULExport unsigned int ulSurfaceGetHeight(ULSurface surface);
+
+///
+/// Number of bytes between rows (usually width * 4)
+///
+ULExport unsigned int ulSurfaceGetRowBytes(ULSurface surface);
+
+///
+/// Size in bytes.
+///
+ULExport size_t ulSurfaceGetSize(ULSurface surface);
+
+///
+/// Lock the pixel buffer and get a pointer to the beginning of the data for reading/writing.
+///
+/// Native pixel format is premultiplied BGRA 32-bit (8 bits per channel).
+///
+ULExport void* ulSurfaceLockPixels(ULSurface surface);
+
+///
+/// Unlock the pixel buffer.
+///
+ULExport void ulSurfaceUnlockPixels(ULSurface surface);
+
+///
+/// Resize the pixel buffer to a certain width and height (both in pixels).
+///
+/// This should never be called while pixels are locked.
+///
+ULExport void ulSurfaceResize(ULSurface surface, unsigned int width, unsigned int height);
+
+///
+/// Set the dirty bounds to a certain value.
+///
+/// This is called after the Renderer paints to an area of the pixel buffer. (The new value will be
+/// joined with the existing dirty_bounds())
+///
+ULExport void ulSurfaceSetDirtyBounds(ULSurface surface, ULIntRect bounds);
+
+///
+/// Get the dirty bounds.
+///
+/// This value can be used to determine which portion of the pixel buffer has been updated since the
+/// last call to ulSurfaceClearDirtyBounds().
+///
+/// The general algorithm to determine if a Surface needs display is:
+/// <pre>
+///   if (!ulIntRectIsEmpty(ulSurfaceGetDirtyBounds(surface))) {
+///       // Surface pixels are dirty and needs display.
+///       // Cast Surface to native Surface and use it here (pseudo code)
+///       DisplaySurface(surface);
+///
+///       // Once you're done, clear the dirty bounds:
+///       ulSurfaceClearDirtyBounds(surface);
+///  }
+///  </pre>
+///
+ULExport ULIntRect ulSurfaceGetDirtyBounds(ULSurface surface);
+
+///
+/// Clear the dirty bounds.
+///
+/// You should call this after you're done displaying the Surface.
+///
+ULExport void ulSurfaceClearDirtyBounds(ULSurface surface);
+
+///
+/// Get the underlying user data pointer (this is only valid if you have set a custom surface
+/// implementation via ulPlatformSetSurfaceDefinition).
+///
+/// This will return nullptr if this surface is the default ULBitmapSurface.
+///
+ULExport void* ulSurfaceGetUserData(ULSurface surface);
+
+/******************************************************************************
+ * BitmapSurface
+ *****************************************************************************/
+
+///
+/// Get the underlying Bitmap from the default Surface.
+///
+/// @note  Do not call ulDestroyBitmap() on the returned value, it is owned by the surface.
+///
+ULExport ULBitmap ulBitmapSurfaceGetBitmap(ULBitmapSurface surface);
+
+/******************************************************************************
+ * Surface Definition
+ *****************************************************************************/
+
+///
+/// The callback invoked when a Surface is created.
+///
+/// @param  width  The width in pixels.
+/// @param  height  The height in pixels.
+///
+/// @return  This callback should return a pointer to user-defined data for the instance. This user
+///          data pointer will be passed to all other callbacks when operating on the instance.
+///
+typedef void* (*ULSurfaceDefinitionCreateCallback)(unsigned int width, unsigned int height);
+
+///
+/// The callback invoked when a Surface is destroyed.
+///
+/// @param  user_data  User data pointer uniquely identifying the surface.
+///
+typedef void (*ULSurfaceDefinitionDestroyCallback)(void* user_data);
+
+///
+/// The callback invoked when a Surface's width (in pixels) is requested.
+///
+/// @param  user_data  User data pointer uniquely identifying the surface.
+///
+typedef unsigned int (*ULSurfaceDefinitionGetWidthCallback)(void* user_data);
+
+///
+/// The callback invoked when a Surface's height (in pixels) is requested.
+///
+/// @param  user_data  User data pointer uniquely identifying the surface.
+///
+typedef unsigned int (*ULSurfaceDefinitionGetHeightCallback)(void* user_data);
+
+///
+/// The callback invoked when a Surface's row bytes is requested.
+///
+/// @note  This value is also known as "stride". Usually width * 4.
+///
+/// @param  user_data  User data pointer uniquely identifying the surface.
+///
+typedef unsigned int (*ULSurfaceDefinitionGetRowBytesCallback)(void* user_data);
+
+///
+/// The callback invoked when a Surface's size (in bytes) is requested.
+///
+/// @param  user_data  User data pointer uniquely identifying the surface.
+///
+typedef size_t (*ULSurfaceDefinitionGetSizeCallback)(void* user_data);
+
+///
+/// The callback invoked when a Surface's pixel buffer is requested to be locked for reading/writing
+/// (should return a pointer to locked bytes).
+///
+/// @param  user_data  User data pointer uniquely identifying the surface.
+///
+typedef void* (*ULSurfaceDefinitionLockPixelsCallback)(void* user_data);
+
+///
+/// The callback invoked when a Surface's pixel buffer is requested to be unlocked after previously
+/// being locked.
+///
+/// @param  user_data  User data pointer uniquely identifying the surface.
+///
+typedef void (*ULSurfaceDefinitionUnlockPixelsCallback)(void* user_data);
+
+///
+/// The callback invoked when a Surface is requested to be resized to a certain width/height.
+///
+/// @param  user_data  User data pointer uniquely identifying the surface.
+///
+/// @param  width      Width in pixels.
+///
+/// @param  height     Height in pixels.
+///
+typedef void (*ULSurfaceDefinitionResizeCallback)(void* user_data, unsigned int width,
+                                                  unsigned int height);
+
+/// 
+/// User-defined surface interface.
+///
+/// You should implement each of these callbacks, then pass an instance of this struct containing
+/// your callbacks to ulPlatformSetSurfaceDefinition().
+///
+typedef struct {
+  ULSurfaceDefinitionCreateCallback create;
+  ULSurfaceDefinitionDestroyCallback destroy;
+  ULSurfaceDefinitionGetWidthCallback get_width;
+  ULSurfaceDefinitionGetHeightCallback get_height;
+  ULSurfaceDefinitionGetRowBytesCallback get_row_bytes;
+  ULSurfaceDefinitionGetSizeCallback get_size;
+  ULSurfaceDefinitionLockPixelsCallback lock_pixels;
+  ULSurfaceDefinitionUnlockPixelsCallback unlock_pixels;
+  ULSurfaceDefinitionResizeCallback resize;
+} ULSurfaceDefinition;
+
+#ifdef __cplusplus
+} // extern "C"
+#endif
+
+#endif // ULTRALIGHT_CAPI_SURFACE_H
@@ -0,0 +1,554 @@
+/**************************************************************************************************
+ *  This file is a part of Ultralight, an ultra-portable web-browser engine.                      *
+ *                                                                                                *
+ *  See <https://ultralig.ht> for licensing and more.                                             *
+ *                                                                                                *
+ *  (C) 2024 Ultralight, Inc.                                                                     *
+ **************************************************************************************************/
+
+///
+/// @file CAPI_View.h
+///
+/// Web-page container rendered to an offscreen surface.
+///
+/// `#include <Ultralight/CAPI/CAPI_View.h>`
+///
+/// The View class is responsible for loading and rendering web-pages to an offscreen surface. It
+/// is completely isolated from the OS windowing system, you must forward all input events to it
+/// from your application.
+///
+/// ## Creating a View
+///
+/// You can create a View by calling ulCreateView():
+///
+/// ```
+/// // Create a ULViewConfig with default values
+/// ULViewConfig view_config = ulCreateViewConfig();
+///
+/// // Create a View, 500 by 500 pixels in size, using the default Session
+/// ULView view = ulCreateView(renderer, 500, 500, view_config, NULL);
+///
+/// // Clean up the ULViewConfig
+/// ulDestroyViewConfig(view_config);
+/// ```
+///
+/// @note When using ulCreateApp(), the library will automatically create a View for you when you
+///       call ulCreateOverlay().
+///
+#ifndef ULTRALIGHT_CAPI_VIEW_H
+#define ULTRALIGHT_CAPI_VIEW_H
+
+#include <Ultralight/CAPI/CAPI_Defines.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/******************************************************************************
+ * ViewConfig
+ *****************************************************************************/
+
+///
+/// Create view configuration with default values (see <Ultralight/platform/View.h>).
+///
+ULExport ULViewConfig ulCreateViewConfig();
+
+///
+/// Destroy view configuration.
+///
+ULExport void ulDestroyViewConfig(ULViewConfig config);
+
+///
+/// Set a user-generated id of the display (monitor, TV, or screen) that the View will be shown on.
+/// 
+/// Animations are driven based on the physical refresh rate of the display. Multiple Views can
+/// share the same display.
+/// 
+/// 
+/// @note This is automatically managed for you when ulCreateApp() is used.
+/// 
+/// @see ulRefreshDisplay()
+/// 
+ULExport void ulViewConfigSetDisplayId(ULViewConfig config, unsigned int display_id);
+
+///
+/// Set whether to render using the GPU renderer (accelerated) or the CPU renderer (unaccelerated).
+///
+/// This option is only valid if you're managing the Renderer yourself (eg, you've previously
+/// called ulCreateRenderer() instead of ulCreateApp()).
+///
+/// When true, the View will be rendered to an offscreen GPU texture using the GPU driver set in
+/// ulPlatformSetGPUDriver(). You can fetch details for the texture via ulViewGetRenderTarget().
+///
+/// When false (the default), the View will be rendered to an offscreen pixel buffer using the
+/// multithreaded CPU renderer. This pixel buffer can optionally be provided by the user--
+/// for more info see ulViewGetSurface().
+///
+ULExport void ulViewConfigSetIsAccelerated(ULViewConfig config, bool is_accelerated);
+
+///
+/// Set whether images should be enabled (Default = True).
+///
+ULExport void ulViewConfigSetIsTransparent(ULViewConfig config, bool is_transparent);
+
+///
+/// Set the initial device scale, ie. the amount to scale page units to screen pixels. This should be
+/// set to the scaling factor of the device that the View is displayed on. (Default = 1.0)
+///
+/// @note 1.0 is equal to 100% zoom (no scaling), 2.0 is equal to 200% zoom (2x scaling)
+///
+ULExport void ulViewConfigSetInitialDeviceScale(ULViewConfig config, double initial_device_scale);
+
+///
+/// Set whether or not the View should initially have input focus. (Default = True)
+///
+ULExport void ulViewConfigSetInitialFocus(ULViewConfig config, bool is_focused);
+
+///
+/// Set whether images should be enabled (Default = True).
+///
+ULExport void ulViewConfigSetEnableImages(ULViewConfig config, bool enabled);
+
+///
+/// Set whether JavaScript should be enabled (Default = True).
+///
+ULExport void ulViewConfigSetEnableJavaScript(ULViewConfig config, bool enabled);
+
+///
+/// Set default font-family to use (Default = Times New Roman).
+///
+ULExport void ulViewConfigSetFontFamilyStandard(ULViewConfig config, ULString font_name);
+
+///
+/// Set default font-family to use for fixed fonts, eg <pre> and <code>
+/// (Default = Courier New).
+///
+ULExport void ulViewConfigSetFontFamilyFixed(ULViewConfig config, ULString font_name);
+
+///
+/// Set default font-family to use for serif fonts (Default = Times New Roman).
+///
+ULExport void ulViewConfigSetFontFamilySerif(ULViewConfig config, ULString font_name);
+
+///
+/// Set default font-family to use for sans-serif fonts (Default = Arial).
+///
+ULExport void ulViewConfigSetFontFamilySansSerif(ULViewConfig config, ULString font_name);
+
+///
+/// Set user agent string (See <Ultralight/platform/Config.h> for the default).
+///
+ULExport void ulViewConfigSetUserAgent(ULViewConfig config, ULString agent_string);
+
+/******************************************************************************
+ * View
+ *****************************************************************************/
+
+///
+/// Create a View with certain size (in pixels).
+///
+/// @note  You can pass null to 'session' to use the default session.
+///
+ULExport ULView ulCreateView(ULRenderer renderer, unsigned int width, unsigned int height,
+                             ULViewConfig view_config, ULSession session);
+
+///
+/// Destroy a View.
+///
+ULExport void ulDestroyView(ULView view);
+
+///
+/// Get current URL.
+///
+/// @note Don't destroy the returned string, it is owned by the View.
+///
+ULExport ULString ulViewGetURL(ULView view);
+
+///
+/// Get current title.
+///
+/// @note Don't destroy the returned string, it is owned by the View.
+///
+ULExport ULString ulViewGetTitle(ULView view);
+
+///
+/// Get the width, in pixels.
+///
+ULExport unsigned int ulViewGetWidth(ULView view);
+
+///
+/// Get the height, in pixels.
+///
+ULExport unsigned int ulViewGetHeight(ULView view);
+
+///
+// Get the display id of the View.
+///
+ULExport unsigned int ulViewGetDisplayId(ULView view);
+
+///
+/// Set the display id of the View.
+/// 
+/// This should be called when the View is moved to another display.
+/// 
+ULExport void ulViewSetDisplayId(ULView view, unsigned int display_id);
+
+///
+/// Get the device scale, ie. the amount to scale page units to screen pixels.
+///
+/// For example, a value of 1.0 is equivalent to 100% zoom. A value of 2.0 is 200% zoom.
+///
+ULExport double ulViewGetDeviceScale(ULView view);
+
+///
+/// Set the device scale.
+///
+ULExport void ulViewSetDeviceScale(ULView view, double scale);
+
+///
+/// Whether or not the View is GPU-accelerated. If this is false, the page will be rendered
+/// via the CPU renderer.
+///
+ULExport bool ulViewIsAccelerated(ULView view);
+
+///
+/// Whether or not the View supports transparent backgrounds.
+///
+ULExport bool ulViewIsTransparent(ULView view);
+
+///
+/// Check if the main frame of the page is currrently loading.
+///
+ULExport bool ulViewIsLoading(ULView view);
+
+///
+/// Get the RenderTarget for the View.
+///
+/// @note  Only valid if this View is GPU accelerated.
+/// 
+///        You can use this with your GPUDriver implementation to bind and display the
+///        corresponding texture in your application.
+///
+ULExport ULRenderTarget ulViewGetRenderTarget(ULView view);
+
+///
+/// Get the Surface for the View (native pixel buffer that the CPU renderer draws into).
+///
+/// @note  This operation is only valid if you're managing the Renderer yourself (eg, you've
+///        previously called ulCreateRenderer() instead of ulCreateApp()).
+///
+///        This function will return NULL if this View is GPU accelerated.
+///
+///        The default Surface is BitmapSurface but you can provide your own Surface implementation
+///        via ulPlatformSetSurfaceDefinition.
+///
+///        When using the default Surface, you can retrieve the underlying bitmap by casting
+///        ULSurface to ULBitmapSurface and calling ulBitmapSurfaceGetBitmap().
+///
+ULExport ULSurface ulViewGetSurface(ULView view);
+
+///
+/// Load a raw string of HTML.
+///
+ULExport void ulViewLoadHTML(ULView view, ULString html_string);
+
+///
+/// Load a URL into main frame.
+///
+ULExport void ulViewLoadURL(ULView view, ULString url_string);
+
+///
+/// Resize view to a certain width and height (in pixels).
+///
+ULExport void ulViewResize(ULView view, unsigned int width, unsigned int height);
+
+///
+/// Acquire the page's JSContext for use with JavaScriptCore API.
+///
+/// @note  This call locks the context for the current thread. You should call
+///        ulViewUnlockJSContext() after using the context so other worker threads can modify
+///        JavaScript state.
+///
+/// @note  The lock is recusive, it's okay to call this multiple times as long as you call
+///        ulViewUnlockJSContext() the same number of times.
+///
+ULExport JSContextRef ulViewLockJSContext(ULView view);
+
+///
+/// Unlock the page's JSContext after a previous call to ulViewLockJSContext().
+///
+ULExport void ulViewUnlockJSContext(ULView view);
+
+///
+/// Evaluate a string of JavaScript and return result.
+///
+/// @param  js_string  The string of JavaScript to evaluate.
+///
+/// @param  exception  The address of a ULString to store a description of the last exception. Pass
+///                    NULL to ignore this. Don't destroy the exception string returned, it's owned
+///                    by the View.
+///
+/// @note Don't destroy the returned string, it's owned by the View. This value is reset with every
+///       call-- if you want to retain it you should copy the result to a new string via
+///       ulCreateStringFromCopy().
+///
+/// @note An example of using this API:
+///       <pre>
+///         ULString script = ulCreateString("1 + 1");
+///         ULString exception;
+///         ULString result = ulViewEvaluateScript(view, script, &exception);
+///         /* Use the result ("2") and exception description (if any) here. */
+///         ulDestroyString(script);
+///       </pre>
+///
+ULExport ULString ulViewEvaluateScript(ULView view, ULString js_string, ULString* exception);
+
+///
+/// Check if can navigate backwards in history.
+///
+ULExport bool ulViewCanGoBack(ULView view);
+
+///
+/// Check if can navigate forwards in history.
+///
+ULExport bool ulViewCanGoForward(ULView view);
+
+///
+/// Navigate backwards in history.
+///
+ULExport void ulViewGoBack(ULView view);
+
+///
+/// Navigate forwards in history.
+///
+ULExport void ulViewGoForward(ULView view);
+
+///
+/// Navigate to arbitrary offset in history.
+///
+ULExport void ulViewGoToHistoryOffset(ULView view, int offset);
+
+///
+/// Reload current page.
+///
+ULExport void ulViewReload(ULView view);
+
+///
+/// Stop all page loads.
+///
+ULExport void ulViewStop(ULView view);
+
+///
+/// Give focus to the View.
+///
+/// You should call this to give visual indication that the View has input focus (changes active
+/// text selection colors, for example).
+///
+ULExport void ulViewFocus(ULView view);
+
+///
+/// Remove focus from the View and unfocus any focused input elements.
+///
+/// You should call this to give visual indication that the View has lost input focus.
+///
+ULExport void ulViewUnfocus(ULView view);
+
+///
+/// Whether or not the View has focus.
+///
+ULExport bool ulViewHasFocus(ULView view);
+
+///
+/// Whether or not the View has an input element with visible keyboard focus (indicated by a
+/// blinking caret).
+///
+/// You can use this to decide whether or not the View should consume keyboard input events (useful
+/// in games with mixed UI and key handling).
+///
+ULExport bool ulViewHasInputFocus(ULView view);
+
+///
+/// Fire a keyboard event.
+///
+ULExport void ulViewFireKeyEvent(ULView view, ULKeyEvent key_event);
+
+///
+/// Fire a mouse event.
+///
+ULExport void ulViewFireMouseEvent(ULView view, ULMouseEvent mouse_event);
+
+///
+/// Fire a scroll event.
+///
+ULExport void ulViewFireScrollEvent(ULView view, ULScrollEvent scroll_event);
+
+typedef void (*ULChangeTitleCallback)(void* user_data, ULView caller, ULString title);
+
+///
+/// Set callback for when the page title changes.
+///
+ULExport void ulViewSetChangeTitleCallback(ULView view, ULChangeTitleCallback callback,
+                                           void* user_data);
+
+typedef void (*ULChangeURLCallback)(void* user_data, ULView caller, ULString url);
+
+///
+/// Set callback for when the page URL changes.
+///
+ULExport void ulViewSetChangeURLCallback(ULView view, ULChangeURLCallback callback,
+                                         void* user_data);
+
+typedef void (*ULChangeTooltipCallback)(void* user_data, ULView caller, ULString tooltip);
+
+///
+/// Set callback for when the tooltip changes (usually result of a mouse hover).
+///
+ULExport void ulViewSetChangeTooltipCallback(ULView view, ULChangeTooltipCallback callback,
+                                             void* user_data);
+
+typedef void (*ULChangeCursorCallback)(void* user_data, ULView caller, ULCursor cursor);
+
+///
+/// Set callback for when the mouse cursor changes.
+///
+ULExport void ulViewSetChangeCursorCallback(ULView view, ULChangeCursorCallback callback,
+                                            void* user_data);
+
+typedef void (*ULAddConsoleMessageCallback)(void* user_data, ULView caller, ULMessageSource source,
+                                            ULMessageLevel level, ULString message,
+                                            unsigned int line_number, unsigned int column_number,
+                                            ULString source_id);
+
+///
+/// Set callback for when a message is added to the console (useful for JavaScript / network errors
+/// and debugging).
+///
+ULExport void ulViewSetAddConsoleMessageCallback(ULView view, ULAddConsoleMessageCallback callback,
+                                                 void* user_data);
+
+typedef ULView (*ULCreateChildViewCallback)(void* user_data, ULView caller, ULString opener_url,
+                                            ULString target_url, bool is_popup,
+                                            ULIntRect popup_rect);
+
+///
+/// Set callback for when the page wants to create a new View.
+///
+/// This is usually the result of a user clicking a link with target="_blank" or by JavaScript
+/// calling window.open(url).
+///
+/// To allow creation of these new Views, you should create a new View in this callback, resize it
+/// to your container, and return it. You are responsible for displaying the returned View.
+///
+/// You should return NULL if you want to block the action.
+///
+ULExport void ulViewSetCreateChildViewCallback(ULView view, ULCreateChildViewCallback callback,
+                                               void* user_data);
+
+typedef ULView (*ULCreateInspectorViewCallback)(void* user_data, ULView caller, bool is_local,
+                                                ULString inspected_url);
+
+///
+/// Set callback for when the page wants to create a new View to display the local inspector in.
+/// 
+/// You should create a new View in this callback, resize it to your
+/// container, and return it. You are responsible for displaying the returned View.
+/// 
+ULExport void ulViewSetCreateInspectorViewCallback(ULView view, ULCreateInspectorViewCallback callback,
+                                                   void* user_data);
+
+typedef void (*ULBeginLoadingCallback)(void* user_data, ULView caller, unsigned long long frame_id,
+                                       bool is_main_frame, ULString url);
+
+///
+/// Set callback for when the page begins loading a new URL into a frame.
+///
+ULExport void ulViewSetBeginLoadingCallback(ULView view, ULBeginLoadingCallback callback,
+                                            void* user_data);
+
+typedef void (*ULFinishLoadingCallback)(void* user_data, ULView caller, unsigned long long frame_id,
+                                        bool is_main_frame, ULString url);
+
+///
+/// Set callback for when the page finishes loading a URL into a frame.
+///
+ULExport void ulViewSetFinishLoadingCallback(ULView view, ULFinishLoadingCallback callback,
+                                             void* user_data);
+
+typedef void (*ULFailLoadingCallback)(void* user_data, ULView caller, unsigned long long frame_id,
+                                      bool is_main_frame, ULString url, ULString description,
+                                      ULString error_domain, int error_code);
+
+///
+/// Set callback for when an error occurs while loading a URL into a frame.
+///
+ULExport void ulViewSetFailLoadingCallback(ULView view, ULFailLoadingCallback callback,
+                                           void* user_data);
+
+typedef void (*ULWindowObjectReadyCallback)(void* user_data, ULView caller,
+                                            unsigned long long frame_id, bool is_main_frame,
+                                            ULString url);
+
+///
+/// Set callback for when the JavaScript window object is reset for a new page load.
+///
+/// This is called before any scripts are executed on the page and is the earliest time to setup any
+/// initial JavaScript state or bindings.
+///
+/// The document is not guaranteed to be loaded/parsed at this point. If you need to make any
+/// JavaScript calls that are dependent on DOM elements or scripts on the page, use DOMReady
+/// instead.
+///
+/// The window object is lazily initialized (this will not be called on pages with no scripts).
+///
+ULExport void ulViewSetWindowObjectReadyCallback(ULView view, ULWindowObjectReadyCallback callback,
+                                                 void* user_data);
+
+typedef void (*ULDOMReadyCallback)(void* user_data, ULView caller, unsigned long long frame_id,
+                                   bool is_main_frame, ULString url);
+
+///
+/// Set callback for when all JavaScript has been parsed and the document is ready.
+///
+/// This is the best time to make any JavaScript calls that are dependent on DOM elements or scripts
+/// on the page.
+///
+ULExport void ulViewSetDOMReadyCallback(ULView view, ULDOMReadyCallback callback, void* user_data);
+
+typedef void (*ULUpdateHistoryCallback)(void* user_data, ULView caller);
+
+///
+/// Set callback for when the history (back/forward state) is modified.
+///
+ULExport void ulViewSetUpdateHistoryCallback(ULView view, ULUpdateHistoryCallback callback,
+                                             void* user_data);
+
+///
+/// Set whether or not a view should be repainted during the next call to ulRender.
+///
+/// @note  This flag is automatically set whenever the page content changes but you can set it
+///        directly in case you need to force a repaint.
+///
+ULExport void ulViewSetNeedsPaint(ULView view, bool needs_paint);
+
+///
+/// Whether or not a view should be painted during the next call to ulRender.
+///
+ULExport bool ulViewGetNeedsPaint(ULView view);
+
+///
+/// Create an Inspector View to inspect / debug this View locally.
+///
+/// This will only succeed if you have the inspector assets in your filesystem-- the inspector
+/// will look for file:///inspector/Main.html when it first loads.
+///
+/// You must handle ulViewSetCreateInspectorViewCallback so that the library has a View to display
+/// the inspector in. This function will call the callback only if an inspector view is not
+/// currently active.
+///
+ULExport void ulViewCreateLocalInspectorView(ULView view);
+
+#ifdef __cplusplus
+} // extern "C"
+#endif
+
+#endif // ULTRALIGHT_CAPI_VIEW_H