Import web site into git before it gets out of hand

author: Kristian Høgsberg <krh@bitplanet.net> 2010-10-29 16:21:56 -0400
committer: Kristian Høgsberg <krh@bitplanet.net> 2010-10-29 16:21:56 -0400
commit: 626c34712d4e7b427a8e6706e49d1cb3a681a821 (patch)
tree: 7619b19fbf2bd98b564817520ce127dfb513652b
19 files changed, 444 insertions, 0 deletions
diff --git a/architecture.html b/architecture.html
new file mode 100644
index 0000000..166f728
--- /dev/null
+++ b/architecture.html
@@ -0,0 +1,216 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> 
+<html> 
+
+<head> 
+<meta http-equiv="Content-Type" content="text/html;charset=utf-8"> 
+<link href="wayland.css" rel="stylesheet" type="text/css">
+<title>Wayland</title> 
+</head>
+
+<body>
+<h1><img src="wayland.png"></h1>
+
+<h2>Wayland Architecture</h2>
+
+<p>A good way to understand the wayland architecture and how it is
+different from X is to follow an event from the input device to the
+point where the change it affects appears on screen.</p>
+
+<p>This is where we are now with X:</p>
+<img src="x-architecture.png">
+
+<ol>
+  <li>
+    The kernel gets an event from an input device and sends it to X
+    through the evdev input driver.  The kernel does all the hard work
+    here by driving the device and translating the different device
+    specific event protocols to the linux evdev input event standard.
+  </li>
+
+  <li>
+    The X server determines which window the event affects and sends
+    it to the clients that have selected for the event in question on
+    that window.  The X server doesn't actually know how to do this
+    right, since the window location on screen is controlled by the
+    compositor and may be transformed in a number of ways that the X
+    server doesn't understand (scaled down, rotated, wobbling,
+    etc).
+  </li>
+
+  <li>
+    The client looks at the event and decides what to do.  Often the
+    UI will have to change in response to the event - perhaps a check
+    box was clicked or the pointer entered a button that must be
+    highlighted.  Thus the client sends a rendering request back to
+    the X server.
+  </li>
+
+  <li>
+    When the X server receives the rendering request, it sends it to
+    the driver to let it program the hardware to do the rendering.
+    The X server also calculates the bounding region of the rendering,
+    and sends that to the compositor as a <em>damage event</em>.
+  </li>
+
+  <li>
+    The damage event tells the compositor that something changed in
+    the window and that it has to recomposite the part of the screen
+    where that window is visible.  The compositor is responsible for
+    rendering the entire screen contents based on its scenegraph and
+    the contents of the X windows.  Yet, it has to go through the X
+    server to render this.
+  </li>
+
+  <li>
+    The X server receives the rendering requests from the compositor
+    and either copies the compositor back buffer to the front buffer
+    or does a pageflip.  In the general case, the X server has to do
+    this step so it can account for overlapping windows, which may
+    require clipping and determine whether or not it can page flip.
+    However, for a compositor, which is always fullscreen, this is
+    another unnecessary context switch.
+  </li>
+</ol>
+
+<p>
+  As suggested above, there are a few problems with this approach.
+  The X server doesn't have the information to decide which window
+  should receive the event, nor can it transform the screen
+  coordinates to window local coordinates.  And even though X has
+  handed responsibility for the final painting of the screen to the
+  compositing manager, X still controls the front buffer and
+  modesetting.  Most of the complexity that the X server used to
+  handle is now available in the kernel or self contained libraries
+  (KMS, evdev, mesa, fontconfig, freetype, cairo, Qt etc).  In
+  general, the X server is now just a middle man that introduces an
+  extra step between applications and the compositor and an extra step
+  between the compositor and the hardware.
+</p>
+
+<p>
+  In wayland the compositor <em>is</em> the display server.  We
+  transfer the control of KMS and evdev to the compositor.  The
+  wayland protocol lets the compositor send the input events directly
+  to the clients and lets the client send the damage event directly to
+  the compositor:
+</p>
+
+<img src="wayland-architecture.png">
+
+<ol>
+  <li>
+    The kernel gets an event and sends it to the compositor.  This is
+    similar to the X case, which is great, since we get to reuse all
+    the input drivers in the kernel.
+  </li>
+
+  <li>
+    The compositor looks through its scenegraph to determine which
+    window should receive the event.  The scenegraph corresponds to
+    what's on screen and the compositor understands the
+    transformations that it may have applied to the elements in the
+    scenegraph.  Thus, the compositor can pick the right window and
+    transform the screen coordinates to window local coordinates, by
+    applying the inverse transformations.  The types of transformation
+    that can be applied to a window is only restriced to what the
+    compositor can do, as long as it can compute the inverse
+    transformation for the input events.
+  </li>
+
+  <li>
+    As in the X case, when the client receives the event, it updates
+    the UI in response.  But in the wayland case, the rendering
+    happens in the client, and the client just sends a request to the
+    compositor to indicate the region that was updated.
+  </li>
+
+  <li>
+    The compositor collects damage requests from its clients and then
+    recomposites the screen.  The compositor can then directly issue
+    an ioctl to schedule a pageflip with KMS.
+  </li>
+</ol>
+
+<h2>Wayland Rendering</h2>
+
+<p>
+  One of the details I left out in the above overview is how clients
+  actually render under wayland.  By removing the X server from the
+  picture we also removed the mechanism by which X clients typically
+  render.  But there's another mechanism that we're already using with
+  DRI2 under X: <em>direct rendering</em>.  With direct rendering, the
+  client and the server share a video memory buffer.  The client links
+  to a rendering library such as OpenGL that knows how to program the
+  hardware and renders directly into the buffer.  The compositor in
+  turn can take the buffer and use it as a texture when it composites
+  the desktop.  After the initial setup, the client only needs to tell
+  the compositor which buffer to use and when and where it has
+  rendered new content into it.
+</p>
+
+<p>
+  This leaves an application with two ways to update its window
+  contents:
+</p>
+
+<ol>
+  <li>
+    Render the new content into a new buffer and tell the compositor
+    to use that instead of the old buffer.  The application can
+    allocate a new buffer every time it needs to update the window
+    contents or it can keep two (or more) buffers around and cycle
+    between them.  The buffer management is entirely under application
+    control.
+  </li>
+
+  <li>
+    Render the new content into the buffer that it previously told the
+    compositor to to use.  While it's possible to just render directly
+    into the buffer shared with the compositor, this might race with
+    the compositor.  What can happen is that repainting the window
+    contents could be interrupted by the compositor repainting the
+    desktop.  If the application gets interrupted just after clearing
+    the window but before rendering the contents, the compositor will
+    texture from a blank buffer.  The result is that the application
+    window will flicker between a blank window or half-rendered
+    content.  The traditional way to avoid this is to render the new
+    content into a back buffer and then copy from there into the
+    compositor surface.  The back buffer can be allocated on the fly
+    and just big enough to hold the new content, or the application
+    can keep a buffer around.  Again, this is under application
+    control.
+  </li>
+</ol>
+
+<p>
+  In either case, the application must tell the compositor which area
+  of the surface holds new contents.  When the application renders
+  directly the to shared buffer, the compositor needs to be noticed
+  that there is new content.  But also when exchanging buffers, the
+  compositor doesn't assume anything changed, and needs a request from
+  the application before it will repaint the desktop.  The idea that
+  even if an application passes a new buffer to the compositor, only a
+  small part of the buffer may be different, like a blinking cursor or
+  a spinner.
+</p>
+
+<h2>X as a Wayland Client</h2>
+
+<p>
+  Wayland is a complete window system in itself, but even so, if we're
+  migrating away from X, it makes sense to have a good backwards
+  compatibility story.  With a few changes, the Xorg server can be
+  modified to use wayland input devices for input and forward either
+  the root window or individual top-level windows as wayland surfaces.
+  The server still runs the same 2D driver with the same acceleration
+  code as it does when it runs natively, the main difference is that
+  wayland handles presentation of the windows instead of KMS.
+</p>
+
+<img src="x-on-wayland.png">
+
+
+<!-- -->
+
+</body>
+</html> 
diff --git a/building.html b/building.html
new file mode 100644
index 0000000..f45e77b
--- /dev/null
+++ b/building.html
@@ -0,0 +1,136 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> 
+<html> 
+
+<head> 
+<meta http-equiv="Content-Type" content="text/html;charset=utf-8"> 
+<link href="wayland.css" rel="stylesheet" type="text/css">
+<title>Wayland</title> 
+</head>
+
+<body>
+<h1><img src="wayland.png"></h1>
+
+<p>The instructions below assume some familiarity with git and
+building and running experimental software.  And be prepared that this
+project isn't at all useful right now, it's still very much a
+prototype.  When the instructions suggest to clone a git repo, you can
+of course just add a remote and fetch instead, if you have a clone of
+that repo around already.  I usually install all software I'm working
+on into $HOME/install, so that's what I'll use in the instructions
+below, but you can use your favorite directory of course or install
+over your system copy (pass --prefix=/usr --sysconfdir=/etc,
+generally).</p>
+
+<h2>Modesetting</h2>
+
+<p>At this point, kernel modesetting is upstream for Intel, AMD and
+nVidia chipsets.  Most distributions ship with kernel modesetting
+enabled by default and will work with Wayland out of the box.  The
+modesetting driver must also support the page flip ioctl, which only
+the intel driver does at this point.</p>
+
+
+<h2>Building mesa</h2>
+
+<p>Wayland uses the mesa EGL stack, and all extensions required to run
+EGL on KMS are now upstream on the master branch.  The 7.9 release of
+mesa has all these extensions, but for the shm buffer feature you'll
+need the GL_EXT_texture_format_BGRA8888 extension from mesa
+master:</p>
+
+<pre>
+    $ git clone git://anongit.freedesktop.org/mesa/mesa
+    $ cd mesa
+    $ ./configure --prefix=$HOME/install  --enable-egl --enable-gles2
+    $ make && make install
+</pre>
+
+<p>If you're using an intel chipset, it's best to also pass
+<code>--disable-gallium</code> to ./configure, since otherwise libEGL
+will try to load the gallium sw rasterizer before loading the Intel
+DRI driver.</p>
+
+
+<h2>libxkbcommon</h2>
+
+<p>Wayland needs libxkbcommon for translating evdev keycodes to
+keysyms.  There's a couple of repos around, and we're trying to
+consolidate the development, but for wayland you'll need the repo from
+my get repository.  For this you'll need development packages for
+xproto, kbproto and libX11.</p>
+
+<pre>
+    $ git clone git://people.freedesktop.org/xorg/lib/libxkbcommon.git
+    $ cd libxkbcommon/
+    $ ./autogen.sh --prefix=$HOME/install
+    $ make && make install
+</pre>
+
+<h2>cairo-gl</h2>
+
+<p>The Wayland clients can render using cairo-gl, but fall back to
+software when cairo-gl is not available.  cairo-gl is an experimental
+cairo backend and has been available since cairo 1.10.  Unless your
+distribution ships cairo with the gl backend enabled, you'll need to
+compile your own version of cairo:</p>
+
+<pre>
+    $ git clone git://anongit.freedesktop.org/cairo
+    $ cd cairo
+    $ ./autogen.sh --prefix=$HOME/install --enable-gl
+    $ make && make install
+</pre>
+
+<h2>Wayland</h2>
+
+<p>With mesa and libxkbcommon in place, we can checkout and build
+Wayland.  Aside from mesa, Wayland needs development packages for
+gdk-pixbuf-2.0, libudev, libdrm, xcb-dri2, xcb-fixes (for X
+compositor) cairo-gl, glib-2.0, gdk-2.0 (for poppler) and
+poppler-glib:</p>
+
+<pre>
+    $ git clone git://people.freedesktop.org/~krh/wayland
+    $ aclocal; autoconf; ./configure --prefix=$HOME/install
+    $ make && make install
+</pre>
+
+<p>Installing into a non-/usr prefix is fine, but the 70-wayland.rules
+udev rule file has to be installed in /etc/udev/rules.d.  Once
+installed, either reboot or run</p>
+
+<pre>
+    $ sudo udevadm trigger --subsystem-match=drm --subsystem-match=input
+</pre>
+
+<p>to make udev label the devices wayland will use.</p>
+
+<p>If DISPLAY is set, the wayland compositor will run under X in a
+window and take input from X.  Otherwise it will run on the KMS
+framebuffer and take input from evdev devices.  Pick a background
+image that you like and copy it to the Wayland source directory as
+background.jpg or use the -b command line option:</p>
+
+<pre>
+    $ ./wayland-system-compositor -b my-image.jpg
+</pre>
+
+<p>To run clients, switch to a different VT and run the client from
+there.  Or run it under X and start up the clients from a terminal
+window.  There are a few demo clients available, but they are all
+pretty simple and mostly for testing specific features in the wayland
+protocol: 'terminal' is a simple terminal emulator, not very compliant
+at all, but works well enough for bash</p>
+
+<ul>
+  <li>'flower' moves a flower around the screen, testing the frame protocol</li>
+  <li>'gears' glxgears, but for wayland, currently broken</li>
+  <li>'image' loads the image files passed on the command line and
+  shows them</li>
+
+  <li>'view' does the same for pdf files, but needs file URIs
+    (file:///path/to/pdf)</li>
+</ul>
+
+</body>
+</html>
diff --git a/clutter-flowers.png b/clutter-flowers.png
new file mode 100644
index 0000000..9ffa898
--- /dev/null
+++ b/clutter-flowers.png
diff --git a/clutter-hands.png b/clutter-hands.png
new file mode 100644
index 0000000..aed5603
--- /dev/null
+++ b/clutter-hands.png
diff --git a/index.html b/index.html
new file mode 100644
index 0000000..e4422af
--- /dev/null
+++ b/index.html
@@ -0,0 +1,37 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> 
+<html> 
+
+<head> 
+<meta http-equiv="Content-Type" content="text/html;charset=utf-8"> 
+<link href="wayland.css" rel="stylesheet" type="text/css">
+<title>Wayland</title> 
+</head>
+
+<body>
+<h1><img src="wayland.png"></h1>
+
+<h2>Wayland</h2>
+
+<p>Wayland is a protocol for a compositor to talk to its clients as
+well as a C library implementation of that protocol.  The compositor
+can be a standalone display server running on Linux kernel modesetting
+and evdev input devices, an X application, or a wayland client itself.
+The clients can be traditional applications, X servers (rootless or
+fullscreen) or other display servers.</p>
+
+<p>The wayland repository includes a compositor which can run as an X
+client or under Linux KMS and a few clients, but both the compositor
+and clients are essentially test cases.</p>
+
+<ul>
+  <li><a href="architecture.html">Wayland architecture</a></li>
+  <li><a href="building.html">Building wayland</a></li>
+  <li><a href="http://cgit.freedesktop.org/wayland">Wayland git repo</a></li>
+  <li><a href="http://lists.freedesktop.org/mailman/listinfo/wayland-devel">Mailing list</a></li>
+  <li><a href="http://gitorious.org/~krh/qt/qt-wayland">Qt port in progress</a></li>
+  <li><a href="screenshots.html">Screenshots</a></li>
+  <li>IRC: #wayland on freenode</li>
+</ul>
+
+</body>
+</html> 
diff --git a/qt-mainwindow.png b/qt-mainwindow.png
new file mode 100644
index 0000000..285850a
--- /dev/null
+++ b/qt-mainwindow.png
diff --git a/qt-on-wayland.png b/qt-on-wayland.png
new file mode 100644
index 0000000..e9d1be5
--- /dev/null
+++ b/qt-on-wayland.png
diff --git a/qt-wayland.png b/qt-wayland.png
new file mode 100644
index 0000000..c403246
--- /dev/null
+++ b/qt-wayland.png
diff --git a/screenshots.html b/screenshots.html
new file mode 100644
index 0000000..8e93cd1
--- /dev/null
+++ b/screenshots.html
@@ -0,0 +1,46 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> 
+<html> 
+
+<head> 
+<meta http-equiv="Content-Type" content="text/html;charset=utf-8"> 
+<link href="wayland.css" rel="stylesheet" type="text/css">
+<title>Wayland</title> 
+</head>
+
+<body>
+<h1><img src="wayland.png"></h1>
+
+<h2>Screenshots</h1>
+
+<p>Wayland demos:</p>
+
+<ul>
+  <li><a href="smoke.png">Software rendering demo</a></li>
+  <li><a href="wayland-dnd.png">Wayland drag and drop demo</a></li>
+</ul>
+
+<p>Qt on Wayland:</p>
+
+<ul>
+  <li><a href="qt-mainwindow.png">Qt Mainwindow demo</a></li>
+  <li><a href="qt-on-wayland.png">Misc Qt demos</a></li>
+  <li><a href="qt-wayland.png">QGraphicsView with GLES2 painter</a></li>
+  <li><a href="webkit-wayland.png">WebKit demo</a></li>
+</ul>
+
+<p>GTK+ on Wayland:</p>
+
+<ul>
+  <li><a href="wayland-gtk.png">Wayland gtk+ applications</a></li>
+  <li><a href="wayland-vte.png">VTE terminal emulator</a></li>
+</ul>
+
+<p>Clutter on Wayland:</p>
+
+<ul>
+  <li><a href="clutter-hands.png">Clutter spinning hands</a></li>
+  <li><a href="clutter-flowers.png">Clutter cairo flowers</a></li>
+</ul>
+
+</body>
+</html> 
diff --git a/smoke.png b/smoke.png
new file mode 100644
index 0000000..8a305c6
--- /dev/null
+++ b/smoke.png
diff --git a/wayland-architecture.png b/wayland-architecture.png
new file mode 100644
index 0000000..4f92e0f
--- /dev/null
+++ b/wayland-architecture.png
diff --git a/wayland-dnd.png b/wayland-dnd.png
new file mode 100644
index 0000000..1693e20
--- /dev/null
+++ b/wayland-dnd.png
diff --git a/wayland-gtk.png b/wayland-gtk.png
new file mode 100644
index 0000000..e183970
--- /dev/null
+++ b/wayland-gtk.png
diff --git a/wayland-vte.png b/wayland-vte.png
new file mode 100644
index 0000000..1f65ef1
--- /dev/null
+++ b/wayland-vte.png
diff --git a/wayland.css b/wayland.css
new file mode 100644
index 0000000..488914a
--- /dev/null
+++ b/wayland.css
@@ -0,0 +1,9 @@
+body { solid; padding: 0px 150px; }
+h1 { margin: 40px 0px; color: #aaa; }
+p { margin: 20px 0px; }
+h1 img { vertical-align: middle; }
+h2 { font-family: sans; color: #888; }
+a { color: #444; }
+a:hover { color: #888; }
+a:visited { color: #666; }
+li { margin: 10px 0px };
diff --git a/wayland.png b/wayland.png
new file mode 100644
index 0000000..c993792
--- /dev/null
+++ b/wayland.png
diff --git a/webkit-wayland.png b/webkit-wayland.png
new file mode 100644
index 0000000..d315daa
--- /dev/null
+++ b/webkit-wayland.png
diff --git a/x-architecture.png b/x-architecture.png
new file mode 100644
index 0000000..098205b
--- /dev/null
+++ b/x-architecture.png
diff --git a/x-on-wayland.png b/x-on-wayland.png
new file mode 100644
index 0000000..0e7d587
--- /dev/null
+++ b/x-on-wayland.png
author	Kristian Høgsberg <krh@bitplanet.net>	2010-10-29 16:21:56 -0400
committer	Kristian Høgsberg <krh@bitplanet.net>	2010-10-29 16:21:56 -0400
commit	626c34712d4e7b427a8e6706e49d1cb3a681a821 (patch)
tree	7619b19fbf2bd98b564817520ce127dfb513652b