~sircmpwn/wayland-book

1985aa147ce8ec611221a7b9d531adba0ce22c24 — Vlad-Stefan Harbuz 1 year, 4 months ago 9023e00
improve phrasing, grammar, typos

Signed-off-by: Vlad-Stefan Harbuz <vlad@vladh.net>
M src/introduction/goals.md => src/introduction/goals.md +1 -1
@@ 14,7 14,7 @@ here about leveraging libdrm in your Wayland compositor, or using libinput to
process evdev events. Thus, this book is not a comprehensive guide for building 
Wayland compositors. We're also not going to talk about drawing technologies 
which are useful for Wayland clients, such as Cairo, Pango, GTK+, and so on, and 
thus neither is this a robust guide for the practical Wayland client 
thus nor is this a robust guide for the practical Wayland client 
implementation. Instead, we focus only on the particulars of Wayland.

This book only covers the protocol and libwayland. If you are writing a client

M src/introduction/high-level-design.md => src/introduction/high-level-design.md +5 -5
@@ 59,12 59,12 @@ tells it so. For this reason, only one component is allowed to talk to it...

This responsibility falls onto the kernel. The kernel is a complex beast, so
we'll focus on only the parts which are relevant to Wayland. Linux's job is to
provide an abstraction over your hardware, so that they can be safely accessed
provide an abstraction over your hardware, so that it can be safely accessed
by *userspace* &mdash; where our Wayland compositors run. For graphics, this is
called **DRM**, or *direct rendering manager*, for efficiently tasking the GPU
with work from userspace. An important subsystem of DRM is **KMS**, or *kernel
mode setting*, for enumerating your displays and setting properties such as 
their selected resolution (also known as their "mode"). Input devices are 
called the **DRM**, or *direct rendering manager*, which efficiently tasks the
GPU with work from userspace. An important subsystem of DRM is **KMS**, or
*kernel mode setting*, for enumerating your displays and setting properties such
as their selected resolution (also known as their "mode"). Input devices are
abstracted through an interface called **evdev**.

Most kernel interfaces are made available to userspace by way of special files

M src/libwayland/interfaces.md => src/libwayland/interfaces.md +1 -1
@@ 68,7 68,7 @@ static const struct wl_surface_listener surface_listener = {
    .leave = wl_surface_leave,
};

// ...cotd...
// ...

struct wl_surface *surf;
wl_surface_add_listener(surf, &surface_listener, NULL);

M src/libwayland/proxies.md => src/libwayland/proxies.md +3 -2
@@ 1,6 1,6 @@
# Proxies & resources

An *object* is an entity which known to both the client and server that has some
An *object* is an entity known to both the client and server that has some
state, changes to which are negotiated over the wire. On the client side,
libwayland refers to these objects through the `wl_proxy` interface. These are a
concrete C-friendly "proxy" for the abstract object, and provides functions


@@ 20,4 20,5 @@ out-of-context, or send a protocol error when the client attempts an invalid
operation.

Another level up is another set of higher-level interfaces, which most Wayland
client & server code interacts with to accomplish a majority of their tasks.
clients & servers interact with to accomplish a majority of their tasks. We will
look at them in the next section.

M src/libwayland/util.md => src/libwayland/util.md +3 -3
@@ 13,6 13,6 @@ handful of primitives for use in Wayland applications. Among these are:
  numbers) and C types
- Debug logging facilities to bubble up information from libwayland internals

The header contains many comments which document itself. The documentation is
quite good &mdash; you should read through the header yourself. We'll go into 
detail on how to apply these primitives in the next several pages.
The header itself contains many comments with quite good documentation &mdash;
you should read through them yourself. We'll go into detail on how to apply
these primitives in the next several pages.

M src/protocol-design/high-level.md => src/protocol-design/high-level.md +2 -2
@@ 31,11 31,11 @@ yourself &mdash; included is additional documentation explaining the purpose and
precise semantics of each request and event.

When processing this XML file, we assign each request and event an opcode in the
order that they appear (both numbered from zero and incrementing independently).
order that they appear, numbered from zero and incrementing independently.
Combined with the list of arguments, you can decode the request or event when it
comes in over the wire, and based on the documentation shipped in the XML file
you can decide how to program your software to behave accordingly.  This usually
comes in the form of code generation &mdash; we'll talk about how libwayland 
comes in the form of code generation &mdash; we'll talk about how libwayland
does this in chapter 3.

Starting from chapter 4, most of the remainder of this book is devoted to

M src/protocol-design/interfaces-reqs-events.md => src/protocol-design/interfaces-reqs-events.md +13 -12
@@ 9,9 9,10 @@ are possible, and the *signature* of each. Let's consider an example interface:

A surface is a box of pixels that can be displayed on-screen. It's one of the
primitives we build things like application windows out of. One of its
*requests* is "damage", which the client uses to indicate that some part of the
surface has changed and needs to be redrawn. Here's an annotated example of a
"damage" message on the wire (in hexadecimal):
*requests*, sent from the client to the server, is "damage", which the client
uses to indicate that some part of the surface has changed and needs to be
redrawn. Here's an annotated example of a "damage" message on the wire (in
hexadecimal):

    0000000A    Object ID (10)
    00180002    Message length (24) and request opcode (2)


@@ 29,11 30,11 @@ for processing internally.

## Events

Requests are sent from the client to the server. The server can also send
messages back &mdash; events. One event that the server can send regarding a
`wl_surface` is "enter", which it sends when that surface is being displayed on
a specific output (the client might respond to this, for example, by adjusting
its scale factor for a HiDPI display). Here's an example of such a message:
The server can also send messages back to the client &mdash; events. One event
that the server can send regarding a `wl_surface` is "enter", which it sends
when that surface is being displayed on a specific output (the client might
respond to this, for example, by adjusting its scale factor for a HiDPI
display). Here's an example of such a message:

    0000000A    Object ID (10)
    000C0000    Message length (12) and event opcode (0)


@@ 43,12 44,12 @@ This message references another object, by its ID: the `wl_output` object which
the surface is being shown on. The client receives this and dances to a similar
tune as the server did. It looks up object 10, associates it with the
`wl_surface` interface, and looks up the signature of the event corresponding to
opcode 0. It decodes the rest of the message accordingly (looking up the
`wl_output` with ID 5 as well), then dispatches it for processing internally.
opcode 0. It decodes the rest of the message accordingly, looking up the
`wl_output` with ID 5 as well, then dispatches it for processing internally.

## Interfaces

The interfaces which define the list of requests and events, the opcodes
associated with each, and the signatures with which you can decode the messages 
&mdash; are agreed upon in advance. I'm sure you're dying to know how &mdash; 
associated with each, and the signatures with which you can decode the messages,
are agreed upon in advance. I'm sure you're dying to know how &mdash; 
simply turn the page to end the suspense.

M src/protocol-design/wire-protocol.md => src/protocol-design/wire-protocol.md +3 -3
@@ 57,9 57,9 @@ assuming you've already negotiated an object ID. Speaking of which...

## Object IDs

When a message comes in with a `new_id` argument, the sender allocates an
object ID for it (the interface used for this object is established through
additional arguments, or agreed upon in advance for that request/event). This
When a message comes in with a `new_id` argument, the sender allocates an object
ID for it &mdash; the interface used for this object is established through
additional arguments, or agreed upon in advance for that request/event. This
object ID can be used in future messages, either as the first word of the
header, or as an `object_id` argument. The client allocates IDs in the range of
`[1, 0xFEFFFFFF]`, and the server allocates IDs in the range of `[0xFF000000,

M src/registry.md => src/registry.md +9 -9
@@ 4,7 4,7 @@ If you'll recall from chapter 2.1, each request and event is associated with an
object ID, but thus far we haven't discussed how objects are created. When we
receive a Wayland message, we must know what interface the object ID represents
to decode it. We must also somehow negotiate available objects, the creation of
new ones, and the assigning of IDs to them, in some manner. On Wayland we solve
new ones, and the assigning of IDs to them, in some manner. In Wayland we solve
both of these problems at once &mdash; when we *bind* an object ID, we agree on 
the interface used for it in all future messages, and stash a mapping of object 
IDs to interfaces in our local state.


@@ 12,14 12,14 @@ IDs to interfaces in our local state.
In order to bootstrap these, the server offers a list of *global* objects. These
globals often provide information and functionality on their own merits, but
most often they're used to broker additional objects to fulfill various
purposes &mdash; such as the creation of application windows. These globals 
themselves also have their own object IDs and interfaces, which we have to 
assign and agree upon somehow.
purposes, such as the creation of application windows. These globals themselves
also have their own object IDs and interfaces, which we have to somehow assign
and agree upon.

With questions of hens and eggs no doubt coming to mind by now, I'll reveal the
secret trick: object ID 1 is already implicitly assigned to the `wl_display`
interface when you make the connection. As you'll recall the interface, take
note of the `wl_display::get_registry` request:
With questions of chickens and eggs no doubt coming to mind by now, I'll reveal
the secret trick: object ID 1 is already implicitly assigned to the `wl_display`
interface when you make the connection. As you recall the interface, take note
of the `wl_display::get_registry` request:

```xml
<interface name="wl_display" version="1">


@@ 31,7 31,7 @@ note of the `wl_display::get_registry` request:
    <arg name="registry" type="new_id" interface="wl_registry" />
  </request>

  <!-- cotd -->
  <!-- ... -->
</interface>
```


M src/registry/binding.md => src/registry/binding.md +7 -8
@@ 4,14 4,13 @@ Upon creating a registry object, the server will emit the `global` event for
each global available on the server. You can then bind to the globals you
require.

This process of taking a known object and assigning it an ID is called
*binding* the object. Once the client binds to the registry like this, the
server emits the `global` event several times to advertise which interfaces it
supports. Each of these globals is assigned a unique `name`, as an unsigned
integer. The `interface` string maps to the name of the interface found in the
protocol: `wl_display` from the XML above is an example of such a name. The
version number is also defined here &mdash; for more information about interface
versioning, see appendix C.
*Binding* is the process of taking a known object and assigning it an ID. Once
the client binds to the registry like this, the server emits the `global` event
several times to advertise which interfaces it supports. Each of these globals
is assigned a unique `name`, as an unsigned integer. The `interface` string maps
to the name of the interface found in the protocol: `wl_display` from the XML
above is an example of such a name. The version number is also defined here
&mdash; for more information about interface versioning, see appendix C.

To bind to any of these interfaces, we use the bind request, which works
similarly to the magical process by which we bound to the `wl_registry`. For

M src/wayland-display.md => src/wayland-display.md +1 -1
@@ 44,7 44,7 @@ for housekeeping on the connection, and are generally not important unless
you're writing your own libwayland replacement.

Instead, this chapter will focus on a number of functions that libwayland
associated with the `wl_display` object, for establishing and maintaining your
associates with the `wl_display` object, for establishing and maintaining your
Wayland connection. These are used to manipulate libwayland's internal state,
rather than being directly related to wire protocol requests and events.


M src/wayland-display/creation.md => src/wayland-display/creation.md +4 -4
@@ 50,11 50,11 @@ libwayland will:

1. If `$WAYLAND_DISPLAY` is set, attempt to connect to
   `$XDG_RUNTIME_DIR/$WAYLAND_DISPLAY`
2. Attempt to connect to `$XDG_RUNTIME_DIR/wayland-0`
3. Fail :(
2. Otherwise, attempt to connect to `$XDG_RUNTIME_DIR/wayland-0`
3. Otherwise, fail :(

This allows users to specify the Wayland display they want to run their clients
on by setting the `$WAYLAND_DISPLAY` to the desired display. If you have more
on by setting `$WAYLAND_DISPLAY` to the desired display. If you have more
complex requirements, you can also establish the connection yourself and create
a Wayland display from a file descriptor:



@@ 115,7 115,7 @@ Connection established!

Using `wl_display_add_socket_auto` will allow libwayland to decide the name for
the display automatically, which defaults to `wayland-0`, or `wayland-$n`,
depending on if any other Wayland compositors have sockets in
depending on whether any other Wayland compositors have sockets in
`$XDG_RUNTIME_DIR`. However, as with the client, you have some other options for
configuring the display:


M src/wayland-display/event-loop.md => src/wayland-display/event-loop.md +2 -2
@@ 2,8 2,8 @@

libwayland provides its own event loop implementation for Wayland servers to
take advantage of, but the maintainers have acknowledged this as a design
overstep. For clients, there is no such equivalent. However, the Wayland server
event loop is useful enough, even if it's out-of-scope.
overstep. For clients, there is no such equivalent. Regardless, the Wayland
server event loop is useful enough, even if it's out-of-scope.

## Wayland server event loop