docs
Loading...
Searching...
No Matches
Config.h
Go to the documentation of this file.
1///
2/// Copyright (C) 2026 Ultralight, Inc. All rights reserved.
3/// A license is required for commercial use. https://ultralig.ht
4///
5#pragma once
8#include <Ultralight/String.h>
10
11// X11's headers define None as a macro; FontHinting::None needs the plain identifier.
12#pragma push_macro("None")
13#undef None
14
15namespace ultralight {
16
17///
18/// The winding order for front-facing triangles. (Only used when the GPU renderer is used)
19///
20enum class FaceWinding : uint8_t {
21 ///
22 /// Clockwise Winding (Direct3D, etc.)
23 ///
25
26 ///
27 /// Counter-Clockwise Winding (OpenGL, etc.)
28 ///
30};
31
32///
33/// The font hinting algorithm to use when rendering glyphs.
34///
35/// @see Config::font_hinting
36///
37enum class FontHinting : uint8_t {
38 ///
39 /// Lighter hinting algorithm-- glyphs are slightly fuzzier but better resemble their original
40 /// shape. This is achieved by snapping glyphs to the pixel grid only vertically which better
41 /// preserves inter-glyph spacing.
42 ///
44
45 ///
46 /// Let the font profile choose-- Config::font_profile picks the hinting that suits its
47 /// appearance, which for every profile but FontProfile::Light means no hinting (Light keeps
48 /// light, vertical-only hinting).
49 ///
51
52 ///
53 /// Strongest hinting algorithm-- outputs only black/white glyphs. The result is usually
54 /// unpleasant if the font has no hints for this type of rendering.
55 ///
56 /// This reaches only the text sizes that are hinted at all (see Config::font_hinting)-- larger
57 /// text keeps antialiased edges.
58 ///
60
61 ///
62 /// No hinting is performed-- fonts may be blurry at smaller font sizes.
63 ///
65};
66
67///
68/// The font-appearance preset that provides default values for the text rendering knobs
69/// (Config::font_blend_mode, Config::font_gamma, Config::font_contrast,
70/// Config::font_stem_darkening, Config::font_embolden, and the hinting behind
71/// FontHinting::Normal). Knobs you set explicitly override the preset's values.
72///
73/// @see Config::font_profile
74///
75enum class FontProfile : uint8_t {
76 ///
77 /// The standard appearance-- currently the same as WindowsLike.
78 ///
80
81 ///
82 /// Text with the weight and sharpness of Safari and other macOS applications.
83 ///
85
86 ///
87 /// Text with the crisp, moderate weight of mainstream browsers on Windows.
88 ///
90
91 ///
92 /// No weight compensation at all-- the thinnest appearance.
93 ///
95};
96
97///
98/// How antialiased glyph edges are blended into the page.
99///
100/// @see Config::font_blend_mode
101///
102enum class FontBlendMode : uint8_t {
103 ///
104 /// Use the value from the font profile.
105 ///
107
108 ///
109 /// Gamma-corrected blending-- edges read lighter with more contrast (how browsers on Windows
110 /// composite text).
111 ///
113
114 ///
115 /// Blend in sRGB space-- edges keep their full coverage (how macOS composites text).
116 ///
118};
119
120///
121/// How the library renders pixel fonts.
122///
123/// A pixel font is a monochrome bitmap font, or an outline font the library detects as drawn
124/// on a pixel grid. Color fonts are never pixel fonts.
125///
126/// Pages can override this per element with the `-ul-font-rendering` CSS property. The value
127/// `auto` follows this setting, while `smooth` and `pixelated` take precedence over it.
128///
129/// @note Using `pixelated` on a monochrome font that isn't a pixel font draws it aliased (hard
130/// edges, no antialiasing) on whole pixels. Color fonts ignore the property.
131///
132/// @see Config::pixel_font_rendering
133///
134enum class PixelFontRendering : uint8_t {
135 ///
136 /// Render pixel fonts like other text-- edges stay antialiased with fractional glyph placement.
137 /// Bitmap glyphs scale smoothly to the font size.
138 ///
140
141 ///
142 /// Keep pixel fonts crisp-- hard pixel edges with every glyph on a whole device pixel.
143 ///
144 /// At any size, the font's pixels are enlarged by repeating device pixels. By default the used
145 /// size moves to a whole multiple of the font's design size (see
146 /// Config::snap_pixel_font_size); with that off, at a size that isn't a whole multiple, some
147 /// font pixels draw one device pixel wider than others.
148 ///
149 /// Glyph advances, letter-spacing and word-spacing round to whole device pixels. Because of
150 /// this, a line's width at fractional device scales can differ slightly from other browsers.
151 ///
152 /// @note An outline pixel font below its design size renders like other text.
153 ///
155};
156
157///
158/// The quality level for rendering effects (CSS filters, shadows, blurs, etc.).
159///
160/// The level trades the fidelity of large blurs and shadows for speed: lower levels process them
161/// at more aggressively reduced resolutions and with a tighter blur falloff.
162///
163/// @see Config::effect_quality
164///
165enum class EffectQuality : uint8_t {
166 ///
167 /// Fastest effect quality. Large blurs and shadows render at heavily reduced resolution and
168 /// with a truncated falloff, so they appear visibly coarser and tighter than at higher levels.
169 ///
171
172 ///
173 /// Default effect quality-- strikes a good balance between quality and performance.
174 ///
176
177 ///
178 /// Highest effect quality-- favors quality over performance.
179 ///
180 /// Only software (CPU) rendering processes very large blurs at higher working resolutions than
181 /// Medium; on GPU-accelerated views blur quality is equivalent to Medium.
182 ///
184};
185
186///
187/// Memory vs. performance tuning for the renderer's HTML / JavaScript
188/// engine heaps.
189///
190/// The profile governs how aggressively the library returns freed heap
191/// memory to the operating system, how it balances allocation speed
192/// against memory footprint, and how much backing-store memory the
193/// compositor keeps per View. The effect of each profile is described on
194/// the enumerator below.
195///
196/// The profile is read when the Renderer is created and again by each
197/// View at its creation; changing Config::memory_profile afterward
198/// affects only Views created later.
199///
200/// @see Config::memory_profile
201///
202enum class MemoryProfile : uint8_t {
203 ///
204 /// Sensible default. Freed memory is returned to the OS on a moderate
205 /// cadence and allocation favors speed. Recommended unless you have a
206 /// specific reason to choose otherwise.
207 ///
209
210 ///
211 /// Optimize for low memory footprint at some cost to peak throughput.
212 /// Freed memory is returned to the OS promptly, allocations are packed
213 /// more densely, and the JavaScript engine collects garbage more
214 /// eagerly. Recommended for resource-constrained targets and
215 /// long-running pages where footprint matters more than raw speed.
216 ///
218
219 ///
220 /// Optimize for peak throughput at the cost of a higher steady-state
221 /// memory footprint. Freed memory is held longer for reuse and the
222 /// JavaScript engine collects garbage less often. Recommended when
223 /// performance is paramount and the host has plenty of RAM to spare.
224 ///
226};
227
228#if UL_HAS(MEDIA)
229
230///
231/// Memory vs. performance tuning for HTML5 `<video>` and `<audio>`.
232///
233/// Pick the profile that matches your target's resource envelope; the
234/// engine will tune internal media-pipeline sizing accordingly. The
235/// effect of each profile is described on the enumerator below.
236///
237/// The profile is read once when each media element starts loading.
238/// Changing Config::media_profile after a `<video>` or `<audio>` element
239/// is already loading does not affect that element; subsequent elements
240/// will pick up the new profile.
241///
242/// @see Config::media_profile
243///
244/// @note The library plays WebM files (`video/webm` and `audio/webm`) with VP9 video and Opus
245/// audio. Other containers and codecs aren't supported.
246///
247enum class MediaProfile : uint8_t {
248 ///
249 /// Sensible default. Smooth playback and responsive seeking with
250 /// bounded memory growth as more media elements load. Recommended
251 /// starting point unless you have a specific reason to choose
252 /// otherwise.
253 ///
255
256 ///
257 /// Optimise for low memory footprint at the cost of some smoothness
258 /// and seek responsiveness. Recommended for resource-constrained
259 /// targets and for long-running pages that may host many media
260 /// elements simultaneously.
261 ///
263
264 ///
265 /// Optimise for the smoothest playback and snappiest seeking, at the
266 /// cost of higher peak memory per media element. Recommended when
267 /// playback quality is paramount and the host has plenty of RAM to
268 /// spare.
269 ///
271};
272
273#endif // UL_HAS(MEDIA)
274
275///
276/// Diagnostics and logging options.
277///
278/// @see Config::diagnostics
279///
281 ///
282 /// Whether or not the library runs in developer mode.
283 ///
284 /// Developer mode turns the DiagnosticsLevel::Auto levels below into DiagnosticsLevel::Warn,
285 /// and lets the diagnostics environment variables (`UL_JS_DIAGNOSTICS`, `UL_DOM_DIAGNOSTICS`)
286 /// override them. You should turn it on in your development builds and leave it off in the
287 /// builds you ship (a release library ignores those variables when developer mode is off, so a
288 /// shipped app's behavior can't be changed from its environment). Each variable takes `off`,
289 /// `warn`, or `strict`.
290 ///
291 bool developer_mode = false;
292
293 ///
294 /// The diagnostics level for JavaScript APIs that leave their own level at
295 /// DiagnosticsLevel::Auto.
296 ///
298
299 ///
300 /// The diagnostics level for the DOM API and data bindings.
301 ///
303
304 ///
305 /// The least severe level the library sends to the Logger (less severe messages are dropped).
306 ///
307 /// Diagnostics warnings are sent at LogLevel::Warning, so a minimum of LogLevel::Error or
308 /// LogLevel::Fatal hides them.
309 ///
311};
312
313///
314/// Core configuration for the renderer.
315///
316/// These are various configuration options that can be used to customize the behavior of the
317/// library. These options can only be set once before creating the Renderer.
318///
319/// ## Setting the Config
320///
321/// You should create an instance of the Config struct, set its members, and then call
322/// Platform::set_config() before creating the Renderer at the beginning of your
323/// application's lifetime.
324///
325/// @par Example usage
326/// ```
327/// Config config;
328/// config.user_stylesheet = "body { background: purple; }";
329///
330/// Platform::instance().set_config(config);
331/// // (Setup other Platform interfaces here.)
332///
333/// auto renderer = Renderer::Create();
334/// ```
335///
337 ///
338 /// A writable OS file path to store persistent Session data in.
339 ///
340 /// This data may include cookies, cached network resources, indexed DB, etc.
341 ///
342 /// @note Files are only written to the path when using a persistent Session.
343 ///
344 /// @see Renderer::CreateSession()
345 ///
347
348 ///
349 /// The relative path to the resources folder (loaded via the FileSystem API).
350 ///
351 /// The library loads certain resources (SSL certs, ICU data, etc.) from the FileSystem API
352 /// during runtime (eg, `file:///resources/cacert.pem`).
353 ///
354 /// You can customize the relative file path to the resources folder by modifying this setting.
355 ///
356 /// @see FileSystem
357 ///
359
360 ///
361 /// The winding order for front-facing triangles.
362 ///
363 /// @pre Only used when GPU rendering is enabled for the View.
364 ///
365 /// @see FaceWinding
366 ///
368
369 ///
370 /// The hinting algorithm to use when rendering fonts.
371 ///
372 /// Leave this at FontHinting::Normal to take the hinting from font_profile. Any other value
373 /// overrides the profile.
374 ///
375 /// When enable_photon_text is enabled (the default), hinting applies only to upright text (no
376 /// rotation or skew) smaller than photon_text_min_px. Larger or rotated text renders from
377 /// unhinted outlines. When enable_photon_text is disabled, hinting applies to upright text of
378 /// every size.
379 ///
380 /// @note Pixel fonts rendered as pixel art (PixelFontRendering::Pixelated) ignore this setting.
381 ///
382 /// @see FontHinting
383 ///
385
386 ///
387 /// The font-appearance preset providing default values for the text rendering knobs below
388 /// (font_blend_mode, font_gamma, font_contrast, font_stem_darkening, font_embolden). Knobs you
389 /// set explicitly override the preset's values, so you can start from a preset and adjust
390 /// individual aspects.
391 ///
392 /// (Default: FontProfile::Default)
393 ///
395
396 ///
397 /// How antialiased glyph edges are blended into the page.
398 ///
399 /// Set to FontBlendMode::Profile to use the value from font_profile.
400 ///
402
403 ///
404 /// The gamma to use when compositing font glyphs. Lower values render text heavier, higher
405 /// values render it lighter with more edge contrast (Adobe and Apple prefer 1.8).
406 ///
407 /// Set to 0 to use the value from font_profile.
408 ///
409 /// (Default: 0, meaning the profile's value; the Default profile uses 2.2)
410 ///
411 double font_gamma = 0.0;
412
413 ///
414 /// Additional contrast enhancement applied when compositing font glyphs. Values above 0
415 /// thicken the midtones of antialiased glyph edges, increasing apparent text weight at every
416 /// size. The useful range is 0.0 (none) to about 1.0.
417 ///
418 /// Set below 0 to use the value from font_profile.
419 ///
420 /// (Default: -1.0, meaning the profile's value; the Default profile uses 0.3)
421 ///
422 double font_contrast = -1.0;
423
424 ///
425 /// Stem-darkening strength for rendered text. Boosts the coverage of antialiased glyph
426 /// pixels so thin stems keep their apparent weight on light backgrounds; each preset shapes
427 /// how the boost varies with glyph size. Text on dark backgrounds is unaffected.
428 ///
429 /// Set below 0 to use the value from font_profile.
430 ///
431 /// (Default: -1.0, meaning the profile's value)
432 ///
433 double font_stem_darkening = -1.0;
434
435 ///
436 /// Extra stroke weight applied to glyph shapes, as a fraction of the font size (eg, 0.01 widens
437 /// stems by roughly 1% of the em).
438 ///
439 /// This applies at every size and on both light and dark backgrounds. Glyph advances and layout
440 /// are unaffected.
441 ///
442 /// Set below 0 to use the value from font_profile.
443 ///
444 /// (Default: -1.0, meaning the profile's value)
445 ///
446 /// @note This does not apply to pixel fonts rendered as pixel art (see PixelFontRendering)--
447 /// they keep the weight they were drawn with.
448 ///
449 double font_embolden = -1.0;
450
451 ///
452 /// How pixel fonts are rendered.
453 ///
454 /// @see PixelFontRendering
455 ///
457
458 ///
459 /// Whether or not to adjust the used size of pixel fonts so each font pixel covers a whole
460 /// number of device pixels at the current device scale (see PixelFontRendering).
461 ///
462 /// The library chooses the closest size the font can draw without scaling. For bitmap fonts,
463 /// this means strike sizes and their whole multiples. For outline pixel fonts, it means the
464 /// design size and its whole multiples. Ties go to the larger size. A size below half the
465 /// smallest such size is left unchanged. This applies with either PixelFontRendering value;
466 /// text styled `-ul-font-rendering: smooth` keeps its size.
467 ///
468 /// For an 8 px design at 1.25x:
469 /// ```
470 /// font-size: 16px -> 20 device px -> 24 device px (19.2px used)
471 /// font-size: 12px -> 15 device px -> 16 device px (12.8px used)
472 /// ```
473 ///
474 /// The computed style (eg, `getComputedStyle()`, `em` units) keeps the size the page asked for.
475 ///
476 /// Set this to false to keep the size the page asked for. Pixel fonts then scale to that size,
477 /// and at a size that isn't a whole multiple of the font's design size some font pixels draw
478 /// one device pixel wider than others.
479 ///
480 /// (Default: true)
481 ///
482 /// @note Text set in a pixel font can grow or shrink with the device scale (and at a 1x scale
483 /// when the page asks for a size the font can't draw 1:1), so layout changes too. Fixed
484 /// line heights and boxes sized in `em` don't follow the text.
485 ///
487
488 ///
489 /// Global user-defined CSS string (included before any CSS on the page).
490 ///
491 /// You can use this to override default styles for various elements on the page.
492 ///
493 /// @note This is an actual string of CSS, not a file path.
494 ///
496
497 ///
498 /// Whether or not to continuously repaint any Views, regardless if they are dirty.
499 ///
500 /// This is mainly used to diagnose painting/shader issues and profile performance.
501 ///
502 bool force_repaint = false;
503
504 ///
505 /// Whether or not GPU-accelerated Views render vector content (path fills and strokes)
506 /// analytically (Photon) instead of tessellating it to triangles. Analytic rendering is
507 /// resolution-independent: edges stay crisp under any zoom or transform.
508 ///
509 /// Path rendering on CPU-rendered Views is unaffected. Disabling this also disables
510 /// `enable_photon_text`.
511 ///
512 /// (Default: true)
513 ///
514 bool enable_photon = true;
515
516 ///
517 /// Whether or not text and color emoji also render analytically when `enable_photon` is
518 /// enabled (see photon_text_min_px for the size cutoff). Ignored when `enable_photon` is
519 /// disabled.
520 ///
521 /// This selects the text appearance for both renderers: CPU-rendered Views match the
522 /// analytic look (unhinted outlines, fractional glyph placement) so output stays
523 /// near-identical across renderers.
524 ///
525 /// (Default: true)
526 ///
528
529 ///
530 /// The minimum on-screen glyph size, in pixels, at which text renders analytically when
531 /// `enable_photon_text` is enabled; smaller glyphs use the rasterized glyph atlas. Set to 0
532 /// to render all text analytically.
533 ///
534 /// (Default: 16)
535 ///
536 uint32_t photon_text_min_px = 16;
537
538 ///
539 /// Additional delay (in seconds) on top of the engine's internal page-settled detection.
540 /// (Default: 0.1)
541 ///
542 /// Increase this if you want a little more assurance that the page has fully settled
543 /// (animations finished, late-arriving network activity complete) before View::is_settled()
544 /// flips and LoadListener::OnPageSettled() fires, at the cost of additional wait time.
545 ///
546 /// @see LoadListener::OnPageSettled()
547 ///
548 double page_settle_delay = 0.1;
549
550 ///
551 /// The number of consecutive idle samples the library requires before it declares a page
552 /// settled. (Default: 5)
553 ///
554 /// Together with page_settle_tick this sets the shortest time a page can take to settle
555 /// (page_settle_cycles * page_settle_tick). Lower it to settle sooner, at the cost of
556 /// tolerance for late layout or paint.
557 ///
558 unsigned page_settle_cycles = 5;
559
560 ///
561 /// How often (in seconds) the library samples a loading page for idleness. (Default: 0.006)
562 ///
563 /// @see page_settle_cycles
564 ///
565 double page_settle_tick = 0.006;
566
567 ///
568 /// The interval (in seconds) at which the library automatically recycles internal caches and
569 /// reclaims memory.
570 ///
571 /// The library performs this lightweight recycle for you from inside `Renderer::Update()` /
572 /// `Renderer::Render()`. It is cheap enough to be invisible at typical frame rates, and letting
573 /// the library drive it on this timer is the recommended approach.
574 ///
575 /// Set to `0` to disable the automatic recycler entirely, for applications that prefer to call
576 /// `Renderer::Recycle()` on their own schedule.
577 ///
578 /// (Default: 0.5)
579 ///
580 double recycle_delay = 0.5;
581
582 ///
583 /// Whether the library automatically collects garbage and returns freed
584 /// memory to the OS without embedder involvement.
585 ///
586 /// When a page builds up a large JavaScript heap and then goes quiet, that
587 /// memory would otherwise stay resident until the next burst of activity or
588 /// an explicit Renderer::Recycle / Renderer::PurgeMemory. With this enabled,
589 /// the library collects on its own and pushes the freed memory back to the
590 /// OS, so the process footprint drifts back down after heavy content:
591 ///
592 /// - While the application is idle (no user input, little render activity),
593 /// collection runs on a paced schedule without blocking the render thread.
594 /// - While the application is busy (for example a game rendering every
595 /// frame), collection still runs concurrently whenever the heap has grown
596 /// well past its last collected size, so a HUD that allocated heavily and
597 /// then stopped does not hold its peak footprint. How eagerly this
598 /// triggers follows `memory_profile`.
599 ///
600 /// Reclamation only happens while Renderer::Update() is being pumped. An
601 /// application that stops calling Renderer::Update() while idle gets no
602 /// automatic reclamation; call Renderer::Recycle() / Renderer::PurgeMemory()
603 /// explicitly in that case.
604 ///
605 /// Set this to false if your application manages collection itself; behavior
606 /// then matches earlier releases.
607 ///
608 /// (Default: true)
609 ///
610 bool idle_gc_enabled = true;
611
612 ///
613 /// How long (in seconds) a page must be idle, with no user input, before
614 /// automatic idle collection begins.
615 ///
616 /// Lower values reclaim sooner after the user stops interacting; higher
617 /// values wait longer before assuming the page is idle. Only used when
618 /// `idle_gc_enabled` is true.
619 ///
620 /// (Default: 2.0)
621 ///
622 double idle_gc_idle_time = 2.0;
623
624 ///
625 /// The maximum size of the library's memory cache in bytes. (Default: 256 MiB)
626 ///
627 /// @note This is used for caching decoded images, compiled JavaScript, etc. Increasing this
628 /// may improve performance for resource-heavy applications (at the cost of higher
629 /// memory usage).
630 ///
631 uint32_t memory_cache_size = 256 * 1024 * 1024;
632
633 ///
634 /// The number of pages to keep in the cache. (Default: 0, none)
635 ///
636 /// @note
637 /// \parblock
638 ///
639 /// Safari typically caches about 5 pages and maintains an on-disk cache to support typical
640 /// web-browsing activities.
641 ///
642 /// If you increase this, you should probably increase the memory cache size as well.
643 ///
644 /// \endparblock
645 ///
646 uint32_t page_cache_size = 0;
647
648 ///
649 /// Memory vs. performance tuning for the renderer's HTML / JavaScript
650 /// engine heaps. See the MemoryProfile enumerator descriptions for the
651 /// effect of each profile.
652 ///
653 /// Read when the Renderer is created and by each View at its creation. (Default: Balanced)
654 ///
656
657 ///
658 /// The system's physical RAM size in bytes.
659 ///
660 /// JavaScriptCore tries to detect the system's physical RAM size to set reasonable allocation
661 /// limits. Set this to anything other than 0 to override the detected value. Size is in bytes.
662 ///
663 /// This can be used to force JavaScriptCore to be more conservative with its allocation strategy
664 /// (at the cost of some performance).
665 ///
666 uint32_t override_ram_size = 0;
667
668 ///
669 /// The minimum size of large VM heaps in JavaScriptCore.
670 ///
671 /// Set this to a lower value to make these heaps start with a smaller initial value.
672 ///
673 /// Set to `0` (the default) to derive this value from `memory_profile`.
674 ///
676
677 ///
678 /// The minimum size of small VM heaps in JavaScriptCore.
679 ///
680 /// Set this to a lower value to make these heaps start with a smaller initial value.
681 ///
682 uint32_t min_small_heap_size = 1 * 1024 * 1024;
683
684 ///
685 /// A soft target for the total JavaScriptCore heap size, in bytes.
686 ///
687 /// This is not a hard limit: the heap may grow beyond this target. When it
688 /// does, the garbage collector treats the heap as under memory pressure and
689 /// reclaims more aggressively to bring it back toward the target.
690 ///
691 /// Set to `0` (the default) to derive this value from `memory_profile`.
692 ///
693 uint32_t max_heap_size = 0;
694
695 ///
696 /// The number of threads to use in the Renderer (for parallel painting on the CPU, etc.).
697 ///
698 /// You can set this to a certain number to limit the number of threads to spawn. Values above
699 /// the number of hardware threads are clamped to it.
700 ///
701 /// Set to `0` (the default) to use 8 threads (or fewer on machines with fewer hardware threads).
702 ///
704
705 ///
706 /// The max amount of time (in seconds) to allow repeating timers to run during each call to
707 /// Renderer::Update.
708 ///
709 /// The library will attempt to throttle timers if this time budget is exceeded.
710 ///
711 double max_update_time = 1.0 / 200.0;
712
713 ///
714 /// The row alignment (in bytes) of the BitmapSurface when using the CPU renderer.
715 ///
716 /// The underlying bitmap associated with each BitmapSurface will have row_bytes padded to reach
717 /// this alignment. This must be a power of two (or 0, see below).
718 ///
719 /// Aligning the bitmap helps improve performance when using the CPU renderer. Determining the
720 /// proper value to use depends on the CPU architecture and max SIMD instruction set used.
721 ///
722 /// We generally target the 128-bit SSE2 instruction set across most PC platforms so '16' is
723 /// a safe value to use.
724 ///
725 /// You can set this to '0' to perform no padding (row_bytes will always be width * 4) at a
726 /// slight cost to performance.
727 ///
728 uint32_t bitmap_row_alignment = 16;
729
730 ///
731 /// The quality of effects (blurs, CSS filters, SVG filters, etc.) to use when rendering.
732 ///
733 /// Applies to every rendering path (CSS element filters, canvas `ctx.filter`, and SVG filters)
734 /// on both the CPU and GPU renderers. See EffectQuality for what each level trades.
735 ///
736 /// (Default: EffectQuality::Medium)
737 ///
739
740 ///
741 /// Whether to ignore SSL certificate errors when using the curl network backend.
742 ///
743 /// When set to true, SSL certificate verification will be disabled, allowing connections
744 /// to servers with self-signed or invalid certificates. This should only be used for
745 /// development/testing purposes.
746 ///
747 /// @warning This option reduces security and should never be enabled in production.
748 ///
749 bool ignore_ssl_errors = false;
750
751 ///
752 /// Whether to validate TLS server certificates against the operating system's certificate
753 /// store instead of the certificate bundle shipped with the application
754 /// (resources/cacert.pem).
755 ///
756 /// When false (the default), HTTPS connections are verified using the bundled certificate
757 /// authority list, giving identical behavior on every platform. When true, certificates
758 /// trusted by the host operating system (including enterprise or user-installed roots) are
759 /// honored and the bundled list is not used.
760 ///
761 /// Currently honored on Windows. On platforms where the OS trust store is not yet supported,
762 /// this option is ignored and the bundled list is used.
763 ///
765
766 ///
767 /// Whether to paint full layers when dirty instead of just the dirty subregion.
768 ///
769 /// When set to true and a layer has dirty regions, the full layer will be repainted
770 /// instead of just the dirty rectangle intersection. This can be useful for debugging
771 /// rendering issues or when dirty region tracking is causing artifacts.
772 ///
773 /// @note Enabling this will impact performance as entire layers are redrawn
774 /// instead of just the changed portions.
775 ///
776 bool paint_full_layers = false;
777
778 ///
779 /// The interval (in milliseconds) at which the library samples and emits resource counters
780 /// (memory usage, VRAM, cache sizes, etc.) via the Profiler's EmitCounter() callback.
781 ///
782 /// Set to 0 to disable resource counter sampling entirely -- scopes and events are unaffected.
783 ///
784 /// Default: 500ms.
785 ///
787
788 ///
789 /// Diagnostics and logging options (developer mode, diagnostics levels, and the minimum log
790 /// level).
791 ///
792 /// @see DiagnosticsConfig
793 ///
795
796#if UL_HAS(MEDIA)
797 ///
798 /// The memory-vs-performance profile for the HTML5 media subsystem.
799 ///
800 /// Picks a tradeoff between peak memory per media element and playback
801 /// smoothness / seek responsiveness. The value is read once when each
802 /// media element starts loading and stays fixed for that element's
803 /// lifetime; later changes to `Config::media_profile` apply only to
804 /// subsequently-loaded elements.
805 ///
806 /// @see MediaProfile
807 ///
809#endif // UL_HAS(MEDIA)
810};
811
812} // namespace ultralight
813
814#pragma pop_macro("None")
#define UExport
Definition Exports.h:22
Unicode string container with conversions for UTF-8, UTF-16, and UTF-32.
Definition String.h:31
Root namespace for every public Ultralight type, function, and enumeration.
FaceWinding
The winding order for front-facing triangles.
Definition Config.h:20
@ CounterClockwise
Counter-Clockwise Winding (OpenGL, etc.).
Definition Config.h:29
@ Clockwise
Clockwise Winding (Direct3D, etc.).
Definition Config.h:24
@ Light
Always use the light look.
Definition Window.h:67
DiagnosticsLevel
How much checking and warning the library does for mistakes made through one of its APIs.
Definition DiagnosticsLevel.h:18
@ Auto
Warn when DiagnosticsConfig::developer_mode is on, Off when it's off.
Definition DiagnosticsLevel.h:39
LogLevel
The severity of a log message, from most to least severe.
Definition Logger.h:16
@ Info
Status information.
Definition Logger.h:36
FontProfile
The font-appearance preset that provides default values for the text rendering knobs (Config::font_bl...
Definition Config.h:75
@ MacOSLike
Text with the weight and sharpness of Safari and other macOS applications.
Definition Config.h:84
@ WindowsLike
Text with the crisp, moderate weight of mainstream browsers on Windows.
Definition Config.h:89
@ Default
The standard appearance– currently the same as WindowsLike.
Definition Config.h:79
@ Normal
Neither minimized nor maximized.
Definition Window.h:123
PixelFontRendering
How the library renders pixel fonts.
Definition Config.h:134
@ Pixelated
Keep pixel fonts crisp– hard pixel edges with every glyph on a whole device pixel.
Definition Config.h:154
MemoryProfile
Memory vs.
Definition Config.h:202
@ LowMemory
Optimize for low memory footprint at some cost to peak throughput.
Definition Config.h:217
@ Performance
Optimize for peak throughput at the cost of a higher steady-state memory footprint.
Definition Config.h:225
@ Balanced
Sensible default.
Definition Config.h:208
EffectQuality
The quality level for rendering effects (CSS filters, shadows, blurs, etc.).
Definition Config.h:165
@ Low
Fastest effect quality.
Definition Config.h:170
@ High
Highest effect quality– favors quality over performance.
Definition Config.h:183
@ Medium
Default effect quality– strikes a good balance between quality and performance.
Definition Config.h:175
@ None
Definition Anchor.h:36
MediaProfile
Memory vs.
Definition Config.h:247
@ FavorMemory
Optimise for low memory footprint at the cost of some smoothness and seek responsiveness.
Definition Config.h:262
@ Balanced
Sensible default.
Definition Config.h:254
@ FavorPerformance
Optimise for the smoothest playback and snappiest seeking, at the cost of higher peak memory per medi...
Definition Config.h:270
FontBlendMode
How antialiased glyph edges are blended into the page.
Definition Config.h:102
@ SRGB
Blend in sRGB space– edges keep their full coverage (how macOS composites text).
Definition Config.h:117
@ GammaCorrected
Gamma-corrected blending– edges read lighter with more contrast (how browsers on Windows composite te...
Definition Config.h:112
@ Profile
Use the value from the font profile.
Definition Config.h:106
FontHinting
The font hinting algorithm to use when rendering glyphs.
Definition Config.h:37
@ Monochrome
Strongest hinting algorithm– outputs only black/white glyphs.
Definition Config.h:59
@ Normal
Let the font profile choose– Config::font_profile picks the hinting that suits its appearance,...
Definition Config.h:50
@ Smooth
Lighter hinting algorithm– glyphs are slightly fuzzier but better resemble their original shape.
Definition Config.h:43
@ Default
The platform's usual corners for this kind of window.
Definition Window.h:138
Core configuration for the renderer.
Definition Config.h:336
MediaProfile media_profile
The memory-vs-performance profile for the HTML5 media subsystem.
Definition Config.h:808
String cache_path
A writable OS file path to store persistent Session data in.
Definition Config.h:346
bool enable_photon
Whether or not GPU-accelerated Views render vector content (path fills and strokes) analytically (Pho...
Definition Config.h:514
uint32_t override_ram_size
The system's physical RAM size in bytes.
Definition Config.h:666
String user_stylesheet
Global user-defined CSS string (included before any CSS on the page).
Definition Config.h:495
double idle_gc_idle_time
How long (in seconds) a page must be idle, with no user input, before automatic idle collection begin...
Definition Config.h:622
MemoryProfile memory_profile
Memory vs.
Definition Config.h:655
bool force_repaint
Whether or not to continuously repaint any Views, regardless if they are dirty.
Definition Config.h:502
PixelFontRendering pixel_font_rendering
How pixel fonts are rendered.
Definition Config.h:456
double recycle_delay
The interval (in seconds) at which the library automatically recycles internal caches and reclaims me...
Definition Config.h:580
bool ignore_ssl_errors
Whether to ignore SSL certificate errors when using the curl network backend.
Definition Config.h:749
bool snap_pixel_font_size
Whether or not to adjust the used size of pixel fonts so each font pixel covers a whole number of dev...
Definition Config.h:486
uint32_t max_heap_size
A soft target for the total JavaScriptCore heap size, in bytes.
Definition Config.h:693
uint32_t page_cache_size
The number of pages to keep in the cache.
Definition Config.h:646
double font_stem_darkening
Stem-darkening strength for rendered text.
Definition Config.h:433
double font_embolden
Extra stroke weight applied to glyph shapes, as a fraction of the font size (eg, 0....
Definition Config.h:449
double page_settle_tick
How often (in seconds) the library samples a loading page for idleness.
Definition Config.h:565
bool use_system_certificate_store
Whether to validate TLS server certificates against the operating system's certificate store instead ...
Definition Config.h:764
bool idle_gc_enabled
Whether the library automatically collects garbage and returns freed memory to the OS without embedde...
Definition Config.h:610
bool enable_photon_text
Whether or not text and color emoji also render analytically when enable_photon is enabled (see photo...
Definition Config.h:527
uint32_t resource_sample_interval
The interval (in milliseconds) at which the library samples and emits resource counters (memory usage...
Definition Config.h:786
double font_contrast
Additional contrast enhancement applied when compositing font glyphs.
Definition Config.h:422
EffectQuality effect_quality
The quality of effects (blurs, CSS filters, SVG filters, etc.) to use when rendering.
Definition Config.h:738
uint32_t photon_text_min_px
The minimum on-screen glyph size, in pixels, at which text renders analytically when enable_photon_te...
Definition Config.h:536
bool paint_full_layers
Whether to paint full layers when dirty instead of just the dirty subregion.
Definition Config.h:776
double page_settle_delay
Additional delay (in seconds) on top of the engine's internal page-settled detection.
Definition Config.h:548
FaceWinding face_winding
The winding order for front-facing triangles.
Definition Config.h:367
double font_gamma
The gamma to use when compositing font glyphs.
Definition Config.h:411
double max_update_time
The max amount of time (in seconds) to allow repeating timers to run during each call to Renderer::Up...
Definition Config.h:711
DiagnosticsConfig diagnostics
Diagnostics and logging options (developer mode, diagnostics levels, and the minimum log level).
Definition Config.h:794
uint32_t min_large_heap_size
The minimum size of large VM heaps in JavaScriptCore.
Definition Config.h:675
FontHinting font_hinting
The hinting algorithm to use when rendering fonts.
Definition Config.h:384
uint32_t memory_cache_size
The maximum size of the library's memory cache in bytes.
Definition Config.h:631
uint32_t min_small_heap_size
The minimum size of small VM heaps in JavaScriptCore.
Definition Config.h:682
FontBlendMode font_blend_mode
How antialiased glyph edges are blended into the page.
Definition Config.h:401
unsigned page_settle_cycles
The number of consecutive idle samples the library requires before it declares a page settled.
Definition Config.h:558
uint32_t bitmap_row_alignment
The row alignment (in bytes) of the BitmapSurface when using the CPU renderer.
Definition Config.h:728
String resource_path_prefix
The relative path to the resources folder (loaded via the FileSystem API).
Definition Config.h:358
uint32_t num_renderer_threads
The number of threads to use in the Renderer (for parallel painting on the CPU, etc....
Definition Config.h:703
FontProfile font_profile
The font-appearance preset providing default values for the text rendering knobs below (font_blend_mo...
Definition Config.h:394
Diagnostics and logging options.
Definition Config.h:280
bool developer_mode
Whether or not the library runs in developer mode.
Definition Config.h:291
DiagnosticsLevel dom
The diagnostics level for the DOM API and data bindings.
Definition Config.h:302
DiagnosticsLevel javascript
The diagnostics level for JavaScript APIs that leave their own level at DiagnosticsLevel::Auto.
Definition Config.h:297
LogLevel min_log_level
The least severe level the library sends to the Logger (less severe messages are dropped).
Definition Config.h:310