Config

#include <Ultralight/platform/Config.h>

Overview

Core configuration for the renderer.

These are various configuration options that can be used to customize the behavior of the library. These options can only be set once before creating the Renderer.

Setting the Config

You should create an instance of the Config struct, set its members, and then call Platform::set_config() before creating the Renderer at the beginning of your application's lifetime.

Example usage

Config config;
config.user_stylesheet = "body { background: purple; }";
 
Platform::instance().set_config(config);
// (Setup other Platform interfaces here.)
 
auto renderer = Renderer::Create();

Public Attributes
String	cache_path
	A writable OS file path to store persistent Session data in.
String	resource_path_prefix = "resources/"
	The relative path to the resources folder (loaded via the FileSystem API).
FaceWinding	face_winding = FaceWinding::CounterClockwise
	The winding order for front-facing triangles.
FontHinting	font_hinting = FontHinting::Normal
	The hinting algorithm to use when rendering fonts.
FontProfile	font_profile = FontProfile::Default
	The font-appearance preset providing default values for the text rendering knobs below (font_blend_mode, font_gamma, font_contrast, font_stem_darkening, font_embolden).
FontBlendMode	font_blend_mode = FontBlendMode::Profile
	How antialiased glyph edges are blended into the page.
double	font_gamma = 0.0
	The gamma to use when compositing font glyphs.
double	font_contrast = -1.0
	Additional contrast enhancement applied when compositing font glyphs.
double	font_stem_darkening = -1.0
	Stem-darkening strength for rendered text.
double	font_embolden = -1.0
	Extra stroke weight applied to glyph shapes, as a fraction of the font size (eg, 0.01 widens stems by roughly 1% of the em).
String	user_stylesheet
	Global user-defined CSS string (included before any CSS on the page).
bool	force_repaint = false
	Whether or not to continuously repaint any Views, regardless if they are dirty.
bool	enable_photon = true
	Whether or not GPU-accelerated Views render vector content (path fills and strokes) analytically (Photon) instead of tessellating it to triangles.
bool	enable_photon_text = true
	Whether or not text and color emoji also render analytically when enable_photon is enabled (see photon_text_min_px for the size cutoff).
uint32_t	photon_text_min_px = 16
	The minimum on-screen glyph size, in pixels, at which text renders analytically when enable_photon_text is enabled; smaller glyphs use the rasterized glyph atlas.
double	page_settle_delay = 0.1
	Additional delay (in seconds) on top of the engine's internal page-settled detection.
unsigned	page_settle_cycles = 5
	The number of consecutive idle samples the library requires before it declares a page settled.
double	page_settle_tick = 0.006
	How often (in seconds) the library samples a loading page for idleness.
double	recycle_delay = 0.5
	The interval (in seconds) at which the library automatically recycles internal caches and reclaims memory.
bool	idle_gc_enabled = true
	Whether the library automatically collects garbage and returns freed memory to the OS without embedder involvement.
double	idle_gc_idle_time = 2.0
	How long (in seconds) a page must be idle, with no user input, before automatic idle collection begins.
uint32_t	memory_cache_size = 256 * 1024 * 1024
	The maximum size of the library's memory cache in bytes.
uint32_t	page_cache_size = 0
	The number of pages to keep in the cache.
MemoryProfile	memory_profile = MemoryProfile::Balanced
	Memory vs.
uint32_t	override_ram_size = 0
	The system's physical RAM size in bytes.
uint32_t	min_large_heap_size = 0
	The minimum size of large VM heaps in JavaScriptCore.
uint32_t	min_small_heap_size = 1 * 1024 * 1024
	The minimum size of small VM heaps in JavaScriptCore.
uint32_t	max_heap_size = 0
	A soft target for the total JavaScriptCore heap size, in bytes.
uint32_t	num_renderer_threads = 0
	The number of threads to use in the Renderer (for parallel painting on the CPU, etc.).
double	max_update_time = 1.0 / 200.0
	The max amount of time (in seconds) to allow repeating timers to run during each call to Renderer::Update.
uint32_t	bitmap_alignment = 16
	The alignment (in bytes) of the BitmapSurface when using the CPU renderer.
EffectQuality	effect_quality = EffectQuality::Medium
	The quality of effects (blurs, CSS filters, SVG filters, etc.) to use when rendering.
bool	ignore_ssl_errors = false
	Whether to ignore SSL certificate errors when using the curl network backend.
bool	use_system_certificate_store = false
	Whether to validate TLS server certificates against the operating system's certificate store instead of the certificate bundle shipped with the application (resources/cacert.pem).
bool	paint_full_layers = false
	Whether to paint full layers when dirty instead of just the dirty subregion.
uint32_t	resource_sample_interval = 500
	The interval (in milliseconds) at which the library samples and emits resource counters (memory usage, VRAM, cache sizes, etc.) via the Profiler's EmitCounter() callback.
DiagnosticsConfig	diagnostics
	Diagnostics and logging options (developer mode, diagnostics levels, and the minimum log level).
MediaProfile	media_profile = MediaProfile::Balanced
	The memory-vs-performance profile for the HTML5 media subsystem.

Member Data Documentation

bitmap_alignment

uint32_t bitmap_alignment = 16

The alignment (in bytes) of the BitmapSurface when using the CPU renderer.

The underlying bitmap associated with each BitmapSurface will have row_bytes padded to reach this alignment.

Aligning the bitmap helps improve performance when using the CPU renderer. Determining the proper value to use depends on the CPU architecture and max SIMD instruction set used.

We generally target the 128-bit SSE2 instruction set across most PC platforms so '16' is a safe value to use.

You can set this to '0' to perform no padding (row_bytes will always be width * 4) at a slight cost to performance.

cache_path

String cache_path

A writable OS file path to store persistent Session data in.

This data may include cookies, cached network resources, indexed DB, etc.

Note

Files are only written to the path when using a persistent Session.

See also

Renderer::CreateSession()

diagnostics

DiagnosticsConfig diagnostics

Diagnostics and logging options (developer mode, diagnostics levels, and the minimum log level).

See also

DiagnosticsConfig

effect_quality

EffectQuality effect_quality = EffectQuality::Medium

The quality of effects (blurs, CSS filters, SVG filters, etc.) to use when rendering.

Applies to every rendering path (CSS element filters, canvas ctx.filter, and SVG filters) on both the CPU and GPU renderers. See EffectQuality for what each level trades.

(Default: EffectQuality::Medium)

enable_photon

bool enable_photon = true

Whether or not GPU-accelerated Views render vector content (path fills and strokes) analytically (Photon) instead of tessellating it to triangles.

Analytic rendering is resolution-independent: edges stay crisp under any zoom or transform.

Path rendering on CPU-rendered Views is unaffected. Disabling this also disables enable_photon_text.

(Default: true)

enable_photon_text

bool enable_photon_text = true

Whether or not text and color emoji also render analytically when enable_photon is enabled (see photon_text_min_px for the size cutoff).

Ignored when enable_photon is disabled.

This selects the text appearance for both renderers: CPU-rendered Views match the analytic look (unhinted outlines, fractional glyph placement) so output stays near-identical across renderers.

(Default: true)

face_winding

FaceWinding face_winding = FaceWinding::CounterClockwise

The winding order for front-facing triangles.

Precondition

Only used when GPU rendering is enabled for the View.

See also

FaceWinding

font_blend_mode

FontBlendMode font_blend_mode = FontBlendMode::Profile

How antialiased glyph edges are blended into the page.

Set to FontBlendMode::Profile to use the value from font_profile.

font_contrast

double font_contrast = -1.0

Additional contrast enhancement applied when compositing font glyphs.

Values above 0 thicken the midtones of antialiased glyph edges, increasing apparent text weight at every size. The useful range is 0.0 (none) to about 1.0.

Set below 0 to use the value from font_profile.

(Default: -1.0, meaning the profile's value; the Default profile uses 0.3)

font_embolden

double font_embolden = -1.0

Extra stroke weight applied to glyph shapes, as a fraction of the font size (eg, 0.01 widens stems by roughly 1% of the em).

Applies at every size and on both light and dark backgrounds; glyph advances and layout are unaffected.

Set below 0 to use the value from font_profile.

(Default: -1.0, meaning the profile's value)

font_gamma

double font_gamma = 0.0

The gamma to use when compositing font glyphs.

Lower values render text heavier, higher values render it lighter with more edge contrast (Adobe and Apple prefer 1.8).

Set to 0 to use the value from font_profile.

(Default: 0, meaning the profile's value; the Default profile uses 2.2)

font_hinting

FontHinting font_hinting = FontHinting::Normal

The hinting algorithm to use when rendering fonts.

Leave this at FontHinting::Normal to use the hinting from font_profile. Any other value pins the hinting and overrides the profile.

See also

FontHinting

font_profile

FontProfile font_profile = FontProfile::Default

The font-appearance preset providing default values for the text rendering knobs below (font_blend_mode, font_gamma, font_contrast, font_stem_darkening, font_embolden).

Knobs you set explicitly override the preset's values, so you can start from a preset and adjust individual aspects.

(Default: FontProfile::Default)

font_stem_darkening

double font_stem_darkening = -1.0

Stem-darkening strength for rendered text.

Boosts the coverage of antialiased glyph pixels so thin stems keep their apparent weight on light backgrounds; each preset shapes how the boost varies with glyph size. Text on dark backgrounds is unaffected.

Set below 0 to use the value from font_profile.

(Default: -1.0, meaning the profile's value)

force_repaint

bool force_repaint = false

Whether or not to continuously repaint any Views, regardless if they are dirty.

This is mainly used to diagnose painting/shader issues and profile performance.

idle_gc_enabled

bool idle_gc_enabled = true

Whether the library automatically collects garbage and returns freed memory to the OS without embedder involvement.

When a page builds up a large JavaScript heap and then goes quiet, that memory would otherwise stay resident until the next burst of activity or an explicit Renderer::Recycle / Renderer::PurgeMemory. With this enabled, the library collects on its own and pushes the freed memory back to the OS, so the process footprint drifts back down after heavy content:

• While the application is idle (no user input, little render activity), collection runs on a paced schedule without blocking the render thread.
• While the application is busy (for example a game rendering every frame), collection still runs concurrently whenever the heap has grown well past its last collected size, so a HUD that allocated heavily and then stopped does not hold its peak footprint. How eagerly this triggers follows memory_profile.

Reclamation only happens while Renderer::Update() is being pumped. An application that stops calling Renderer::Update() while idle gets no automatic reclamation; call Renderer::Recycle() / Renderer::PurgeMemory() explicitly in that case.

Set this to false if your application manages collection itself; behavior then matches earlier releases.

(Default: true)

idle_gc_idle_time

double idle_gc_idle_time = 2.0

How long (in seconds) a page must be idle, with no user input, before automatic idle collection begins.

Lower values reclaim sooner after the user stops interacting; higher values wait longer before assuming the page is idle. Only used when idle_gc_enabled is true.

(Default: 2.0)

ignore_ssl_errors

bool ignore_ssl_errors = false

Whether to ignore SSL certificate errors when using the curl network backend.

When set to true, SSL certificate verification will be disabled, allowing connections to servers with self-signed or invalid certificates. This should only be used for development/testing purposes.

Warning

This option reduces security and should never be enabled in production.

max_heap_size

uint32_t max_heap_size = 0

A soft target for the total JavaScriptCore heap size, in bytes.

This is not a hard limit: the heap may grow beyond this target. When it does, the garbage collector treats the heap as under memory pressure and reclaims more aggressively to bring it back toward the target.

Set to 0 (the default) to derive this value from memory_profile.

max_update_time

double max_update_time = 1.0 / 200.0

The max amount of time (in seconds) to allow repeating timers to run during each call to Renderer::Update.

The library will attempt to throttle timers if this time budget is exceeded.

media_profile

MediaProfile media_profile = MediaProfile::Balanced

The memory-vs-performance profile for the HTML5 media subsystem.

Picks a tradeoff between peak memory per media element and playback smoothness / seek responsiveness. The value is read once when each media element starts loading and stays fixed for that element's lifetime; later changes to Config::media_profile apply only to subsequently-loaded elements.

See also

MediaProfile

memory_cache_size

uint32_t memory_cache_size = 256 * 1024 * 1024

The maximum size of the library's memory cache in bytes.

(Default: 256 MiB)

Note

This is used for caching decoded images, compiled JavaScript, etc. Increasing this may improve performance for resource-heavy applications (at the cost of higher memory usage).

memory_profile

MemoryProfile memory_profile = MemoryProfile::Balanced

Memory vs.

performance tuning for the renderer's HTML / JavaScript engine heaps. See the MemoryProfile enumerator descriptions for the effect of each profile.

Read when the Renderer is created and by each View at its creation. (Default: Balanced)

min_large_heap_size

uint32_t min_large_heap_size = 0

The minimum size of large VM heaps in JavaScriptCore.

Set this to a lower value to make these heaps start with a smaller initial value.

Set to 0 (the default) to derive this value from memory_profile.

min_small_heap_size

uint32_t min_small_heap_size = 1 * 1024 * 1024

The minimum size of small VM heaps in JavaScriptCore.

Set this to a lower value to make these heaps start with a smaller initial value.

num_renderer_threads

uint32_t num_renderer_threads = 0

The number of threads to use in the Renderer (for parallel painting on the CPU, etc.).

You can set this to a certain number to limit the number of threads to spawn.

Note

If this value is 0, the number of threads will be determined at runtime using the following formula:

max(PhysicalProcessorCount() - 1, 1)

override_ram_size

uint32_t override_ram_size = 0

The system's physical RAM size in bytes.

JavaScriptCore tries to detect the system's physical RAM size to set reasonable allocation limits. Set this to anything other than 0 to override the detected value. Size is in bytes.

This can be used to force JavaScriptCore to be more conservative with its allocation strategy (at the cost of some performance).

page_cache_size

uint32_t page_cache_size = 0

The number of pages to keep in the cache.

(Default: 0, none)

Note

Safari typically caches about 5 pages and maintains an on-disk cache to support typical web-browsing activities.

If you increase this, you should probably increase the memory cache size as well.

page_settle_cycles

unsigned page_settle_cycles = 5

The number of consecutive idle samples the library requires before it declares a page settled.

(Default: 5)

Together with page_settle_tick this sets the shortest time a page can take to settle (page_settle_cycles * page_settle_tick). Lower it to settle sooner, at the cost of tolerance for late layout or paint.

page_settle_delay

double page_settle_delay = 0.1

Additional delay (in seconds) on top of the engine's internal page-settled detection.

(Default: 0.1)

Increase this if you want a little more assurance that the page has fully settled (animations finished, late-arriving network activity complete) before View::is_settled() flips and LoadListener::OnPageSettled() fires, at the cost of additional wait time.

See also

LoadListener::OnPageSettled()

page_settle_tick

double page_settle_tick = 0.006

How often (in seconds) the library samples a loading page for idleness.

(Default: 0.006)

See also

page_settle_cycles

paint_full_layers

bool paint_full_layers = false

Whether to paint full layers when dirty instead of just the dirty subregion.

When set to true and a layer has dirty regions, the full layer will be repainted instead of just the dirty rectangle intersection. This can be useful for debugging rendering issues or when dirty region tracking is causing artifacts.

Note

Enabling this will impact performance as entire layers are redrawn instead of just the changed portions.

photon_text_min_px

uint32_t photon_text_min_px = 16

The minimum on-screen glyph size, in pixels, at which text renders analytically when enable_photon_text is enabled; smaller glyphs use the rasterized glyph atlas.

Set to 0 to render all text analytically.

(Default: 16)

recycle_delay

double recycle_delay = 0.5

The interval (in seconds) at which the library automatically recycles internal caches and reclaims memory.

The library performs this lightweight recycle for you from inside Renderer::Update() / Renderer::Render(). It is cheap enough to be invisible at typical frame rates, and letting the library drive it on this timer is the recommended approach.

Set to 0 to disable the automatic recycler entirely, for applications that prefer to call Renderer::Recycle() on their own schedule.

(Default: 0.5)

resource_path_prefix

String resource_path_prefix = "resources/"

The relative path to the resources folder (loaded via the FileSystem API).

The library loads certain resources (SSL certs, ICU data, etc.) from the FileSystem API during runtime (eg, file:///resources/cacert.pem).

You can customize the relative file path to the resources folder by modifying this setting.

See also

FileSystem

resource_sample_interval

uint32_t resource_sample_interval = 500

The interval (in milliseconds) at which the library samples and emits resource counters (memory usage, VRAM, cache sizes, etc.) via the Profiler's EmitCounter() callback.

Set to 0 to disable resource counter sampling entirely – scopes and events are unaffected.

Default: 500ms.

use_system_certificate_store

bool use_system_certificate_store = false

Whether to validate TLS server certificates against the operating system's certificate store instead of the certificate bundle shipped with the application (resources/cacert.pem).

When false (the default), HTTPS connections are verified using the bundled certificate authority list, giving identical behavior on every platform. When true, certificates trusted by the host operating system (including enterprise or user-installed roots) are honored and the bundled list is not used.

Currently honored on Windows. On platforms where the OS trust store is not yet supported, this option is ignored and the bundled list is used.

user_stylesheet

String user_stylesheet

Global user-defined CSS string (included before any CSS on the page).

You can use this to override default styles for various elements on the page.

Note

This is an actual string of CSS, not a file path.

---

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

• Ultralight/platform/Config.h