Mirrors_UI_SDK/fltk
1
0
Fork 0
mirror of https://github.com/fltk/fltk.git synced 2026-05-20 04:31:25 +08:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

Wayland.dox: add a few more detailed explanations

Browse Source
This commit is contained in:
ManoloFLTK
2023-06-21 21:05:47 +02:00
parent c43cf2f192
commit eca471eee6
1 changed files with 45 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files
documentation/src/wayland.dox
+45 -28
View File
@@ -54,7 +54,7 @@ Wayland allows to create popup windows positioned relatively to a previously map
window. This allows FLTK to position adequately menu and tooltip windows, see
\ref menu-windows.
Wayland uses a trick of its own to handle lists of linked records. It defines the opaque type
Wayland uses a trick of its own to handle lists of linked records. It defines 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
lists must contain a member variable of type <tt>struct wl_list</tt> used to link records together
@@ -96,7 +96,8 @@ to a mapped Fl_Window.
Classes \c Fl_Wayland_Window_Driver, \c Fl_Wayland_Screen_Driver, \c Fl_Wayland_Graphics_Driver,
\c Fl_Wayland_Copy_Surface_Driver, \c Fl_Wayland_Image_Surface_Driver and
\c Fl_Wayland_Gl_Window_Driver contain all the Wayland-specific code of the FLTK library.
\c Fl_Wayland_Gl_Window_Driver and \c file fl_wayland_platform_init.cxx
contain all the Wayland-specific code of the FLTK library.
This code is located at \c src/drivers/Wayland/ in the FLTK source tree.
A single C++ source file generally contains all the code of a given class.
The code related to copy, paste and drag-and-drop operations, however,
@@ -111,7 +112,7 @@ The public C API to Wayland, xkb and libdecor libraries are obtained with
#include <wayland-cursor.h>
#include <xkbcommon/xkbcommon.h>
#include <xkbcommon/xkbcommon-compose.h>
#include <linux/input.h>
#include <linux/input.h> // for BTN_LEFT, BTN_RIGHT, BTN_MIDDLE
#include "../../../libdecor/src/libdecor.h"
#include "../../../libdecor/src/libdecor-plugin.h"
\endcode
@@ -142,8 +143,8 @@ use the same type name for different purposes or the same symbol name.
That is why function <tt>fl_xid(const Fl_Window*)</tt> is deprecated in FLTK 1.4 and replaced by
\c fl_wl_xid() for Wayland and \c fl_x11_xid() for X11. Also, global variable
<tt>Window fl_window</tt> is not used by the Wayland platform which instead uses
<tt>static struct wld_window *Fl_Wayland_Window_Driver:: wld_window;</tt>.
The FLTK library contains also a dedicated source file,
<tt>static struct wld_window *Fl_Wayland_Window_Driver:: wld_window</tt>.
The FLTK library contains also a short source file,
\c fl_wayland_platform_init.cxx, that determines, at startup time, whether
the app will run as a Wayland or as an X11 client. Function \c attempt_wayland() therein performs
this choice as follows :
@@ -180,19 +181,26 @@ corresponding Wayland object, usually right after the object's creation, by a ca
specific Wayland function named following the form \c wl_XXX_add_listener().
For example, this code:
\code
static void surface_enter(……) { …… } // called when a surface enters a display
static void surface_leave(……) { …… } // called when a surface leaves a display
static struct wl_surface_listener surface_listener = {
surface_enter,
surface_leave,
};
pointer_type pter_to_data;
struct wl_surface *my_wl_surface;
my_wl_surface = wl_compositor_create_surface(scr_driver->wl_compositor);
wl_surface_add_listener(my_wl_surface, &surface_listener, pter_to_data);
some_pointer_type pter_to_data;
struct wl_surface *my_wl_surface;
my_wl_surface = wl_compositor_create_surface(scr_driver->wl_compositor);
wl_surface_add_listener(my_wl_surface, &surface_listener, pter_to_data);
\endcode
creates a Wayland object of type <tt>struct wl_surface</tt>, associates
a 2-member listener called \c surface_listener to it,
and associates \c pter_to_data to it as <em>user data</em>. The \c wl_surface object's
creates a Wayland object of type <tt>struct wl_surface</tt>, and associates it with
a 2-member listener called \c surface_listener. After this, Wayland is expected to call
the 2 listener members, \c surface_enter or \c surface_leave, each time \c my_wl_surface will
enter or leave, respectively, a display. The arguments of these calls, not detailed here,
allow the member functions to identify which surface enters or leaves which display.
The \c wl_surface_add_listener() call above also associates \c pter_to_data to
\c my_wl_surface as <em>user data</em>. The \c wl_surface object's
"user data" can be obtained later calling function \c wl_surface_get_user_data().
Wayland function \c wl_proxy_get_listener() returns a pointer
@@ -231,19 +239,25 @@ 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:
\code
static const struct wl_callback_listener sync_listener = {
sync_done
};
static void sync_done(void *data, struct wl_callback *cb, uint32_t time) {
*(struct wl_callback **)data = NULL;
wl_callback_destroy(cb);
}
struct wl_callback *registry_cb = wl_display_sync(wl_display);
wl_callback_add_listener(registry_cb, &sync_listener, &registry_cb);
while (registry_cb) wl_display_dispatch(wl_display);
static const struct wl_callback_listener sync_listener = {
sync_done
};
struct wl_callback *registry_cb = wl_display_sync(wl_display);
wl_callback_add_listener(registry_cb, &sync_listener, &registry_cb);
while (registry_cb) wl_display_dispatch(wl_display);
\endcode
A pointer to an object of type <tt>struct wl_callback</tt> created by function
\c wl_display_sync() is assigned to variable \c registry_cb.
Then a 1-member listener is attached to this object. Wayland will run this listener's
member function, \c sync_done(), after all calls to \c registry_handle_global() have
occurred. Function \c sync_done() sets to null variable \c registry_cb.
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.
@@ -259,8 +273,9 @@ and version of a component or feature of the Wayland system. It's necessary to c
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", \c the value returned by wl_registry_bind() is
stored as member \c wl_compositor of the \c Fl_Wayland_Screen_Driver object.
For example, when \c interface equals "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 KDE compositor is connected
and stores this information in static member variable \c Fl_Wayland_Screen_Driver::compositor.
@@ -548,9 +563,9 @@ in function \c Fl_Wayland_Window_Driver::make_current() with
Thus, \c buffer_commit() runs only when \c cb is NULL. If an app rapidly performs calls
to Fl_Window::make_current() and to drawing functions, FLTK will copy \c draw_buffer to the Wayland
buffer and instruct Wayland to map it to the display when \c cb is NULL
which means that the compositor is ready to start performing a mapping operation, and will only
modify \c draw_buffer when \c cb is not NULL, letting the compositor complete its ongoing
mapping task.
which means that the compositor is ready to start performing a mapping operation.
In contrast, FLTK will only modify \c draw_buffer when \c cb is not NULL, letting the compositor
complete its ongoing mapping task.
For example, FLTK's mandelbrot test app set to fullscreen can be seen to progressively fill its window from
top to bottom by blocks of lines, each block appearing when the compositor is ready to map
a new buffer. When the compositor is not ready, the app does not block but continues
@@ -1019,10 +1034,12 @@ Files dropped are received one pathname per line, with no \c '\\n' after the las
Wayland uses <a href=https://www.khronos.org/api/egl>EGL™</a> to interface OpenGL with the underlying
native platform window system. OpenGL-using FLTK apps are therefore linked to \c libwayland-egl.so and
\c libEGL.so in addition to \c libGL.so and \c libGLU.so. These librairies allow FLTK to
create and initialize an EGL display connection, create objects of type \c wl_egl_window,
\c EGLSurface, and \c GLContext. An object of type \c wl_egl_window is created by function
\c Fl_Wayland_Gl_Window_Driver::make_current_before() in reference to
an existing \c wl_surface object which connects this EGL-object with a given Wayland window.
create and initialize an EGL display connection, and create objects of type \c wl_egl_window,
\c EGLSurface, and \c GLContext.
Function \c Fl_Wayland_Gl_Window_Driver::make_current_before() creates an object of type
\c wl_egl_window for each show()'n \c Fl_Gl_Window calling function \c wl_egl_window_create().
The first argument of this call of type <tt>struct wl_surface</tt> is how a Wayland window is
set to use OpenGL.
FLTK calls function \c Fl_Wayland_Gl_Window_Driver::swap_buffers() each time it wants a GL context
to be sent to the display. This function contains some pure GL code to emulate an overlay buffer