Creating the Renderer

Configure the library and create the Renderer to manage views, sessions, and rendering.

The Renderer is the central singleton that creates views, manages sessions, and runs web pages inside your app.

It coordinates page loading, JavaScript execution, and View painting across the entire library.

📘 Using AppCore

When using AppCore, the Renderer is automatically created and managed for you in App::Create() (you can still customize the Config, however)— see App Lifecycle and Settings.

#Setup Order

Before creating views or rendering frames, you must configure the library and initialize the platform singleton. Steps 1 and 2 can run in either order, but both must finish before calling Renderer::Create().

#Creating the Renderer Instance

Call Renderer::Create() after registering platform handlers, storing the instance in a RefPtr to keep it alive (see Setting Up the Platform):

RefPtr<Renderer> renderer;

void CreateRenderer() {
  ///
  /// Register the platform handlers first.
  ///
  InitPlatform();

  renderer = Renderer::Create();
}

🚧 Create One Renderer Per Application

You should create only one Renderer during the lifetime of your program. Initialize the instance once at startup and keep it alive until shutdown.

#The Renderer's Thread

The thread that calls Renderer::Create() becomes the Renderer's thread. Tasks posted with Renderer::PostTask() run on the Renderer's thread during a later call to Renderer::Update().

🚧 Thread Restrictions

You must make all Renderer and View calls on the Renderer's thread only. Both Renderer::PostTask() and Renderer::PostDelayedTask() are safe to call from any thread to hand work to the Renderer's thread— see Integrating into a Game Engine.

#Configuring the Library

The Config struct sets library-wide options, while per-view options use ViewConfig— see Creating Views.

Populate the struct and pass it to Platform::instance().set_config() before calling Renderer::Create(). The renderer reads these settings when it is created.

The library copies the configuration immediately, so allocating a Config on the stack is fine.

Set configuration values on the platform singleton before creating the renderer (the C version sits in the tab below):

void Init() {
  InitPlatform();

  ///
  /// Let's set some custom global CSS to make our background
  /// purple by default.
  ///
  Config config;
  config.user_stylesheet = "body { background: purple; }";

  ///
  /// Store persistent Session data in a writable folder.
  ///
  config.cache_path = "./ultralight_cache/";

  ///
  /// Pass our configuration to the Platform singleton, then create
  /// the Renderer.
  ///
  Platform::instance().set_config(config);
  renderer = Renderer::Create();
}

#include <Ultralight/CAPI.h>

static ULRenderer renderer = NULL;

void Init(void) {
  ULConfig config = ulCreateConfig();

  ///
  /// Let's set some custom global CSS to make our background
  /// purple by default.
  ///
  ULString css = ulCreateString("body { background: purple; }");
  ulConfigSetUserStylesheet(config, css);
  ulDestroyString(css);

  ///
  /// Store persistent Session data in a writable folder.
  ///
  ULString cache_path = ulCreateString("./ultralight_cache/");
  ulConfigSetCachePath(config, cache_path);
  ulDestroyString(cache_path);

  ///
  /// Pass our configuration to the library when creating the Renderer
  /// (after the platform handlers are set up), then destroy it.
  ///
  renderer = ulCreateRenderer(config);
  ulDestroyConfig(config);
}

#Common Options

Most applications configure only a few common settings before creating the renderer.

#Other Options

The remaining options tune specific subsystems, grouped by purpose below. The linked guide for each group covers its settings in detail, and the Config API reference lists every field.

#Text Rendering

Configure font appearance, glyph hinting, and vector text rendering. See Text Rendering and Fonts for font configuration details.

#Memory and Reclamation

Tune cache limits, heap sizing, and automatic garbage collection. See Managing Memory for memory management strategies.

#Page Settling

Control how long the engine waits before declaring a loaded page settled. See Handling View Events for listening to load and settle events.

#Threads and Timing

Configure worker thread counts, timer update budgets, and CPU bitmap row alignment.

#GPU and Debugging

Configure GPU geometry winding and diagnostic painting modes. See Implementing a GPUDriver for custom rendering backends.

#Network Security

Manage certificate verification for network requests.

#Diagnostics and Profiling

Configure logging verbosity and runtime metrics sampling.

#Media (Pro Edition and Higher)

Tune media decoding and buffering behavior. See Media and Audio for media playback options.

#The Default Session

Renderer::Create() automatically creates a persistent session named "default". Views created without a session use it— see Sessions and Site Data to configure custom storage locations, in-memory sessions, or session sharing.