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 | |
rjkroege
2016/10/28 20:22:13
The abstraction is complete already for internal-w
fwang
2016/10/31 10:42:51
This was in the original doc, I did not change it.
| |
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, | |
rjkroege
2016/10/28 20:22:13
something funny in this sentence?
fwang
2016/10/31 10:42:50
This was in the original documentation too. Not su
| |
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 | |
rjkroege
2016/10/28 20:22:13
What do you mean "under mojo"? You mean mus?
fwang
2016/10/31 10:42:51
Again in the original documentation, no ideas what
| |
51 to a `NativeViewport`. On bare hardware, the underlying windowing system is | |
rjkroege
2016/10/28 20:22:13
What is a NativeViewport? This is at odds with my
fwang
2016/10/31 10:42:51
Same here, let's handle that in follow-up CLs :-)
| |
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, | |
rjkroege
2016/10/28 20:22:13
I recall that this was vaguely tedious. :-)
fwang
2016/10/31 10:42:50
:-)
| |
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 | |
rjkroege
2016/10/28 20:22:13
We don't use this in mus.
fwang
2016/10/31 10:42:51
I'll do yet another "in the original document, han
| |
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 Building & running `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 ./out/OzoneChromeOS/chrome --ozone-platform=x11 --no-sandbox | |
rjkroege
2016/10/28 20:22:13
I think it's worth noting that other platforms are
fwang
2016/10/31 10:42:50
The original doc did that with "headless" without
rjkroege
2016/10/31 20:36:49
headless runs on the builders.
fwang
2016/10/31 20:45:36
Mmh, I don't think *chrome* runs in headless mode
| |
129 ``` | |
130 | |
131 ### Embedded | |
132 | |
133 The following targets are currently working for embedded builds: | |
134 | |
135 * `content_shell` | |
136 * various unit tests | |
137 | |
138 The following targets are currently NOT supported: | |
139 | |
140 * `ash_shell_with_content` | |
141 * `chrome` | |
142 | |
143 Building & running `content_shell` (do this from the `src` directory): | |
144 | |
145 ``` shell | |
146 gn args out/OzoneEmbedded --args="use_ozone=true toolkit_views=false" | |
147 ninja -C out/OzoneEmbedded content_shell | |
148 ./out/OzoneEmbedded/content_shell --no-sandbox \ | |
149 --ozone-platform=headless \ | |
150 --ozone-dump-file=/tmp/ | |
151 ``` | |
152 | |
153 ### Linux Desktop - ([bug](http://crbug.com/295089)) | |
154 | |
155 This is not supported by any of the in-tree platforms. Please see above and try | |
156 a ChromeOS or embedded build for now. | |
157 | |
158 ### GN Configuration notes | |
rjkroege
2016/10/28 20:22:13
Awesome!
| |
159 | |
160 You can turn properly implemented ozone platforms on and off by setting the | |
161 corresponding flags in your GN configuration. For example | |
162 `ozone_platform_headless=false ozone_platform_gbm=false` will turn off the | |
163 headless and DRM/GBM platforms. | |
164 This will result in a smaller binary and faster builds. To turn ALL platforms | |
165 off by default, set `ozone_auto_platforms=false`. | |
166 | |
167 You can also specify a default platform to run by setting the `ozone_platform` | |
168 build parameter. For example `ozone_platform="x11"` will make X11 the | |
169 default platform when `--ozone-platform` is not passed to the program. | |
170 If `ozone_auto_platforms` is true then `ozone_platform` is set to `headless` | |
171 by default. | |
172 | |
173 ## Running with Ozone | |
174 | |
175 Specify the platform you want to use at runtime using the `--ozone-platform` | |
176 flag. During development you may need either to compile and use a sandbox, | |
rjkroege
2016/10/28 20:22:13
The part of me beholden to security team would lik
fwang
2016/10/31 10:42:50
OK, I'll put back --disable-setuid-sandbox everywh
rjkroege
2016/10/31 20:36:49
I think that additional words are needed in a futu
| |
177 to disable the setuid sandbox (using the `--disable-setuid-sandbox` flag) or to | |
178 completly ignore the sandbox (using the `--no-sandbox` flag). | |
179 | |
180 For example, to run content_shell with the GBM platform: | |
181 | |
182 ``` shell | |
183 content_shell --no-sandbox --ozone-platform=gbm | |
184 ``` | |
185 | |
186 Caveats: | |
187 | |
188 * `content_shell` always runs at 800x600 resolution | |
rjkroege
2016/10/28 20:22:13
. at end?
fwang
2016/10/31 10:42:51
Acknowledged.
| |
189 * For the GBM platform, you may need to terminate your X server (or any other | |
190 display server) prior to testing. | |
191 | |
192 ## Ozone Platforms | |
193 | |
194 ### Headless | |
195 | |
196 This platform | |
197 draws graphical output to a PNG image (no GPU support; software rendering only) | |
198 and will not output to the screen. You can set | |
199 the path of the directory where to output the images | |
200 by specifying `--ozone-dump-file=/path/to/output-directory` on the | |
201 command line: | |
202 | |
203 ``` shell | |
204 content_shell --no-sandbox \ | |
205 --ozone-platform=headless \ | |
206 --ozone-dump-file=/tmp/ | |
207 ``` | |
208 | |
209 ### DRM/GBM | |
210 | |
211 This is Linux direct rending with acceleration via mesa GBM & linux DRM/KMS | |
212 (EGL/GLES2 accelerated rendering & modesetting in GPU process). | |
rjkroege
2016/10/28 20:22:13
And is in production use on ChromeOS. And maybe ad
fwang
2016/10/31 10:42:51
OK, I'll try to add these. Again, for this and oth
| |
213 | |
214 ### Cast | |
215 | |
216 This platform is used for | |
217 [Chromecast](https://www.google.com/intl/en_us/chromecast/). | |
218 | |
219 ### X11 | |
220 | |
221 This platform provides support for the [X window system](https://www.x.org/). | |
222 | |
223 ### Wayland | |
224 | |
225 This platform provides support for the | |
226 [Wayland](http://wayland.freedesktop.org/) display protocol. It was | |
227 initially developed by Intel as | |
228 [a fork of chromium](https://github.com/01org/ozone-wayland) | |
229 and then partially upstreamed. | |
230 It is still actively being developed in the chromium tree, feel free to discuss | |
231 with us on freenode.net, `#ozone-wayland` channel or on `ozone-dev`. | |
232 | |
233 In order to run an Ozone build of `chrome`, you currently (2016/10/28) | |
234 need to compile it for ChromeOS, where software rendering is not allowed. | |
235 Also, accelerated rendering only works in Ozone/Wayland when the UI and GPU | |
236 components are running in the same process. Below are some quick build & run | |
237 instructions. It is assumed that you are launching `chrome` from a Wayland | |
238 environment such as `weston`. | |
239 | |
240 ``` shell | |
241 gn args out/OzoneWayland --args="use_ozone=true ozone_platform_wayland=true targ et_os=\"chromeos\"" | |
242 ninja -C out/OzoneWayland chrome | |
243 ./out/OzoneWayland/chrome --ozone-platform=wayland --in-process-gpu --no-sandbox | |
244 ``` | |
245 | |
246 ### Caca | |
247 | |
248 This platform | |
249 draws graphical output to text using | |
250 [libcaca](http://caca.zoy.org/wiki/libcaca) | |
251 (no GPU support; software | |
252 rendering only). In case you ever wanted to test embedded content shell on | |
253 tty. | |
254 It has been | |
255 [removed from the tree](https://codereview.chromium.org/2445323002/) and is no | |
256 longer maintained but you can try the | |
257 [latest working revision](https://chromium.googlesource.com/chromium/src/+/0e64b e9cf335ee3bea7c989702c5a9a0934af037/ui/ozone/platform/caca/). | |
258 You need additional dependencies (libcaca shared library and development files) | |
259 that are not provided in the sysroot. Here are quick instructions to build and | |
260 run it: | |
261 | |
262 ``` shell | |
263 # Do this at revision 0e64be9cf335ee3bea7c989702c5a9a0934af037 | |
264 gclient sync --with_branch_heads | |
265 gn args out/OzoneCaca \ | |
266 --args="use_ozone=true ozone_platform_caca=true use_sysroot=false ozone_ auto_platforms=false toolkit_views=false" | |
267 ninja -C out/OzoneCaca content_shell | |
268 ./out/OzoneCaca/content_shell --no-sandbox | |
269 ``` | |
270 | |
271 Note: traditional TTYs are not the ideal browsing experience.<br/> | |
272 [![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) | |
273 | |
274 ## Communication | |
275 | |
276 There is a public mailing list: | |
277 [ozone-dev@chromium.org](https://groups.google.com/a/chromium.org/forum/#!forum/ ozone-dev) | |
OLD | NEW |