Renderer

#include <Ultralight/Renderer.h>

Overview

Core renderer singleton for the library, coordinates all library functions.

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 App::Create() (access it via App::renderer).

App::Create() 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. 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. 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 FileSystem and FontLoader otherwise Renderer creation will fail.

Setting Up the Config

You can configure various library options by creating a Config object and passing it to Platform::instance().set_config().

Creating the Renderer

Once you've set up the Platform handlers and Config, you can create the Renderer by calling Renderer::Create(). You should store the result in a RefPtr to keep it alive.

Example creation code

// Get the Platform singleton (maintains global library state)
auto& platform = Platform::instance();
 
// Setup config
Config my_config;
platform.set_config(my_config);
 
// Create platform handlers (these are the minimum required)
// (This is pseudo-code, you will need to define your own)
MyFileSystem* file_system = new MyFileSystem();
MyFontLoader* font_loader = new MyFontLoader();
 
// Setup platform handlers
platform.set_file_system(file_system);
platform.set_font_loader(font_loader);
 
// Create the Renderer
RefPtr<Renderer> renderer = Renderer::Create();
 
// Create Views here

Updating Renderer Logic

You should call Renderer::Update() 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
    renderer.Update();
  }
}

Rendering Each Frame

When your program is ready to display a new frame (usually in synchrony with the monitor refresh rate), you should call Renderer::RefreshDisplay() and Renderer::Render() so the library can render all active Views as needed.

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.
    renderer.RefreshDisplay(0);
 
    // Render all Views as needed
    renderer.Render();
 
    // Each View will render to a
    //   - Pixel-Buffer Surface (View::surface())
    //     or
    //   - GPU texture (View::render_target())
    // based on whether CPU or GPU rendering is used.
    //
    // You will need to display the image data here as needed.
  }
}

Inheritance diagram for Renderer:

Static Public Member Functions
static RefPtr< Renderer >	Create ()
	Create the core renderer singleton for the library.

Public Member Functions
virtual RefPtr< Session >	CreateSession (bool is_persistent, const String &name)=0
	Create a unique, named Session to store browsing data in (cookies, local storage, application cache, indexed db, etc).
virtual RefPtr< Session >	default_session ()=0
	Get the default Session.
virtual RefPtr< View >	CreateView (uint32_t width, uint32_t height, const ViewConfig &config, RefPtr< Session > session)=0
	Create a new View to load and display web pages in.
virtual void	Update ()=0
	Update timers and dispatch callbacks.
virtual void	RefreshDisplay (uint32_t display_id)=0
	Notify the renderer that a display has refreshed (you should call this after vsync).
virtual void	Render ()=0
	Render all active views to their respective render-targets/surfaces.
virtual void	RenderOnly (View **view_array, size_t view_array_len)=0
	Render a subset of views to their respective surfaces and render targets.
virtual void	PurgeMemory ()=0
	Attempt to release as much memory as possible.
virtual void	LogMemoryUsage ()=0
	Print detailed memory usage statistics to the log.
virtual bool	StartRemoteInspectorServer (const char *address, uint16_t port)=0
	Start the remote inspector server.
virtual void	SetGamepadDetails (uint32_t index, const String &id, uint32_t axis_count, uint32_t button_count)=0
	Describe the details of a gamepad, to be used with FireGamepadEvent and related events below.
virtual void	FireGamepadEvent (const GamepadEvent &evt)=0
	Fire a gamepad event (connection / disconnection).
virtual void	FireGamepadAxisEvent (const GamepadAxisEvent &evt)=0
	Fire a gamepad axis event (to be called when an axis value is changed).
virtual void	FireGamepadButtonEvent (const GamepadButtonEvent &evt)=0
	Fire a gamepad button event (to be called when a button value is changed).
Public Member Functions inherited from RefCounted
virtual void	AddRef () const =0
virtual void	Release () const =0
virtual int	ref_count () const =0

Protected Member Functions
virtual	~Renderer ()
Protected Member Functions inherited from RefCounted
virtual	~RefCounted ()

Constructor & Destructor Documentation

~Renderer()

virtual ~Renderer ( )

protectedvirtual

Member Function Documentation

Create()

static RefPtr< Renderer > Create ( )

static

Create the core renderer singleton for the library.

You should set up the Platform singleton before calling this function.

Note

You do not need to the call this if you're using the App class from AppCore.

Warning

You'll need to define a FontLoader and FileSystem within the Platform singleton or else this call will fail.

Warning

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

Returns

Renderer is ref-counted. This method returns a ref-pointer to a new instance, you should store it in a RefPtr to keep the instance alive.

CreateSession()

virtual RefPtr< Session > CreateSession ( bool is_persistent, const String & name )

pure virtual

Create a unique, named Session to store browsing data in (cookies, local storage, application cache, indexed db, etc).

Note

A default, persistent Session is already created for you. You only need to call this if you want to create private, in-memory session or use a separate session for each View.

Parameters

is_persistent	Whether or not to store the session on disk. Persistent sessions will be written to the path set in Config::cache_path
name	A unique name for this session, this will be used to generate a unique disk path for persistent sessions.

CreateView()

virtual RefPtr< View > CreateView ( uint32_t width, uint32_t height, const ViewConfig & config, RefPtr< Session > session )

pure virtual

Create a new View to load and display web pages in.

Views are similar to a tab in a browser. They have certain dimensions but are rendered to an offscreen surface and must be forwarded all input events.

Parameters

width	The initial width, in pixels.
height	The initial height, in pixels.
config	Configuration details for the View.
session	The session to store local data in. Pass a nullptr to use the default session.

Returns

Returns a ref-pointer to a new View instance.

default_session()

virtual RefPtr< Session > default_session ( )

pure virtual

Get the default Session.

This session is persistent (backed to disk) and has the name "default".

FireGamepadAxisEvent()

virtual void FireGamepadAxisEvent ( const GamepadAxisEvent & evt )

pure virtual

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

See also

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

FireGamepadButtonEvent()

virtual void FireGamepadButtonEvent ( const GamepadButtonEvent & evt )

pure virtual

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

See also

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

FireGamepadEvent()

virtual void FireGamepadEvent ( const GamepadEvent & evt )

pure virtual

Fire a gamepad event (connection / disconnection).

Note

The gamepad should first be described via SetGamepadDetails before calling this function.

See also

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

LogMemoryUsage()

virtual void LogMemoryUsage ( )

pure virtual

Print detailed memory usage statistics to the log.

See also

Platform::set_logger

PurgeMemory()

virtual void PurgeMemory ( )

pure virtual

Attempt to release as much memory as possible.

Warning

Don't call this from any callbacks or driver code.

RefreshDisplay()

virtual void RefreshDisplay ( uint32_t display_id )

pure virtual

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.

Render()

virtual void Render ( )

pure virtual

Render all active views to their respective render-targets/surfaces.

Note

Views are only repainted if they actually need painting.

RenderOnly()

virtual void RenderOnly ( View ** view_array, size_t view_array_len )

pure virtual

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

Parameters

view_array	A C-array containing a list of View pointers.
view_array_len	The length of the C-array.

SetGamepadDetails()

virtual void SetGamepadDetails ( uint32_t index, const String & id, uint32_t axis_count, uint32_t button_count )

pure virtual

Describe the details of a gamepad, to be used with FireGamepadEvent and related events below.

This can be called multiple times with the same index if the details change.

Parameters

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

StartRemoteInspectorServer()

virtual bool StartRemoteInspectorServer ( const char * address, uint16_t port )

pure virtual

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:

inspector://<ADDRESS>:<PORT>

Parameters

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.

Update()

virtual void Update ( )

pure virtual

Update timers and dispatch callbacks.

You should call this as often as you can from your application's run loop.

---

The documentation for this class was generated from the following file:

• Ultralight/Renderer.h