Initial implementation of ReplacementVisitor

[AnyOldName3]

Pull Request Template

Description

As discussed on a call last year, and alluded to in some PR/issue/discussion comments since, a vsg::Visitor can't replace objects in the scenegraph it operates on except by handling it at the level of their parent. If you know the structure of the data being operated on and either the object only makes sense in the context of its parent (e.g. swapping the vertex buffer of a VertexIndexDraw) or can limit the number of parent types to a feasible number (e.g. you know the node you want to swap out will always have a StateGroup as its parent), that's fine, but that's not always the case with real-world data.

An example use-case is the IntersectionOptimizeVisitor on my intersection optimisation branch that swaps out nodes for an optimised class which handles intersections faster (and passes other kinds of traversal onto the original node). At the moment, it explicitly handles StateGroup because that's the parent of the target nodes in the sample data I've got, but to work in the general case, it would need to explicitly handle every VSG node type that can have one or more children. With this PR applied, it can just handle the specific node types it targets and avoid needing to handle every possible parent. It would also make it easier to move the generated intersection proxy nodes higher in the scenegraph when only one node in a subgraph is intersectable.

I've implemented a slightly contrived but more obvious and straightforward example for the vsgExamples repo that illustrates how the new visitor type can be used and points out a gotcha I expect users of the class might run into. The PR for that is here: vsg-dev/vsgExamples#392

Type of change

Please delete options that are not relevant.

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

So far, basically just the new vsgExample I made to demo the feature. I've not yet adapted the intersection optimisation branch to use it, as I thought it was a good idea to get more eyes on the implementation before marrying anything to it.

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published in downstream modules

[robertosfield]

I have done a first pass review of the changes. My gut reaction is that it's a lot of code changes for something very specific and that there is likely a simpler, easier to understand and use approach lurking out on the either.

[AnyOldName3]

The obvious alternatives are to make any visitor that wants to replace nodes with other nodes replicate all this code in its implementation (which means more code total as soon as there's more than one), or to do something complicated like the some of the osg::Optimizer optimisations do with multiple visitors and multiple traversals both root-to-leaves and leaves-to-root and heavy use of getParents() (which isn't even possible with the VSG). Even with the extra features the OSG had that haven't made it to the VSG, lots of those solutions aren't as simple or elegant as they could be if built with a base visitor like this. I also think it demonstrates quite a few things that it's reasonable to do with a scene graph, and that therefore should ideally be easy to write an implementation of.

For example, with this PR, something like RemoveRedundantNodesVisitor could be implemented without being a two-pass process, without needing to keep track of all the redundant nodes it had found so far, without having to access the parents of any nodes it was replacing, and without requiring that all parents were osg::Group subclasses. If the traversal found a node it felt was redundant, it would return a ref_ptr to its child, and otherwise it'd return std::nullopt, and that's all it would need to do.

Fundamentally, the approach kind of has to look something like this. There needs to be something resembling the Visitor Pattern to allow operations to happen based on the object type (which is a well established good fit, hence the existing visitor classes existing both in the OSG and VSG), and the sensible place for the code describing how to swap out a child object for another is obviously the class that has the child objects. You could get the same kind of thing if a subclass of the existing vsg::Visitor had a mechanism like the OSG's pushOntoNodePath so we had a way to access an object's parent, and then vsg::Object could be given a virtual replaceChild, but that falls apart when a parent object has multiple collections of children, e.g. a vsg::Switch that had the same node under multiple masks (or something like that but that couldn't be resolved just by combining the masks) wouldn't know if it was supposed to replace that child under both masks or just one.