Allow, and document, management of visibility and lifetime of rendered objects in OpenGLRenderer

[jsfrancal]

Description

Currently, there doesn't seem to be explicit functionality to toggle rendering of certain objects that have been added with a render_* call in the OpenGLRenderer. The visible parameter present on some of these render_* methods is currently not used at all (see e.g. the code for OpenGLRenderer.render_line_* ). The renderer documentation is too sparse to figure this out without looking at the code. The articulations between instances, shapes instances, the register / deregister and add_shape_instance / remove_shape_instance methods is not clear or documented; the lifetime of the objects created by these methods and the render_* methods is unclear and undocumented.

The OpenGL example provided shows render_* methods being called in the render method inside the draw loop, but it so happens that the render_* calls creates persistent shape instances or instancers (when examining the code), meaning that the render_* calls could be called once at initialization and never again appear in the render method, the corresponding objects would still be drawn (presumably through the begin_frame or end_frame methods). I have verified this myself.

If one wants to remove these persistant instances (e.g. a mesh) to achieve the desired render toggling effect, simple calls to remove_shape_instance have no effect, or trying to manually remove them from the OpenGLRenderer._instances result in a crash presumably because some linked objects (e.g. transforms) linked to the instance have survived the instance disappearance. I cannot figure out from the provided documentation what is a bug or a misuse of the public methods here.

Context

I am trying to visualize the mesh extracted from a volumetric SDF or opacity field. I wish to turn off the mesh rendering to be able to render other visualizations, such as a textured slice of the SDF or opacity field. I have spent several hours trying to figure out how to turn off an object, something that would only require a simple if branch in a regular OpenGL rendering workflow. The only way I found, ultimately, was to use render_mesh("mesh_name", [], [], update_topology=True), namely overwriting the underlying VBO with an empty coordinate and face array. It would vastly help to better document the render functionality to avoid having to find circumvoluted solutions.