Added SDK
This commit is contained in:
Andrew Zambazos
@@ -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
|
||||
Reference in New Issue
Block a user