[render] Canvas and WindowManager documentation

docs/Doxyfile

@@ -519,13 +519,13 @@ TIMESTAMP              = NO
 # normally produced when WARNINGS is set to YES.
 # The default value is: NO.
 
-EXTRACT_ALL            = YES
+EXTRACT_ALL            = NO
 
 # If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will
 # be included in the documentation.
 # The default value is: NO.
 
-EXTRACT_PRIVATE        = NO
+EXTRACT_PRIVATE        = YES
 
 # If the EXTRACT_PRIV_VIRTUAL tag is set to YES, documented private virtual
 # methods of a class will be included in the documentation.
@@ -2588,7 +2588,7 @@ CLASS_GRAPH            = YES
 # The default value is: YES.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-COLLABORATION_GRAPH    = YES
+COLLABORATION_GRAPH    = NO
 
 # If the GROUP_GRAPHS tag is set to YES then doxygen will generate a graph for
 # groups, showing the direct groups dependencies. Explicit enabling a group

vclib/render/include/vclib/render/concepts/canvas.h

@@ -28,6 +28,73 @@
 
 namespace vcl {
 
+/**
+ * @brief The CanvasConcept concept is used to check if a class satisfies the
+ * requirements of the Canvas concept.
+ *
+ * Each class that satisfies this concept can be used as a canvas in the
+ * @ref vcl::Renderer class (second template parameter). The Canvas class is
+ * responsible for managing the render backend and the surface where the Drawer
+ * objects can draw.
+ *
+ * It is a class that is templated on the Renderer class (using the CRTP
+ * pattern). The class is then allowed to access the member functions of the
+ * public members of the @ref vcl::Renderer class and all the members of the
+ * @ref vcl::Renderer::CNV inner class.
+ *
+ * @par Constructors
+ *
+ * The class must have the following constructors:
+ * - `CanvasType(void* winId, uint width, uint height)`: Constructor that
+ * initializes the canvas with the window id (the platform dependent
+ * identifier of the window where the canvas will be placed) and the initial
+ * size of the canvas.
+ * - `CanvasType(void* winId, uint width, uint height, void* displayId)`: Same
+ * as the previous constructor, but also takes the display id (the platform
+ * dependent identifier of the display where the window is placed - this
+ * parameter is required only on linux platforms, it can be left nullptr in
+ * other platforms).
+ *
+ * @par Inner types
+ *
+ * The class must have the following inner types:
+ * - `CallbackReadBuffer`: A type that represents the signature of the callback
+ * function that will be called when the depth value is read from the depth
+ * buffer of the Canvas. See the `onReadDepth` member function for more details.
+ *
+ * @par Member functions
+ *
+ * The class must have the following member functions:
+ * - `size() -> Point2Concept`: Returns the size of the canvas, as a Point2i
+ * object having the width as x() and height as y().
+ * - `viewId() -> uint`: Returns an unsigned integer that represents the view
+ * id of the canvas. The view id is used to identify the canvas when drawing
+ * content on it, and it is passed to the Drawer objects at each draw call.
+ * - `onInit() -> void`: Called when the canvas is initialized. This function
+ * is called by the Renderer class when the WindowManager of the vcl::Renderer
+ * is initialized. This function should contain all the initialization calls
+ * that cannot be done in the constructor (e.g. because the WindowManager
+ * could not guarantee the initialization of the backend context in the
+ * constructor).
+ * - `onResize(uint width, uint height) -> void`: Called when the canvas is
+ * resized. This function is called by the Renderer class when the WindowManager
+ * of the vcl::Renderer is resized. The function should resize the canvas to
+ * the new size.
+ * - `onPaint() -> void`: Called when the canvas must be repainted. This
+ * function is called by the Renderer class when the WindowManager of the
+ * vcl::Renderer is repainted. The function should draw the content of the
+ * canvas, by calling the vcl::Renderer::CNV::draw() member function of the
+ * Renderer class.
+ * - `onReadDepth(const vcl::Point2i& point, CallbackReadBuffer callback) ->
+ * bool`: Called when a Drawer object asks to read the depth value at the
+ * specified point on the canvas. The function should read the depth value at
+ * the specified point and call the callback function with the depth value.
+ * - `onScreenshot(const std::string& filename, uint width = 0, uint height = 0)
+ * -> bool`: Called when a Drawer object asks for a screenshot of the canvas.
+ * The function should take a screenshot of the canvas and save it to the
+ * specified filename. If the width and height are specified, the screenshot
+ * should be resized to the specified dimensions.
+ */
 template<typename T>
 concept CanvasConcept = requires (
     T&&                                       obj,
@@ -36,6 +103,7 @@ concept CanvasConcept = requires (
     vcl::Point2i                              p,
     typename RemoveRef<T>::CallbackReadBuffer cbrb,
     std::string                               str) {
+
     typename RemoveRef<T>::CallbackReadBuffer;
 
     T(vPtr, u, u);

vclib/render/include/vclib/render/concepts/window_manager.h

@@ -28,7 +28,61 @@
 #include <concepts>
 
 namespace vcl {
-
+/**
+ * @brief The WindowManagerConcept concept is used to check if a class satisfies
+ * the requirements of the WindowManager concept.
+ *
+ * Each class that satisfies this concept can be used as a window manager in the
+ * @ref vcl::Renderer class (first template parameter). The WindowManager class
+ * is responsible for managing the window and the window events.
+ *
+ * It is a class that is templated on the Renderer class (using the CRTP
+ * pattern). The class is then allowed to access the member functions of the
+ * public members of the @ref vcl::Renderer class and all the members of the
+ * @ref vcl::Renderer::WM inner class.
+ *
+ * Moreoever, to work correctly with the Renderer class, the Canvas class and
+ * the Drawer classes, **the WindowManager class should call for each event**
+ * (e.g. init, resize, mouseMove, ...) **the corresponding member function of
+ * the vcl::Renderer::WM inner class**. This is necessary to propagate the event
+ * to the Canvas and to the Drawer objects. This requirement is not modeled in
+ * this concept definition because any platform can have different event
+ * handling.
+ *
+ * @par Constructors
+ *
+ * The class must have the following constructors:
+ * - `WindowManagerType(ParentType* parent = nullptr)`: Default constructor that
+ * initializes the window manager with a parent object (if available).
+ * - `WindowManagerType(const std::string& windowTitle, uint width, uint height,
+ * ParentType* parent = nullptr)`: Constructor that initializes the window
+ * manager with the window title, the initial width and height of the window,
+ * and a parent object (if available).
+ *
+ * @par Inner types
+ *
+ * The class must have the following inner types:
+ * - `ParentType`: The type of the parent object of the window manager. This
+ * object is used to propagate events from the window manager to the parent
+ * object, if available. The parent object is necessary only on some platforms
+ * (e.g. Qt). If the parent object is not available, the type should be set to
+ * `void`.
+ *
+ * @par Member functions
+ *
+ * The class must have the following member functions:
+ * - `windowTitle() -> const std::string&`: Returns the title of the window.
+ * - `setWindowTitle(const std::string&) -> void`: Sets the title of the window.
+ * - `width() -> uint`: Returns the width of the window.
+ * - `height() -> uint`: Returns the height of the window.
+ * - `dpiScale() -> Point2Concept`: Returns the DPI scale of the window.
+ * - `winId() -> void*`: Returns the platform dependent identifier of the
+ * window.
+ * - `displayId() -> void*`: Returns the platform dependent identifier of the
+ * display where the window is placed. This parameter is required only on linux
+ * platforms, it can be left nullptr in other platforms.
+ * - `update() -> void`: Updates the window.
+ */
 template<typename T>
 concept WindowManagerConcept =
     requires (

vclib/render/include/vclib/render/renderer.h

@@ -337,10 +337,16 @@ class Renderer :
 
 /**
  * @brief The Renderer::WM inner class is an Attorney that allow access to some
- * private member functions of the Renderer class to the WindowManager
+ * private member functions of the Renderer class to the WindowManagerType
  * class.
- * They can be called only by the WindowManager class in the following way:
+ *
+ * The member functions of the Renderer::WM inner class can be called only by
+ * the WindowManagerType class. For example, to call the init member function,
+ * the WindowManagerType can call it in the following way:
+ *
+ * @code{.cpp}
  * Renderer::WM::init(static_cast<Renderer*>(this));
+ * @endcode
  */
 template<
     template<typename> typename WindowManagerT,
@@ -520,8 +526,14 @@ class Renderer<WindowManagerT, CanvasT, Drawers...>::WM
 /**
  * @brief The Renderer::CNV inner class is an Attorney that allow access to some
  * private member functions of the Renderer class to the CanvasType class.
- * They can be called only by the CanvasType class in the following way:
+ *
+ * The member functions of the Renderer::CNV inner class can be called only by
+ * the CanvasType class. For example, to call the update member function,
+ * the CanvasType can call it in the following way:
+ *
+ * @code{.cpp}
  * Renderer::CNV::update(static_cast<Renderer*>(this));
+ * @endcode
  */
 template<
     template<typename> typename WindowManagerT,
@@ -553,17 +565,21 @@ class Renderer<WindowManagerT, CanvasT, Drawers...>::CNV
  * @brief The Renderer::DRW inner class is an Attorney that allow access to some
  * private member functions of the Renderer class to the Drawer
  * classes.
- * They can be called only by the Drawer classes in the following way:
- * Renderer::D::canvasSize(static_cast<Renderer*>(this));
+ *
+ * The member functions of the Renderer::DRW inner class can be called only by
+ * the Drawer classes. For example, to call the canvasFrameBuffer member
+ * function, the Drawer can call it in the following way:
+ *
+ * @code{.cpp}
+ * Renderer::DRW::canvasFrameBuffer(static_cast<Renderer*>(this));
+ * @endcode
  */
 template<
     template<typename> typename WindowManagerT,
     template<typename> typename CanvasT,
     template<typename> typename... Drawers>
 class Renderer<WindowManagerT, CanvasT, Drawers...>::DRW
 {
-    /// @cond VCLIB_SHOW_DOCS
-
     // TODO: right now all the function in this inner class are public,
     // because variadic friends are still not allowed in C++.
     // It will allowed in C++26: https://stackoverflow.com/a/78246001/5851101
@@ -619,8 +635,6 @@ class Renderer<WindowManagerT, CanvasT, Drawers...>::DRW
     {
         return r->dReadDepth(point, callback);
     }
-
-    /// @endcond
 };
 
 } // namespace vcl