IECore::Renderer Class Reference

#include <Renderer.h>

Inheritance diagram for IECore::Renderer:

List of all members.

Classes
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)
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.
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
	Creates a named coordinate system from the current transform.
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

---

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 :

• "name"
  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.

• "prefix:name"
  Used to specify data intended only for a particular implementation. Implementations silently ignore all data destined for other implementations. For instance, the "gl:primitive:wireframe" attribute is used by the GL renderer implementation but silently ignored by other implementations.

• "user:name"
  Used to specify data for the purposes of users. The renderer should store the value and make it available for query, but otherwise it should have no effect. This applies mostly to the attribute and option calls.

---

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 IECore::CapturingRenderer, IECoreRI::Renderer, and IECoreGL::Renderer.

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 :

• "resolution" V2iData
  The resolution of any output images. Should default to 640x480 if not specified.

• "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 IECore::CapturingRenderer, IECoreRI::Renderer, and IECoreGL::Renderer.

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", ... ).

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

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 IECore::CapturingRenderer, IECoreRI::Renderer, and IECoreGL::Renderer.

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 IECore::CapturingRenderer, IECoreRI::Renderer, and IECoreGL::Renderer.

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 IECore::CapturingRenderer, IECoreRI::Renderer, and IECoreGL::Renderer.

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 IECore::CapturingRenderer, IECoreRI::Renderer, and IECoreGL::Renderer.

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 IECore::CapturingRenderer, IECoreRI::Renderer, and IECoreGL::Renderer.

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 IECore::CapturingRenderer, IECoreRI::Renderer, and IECoreGL::Renderer.

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 :

• "color" Color3fData
  The color of primitives. Defaults to 1, 1, 1 if not specified.

• "opacity" Color3fData
  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 IECore::CapturingRenderer, IECoreRI::Renderer, and IECoreGL::Renderer.

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 IECore::CapturingRenderer, IECoreRI::Renderer, and IECoreGL::Renderer.

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 IECore::CapturingRenderer, IECoreRI::Renderer, and IECoreGL::Renderer.

virtual void IECore::Renderer::worldBegin

(

)

[pure virtual]

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

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

---

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

• include/IECore/Renderer.h