Figuring out the terms used in the documentation

[Adam Jackson]

On Sat, 2020-06-06 at 08:18 -0300, Sleep wrote:
> Thank you very much Adam, I have written a small diagram as an
> exercise, 
> I would appreciate if someone could tell me if this is correct:
> 
> Display -> is ------> +---------------+
>     |                  |   Server and  |
>     V                  | Input Devices |
> contains              +---------------+
>     |
>     V
> Screens
>     |
>     V
>   and a
>     |
>     V
> Screen -------------+
>     |                |
>     V                V
> contains         contains         +-------- which uses colors from
>     |                |             |                      ^
>     V                |             V                      |
> Visuals <----+      |      Colormap* (and only one)    images**
>     ^         |      |             ^                      ^
>     |         |      |             |                      |
>   from        |      |      is associated with <---    contains
>     ^         |      +-----------                  \____  ^
>     |         |                  \                      \ |
> Visual    are associated with <- Windows -> contains -> Window
>    ^                                                      ^
>    |                                                      |
>    +-----------------------------------------is associated with

The left side of this is pretty good. The right side isn't wrong, but
maybe... incomplete?

Windows don't necessarily contain images. There are two kinds of
windows, InputOnly and InputOutput. InputOnly windows are often used as
targets for mouse clicks or IPC. All windows have a geometry and can
receive events, but only InputOutput Windows have pixels; attempting to
draw to an InputOnly Window will fail, even though its subregion of the
parent InputOutput window might be valid. An InputOnly window can not
be the parent of an InputOutput window.

Colormaps are server resources the same way Windows are, in general the
client may create its own Colormaps or Windows and manipulate them how
it likes. In particular, just as there is a predefined root Window for
each screen, there is a predefined Colormap associated with that root
Window. For TrueColor Visuals, said Colormap is read-only, and is
effectively the gamma correction ramp. For PseudoColor visuals, the
Colormap is a traditional color palette, where the pixel value directly
determines all of R G and B at once.

You describe the server as "containing" both Visuals and Windows, but
they're not really the same kind of relationship. It might be better to
say a server "supports" a set of Visuals. Visuals are not dynamic, they
may not be created destroyed or modified by any client, they are
defined up-front by the server. They are a description of what kinds of
Window are supported. (Similarly, Formats describe what kinds of Pixmap
are supported.)

- ajax