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.
double	font_gamma = 1.8
	The gamma to use when compositing font glyphs.
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.
double	animation_timer_delay = 1.0 / 60.0
	The delay (in seconds) between every tick of a CSS animation.
double	scroll_timer_delay = 1.0 / 60.0
	The delay (in seconds) between every tick of a smooth scroll animation.
double	recycle_delay = 4.0
	The delay (in seconds) between every call to the recycler.
uint32_t	memory_cache_size = 64 * 1024 * 1024
	The size of WebCore's memory cache in bytes.
uint32_t	page_cache_size = 0
	The number of pages to keep in the cache.
uint32_t	override_ram_size = 0
	The system's physical RAM size in bytes.
uint32_t	min_large_heap_size = 32 * 1024 * 1024
	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	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.

Member Data Documentation

animation_timer_delay

double animation_timer_delay = 1.0 / 60.0

The delay (in seconds) between every tick of a CSS animation.

(Default: 60 FPS)

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()

effect_quality

EffectQuality effect_quality = EffectQuality::Medium

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

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_gamma

double font_gamma = 1.8

The gamma to use when compositing font glyphs.

You can change this value to adjust font contrast (Adobe and Apple prefer 1.8).

font_hinting

FontHinting font_hinting = FontHinting::Normal

The hinting algorithm to use when rendering fonts.

See also

FontHinting

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.

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.

memory_cache_size

uint32_t memory_cache_size = 64 * 1024 * 1024

The size of WebCore's memory cache in bytes.

Note

You should increase this if you anticipate handling pages with large resources, Safari typically uses 128+ MiB for its cache.

min_large_heap_size

uint32_t min_large_heap_size = 32 * 1024 * 1024

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.

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.

recycle_delay

double recycle_delay = 4.0

The delay (in seconds) between every call to the recycler.

The library attempts to reclaim excess memory during calls to the internal recycler. You can change how often this is run by modifying this value.

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

scroll_timer_delay

double scroll_timer_delay = 1.0 / 60.0

The delay (in seconds) between every tick of a smooth scroll animation.

(Default: 60 FPS)

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