NOTES

   1
   2 KEYWORDS:
   3
   4 Wayland is a nano display server, relying on drm modesetting, gem
   5 batchbuffer submission and hw initialization generally in the kernel.
   6 Wayland puts the compositing manager and display server in the same
   7 process.  Window management is largely pushed to the clients, they
   8 draw their own decorations and move and resize themselves, typically
   9 implemented in a toolkit library.  More of the core desktop could be
  10 pushed into wayland, for example, stock desktop components such as the
  11 panel or the desktop background.
  12
  13 The actual compositor will define a fair bit of desktop policy and it
  14 is expected that different use cases (desktop environments, devices,
  15 appliances) will provide their own custom compositor.
  16
  17 It is still designed with a windowed type of desktop in mind, as
  18 opposed to fullscreen-all-the-time type of interface, but should be
  19 useful wherever several processes contribute content to be composited.
  20
  21 Current trends goes towards less and less rendering in X server, more
  22 hardware setup and management in kernel and shared libraries allow
  23 code sharing without putting it all in a server.  freetype,
  24 fontconfig, cairo all point in this direction, as does direct
  25 rendering mesa.
  26
  27 Client allocates DRM buffers, draws decorations, and full window
  28 contents and posts entire thing to server along with dimensions.
  29
  30 Everything is direct rendered and composited.  No cliprects, no
  31 drawing api/protocl between server and client.  No
  32 pixmaps/windows/drawables, only surfaces (essentially pixmaps).  No
  33 gcs/fonts, no nested windows.  OpenGL is already direct rendered,
  34 pixman may be direct rendered which adds the cairo API, or cairo
  35 may gain a GL backend.
  36
  37 Could be a "shell" for launching gdm X server, user session servers,
  38 safe mode xservers, graphics text console.  From gdm, we could also
  39 launch a rdp session, solid ice sessions.
  40
  41 All surface commands (copy, attach, map=set quads) are buffered until
  42 the client sends a commit command, which executes everything
  43 atomically.  The commit command includes a cookie, which will be
  44 returned in an event generated by the server once the commit has been
  45 executed.  This allows clients to throttle themselves against the
  46 server and implement smooth animations.
  47
  48 Throttling/scheduling - there is currently no mechanism for scheduling
  49 clients to prevent greedy clients from spamming the server and
  50 starving other clients.  On the other hand, now that recompositing is
  51 done in the idle handler (and eventually at vertical retrace time),
  52 there's nothing a client can do to hog the server.  Unless we include
  53 a copyregion type request, to let a client update it's surface
  54 contents by asking the server to atomically copy a region from some
  55 other buffer to the surface buffer.
  56
  57 Atomicity - we have the map and the attach requests which sometimes
  58 will have to be executed atomically.  Moving the window is done using
  59 the map request and will not involve an attach requet.  Updating the
  60 window contents will use an attach request but no map.  Resizing,
  61 however, will use both and in that case must be executed atomically.
  62 One way to do this is to have the server always batch up requests and
  63 then introduce a kind of "commit" request, which will push the batched
  64 changes into effect.  This is easier than it sounds, since we only
  65 have to remember the most recent map and most recent attach.  The
  66 commit request will generate an corresponding commit event once the
  67 committed changes become visible on screen.  The client can provide a
  68 bread-crumb id in the commit request, which will be sent back in the
  69 commit event.
  70
  71  - is batching+commit per client or per surface?  Much more convenient
  72    if per-client, since a client can batch up a bunch of stuff and get
  73    atomic updates to multiple windows.  Also nice to only get one
  74    commit event for changes to a bunch of windows.  Is a little more
  75    tricky server-side, since we now have to keep a list of windows
  76    with pending changes in the wl_client struct.
  77
  78  - batching+commit also lets a client reuse parts of the surface
  79    buffer without allocating a new full-size back buffer.  For
  80    scrolling, for example, the client can render just the newly
  81    exposed part of the page to a smaller temporary buffer, then issue
  82    a copy request to copy the preserved part of the page up, and the
  83    new part of the page into the exposed area.
  84
  85  - This does let a client batch up an uncontrolled amount of copy
  86    requests that the server has to execute when it gets the commit
  87    request.  This could potentially lock up the server for a while,
  88    leading to lost frames.  Should never cause tearing though, we're
  89    changing the surface contents, not the server back buffer which is
  90    what is scheduled for blitting at vsync time.
  91
  92
  93 RMI
  94
  95 The wayland protocol is a async object oriented protocol.  All
  96 requests are method invocations on some object.  The request include
  97 an object id that uniquely identifies an object on the server.  Each
  98 object implements an interface and the requests include an opcode that
  99 identifies which method in the interface to invoke.
 100
 101 The server sends back events to the client, each event is emitted from
 102 an object.  Events can be error conditions.  The event includes the
 103 object id and the event opcode, from which the client can determine
 104 the type of event.  Events are generated both in repsonse to a request
 105 (in which case the request and the event constitutes a round trip) or
 106 spontanously when the server state changes.
 107
 108 the get_interface method is called on an object to get an object
 109 handle that implements the specified interface.
 110
 111
 112 EMBEDDING OTHER WINDOWS
 113
 114 X11 lets clients embed windows from other clients other copy pixmap
 115 contents rendered by another client into their window.  This is often
 116 used for applets in a panel, browser plugins and similar.  Wayland
 117 doesn't directly allow this, but clients can communicate GEM buffer
 118 names out-of-band, for example, using d-bus or as command line
 119 arguments when the panel launches the applet.  Another option is to
 120 use a nested wayland instance.  For this, the wayland server will have
 121 to be a library that the host application links to.  The host
 122 application will then pass the wayland server socket name to the
 123 embedded application, and will need to implement the wayland
 124 compositor interface.  The host application composites the client
 125 surfaces as part of it's window, that is, in the web page or in the
 126 panel.  The benefit of nesting the wayland server is that it provides
 127 the requests the embedded client needs to inform the host about buffer
 128 updates and a mechanism for forwarding input events from the host
 129 application.