Wayland developer's documentation: miscellaneous updates
This commit is contained in:
ManoloFLTK
parent
c8c5725628
commit
b8d2359a3c
@ -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
|
||||
<tt>xdg shell</tt> 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
|
||||
<tt>struct wl_list</tt> 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 <xkbcommon/xkbcommon-compose.h>
|
||||
#include <linux/input.h>
|
||||
#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 <tt>os_create_anonymous_file(off_t size)</tt> 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
|
||||
<a href=https://gitlab.freedesktop.org/wayland/wayland/-/blob/main/cursor/wayland-cursor.c>
|
||||
wayland-cursor.c</a> 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 <tt>struct wl_cursor_image</tt> object, this one being part of the public Wayland API.
|
||||
It also shows that a <tt>struct cursor_image</tt> 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
|
||||
<tt>struct wl_keyboard_listener</tt>. 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 <tt>wl_keyboard</tt> 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 <tt>struct zwp_text_input_manager_v3 *</tt> 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 <tt>struct zwp_text_input_manager_v3</tt> 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()</a>.
|
||||
\section wayland-type FLTK-defined, Wayland-specific types
|
||||
|
||||
\anchor wld_window
|
||||
- <tt>struct wld_window</tt> is defined in \c Fl_Wayland_Window_Driver.H. One such record is created
|
||||
<h3>struct wld_window</h3>
|
||||
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 <tt>struct wld_window</tt> of its argument.
|
||||
<pre>
|
||||
@ -810,7 +815,8 @@ struct wld_window {
|
||||
</pre>
|
||||
|
||||
\anchor fl_wld_buffer
|
||||
- <tt>struct fl_wld_buffer</tt> is defined in \c Fl_Wayland_Graphics_Driver.H. One such record is
|
||||
<h3>struct fl_wld_buffer</h3>
|
||||
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().
|
||||
<pre>
|
||||
struct fl_wld_buffer {
|
||||
@ -827,7 +833,8 @@ struct fl_wld_buffer {
|
||||
</pre>
|
||||
|
||||
\anchor output
|
||||
- <tt>struct output</tt> is defined inside class \c Fl_Wayland_Screen_Driver. One such record is
|
||||
<h3>struct output</h3>
|
||||
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
|
||||
};
|
||||
</pre>
|
||||
|
||||
|
||||
\anchor seat
|
||||
- <tt>struct seat</tt> 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
|
||||
<h3>struct seat</h3>
|
||||
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.
|
||||
<pre>
|
||||
struct seat {
|
||||
struct wl_seat *wl_seat;
|
||||
@ -891,10 +898,10 @@ struct seat {
|
||||
<table summary="Wayland Documentation" width="100%" border="1">
|
||||
<tr>
|
||||
<td>
|
||||
<a href=https://wayland-book.com/>The Wayland Protocol</a>
|
||||
<a href=https://wayland-book.com/>The Wayland book</a>
|
||||
</td>
|
||||
<td>Extensive introduction to Wayland programming written by the Wayland author,
|
||||
unfortunately unachieved.
|
||||
<td>Extensive introduction to Wayland programming written by the author of the <i>sway</i>
|
||||
compositor, unfortunately unachieved.
|
||||
<td>
|
||||
</tr>
|
||||
|
||||
@ -902,7 +909,7 @@ struct seat {
|
||||
<td>
|
||||
<a href=https://wayland.app/protocols/>Wayland Explorer</a>
|
||||
</td>
|
||||
<td>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.
|
||||
<td>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.
|
||||
<td>
|
||||
</tr>
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user