Consolidate NOTES and README

NOTES

@@ -1,90 +0,0 @@
-
-KEYWORDS:
-
-Wayland is a nano display server, relying on drm modesetting, gem
-batchbuffer submission and hw initialization generally in the kernel.
-Wayland puts the compositing manager and display server in the same
-process.  Window management is largely pushed to the clients, they
-draw their own decorations and move and resize themselves, typically
-implemented in a toolkit library.  More of the core desktop could be
-pushed into wayland, for example, stock desktop components such as the
-panel or the desktop background.
-
-The actual compositor will define a fair bit of desktop policy and it
-is expected that different use cases (desktop environments, devices,
-appliances) will provide their own custom compositor.
-
-It is still designed with a windowed type of desktop in mind, as
-opposed to fullscreen-all-the-time type of interface, but should be
-useful wherever several processes contribute content to be composited.
-
-Current trends goes towards less and less rendering in X server, more
-hardware setup and management in kernel and shared libraries allow
-code sharing without putting it all in a server.  freetype,
-fontconfig, cairo all point in this direction, as does direct
-rendering mesa.
-
-Client allocates DRM buffers, draws decorations, and full window
-contents and posts entire thing to server along with dimensions.
-
-Everything is direct rendered and composited.  No cliprects, no
-drawing api/protocl between server and client.  No
-pixmaps/windows/drawables, only surfaces (essentially pixmaps).  No
-gcs/fonts, no nested windows.  OpenGL is already direct rendered,
-pixman may be direct rendered which adds the cairo API, or cairo
-may gain a GL backend.
-
-Could be a "shell" for launching gdm X server, user session servers,
-safe mode xservers, graphics text console.  From gdm, we could also
-launch a rdp session, solid ice sessions.  
-
-All surface commands (copy, attach, map=set quads) are buffered until
-the client sends a commit command, which executes everything
-atomically.  The commit command includes a cookie, which will be
-returned in an event generated by the server once the commit has been
-executed.  This allows clients to throttle themselves against the
-server and implement smooth animations.
-
-Throttling/scheduling - there is currently no mechanism for scheduling
-clients to prevent greedy clients from spamming the server and
-starving other clients.  On the other hand, now that recompositing is
-done in the idle handler (and eventually at vertical retrace time),
-there's nothing a client can do to hog the server.  Unless we include
-a copyregion type request, to let a client update it's surface
-contents by asking the server to atomically copy a region from some
-other buffer to the surface buffer.
-
-Atomicity - we have the map and the attach requests which sometimes
-will have to be executed atomically.  Moving the window is done using
-the map request and will not involve an attach requet.  Updating the
-window contents will use an attach request but no map.  Resizing,
-however, will use both and in that case must be executed atomically.
-One way to do this is to have the server always batch up requests and
-then introduce a kind of "commit" request, which will push the batched
-changes into effect.  This is easier than it sounds, since we only
-have to remember the most recent map and most recent attach.  The
-commit request will generate an corresponding commit event once the
-committed changes become visible on screen.  The client can provide a
-bread-crumb id in the commit request, which will be sent back in the
-commit event.
-
- - is batching+commit per client or per surface?  Much more convenient
-   if per-client, since a client can batch up a bunch of stuff and get
-   atomic updates to multiple windows.  Also nice to only get one
-   commit event for changes to a bunch of windows.  Is a little more
-   tricky server-side, since we now have to keep a list of windows
-   with pending changes in the wl_client struct.
-
- - batching+commit also lets a client reuse parts of the surface
-   buffer without allocating a new full-size back buffer.  For
-   scrolling, for example, the client can render just the newly
-   exposed part of the page to a smaller temporary buffer, then issue
-   a copy request to copy the preserved part of the page up, and the
-   new part of the page into the exposed area.
-
- - This does let a client batch up an uncontrolled amount of copy
-   requests that the server has to execute when it gets the commit
-   request.  This could potentially lock up the server for a while,
-   leading to lost frames.  Should never cause tearing though, we're
-   changing the surface contents, not the server back buffer which is
-   what is scheduled for blitting at vsync time.

README

@@ -1,5 +1,30 @@
-These instructions assume some familiarity with git and building and
-running experimental software.  And be prepared that this project
+What is Wayland
+
+Wayland is a project to define a protocol for a compositor to talk to
+its clients as well as a library implementation of the protocol.  The
+compositor can be a standalone display server running on Linux kernel
+modesetting and evdev input devices, an X applications, or a wayland
+client itself.  The clients can be traditional appliactions, X servers
+(rootless or fullscreen) or other display servers.
+
+The wayland protocol is essentially only about input handling and
+buffer management.  The compositor receives input events and forwards
+them to the relevant client.  The clients creates buffers and renders
+into them and notifies the compositor when it needs to redraw.  The
+protocol also handles drag and drop, selections, window management and
+other interactions that must go throught the compositor.  However, the
+protocol does not handle rendering, which is one of the features that
+makes wayland so simple.  All clients are expected to handle rendering
+themselves, typically through cairo or OpenGL.
+
+The wayland repository includes a compositor and a few clients, but
+both the compositor and clients are essentially test cases.
+
+
+Building Instructions
+
+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