From b8d2359a3c641a6881403120e241dfb0b397ba39 Mon Sep 17 00:00:00 2001 From: ManoloFLTK <41016272+ManoloFLTK@users.noreply.github.com> Date: Mon, 20 Feb 2023 09:40:54 +0100 Subject: Wayland developer's documentation: miscellaneous updates --- documentation/src/wayland.dox | 77 +++++++++++++++++++++++-------------------- 1 file changed, 42 insertions(+), 35 deletions(-) (limited to 'documentation') diff --git a/documentation/src/wayland.dox b/documentation/src/wayland.dox index 792363629..6100fc485 100644 --- a/documentation/src/wayland.dox +++ b/documentation/src/wayland.dox @@ -28,14 +28,21 @@ CSD and SSD compositors. It bundles a library called \c libdecor charged of dete a CSD or a SSD compositor is active, and of drawing titlebars in the first case. Wayland is divided in various protocols that a given compositor may or may not support, -although they all support the \c core protocol. The core protocol allows a client app -to discover what protocols its compositor supports. Protocols can be stable, +although they all support the \c core protocol. Each protocol adds functionality not available +in the core protocol. The core protocol allows a client app +to discover what protocols the connected compositor supports. Protocols can be stable, which means they have a defined API that will not change but can be expanded, or unstable. For example, mapping a window on a display is not done by the core protocol but by the xdg shell protocol which is stable. Unstable protocols are named beginning with letter 'z'. For example, the protocol FLTK uses to support CJK input methods is called \c zwp_text_input_v3 and is, unfortunately, unstable. +Wayland makes intensive use of the 'listener' mechanism. A listener is a small array of pointers +to FLTK-defined callback functions associated to a Wayland-defined object; Wayland +calls these functions when defined events occur, and transmits relevant information to the client +app as parameters of these calls. Each listener is first associated to its corresponding +Wayland object by a call to a specific Wayland function of the form \c wl_XXX_add_listener(). + Wayland differs noticeably from X11 in that the position of a window in the display is completely hidden to the client app. Besides toplevel and sub-windows, Wayland allows to create popup windows positioned relatively to a previously mapped other window. @@ -44,12 +51,6 @@ to pilot menus, because the previous algorithm conceived for other platforms ass the position of a window in the display to be known to the client app, which is wrong under Wayland. -Wayland makes intensive use of the 'listener' mechanism. A listener is a small array of pointers -to FLTK-defined callback functions associated to a Wayland-defined object; Wayland -calls these functions when defined events occur and transmits relevant information to the client -app as parameters of these calls. Each listener is first associated to its corresponding -Wayland object by a call to a specific Wayland function of the form \c wl_XXX_add_listener(). - Wayland uses a trick of its own to handle lists of linked records. It defines the opaque type struct wl_list and a few macros (\c wl_list_init(), \c wl_list_for_each(), \c wl_list_insert(), \c wl_list_for_each_safe(), \c wl_list_remove()) to manage linked lists. Records put in these @@ -106,6 +107,7 @@ The public C API to Wayland, xkb and libdecor libraries are obtained with #include #include #include "../../../libdecor/src/libdecor.h" +#include "../../../libdecor/src/libdecor-plugin.h" \endcode as necessary. @@ -201,11 +203,11 @@ stored as member \c wl_compositor of the \c Fl_Wayland_Screen_Driver object. and stores this information in static member variable \c Fl_Wayland_Screen_Driver::compositor. Finally, function \c wl_display_get_fd() is called to obtain the file descriptor of the Wayland socket -and a call to Fl::add_fd() makes FLTK listen to this descriptor and associates function -\c wayland_socket_callback() -from file \c Fl_Wayland_Screen_Driver.cxx with it. This function calls \c wl_display_dispatch() which -asks the Wayland client library to process requests arrived in the socket. The \c wl_display_dispatch() -call is repeated as long as data are available for reading. +and a call to Fl::add_fd() makes FLTK listen to this descriptor in \c FL_READ mode and associates +function \c wayland_socket_callback() from file \c Fl_Wayland_Screen_Driver.cxx with it. +This function calls \c wl_display_dispatch() which reads and interprets data available from the +file descriptor, and calls corresponding listeners. +The \c wl_display_dispatch() call is repeated as long as data are available for reading. The event loop is run by function \c Fl_Unix_System_Driver::wait() which is used by both the Wayland and X11 FLTK backends. Among various tasks, this function waits for data arriving @@ -314,7 +316,7 @@ window has just been created or resized. In that case, FLTK calls member functio - a Wayland buffer; - a Cairo image surface. -Each of these two objects bundles a byte array of the same size and the same memory layout +Each of these two objects encapsulates a byte array of the same size and the same memory layout destined to contain the Fl_Window's graphics. The Cairo surface object is where FLTK draws. The Wayland buffer is what Wayland maps on the display. FLTK copies the Cairo surface's byte array to the Wayland buffer's byte array before beginning the mapping operation. @@ -385,7 +387,7 @@ That's done by member function \c Fl_Wayland_Graphics_Driver::create_shm_buffer( which follows this 3-step procedure to create a "buffer factory" for FLTK and construct Wayland buffers from it: - Libdecor function os_create_anonymous_file(off_t size) creates an adequate file and mmap's -it. FLTK initially sets this file size to \c pool_size = 10 MB. This file will be enlarged when and +it. FLTK initially sets this file size to \c pool_size = 10 MB. This size will be increased when and if necessary. FLTK stores in variable \c pool_memory the address of the beginning of the mmap'ed memory structure. - Wayland function \c wl_shm_create_pool() has this mmap'ed memory shared with the @@ -547,8 +549,10 @@ struct cursor_image { int offset; }; \endcode -This definition has been copied to the FLTK source code from file \c wayland-cursor.c of the -Wayland project source code because it's not accessible via Wayland header files. +This definition has been copied to the FLTK source code from file + +wayland-cursor.c of the Wayland project source code +because it's not accessible via Wayland header files. It shows that a pointer to a \c cursor_image object can also be viewed as a pointer to the embedded struct wl_cursor_image object, this one being part of the public Wayland API. It also shows that a struct cursor_image object has an associated @@ -583,11 +587,11 @@ gets associated to a standard cursor or to a new custom cursor. \section wayland-text Text input -The "Mouse handling" topic above mentionned function \c seat_capabilities() that Wayland calls when +The "Mouse handling" section above mentionned function \c seat_capabilities() that Wayland calls when the app discovers its "seat". Presence of flag \c WL_SEAT_CAPABILITY_KEYBOARD in argument -\c capabilities of this function indicates that a keyboard is available. This availability is -stored in member \c wl_keyboard of the \ref seat object. Then, a call to -\c wl_keyboard_add_listener() installs a 6-member listener of type +\c capabilities of this function indicates that a keyboard is available. In that case, a call to +\c wl_seat_get_keyboard() returns a pointer stored in member \c wl_keyboard of the \ref seat object, +and a call to \c wl_keyboard_add_listener() installs a 6-member listener of type struct wl_keyboard_listener. These 6 FLTK-defined, callback functions are used as follows. Function \c wl_keyboard_keymap() runs once and allows initialization of access to this keyboard. @@ -619,9 +623,9 @@ the wl_keyboard object which is at version 3 in all tested Wayland comp When the connected Wayland compositor supports text input methods, function \c registry_handle_global() gets called with its \c interface argument equal to -\c zwp_text_input_manager_v3_interface.name. The following call to \c wl_registry_bind() returns an -object of type struct zwp_text_input_manager_v3 * that is stored as member \c text_input_base -of the \c Fl_Wayland_Screen_Driver object. +\c zwp_text_input_manager_v3_interface.name. The following call to \c wl_registry_bind() returns a +pointer to type struct zwp_text_input_manager_v3 that is stored as member +\c text_input_base of the \c Fl_Wayland_Screen_Driver object. Later, when function \c seat_capabilities() runs, \c text_input_base is found not NULL, which triggers a call to function \c zwp_text_input_manager_v3_get_text_input() returning a value of type @@ -782,7 +786,8 @@ description of function wl_display_prepare_read_queue(). \section wayland-type FLTK-defined, Wayland-specific types \anchor wld_window -- struct wld_window is defined in \c Fl_Wayland_Window_Driver.H. One such record is created +

struct wld_window

+Defined in \c Fl_Wayland_Window_Driver.H. One such record is created for each shown()'n Fl_Window by \c Fl_Wayland_Window_Driver::makeWindow(). Function \c fl_wl_xid(Fl_Window*) returns a pointer to the struct wld_window of its argument. 
@@ -810,7 +815,8 @@ struct wld_window {
\anchor fl_wld_buffer -- struct fl_wld_buffer is defined in \c Fl_Wayland_Graphics_Driver.H. One such record is +

struct fl_wld_buffer

+Defined in \c Fl_Wayland_Graphics_Driver.H. One such record is created for each shown()'n or resized Fl_Window by \c Fl_Wayland_Graphics_Driver::create_shm_buffer(). 
 struct fl_wld_buffer {
@@ -827,7 +833,8 @@ struct fl_wld_buffer {
\anchor output -- struct output is defined inside class \c Fl_Wayland_Screen_Driver. One such record is +

struct output

+Defined inside class \c Fl_Wayland_Screen_Driver. One such record is created for each display of the system by function \c registry_handle_global() when it receives a \c "wl_output" interface. These records are kept in a linked list of them all, and an identifier of this linked list is stored in member \c outputs of the unique @@ -850,12 +857,12 @@ struct output { // one record for each display }; - \anchor seat -- struct seat is defined in file \c Fl_Wayland_Screen_Driver.H. One such record is -created for each seat (e.g., a collection of displays, a keyboard and a mouse) of the system by +

struct seat

+Defined in file \c Fl_Wayland_Screen_Driver.H. One such record is created by function \c registry_handle_global() when it receives a \c "wl_seat" or -\c wl_data_device_manager_interface.name interface. +\c wl_data_device_manager_interface.name interface. A pointer to this record is stored in member +\c seat of the client's unique \c Fl_Wayland_Screen_Driver object. 
 struct seat {
   struct wl_seat *wl_seat;
@@ -891,10 +898,10 @@ struct seat {
 
-  
 
@@ -902,7 +909,7 @@ struct seat {
   
-  
 
-- 
cgit v1.2.3



 

   
-    The Wayland Protocol
+    The Wayland book
   Extensive introduction to Wayland programming written by the Wayland author,
-  unfortunately unachieved.
+  Extensive introduction to Wayland programming written by the author of the sway
+  compositor, unfortunately unachieved.
   
 

     Wayland Explorer
   Documentation of all Wayland protocols, both stable and unstable. A language-independent syntax is used which makes function names usable in the C language not always obvious. Also some useful functions seem undocumented here for an unclear reason.
+  Documentation of all Wayland protocols, both stable and unstable. A language-independent syntax is used which makes function names usable from C or C++ not always obvious. Some useful functions seem undocumented here for an unclear reason.