OLD | NEW |
(Empty) | |
| 1 # Ozone Overview |
| 2 |
| 3 Ozone is a platform abstraction layer beneath the Aura window system that is |
| 4 used for low level input and graphics. Once complete, the abstraction will |
| 5 support underlying systems ranging from embedded SoC targets to new |
| 6 X11-alternative window systems on Linux such as Wayland or Mir to bring up Aura |
| 7 Chromium by providing an implementation of the platform interface. |
| 8 |
| 9 ## Guiding Principles |
| 10 |
| 11 Our goal is to enable chromium to be used in a wide variety of projects by |
| 12 making porting to new platforms easy. To support this goal, ozone follows the |
| 13 following principles: |
| 14 |
| 15 1. **Interfaces, not ifdefs**. Differences between platforms are handled by |
| 16 calling a platform-supplied object through an interface instead of using |
| 17 conditional compilation. Platform internals remain encapsulated, and the |
| 18 public interface acts as a firewall between the platform-neutral upper |
| 19 layers (aura, blink, content, etc) and the platform-specific lower layers. |
| 20 The platform layer is relatively centralized to minimize the number of |
| 21 places ports need to add code. |
| 22 2. **Flexible interfaces**. The platform interfaces should encapsulate just what |
| 23 chrome needs from the platform, with minimal constraints on the platform's |
| 24 implementation as well as minimal constraints on usage from upper layers. An |
| 25 overly prescriptive interface is less useful for porting because fewer ports |
| 26 will be able to use it unmodified. Another way of stating is that the |
| 27 platform layer should provide mechanism, not policy. |
| 28 3. **Runtime binding of platforms**. Avoiding conditional compilation in the |
| 29 upper layers allows us to build multiple platforms into one binary and bind |
| 30 them at runtime. We allow this and provide a command-line flag to select a |
| 31 platform (`--ozone-platform`) if multiple are enabled. Each platform has a |
| 32 unique build define (e.g. `ozone_platform_foo`) that can be turned on or off |
| 33 independently. |
| 34 4. **Easy out-of-tree platforms**. Most ports begin as forks. Some of them |
| 35 later merge their code upstream, others will have an extended life out of |
| 36 tree. This is OK, and we should make this process easy to encourage ports, |
| 37 and to encourage frequent gardening of chromium changes into the downstream |
| 38 project. If gardening an out-of-tree port is hard, then those projects will |
| 39 simply ship outdated and potentially insecure chromium-derived code to users. |
| 40 One way we support these projects is by providing a way to inject additional |
| 41 platforms into the build by only patching one `ozone_extra.gni` file. |
| 42 |
| 43 ## Ozone Platform Interface |
| 44 |
| 45 Ozone moves platform-specific code behind the following interfaces: |
| 46 |
| 47 * `PlatformWindow` represents a window in the windowing system underlying |
| 48 chrome. Interaction with the windowing system (resize, maximize, close, etc) |
| 49 as well as dispatch of input events happens via this interface. Under aura, a |
| 50 `PlatformWindow` corresponds to a `WindowTreeHost`. Under mojo, it corresponds |
| 51 to a `NativeViewport`. On bare hardware, the underlying windowing system is |
| 52 very simple and a platform window corresponds to a physical display. |
| 53 * `SurfaceFactoryOzone` is used to create surfaces for the Chrome compositor to |
| 54 paint on using EGL/GLES2 or Skia. |
| 55 * `GpuPlatformSupportHost` provides the platform code |
| 56 access to IPC between the browser & GPU processes. Some platforms need this |
| 57 to provide additional services in the GPU process such as display |
| 58 configuration. |
| 59 * `CursorFactoryOzone` is used to load & set platform cursors. |
| 60 * `OverlayManagerOzone` is used to manage overlays. |
| 61 * `InputController` allows to control input devices such as keyboard, mouse or |
| 62 touchpad. |
| 63 * `SystemInputInjector` converts input into events and injects them to the |
| 64 Ozone platform. |
| 65 * `NativeDisplayDelegate` is used to support display configuration & hotplug. |
| 66 |
| 67 ## Ozone in Chromium |
| 68 |
| 69 Our implementation of Ozone required changes concentrated in these areas: |
| 70 |
| 71 * Cleaning up extensive assumptions about use of X11 throughout the tree, |
| 72 protecting this code behind the `USE_X11` ifdef, and adding a new `USE_OZONE` |
| 73 path that works in a relatively platform-neutral way by delegating to the |
| 74 interfaces described above. |
| 75 * a `WindowTreeHostOzone` to send events into Aura and participate in display |
| 76 management on the host system, and |
| 77 * an Ozone-specific flavor of `GLSurfaceEGL` which delegates allocation of |
| 78 accelerated surfaces and refresh syncing to the provided implementation of |
| 79 `SurfaceFactoryOzone`. |
| 80 |
| 81 ## Porting with Ozone |
| 82 |
| 83 Users of the Ozone abstraction need to do the following, at minimum: |
| 84 |
| 85 * Write a subclass of `PlatformWindow`. This class (I'll call it |
| 86 `PlatformWindowImpl`) is responsible for window system integration. It can |
| 87 use `MessagePumpLibevent` to poll for events from file descriptors and then |
| 88 invoke `PlatformWindowDelegate::DispatchEvent` to dispatch each event. |
| 89 * Write a subclass of `SurfaceFactoryOzone` that handles allocating accelerated |
| 90 surfaces. I'll call this `SurfaceFactoryOzoneImpl`. |
| 91 * Write a subclass of `CursorFactoryOzone` to manage cursors, or use the |
| 92 `BitmapCursorFactoryOzone` implementation if only bitmap cursors need to be |
| 93 supported. |
| 94 * Write a subclass of `OverlayManagerOzone` or just use `StubOverlayManager` if |
| 95 your platform does not support overlays. |
| 96 * Write a subclass of `NativeDisplayDelegate` if necessary or just use |
| 97 `FakeDisplayDelegate`. |
| 98 * Write a subclass of `GpuPlatformSupportHost` or just use |
| 99 `StubGpuPlatformSupportHost`. |
| 100 * Write a subclass of `InputController` or just use `StubInputController`. |
| 101 * Write a subclass of `SystemInputInjector` if necessary. |
| 102 * Write a subclass of `OzonePlatform` that owns instances of |
| 103 the above subclasses and provide a static constructor function for these |
| 104 objects. This constructor will be called when |
| 105 your platform is selected and the returned objects will be used to provide |
| 106 implementations of all the ozone platform interfaces. |
| 107 If your platform does not need some of the interfaces then you can just |
| 108 return a `Stub*` instance or a `nullptr`. |
| 109 |
| 110 ## Adding an Ozone Platform to the build (instructions for out-of-tree ports) |
| 111 |
| 112 The recommended way to add your platform to the build is as follows. This walks |
| 113 through creating a new ozone platform called `foo`. |
| 114 |
| 115 1. Fork `chromium/src.git`. |
| 116 2. Add your implementation in `ui/ozone/platform/` alongside internal platforms. |
| 117 3. Patch `ui/ozone/ozone_extra.gni` to add your `foo` platform. |
| 118 |
| 119 ## Building with Ozone |
| 120 |
| 121 ### ChromeOS - ([waterfall](http://build.chromium.org/p/chromium.chromiumos/wate
rfall?builder=Linux+ChromiumOS+Ozone+Builder&builder=Linux+ChromiumOS+Ozone+Test
s+%281%29&builder=Linux+ChromiumOS+Ozone+Tests+%282%29&reload=none)) |
| 122 |
| 123 To build `chrome`, do this from the `src` directory: |
| 124 |
| 125 ``` shell |
| 126 gn args out/OzoneChromeOS --args="use_ozone=true target_os=\"chromeos\"" |
| 127 ninja -C out/OzoneChromeOS chrome |
| 128 ``` |
| 129 |
| 130 Then to run for example the X11 platform: |
| 131 |
| 132 ``` shell |
| 133 ./out/OzoneChromeOS/chrome --ozone-platform=x11 --disable-setuid-sandbox |
| 134 ``` |
| 135 |
| 136 ### Embedded |
| 137 |
| 138 The following targets are currently working for embedded builds: |
| 139 |
| 140 * `content_shell` |
| 141 * various unit tests |
| 142 |
| 143 The following targets are currently NOT supported: |
| 144 |
| 145 * `ash_shell_with_content` |
| 146 * `chrome` |
| 147 |
| 148 To build `content_shell`, do this from the `src` directory: |
| 149 |
| 150 ``` shell |
| 151 gn args out/OzoneEmbedded --args="use_ozone=true toolkit_views=false" |
| 152 ninja -C out/OzoneEmbedded content_shell |
| 153 ``` |
| 154 |
| 155 Then to run for example the headless platform: |
| 156 |
| 157 ``` shell |
| 158 ./out/OzoneEmbedded/content_shell --disable-setuid-sandbox \ |
| 159 --ozone-platform=headless \ |
| 160 --ozone-dump-file=/tmp/ |
| 161 ``` |
| 162 |
| 163 ### Linux Desktop - ([bug](http://crbug.com/295089)) |
| 164 |
| 165 This is not supported by any of the in-tree platforms. Please see above and try |
| 166 a ChromeOS or embedded build for now. |
| 167 |
| 168 ### GN Configuration notes |
| 169 |
| 170 You can turn properly implemented ozone platforms on and off by setting the |
| 171 corresponding flags in your GN configuration. For example |
| 172 `ozone_platform_headless=false ozone_platform_gbm=false` will turn off the |
| 173 headless and DRM/GBM platforms. |
| 174 This will result in a smaller binary and faster builds. To turn ALL platforms |
| 175 off by default, set `ozone_auto_platforms=false`. |
| 176 |
| 177 You can also specify a default platform to run by setting the `ozone_platform` |
| 178 build parameter. For example `ozone_platform="x11"` will make X11 the |
| 179 default platform when `--ozone-platform` is not passed to the program. |
| 180 If `ozone_auto_platforms` is true then `ozone_platform` is set to `headless` |
| 181 by default. |
| 182 |
| 183 ## Running with Ozone |
| 184 |
| 185 Specify the platform you want to use at runtime using the `--ozone-platform` |
| 186 flag. Disabling the setuid sandbox may be required during development. |
| 187 |
| 188 For example, to run content_shell with the GBM platform: |
| 189 |
| 190 ``` shell |
| 191 content_shell --disable-setuid-sandbox --ozone-platform=gbm |
| 192 ``` |
| 193 |
| 194 Caveats: |
| 195 |
| 196 * `content_shell` always runs at 800x600 resolution. |
| 197 * For the GBM platform, you may need to terminate your X server (or any other |
| 198 display server) prior to testing. |
| 199 |
| 200 ## Ozone Platforms |
| 201 |
| 202 ### Headless |
| 203 |
| 204 This platform |
| 205 draws graphical output to a PNG image (no GPU support; software rendering only) |
| 206 and will not output to the screen. You can set |
| 207 the path of the directory where to output the images |
| 208 by specifying `--ozone-dump-file=/path/to/output-directory` on the |
| 209 command line: |
| 210 |
| 211 ``` shell |
| 212 content_shell --disable-setuid-sandbox \ |
| 213 --ozone-platform=headless \ |
| 214 --ozone-dump-file=/tmp/ |
| 215 ``` |
| 216 |
| 217 ### DRM/GBM |
| 218 |
| 219 This is Linux direct rending with acceleration via mesa GBM & linux DRM/KMS |
| 220 (EGL/GLES2 accelerated rendering & modesetting in GPU process) and is in |
| 221 production use on [ChromeOS](http://www.chromium.org/chromium-os). |
| 222 |
| 223 Note that all ChromeOS builds of Chrome will compile and attempt to use this. |
| 224 See [Building Chromium for Chromium OS](https://www.chromium.org/chromium-os/how
-tos-and-troubleshooting/building-chromium-browser) for build instructions. |
| 225 |
| 226 ### Cast |
| 227 |
| 228 This platform is used for |
| 229 [Chromecast](https://www.google.com/intl/en_us/chromecast/). |
| 230 |
| 231 ### X11 |
| 232 |
| 233 This platform provides support for the [X window system](https://www.x.org/). |
| 234 |
| 235 ### Wayland |
| 236 |
| 237 This platform provides support for the |
| 238 [Wayland](http://wayland.freedesktop.org/) display protocol. It was |
| 239 initially developed by Intel as |
| 240 [a fork of chromium](https://github.com/01org/ozone-wayland) |
| 241 and then partially upstreamed. |
| 242 It is still actively being developed in the chromium tree, feel free to discuss |
| 243 with us on freenode.net, `#ozone-wayland` channel or on `ozone-dev`. |
| 244 |
| 245 In order to run an Ozone build of `chrome`, you currently (2016/10/28) |
| 246 need to compile it for ChromeOS, where software rendering is not allowed. |
| 247 Also, accelerated rendering only works in Ozone/Wayland when the UI and GPU |
| 248 components are running in the same process. Below are some quick build & run |
| 249 instructions. It is assumed that you are launching `chrome` from a Wayland |
| 250 environment such as `weston`. |
| 251 |
| 252 ``` shell |
| 253 gn args out/OzoneWayland --args="use_ozone=true ozone_platform_wayland=true targ
et_os=\"chromeos\"" |
| 254 ninja -C out/OzoneWayland chrome |
| 255 ./out/OzoneWayland/chrome --ozone-platform=wayland \ |
| 256 --in-process-gpu \ |
| 257 --disable-setuid-sandbox |
| 258 ``` |
| 259 |
| 260 ### Caca |
| 261 |
| 262 This platform |
| 263 draws graphical output to text using |
| 264 [libcaca](http://caca.zoy.org/wiki/libcaca) |
| 265 (no GPU support; software |
| 266 rendering only). In case you ever wanted to test embedded content shell on |
| 267 tty. |
| 268 It has been |
| 269 [removed from the tree](https://codereview.chromium.org/2445323002/) and is no |
| 270 longer maintained but you can try the |
| 271 [latest working revision](https://chromium.googlesource.com/chromium/src/+/0e64b
e9cf335ee3bea7c989702c5a9a0934af037/ui/ozone/platform/caca/). |
| 272 You need additional dependencies (libcaca shared library and development files) |
| 273 that are not provided in the sysroot. Here are quick instructions to build and |
| 274 run it: |
| 275 |
| 276 ``` shell |
| 277 # Do this at revision 0e64be9cf335ee3bea7c989702c5a9a0934af037 |
| 278 gclient sync --with_branch_heads |
| 279 gn args out/OzoneCaca \ |
| 280 --args="use_ozone=true ozone_platform_caca=true use_sysroot=false ozone_
auto_platforms=false toolkit_views=false" |
| 281 ninja -C out/OzoneCaca content_shell |
| 282 ./out/OzoneCaca/content_shell --disable-setuid-sandbox |
| 283 ``` |
| 284 |
| 285 Note: traditional TTYs are not the ideal browsing experience.<br/> |
| 286 [![Picture of a workstation using Ozone/caca to display the Google home page i
n a text terminal](https://www.chromium.org/_/rsrc/1396307876689/developers/desi
gn-documents/ozone/IMG_20140331_151619.jpg?height=240&width=320)](https://ww
w.chromium.org/developers/design-documents/ozone/IMG_20140331_151619.jpg?attredi
rects=0) |
| 287 |
| 288 ## Communication |
| 289 |
| 290 There is a public mailing list: |
| 291 [ozone-dev@chromium.org](https://groups.google.com/a/chromium.org/forum/#!forum/
ozone-dev) |
OLD | NEW |