From 9d869d73c1ca8f6c884f528a3ad4f623f25dffb1 Mon Sep 17 00:00:00 2001 From: ManoloFLTK <41016272+ManoloFLTK@users.noreply.github.com> Date: Thu, 10 Mar 2022 15:05:26 +0100 Subject: Begin documenting the Wayland platform, new in FLTK version 1.4 --- documentation/src/drawing.dox | 8 +++-- documentation/src/opengl.dox | 21 ++++++++++++ documentation/src/osissues.dox | 76 ++++++++++++++++++++++++++++++++++++++++++ documentation/src/preface.dox | 9 +++-- 4 files changed, 110 insertions(+), 4 deletions(-) (limited to 'documentation') diff --git a/documentation/src/drawing.dox b/documentation/src/drawing.dox index 1eee9f195..a80286f68 100644 --- a/documentation/src/drawing.dox +++ b/documentation/src/drawing.dox @@ -69,11 +69,15 @@ The current scale factor value, for an Fl_Window named \e window, is given by One drawing unit generally corresponds to one screen pixel ...
  • ... but not on macOS and for retina displays, where one drawing unit corresponds to two pixels. + +
  • ... and not with the Wayland platform, where one drawing unit may +correspond to 1, 2, or 3 pixels according to the current value of the +Wayland-defined, integer-valued scale factor. At application start time, FLTK attempts to detect the adequate scale factor value for -each screen of the system. Here is how that's done under the \ref osissues_x_scaling "X11" -and \ref osissues_windows_scaling "Windows" platforms. +each screen of the system. Here is how that's done under the \ref osissues_x_scaling "X11", +\ref osissues_windows_scaling "Windows", and \ref osissues_wayland_scaling "Wayland" platforms. If the resulting scale factor is not satisfactory, and also under the macOS platform, it's possible to set the FLTK_SCALING_FACTOR environmental variable to the desired numerical value diff --git a/documentation/src/opengl.dox b/documentation/src/opengl.dox index 668e26ef9..c80d4fd85 100644 --- a/documentation/src/opengl.dox +++ b/documentation/src/opengl.dox @@ -614,6 +614,27 @@ glewExperimental = GL_TRUE; \endcode before the glewInit() call. +\par Testing for success of the glewInit() call +Testing whether the glewInit() call is successful is to be done as follows: +\code +#include // defines FLTK_USE_WAYLAND under the Wayland platform +#include // for Fl::warning() +#ifndef __APPLE__ +# if defined(_WIN32) +# define GLEW_STATIC 1 +# endif +# include + + GLenum err = glewInit(); // defines pters to functions of OpenGL V 1.2 and above +# ifdef FLTK_USE_WAYLAND + // glewInit returns GLEW_ERROR_NO_GLX_DISPLAY with Wayland + if (err == GLEW_ERROR_NO_GLX_DISPLAY) err = GLEW_OK; +# endif + if (err != GLEW_OK) Fl::warning("glewInit() failed returning %u", err); +#endif // ! __APPLE__ +\endcode + + \par Changes in the build process Link with libGLEW.so (on Unix/Linux), libglew32.a (with MinGW) or glew32.lib (with MS Visual Studio); no change is needed on the Mac OS platform. diff --git a/documentation/src/osissues.dox b/documentation/src/osissues.dox index 82d28d1d8..4caccda11 100644 --- a/documentation/src/osissues.dox +++ b/documentation/src/osissues.dox @@ -7,6 +7,7 @@ This appendix describes the operating system specific interfaces in FLTK: \li \ref osissues_unix \li \ref osissues_win32 \li \ref osissues_macos +\li \ref osissues_wayland \section osissues_accessing Accessing the OS Interfaces @@ -928,6 +929,81 @@ FLTK uses UTF-8-encoded UNIX-style filenames and paths. \sa group_macosx +\section osissues_wayland The Wayland Interface + +Wayland-specific source code can be organized as follows to be distinguished +from X11-specific source code : +\code +#include // defines FLTK_USE_WAYLAND or FLTK_USE_X11 as appropriate + +#if defined(FLTK_USE_WAYLAND) +… Wayland-specific source code … +#elif defined(FLTK_USE_X11) +… X11-specific source code … +#endif +\endcode + +extern struct wl_display *fl_display; +\par +After fl_open_display() has run, the \c fl_display global variable points to the +struct wl_display representing the connection between the application and Wayland. +Therefore, \c wl_display_get_fd(fl_display) gives the file descriptor one can +use to communicate with the Wayland compositor according to the Wayland protocol. + +Window fl_xid(const Fl_Window *) +\par +Returns a pointer to an FLTK-defined structure holding Wayland-related +data created when a window gets show()'n, or NULL if not show()'n. + +Fl_Window *fl_find(Window wld_win) +\par +Returns the Fl_Window that corresponds to the given Window, or NULL if not found. + +struct wl_surface *fl_wl_surface(Window wld_win) +\par +Returns a pointer to the struct wl_surface corresponding to a show()'n +top-level window or subwindow. + +struct _cairo *fl_wl_cairo(void) +\par +Drawing natively to a Wayland window : Within an overridden Fl_Widget::draw() method, +or after a call to Fl_Window::make_current(), it's possible to draw +using the Cairo library. Function \c fl_wl_cairo() returns the adequate +\c cairo_t* (equivalent to struct _cairo*) value. All FLTK-defined +drawing functions (e.g., fl_rect(), fl_draw()) can be used too. + +void fl_close_display() +\par +This closes the Wayland connection. You do not need to call +this to exit. It may be useful to call this if you want your program to continue +without the Wayland connection. You cannot open the display again, and +cannot call any FLTK functions. + +\subsection osissues_wayland_scaling HiDPI display support +FLTK Wayland apps automatically scale according to the Wayland-defined, integer-valued +scale factor. On a HiDPI display, it's enough to set this factor to 2 for +any FLTK app to be drawn using twice as many pixels and thus to be as readable +as it is on a regular display. With the gnome desktop, that is achieved in the +"Displays" section of the "Settings" application, selecting 200 % for the "Scale" parameter. +In addition to this, FLTK apps can also be scaled up or down typing ctrl/+/-/0/ +and with the \c FLTK_SCALING_FACTOR environment variable. + +\subsection osissues_wayland_decoration Window titlebars +Wayland supports both client-side window decoration (CSD), where client applications +are responsible for drawing window titlebars, and server-side window +decoration (SSD), where the Wayland compositor itself draws window titlebars. Among 3 +tested Wayland compositors, Mutter (gnome's compositor) and Weston use CSD mode +whereas the KDE compositor uses SSD mode. When running in CSD mode, FLTK uses a library called +libdecor to draw titlebars. +The libdecor library has been conceived to use various plug-in's to draw +titlebars in various fashions intended to match any desktop's preferred titlebar style. +FLTK supports drawing titlebars with any libdecor plug-in via an environment variable +called \c LIBDECOR_PLUGIN_DIR which can be given the name of a directory containing the +desired plug-in. When \c LIBDECOR_PLUGIN_DIR is not defined, or points to a directory +that doesn't contain a libdecor plug-in, FLTK uses its built-in plug-in to draw titlebars. +That is the most common situation, until libdecor plug-in's become available +for popular UNIX desktops. + \htmlonly
    diff --git a/documentation/src/preface.dox b/documentation/src/preface.dox index ab61efc03..c62a9d664 100644 --- a/documentation/src/preface.dox +++ b/documentation/src/preface.dox @@ -4,8 +4,13 @@ This manual describes the Fast Light Tool Kit ("FLTK") version 1.4.0, a C++ Graphical User Interface -("GUI") toolkit for UNIX, Microsoft Windows and Apple OS X. Each -of the chapters in this manual is designed as a tutorial for +("GUI") toolkit for UNIX, Microsoft Windows and Apple OS X. + +Version 1.4.0 introduces support for a new windowing system +under UNIX: Wayland. Thus, FLTK applications under UNIX can +now be built to use either X11 or Wayland as windowing system. + +Each of the chapters in this manual is designed as a tutorial for using FLTK, while the appendices provide a convenient reference for all FLTK widgets, functions, and operating system interfaces. -- cgit v1.2.3