From ef313cf9fc2e6fb029c36ed941cf9ff8f25a790f Mon Sep 17 00:00:00 2001
From: ManoloFLTK <41016272+ManoloFLTK@users.noreply.github.com>
Date: Wed, 8 May 2024 13:06:57 +0200
Subject: Wayland documentation: beef up description of
 registry_handle_global()

---
 documentation/src/wayland.dox | 55 ++++++++++++++++++++++++++++++-------------
 1 file changed, 39 insertions(+), 16 deletions(-)

(limited to 'documentation')

diff --git a/documentation/src/wayland.dox b/documentation/src/wayland.dox
index de09a6424..07191add9 100644
--- a/documentation/src/wayland.dox
+++ b/documentation/src/wayland.dox
@@ -264,10 +264,10 @@ that allows the FLTK display opening procedure of the Wayland/X11 hybrid to reco
 access is not possible and to fallback to X11.
 
 Then, function \c wl_registry_add_listener() associates a 2-member listener, whose 1st member,
-\c registry_handle_global(), will be called by Wayland a number of times to indicate each time a protocol
-supported by the compositor or a system feature such as displays and keyboards.
-This code allows to run the client until all calls to \c registry_handle_global() have
-occurred:
+\c registry_handle_global(), will be called by Wayland a number of times to indicate each time
+a protocol supported by the compositor or a system feature such as displays and keyboards.
+
+FLTK runs this code to receive calls to \c registry_handle_global():
 \code
 static void sync_done(void *data, struct wl_callback *cb, uint32_t time) {
   *(struct wl_callback **)data = NULL;
@@ -289,8 +289,8 @@ member function, \c sync_done(), after all calls to \c registry_handle_global()
 occurred. Function \c sync_done() sets to null variable \c registry_cb and destroys
 the \c wl_callback.
 Finally, function \c wl_display_dispatch() is called as long as variable \c registry_cb is
-not null. This makes Wayland process all its pending requests until \c sync_done() runs.
-
+not null. Thus, when \c sync_done() runs, FLTK has received all due calls to
+\c registry_handle_global().
 
 The prototype of function \c registry_handle_global is:
 \code
@@ -298,12 +298,32 @@ static void registry_handle_global(void *user_data, struct wl_registry *wl_regis
            uint32_t id, const char *interface, uint32_t version)
 \endcode
 Each time Wayland calls \c registry_handle_global(), \c interface and \c version give the name
-and version of a component or feature of the Wayland system. It's necessary to call each time function
+and version of a component or feature of the Wayland system.
+Here is the list of the \c interface value for all protocols and system features FLTK uses:
+<table>
+ <tr><th>interface  </th><th> use</th> </tr>
+ <tr><td>wl_compositor </td><td> create wl_surface objects </td> </tr>
+ <tr><td>wl_subcompositor </td><td>create subwindows </td> </tr>
+ <tr><td>wl_shm </td><td> create buffers and buffer factories</td> </tr>
+ <tr><td>wl_seat </td><td> create the unique "seat"</td> </tr>
+ <tr><td>wl_data_device </td><td> support of copy/paste/drag-n-drop</td> </tr>
+ <tr><td>wl_output </td><td>received once for each display </td> </tr>
+ <tr><td>xdg_wm_base </td><td>create mapped windows </td> </tr>
+ <tr><td>gtk_shell1 </td><td>signals Mutter is in use + titlebar gestures</td> </tr>
+ <tr><td>weston_desktop_shell </td><td> signals Weston is in use</td></tr>
+ <tr><td>org_kde_plasma_shell </td><td> signals KDE/Plasma is in use</td></tr>
+ <tr><td>zwp_text_input_manager_v3 </td><td>interface with Text Input Methods </td></tr>
+ <tr><td>zxdg_decoration_manager_v1 </td><td>select between CSD and SSD modes </td></tr>
+</table>
+Wayland compositors typically support several other protocols (e.g., \c zxdg_output_manager_v1)
+that FLTK does not use.
+
+Each time \c registry_handle_global runs with an \c interface from the table above, FLTK calls
 \c wl_registry_bind() which returns a pointer to a Wayland structure that will be the client's access
 point to the corresponding Wayland protocol or system feature. This pointer is stored in a dedicated
 member variable of the unique \c Fl_Wayland_Screen_Driver object of an FLTK app, or of another object
 accessible from this object.
-For example, when \c interface equals "wl_compositor", the value returned by
+For example, when \c interface equals \c "wl_compositor", the value returned by
 \c wl_registry_bind() is stored as member \c wl_compositor of the
 \c Fl_Wayland_Screen_Driver object.
 \c registry_handle_global() also identifies whether the Mutter, Weston, or KWin compositor is connected
@@ -342,19 +362,22 @@ and in overridden functions \c Fl_Wayland_Screen_Driver::poll_or_select_with_del
 
 Wayland defines objects called surfaces of type <tt>struct wl_surface</tt>. A Wayland surface
 "has a rectangular area which may be displayed on zero or more displays, present buffers,
-receive user input, and define a local coordinate system". In other words,
+receive user input, and define a local coordinate system". In short,
 surface is the name Wayland uses for a window.
 Buffers allow the client app to define the graphical content of surfaces (see \ref wayland-buffer).
 FLTK creates a surface each time an Fl_Window is show()'n calling function
 \c wl_compositor_create_surface().
 Static member function <tt>Fl_Wayland_Window_Driver::surface_to_window(struct wl_surface *)</tt>
 gives the \c Fl_Window* corresponding to the surface given in argument.
-FLTK recognizes 4 distinct
-kinds of surfaces named DECORATED, UNFRAMED, POPUP and SUBWINDOW.
-DECORATED are toplevel windows with a titlebar. UNFRAMED have no titlebar. POPUP correspond to menus
-and tooltips, SUBWINDOW to an Fl_Window embedded in another Fl_Window. Function
-\c Fl_Wayland_Window_Driver::makeWindow() creates all these surfaces, creates for each a record of
-type <tt>struct wld_window</tt> (see \ref wld_window), and stores the window kind in
+
+FLTK recognizes 4 mutually exclusive kinds of surfaces :
+- DECORATED are toplevel windows with a titlebar;
+- UNFRAMED are toplevel windows without titlebar;
+- POPUP correspond to menus and tooltips;
+- SUBWINDOW correspond to an Fl_Window embedded in another Fl_Window.
+
+Function \c Fl_Wayland_Window_Driver::makeWindow() creates all these surfaces, creates for each
+a record of type <tt>struct wld_window</tt> (see \ref wld_window), and stores the window kind in
 member variable \c kind of this record. Member variable \c xid of the window's \c Fl_X record stores
 the adress of this record.
 
@@ -713,7 +736,7 @@ stores the access point to the linked list of \c wl_buffer objects that will be
 the \c wl_shm_pool.
 - A variable named \c chunk_offset represents the offset within the pool's shared
 memory available for the buffer being constructed. It equals 0 when the pool has just been
-created and is updated as detailed below when one or more buffers have been previously created
+created and is updated as detailed below each time a buffer is created
 from the pool. A record of type  <tt>struct Fl_Wayland_Graphics_Driver::wld_buffer</tt> is created. This record will
 contain (member \c wl_buffer) the address of a \c wl_buffer object that's created by function
 \c wl_shm_pool_create_buffer(). This \c wl_buffer object encapsulates a section of a given
-- 
cgit v1.2.3