Skip to content

Commit

Permalink
Move Ozone developer documentation into the chromium tree
Browse files Browse the repository at this point in the history 
The Ozone Overview [1] is a bit old. We convert it to Markdown and move
it into the docs/ directory so that it will be easier to maintain in the
future. We also update a bit that documentation.

[1] https://www.chromium.org/developers/design-documents/ozone

BUG=None

Review-Url: https://codereview.chromium.org/2457443003
Cr-Commit-Position: refs/heads/master@{#428808}
  • Loading branch information
@fred-wang
fred-wang authored and Commit bot committed Oct 31, 2016
1 parent e51486d commit 8491a61
Showing 1 changed file with 291 additions and 0 deletions.
291 changes: 291 additions & 0 deletions docs/ozone_overview.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,291 @@
# 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.

## 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 one `ozone_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, a
`PlatformWindow` corresponds to a `WindowTreeHost`. Under mojo, it corresponds
to a `NativeViewport`. 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.
* `CursorFactoryOzone` is used to load & set platform cursors.
* `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.

## 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 the `USE_X11` ifdef, and adding a new `USE_OZONE`
path that works in a relatively platform-neutral way by delegating to the
interfaces described above.
* a `WindowTreeHostOzone` to send events into Aura and participate in display
management on the host system, and
* an Ozone-specific flavor of `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 `PlatformWindow`. This class (I'll call it
`PlatformWindowImpl`) is responsible for window system integration. It can
use `MessagePumpLibevent` to poll for events from file descriptors and then
invoke `PlatformWindowDelegate::DispatchEvent` to dispatch each event.
* Write a subclass of `SurfaceFactoryOzone` that handles allocating accelerated
surfaces. I'll call this `SurfaceFactoryOzoneImpl`.
* Write a subclass of `CursorFactoryOzone` to manage cursors, or use the
`BitmapCursorFactoryOzone` implementation if only bitmap cursors need to be
supported.
* Write a subclass of `OverlayManagerOzone` or just use `StubOverlayManager` if
your platform does not support overlays.
* Write a subclass of `NativeDisplayDelegate` if necessary or just use
`FakeDisplayDelegate`.
* Write a subclass of `GpuPlatformSupportHost` or just use
`StubGpuPlatformSupportHost`.
* Write a subclass of `InputController` or just use `StubInputController`.
* Write a subclass of `SystemInputInjector` if necessary.
* Write a subclass of `OzonePlatform` 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 a `Stub*` instance or a `nullptr`.

## 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 called `foo`.

1. Fork `chromium/src.git`.
2. Add your implementation in `ui/ozone/platform/` alongside internal platforms.
3. Patch `ui/ozone/ozone_extra.gni` to add your `foo` platform.

## Building with Ozone

### ChromeOS - ([waterfall](http://build.chromium.org/p/chromium.chromiumos/waterfall?builder=Linux+ChromiumOS+Ozone+Builder&builder=Linux+ChromiumOS+Ozone+Tests+%281%29&builder=Linux+ChromiumOS+Ozone+Tests+%282%29&reload=none))

To build `chrome`, do this from the `src` directory:

``` shell
gn args out/OzoneChromeOS --args="use_ozone=true target_os=\"chromeos\""
ninja -C out/OzoneChromeOS chrome
```

Then to run for example the X11 platform:

``` shell
./out/OzoneChromeOS/chrome --ozone-platform=x11 --disable-setuid-sandbox
```

### Embedded

The following targets are currently working for embedded builds:

* `content_shell`
* various unit tests

The following targets are currently NOT supported:

* `ash_shell_with_content`
* `chrome`

To build `content_shell`, do this from the `src` directory:

``` shell
gn args out/OzoneEmbedded --args="use_ozone=true toolkit_views=false"
ninja -C out/OzoneEmbedded content_shell
```

Then to run for example the headless platform:

``` shell
./out/OzoneEmbedded/content_shell --disable-setuid-sandbox \
--ozone-platform=headless \
--ozone-dump-file=/tmp/
```

### Linux Desktop - ([bug](http://crbug.com/295089))

This is not supported by any of the in-tree platforms. Please see above and try
a ChromeOS or embedded build for now.

### GN Configuration notes

You can turn properly implemented ozone platforms on and off by setting the
corresponding flags in your GN configuration. For example
`ozone_platform_headless=false ozone_platform_gbm=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, set `ozone_auto_platforms=false`.

You can also specify a default platform to run by setting the `ozone_platform`
build parameter. For example `ozone_platform="x11"` will make X11 the
default platform when `--ozone-platform` is not passed to the program.
If `ozone_auto_platforms` is true then `ozone_platform` is set to `headless`
by default.

## 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 GBM platform:

``` shell
content_shell --disable-setuid-sandbox --ozone-platform=gbm
```

Caveats:

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

## 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:

``` shell
content_shell --disable-setuid-sandbox \
--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 on [ChromeOS](http://www.chromium.org/chromium-os).

Note that all ChromeOS builds of Chrome will compile and attempt to use this.
See [Building Chromium for Chromium OS](https://www.chromium.org/chromium-os/how-tos-and-troubleshooting/building-chromium-browser) for build instructions.

### Cast

This platform is used for
[Chromecast](https://www.google.com/intl/en_us/chromecast/).

### X11

This platform provides support for the [X window system](https://www.x.org/).

### Wayland

This platform provides support for the
[Wayland](http://wayland.freedesktop.org/) display protocol. It was
initially developed by Intel as
[a fork of chromium](https://github.com/01org/ozone-wayland)
and then partially upstreamed.
It is still actively being developed in the chromium tree, feel free to discuss
with us on freenode.net, `#ozone-wayland` channel or on `ozone-dev`.

In order to run an Ozone build of `chrome`, you currently (2016/10/28)
need to compile it for ChromeOS, where software rendering is not allowed.
Also, accelerated rendering only works in Ozone/Wayland when the UI and GPU
components are running in the same process. Below are some quick build & run
instructions. It is assumed that you are launching `chrome` from a Wayland
environment such as `weston`.

``` shell
gn args out/OzoneWayland --args="use_ozone=true ozone_platform_wayland=true target_os=\"chromeos\""
ninja -C out/OzoneWayland chrome
./out/OzoneWayland/chrome --ozone-platform=wayland \
--in-process-gpu \
--disable-setuid-sandbox
```

### Caca

This platform
draws graphical output to text using
[libcaca](http://caca.zoy.org/wiki/libcaca)
(no GPU support; software
rendering only). In case you ever wanted to test embedded content shell on
tty.
It has been
[removed from the tree](https://codereview.chromium.org/2445323002/) and is no
longer maintained but you can try the
[latest working revision](https://chromium.googlesource.com/chromium/src/+/0e64be9cf335ee3bea7c989702c5a9a0934af037/ui/ozone/platform/caca/).
You need additional dependencies (libcaca shared library and development files)
that are not provided in the sysroot. Here are quick instructions to build and
run it:

``` shell
# Do this at revision 0e64be9cf335ee3bea7c989702c5a9a0934af037
gclient sync --with_branch_heads
gn args out/OzoneCaca \
--args="use_ozone=true ozone_platform_caca=true use_sysroot=false ozone_auto_platforms=false toolkit_views=false"
ninja -C out/OzoneCaca content_shell
./out/OzoneCaca/content_shell --disable-setuid-sandbox
```

Note: traditional TTYs are not the ideal browsing experience.<br/>
[![Picture of a workstation using Ozone/caca to display the Google home page in a text terminal](https://www.chromium.org/_/rsrc/1396307876689/developers/design-documents/ozone/IMG_20140331_151619.jpg?height=240&amp;width=320)](https://www.chromium.org/developers/design-documents/ozone/IMG_20140331_151619.jpg?attredirects=0)

## Communication

There is a public mailing list:
[ozone-dev@chromium.org](https://groups.google.com/a/chromium.org/forum/#!forum/ozone-dev)

0 comments on commit 8491a61

Please sign in to comment.