Ozone Overview

Ozone is a platform abstraction layer beneath the Aura window system that is used for low level input and graphics. Once complete, the abstraction will support underlying systems ranging from embedded SoC targets to new X11-alternative window systems on Linux such as Wayland or Mir to bring up Aura Chromium by providing an implementation of the platform interface.

Note: There are 2 buildflags which target platforms who use OZONE. They are slightly different from each other:

• IS_OZONE: Targets Linux, ChromeOS, and Fuchsia.
• IS_OZONE_WAYLAND: Targets only Linux systems using the Wayland window manager. Does not include ChromeOS or Fuchsia.

Guiding Principles

Our goal is to enable chromium to be used in a wide variety of projects by making porting to new platforms easy. To support this goal, ozone follows the following principles:

1. Interfaces, not ifdefs. Differences between platforms are handled by calling a platform-supplied object through an interface instead of using conditional compilation. Platform internals remain encapsulated, and the public interface acts as a firewall between the platform-neutral upper layers (aura, blink, content, etc) and the platform-specific lower layers. The platform layer is relatively centralized to minimize the number of places ports need to add code.
2. Flexible interfaces. The platform interfaces should encapsulate just what chrome needs from the platform, with minimal constraints on the platform's implementation as well as minimal constraints on usage from upper layers. An overly prescriptive interface is less useful for porting because fewer ports will be able to use it unmodified. Another way of stating is that the platform layer should provide mechanism, not policy.
3. Runtime binding of platforms. Avoiding conditional compilation in the upper layers allows us to build multiple platforms into one binary and bind them at runtime. We allow this and provide a command-line flag to select a platform (--ozone-platform) if multiple are enabled. Each platform has a unique build define (e.g.ozone_platform_foo) that can be turned on or off independently.
4. Easy out-of-tree platforms. Most ports begin as forks. Some of them later merge their code upstream, others will have an extended life out of tree. This is OK, and we should make this process easy to encourage ports, and to encourage frequent gardening of chromium changes into the downstream project. If gardening an out-of-tree port is hard, then those projects will simply ship outdated and potentially insecure chromium-derived code to users. One way we support these projects is by providing a way to inject additional platforms into the build by only patching oneozone_extra.gni file.

Ozone Platform Interface

Ozone moves platform-specific code behind the following interfaces:

• PlatformWindow represents a window in the windowing system underlying chrome. Interaction with the windowing system (resize, maximize, close, etc) as well as dispatch of input events happens via this interface. Under aura, aPlatformWindow corresponds to aWindowTreeHost. Under mojo, it corresponds to aNativeViewport. On bare hardware, the underlying windowing system is very simple and a platform window corresponds to a physical display.
• SurfaceFactoryOzone is used to create surfaces for the Chrome compositor to paint on using EGL/GLES2 or Skia.
• GpuPlatformSupportHost provides the platform code access to IPC between the browser & GPU processes. Some platforms need this to provide additional services in the GPU process such as display configuration.
• OverlayManagerOzone is used to manage overlays.
• InputController allows to control input devices such as keyboard, mouse or touchpad.
• SystemInputInjector converts input into events and injects them to the Ozone platform.
• NativeDisplayDelegate is used to support display configuration & hotplug.
• PlatformScreen is used to fetch screen configuration.
• ClipboardDelegate provides an interface to exchange data with other applications on the host system using a system clipboard mechanism.

Ozone in Chromium

Our implementation of Ozone required changes concentrated in these areas:

• Cleaning up extensive assumptions about use of X11 throughout the tree, protecting this code behind theUSE_X11 ifdef, and adding a newIS_OZONE path that works in a relatively platform-neutral way by delegating to the interfaces described above.
• aWindowTreeHostOzone to send events into Aura and participate in display management on the host system, and
• an Ozone-specific flavor ofGLSurfaceEGL which delegates allocation of accelerated surfaces and refresh syncing to the provided implementation ofSurfaceFactoryOzone.

Porting with Ozone

Users of the Ozone abstraction need to do the following, at minimum:

• Write a subclass ofPlatformWindow. This class (I'll call itPlatformWindowImpl) is responsible for window system integration. It can useMessagePumpLibevent to poll for events from file descriptors and then invokePlatformWindowDelegate::DispatchEvent to dispatch each event.
• Write a subclass ofSurfaceFactoryOzone that handles allocating accelerated surfaces. I'll call thisSurfaceFactoryOzoneImpl.
• Write a subclass ofCursorFactory to manage cursors, or use theBitmapCursorFactory implementation if only bitmap cursors need to be supported.
• Write a subclass ofOverlayManagerOzone or just useStubOverlayManager if your platform does not support overlays.
• Write a subclass ofNativeDisplayDelegate if necessary or just useFakeDisplayDelegate, and write a subclass ofPlatformScreen, which is used by aura::ScreenOzone then.
• Write a subclass ofGpuPlatformSupportHost or just useStubGpuPlatformSupportHost.
• Write a subclass ofInputController or just useStubInputController.
• Write a subclass ofSystemInputInjector if necessary.
• Write a subclass ofOzonePlatform that owns instances of the above subclasses and provide a static constructor function for these objects. This constructor will be called when your platform is selected and the returned objects will be used to provide implementations of all the ozone platform interfaces. If your platform does not need some of the interfaces then you can just return aStub* instance or anullptr.

Adding an Ozone Platform to the build (instructions for out-of-tree ports)

The recommended way to add your platform to the build is as follows. This walks through creating a new ozone platform calledfoo.

1. Forkchromium/src.git.
2. Add your implementation inui/ozone/platform/ alongside internal platforms.
3. Patchui/ozone/ozone_extra.gni to add yourfoo platform.

Building with Ozone

Chrome OS - (waterfall)

To buildchrome, do this from thesrc directory:

gn argsout/OzoneChromeOS--args="use_ozone=true target_os=\"chromeos\""ninja-Cout/OzoneChromeOS chrome

Then to run for example the X11 platform:

./out/OzoneChromeOS/chrome--ozone-platform=x11

Embedded

Warning: Only some targets such ascontent_shell or unit tests are currently working for embedded builds.

To buildcontent_shell, do this from thesrc directory:

gn argsout/OzoneEmbedded--args="use_ozone=true toolkit_views=false"ninja-Cout/OzoneEmbedded content_shell

Then to run for example the headless platform:

./out/OzoneEmbedded/content_shell--ozone-platform=headless \--ozone-dump-file=/tmp/

Linux Desktop - (X11 waterfall &&

Wayland waterfall)

By default, Linux enables the following Ozone backends - X11, Wayland and Headless.

If you want to disable Ozone/X11 in the build, do this from thesrc directory:

gn argsout/OzoneLinuxDesktop--args="ozone_platform_x11=false"ninja-Cout/OzoneLinuxDesktop chrome

If you want to disable all, but Wayland Ozone backend, do this from thesrc directory:

gn argsout/OzoneLinuxDesktop--args="ozone_auto_platforms=false ozone_platform_wayland=true"ninja-Cout/OzoneLinuxDesktop chrome

Chrome/Linux uses X11 Ozone backend by default. Thus, simply start the browser without any parameters:

./out/OzoneLinuxDesktop/chrome

Or run for example the Wayland platform:

./out/OzoneLinuxDesktop/chrome--ozone-platform=wayland

It is also possible to choose an Ozone backend via thechrome://flags/#ozone-platform-hint. The following options are available - Default, X11, Wayland, and Auto. “Auto” selects Wayland if possible, X11 otherwise.

GN Configuration notes

You can turn properly implemented ozone platforms on and off by setting the corresponding flags in your GN configuration. For exampleozone_platform_headless=false ozone_platform_drm=false will turn off the headless and DRM (GBM) platforms. This will result in a smaller binary and faster builds. To turn ALL platforms off by default, setozone_auto_platforms=false.

You can also specify a default platform to run by setting theozone_platform build parameter. For exampleozone_platform="x11" will make X11 the default platform when--ozone-platform is not passed to the program. Ifozone_auto_platforms is true thenozone_platform is set toheadless by default.

Running with Ozone

Specify the platform you want to use at runtime using the--ozone-platform flag. For example, to runcontent_shell with the DRM (GBM) platform:

content_shell--ozone-platform=drm

Caveats:

• content_shell always runs at 800x600 resolution.
• For the DRM (GBM) platform, you may need to terminate your X server (or any other display server) prior to testing.
• During development, you may need to configuresandboxing or to disable it.

Ozone Platforms

Headless

This platform draws graphical output to a PNG image (no GPU support; software rendering only) and will not output to the screen. You can set the path of the directory where to output the images by specifying--ozone-dump-file=/path/to/output-directory on the command line:

content_shell--ozone-platform=headless \--ozone-dump-file=/tmp/

DRM/GBM

This is Linux direct rending with acceleration via mesa GBM & linux DRM/KMS (EGL/GLES2 accelerated rendering & modesetting in GPU process) and is in production use onChrome OS.

Note that all Chrome OS builds of Chrome will compile and attempt to use this. SeeBuilding Chromium for Chromium OS for build instructions.

Cast

This platform is used forChromecast.

X11

This platform provides support for theX window system.

X11 is the default Ozone backend. You can try to compile and run it with the following configuration:

gn argsout/OzoneX11ninja-Cout/OzoneX11 chrome./out/OzoneX11/chrome

Wayland

This platform provides support for theWayland display protocol. It was initially developed by Intel asa fork of chromium and then partially upstreamed.

Currently, the Ozone/Wayland is actively being developed by Igalia in the Chromium mainline repository with some features missing at the moment. The progress can be tracked in theissue #578890.

Below are some quick build & run instructions. It is assumed that you are launchingchrome from a Wayland environment such asweston. Execute the following commands (make sure a system version of gbm and drm is used, which are required by Ozone/Wayland by design, when running on Linux platforms.):

Please note that the Wayland Ozone backend is built by default unlessozone_auto_platforms=false is set (the same as the X11 Ozone backend).

gn argsout/OzoneWaylandninja-Cout/OzoneWayland chrome./out/OzoneWayland/chrome--ozone-platform=wayland

Native file dialogs are currently supported through the GTK toolkit. That implies that the browser is compiled with glib and gtk enabled. Please append the following gn args to your configuration:

use_ozone=trueuse_system_minigbm=trueuse_system_libdrm=trueuse_xkbcommon=trueuse_glib=trueuse_gtk=true

Running some test suites requires a Wayland server. If you're not running one you can use a locally compiled version of Weston or Mutter. This is what the build bots do. Please note that this is required for interactive_ui_tests, as those tests use a patched version of the compositor.

Mutter and its dependencies are not checked out by default to keep the disk usage optimal for most developers. In order to checkout mutter, add thecheckout_mutter custom var in your .gclient file and set it toTrue and rungclient sync.

solutions = [  {    "url": "https://chromium.googlesource.com/chromium/src.git",    "managed": False,    "name": "src",    "custom_deps": {},    "custom_vars": {      "checkout_mutter": True,    },  },]

For weston, simply add this to your gn args:

use_bundled_weston=true

Then after building the test executable, run the xvfb.py wrapper script and tell it to start the compositor with the tests:

cdout/debug# or your out directory

# For weston../../testing/xvfb.py--use-weston--no-xvfb./views_unittests--ozone-platform=wayland

# For mutter../../testing/xvfb.py--use-mutter--no-xvfb./views_unittests--ozone-platform=wayland

Feel free to discuss with us on freenode.net,#ozone-wayland channel or onozone-dev, or on#ozone-wayland-x11 channel inchromium slack.

Caca

This platform draws graphical output to text usinglibcaca (no GPU support; software rendering only). In case you ever wanted to test embedded content shell on tty. It has beenremoved from the tree and is no longer maintained but you canbuild it as an out-of-tree port.

Alternatively, you can try the latest revision known to work. First, install libcaca shared library and development files. Next, move to the git revision0e64be9cf335ee3bea7c989702c5a9a0934af037 (you will probably need to synchronize the build dependencies withgclient sync --with_branch_heads). Finally, build and run the caca platform with the following commands:

gn argsout/OzoneCaca \--args="use_ozone=true ozone_platform_caca=true use_sysroot=false ozone_auto_platforms=false toolkit_views=false"ninja-Cout/OzoneCaca content_shell./out/OzoneCaca/content_shell

Note: traditional TTYs are not the ideal browsing experience.

drm

Ash-chrome client implementation.

flatland

For fuchsia.

Communication

There is a public mailing list:ozone-dev@chromium.org