Porting from 1.4 to 2.0

Migrate an application from Ultralight 1.4 to 2.0.

You can update an application from 1.4 to 2.0 by focusing on the specific subsystems your code touches. Most CPU-rendered apps need only a handful of edits— the heavier work lands on GPU drivers, Overlay users, custom clipboards, JSHelpers users, and C embedders.

Custom FileSystem, FontLoader, Logger, and ThreadFactory implementations compile against 2.0 untouched. A custom Surface gains one required method, Scroll().

#At a Glance

• Everyone — recompile everything against the 2.0 SDK (the ABI changed) and skim Behavior Changes.
• AppCore apps — Overlay is gone (the panel layout replaces it), window geometry moved to logical pixels, and WindowListener signatures changed.
• GPUDriver implementers — plan to update your entire driver for seven shader programs, new blend state, and new texture flags.
• Custom Clipboard implementers — the interface is replaced with whole-payload methods.
• Custom Surface implementers — add one required method, Scroll(). The dirty area is also available as a list of rectangles.
• JSHelpers users — the header is removed, replaced by the typed bridge.
• C embedders — every callback setter gained a fourth argument, and a few signatures changed.

#Build and Toolchain

• The public headers now require C++20— compiling with an older compiler or language mode triggers a #error. On Windows, you'll need Visual Studio 2022 or later with /std:c++20.
• The SDK ships as a CMake package. Use find_package(Ultralight REQUIRED), link Ultralight::AppCore, and call ultralight_copy_runtime_files() to stage the runtime files. See Linking to the Library to configure your build targets.
• The package layout is flat. Libraries live in bin/ and lib/ with no per-OS subfolders, and reference platform implementations (GPU drivers, font loaders, and file systems that back AppCore) ship as Zlib-licensed source in the package's platform folder.

📘 Two headers share a name now

The new generated <Ultralight/Config.h> (edition and feature macros, pulled in by every Ultralight header) is a different file from <Ultralight/platform/Config.h> (the Config struct you fill in). 1.4 had only the latter.

The generated header defines UL_HAS(x) for feature checks (eg, #if UL_HAS(MEDIA)) and UL_EDITION_AT_LEAST(x) for edition checks. These preprocessor gates remove declarations from Free-edition headers entirely, so referencing them causes a compile error instead of a runtime failure.

#Behavior Changes

These changes affect how a rebuilt application runs without triggering compile errors.

• Text renders differently — Kerning and ligatures now apply (1.4 never shaped text), and a font profile controls glyph weight and hinting (Config::font_gamma now defaults to 0, which inherits from Config::font_profile). Under AppCore, generic CSS font families come from the host OS (monospace resolves to Menlo on macOS and Consolas on Windows, sized at 13px). Metrics land much closer to mainstream browsers. See Text Rendering and Fonts to configure font profiles and the generic font families.
• GPU-rendered Views use analytic rendering by default — Paths, strokes, and text now render more sharply. Set Config::enable_photon and Config::enable_photon_text to false to keep the 1.4 look.
• Submitting an invalid form now blocks — Constraint validation runs the way browsers do. The invalid event fires, and the first invalid control takes focus. Calling reportValidity() checks the form without drawing a message bubble. Add novalidate to a form to submit without validation. See Forms and Inputs to handle form validation and submission.
• The compositor is enabled by default — ViewConfig::enable_compositor defaults to true (was false). Elements with 3D or animated transforms, animated opacity, video, will-change, or translateZ(0) now render into their own layers— each layer uses extra memory.
• WebAssembly is no longer available — The global WebAssembly object is now undefined on all platforms (1.4 supported it on macOS and Linux, but never on Windows). Pages that check for the feature switch to their JavaScript fallback— pages that depend on it stop working.
• Two ViewConfig defaults changed — ViewConfig::preferred_color_scheme now defaults to ColorScheme::Auto, so AppCore apps match the OS dark mode and apply page dark styles (apps without AppCore are unaffected, and ColorScheme::Light keeps the 1.4 light look). ViewConfig::clipboard_read_policy now lets page script in local content (file:/// pages and HTML from View::LoadHTML()) read the clipboard on a click or key press, excluding remote web pages. See Dark Mode and Color Schemes to configure theme settings and color schemes.
• Editing follows the OS under AppCore — Settings::match_native_editing_behavior defaults to true, so selection and caret behavior match each platform. Views you create manually keep uniform cross-platform editing unless you enable ViewConfig::match_native_editing_behavior.
• Memory management runs automatically — Config::recycle_delay sets the interval between automatic lightweight recycles and defaults to 0.5 seconds (was 4.0 seconds), with 0 disabling them. Idle pages reclaim JavaScript heaps automatically (Config::idle_gc_enabled), and Config::memory_cache_size defaults to 256 MiB (was 64 MiB). If you target memory-constrained devices, configure these values explicitly. See Managing Memory to tune memory profiles, cache limits, and reclamation.
• The default User-Agent reports the host platform and Ultralight/2.0.0 — Version 1.4 reported Windows on every OS, so sites that sniff the User-Agent string may serve different content on macOS and Linux. Overriding ViewConfig::user_agent is unavailable in the Free edition.
• Smooth scrolling uses a physics-based spring model — The rewritten scrolling logic changes scroll feel to match macOS and iOS.
• CSS transitions take precedence over !important declarations — This change aligns with the CSS specification. Pages where transition targets use !important animate instead of snapping instantly.
• LogLevel gained Fatal and Debug — Fatal comes first and Debug last, so every level's number changed (in C, kLogLevel_Error is now 1). Update switch statements in a custom Logger and any level numbers hard-coded in C or C# code. AppCore's default logger shows a message box for every LogLevel::Fatal message.

#Core API

• RefPtr's boolean conversion is now an explicit operator bool. Conditional checks like if (ptr) still compile, but implicit conversions (such as bool ok = ptr; or passing a RefPtr to a bool parameter) require ptr.get() != nullptr instead.
• The Config::animation_timer_delay and Config::scroll_timer_delay fields are removed. Animations advance when you call Renderer::RefreshDisplay(). To throttle an individual View, set ViewConfig::max_render_fps or call View::set_max_render_fps() (0 leaves the View unthrottled).
• KeyEvent now owns platform data— zeroing or copying it with memset or memcpy causes a crash. Construct and copy instances using standard C++ constructors and assignment.
• BitmapFormat gained new values, so update switch statements to handle the new cases. Compressed formats don't have a bytes-per-pixel value— call GetBitmapFormatInfo() to get format details.
• View::LockJSContext(), View::JavaScriptVM(), and View::EvaluateScript() each take an optional frame name to target an <iframe>. The parameter defaults to the main frame, so existing call sites compile unchanged.
• Renderer::Recycle() reclaims memory on demand, and Renderer::PostTask() schedules work on the renderer thread from any thread.
• Custom Surface implementations gain one required method, Scroll(), which shifts a rectangle of pixels when the page scrolls (most implementations are one call to Surface::ShiftPixels(), returning false). The dirty area is also available as a list of rectangles (dirty_rect_count(), dirty_rect()). dirty_bounds() is still their union, so existing display code keeps working. In C, ULSurfaceDefinition gained a scroll field appended last— zero-initialize the struct, and the library handles a NULL callback itself. See Render Surfaces to implement scrolling and handle dirty rectangles.

#GPUDriver Implementations

Custom GPU drivers require substantial updates for 2.0. See Implementing a GPUDriver to implement the complete driver interface.

• Seven shader programs are required instead of two. FilterBasic, FilterBlur, FilterDropShadow, FillPhoton, and FillPhotonGrid join Fill and FillPath. All programs are mandatory because the library never queries for per-program support. Stock shaders for every program ship in the SDK's platform/shaders folder in compiled or generated form for each backend.
• GPUDriver::CreateTexture() takes a third flags parameter (kGPUTextureFlag_RenderTarget, kGPUTextureFlag_Antialiased, and kGPUTextureFlag_Immutable). Texture flags now determine whether a texture is a render target, rather than checking for an empty bitmap.
• GPUDriver::UpdateTexture() takes a dirty_rect parameter as an optimization hint. You can upload only that region, or ignore the hint and upload the entire bitmap.
• GPUState gained blend_src_factor, blend_dst_factor, blend_equation, texture_4_id, and uniform_integer. Because the struct's byte layout changed, re-mirror your constant buffers and recompile. Map the blend fields directly to your graphics API's blend state— the renderer emits explicit blend state per draw instead of assuming premultiplied alpha.
• VertexBufferFormat gained a third layout, _2f_2ui, with the matching Vertex_2f_2ui struct (float pos[2], uint32_t header_addr, uint32_t path_slot). The FillPhotonGrid program draws with it, so a driver that hardcodes two input layouts needs a third.
• CommandType::Flush is new. Submit pending GPU work before executing the next command (Flush() on Direct3D 11 or glFlush() on OpenGL, and typically a no-op on Direct3D 12, Metal, or Vulkan where pipeline barriers order accesses).
• GPUDriver::GetDeviceCaps() is new and optional as the driver's only non-pure virtual method. Override it to report MSAA support, compressed texture formats, and size limits, or omit it to let the engine substitute conservative defaults.
• Render targets can now be single-channel. Back an A8_UNORM render target with a renderable one-channel format (such as R8 on modern graphics APIs) and skip the alpha swizzle that sampled A8 textures use.

The C ULGPUDriver struct mirrors these changes. Its create and update callbacks take the new parameters, ULGPUState includes the new blend and texture fields, and the struct adds a get_device_caps function pointer.

#Windows and AppCore

#Moving from Overlay to Panels

Overlay is removed and replaced by the panel layout system. A panel is the unit of web content, and the window manages input, focus, and painting for each panel automatically:

///
/// 1.4: create an Overlay covering the window.
///
auto overlay = Overlay::Create(window, 1024, 768, 0, 0);
overlay->view()->LoadURL("file:///app.html");

///
/// 2.0: a bare AddPanel() fills the whole window.
///
auto panel = window->AddPanel();
panel->view()->LoadURL("file:///app.html");

Overlay calls map to window panel operations as shown below. See Laying Out Panels to construct and arrange the layout tree.

#Window and Monitor Geometry

Window::width(), Window::height(), Monitor::width(), and Monitor::height() now return logical double pixels instead of device pixels (macOS monitors already used logical values). The method names haven't changed, so existing call sites still compile— but they return different values whenever the scale factor isn't 1.0. Window::Create(), MoveTo(), x(), and y() keep the same units, but now use double. Assigning those values to an int truncates them.

Device-pixel dimensions are now returned by device_width() and device_height() on both Window and Monitor. The conversions ScreenToPixels() and PixelsToScreen() are replaced by LogicalToDevice() and DeviceToLogical(). The old screen_width() and screen_height() functions are removed.

#WindowListener Callbacks and WindowFlags

WindowFlags is now an enum class. For example, kWindowFlags_Titled | kWindowFlags_Resizable becomes WindowFlags::Titled | WindowFlags::Resizable. The C API enumerator names remain unchanged.

Mouse, keyboard, and scroll callbacks in WindowListener gained a leading Window* parameter, and OnResize() now receives logical double dimensions.

🚧 Mark your WindowListener overrides with override

A 1.4 OnKeyEvent(const KeyEvent&) override still compiles in 2.0— it declares a brand-new function and silently stops being called. The override keyword turns that into a compile error, so add it before you build.

#Smaller AppCore Changes

• Settings::load_shaders_from_file_system and its C setter are removed with no replacement.
• App::RunOnce() is new. It executes a single iteration of the application event loop, allowing you to run AppCore from an existing main loop instead of passing thread control to Run().
• The 1.4 public AppCore source repository (LGPL) is superseded. Reference implementations previously copied from it (GPU drivers, font loaders, file systems, and clipboards) now ship as Zlib-licensed source in the SDK's platform folder.

#Clipboard Implementations

Clipboard::ReadPlainText() and WritePlainText() are replaced by whole-payload methods so a single copy operation can transfer multiple formats (eg, text/plain and text/html) at once:

///
/// 1.4: plain text only.
///
String ReadPlainText() override;
void WritePlainText(const String& text) override;

///
/// 2.0: whole payloads, one entry per format.
///
RefPtr<ClipboardData> Read() override;
void Write(RefPtr<ClipboardData> data) override;

A text-only backend remains simple. Return ClipboardData::Create(text) from Read(). In Write(), write data->AsText() and skip unrecognized data types.

The C ULClipboard struct mirrors these changes. Every callback gained a leading void* user_data parameter, the struct gained a user_data field, and the read and write functions operate on the new ULClipboardData handle rather than ULString.

#JSHelpers Is Removed

#Replacing JSHelpers with the Typed Bridge

The <AppCore/JSHelpers.h> header is removed, along with all its declarations (including JSValue, JSObject, JSFunction, SetJSContext(), and BindJSCallback). The typed bridge in <Ultralight/js/API.h> replaces these helpers. Unlike JSHelpers, bindings registered through the typed bridge survive page navigation:

///
/// 1.4: set a global context and re-bind on every page load.
///
auto lock = caller->LockJSContext();
SetJSContext(lock->ctx());
JSObject global = JSGlobalObject();
global["ShowMessage"] = BindJSCallback(&MyApp::ShowMessage);

///
/// 2.0: bind once and attach to the View-- bindings survive navigation.
///
js::API api("myApp");
api["ShowMessage"] = js::Bind(this, &MyApp::ShowMessage);

if (api.AttachTo(view.get()))
  view->LoadURL("file:///app.html");

The page now calls myApp.ShowMessage() instead of a global ShowMessage().

Keep the js::API object alive (eg, as a member of your app) for as long as pages should have the bindings— destroying it detaches it from every View.

#JSHelpers Pattern Map

Common JSHelpers patterns map to the 2.0 typed bridge as shown in this table. See About JavaScript Interop to register callbacks and export classes.

#Using JavaScriptCore Directly

The raw JavaScriptCore C API remains fully supported. You can obtain a context reference by calling View::LockJSContext().

The library's extensions to JavaScriptCore are purely additive. Because JSClassDefinition gained additional members, code using JavaScriptCore must be recompiled rather than relinked. See Using JavaScriptCore Directly to work with native contexts and low-level JavaScript values.

#The C API

Every 1.4 callback setter gained a trailing destroy_user_data parameter. Passing NULL indicates there is nothing to free. Every callback registration added in 2.0 takes the same parameter.

The destroy callback runs once when the registration releases its user data, and it never runs while the callback itself is active. You must update every registration call site. See C API Conventions for user-data lifetime and ownership rules:

///
/// 1.4: callback plus user data.
///
ulWindowSetCloseCallback(window, OnClose, my_data);

///
/// 2.0: the same call with the new fourth parameter.
///
ulWindowSetCloseCallback(window, OnClose, my_data, NULL);

• The Overlay C API (the ULOverlay handle and its associated functions) is removed in favor of the layout API. Call ulWindowAddPanel(window, NULL, NULL) to create a full-window panel, and call ulPanelGetView() to access its View. Layout functions are declared in <AppCore/CAPI/CAPI_Layout.h>.
• ulCreateScrollEvent() gained two cursor-coordinate parameters. Pass -1, -1 to preserve 1.4 behavior and dispatch at the last known cursor position.
• ulConfigSetAnimationTimerDelay() and ulConfigSetScrollTimerDelay() are removed. Throttle individual views with ulViewSetMaxRenderFps().
• Window and monitor geometry moved to logical double pixels. ulWindowGetWidth() and ulMonitorGetWidth() return logical pixels, while ulWindowGetDeviceWidth() provides the device-pixel measurement. ULResizeCallback passes double values, and screen-coordinate functions are removed.
• The C API also gained window-level keyboard, mouse, and scroll callbacks (1.4 had no C way to intercept them), native message boxes, ulAppRunOnce(), and dedicated setters for every Config field.

#What's New

Beyond the changes above, 2.0 adds new subsystems that have no 1.4 counterpart. Each subsystem is documented in its own guide:

• A native DOM API and declarative data bindings to inspect, modify, and bind UI state without JavaScript.
• The typed JavaScript bridge shown above to expose native functions and classes.
• Text editing, IME, and clipboard control, including View::editor().
• HTML5 video and audio (Pro), compressed GPU textures (Pro), the Profiler (Pro), and render tracing (Enterprise).
• Handling View Events, Sessions and Site Data, Dark Mode and Color Schemes, and the Color, URL, and JSON value types in Working with Colors, Working with URLs, and Working with JSON.
• Window backdrops, custom chrome, transparency, and popups under AppCore.
• Frame timing is under your control through the timed form of Renderer::RefreshDisplay(), declared display refresh rates, and custom clocks. See Updating and Rendering to configure custom animation timing. AppCore syncs animations to each frame's on-screen time for you and enumerates monitors through App::monitor().