osissues.dox: add "The Wayland/X11 hybrid library"
This commit is contained in:
ManoloFLTK
parent
8178d95eb6
commit
1a8d6662ce
@ -11,15 +11,10 @@ Contents
|
||||
2.1 Configuration
|
||||
2.2 Known Limitations
|
||||
|
||||
3 Preparing Platform Specific Code for the Wayland Platform
|
||||
3.1 Handling X11 specific Source Code
|
||||
3.2 Handling X11 and Wayland Specific Source Code in the Same App
|
||||
3.3 Forcing an FLTK App to Always Use the X11 Backend
|
||||
|
||||
4 Platform Specific Notes
|
||||
4.1 Debian and Derivatives (like Ubuntu)
|
||||
4.2 Fedora
|
||||
4.3 FreeBSD
|
||||
3 Platform Specific Notes
|
||||
3.1 Debian and Derivatives (like Ubuntu)
|
||||
3.2 Fedora
|
||||
3.3 FreeBSD
|
||||
|
||||
|
||||
1 Introduction
|
||||
@ -31,7 +26,7 @@ Pre-existing platform-independent source code for FLTK 1.3.x should build and
|
||||
run unchanged with FLTK 1.4 and the Wayland platform.
|
||||
The code has been tested on Debian, Ubuntu, RaspberryPiOS and Fedora with
|
||||
3 distinct Wayland compositors: mutter (Gnome's compositor), weston, and KDE.
|
||||
The code has also been tested under FreeBSD and the sway wayland compositor.
|
||||
The code has also been tested under FreeBSD and the Sway Wayland compositor.
|
||||
CJK text-input methods, as well as dead and compose keys are supported.
|
||||
|
||||
|
||||
@ -54,7 +49,12 @@ X11 is used at run time as follows:
|
||||
compositor is available;
|
||||
- if $FLTK_BACKEND has another value, the library stops with error.
|
||||
|
||||
See also 3.3 below for another way to control whether Wayland or X11 is used.
|
||||
Alternatively, it is possible to force a program linked to a Wayland-enabled
|
||||
FLTK library to use X11 in all situations by putting this declaration somewhere
|
||||
in the source code :
|
||||
FL_EXPORT bool fl_disable_wayland = true;
|
||||
FLTK source code and also X11-specific source code conceived for FLTK 1.3
|
||||
should run with a Wayland-enabled, FLTK 1.4 library with that single change only.
|
||||
|
||||
On pure Wayland systems without the X11 headers and libraries, FLTK can be built
|
||||
with its Wayland backend only (see below).
|
||||
@ -63,7 +63,7 @@ with its Wayland backend only (see below).
|
||||
------------------
|
||||
|
||||
On Linux and FreeBSD systems equipped with the adequate software packages
|
||||
(see section 4 below), the default building procedure produces a Wayland/X11
|
||||
(see section 3 below), the default building procedure produces a Wayland/X11
|
||||
hybrid library. On systems lacking all or part of Wayland-required packages,
|
||||
the default building procedure produces a X11-based library.
|
||||
|
||||
@ -106,86 +106,13 @@ so feedback on this subject would be helpful.
|
||||
although it works inside X11 windows on the same hardware.
|
||||
|
||||
|
||||
3 Preparing Platform Specific Code for the Wayland Platform
|
||||
===========================================================
|
||||
|
||||
While platform-independent source code prepared for FLTK 1.3 is expected
|
||||
to be compatible with no change with FLTK 1.4 and the Wayland platform,
|
||||
X11-specific source code may require some attention.
|
||||
|
||||
3.1 Handling X11 specific Source Code
|
||||
-------------------------------------
|
||||
|
||||
If an FLTK 1.4 application contains X11-specific code, execution of this code
|
||||
in the context of an active Wayland session can produce malfunctions or program crashes.
|
||||
To ensure that X11-specific code gets called only when an X11 connection is active,
|
||||
check that function fl_x11_display() returns non-NULL before using any X11-specific
|
||||
function or variable.
|
||||
|
||||
3.2 Handling X11 and Wayland Specific Source Code in the Same App
|
||||
-----------------------------------------------------------------
|
||||
|
||||
The recommended way to prepare and use platform-specific code that would contain
|
||||
X11-specific and possibly Wayland-specific parts is as follows :
|
||||
|
||||
a) Organize platform-specific code as follows¹:
|
||||
|
||||
#include <FL/platform.H>
|
||||
|
||||
#ifdef __APPLE__
|
||||
*** macOS-specific code ***
|
||||
#elif defined(_WIN32)
|
||||
*** Windows-specific code ***
|
||||
#else
|
||||
# ifdef FLTK_USE_X11
|
||||
*** X11-specific code ***
|
||||
# endif
|
||||
# ifdef FLTK_USE_WAYLAND
|
||||
*** Wayland-specific code ***
|
||||
# endif
|
||||
#endif
|
||||
|
||||
b) Make sure to use distinct names for global variables and functions
|
||||
in the X11- and the Wayland-specific sections.
|
||||
|
||||
c) Check that function fl_x11_display() returns non-NULL before using any X11-specific
|
||||
function or variable, and that fl_wl_display() returns non-NULL before using any
|
||||
Wayland-specific function or variable. Make sure that fl_open_display() was called
|
||||
directly or indirectly before using any such symbol.
|
||||
|
||||
¹ To be also compatible with macOS+XQuartz, a slightly different organization is necessary:
|
||||
#include <FL/platform.H>
|
||||
#if defined(FLTK_USE_X11) || defined(FLTK_USE_WAYLAND)
|
||||
# ifdef FLTK_USE_X11
|
||||
*** X11-specific code which can run under Linux/Unix or under macOS+XQuartz ***
|
||||
# endif
|
||||
# ifdef FLTK_USE_WAYLAND
|
||||
*** Wayland-specific code ***
|
||||
# endif
|
||||
#elif defined(__APPLE__)
|
||||
*** macOS-specific code which doesn't run under XQuartz ***
|
||||
#elif defined(_WIN32)
|
||||
*** Windows-specific code ***
|
||||
#endif
|
||||
|
||||
3.3 Forcing an FLTK App to Always Use the X11 Backend
|
||||
-----------------------------------------------------
|
||||
|
||||
Alternatively, it is possible to force a program linked to a Wayland-enabled
|
||||
FLTK library to use X11 in all situations by putting this declaration somewhere
|
||||
in the source code :
|
||||
FL_EXPORT bool fl_disable_wayland = true;
|
||||
FLTK source code and also X11-specific source code conceived for FLTK 1.3
|
||||
should run with a Wayland-enabled, FLTK 1.4 library with that single change only.
|
||||
|
||||
|
||||
4 Platform Specific Notes
|
||||
3 Platform Specific Notes
|
||||
=========================
|
||||
|
||||
The following are notes about building FLTK for the Wayland platform
|
||||
on the various supported Linux distributions/OS.
|
||||
|
||||
4.1 Debian and Derivatives (like Ubuntu, RaspberryPiOS)
|
||||
3.1 Debian and Derivatives (like Ubuntu, RaspberryPiOS)
|
||||
-------------------------------------------------------
|
||||
|
||||
Under Debian, the Wayland platform requires version 11 (a.k.a. Bullseye) or more recent.
|
||||
@ -216,7 +143,7 @@ These packages allow to run FLTK apps under the KDE/Plasma-Wayland desktop:
|
||||
Package installation command: sudo apt-get install <package-name ...>
|
||||
|
||||
|
||||
4.2 Fedora
|
||||
3.2 Fedora
|
||||
----------
|
||||
|
||||
The Wayland platform is known to work with Fedora version 35.
|
||||
@ -239,12 +166,12 @@ package groups listed in section 2.2 of file README.Unix.txt :
|
||||
Package installation command: sudo yum install <package-name ...>
|
||||
|
||||
|
||||
4.3 FreeBSD
|
||||
3.3 FreeBSD
|
||||
-----------
|
||||
|
||||
The Wayland platform is known to work with FreeBSD version 13.1 and the sway compositor.
|
||||
The Wayland platform is known to work with FreeBSD version 13.1 and the Sway compositor.
|
||||
|
||||
These packages are necessary to build the FLTK library and the sway compositor:
|
||||
These packages are necessary to build the FLTK library and use the Sway compositor:
|
||||
git autoconf pkgconf xorg urwfonts gnome glew seatd sway dmenu-wayland dmenu evdev-proto
|
||||
|
||||
Package installation command: sudo pkg install <package-name ...>
|
||||
|
||||
@ -4,6 +4,7 @@
|
||||
|
||||
This appendix describes the operating system specific interfaces in FLTK:
|
||||
\li \ref osissues_accessing
|
||||
\li \ref osissues_wl_x11_hybrid
|
||||
\li \ref osissues_unix
|
||||
\li \ref osissues_win32
|
||||
\li \ref osissues_macos
|
||||
@ -44,8 +45,40 @@ operating system.
|
||||
</TABLE>
|
||||
</CENTER>
|
||||
|
||||
\section osissues_wl_x11_hybrid The Wayland/X11 hybrid library
|
||||
|
||||
By default, the FLTK library is, under Linux and Unix, a Wayland/X11 hybrid which
|
||||
can run FLTK-based apps as Wayland clients or as X11 clients.
|
||||
The choice between running an app as a Wayland or an X11 client is done as follows,
|
||||
when the app runs function \c fl_open_display() (that function can be called explicitly by the app
|
||||
or implicitly by FLTK, for example the first time an Fl_Window is show()'n) :
|
||||
- if environment variable FLTK_BACKEND is not defined, Wayland is used if a Wayland compositor
|
||||
is available, otherwise X11 is used;
|
||||
- if $FLTK_BACKEND equals "wayland", the library makes the app a Wayland client, and stops
|
||||
with error if no Wayland compositor is available;
|
||||
- if $FLTK_BACKEND equals "x11", the library makes the app an X11 client even if a Wayland
|
||||
compositor is available.
|
||||
|
||||
After function \c fl_open_display() has been called, exactly one of the functions \c fl_wl_display()
|
||||
and \c fl_x11_display() returns a non-NULL value.
|
||||
When the former function does, the app runs as a Wayland client,
|
||||
and Wayland-specific functions and symbols described below (\ref osissues_wayland) can be used, whereas
|
||||
X11-specific functions and symbols cannot. Otherwise, the app runs as an X11 client, and only
|
||||
X11-specific functions and symbols below (\ref osissues_unix) can be used.
|
||||
|
||||
Because a single app can be expected to run either Wayland or X11, it's necessary to use distinct
|
||||
names for global variables and functions in the X11- and the Wayland-specific source code.
|
||||
|
||||
Non-default configurations of the FLTK library under Linux/Unix are described in
|
||||
file README.Wayland.txt.
|
||||
|
||||
\section osissues_unix The UNIX (X11) Interface
|
||||
|
||||
Cross-platform applications should bracket X11-specific source code between
|
||||
<tt>\#if defined(FLTK_USE_X11) / \#endif</tt> and should ensure function
|
||||
\c fl_x11_display() returns non-NULL before calling X11-specific functions and using
|
||||
X11-specific symbols.
|
||||
|
||||
The UNIX interface provides access to the X Window System
|
||||
state information and data structures.
|
||||
|
||||
@ -494,6 +527,9 @@ what is done by the gnome and KDE desktops.
|
||||
|
||||
\section osissues_win32 The Windows Interface
|
||||
|
||||
Cross-platform applications should bracket Windows-specific source code between
|
||||
<tt>\#ifdef _WIN32 / \#endif</tt>.
|
||||
|
||||
The Windows interface provides access to the Windows GDI
|
||||
state information and data structures.
|
||||
|
||||
@ -712,6 +748,9 @@ version of FLTK:
|
||||
|
||||
\section osissues_macos The Apple OS X Interface
|
||||
|
||||
Cross-platform applications should bracket macOS-specific source code between
|
||||
<tt>\#if defined(\_\_APPLE\_\_) && !defined(FLTK_USE_X11) / \#endif</tt>.
|
||||
|
||||
FLTK supports Apple OS X using the Apple Cocoa library. Older
|
||||
versions of MacOS are no longer supported.
|
||||
|
||||
@ -948,8 +987,10 @@ FLTK uses UTF-8-encoded UNIX-style filenames and paths.
|
||||
|
||||
\section osissues_wayland The Wayland Interface
|
||||
|
||||
See file README.Wayland.txt for details about how to organize platform-specific
|
||||
source code for the Wayland platform.
|
||||
Cross-platform applications should bracket Wayland-specific source code between
|
||||
<tt>\#ifdef FLTK_USE_WAYLAND / \#endif</tt> and should ensure function
|
||||
\c fl_wl_display() returns non-NULL before calling Wayland-specific functions and using
|
||||
Wayland-specific symbols.
|
||||
|
||||
extern struct wl_display *fl_wl_display();
|
||||
\par
|
||||
|
||||
Loading…
Reference in New Issue
Block a user