For Developers‎ > ‎Design Documents‎ > ‎

Ozone Overview

We have recently started adding the Ozone meta-platform to Chromium. Ozone is an abstraction beneath the Aura window system 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 without needing additional platform code added to the Chromium source tree.

Ozone moves all platform-specific code behind the following interfaces: 
  • SurfaceFactoryOzone is used to create surfaces for the Chrome compositor to paint on using EGL or Skia.
  • EventFactoryOzone is used to initiate dispatching of input events (ui::Event) from the platform into aura.
  • CursorFactoryOzone is used to load & set platform cursors.

Ozone in Chromium

Our implementation of Ozone required changes concentrated in three areas of the codebase:
  • providing a new base::MessagePumpOzone that can watch an arbitrary file descriptor for incoming events
  • a ui::WindowTreeHostOzone to send events into Aura and participate in display management on the host system, and
  • an Ozone-specific flavor of gfx::GLSurfaceEGL which delegates allocation of accelerated surfaces and refresh syncing to the provided implementation of SurfaceFactoryOzone.

Porting with Ozone

Users of the Ozone abstraction need to do the following, at minimum:
  • Write a subclass of gfx::SurfaceFactoryOzone that handles allocating accelerated surfaces. I'll call this SurfaceFactoryOzoneImpl but as this code can lie outside of the Chromium tree, feel free to name as you deem appropriate.
  • Write a subclass of ui::EventFactoryOzone. This class (I'll call it EventFactoryOzoneImpl) is responsible for dispatching input events. It can use base::MessagePumpOzone to poll for events from file descriptors and then invoke ui::EventFactoryOzone::DispatchEvent to dispatch each event.
  • Write a subclass of ui::OzonePlatform that owns instances of your gfx::SurfaceFactoryOzone and ui::EventFactoryOzone and provide a static constructor function for this object. This constructor will be called when your platform is selected and the returned object will be used to provide implementations of all the ozone platform interfaces.

Adding an Ozone Platform to the build

The recommended way to add your platform to the build is as follows. This walks through creating a new ozone platform called foo.
  1. Check out your code at src/ozone-foo.
  2. Create a file called src/ozone-foo/supplement.gypi with the following contents:
    { 'variables': { 'ozone_platform_foo%': 1, }, 'conditions': [ ['<(ozone_platform_foo) == 1', { 'variables': { 'external_ozone_platform_deps': [ '<(DEPTH)/ozone-foo/foo.gyp:foo', ], 'external_ozone_platforms': [ 'foo' ], 'ozone_platform%': 'foo', }, }], ], }
  3. Create a file called src/ozone-foo/foo.gyp with the following contents:
    { 'targets': [ { 'target_name': 'foo', 'type': 'static_library', 'dependencies': [ '<(DEPTH)/base/base.gyp:base', '<(DEPTH)/ui/gfx/gfx.gyp:gfx', '<(DEPTH)/ui/events/events.gyp:events', # additional dependencies for your platform ], 'include_dirs': [ '..', ], 'sources': [ 'ozone_platform_foo.cc', 'ozone_platform_foo.h', 'surface_factory_foo.cc', 'surface_factory_foo.h', 'event_factory_foo.cc', 'event_factory_foo.h', # additional source files for your platform ], }, ] }
  4. Write a constructor function for your platform. It must be called ui::CreateOzonePlatformFoo. Put this function in the source file for your OzonePlatform subclass.
    OzonePlatform* CreateOzonePlatformFoo() { return new OzonePlatformFoo; }

Building with Ozone

The following targets are currently working:
  • content_shell
  • various unit tests
The following targets are currently NOT working:
  • ash_shell
  • chrome
    Building & running content_shell (do this from the src directory):

    GYP_DEFINES="use_aura=1 use_ash=0 toolkit_views=0 use_ozone=1" gclient runhooks
    ninja -C out/Debug content_shell
    ./out/Debug/content_shell --disable-setuid-sandbox

    GYP Configuration notes:

    • Ozone cannot be used without aura. Always specify use_aura=1 in your GYP_DEFINES
    • Ash does not yet build with ozone. Specify use_ash=0 in your GYP_DEFINES until this is fixed.
    • If you set chromeos=1 a single native window will created that will contain all chrome windows. However, you will also get some unnecessary ChromeOS support code. We are working to untangle the "single window" mode from ChromeOS.
    • You can turn properly implemented ozone platforms on and off with GYP_DEFINES. For example
      GYP_DEFINES="use_aura=1 use_ash=0 use_ozone=1 ozone_platform_dri=0 ozone_platform_test=0"
      will turn off the current in-tree platforms. This will result in a smaller binary and faster builds.

    Running with Ozone

    Specify the platform you want to use at runtime using the --ozone-platform flag. Disabling the setuid sandbox may be required during development.

    For example, to run content_shell with the DRI platform:

    content_shell --disable-setuid-sandbox --ozone-platform=dri

    If no platform is specified, the "test" platform is selected by default. This platform dumps images to a file and will not output to the screen. You can set the image path by specifying --ozone-dump-file=/path/to/image.png on the command line:

    content_shell --disable-setuid-sandbox --ozone-platform=test --ozone-dump-file=/tmp/ozone.png

    Caveats:

    • content_shell always runs at 800x600 resolution
    • For the DRI platform, you may need to terminate your X server (or any other display server) prior to testing.

    Ozone Platforms

    Internal platforms:
    • dri - Linux direct rendering
    • test - Dumps images
    • caca - Uses libcaca to display on a tty in case you ever wanted to test embedded content shell on tty. Add libcaca to your favourite Chromium development workstation and build like so:
    GYP_DEFINES="use_aura=1 use_ash=0 toolkit_views=0 use_ozone=1 ozone_platform_caca=1" gclient runhooks
    ninja -C out/Debug content_shell
    out/Debug/content_shell --disable-setuid-sandbox --ozone-platform=caca 

    Note: traditional TTYs are not the ideal browsing experience.




    External platform projects:

    Communication

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

    Coming Soon

    The Ozone abstraction was first designed for the Ash window management approach where Chromium controls the entire display. This is not sufficient to fully support a foreign multi-window desktop.  We are currently working with contributors from Intel to generalize Ozone sufficiently so that it is adequate for DesktopAura-style Chromium ports such as a port of Aura Chromium to the Wayland platform.





    Comments