Overview

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)

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 ship as Zlib-licensed source in the SDK's platform folder. You can use these stock implementations by copying the code into your project, or you can write your own.

At a minimum, you must provide a ULFileSystem and a ULFontLoader. Without them, the library exits the process with an error when it first needs them.

Creating the Renderer

Once you've set up the Platform handlers you can create the Renderer by calling ulCreateRenderer().

Example creation code: // Setup our config.

ULConfig config = ulCreateConfig();

// Use the default platform font loader.

ulEnablePlatformFontLoader();

// Use the default platform 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...

ulEnablePlatformFontLoader
void ulEnablePlatformFontLoader(void)
Initialize the platform font loader and set it as the current FontLoader.

ulEnablePlatformFileSystem
void ulEnablePlatformFileSystem(ULString base_dir)
Initialize the platform file system (needed for loading file:/// URLs) and set it as the current File...

ulDestroyConfig
void ulDestroyConfig(ULConfig config)
Destroy a ULConfig instance created by ulCreateConfig().

ulCreateConfig
ULConfig ulCreateConfig(void)
Create config with default values (see <Ultralight/platform/Config.h>).

ulCreateRenderer
ULRenderer ulCreateRenderer(ULConfig config)
Create the core renderer singleton for the library.

ulCreateString
ULString ulCreateString(const char *str)
Create string from a null-terminated UTF-8 C-string.

ulDestroyString
void ulDestroyString(ULString str)
Destroy a string previously created with ulCreateString(), ulCreateStringUTF8(), ulCreateStringUTF16(...

ULString
struct C_String * ULString
Opaque handle to a String object.
Definition CAPI_Defines.h:96

ULConfig
struct C_Config * ULConfig
Opaque handle to a Config object.
Definition CAPI_Defines.h:75

ULRenderer
struct C_Renderer * ULRenderer
Opaque handle to a Renderer object.
Definition CAPI_Defines.h:78

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:

Example update code: void mainLoop()

{

while(true)

{

// Update program logic here

ulUpdate(renderer);

}

}

ulUpdate
void ulUpdate(ULRenderer renderer)
Update timers and dispatch internal callbacks (JavaScript and network).

Rendering Each Frame

When your program is ready to display a new frame (usually in sync with the monitor's refresh rate), you should call ulRefreshDisplay() and ulRender() so the library can render all active Views as needed.

Animations and smooth scrolling advance with each ulRefreshDisplay() call. Call it once per frame you present (once per display refresh for a vsynced loop, or once per rendered frame for a vsync-off or variable-refresh game loop).

Example per-frame render code: void displayFrame()

{

// Notify the renderer that the main display has refreshed. This updates animations,

// smooth scrolling, and window.requestAnimationFrame() for all Views on that display.

ulRefreshDisplay(renderer, 0);

// Render all Views as needed

ulRender(renderer);

// Each View renders 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.

}

ulRefreshDisplay
void ulRefreshDisplay(ULRenderer renderer, unsigned int display_id)
Notify the renderer that a display has refreshed.

ulRender
void ulRender(ULRenderer renderer)
Render all active Views to their respective surfaces and render targets.

Classes
struct	ULGCInfo
	A snapshot of the JavaScript heap's state. More...

Functions
ULRenderer	ulCreateRenderer (ULConfig config)
	Create the core renderer singleton for the library.
void	ulDestroyRenderer (ULRenderer renderer)
	Destroy a renderer previously created with ulCreateRenderer().
void	ulUpdate (ULRenderer renderer)
	Update timers and dispatch internal callbacks (JavaScript and network).
void	ulRefreshDisplay (ULRenderer renderer, unsigned int display_id)
	Notify the renderer that a display has refreshed.
void	ulRefreshDisplayWithTimestamp (ULRenderer renderer, unsigned int display_id, double target_timestamp)
	Notify the renderer that a display has refreshed, and when the resulting frame will be shown.
void	ulRendererSetDisplayRefreshRate (ULRenderer renderer, unsigned int display_id, double refresh_rate)
	Declare a display's refresh rate.
double	ulRendererGetDisplayRefreshRate (ULRenderer renderer, unsigned int display_id)
	Get the refresh rate declared for a display.
void	ulRendererSetDisplayUsesCustomClock (ULRenderer renderer, unsigned int display_id, bool uses_custom_clock)
	Declare that a display's refresh timestamps are on your own timeline rather than the system clock (Default = False).
bool	ulRendererGetDisplayUsesCustomClock (ULRenderer renderer, unsigned int display_id)
	Get whether a display was declared to use a custom clock.
void	ulRender (ULRenderer renderer)
	Render all active Views to their respective surfaces and render targets.
void	ulRendererPostTask (ULRenderer renderer, ULRendererTaskCallback task, void *user_data, ULUserDataDestroyCallback destroy_user_data)
	Post a task to run on the Renderer's thread during a future call to ulUpdate().
void	ulRendererPostDelayedTask (ULRenderer renderer, double delay_ms, ULRendererTaskCallback task, void *user_data, ULUserDataDestroyCallback destroy_user_data)
	Post a task to run on the Renderer's thread once a delay has elapsed.
void	ulRecycle (ULRenderer renderer, ULRecycleMode mode)
	Recycle internal caches and memory.
void	ulPurgeMemory (ULRenderer renderer)
	Attempt to release as much memory as possible.
void	ulLogMemoryUsage (ULRenderer renderer)
	Print detailed memory usage statistics to the log.
bool	ulStartRemoteInspectorServer (ULRenderer renderer, const char *address, unsigned short port)
	Start the remote inspector server.
void	ulSetGamepadDetails (ULRenderer renderer, unsigned int index, ULString id, unsigned int axis_count, unsigned int button_count)
	Describe the details of a gamepad, to be used with ulFireGamepadEvent and related events below.
void	ulFireGamepadEvent (ULRenderer renderer, ULGamepadEvent evt)
	Fire a gamepad event (connection / disconnection).
void	ulFireGamepadAxisEvent (ULRenderer renderer, ULGamepadAxisEvent evt)
	Fire a gamepad axis event (to be called when an axis value is changed).
void	ulFireGamepadButtonEvent (ULRenderer renderer, ULGamepadButtonEvent evt)
	Fire a gamepad button event (to be called when a button value is changed).
void	ulRenderOnly (ULRenderer renderer, ULView *view_array, unsigned int view_array_len)
	Render a subset of Views to their respective surfaces and render targets.
ULString	ulGetMemoryUsage (ULRenderer renderer)
	Get formatted memory usage statistics as a string.
void	ulRendererSetSystemColorScheme (ULRenderer renderer, ULColorScheme scheme)
	Set the system color scheme that Views report to pages via the prefers-color-scheme CSS media feature.
ULColorScheme	ulRendererGetSystemColorScheme (ULRenderer renderer)
	Get the current system color scheme.
bool	ulRendererBeginRenderTrace (ULRenderer renderer, const char *path, bool verbose)
	Begin recording a render trace to the specified file path.
void	ulRendererEndRenderTrace (ULRenderer renderer)
	End the current render trace.
bool	ulRendererIsRenderTraceActive (ULRenderer renderer)
	Check if a render trace is currently being recorded.
void	ulRendererSetGCRequestGCCallback (ULRenderer renderer, ULGCRequestGCCallback callback, void *user_data, ULUserDataDestroyCallback destroy_user_data)
	Set the callback for when the engine wants to run a collection on your thread (see ULGCRequestGCCallback).
void	ulRendererSetGCPressureChangedCallback (ULRenderer renderer, ULGCPressureChangedCallback callback, void *user_data, ULUserDataDestroyCallback destroy_user_data)
	Set the callback for when reclaimable memory rises past a threshold (see ULGCPressureChangedCallback).
void	ulRendererSetGCCollectCompleteCallback (ULRenderer renderer, ULGCCollectCompleteCallback callback, void *user_data, ULUserDataDestroyCallback destroy_user_data)
	Set the callback for when a collection on your thread finishes (see ULGCCollectCompleteCallback).
ULGCInfo	ulRendererGetGCStatus (ULRenderer renderer)
	Get a snapshot of the JavaScript heap's state.
void	ulRecycleEx (ULRenderer renderer, ULRecycleMode mode, ULCodeDropMode code)
	Reclaim memory, choosing how much compiled code to discard.
void	ulRendererCollectNow (ULRenderer renderer, ULCodeDropMode code, bool sync)
	Collect the JavaScript heap now, leaving rendering and GPU caches intact.

Typedefs
typedef void(*)	ULRendererTaskCallback(void *user_data)
typedef void(*)	ULGCRequestGCCallback(void *user_data, ULRenderer caller, ULGCInfo info, ULCodeDropMode code)
	Called when the engine wants to run a collection on your thread.
typedef void(*)	ULGCPressureChangedCallback(void *user_data, ULRenderer caller, ULGCInfo info)
	Called when reclaimable memory rises past a threshold (see ULGCInfo).
typedef void(*)	ULGCCollectCompleteCallback(void *user_data, ULRenderer caller, ULGCInfo info, ULCodeDropMode code, double duration_ms, unsigned long long bytes_reclaimed)
	Called after a collection on your thread finishes.

Enumerations
enum	ULRecycleMode { kRecycleMode_Lightweight = 0 , kRecycleMode_Full }
	Controls how aggressively ulRecycle() reclaims memory. More...
enum	ULCodeDropMode { kCodeDropMode_Nothing = 0 , kCodeDropMode_Linked , kCodeDropMode_All }
	How much compiled JavaScript code a collection discards. More...

Function Documentation

◆ ulCreateRenderer()

ULRenderer ulCreateRenderer ( ULConfig config )

Create the core renderer singleton for the library.

You should set up the Platform singleton (see CAPI_Platform.h) before calling this function.

Parameters

config The configuration to use for the renderer.

Returns: Returns the new renderer instance, or NULL on failure. You must call ulDestroyRenderer() when finished.

Note: You do not need to call this if you're using ulCreateApp() from AppCore.

Warning: You must define a ULFontLoader and a ULFileSystem in the Platform singleton. Without them, the library exits the process with an error when it first needs them.

Warning: You should only create one Renderer during the lifetime of your program.

◆ ulDestroyRenderer()

void ulDestroyRenderer ( ULRenderer renderer )

Destroy a renderer previously created with ulCreateRenderer().

Parameters

renderer The renderer instance to destroy (can be NULL).

◆ ulFireGamepadAxisEvent()

void ulFireGamepadAxisEvent	(	ULRenderer	renderer,
		ULGamepadAxisEvent	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.

Parameters

renderer	The active renderer instance.
evt	The event to fire.

See also: https://developer.mozilla.org/en-US/docs/Web/API/Gamepad/axes

◆ ulFireGamepadButtonEvent()

void ulFireGamepadButtonEvent	(	ULRenderer	renderer,
		ULGamepadButtonEvent	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.

Parameters

renderer	The active renderer instance.
evt	The event to fire.

See also: https://developer.mozilla.org/en-US/docs/Web/API/Gamepad/buttons

◆ ulFireGamepadEvent()

void ulFireGamepadEvent	(	ULRenderer	renderer,
		ULGamepadEvent	evt )

Fire a gamepad event (connection / disconnection).

Note: The gamepad should first be described via ulSetGamepadDetails before calling this function.

Parameters

renderer	The active renderer instance.
evt	The event to fire.

See also: https://developer.mozilla.org/en-US/docs/Web/API/Gamepad

◆ ulGetMemoryUsage()

ULString ulGetMemoryUsage ( ULRenderer renderer )

Get formatted memory usage statistics as a string.

This is the same information ulLogMemoryUsage() prints, in a form you can show in a debug overlay or capture programmatically.

Parameters

renderer The active renderer instance.

Returns: Returns a new ULString holding the memory usage report. You must call ulDestroyString() when finished.

◆ ulLogMemoryUsage()

void ulLogMemoryUsage ( ULRenderer renderer )

Print detailed memory usage statistics to the log.

Parameters

renderer The active renderer instance.

See also: ulPlatformSetLogger()

◆ ulPurgeMemory()

void ulPurgeMemory ( ULRenderer renderer )

Attempt to release as much memory as possible.

This also discards all compiled JavaScript code, so pages run slower for a while as it's recompiled.

Parameters

renderer The active renderer instance.

Warning: Don't call this while the renderer is rendering (eg, from a GPU driver callback): the rendering caches can't be released then, and are skipped with a warning.

◆ ulRecycle()

void ulRecycle	(	ULRenderer	renderer,
		ULRecycleMode	mode )

Recycle internal caches and memory.

Parameters

renderer	The active renderer instance.
mode	How aggressively to reclaim memory.

See also: Renderer::Recycle()

◆ ulRecycleEx()

void ulRecycleEx	(	ULRenderer	renderer,
		ULRecycleMode	mode,
		ULCodeDropMode	code )

Reclaim memory, choosing how much compiled code to discard.

This works like ulRecycle(). With kRecycleMode_Full, code sets how much compiled code the collection discards (it has no effect with kRecycleMode_Lightweight).

Parameters

renderer	The Renderer.
mode	How aggressively to reclaim memory.
code	How much compiled code to discard.

Precondition: Requires the Pro edition or higher.

See also: ulRecycle()

◆ ulRefreshDisplay()

void ulRefreshDisplay	(	ULRenderer	renderer,
		unsigned int	display_id )

Notify the renderer that a display has refreshed.

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.

Animations and smooth scroll advance to each ulRefreshDisplay() call. Call it once per frame you present (once per display refresh for a vsynced loop, or once per rendered frame for a vsync-off or variable-refresh game loop).

Call this once per frame you present, for each display (usually right after vsync). It advances animations, smooth scrolling, and window.requestAnimationFrame() for the Views on that display, so they can repaint during the next ulRender().

Parameters

renderer	The active renderer instance.
display_id	The id of the display that refreshed (see ulViewConfigSetDisplayId()).

Note: Keep calling this even while ulViewGetNeedsPaint() returns false: animations only request a repaint from this call.

Note: Call this on the thread the renderer was created on.

◆ ulRefreshDisplayWithTimestamp()

void ulRefreshDisplayWithTimestamp	(	ULRenderer	renderer,
		unsigned int	display_id,
		double	target_timestamp )

Notify the renderer that a display has refreshed, and when the resulting frame will be shown.

This works like ulRefreshDisplay(), but animation time follows your timestamps instead of the wall clock, so animations are timed for the moment the frame reaches the screen.

Parameters

renderer	The active renderer instance.
display_id	The id of the display that refreshed.
target_timestamp	When this frame will be shown, in seconds. Use the system's monotonic clock (eg, the target time your display link reports), or your own timeline after calling ulRendererSetDisplayUsesCustomClock(). Timestamps must never decrease.

Note: performance.now() stays on the wall clock, so pages that compare it to window.requestAnimationFrame() timestamps will see the difference.

See also: ulRendererSetDisplayRefreshRate(), ulRendererSetDisplayUsesCustomClock()

◆ ulRender()

void ulRender ( ULRenderer renderer )

Render all active Views to their respective surfaces and render targets.

Parameters

renderer The active renderer instance.

◆ ulRendererBeginRenderTrace()

bool ulRendererBeginRenderTrace	(	ULRenderer	renderer,
		const char *	path,
		bool	verbose )

Begin recording a render trace to the specified file path.

Parameters

renderer	The active renderer instance.
path	Output file path (eg, "render_trace.perfetto-trace").
verbose	If true, enables verbose mode (args + events in addition to scopes).

Returns: Returns whether or not the trace started (false if a trace is already active or the trace file can't be opened).

Precondition: Requires the Enterprise edition or higher.

◆ ulRendererCollectNow()

void ulRendererCollectNow	(	ULRenderer	renderer,
		ULCodeDropMode	code,
		bool	sync )

Collect the JavaScript heap now, leaving rendering and GPU caches intact.

Unlike ulRecycle(), this reclaims only the JavaScript heap, so rendering stays fast. You can call it from your ULGCRequestGCCallback or at any moment when a short pause won't be noticed.

Parameters

renderer	The Renderer.
code	How much compiled code to discard.
sync	If true, collect before returning. If false, collect in the background.

Note: If you call this while JavaScript is running (eg, from a JS callback), the collection waits until the script returns, even with sync set to true.

Note: The collect-complete callback fires only for a synchronous collection.

Precondition: Requires the Pro edition or higher.

◆ ulRendererEndRenderTrace()

void ulRendererEndRenderTrace ( ULRenderer renderer )

End the current render trace.

The trace file is finished and closed shortly after this returns (on the next ulUpdate()).

Parameters

renderer The active renderer instance.

Precondition: Requires the Enterprise edition or higher.

◆ ulRendererGetDisplayRefreshRate()

double ulRendererGetDisplayRefreshRate	(	ULRenderer	renderer,
		unsigned int	display_id )

Get the refresh rate declared for a display.

Parameters

renderer	The active renderer instance.
display_id	The display ID.

Returns: Returns the display's declared refresh rate (in Hz), or 0 if ulRendererSetDisplayRefreshRate() was never called for it.

◆ ulRendererGetDisplayUsesCustomClock()

bool ulRendererGetDisplayUsesCustomClock	(	ULRenderer	renderer,
		unsigned int	display_id )

Get whether a display was declared to use a custom clock.

Parameters

renderer	The active renderer instance.
display_id	The display ID.

Returns: Returns the value last passed to ulRendererSetDisplayUsesCustomClock() for the display, or false if it was never called.

◆ ulRendererGetGCStatus()

ULGCInfo ulRendererGetGCStatus ( ULRenderer renderer )

Get a snapshot of the JavaScript heap's state.

Parameters

renderer The Renderer.

Returns: Returns the current heap state (see ULGCInfo).

Precondition: Requires the Pro edition or higher.

◆ ulRendererGetSystemColorScheme()

ULColorScheme ulRendererGetSystemColorScheme ( ULRenderer renderer )

Get the current system color scheme.

Parameters

renderer The active renderer instance.

Returns: Returns the scheme last set with ulRendererSetSystemColorScheme(), or kColorScheme_Light if it was never called.

◆ ulRendererIsRenderTraceActive()

bool ulRendererIsRenderTraceActive ( ULRenderer renderer )

Check if a render trace is currently being recorded.

Parameters

renderer The active renderer instance.

Returns: Returns whether a render trace session is active.

Precondition: Requires the Enterprise edition or higher.

◆ ulRendererPostDelayedTask()

void ulRendererPostDelayedTask	(	ULRenderer	renderer,
		double	delay_ms,
		ULRendererTaskCallback	task,
		void *	user_data,
		ULUserDataDestroyCallback	destroy_user_data )

Post a task to run on the Renderer's thread once a delay has elapsed.

The delay is measured against the ulUpdate() cadence rather than a background timer. The task runs during the first ulUpdate() at or after the deadline, so delivery waits while ulUpdate() is not being called (for example, a paused application). Tasks whose deadlines fall in the same ulUpdate() run in posting order.

Parameters

renderer	The active renderer instance.
delay_ms	Minimum delay before the task may run, in milliseconds.
task	Invoked once on the Renderer's thread with user_data.
user_data	Pointer passed through to task (can be NULL).
destroy_user_data	Invoked exactly once after task runs, or without task running if the Renderer is destroyed first or renderer is NULL (can be NULL).

See also: ulRendererPostTask()

◆ ulRendererPostTask()

void ulRendererPostTask	(	ULRenderer	renderer,
		ULRendererTaskCallback	task,
		void *	user_data,
		ULUserDataDestroyCallback	destroy_user_data )

Post a task to run on the Renderer's thread during a future call to ulUpdate().

You can use this to hand work from your other threads to the thread that drives the Renderer (the only thread that may touch Views and the DOM API).

Tasks run in posting order during the next ulUpdate() after they are posted. A task posted while ulUpdate() is draining tasks runs at the following ulUpdate().

Parameters

renderer	The active renderer instance.
task	Invoked once on the Renderer's thread with user_data. A NULL task posts nothing; destroy_user_data then runs at once.
user_data	Pointer passed through to task (can be NULL).
destroy_user_data	Invoked exactly once after task runs, or without task running if the Renderer is destroyed first or renderer is NULL (can be NULL).

Note: Safe to call from any thread.

Note: With AppCore, ulAppPostTask() posts to this same queue and also wakes the app's loop, so prefer it there.

◆ ulRendererSetDisplayRefreshRate()

void ulRendererSetDisplayRefreshRate	(	ULRenderer	renderer,
		unsigned int	display_id,
		double	refresh_rate )

Declare a display's refresh rate.

Pages see the declared rate through window.requestAnimationFrame() scheduling. Call this when the display's mode changes (eg, a variable-rate display switching between 120 Hz and 48 Hz). Small changes are absorbed, and a change reaches pages at most once a second.

Parameters

renderer	The active renderer instance.
display_id	The id of the display.
refresh_rate	The display mode's nominal refresh rate in Hz (eg, 60.0, 59.94, 120.0), or 0 to clear it (the library then measures how often ulRefreshDisplay() is called).

Note: Call this on the thread the renderer was created on.

◆ ulRendererSetDisplayUsesCustomClock()

void ulRendererSetDisplayUsesCustomClock	(	ULRenderer	renderer,
		unsigned int	display_id,
		bool	uses_custom_clock )

Declare that a display's refresh timestamps are on your own timeline rather than the system clock (Default = False).

By default, the timestamps you pass to ulRefreshDisplayWithTimestamp() are treated as readings of the system's monotonic clock. Declare a custom clock when they're on a timeline of your own (eg, a media timeline for offline rendering, or simulation time): animation then follows your timestamps exactly.

Parameters

renderer	The active renderer instance.
display_id	The id of the display.
uses_custom_clock	True if timestamps for this display are on your own timeline.

Precondition: Call this before the display's first timed refresh.

Note: Call this on the thread the renderer was created on.

◆ ulRendererSetGCCollectCompleteCallback()

void ulRendererSetGCCollectCompleteCallback	(	ULRenderer	renderer,
		ULGCCollectCompleteCallback	callback,
		void *	user_data,
		ULUserDataDestroyCallback	destroy_user_data )

Set the callback for when a collection on your thread finishes (see ULGCCollectCompleteCallback).

Parameters

renderer	The Renderer.
callback	The callback to invoke, or NULL to remove it.
user_data	Pointer passed through to callback (can be NULL). Ownership transfers to the Renderer.
destroy_user_data	Invoked exactly once on user_data when the callback is replaced or the Renderer is destroyed, or right away if renderer is NULL. Can be NULL.

Precondition: Requires the Pro edition or higher.

See also: ulRendererSetGCRequestGCCallback()

◆ ulRendererSetGCPressureChangedCallback()

void ulRendererSetGCPressureChangedCallback	(	ULRenderer	renderer,
		ULGCPressureChangedCallback	callback,
		void *	user_data,
		ULUserDataDestroyCallback	destroy_user_data )

Set the callback for when reclaimable memory rises past a threshold (see ULGCPressureChangedCallback).

Parameters

renderer	The Renderer.
callback	The callback to invoke, or NULL to remove it.
user_data	Pointer passed through to callback (can be NULL). Ownership transfers to the Renderer.
destroy_user_data	Invoked exactly once on user_data when the callback is replaced or the Renderer is destroyed, or right away if renderer is NULL. Can be NULL.

Precondition: Requires the Pro edition or higher.

See also: ulRendererSetGCRequestGCCallback()

◆ ulRendererSetGCRequestGCCallback()

void ulRendererSetGCRequestGCCallback	(	ULRenderer	renderer,
		ULGCRequestGCCallback	callback,
		void *	user_data,
		ULUserDataDestroyCallback	destroy_user_data )

Set the callback for when the engine wants to run a collection on your thread (see ULGCRequestGCCallback).

Setting a callback replaces the previous one. With no callback set, the engine collects right away.

Parameters

renderer	The Renderer.
callback	The callback to invoke, or NULL to remove it.
user_data	Pointer passed through to callback (can be NULL). Ownership transfers to the Renderer.
destroy_user_data	Invoked exactly once on user_data when the callback is replaced or the Renderer is destroyed (never while the callback is running), or right away if renderer is NULL. Can be NULL.

Note: All GC callbacks run during ulUpdate() on the thread that calls it.

Note: Each setter owns its user_data separately, so pass a shared context with a NULL destroy_user_data to all but one setter.

Warning: Don't remove a GC callback from inside a GC callback.

Precondition: Requires the Pro edition or higher.

◆ ulRendererSetSystemColorScheme()

void ulRendererSetSystemColorScheme	(	ULRenderer	renderer,
		ULColorScheme	scheme )

Set the system color scheme that Views report to pages via the prefers-color-scheme CSS media feature.

(Default = kColorScheme_Light)

The library never reads the OS setting itself, so the scheme stays Light until you call this.

A change re-evaluates prefers-color-scheme media queries in every View whose preferred color scheme is kColorScheme_Auto. Views pinned to Light or Dark are unaffected.

Parameters

renderer	The active renderer instance.
scheme	kColorScheme_Light or kColorScheme_Dark. kColorScheme_Auto or an out-of-range value logs a warning and is ignored.

See also: ulViewSetPreferredColorScheme()

◆ ulRenderOnly()

void ulRenderOnly	(	ULRenderer	renderer,
		ULView *	view_array,
		unsigned int	view_array_len )

Render a subset of Views to their respective surfaces and render targets.

Parameters

renderer	The active renderer instance.
view_array	A C-array of ULView handles to render.
view_array_len	The number of elements in the array.

Deprecated: Use ulRender() instead. To stop a View from painting, pause it with ulViewSetVisible() (ulRender() skips hidden Views).

◆ ulSetGamepadDetails()

void ulSetGamepadDetails	(	ULRenderer	renderer,
		unsigned int	index,
		ULString	id,
		unsigned int	axis_count,
		unsigned int	button_count )

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.

Parameters

renderer	The active renderer instance.
index	The gamepad's connection slot, and the array position the page sees. A gamepad described at index 1 arrives as navigator.getGamepads()[1] with gamepad.index 1, leaving slot 0 null. Number your controllers from 0.
id	A string ID representing the device, this will be made available in JavaScript as gamepad.id
axis_count	The number of axes on the device.
button_count	The number of buttons on the device.

◆ ulStartRemoteInspectorServer()

bool ulStartRemoteInspectorServer	(	ULRenderer	renderer,
		const char *	address,
		unsigned short	port )

Start the remote inspector server.

While it runs, another Ultralight app (on the same machine or over the network) can inspect this renderer's Views by loading this URL in a View:

inspector://<ADDRESS>:<PORT>

Parameters

renderer	The active renderer instance.
address	The address for the server to listen on (eg, "127.0.0.1")
port	The port for the server to listen on (eg, 9222)

Returns: Returns whether the server started successfully or not.

Precondition: Not available in the Free edition (always returns false there).

◆ ulUpdate()

void ulUpdate ( ULRenderer renderer )

Update timers and dispatch internal callbacks (JavaScript and network).

Parameters

renderer The active renderer instance.

Typedef Documentation

◆ ULGCCollectCompleteCallback

typedef void(*) ULGCCollectCompleteCallback(void *user_data, ULRenderer caller, ULGCInfo info, ULCodeDropMode code, double duration_ms, unsigned long long bytes_reclaimed)

Called after a collection on your thread finishes.

This covers the engine's own collections and the ones you start with ulRendererCollectNow(), ulRecycle(), ulRecycleEx(), or ulPurgeMemory(). It's called during the next ulUpdate().

Parameters

user_data	The pointer you passed to ulRendererSetGCCollectCompleteCallback().
caller	The Renderer.
info	The heap state when this is called.
code	How much compiled code the collection was asked to discard.
duration_ms	How long the collection took in milliseconds.
bytes_reclaimed	How many bytes the collection freed.

◆ ULGCPressureChangedCallback

typedef void(*) ULGCPressureChangedCallback(void *user_data, ULRenderer caller, ULGCInfo info)

Called when reclaimable memory rises past a threshold (see ULGCInfo).

You can use this to decide when to reclaim memory yourself (eg, with ulRendererCollectNow()). It fires again only after the pressure drops and rises again.

Parameters

user_data	The pointer you passed to ulRendererSetGCPressureChangedCallback().
caller	The Renderer.
info	The current heap state.

◆ ULGCRequestGCCallback

typedef void(*) ULGCRequestGCCallback(void *user_data, ULRenderer caller, ULGCInfo info, ULCodeDropMode code)

Called when the engine wants to run a collection on your thread.

The Renderer collects JavaScript garbage continuously in the background on other threads, so most collection work never touches your thread. Occasionally it needs a larger collection that runs on the thread that calls ulUpdate() and pauses it while it runs.

Your application knows better than the engine when a pause won't be noticed (eg, a loading screen or a quiet moment in your update loop). So the engine asks first, when there's been no input for a while (see ulConfigSetIdleGCEnabled()). One idle period can bring two requests: a lighter one first, then, if the app stays idle, one that drops more compiled code. A request you don't act on isn't offered again until new input ends the idle period.

From the callback, call ulRendererCollectNow() with code to collect right away, or call it later at a moment you choose, or skip the collection. With no callback set, the engine collects right away.

Parameters

user_data	The pointer you passed to ulRendererSetGCRequestGCCallback().
caller	The Renderer to collect on.
info	The current heap state.
code	How much compiled code the engine recommends discarding (pass it to ulRendererCollectNow()).

◆ ULRendererTaskCallback

typedef void(*) ULRendererTaskCallback(void *user_data)

Enumeration Type Documentation

◆ ULCodeDropMode

enum ULCodeDropMode

How much compiled JavaScript code a collection discards.

Compiled code keeps some JavaScript objects alive, so discarding it lets a collection free more memory. Pages then run slower for a while as their code is compiled again.

See also: ulRendererCollectNow(), ulRecycleEx()

Enumerator
kCodeDropMode_Nothing	Keep all compiled code.
kCodeDropMode_Linked	Discard compiled code but keep parsed scripts (pages recompile but don't re-parse).
kCodeDropMode_All	Discard compiled code and parsed scripts (pages re-parse and recompile).

◆ ULRecycleMode

enum ULRecycleMode

Controls how aggressively ulRecycle() reclaims memory.

See also: Renderer::RecycleMode

Enumerator

kRecycleMode_Lightweight

A quick recycle, cheap enough to call every frame (the same work the automatic recycler does).

kRecycleMode_Full

A thorough recycle, for idle periods or transitions (eg, a loading screen).

A call within a second of the last one does nothing.

Go to the source code of this file.

Overview

Creating the Renderer

Defining Platform Handlers

Creating the Renderer

Updating Renderer Logic

Rendering Each Frame

Classes

Functions

Typedefs

Enumerations

Function Documentation

◆ ulCreateRenderer()

◆ ulDestroyRenderer()

◆ ulFireGamepadAxisEvent()

◆ ulFireGamepadButtonEvent()

◆ ulFireGamepadEvent()

◆ ulGetMemoryUsage()

◆ ulLogMemoryUsage()

◆ ulPurgeMemory()

◆ ulRecycle()

◆ ulRecycleEx()

◆ ulRefreshDisplay()

Rendering Each Frame

◆ ulRefreshDisplayWithTimestamp()

◆ ulRender()

◆ ulRendererBeginRenderTrace()

◆ ulRendererCollectNow()

◆ ulRendererEndRenderTrace()

◆ ulRendererGetDisplayRefreshRate()

◆ ulRendererGetDisplayUsesCustomClock()

◆ ulRendererGetGCStatus()

◆ ulRendererGetSystemColorScheme()

◆ ulRendererIsRenderTraceActive()

◆ ulRendererPostDelayedTask()

◆ ulRendererPostTask()

◆ ulRendererSetDisplayRefreshRate()

◆ ulRendererSetDisplayUsesCustomClock()

◆ ulRendererSetGCCollectCompleteCallback()

◆ ulRendererSetGCPressureChangedCallback()

◆ ulRendererSetGCRequestGCCallback()

◆ ulRendererSetSystemColorScheme()

◆ ulRenderOnly()

◆ ulSetGamepadDetails()

◆ ulStartRemoteInspectorServer()

◆ ulUpdate()

Typedef Documentation

◆ ULGCCollectCompleteCallback

◆ ULGCPressureChangedCallback

◆ ULGCRequestGCCallback

◆ ULRendererTaskCallback

Enumeration Type Documentation

◆ ULCodeDropMode

◆ ULRecycleMode