Porting from 1.1 to 1.2

High-level overview of the API changes between v1.1 and v1.2


  • Config::device_scale_hint has been renamed to Config::device_scale
  • You must now supply a path to Config::resource_path (this is the resources folder from the SDK)
  • You must now supply a writable path to Config::cache_path (used by Session to write cookies and other persistent data)
  • Config::use_gpu_renderer has been added. When this is disabled (the default), the Renderer will use the CPU renderer to paint Views to an offscreen Surface. (Only relevant if you are using Renderer::Create()-- this is overriden by App::Create())
  • Config::use_bgra_for_offscreen_rendering has been removed. The new CPU renderer now always writes BGRA32 values to the Surface API.


The library now requires you to distribute the resources folder with your executable (you can tell the library the location of this folder in Config).

Currently, the resources folder contains the following two files:

cacert.pemThis file contains a list of CA Root Certificates to use when verifying SSL certificates.

You can always find the latest at cURL's website

Failure to include this file may cause HTTPS requests to fail.
icudt67l.datThis file contains data for the ICU library, necessary for Unicode support.

Failure to include this file may cause the library to fail when performing certain text operations, or, in the worst case, crash.


You can now get access to library errors and info by providing a Logger to Platform::instance().set_logger()

Coordinate System

The library now uses pixel coordinates for almost every API routine except Window::Create() (which uses device coordinates).

For example, in v1.1, if you called Renderer::CreateView() with a width of 100 and were using a device_scale_hint of 2.0, the library would actually allocate a View with a width of 200 pixels.

In v1.2, Renderer::CreateView() and Overlay::Create() now take width/height in pixels instead.

This change applies to the GPUDriver API as well-- all viewport coordinates and scissor rects are now specified in pixels.


Beyond the coordinate system change mentioned above, GPUDriver has also been cleaned up, the following methods have been removed:

  • GPUDriver::BindTexture
  • GPUDriver::BindRenderBuffer
  • GPUDriver::ClearRenderBuffer
  • GPUDriver::DrawGeometry
  • GPUDriver::HasCommandsPending
  • GPUDriver::DrawCommandList

These methods weren't actually being called by the library-- the GPUDriver implementations in AppCore would typically call these methods internally after handling a call to GPUDriver::UpdateCommandList(). We've removed these for clarity.


The FileSystem interface has been simplified to the following functions (all others were removed):

  • FileSystem::FileExists
  • FileSystem::GetFileSize
  • FileSystem::GetFileMimeType
  • FileSystem::OpenFile
  • FileSystem::ReadFromFile
  • FileSystem::CloseFile

Bitmap API replaced with Surface API

View::bitmap() has been replaced with View::surface() (the default Surface wraps a Bitmap).

This new API allows users to provide their own Surface implementation via Platform::instance().set_surface_factory().

View::js_context() changes

View::js_context() has been replaced with View::LockJSContext() which returns a scoped lock for the context.

View::EvaluateScript() changes

View::EvaluateScript() now returns a String instead of a JSValueRef. (This function now automatically locks the context for thread-safety)

If you still need a native JSValueRef, you should call View::LockJSContext(), get the underlying context handle, and call JSEvaluateScript() (defined in the native JavaScriptCore API).

Platform FileSystem/FontLoader/Logger implementations

If you're using Renderer::Create() standalone, you can now use AppCore's platform-specific implementations for the Platform handlers, see <AppCore/Platform.h>