From 69cb2744152c12dd084b438c593b53299714b4c8 Mon Sep 17 00:00:00 2001
From: ManoloFLTK <41016272+ManoloFLTK@users.noreply.github.com>
Date: Wed, 28 Jun 2023 11:12:57 +0200
Subject: Documentation: beef-up the OpenGL section of wayland.dox

---
 documentation/src/wayland.dox | 57 ++++++++++++++++++++++++++++++++++---------
 1 file changed, 46 insertions(+), 11 deletions(-)

(limited to 'documentation/src')

diff --git a/documentation/src/wayland.dox b/documentation/src/wayland.dox
index 70e7ac316..87285319a 100644
--- a/documentation/src/wayland.dox
+++ b/documentation/src/wayland.dox
@@ -1037,21 +1037,56 @@ 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, 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
-to support Fl_Gl_Window objects overriding their \c draw_overlay() member function.
+\c libEGL.so in addition to \c libGL.so and \c libGLU.so.
+
+EGL is initialized calling member function \c Fl_Wayland_Gl_Window_Driver::init()
+once, the first time the \c Fl_Wayland_Gl_Window_Driver c'tor runs. That is done
+with calls to <tt>eglGetDisplay(), eglInitialize(), eglGetConfigs(), and
+eglBindAPI()</tt>. Function \c eglGetConfigs() computes the number of usable
+EGL frame buffer configurations for the display and stores it in static member variable
+\c Fl_Wayland_Gl_Window_Driver::configs_count.
+
+Member function \c Fl_Wayland_Gl_Window_Driver::find() calls \c eglChooseConfig()
+to filter the set of GL configurations that match the \c Fl_Gl_Window's mode(),
+and puts in the returned \c Fl_Gl_Choice object the first matching configuration.
+The filtering gets done with bits \c EGL_WINDOW_BIT, to support the creation of window
+surfaces, and \c EGL_OPENGL_BIT, to support the creation of OpenGL contexts.
+
+EGL needs 2 more objects created for each \c Fl_Gl_Window of type
+<tt>struct wl_egl_window</tt> and \c EGLSurface. Both are created by member
+function \c Fl_Wayland_Gl_Window_Driver::make_current_before() which runs at the
+beginning of \c Fl_Gl_Window::make_current().
+The first argument of the call to \c wl_egl_window_create() therein has type
+<tt>struct wl_surface *</tt> and is what connects EGL with the desired Wayland window.
+
+EGL creates with \c eglCreateContext() an object of type \c EGLContext via member
+function \c Fl_Wayland_Gl_Window_Driver::create_gl_context() called by
+\c Fl_Gl_Window::make_current(). Types \c EGLContext and \c GLContext are 2 names
+for the same object. The call to \c eglCreateContext() is made asking for a GL
+context of version at least 2. This does not prevent from obtaining contexts of higher
+versions, namely above 3.2, which are compatible with version 2 (the so-called
+compatibility profile) under all tested Linux systems.
+
+FLTK function \c Fl_Gl_Window::make_current() calls overridden function
+\c Fl_Wayland_Gl_Window_Driver::set_gl_context() which calls EGL function
+\c eglMakeCurrent() when the cached context changes.
+
+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 to support Fl_Gl_Window objects overriding their
+\c draw_overlay() member function.
 Then, it calls function \c eglSwapBuffers() after having called
 \c wl_display_dispatch_pending() to synchronize EGL use
 with the rest of the Wayland compositor's activity.
 
+The overridden \c Fl_Wayland_Gl_Window_Driver::resize() function is implemented with
+calls to \c wl_egl_window_get_attached_size() and \c wl_egl_window_resize().
+
+Class \c Fl_Wayland_Gl_Plugin exists to allow \c libfltk to call functions from
+\c libfltk_gl, \c libwayland-egl.so or \c libEGL.so and without having \c libfltk
+force linking any FLTK app with these GL-related libraries.
+For example, \c Fl_Wayland_Window_Driver::flush() needs to call
+\c Fl_Gl_Window::valid(0).
 
 \section wayland-type FLTK-defined, Wayland-specific types
 
-- 
cgit v1.2.3