Gsoc2024 basic viewer glfw tgrillon

[tgrillon]

Summary of Changes

GLFW Basic viewer

Features

The main addition of this pull request is a new basic viewer based on GLFW. Its purpose is to provide the same features as the Qt viewer while using a lighter API.

Here is a summary of the main features that both viewers offer:

Camera features

• Two type of camera: Orbiter & Free-fly (FPS).
• Two camera mode: Perspective view (3D) & Orthographic view (2D).
• FOV modification (40-90).
• Translate/rotate the visualized structure.
• Rotation/translation speed modification.
• Zoom in/out.
• Align camera to world axis.
• Align camera to clipping plane.
• Recenter the scene.
• Reset position/orientation.
• Rotation constraint axis (up, right and forward axis).

Clipping plane features

• Four modes:
  • CLIPPING_PLANE_OFF: Disables the clipping plane.
  • CLIPPING_PLANE_SOLID_HALF_TRANSPARENT_HALF: Renders half of the clipped object as solid and half as transparent.
  • CLIPPING_PLANE_SOLID_HALF_WIRE_HALF: Renders half of the clipped object as solid and half with wireframe.
  • CLIPPING_PLANE_SOLID_HALF_ONLY: Only renders the positive side of the clipped object.
• Align clipping plane to camera.
• Rotate/Translate clipping plane.
• Translate clipping plane along its normal.
• Translate clipping plane along camera forward direction.
• Rotation constraint axis (up and right axis).
• Show/Hide clipping plane rendering.

Scene features

• Show/Hide edges/vertices/faces/lines/rays/mesh triangles.
• Single color mode:
  • Draw primitives using their default color defined in the graphics scene.
• Multiple color mode:
  • Draw primitives using their defined color.
• Draw edge as cylinder.
• Draw vertex as sphere.
• Draw vertex or face normal.
• Inverse normal.
• Use mono or direction based color for normal.
• Show/Hide XY grid.
• Show/Hide world axis.
• Take a screenshot.

Feature only in GLFW viewer

• make_screenshot(...): Takes a screenshot of the scene without displaying the window. Setters are available to tweak scene parameters (check <week 5: 15 July - 21 July> on the wiki page). An example of this feature is provided here.

Check out the wiki page where some of these features are presented.

Documentation

A file that provide documentation for public methods of the basic viewer class has been added in Basic_viewer/doc/Basic_viewer/CGAL/GLFW.

Project structure

All GLFW viewer components are located in Basic_viewer/include/CGAL/GLFW, with the following folders/files:

• internal: Headers where classes used by the viewer are declared and implemented, such as Camera, ClippingPlane, Input, etc.
• vendor: Contains the dependencies described in the next section.
• Basic_viewer_impl.h: Contains the implementations of the basic viewer methods (this file is included in Basic_viewer.h).
• Basic_viewer.h: Basic viewer class declaration.
• bv_settings.h: Settings file containing tweakable viewer parameters such as window height and width, window samples, size of vertices/edges, etc.

Dependencies and build system

Here are the libraries used for this viewer:

• GLFW : An open-source, cross-platform OpenGL API used to create windows, contexts, and manage inputs (library location).
• GLAD: OpenGL functions loader (one source and one header file).
• STBImage: use to save the rendered window as an image for the screenshot feature (only one header file).

The two viewers requires CGAL_Qt6 or CGAL_GLFW depending on which basic viewer the user wants to use. If both components are used, the Qt viewer will be the default. The viewers are only available if the macros CGAL_USE_BASIC_VIEWER/CGAL_USE_BASIC_VIEWER_QT (Qt viewer) or CGAL_USE_BASIC_VIEWER_GLFW (GLFW viewer) are defined.

The file CGAL_SetupCGAL_GLFWDependencies.cmake was added to manage GLFW/GLAD compilation and library linkage.

In CGALConfig.cmake, two new targets are generated:

• CGAL::CGAL_Basic_viewer_Qt: target to which the Qt library will be linked.
• CGAL::CGAL_Basic_viewer_GLFW: target to which the GLFW/GLAD libraries will be linked.

Note: Previously, only one target was defined for the Qt viewer: CGAL::CGAL_Basic_viewer. This target has not been removed yet. For the Qt viewer, both of CGAL::CGAL_Basic_viewer_Qt and CGAL::CGAL_Basic_viewer work.

• Linking with the cmake target CGAL::CGAL_Basic_viewer/CGAL::CGAL_Basic_viewer_Qt will link with CGAL_Qt6 and add the definition CGAL_USE_BASIC_VIEWER/CGAL_USE_BASIC_VIEWER_QT.
• Linking with the cmake target CGAL::CGAL_Basic_viewer_GLFW will link with CGAL_GLFW and add the definition CGAL_USE_BASIC_VIEWER_GLFW.

Qt viewer fixes

Some fixes and improvements have been made to the Qt viewer:

• Fixing line width modification (using a geometry shader instead of deprecated glLineWidth method).
• Improved mono color display performance (use uniform instead of vertex attribute).

TODO

• [ ] Check cmake configuration (for @lrineau)
• [ ] Remove CGAL::CGAL_Basic_viewer target and CGAL_USE_BASIC_VIEWER (?) (for @lrineau)

[afabri]

We have to remove the files of GLFW/vendor This should be a third party software that we just link with. Or do I miss something?

[gdamiand]

We have to remove the files of GLFW/vendor This should be a third party software that we just link with. Or do I miss something?

The idea is maybe to ship these files in cgal to simplify user life avoiding installing many external libraries; this is maybe possible because the files are small.

Of course, this will be discussed and validated with Laurent, Sébastien, ...