CAPI_Platform.h

Overview

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 ship as Zlib-licensed source in the SDK's platform folder, 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.

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
ULThreadFactory	Optional	Optional
ULAudioOutput	Optional	Provided
ULProfiler	Optional	Optional

ULAudioOutput and ULProfiler require the Pro edition or higher.

Setting Handlers

Each ulPlatformSet*() function copies the struct you pass it, so the struct can be a temporary. The function pointers in it must stay valid until the Renderer or App is destroyed.

Set each handler once, before calling ulCreateRenderer() or ulCreateApp(). A later call replaces a handler that the library may still be using.

Functions
void	ulPlatformSetLogger (ULLogger logger)
	Set a custom Logger implementation.
void	ulPlatformSetFileSystem (ULFileSystem file_system)
	Set a custom FileSystem implementation.
void	ulPlatformSetFontLoader (ULFontLoader font_loader)
	Set a custom FontLoader implementation.
void	ulPlatformSetSurfaceDefinition (ULSurfaceDefinition surface_definition)
	Set a custom Surface implementation.
void	ulPlatformSetGPUDriver (ULGPUDriver gpu_driver)
	Set a custom GPUDriver implementation.
void	ulPlatformSetClipboard (ULClipboard clipboard)
	Set a custom Clipboard implementation.
void	ulPlatformSetThreadFactory (ULThreadFactory thread_factory)
	Set a custom ThreadFactory implementation.
void	ulPlatformSetAudioOutput (ULAudioOutput audio_output)
	Set a custom AudioOutput implementation.
void	ulPlatformSetProfiler (ULProfiler profiler)
	Set a custom Profiler implementation.

Function Documentation

ulPlatformSetAudioOutput()

void ulPlatformSetAudioOutput

(

ULAudioOutput

audio_output

)

Set a custom AudioOutput implementation.

The library uses this to play decoded audio for <video> and <audio> elements. ulCreateApp() provides one for you unless you've set your own first. If you are using ulCreateRenderer() and don't set one, media plays without sound.

You should call this before ulCreateRenderer() or ulCreateApp(). The callbacks must remain valid until after the Renderer/App is destroyed.

Precondition

Requires the Pro edition or higher.

ulPlatformSetClipboard()

void ulPlatformSetClipboard

(

ULClipboard

clipboard

)

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().

ulPlatformSetFileSystem()

void ulPlatformSetFileSystem

(

ULFileSystem

file_system

)

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 also

<AppCore/CAPI.h>)

ulPlatformSetFontLoader()

void ulPlatformSetFontLoader

(

ULFontLoader

font_loader

)

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 also

<AppCore/CAPI.h>)

ulPlatformSetGPUDriver()

void ulPlatformSetGPUDriver

(

ULGPUDriver

gpu_driver

)

Set a custom GPUDriver implementation.

This should be used if you are using ulCreateRenderer() (which does not provide its own GPUDriver implementation) and want Views rendered on the GPU. A View renders on the GPU when you create it with ulViewConfigSetIsAccelerated() set to true.

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 Zlib-licensed reference implementations for this interface in the SDK's platform folder.

You should call this before ulCreateRenderer().

ulPlatformSetLogger()

void ulPlatformSetLogger

(

ULLogger

logger

)

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 also

<AppCore/CAPI.h>)

ulPlatformSetProfiler()

void ulPlatformSetProfiler

(

ULProfiler

profiler

)

Set a custom Profiler implementation.

When set, the library emits structured timing data (scopes, events, counters) at key internal boundaries that can be forwarded to any profiling tool or trace format.

You should call this before ulCreateRenderer() or ulCreateApp(). The profiler callbacks must remain valid until after the Renderer/App is destroyed.

Precondition

Requires the Pro edition or higher.

ulPlatformSetSurfaceDefinition()

void ulPlatformSetSurfaceDefinition

(

ULSurfaceDefinition

surface_definition

)

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().

ulPlatformSetThreadFactory()

void ulPlatformSetThreadFactory

(

ULThreadFactory

thread_factory

)

Set a custom ThreadFactory implementation.

This can be used to provide a platform-specific thread creation implementation for the library to use when creating threads (useful for tracking thread creation, setting thread names, etc).

You should call this before ulCreateRenderer() or ulCreateApp().

Note

The library creates threads using the default platform-specific thread creation functions if you never call this.

Go to the source code of this file.