doc: output management sequence diagrams

When we were designing the libweston output API, I wrote a design document
as a Phabricator wiki page. Phabricator is no longer accessible so that
information needs to be migrated to a new place. Here I am converting most of
it into libweston Sphinx documentation, particularly pulling in the sequence
diagrams I drew. This should help people understand how libweston output
configuration works.

The diagrams are committed as both MSC source files and rendered PNG files. I
did not bother tinkering with the build to run mscgen automatically and then
with the CI images to install the tool.

The Sphinx configuration need numref explicitly enabled so that figures are
automatically numbered and can be referenced by their number rather than their
whole caption text(!).

The document structure is changed a little better flowing with Output
Management being the overview page and the Heads and Outputs being the API
pages.

First I wrote the struct weston_output and weston_head descriptions in Doxygen
comments in libweston.h, but then in the API page that text would have been
buried somewhere towards the end of the page. So I put that text in ReST
instead where it comes as first on the pages as it should. The doc for the
structs only contain a link to the top of the page. Yes, the comment style in
libweston.h is a little broken. If I left the asterisk there it would show up
as a bullet point in Sphinx. OTOH putting everything from \rst in a single line
did not produce anything.

Because Sphinx cannot look in two places, the images need to be copied into the
build dir too.

mscgen: http://www.mcternan.me.uk/mscgen/

Fixes: https://gitlab.freedesktop.org/wayland/weston/issues/25

Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>

doc/sphinx/toc/libweston/images/create_output.msc

@@ -0,0 +1,31 @@
+#!/usr/bin/mscgen -Tpng
+
+msc {
+	hscale="1.5";
+
+	c [label = "compositor"], w [label = "libweston core"],
+	b [label = "backend"];
+
+	|||;
+
+	--- [label = "Compositor creates an output for a head"];
+
+	c box c [label = "Have an existing head to process."];
+	c => w [label = "weston_compositor_create_output_with_head()"];
+	w => b [label = "weston_backend::create_output()"];
+	w << b [label = "an empty output, no hw resources"];
+	w => b [label = "weston_output::attach_head()"];
+	w << b [label = "success"];
+	c << w [label = "success"];
+
+	c abox c [label = "optionally more heads with weston_output_attach_head() for hardware clone mode."];
+
+	c :> w [label = "weston_output_set_scale()"];
+	c :> w [label = "weston_output_set_transform()"];
+	c :> b [label = "backend specific settings via plugin API"];
+	c => w [label = "weston_output_enable()"];
+	w => b [label = "weston_output::enable()"];
+	b box b [label = "hw resource allocation"];
+	w << b [label = "success"];
+	c << w [label = "success"];
+}

doc/sphinx/toc/libweston/images/destroy-output.msc

@@ -0,0 +1,29 @@
+#!/usr/bin/mscgen -Tpng
+
+msc {
+	hscale="1.5";
+
+	c [label = "compositor"], w [label = "libweston core"],
+	b [label = "backend"];
+
+	|||;
+
+	--- [label = "Compositor destroys an output for a head"];
+
+	c box c [label = "A head is found disconnected, is being destroyed, or something else needs it disabled."];
+
+	c => w [label = "weston_head_get_output()"];
+	c << w [label = "weston_output"];
+
+	c box c [label = "decide the output needs to be destroyed"];
+
+	c => w [label = "weston_output_destroy()"];
+	w => b [label = "weston_output::destroy()"];
+	w <= b [label = "weston_output_release()"];
+	w <= w [label = "weston_head_detach()"];
+	w :> b [label = "weston_output::detach_head()"];
+	w >> b [label = "release return"];
+	b box b [label = "free(output)"];
+	w << b;
+	c << w;
+}

doc/sphinx/toc/libweston/images/head-destroyed.msc

@@ -0,0 +1,26 @@
+#!/usr/bin/mscgen -Tpng
+
+msc {
+	hscale="1.5";
+
+	c [label = "compositor"], w [label = "libweston core"],
+	b [label = "backend"];
+
+	|||;
+
+	--- [label = "Head is destroyed for an enabled output"];
+
+	b box b [label = "A head disappears, e.g. MST connector is removed, not just disconnected"];
+
+	w <= b [label = "weston_head_release()"];
+	c x- w [label = "head->destroy_signal"];
+	w => w [label = "weston_head_detach()"];
+	w :> b [label = "weston_output::detach_head()"];
+	w note w [label = "No heads left in the output."];
+	w => w [label = "weston_output_disable()"];
+	w :> b [label = "weston_output::disable()"];
+	w >> b [label = "release return"];
+	b box b [label = "free(head)"];
+
+	--- [label = "The output is left disabled."];
+}

doc/sphinx/toc/libweston/images/initial-heads.msc

@@ -0,0 +1,35 @@
+#!/usr/bin/mscgen -Tpng
+
+msc {
+	hscale="1.5";
+
+	c [label = "compositor"], w [label = "libweston core"],
+	b [label = "backend"];
+
+	|||;
+
+	c => w [label = "weston_compositor_load_backend()"];
+	w => b [label = "init"];
+
+	--- [label = "Create initial heads"];
+	b box b [label = "Backend discovers an entity to create a head for."];
+
+	w <: b [label = "weston_head_init()"];
+	b box b [label = "assign hw resource to head"];
+	w <: b [label = "weston_head_set_monitor_strings()"];
+	w <: b [label = "weston_head_set_physical_size()"];
+	w <: b [label = "weston_head_set_subpixel()"];
+	w <: b [label = "weston_head_set_connection_status()"];
+	w <= b [label = "weston_compositor_add_head()"];
+	w <= w [label = "schedule heads_changed"];
+	w << b [label = "init success"];
+	c << w [label = "load success"];
+
+	|||;
+
+	--- [label = "Compositor start-up"];
+
+	c => w [label = "weston_compositor_flush_heads_changed()"];
+	c <<= w [label = "heads_changed callback"];
+
+}

doc/sphinx/toc/libweston/images/meson.build

@@ -0,0 +1,13 @@
+# Sphinx does not know look for these files in the source directory, so
+# they must be copied to the build directory.
+files = [
+	'create_output.png',
+	'destroy-output.png',
+	'head-destroyed.png',
+	'initial-heads.png',
+	'react-to-heads-changed.png',
+]
+
+foreach file : files
+	configure_file(input: file, output: file, copy: true)
+endforeach

doc/sphinx/toc/libweston/images/react-to-heads-changed.msc

@@ -0,0 +1,24 @@
+#!/usr/bin/mscgen -Tpng
+
+msc {
+	hscale="1.5";
+
+	c [label = "compositor"], w [label = "libweston core"],
+	b [label = "backend"];
+
+	|||;
+
+	--- [label = "Compositor reacts to heads_changed"];
+
+	c <<= w [label = "heads_changed callback"];
+	c box c [label = "Iterate with weston_compositor_iterate_heads(), for each head"];
+	c => w [label = "weston_head_is_connected()"];
+	c << w [label = "bool"];
+	c => w [label = "weston_head_is_enabled()"];
+	c << w [label = "bool"];
+	c => w [label = "weston_head_is_device_changed()"];
+	c << w [label = "bool"];
+	c abox c [label = "If the head needs enabling, create an output."];
+	c abox c [label = "If the head needs disabling, disable the output or destroy the output."];
+	c >> w;
+}