ultralight::Renderer Class Reference

#include <Ultralight/Renderer.h>

Details

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.

Initializing the Renderer

To initialize the library, you should set up the Platform singleton and call Renderer::Create.

Example initialization 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::Render() so the library can render all active Views as needed.

Example rendering code

void displayFrame()
{
    // 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.
  }
}

Note

The App class creates and manages its own Renderer (optional API in AppCore, available on desktop OS only).

Warning

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

Inheritance diagram for ultralight::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	Render ()=0
	Render all active views to their respective surfaces and render targets.
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 ultralight::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 ultralight::RefCounted
virtual	~RefCounted ()

Constructor & Destructor Documentation

~Renderer()

virtual ultralight::Renderer::~Renderer ( )

protectedvirtual

Member Function Documentation

Create()

static RefPtr< Renderer > ultralight::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 > ultralight::Renderer::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 > ultralight::Renderer::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 > ultralight::Renderer::default_session ( )

pure virtual

Get the default Session.

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

FireGamepadAxisEvent()

virtual void ultralight::Renderer::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 ultralight::Renderer::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 ultralight::Renderer::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 ultralight::Renderer::LogMemoryUsage ( )

pure virtual

Print detailed memory usage statistics to the log.

See also

Platform::set_logger

PurgeMemory()

virtual void ultralight::Renderer::PurgeMemory ( )

pure virtual

Attempt to release as much memory as possible.

Warning

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

Render()

virtual void ultralight::Renderer::Render ( )

pure virtual

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

You should call this once per frame (usually in synchrony with the monitor's refresh rate).

Note

Views are only rendered if they actually need rendering.

RenderOnly()

virtual void ultralight::Renderer::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 ultralight::Renderer::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 ultralight::Renderer::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>

Returns

Returns whether the server started successfully or not.

Update()

virtual void ultralight::Renderer::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