Cortex  10.0.0-a4
Classes | Public Member Functions | List of all members
IECore::Renderer Class Referenceabstract

#include <Renderer.h>

+ Inheritance diagram for IECore::Renderer:

Classes

class  ExternalProcedural
 
class  Procedural
 

Public Member Functions

 IE_CORE_DECLARERUNTIMETYPED (Renderer, RunTimeTyped)
 
virtual void camera (const std::string &name, const CompoundDataMap &parameters)=0
 
virtual void display (const std::string &name, const std::string &type, const std::string &data, const CompoundDataMap &parameters)=0
 
 IE_CORE_DECLAREPTR (Procedural)
 
 IE_CORE_DECLAREPTR (ExternalProcedural)
 
virtual void procedural (ProceduralPtr proc)=0
 Renders a piece of procedural geometry.
 
virtual DataPtr command (const std::string &name, const CompoundDataMap &parameters)=0
 
Options

Options are named items of data which control some global aspect of the render. These functions allow their setting and getting. All options must be set before a call to worldBegin() - it is invalid to change an option after worldBegin().

Standard SearchPath Options

  • "searchPath:font" StringData
    A colon separated list of paths to search for fonts on - these are used by the text() primitive. The default value should come from the IECORE_FONT_PATHS environment variable if set.
Rerendering Options

  • "editable" BoolData
    This option must be set to enable the use of the interactive rerendering methods defined below.
virtual void setOption (const std::string &name, ConstDataPtr value)=0
 Set an option. Must not be called after worldBegin().
 
virtual ConstDataPtr getOption (const std::string &name) const =0
 Get the value of a previously set option.
 
World block

Once all options, cameras and displays are specified, a world block is created in which the visible elements of the scene are described.

virtual void worldBegin ()=0
 
virtual void worldEnd ()=0
 Finishes the world block.
 
Transforms

The Renderer manages a hierarchical set of transforms, applying the current transform to all cameras and primitives that are created.

virtual void transformBegin ()=0
 
virtual void transformEnd ()=0
 Returns to the transform state saved by the last transformBegin() call.
 
virtual void setTransform (const Imath::M44f &m)=0
 Sets the current transform.
 
virtual void setTransform (const std::string &coordinateSystem)=0
 
virtual Imath::M44f getTransform () const =0
 Returns the current transform.
 
virtual Imath::M44f getTransform (const std::string &coordinateSystem) const =0
 Returns the transform associated with the named coordinate system.
 
virtual void concatTransform (const Imath::M44f &m)=0
 Concatenates the specified transform onto the current transform.
 
virtual void coordinateSystem (const std::string &name)=0
 
Attributes

Attributes are named items of data which control some per-object aspect of the render. Attributes may be set both before and after worldBegin(), and are scoped between attributeBegin(), attributeEnd() calls.

virtual void attributeBegin ()=0
 
virtual void attributeEnd ()=0
 Return to the attribute state saved by the last call to attributeBegin().
 
virtual void setAttribute (const std::string &name, ConstDataPtr value)=0
 
virtual ConstDataPtr getAttribute (const std::string &name) const =0
 Return the value of the named attribute.
 
virtual void shader (const std::string &type, const std::string &name, const CompoundDataMap &parameters)=0
 Specifies a shader to be applied to subsequent primitives.
 
virtual void light (const std::string &name, const std::string &handle, const CompoundDataMap &parameters)=0
 Specifies a light to apply to subsequent primitives.
 
virtual void illuminate (const std::string &lightHandle, bool on)=0
 Turns the specified light on or off for the current attribute state.
 
Motion blur
virtual void motionBegin (const std::set< float > &times)=0
 
virtual void motionEnd ()=0
 
Primitives

Primitives specify actual visible objects to be rendered. Each primitive has a topology which is usually specified in a manner unique to that type, and a set of PrimitiveVariables which is specified in the same manner for all primitives - these specify data to vary over the surface of the primitive.

Todo:
Better documentation for the calls below, particularly in relation to the rightHandedOrientation attribute.
virtual void points (size_t numPoints, const PrimitiveVariableMap &primVars)=0
 Renders a set of points.
 
virtual void disk (float radius, float z, float thetaMax, const PrimitiveVariableMap &primVars)=0
 
virtual void curves (const CubicBasisf &basis, bool periodic, ConstIntVectorDataPtr numVertices, const IECore::PrimitiveVariableMap &primVars)=0
 Renders a set of curves.
 
virtual void text (const std::string &font, const std::string &text, float kerning=1.0f, const PrimitiveVariableMap &primVars=PrimitiveVariableMap())=0
 Renders some text.
 
virtual void sphere (float radius, float zMin, float zMax, float thetaMax, const PrimitiveVariableMap &primVars)=0
 
virtual void image (const Imath::Box2i &dataWindow, const Imath::Box2i &displayWindow, const PrimitiveVariableMap &primVars)=0
 
virtual void mesh (ConstIntVectorDataPtr vertsPerFace, ConstIntVectorDataPtr vertIds, const std::string &interpolation, const PrimitiveVariableMap &primVars)=0
 
virtual void nurbs (int uOrder, ConstFloatVectorDataPtr uKnot, float uMin, float uMax, int vOrder, ConstFloatVectorDataPtr vKnot, float vMin, float vMax, const PrimitiveVariableMap &primVars)=0
 Renders a nurbs surface.
 
virtual void patchMesh (const CubicBasisf &uBasis, const CubicBasisf &vBasis, int nu, bool uPeriodic, int nv, bool vPeriodic, const PrimitiveVariableMap &primVars)=0
 Render a patch mesh.
 
virtual void geometry (const std::string &type, const CompoundDataMap &topology, const PrimitiveVariableMap &primVars)=0
 Generic call for specifying renderer specify geometry types.
 
Instancing

These methods provide a means of describing a portion of a scene once and reusing it many times.

virtual void instanceBegin (const std::string &name, const CompoundDataMap &parameters)=0
 Starts the description of a portion of a scene to be instanced.
 
virtual void instanceEnd ()=0
 Ends the description of an instance.
 
virtual void instance (const std::string &name)=0
 
Interactive rerendering

These methods provide a means of upating the scene following a call to worldEnd(), causing the renderer to interactively rerender the scene.

virtual void editBegin (const std::string &editType, const CompoundDataMap &parameters)=0
 
virtual void editEnd ()=0
 Ends the current scene edit.
 
- 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.
 

Additional Inherited Members

- 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
 
- 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.
 
- 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 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 ()
 
- Static Protected Attributes inherited from IECore::RunTimeTyped
static Mutex g_baseTypeIdsMutex
 
static Mutex g_derivedTypeIdsMutex
 

Detailed Description

The Renderer class provides a means of describing scenes for rendering. Its interface is modelled closely on OpenGL/Renderman with an attribute and transform stack etc. Renderer implementations should flag errors and warnings using the MessageHandler class rather than by throwing Exceptions - it's often more useful to have an incomplete image for diagnosis of the problem than to have an Exception thrown.

Naming conventions

Many of the calls in the Renderer interface associate a name with a piece of data. Both the setOption() and setAttribute() calls take a name to specify what is being modified and a DataPtr to specify the new value. Many other calls accept either a CompoundDataMap or a PrimitiveVariableMap, both of which may contain many named pieces of Data.

A naming convention exists to specify that particular data is intended only for a particular Renderer implementation. This allows rendering to be customised for a particular implementation without causing other implementations to error due to unsupported features. The convention for each name is as follows :

\li <b>"name"</b><br>

Should be supported by all Renderer implementations. For instance, the "doubleSided" attribute should be supported by all Renderers. A warning message should be output if the name is not recognised and supported.

Member Function Documentation

virtual void IECore::Renderer::attributeBegin ( )
pure virtual

Push a new attribute state onto the attribute stack. This is identical to the current state, but subsequent calls to setAttribute() will be discarded by the matching attributeEnd().

Implemented in IECoreGL::Renderer, IECoreRI::Renderer, and IECore::CapturingRenderer.

virtual void IECore::Renderer::camera ( const std::string &  name,
const CompoundDataMap parameters 
)
pure virtual

Creates a named camera at the position defined by the current transform. The camera looks down negative Z, with screen space left to right being positive X and screen space top to bottom being positive Y. The last camera specified before worldBegin() is considered to be the camera for rendering through - other cameras may be used in implementation specific ways by Renderer subclasses.

Standard Parameters

The following standard parameters should be supported by all implementations wherever possible - they are largely based on the RenderMan specification :
\li <b>"resolution" V2iData</b><br>
The resolution of any output images. Should default to 640x480 if not specified.
  • "pixelAspectRatio" FloatData
    The xSize/ySize aspect ratio for a pixel.
  • "screenWindow" Box2fData
    The region in screen space which is mapped to the output resolution. If unspecified then this should default to -1,1 in the smallest image dimension and the other dimension should be sized appropriately to preserve pixel aspect ratio.
  • "cropWindow" Box2fData
    The region in raster space which should actually be rendered - this allows just a section of the full resolution to be rendered. Note that raster space runs from 0,0 at the top left to 1,1 at the bottom right. Defaults to 0,0 1,1 if not specified.
  • "projection" StringData
    The projection that determines how camera coordinates are converted to screen space coordinates. Implementations should support "perspective" and "orthographic", with orthographic being the default if not specified.
  • "projection:fov" FloatData
    In the case of the "projection" parameter specifying a perspective projection, this specifies the field of view (in degrees) which is visible between -1 and 1 in screen space. Defaults to 90 degrees if unspecified.
  • "clippingPlanes" V2fData
    The near and far clipping planes. Defaults to 0.01, 100000 if unspecified.
  • "shutter" V2fData
    The time interval for which the shutter is open - this is used in conjunction with the times passed to motionBegin() to specify motion blur. Defaults to 0,0 if unspecified.

Implemented in IECoreRI::Renderer, IECoreGL::Renderer, and IECore::CapturingRenderer.

virtual DataPtr IECore::Renderer::command ( const std::string &  name,
const CompoundDataMap parameters 
)
pure virtual

Generic call for executing arbitrary renderer commands. This is intended to allow derived classes to support calls such as RiMakeTexture via calls of the form renderer->command( "ri:makeTexture", ... ).

Renderers supporting arbitrary clipping planes should implement a "clippingPlane" command which must be issued before worldBegin(), and which makes a clipping plane using the current transformation.

Todo:
Make a dedicated virtual clippingPlane() method for the next major version.

Implemented in IECoreGL::Renderer, IECoreRI::Renderer, and IECore::CapturingRenderer.

virtual void IECore::Renderer::coordinateSystem ( const std::string &  name)
pure virtual

Creates a named coordinate system from the current transform. Coordinate systems are scoped by attributeBegin/attributeEnd blocks.

Implemented in IECoreGL::Renderer, IECoreRI::Renderer, and IECore::CapturingRenderer.

virtual void IECore::Renderer::disk ( float  radius,
float  z,
float  thetaMax,
const PrimitiveVariableMap primVars 
)
pure virtual

Renders a disk of the specified radius on the xy plane, at the specified z value. If the "rightHandedOrientation" attribute is true then the normal faces down positive z, otherwise it faces down negative z.

Implemented in IECoreGL::Renderer, IECoreRI::Renderer, and IECore::CapturingRenderer.

virtual void IECore::Renderer::display ( const std::string &  name,
const std::string &  type,
const std::string &  data,
const CompoundDataMap parameters 
)
pure virtual

Specifies an image to be output from the renderer. In the case of file outputs name specified the filename. type specifies the type of output to create and data specifies the data to be output, for instance "rgba". parameters provides an implementation specific set of parameters to control other aspects of the image created. It is only valid to call this before worldBegin.

Implemented in IECoreRI::Renderer, IECoreGL::Renderer, and IECore::CapturingRenderer.

virtual void IECore::Renderer::editBegin ( const std::string &  editType,
const CompoundDataMap parameters 
)
pure virtual

Starts a new scene edit of the specified type. The standard functions above for declaring the scene can then be used to perform the edit.

Todo:
Better define the semantics of this function as we implement it for different renderers.

Implemented in IECoreGL::Renderer, IECoreRI::Renderer, and IECore::CapturingRenderer.

virtual void IECore::Renderer::image ( const Imath::Box2i &  dataWindow,
const Imath::Box2i &  displayWindow,
const PrimitiveVariableMap primVars 
)
pure virtual

Renders an image.

Todo:
Clarify the intended use of dataWindow and displayWindow.

Implemented in IECoreGL::Renderer, IECoreRI::Renderer, and IECore::CapturingRenderer.

virtual void IECore::Renderer::instance ( const std::string &  name)
pure virtual

Instantiates a previously described instance at the current transform position, and using the current attribute state.

Implemented in IECoreGL::Renderer, IECoreRI::Renderer, and IECore::CapturingRenderer.

virtual void IECore::Renderer::mesh ( ConstIntVectorDataPtr  vertsPerFace,
ConstIntVectorDataPtr  vertIds,
const std::string &  interpolation,
const PrimitiveVariableMap primVars 
)
pure virtual

Renders a mesh. The geometric normal of a face will be facing camera if the winding order of its vertices is anticlockwise from the point of view of the camera and the "rightHandedOrientation" attribute is true. If the "rightHandedOrientation" attribute is false then faces whose vertices wind /clockwise/ with respect to the camera are considered forward facing instead.

Implemented in IECore::CapturingRenderer.

virtual void IECore::Renderer::motionBegin ( const std::set< float > &  times)
pure virtual

Starts a new motion block. You should then make times.size() calls to one of the primitive or transform functions to specify the motion for the block.

Implemented in IECoreGL::Renderer, IECoreRI::Renderer, and IECore::CapturingRenderer.

virtual void IECore::Renderer::motionEnd ( )
pure virtual

Ends a motion block. Should be called when times.size() calls to an appropriate primitive or transform function have been made following a motionBegin() call.

Implemented in IECoreGL::Renderer, IECoreRI::Renderer, and IECore::CapturingRenderer.

virtual void IECore::Renderer::setAttribute ( const std::string &  name,
ConstDataPtr  value 
)
pure virtual

Sets the named attribute to the specified value.

Standard Attributes

The following standard attributes should be supported by all implementations wherever possible :
\li <b>"color"      Color3fData</b><br>
The color of primitives. Defaults to 1, 1, 1 if not specified.
\li <b>"opacity" Color3fData</b><br>
The opacity of primitives. Defaults to 1, 1, 1 if not specified.
  • "doubleSided" BoolData
    When true both sides of a primitive are rendered, when false only one side is. Defaults to true.
  • "rightHandedOrientation" BoolData
    Controls which side of a primitive is forward facing. This attribute starts with a value of true, because the camera is specified in a right handed coordinate system - a value of false specifies that the current orientation is left handed. The renderer will automatically toggle the value whenever a transformation flips the sense of the current object space coordinate system (this happens when a transform has a negative determinant - typically a negative scaling in some axis). You can change the interpretation of "forward facing" by flipping the attribute value at any time - see the documentation for the various primitives below for how orientation affects the way their front face is defined.
  • "name" StringData "unnamed"
  • A descriptive name for the object.
  • "user:*"
    Should be stored for later query, but have no other effect upon the rendering process.

Implemented in IECore::CapturingRenderer.

virtual void IECore::Renderer::setTransform ( const std::string &  coordinateSystem)
pure virtual

Sets the current transform to a coordinate system previously created with a call to coordinateSystem().

Implemented in IECoreGL::Renderer, IECoreRI::Renderer, and IECore::CapturingRenderer.

virtual void IECore::Renderer::sphere ( float  radius,
float  zMin,
float  zMax,
float  thetaMax,
const PrimitiveVariableMap primVars 
)
pure virtual

Renders a sphere of the specified radius. zMin and zMax are measured as a proportion of the radius - so no matter what the radius, the default values will always give a full sphere. If the "rightHandedOrientation" attribute is true then the normals point outwards, otherwise they point inwards.

Todo:
Give this the default values it talks about.

Implemented in IECoreGL::Renderer, IECoreRI::Renderer, and IECore::CapturingRenderer.

virtual void IECore::Renderer::transformBegin ( )
pure virtual

Push a new transform state identical to the current one. Modifications can then be made locally before calling transformEnd() to return to the previous transform state.

Implemented in IECoreGL::Renderer, IECoreRI::Renderer, and IECore::CapturingRenderer.

virtual void IECore::Renderer::worldBegin ( )
pure virtual

Starts the world block and resets the current transform to the identity.

Implemented in IECoreRI::Renderer, IECoreGL::Renderer, and IECore::CapturingRenderer.


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