From b328c1f90257e21f1fa2883dd7f18b22fd61592e Mon Sep 17 00:00:00 2001
From: ManoloFLTK <41016272+ManoloFLTK@users.noreply.github.com>
Date: Mon, 28 Aug 2023 10:16:01 +0200
Subject: Wayland.dox: some rephrasing
---
documentation/src/wayland.dox | 43 +++++++++++++++++++++----------------------
src/Fl_Device.cxx | 4 ++--
2 files changed, 23 insertions(+), 24 deletions(-)
diff --git a/documentation/src/wayland.dox b/documentation/src/wayland.dox
index 78fc5ce84..3983c26f2 100644
--- a/documentation/src/wayland.dox
+++ b/documentation/src/wayland.dox
@@ -44,7 +44,7 @@ below).
Wayland differs noticeably from X11 in that rendering is left to clients: Wayland provides
no drawing API. Instead, Wayland provides objects of type struct wl_buffer which
-bundle a memory array of pixel values shared between the client and the compositor.
+encapsulate a memory array of pixel values shared between the client and the compositor.
The client app is expected to draw to that memory buffer with whatever means it chooses,
and to instruct the compositor to map those pixels to the display when the drawing
is complete. The Wayland platform of FLTK draws with the Cairo library to \c Fl_Window's
@@ -538,9 +538,9 @@ Section \ref wayland-buffer-factory below details how FLTK creates \c wl_buffer
FLTK associates to each surface a
struct Fl_Wayland_Graphics_Driver::wld_buffer (see \ref wld_buffer) containing
-a pointer to the byte array of the Cairo image surface (member \c buffer), information about the
+a pointer to the byte array of the Cairo image surface (member \c draw_buffer.buffer), information about the
Wayland buffer (members \c wl_buffer and \c data), the common size of the Cairo surface's and
-Wayland buffer's byte arrays (member \c data_size), and other information. A pointer to this
+Wayland buffer's byte arrays (member \c draw_buffer.data_size), and other information. A pointer to this
struct Fl_Wayland_Graphics_Driver::wld_buffer is memorized as member \c buffer of the Fl_Window's \ref wld_window.
All drawing operations to the Fl_Window then modify the content of the Cairo image surface.
@@ -604,7 +604,7 @@ static void surface_frame_done(void *data, struct wl_callback *cb, uint32_t time
}
\endcode
which, provided member variable \c draw_buffer_needs_commit is true, calls
-\c Fl_Wayland_Graphics_Driver::buffer_commit(). This makes the compositor maps the
+\c Fl_Wayland_Graphics_Driver::buffer_commit(). This makes the compositor map the
Wayland buffer in its new, more advanced, state. Here is where member variable
\c draw_buffer_needs_commit is useful : it informs Wayland that the graphics
buffer has changed and needs being committed. This variable is turned \c true
@@ -1160,25 +1160,18 @@ struct wld_window {
}
-\anchor wld_buffer
-struct wld_buffer and struct draw_buffer
-They are defined as types of class \c Fl_Wayland_Graphics_Driver in file
-\c Fl_Wayland_Graphics_Driver.H.
-One struct Fl_Wayland_Graphics_Driver::wld_buffer record is created
-by \c Fl_Wayland_Graphics_Driver::create_shm_buffer() when
-an Fl_Window is show()'n or resized,
-when a custom cursor shape is created, or when text is dragged.
-
-A struct Fl_Wayland_Graphics_Driver::draw_buffer record
-is created when an Fl_Image_Surface object is created.
+\anchor draw_buffer
+struct Fl_Wayland_Graphics_Driver::draw_buffer
+Defined in file \c Fl_Wayland_Graphics_Driver.H.
+One such record is created when an Fl_Image_Surface object is created.
One such record is also embedded inside each
-struct Fl_Wayland_Graphics_Driver::wld_buffer record.
+struct Fl_Wayland_Graphics_Driver::wld_buffer record (see \ref wld_buffer).
struct Fl_Wayland_Graphics_Driver::draw_buffer {
- size_t data_size; // of wl_buffer and buffer
+ size_t data_size; // of wl_buffer and buffer, in bytes
int stride; // bytes per line
- int width;
+ int width; // in pixels
unsigned char *buffer; // address of the beginning of the Cairo image surface's byte array
cairo_t *cairo_; // used when drawing to the Cairo image surface
};
@@ -1186,13 +1179,19 @@ struct Fl_Wayland_Graphics_Driver::draw_buffer {
FLTK gives offscreen buffers the platform-dependent type \c Fl_Offscreen which is
in fact member \c cairo_ of struct Fl_Wayland_Graphics_Driver::draw_buffer.
Thus, a variable with type \c Fl_Offscreen needs be casted to type \c cairo_t*.
-Member function struct Fl_Wayland_Graphics_Driver::draw_buffer *
-Fl_Wayland_Graphics_Driver::offscreen_buffer(Fl_Offscreen);
-returns the \c draw_buffer record corresponding to an \c Fl_Offscreen value.
+
Static member function struct draw_buffer *offscreen_buffer(Fl_Offscreen)
+of class \c Fl_Wayland_Graphics_Driver returns the \c draw_buffer record corresponding
+to an \c Fl_Offscreen value.
+\anchor wld_buffer
+struct Fl_Wayland_Graphics_Driver::wld_buffer
+Defined in file \c Fl_Wayland_Graphics_Driver.H.
+One such record is created by \c Fl_Wayland_Graphics_Driver::create_shm_buffer() when
+an Fl_Window is show()'n or resized, when a custom cursor shape is created, or when
+text is dragged.
struct Fl_Wayland_Graphics_Driver::wld_buffer {
- struct draw_buffer draw_buffer;
+ struct draw_buffer draw_buffer; // see \ref draw_buffer
struct wl_buffer *wl_buffer; // the Wayland buffer
void *data; // address of the beginning of the Wayland buffer's byte array
struct wl_callback *cb; // non-NULL while Wayland buffer is being committed
diff --git a/src/Fl_Device.cxx b/src/Fl_Device.cxx
index bfd9db063..b6c3f4da0 100644
--- a/src/Fl_Device.cxx
+++ b/src/Fl_Device.cxx
@@ -49,14 +49,14 @@
+- Fl_Graphics_Driver -> directed to an Fl_Surface_Device object
|
- +- Fl_PostScript_Graphics_Driver: platform-independent graphics driver for PostScript drawing
+ +- Fl_PostScript_Graphics_Driver: platform-independent graphics driver for PostScript/EPS drawing
+- Fl_SVG_Graphics_Driver: platform-independent graphics driver for Scalable Vector Graphics drawing
+- Fl_Quartz_Graphics_Driver: platform-specific graphics driver (MacOS)
+- Fl_Quartz_Printer_Graphics_Driver: MacOS-specific, for drawing to printers
+- Fl_Scalable_Graphics_Driver: helper class to support GUI scaling
+- Fl_Xlib_Graphics_Driver: X11-specific graphics driver
+- Fl_GDI_Graphics_Driver: Windows-specific graphics driver
- +- Fl_GDI_Printer_Graphics_Driver: re-implements a few member functions especially for output to printer
+ +- Fl_GDI_Printer_Graphics_Driver: overrides a few member functions especially for output to printer
+- Fl_Cairo_Graphics_Driver: full FLTK drawing API based on Cairo and Pango
+- Fl_Wayland_Graphics_Driver: Wayland-specific graphics driver
+- Fl_X11_Cairo_Graphics_Driver: used by X11 leg of hybrid Wayland/X11 platform
--
cgit v1.2.3