Details

Global config for Ultralight.

This can be used to configure the library when calling ulCreateRenderer() or ulCreateApp().

Functions
ULExport ULConfig	ulCreateConfig ()
	Create config with default values (see <Ultralight/platform/Config.h>).

ULExport void	ulDestroyConfig (ULConfig config)
	Destroy config.

ULExport void	ulConfigSetCachePath (ULConfig config, ULString cache_path)
	A writable OS file path to store persistent Session data in.

ULExport void	ulConfigSetResourcePathPrefix (ULConfig config, ULString resource_path_prefix)
	The relative path to the resources folder (loaded via the FileSystem API).

ULExport void	ulConfigSetFaceWinding (ULConfig config, ULFaceWinding winding)
	The winding order for front-facing triangles.

ULExport void	ulConfigSetFontHinting (ULConfig config, ULFontHinting font_hinting)
	The hinting algorithm to use when rendering fonts.

ULExport void	ulConfigSetFontGamma (ULConfig config, double font_gamma)
	The gamma to use when compositing font glyphs, change this value to adjust contrast (Adobe and Apple prefer 1.8, others may prefer 2.2).

ULExport void	ulConfigSetUserStylesheet (ULConfig config, ULString css_string)
	Global user-defined CSS string (included before any CSS on the page).

ULExport void	ulConfigSetForceRepaint (ULConfig config, bool enabled)
	Whether or not to continuously repaint any Views, regardless if they are dirty.

ULExport void	ulConfigSetAnimationTimerDelay (ULConfig config, double delay)
	The delay (in seconds) between every tick of a CSS animation.

ULExport void	ulConfigSetScrollTimerDelay (ULConfig config, double delay)
	The delay (in seconds) between every tick of a smooth scroll animation.

ULExport void	ulConfigSetRecycleDelay (ULConfig config, double delay)
	The delay (in seconds) between every call to the recycler.

ULExport void	ulConfigSetMemoryCacheSize (ULConfig config, unsigned int size)
	The size of WebCore's memory cache in bytes.

ULExport void	ulConfigSetPageCacheSize (ULConfig config, unsigned int size)
	The number of pages to keep in the cache.

ULExport void	ulConfigSetOverrideRAMSize (ULConfig config, unsigned int size)
	The system's physical RAM size in bytes.

ULExport void	ulConfigSetMinLargeHeapSize (ULConfig config, unsigned int size)
	The minimum size of large VM heaps in JavaScriptCore.

ULExport void	ulConfigSetMinSmallHeapSize (ULConfig config, unsigned int size)
	The minimum size of small VM heaps in JavaScriptCore.

ULExport void	ulConfigSetNumRendererThreads (ULConfig config, unsigned int num_renderer_threads)
	The number of threads to use in the Renderer (for parallel painting on the CPU, etc.).

ULExport void	ulConfigSetMaxUpdateTime (ULConfig config, double max_update_time)
	The max amount of time (in seconds) to allow repeating timers to run during each call to Renderer::Update.

ULExport void	ulConfigSetBitmapAlignment (ULConfig config, unsigned int bitmap_alignment)
	The alignment (in bytes) of the BitmapSurface when using the CPU renderer.

Function Documentation

◆ ulConfigSetAnimationTimerDelay()

ULExport void ulConfigSetAnimationTimerDelay	(	ULConfig	config,
		double	delay
	)

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

(Default = 1.0 / 60.0)

◆ ulConfigSetBitmapAlignment()

ULExport void ulConfigSetBitmapAlignment	(	ULConfig	config,
		unsigned int	bitmap_alignment
	)

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.

(Default = 16)

◆ ulConfigSetCachePath()

ULExport void ulConfigSetCachePath	(	ULConfig	config,
		ULString	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.

◆ ulConfigSetFaceWinding()

ULExport void ulConfigSetFaceWinding	(	ULConfig	config,
		ULFaceWinding	winding
	)

The winding order for front-facing triangles.

Precondition: Only used when GPU rendering is enabled for the View.

(Default = kFaceWinding_CounterClockwise)

◆ ulConfigSetFontGamma()

ULExport void ulConfigSetFontGamma	(	ULConfig	config,
		double	font_gamma
	)

The gamma to use when compositing font glyphs, change this value to adjust contrast (Adobe and Apple prefer 1.8, others may prefer 2.2).

(Default = 1.8)

◆ ulConfigSetFontHinting()

ULExport void ulConfigSetFontHinting	(	ULConfig	config,
		ULFontHinting	font_hinting
	)

The hinting algorithm to use when rendering fonts.

(Default = kFontHinting_Normal)

See also: ULFontHinting

◆ ulConfigSetForceRepaint()

ULExport void ulConfigSetForceRepaint	(	ULConfig	config,
		bool	enabled
	)

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.

(Default = False)

◆ ulConfigSetMaxUpdateTime()

ULExport void ulConfigSetMaxUpdateTime	(	ULConfig	config,
		double	max_update_time
	)

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.

(Default = 1.0 / 200.0)

◆ ulConfigSetMemoryCacheSize()

ULExport void ulConfigSetMemoryCacheSize	(	ULConfig	config,
		unsigned int	size
	)

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.

(Default = 64 * 1024 * 1024)

◆ ulConfigSetMinLargeHeapSize()

ULExport void ulConfigSetMinLargeHeapSize	(	ULConfig	config,
		unsigned int	size
	)

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.

(Default = 32 * 1024 * 1024)

◆ ulConfigSetMinSmallHeapSize()

ULExport void ulConfigSetMinSmallHeapSize	(	ULConfig	config,
		unsigned int	size
	)

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.

(Default = 1 * 1024 * 1024)

◆ ulConfigSetNumRendererThreads()

ULExport void ulConfigSetNumRendererThreads	(	ULConfig	config,
		unsigned int	num_renderer_threads
	)

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)

◆ ulConfigSetOverrideRAMSize()

ULExport void ulConfigSetOverrideRAMSize	(	ULConfig	config,
		unsigned int	size
	)

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

◆ ulConfigSetPageCacheSize()

ULExport void ulConfigSetPageCacheSize	(	ULConfig	config,
		unsigned int	size
	)

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.

(Default = 0)

◆ ulConfigSetRecycleDelay()

ULExport void ulConfigSetRecycleDelay	(	ULConfig	config,
		double	delay
	)

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.

(Default = 4.0)

◆ ulConfigSetResourcePathPrefix()

ULExport void ulConfigSetResourcePathPrefix	(	ULConfig	config,
		ULString	resource_path_prefix
	)

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.

(Default = "resources/")

◆ ulConfigSetScrollTimerDelay()

ULExport void ulConfigSetScrollTimerDelay	(	ULConfig	config,
		double	delay
	)

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

(Default = 1.0 / 60.0)

◆ ulConfigSetUserStylesheet()

ULExport void ulConfigSetUserStylesheet	(	ULConfig	config,
		ULString	css_string
	)

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.

◆ ulCreateConfig()

ULExport ULConfig ulCreateConfig ( )

Create config with default values (see <Ultralight/platform/Config.h>).

◆ ulDestroyConfig()

ULExport void ulDestroyConfig ( ULConfig config )

Destroy config.