CAPI_Platform.h File Reference

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 are defined in the AppCore repository, 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

Note

This singleton should be set up before creating the Renderer or App.

Functions
ULExport void	ulPlatformSetLogger (ULLogger logger)
	Set a custom Logger implementation.
ULExport void	ulPlatformSetFileSystem (ULFileSystem file_system)
	Set a custom FileSystem implementation.
ULExport void	ulPlatformSetFontLoader (ULFontLoader font_loader)
	Set a custom FontLoader implementation.
ULExport void	ulPlatformSetSurfaceDefinition (ULSurfaceDefinition surface_definition)
	Set a custom Surface implementation.
ULExport void	ulPlatformSetGPUDriver (ULGPUDriver gpu_driver)
	Set a custom GPUDriver implementation.
ULExport void	ulPlatformSetClipboard (ULClipboard clipboard)
	Set a custom Clipboard implementation.

Function Documentation

ulPlatformSetClipboard()

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

ULExport 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.

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

ULExport 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.

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

ULExport void ulPlatformSetGPUDriver

(

ULGPUDriver

gpu_driver

)

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

ulPlatformSetLogger()

ULExport 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.

If you're not using ulCreateApp(), (eg, using ulCreateRenderer()) you can still use the default logger by calling ulEnableDefaultLogger() (

See also

<AppCore/CAPI.h>)

ulPlatformSetSurfaceDefinition()

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

Go to the source code of this file.