Move Ozone developer documentation into the chromium tree

Move Ozone developer documentation into the chromium tree

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

Committed: https://crrev.com/8491a61260b848bed524bee5ee4ce7c3dcc09ec1
Cr-Commit-Position: refs/heads/master@{#428808}

[fwang, 2016-10-28 16:25:44]

fwang@igalia.com changed reviewers:
+ rjkroege@chromium.org, spang@chromium.org

[fwang, 2016-10-28 16:25:45]

PTAL

[rjkroege, 2016-10-28 20:22:13]

Thanks so much for doing this. Better docs at last!

https://codereview.chromium.org/2457443003/diff/160001/docs/ozone_overview.md
File docs/ozone_overview.md (right):

https://codereview.chromium.org/2457443003/diff/160001/docs/ozone_overview.md...
docs/ozone_overview.md:4: used for low level input and graphics. Once complete,
the abstraction will
The abstraction is complete already for internal-window uses. Do you want to
explain this difference perhaps?

https://codereview.chromium.org/2457443003/diff/160001/docs/ozone_overview.md...
docs/ozone_overview.md:36: tree. This is OK, and we should make this process
easy to encourage ports,
something funny in this sentence?

https://codereview.chromium.org/2457443003/diff/160001/docs/ozone_overview.md...
docs/ozone_overview.md:50: `PlatformWindow` corresponds to a `WindowTreeHost`.
Under mojo, it corresponds
What do you mean "under mojo"? You mean mus?

https://codereview.chromium.org/2457443003/diff/160001/docs/ozone_overview.md...
docs/ozone_overview.md:51: to a `NativeViewport`. On bare hardware, the
underlying windowing system is
What is a NativeViewport? This is at odds with my understanding. Per
https://cs.chromium.org/chromium/src/services/ui/ws/platform_display.cc?sq=pa...,
I claim that the ozone PlatformWindow is connected to a mus window server's
PlatformDisplay.

https://codereview.chromium.org/2457443003/diff/160001/docs/ozone_overview.md...
docs/ozone_overview.md:71: * Cleaning up extensive assumptions about use of X11
throughout the tree,
I recall that this was vaguely tedious. :-)

https://codereview.chromium.org/2457443003/diff/160001/docs/ozone_overview.md...
docs/ozone_overview.md:75: * a `WindowTreeHostOzone` to send events into Aura
and participate in display
We don't use this in mus.

https://codereview.chromium.org/2457443003/diff/160001/docs/ozone_overview.md...
docs/ozone_overview.md:128: ./out/OzoneChromeOS/chrome --ozone-platform=x11
--no-sandbox
I think it's worth noting that other platforms are available and x11 is only an
example of one?

https://codereview.chromium.org/2457443003/diff/160001/docs/ozone_overview.md...
docs/ozone_overview.md:158: ### GN Configuration notes
Awesome!

https://codereview.chromium.org/2457443003/diff/160001/docs/ozone_overview.md...
docs/ozone_overview.md:176: flag. During development you may need either to
compile and use a sandbox,
The part of me beholden to security team would like you to emphasize that
turning off the sandbox is bad and developers should fix it as soon as possible.
And maybe remove --no-sandbox so that people who don't read this carefully don't
start thinking that --no-sandbox is ok.

https://codereview.chromium.org/2457443003/diff/160001/docs/ozone_overview.md...
docs/ozone_overview.md:188: * `content_shell` always runs at 800x600 resolution
. at end?

https://codereview.chromium.org/2457443003/diff/160001/docs/ozone_overview.md...
docs/ozone_overview.md:212: (EGL/GLES2 accelerated rendering & modesetting in
GPU process).
And is in production use on ChromeOS. And maybe add a link to some kind of
ChromeOS page?

I think it's worth adding that all ChromeOS builds of Chrome will compile and
attempt to use this. You can link to
https://www.chromium.org/chromium-os/how-tos-and-troubleshooting/building-chr...
for build instructions.

[fwang, 2016-10-31 10:42:51]

Thanks for the review Robert!

https://codereview.chromium.org/2457443003/diff/160001/docs/ozone_overview.md
File docs/ozone_overview.md (right):

https://codereview.chromium.org/2457443003/diff/160001/docs/ozone_overview.md...
docs/ozone_overview.md:4: used for low level input and graphics. Once complete,
the abstraction will
On 2016/10/28 20:22:13, rjkroege wrote:
> The abstraction is complete already for internal-window uses. Do you want to
> explain this difference perhaps?

This was in the original doc, I did not change it. Let's do that in follow-up
changes.

https://codereview.chromium.org/2457443003/diff/160001/docs/ozone_overview.md...
docs/ozone_overview.md:36: tree. This is OK, and we should make this process
easy to encourage ports,
On 2016/10/28 20:22:13, rjkroege wrote:
> something funny in this sentence?

This was in the original documentation too. Not sure my English is good enough
to make a better wording, so let's do it in follow-up changes too.

https://codereview.chromium.org/2457443003/diff/160001/docs/ozone_overview.md...
docs/ozone_overview.md:50: `PlatformWindow` corresponds to a `WindowTreeHost`.
Under mojo, it corresponds
On 2016/10/28 20:22:13, rjkroege wrote:
> What do you mean "under mojo"? You mean mus?

Again in the original documentation, no ideas what is meant here. In this CL, I
just added new interfaces and removed obsolete ones. To be honest I did not try
to check whether this paragraph is (still) correct.

https://codereview.chromium.org/2457443003/diff/160001/docs/ozone_overview.md...
docs/ozone_overview.md:51: to a `NativeViewport`. On bare hardware, the
underlying windowing system is
On 2016/10/28 20:22:13, rjkroege wrote:
> What is a NativeViewport? This is at odds with my understanding. Per
>
https://cs.chromium.org/chromium/src/services/ui/ws/platform_display.cc?sq=pa...,
> I claim that the ozone PlatformWindow is connected to a mus window server's
> PlatformDisplay.

Same here, let's handle that in follow-up CLs :-)

https://codereview.chromium.org/2457443003/diff/160001/docs/ozone_overview.md...
docs/ozone_overview.md:71: * Cleaning up extensive assumptions about use of X11
throughout the tree,
On 2016/10/28 20:22:13, rjkroege wrote:
> I recall that this was vaguely tedious. :-)

:-)

https://codereview.chromium.org/2457443003/diff/160001/docs/ozone_overview.md...
docs/ozone_overview.md:75: * a `WindowTreeHostOzone` to send events into Aura
and participate in display
On 2016/10/28 20:22:13, rjkroege wrote:
> We don't use this in mus.

I'll do yet another "in the original document, handle this later" reply.

https://codereview.chromium.org/2457443003/diff/160001/docs/ozone_overview.md...
docs/ozone_overview.md:128: ./out/OzoneChromeOS/chrome --ozone-platform=x11
--no-sandbox
On 2016/10/28 20:22:13, rjkroege wrote:
> I think it's worth noting that other platforms are available and x11 is only
an
> example of one?

The original doc did that with "headless" without any explanation (BTW I changed
it to x11 since software rendering is not allowed on ChromeOS so headless does
not work) but yes I'll add a note.

https://codereview.chromium.org/2457443003/diff/160001/docs/ozone_overview.md...
docs/ozone_overview.md:176: flag. During development you may need either to
compile and use a sandbox,
On 2016/10/28 20:22:13, rjkroege wrote:
> The part of me beholden to security team would like you to emphasize that
> turning off the sandbox is bad and developers should fix it as soon as
possible.
> And maybe remove --no-sandbox so that people who don't read this carefully
don't
> start thinking that --no-sandbox is ok.

OK, I'll put back --disable-setuid-sandbox everywhere as in the original doc. I
think Antonio was able to make some cases work by building a sandbox but I was
not so lucky (I always had to use --no-sandbox).

https://codereview.chromium.org/2457443003/diff/160001/docs/ozone_overview.md...
docs/ozone_overview.md:188: * `content_shell` always runs at 800x600 resolution
On 2016/10/28 20:22:13, rjkroege wrote:
> . at end?

Acknowledged.

https://codereview.chromium.org/2457443003/diff/160001/docs/ozone_overview.md...
docs/ozone_overview.md:212: (EGL/GLES2 accelerated rendering & modesetting in
GPU process).
On 2016/10/28 20:22:13, rjkroege wrote:
> And is in production use on ChromeOS. And maybe add a link to some kind of
> ChromeOS page?
> 
> I think it's worth adding that all ChromeOS builds of Chrome will compile and
> attempt to use this. You can link to
>
https://www.chromium.org/chromium-os/how-tos-and-troubleshooting/building-chr...
> for build instructions.

OK, I'll try to add these. Again, for this and other platforms I just copy the
original doc. I suspect for each of them we should give more details about the
platform and how to build it, but probably in follow-up CLs.

[rjkroege, 2016-10-31 20:36:49]

lgtm

I'm ok with you landing this. We'll add more docs.

https://codereview.chromium.org/2457443003/diff/160001/docs/ozone_overview.md
File docs/ozone_overview.md (right):

https://codereview.chromium.org/2457443003/diff/160001/docs/ozone_overview.md...
docs/ozone_overview.md:128: ./out/OzoneChromeOS/chrome --ozone-platform=x11
--no-sandbox
On 2016/10/31 10:42:50, fwang wrote:
> On 2016/10/28 20:22:13, rjkroege wrote:
> > I think it's worth noting that other platforms are available and x11 is only
> an
> > example of one?
> 
> The original doc did that with "headless" without any explanation (BTW I
changed
> it to x11 since software rendering is not allowed on ChromeOS so headless does
> not work) but yes I'll add a note.

headless runs on the builders.

https://codereview.chromium.org/2457443003/diff/160001/docs/ozone_overview.md...
docs/ozone_overview.md:176: flag. During development you may need either to
compile and use a sandbox,
On 2016/10/31 10:42:50, fwang wrote:
> On 2016/10/28 20:22:13, rjkroege wrote:
> > The part of me beholden to security team would like you to emphasize that
> > turning off the sandbox is bad and developers should fix it as soon as
> possible.
> > And maybe remove --no-sandbox so that people who don't read this carefully
> don't
> > start thinking that --no-sandbox is ok.
> 
> OK, I'll put back --disable-setuid-sandbox everywhere as in the original doc.
I
> think Antonio was able to make some cases work by building a sandbox but I was
> not so lucky (I always had to use --no-sandbox).

I think that additional words are needed in a future CL.

[fwang, 2016-10-31 20:45:36]

https://codereview.chromium.org/2457443003/diff/160001/docs/ozone_overview.md
File docs/ozone_overview.md (right):

https://codereview.chromium.org/2457443003/diff/160001/docs/ozone_overview.md...
docs/ozone_overview.md:128: ./out/OzoneChromeOS/chrome --ozone-platform=x11
--no-sandbox
Mmh, I don't think *chrome* runs in headless mode on ChromeOS, which was the
case provided in the original doc. IIUC, the builder only runs the headless
tests.

See also
https://groups.google.com/a/chromium.org/d/msg/ozone-dev/v84vr0MaQvE/m34EP3Zm...

[fwang, 2016-10-31 20:45:55]

The CQ bit was checked by fwang@igalia.com

[commit-bot: I haz the power, 2016-10-31 20:46:34]

CQ is trying da patch. Follow status at
 
https://chromium-cq-status.appspot.com/v2/patch-status/codereview.chromium.or...

[commit-bot: I haz the power, 2016-10-31 21:01:01]

Committed patchset #10 (id:180001)

[commit-bot: I haz the power, 2016-10-31 21:02:23]

Description was changed from

==========
Move Ozone developer documentation into the chromium tree

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
==========

to

==========
Move Ozone developer documentation into the chromium tree

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

Committed: https://crrev.com/8491a61260b848bed524bee5ee4ce7c3dcc09ec1
Cr-Commit-Position: refs/heads/master@{#428808}
==========

[commit-bot: I haz the power, 2016-10-31 21:02:24]

Patchset 10 (id:??) landed as
https://crrev.com/8491a61260b848bed524bee5ee4ce7c3dcc09ec1
Cr-Commit-Position: refs/heads/master@{#428808}