Move Ozone developer documentation into the chromium tree

docs/ozone_overview.md

Index: docs/ozone_overview.md
diff --git a/docs/ozone_overview.md b/docs/ozone_overview.md
new file mode 100644
index 0000000000000000000000000000000000000000..48fe5009dcbfd15edc35ec5738c2f8824c787c70
--- /dev/null
+++ b/docs/ozone_overview.md
@@ -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)