Cortex  10.0.0-a4
Classes | Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Types | Static Protected Member Functions | List of all members
IECore::SceneInterface Class Referenceabstract

#include <SceneInterface.h>

+ Inheritance diagram for IECore::SceneInterface:

Classes

struct  FileFormatDescription
 

Public Types

enum  MissingBehaviour { ThrowIfMissing = IndexedIO::ThrowIfMissing, NullIfMissing = IndexedIO::NullIfMissing, CreateIfMissing = IndexedIO::CreateIfMissing }
 
enum  TagFilter { DescendantTag = 1, LocalTag = 2, AncestorTag = 4, EveryTag = DescendantTag | LocalTag | AncestorTag }
 
enum  HashType {
  TransformHash, AttributesHash, BoundHash, ObjectHash,
  ChildNamesHash, HierarchyHash
}
 
typedef IndexedIO::EntryID Name
 
typedef IndexedIO::EntryIDList NameList
 
typedef IndexedIO::EntryIDList Path
 
- Public Types inherited from IECore::RunTimeTyped
typedef RefCounted BaseClass
 A typedef for the class this class derives from. All RunTimeTyped classes define this typedef.
 
- Public Types inherited from IECore::RefCounted
typedef size_t RefCount
 

Public Member Functions

 IE_CORE_DECLARERUNTIMETYPED (SceneInterface, RunTimeTyped)
 
virtual std::string fileName () const =0
 Returns the file that this scene is mapped to. Throws exception if there's no file.
 
virtual Name name () const =0
 Returns the name of the scene location which this instance is referring to. The root path returns "/".
 
virtual void path (Path &p) const =0
 Returns the path scene this instance is referring to.
 
virtual bool hasBound () const
 
virtual Imath::Box3d readBound (double time) const =0
 
virtual void writeBound (const Imath::Box3d &bound, double time)=0
 
virtual ConstDataPtr readTransform (double time) const =0
 
virtual Imath::M44d readTransformAsMatrix (double time) const =0
 
virtual void writeTransform (const Data *transform, double time)=0
 
virtual bool hasAttribute (const Name &name) const =0
 Convenience method to determine if an attribute exists without reading it.
 
virtual void attributeNames (NameList &attrs) const =0
 Fills attrs with the names of all attributes available in the current directory.
 
virtual ConstObjectPtr readAttribute (const Name &name, double time) const =0
 Returns the attribute value at the given time.
 
virtual void writeAttribute (const Name &name, const Object *attribute, double time)=0
 
virtual bool hasTag (const Name &name, int filter=LocalTag) const =0
 
virtual void readTags (NameList &tags, int filter=LocalTag) const =0
 
virtual void writeTags (const NameList &tags)=0
 Adds tags to the current scene location.
 
virtual bool hasObject () const =0
 Convenience method to determine if a piece of geometry exists without reading it.
 
virtual ConstObjectPtr readObject (double time) const =0
 Reads the object stored at this path in the scene at the given time.
 
virtual PrimitiveVariableMap readObjectPrimitiveVariables (const std::vector< InternedString > &primVarNames, double time) const =0
 
virtual void writeObject (const Object *object, double time)=0
 
virtual bool hasChild (const Name &name) const =0
 Convenience method to determine if a child exists.
 
virtual void childNames (NameList &childNames) const =0
 
virtual SceneInterfacePtr child (const Name &name, MissingBehaviour missingBehaviour=ThrowIfMissing)=0
 
virtual ConstSceneInterfacePtr child (const Name &name, MissingBehaviour missingBehaviour=ThrowIfMissing) const =0
 Returns a read-only interface for a child location in the scene.
 
virtual SceneInterfacePtr createChild (const Name &name)=0
 
virtual SceneInterfacePtr scene (const Path &path, MissingBehaviour missingBehaviour=ThrowIfMissing)=0
 Returns a interface for querying the scene at the given path (full path).
 
virtual ConstSceneInterfacePtr scene (const Path &path, MissingBehaviour missingBehaviour=ThrowIfMissing) const =0
 Returns a const interface for querying the scene at the given path (full path).
 
virtual void hash (HashType hashType, double time, MurmurHash &h) const
 
- Public Member Functions inherited from IECore::RunTimeTyped
 IE_CORE_DECLAREMEMBERPTR (RunTimeTyped)
 
virtual TypeId typeId () const
 
virtual const char * typeName () const
 
virtual bool isInstanceOf (TypeId typeId) const
 
virtual bool isInstanceOf (const char *typeName) const
 
- Public Member Functions inherited from IECore::RefCounted
 IE_CORE_DECLAREMEMBERPTR (RefCounted)
 
void addRef () const
 Add a reference to the current object.
 
void removeRef () const
 Remove a reference from the current object.
 
RefCount refCount () const
 Returns the current reference count.
 

Static Public Member Functions

static SceneInterfacePtr create (const std::string &path, IndexedIO::OpenMode mode)
 
static std::vector< std::string > supportedExtensions (IndexedIO::OpenMode modes=IndexedIO::Read|IndexedIO::Write|IndexedIO::Append)
 
static void pathToString (const Path &p, std::string &path)
 Converts a internal Path to a path-like string. The root path results in "/".
 
static void stringToPath (const std::string &path, Path &p)
 
- Static Public Member Functions inherited from IECore::RunTimeTyped
static TypeId staticTypeId ()
 Returns the TypeId for this class, without needing an instance.
 
static const char * staticTypeName ()
 Returns the type name for this class, without needing an instance.
 
static TypeId baseTypeId ()
 
static const char * baseTypeName ()
 
static bool inheritsFrom (TypeId typeId)
 Returns true if this class inherits from the specified type.
 
static bool inheritsFrom (const char *typeName)
 Returns true if this class inherits from the specified type.
 
static bool inheritsFrom (TypeId type, TypeId baseType)
 Returns true if type inherits from baseType.
 
static bool inheritsFrom (const char *typeName, const char *baseTypeName)
 Returns true if typeName inherits from baseTypeName.
 
static TypeId baseTypeId (TypeId typeId)
 Returns the base type of the given type, or InvalidTypeId if no such base exists.
 
static const std::vector< TypeId > & baseTypeIds (TypeId typeId)
 
static const std::set< TypeId > & derivedTypeIds (TypeId typeId)
 
static TypeId typeIdFromTypeName (const char *typeName)
 
static const char * typeNameFromTypeId (TypeId typeId)
 
static void registerType (TypeId derivedTypeId, const char *derivedTypeName, TypeId baseTypeId)
 Allows external modules to register their own type ids.
 

Static Public Attributes

static const NamerootName
 Constant name assigned to the root location "/".
 
static const Path & rootPath
 Utility variable that can be used anytime you want to refer to the root path in the Scene.
 
static const NamevisibilityName
 Name of the visibility attribute.
 

Protected Types

typedef SceneInterfacePtr(* CreatorFn) (const std::string &, IndexedIO::OpenMode)
 
- Protected Types inherited from IECore::RunTimeTyped
typedef std::map< TypeId, TypeIdBaseTypeRegistryMap
 
typedef std::map< TypeId, std::vector< TypeId > > BaseTypesRegistryMap
 
typedef std::map< TypeId, std::set< TypeId > > DerivedTypesRegistryMap
 
typedef tbb::spin_rw_mutex Mutex
 
typedef std::map< TypeId, std::string > TypeIdsToTypeNamesMap
 
typedef std::map< std::string, TypeIdTypeNamesToTypeIdsMap
 

Static Protected Member Functions

static CreatorMap & fileCreators ()
 
static void registerCreator (const std::string &extension, IndexedIO::OpenMode modes, CreatorFn f)
 
- Static Protected Member Functions inherited from IECore::RunTimeTyped
static BaseTypeRegistryMap & baseTypeRegistry ()
 
static DerivedTypesRegistryMap & derivedTypesRegistry ()
 
static BaseTypesRegistryMap & completeBaseTypesRegistry ()
 
static DerivedTypesRegistryMap & completeDerivedTypesRegistry ()
 
static void derivedTypeIdsWalk (TypeId typeId, std::set< TypeId > &)
 
static TypeIdsToTypeNamesMap & typeIdsToTypeNames ()
 
static TypeNamesToTypeIdsMap & typeNamesToTypeIds ()
 

Additional Inherited Members

- Static Protected Attributes inherited from IECore::RunTimeTyped
static Mutex g_baseTypeIdsMutex
 
static Mutex g_derivedTypeIdsMutex
 

Detailed Description

A pure virtual base class for navigating a hierarchical animated 3D scene. A scene is defined by a hierarchy of named 3D transforms. Each SceneInterface instance maps to a specific transform in a scene, uniquely identified by it's path. A path is an array of transform names. Using the method child, you can explore the hierarchy (and create new transforms). Each transform on the hierarchy has a unique name and contains the 3D transformation, custom attributes, tags, a bounding box, a main object and more child transforms. All of them can be animated. Animation is stored by providing the time and the value. And it's retrieved by querying it's value at any time, and if the animation is inherently sampled, interpolation will be applied for queries on attributes, objects, transforms and bounds. The path to the root transform is an empty array. The name of the root transform is "/" though. The root transform by definition cannot store transformation or an object. Attributes and Tags are allowed. Tags are string labels assigned to any location in a scene and they are propagated up and down in the hierarchy when the scene is saved to files, so they can be used for efficiently filtering the hierarchy. Check on the Maya and Houdini scene reader nodes for examples on how to filter by tag.

Todo:
Implement a TransformStack class that can represent any custom transformation that could be interpolated and consider using it here as the returned type as opposed to DataPtr.

Member Function Documentation

virtual SceneInterfacePtr IECore::SceneInterface::child ( const Name name,
MissingBehaviour  missingBehaviour = ThrowIfMissing 
)
pure virtual

Returns an object for the specified child location in the scene. If the child does not exist then it will behave according to the missingBehavior parameter. May throw and exception, may return a NULL pointer, or may create the child (if that is possible). Bounding boxes will be automatically propagated up from the children to the parent as it is written.

Implemented in IECoreMaya::LiveScene, IECore::LinkedScene, IECore::SceneCache, and IECoreHoudini::LiveScene.

virtual void IECore::SceneInterface::childNames ( NameList &  childNames) const
pure virtual

Queries the names of any existing children of path() within the scene.

Implemented in IECore::LinkedScene, and IECore::SceneCache.

static SceneInterfacePtr IECore::SceneInterface::create ( const std::string &  path,
IndexedIO::OpenMode  mode 
)
static

Create an instance of a subclass which is able to open the file found at "path". Files can be opened for Read, Write, or Append depending on the derived classes. During "Read" operations it is not permitted to make any modifications to the underlying files. When opening a scene file in "Write" mode its contents below the root directory are removed. For "Append" operations (if supported) it is possible to write new files, or overwrite existing ones.

Parameters
pathA file on disk. The appropriate scene interface for reading/writing is determined by the path's extension.
modeA bitwise-ORed combination of constants which determine how the file system should be accessed.
virtual SceneInterfacePtr IECore::SceneInterface::createChild ( const Name name)
pure virtual

Returns a writable interface to a new child. Throws an exception if it already exists. Bounding boxes will be automatically propagated up from the children to the parent as it is written.

Implemented in IECoreMaya::LiveScene, IECore::LinkedScene, IECore::SceneCache, and IECoreHoudini::LiveScene.

Referenced by IECoreMaya.FnSceneShape::expandOnce().

virtual bool IECore::SceneInterface::hasBound ( ) const
virtual

Returns true if a bounding box is available for reading, false if not. Default implementation returns true.

virtual void IECore::SceneInterface::hash ( HashType  hashType,
double  time,
MurmurHash h 
) const
virtual

Computes the requested type of hash for the current location on the scene at the given time. The hash returned is not content-based, but it uniquely identifies the queried information so that it can be used for memory caches, for example, used by ComputationCache objects. This function is only available when reading scenes and it raises an exception otherwise. The base class implementation only adds the class typeId information to garantee that the hash won't collide with other Cortex objects and derived classes are responsible to call the base class implementation as well as add the time dependency as applicable.

Reimplemented in IECoreMaya::LiveScene, IECore::LinkedScene, IECore::SceneCache, and IECoreHoudini::LiveScene.

virtual bool IECore::SceneInterface::hasTag ( const Name name,
int  filter = LocalTag 
) const
pure virtual

Utility function that quickly checks for the existence of one tag relative to the current scene location and the given filter.

Parameters
filterWill filter the results based on a combination of flags DescendantTag, LocalTag and AncestorTag. Use LocalTag for tags stored in the current scene location (default). DescendantTags for tags stored in child locations and AncestorTags for tags stored in parent locations. Some implementations may not support all combinations of these flags and will ignore them.

Implemented in IECore::LinkedScene, IECoreMaya::LiveScene, IECore::SceneCache, and IECoreHoudini::LiveScene.

virtual Imath::Box3d IECore::SceneInterface::readBound ( double  time) const
pure virtual

Returns the bounding box for the entire scene contents from path() down, inclusive of the object at this path, but exclusive of the transform at this path.

Implemented in IECore::SampledSceneInterface, IECore::LinkedScene, IECoreMaya::LiveScene, and IECoreHoudini::LiveScene.

virtual PrimitiveVariableMap IECore::SceneInterface::readObjectPrimitiveVariables ( const std::vector< InternedString > &  primVarNames,
double  time 
) const
pure virtual

Reads primitive variables from the object of type Primitive stored at this path in the scene at the given time. Raises exception if it turns out not to be a Primitive object.

Implemented in IECore::LinkedScene, IECoreMaya::LiveScene, IECore::SceneCache, and IECoreHoudini::LiveScene.

virtual void IECore::SceneInterface::readTags ( NameList &  tags,
int  filter = LocalTag 
) const
pure virtual

Reads all the tags relative to the current scene location and the filter. Does not guarantee unique set of tags to be returned.

Parameters
filterWill filter the results based on a combination of flags DescendantTag, LocalTag and AncestorTag. Use LocalTag for tags stored in the current scene location (default). DescendantTags for tags stored in child locations and AncestorTags for tags stored in parent locations. Some implementations may not support all combinations of these flags and will ignore them.

Implemented in IECore::LinkedScene, and IECore::SceneCache.

virtual ConstDataPtr IECore::SceneInterface::readTransform ( double  time) const
pure virtual

Returns the interpolated transform object of this node at the specified point in time.

Implemented in IECore::LinkedScene, IECore::SampledSceneInterface, IECoreMaya::LiveScene, and IECoreHoudini::LiveScene.

virtual Imath::M44d IECore::SceneInterface::readTransformAsMatrix ( double  time) const
pure virtual

Returns the transform of this node at the specified point in time as a matrix.

Implemented in IECore::LinkedScene, IECore::SampledSceneInterface, IECoreMaya::LiveScene, and IECoreHoudini::LiveScene.

static void IECore::SceneInterface::stringToPath ( const std::string &  path,
Path &  p 
)
static

Returns the object path within the scene that this class is referring to. For instances created using the constructor this will be "/". Use the childNames() and child() methods to traverse to other parts of the scene.

static std::vector<std::string> IECore::SceneInterface::supportedExtensions ( IndexedIO::OpenMode  modes = IndexedIO::Read|IndexedIO::Write|IndexedIO::Append)
static

Returns all the file extensions for which a SceneInterface implementation is available for the given access mode(s). Extensions do not include the preceding dot character ('.').

virtual void IECore::SceneInterface::writeAttribute ( const Name name,
const Object attribute,
double  time 
)
pure virtual

Writers the attribute to this path within the scene Raises an exception if you try to write an attribute in the root path with a time different than 0.

Implemented in IECore::LinkedScene, IECoreMaya::LiveScene, IECore::SceneCache, and IECoreHoudini::LiveScene.

virtual void IECore::SceneInterface::writeBound ( const Imath::Box3d &  bound,
double  time 
)
pure virtual

Writes the bound for this path, overriding the default bound that would be written automatically. Note that it might be useful when writing objects which conceptually have a bound but don't derive from VisibleRenderable.

Implemented in IECore::LinkedScene, IECore::SceneCache, IECoreMaya::LiveScene, and IECoreHoudini::LiveScene.

virtual void IECore::SceneInterface::writeObject ( const Object object,
double  time 
)
pure virtual

Writes a geometry to this path in the scene. Raises an exception if you try to write an object in the root path.

Implemented in IECore::LinkedScene, IECoreMaya::LiveScene, IECore::SceneCache, and IECoreHoudini::LiveScene.

virtual void IECore::SceneInterface::writeTransform ( const Data transform,
double  time 
)
pure virtual

Writes the transform applied to this path within the scene. Raises an exception if you try to write transform in the root path Currently it only accepts M44dData or TransformationMatrixdData.

Implemented in IECore::LinkedScene, IECore::SceneCache, IECoreMaya::LiveScene, and IECoreHoudini::LiveScene.


The documentation for this class was generated from the following file: