GSoC 2023: Final Checkpoint

[jbinvnt]

Google Summer of Code 2023 Final Report

My original GSoC project proposal may be viewed here.

Mentors	Special Thanks
Torsten Paul @t-paul	Marius Kintel @kintel

Initial Notes About this Pull Request

This PR will contain my final report on work that I did during Google Summer of Code 2023. Although it is expected that code from this branch will be revised and merged at a later date, this particular pull request should not be edited after this year's GSoC ends. Closing this PR and instead doing the future work on a new branch will preserve the record of what was done for GSoC.

Commits from Last Year

Several of the commits on this branch match those from my GSoC 2022 PR #4330. That is because this branch rebases the shader features I created last year onto the current version of master (including my GSoC 2023 work).

About the Project

This project restructures portions of OpenSCAD's rendering code to help the transition to modern OpenGL capabilities. My initial work focused on consolidating duplicate instructions into a single class that can be used across different types of renderers. Readability improvements were also implemented in a few places. My final topic of work involved allowing an initial build to be made with OpenGL Core 3.2, the first GL version that fully removes deprecated immediate/fixed-function/legacy API calls. The process of building modern replacements for all those features is an ongoing effort. Fortunately, I did some of that work already: my GSoC project last year was to enable GLSL shaders for the F6 render view. The final commits here involve updating the GSoC 2022 code to be compatible with the latest changes I made this year.

Pull Request Structure

I presented my work this summer in a modular fashion with incrementally merged PRs. Also note that all branches are prefixed gsoc-2023-.

This Year

From newest to oldest

• Final Checkpoint (you are here) GSoC 2023: Final Checkpoint #4752
• Macro to allow building with OpenGL Core GSoC 2023: Macro to allow building with OpenGL Core #4738
• Rename vertices_size to num_vertices Gsoc 2023: Rename vertices_size to num_vertices where appropriate #4705
• Create VertexStateManager GSoC 2023: Create VertexStateManager #4675

Last year

• GSoC 2022 GSoC 2022: 3D Viewport Graphical Enhancements  #4330

Topline Summary of Enhancements

• An optional macro allows disabling features that would prevent OpenSCAD being built with OpenGL Core 3.2+ profiles
  • It is disabled by default because rendering won't work until modern OpenGL replacements are implemented for all legacy GL calls
• Common steps for management of vertex states are now contained in a single class
  • Allows the code to be reused across functions instead of duplicated

Detailed Description of Changes

To reiterate, the diff of this particular PR actually reflects mainly my work from GSoC 2022. To see the changes introduced from 2023, look at the individual pull requests linked above.

Building with a Core Profile

With normal build settings, OpenSCAD builds using an OpenGL Core profile will currently fail due to the use of legacy calls. The option that I created to fix this can be activated by adding the flag -DDISABLE_FIXEDFUNCTION_GL="ON" to CMake.

For my testing, I used GLAD to switch from a compatibility profile to core. GLAD support was added in #4549 and can be activated with -DUSE_GLAD="ON". And to get the CLI that generates the header files, I installed the Python module using pip3 install git+https://github.com/Dav1dde/glad.git.

Generally the GLAD command structure to use is kept in the README. However, that may not match exactly what was used to produce a certain development configuration. So the most accurate reference may be in the auto-generated comments at the beginning of the header files themselves.

Using the Vertex State Manager

A VertexStateManager wraps common operations for initialization and activation of vertex arrays. Previously, slight variations of these operations were duplicated across functions in classes like CGALRenderer and OpenCSGRenderer. Now, when a modernization is implemented for one function, it can take effect across all renderers at once.

Objects of type VertexStateManager are intended to be scoped within a larger rendering function. Initialization takes references to both the current renderer and the vertex array to be managed.

void CGALRenderer::createPolySets()
{
  PRINTD("createPolySets() polyset");

  polyset_states.clear();

  VertexArray vertex_array(std::make_shared<VertexStateFactory>(), polyset_states);

  VertexStateManager vsm(*this, vertex_array);
  
  //...

Source

For example, instead of replicating the decision logic for setting the vertex array's size, vsm.initializeSize can be called with the number of vertices. Other functions can also be added later to VertexStateManager as reusable parts of modern OpenGL rendering processes are discovered.

Testing

Running a core profile build as described above requires a few extra steps to run without crashing. First, enabling all experimental vertex-... features in the settings menu is required. Secondly, because F5 mode still relies on OpenCSG, previews are likely to cause a segfault until the necessary future work is done. F6 renders do not cause an error, but nothing is shown because of the viewport's reliance on legacy calls.

This PR doesn't introduce any CI test failures beyond those that might be present in the current master branch that it is based on.

Challenges Encountered

Legacy OpenGL has deep roots in the OpenSCAD codebase. Full modernization will require a long-term effort. Moreover, the interdependence of many features means that even after some functions are updated to use shaders, the results can't fully work in a Core Profile build until many other portions are brought up-to-date as well.

Work to modernize the fundamental rendering is also happening in parallel with other changes to extension loading and dependencies. These different aspects will require ongoing coordination to proceed in harmony, but fortunately I think that aspect has been going well so far.

Last GSoC Commit

I plan to contribute to this feature as a volunteer after GSoC ends. The last commit I made for GSoC will likely have its hash change after a pre-merge rebase. The most reliable way to find it is going to be looking at the top commit of #4738.

Future Work

Future work will be a step-by-step process of creating shader-based replacements for functionality that is now disabled by the macro. Also, so that current builds of master can be functional, the GLAD header files are left on a compatibility profile. When everything is ready to switch to a version of OpenGL Core in the future, they can be regenerated.

[t-paul]

Note: The openscad-mxe-64bit CI failure is related to the gcc-13 upgrade and not related to the code changes in the PR.