Scene Graph Iterators

group SI

API that allows to iterate through the locations and attributes on a Scenegraph.

This API allows to iterate through the locations on a scenegraph and query their attributes. This is an auxiliary API that can be used when implementing, for example, a connection of Katana to a Renderer. In this specific case the renderer will have at some point to discover which locations and attributes exist on the Katana scene being rendered.

Given the lazy initialization nature of Katana the scenegraph locations and attributes will be procedurally generated under the hood as the iterators go through the scene. Whenever a FnScenegraphIterator is instantiated Katana will generate its corresponding location if needed on that moment.

class FnScenegraphIterator

#include <FnScenegraphIterator.h>

The Scenegraph Iterator that ‘points’ at a location in a scenegraph.

Each instance of this class will be conceptually pointing at a specific location of the scenegraph. It presents methods that return other iterators that point at child, sibling, parent and other arbitraty locations on the scenegraph. The location pointed by the instance is referred here as “current

location”.

Public Functions

FnScenegraphIterator(FnSgIteratorHandle handle)

FnScenegraphIterator()

~FnScenegraphIterator()

FnScenegraphIterator(const FnScenegraphIterator &rhs)

FnScenegraphIterator &operator=(const FnScenegraphIterator &rhs)

inline bool isValid() const: Returns true if this Scenegraph Iterator is valid.

std::string getName() const: Returns the name of the current Location. (ex: “pony” in “/root/world/geo/pony”)

std::string getFullName() const: Returns the full path name of the current Location. (ex: “/root/world/geo/pony”)

std::string getType() const: Returns the type of the current Location. (ex: “subdmesh” or “group”)

FnScenegraphIterator getFirstChild(bool evict = false) const: Returns an iterator that poins at the first child of the current location.

FnScenegraphIterator getNextSibling(bool evict = false) const: Returns an iterator that poins at the next sibling of the current location.

FnScenegraphIterator getParent() const: Returns an iterator that poins at the parent of the current location.

FnScenegraphIterator getRoot() const: Returns an iterator that poins at the root location of the scenegraph where the current locations lives.

FnAttribute::StringAttribute getPotentialChildren() const

Returns:: a list of immediate potential child names

FnScenegraphIterator getChildByName(const std::string &name, bool evict = false) const

Returns an iterator to a child of the current location.

Returns an iterator that points at a child location with the given name underneath the current location.

Parameters:

name – The name of the child location for which to return a scene graph iterator.
evict – Flag that controls whether the Geolib3 Runtime will flush cached scene data, while protecting data that is deemed potentially relevant to the child scene graph location with the given name, for example that of ancestor locations.

FnScenegraphIterator getByPath(const std::string &path, bool evict = false) const

Returns an iterator pointing at a location with a given path.

Returns an iterator that points to a location in the scene graph that is identified by the given forward slash-separated scene graph location path.

Parameters:

path – The forward slash-separated path of the scene graph location for which to return a scene graph iterator.
evict – Flag that controls whether the Geolib3 Runtime will flush cached scene data, while protecting data that is deemed potentially relevant to the scene graph location with the given path, for example that of ancestor locations.

FnAttribute::Attribute getAttribute(const std::string &name, bool global = false) const

Get a specific attribute from the location pointed by the iterator.

Returns an existing Attribute from the current Location if no location is specified. If there isn’t any Attribute with the given name on the given Location then an invalid FnAttribute is returned (which can be checked with the function FnAttribute::isValid()).

Parameters:

name – The name of the attribute - can be a child of a GroupAttribute (ex: “geometry.point.P”)
global – If false then the global attributes (inherited from parent Locations) will be ignored. In this case if the requested Attribute is global, then an invalid attribute is returned.

FnAttribute::StringAttribute getAttributeNames() const

Return the names of all the attributes on the location pointed by the iterator.

Returns:: A valid StringAttribute

FnAttribute::GroupAttribute getGlobalXFormGroup() const

Returns:: a GroupAttribute that represents the global transform for this location.

void finalizeRuntime() const

Notifies the Geolib Runtime that the renderer plug-in will not interact with it again, and therefore resources can be deallocated (e.g. cached scene data, internal threads, etc.).

To be used (just) after the scene has been entirely traversed, and typically before the renderer starts rendering.

This function can take time. It may be desirable to invoke this function from a worker thread to avoid blocking the actual rendering.

Note

All iterators associated with the same runtime instance will be invalidated, as no more interaction is expected from them.

FnGeolibOpId getClientOpId() const