IECoreRI::Renderer Class Reference

#include <Renderer.h>

Inheritance diagram for IECoreRI::Renderer:

List of all members.

Public Member Functions
	Renderer ()
	Renderer (const std::string &name)
	IE_CORE_DECLARERUNTIMETYPEDEXTENSION (IECoreRI::Renderer, RendererTypeId, IECore::Renderer)
virtual void	setOption (const std::string &name, IECore::ConstDataPtr value)
virtual IECore::ConstDataPtr	getOption (const std::string &name) const
virtual void	camera (const std::string &name, const IECore::CompoundDataMap &parameters)
virtual void	display (const std::string &name, const std::string &type, const std::string &data, const IECore::CompoundDataMap &parameters)
virtual void	worldBegin ()
virtual void	worldEnd ()
	Finishes the world block.
virtual void	transformBegin ()
virtual void	transformEnd ()
	Returns to the transform state saved by the last transformBegin() call.
virtual void	setTransform (const Imath::M44f &m)
	Sets the current transform.
virtual void	setTransform (const std::string &coordinateSystem)
virtual Imath::M44f	getTransform () const
	Returns the current transform.
virtual Imath::M44f	getTransform (const std::string &coordinateSystem) const
	Returns the transform associated with the named coordinate system.
virtual void	concatTransform (const Imath::M44f &m)
	Concatenates the specified transform onto the current transform.
virtual void	coordinateSystem (const std::string &name)
	Creates a named coordinate system from the current transform.
virtual void	attributeBegin ()
virtual void	attributeEnd ()
	Return to the attribute state saved by the last call to attributeBegin().
virtual void	setAttribute (const std::string &name, IECore::ConstDataPtr value)
virtual IECore::ConstDataPtr	getAttribute (const std::string &name) const
virtual void	shader (const std::string &type, const std::string &name, const IECore::CompoundDataMap &parameters)
virtual void	light (const std::string &name, const std::string &handle, const IECore::CompoundDataMap &parameters)
	Specifies a light to apply to subsequent primitives.
virtual void	illuminate (const std::string &lightHandle, bool on)
	Turns the specified light on or off for the current attribute state.
virtual void	motionBegin (const std::set< float > &times)
virtual void	motionEnd ()
virtual void	points (size_t numPoints, const IECore::PrimitiveVariableMap &primVars)
	Renders a set of points.
virtual void	disk (float radius, float z, float thetaMax, const IECore::PrimitiveVariableMap &primVars)
virtual void	curves (const IECore::CubicBasisf &basis, bool periodic, IECore::ConstIntVectorDataPtr numVertices, const IECore::PrimitiveVariableMap &primVars)
virtual void	text (const std::string &font, const std::string &text, float kerning=1.0f, const IECore::PrimitiveVariableMap &primVars=IECore::PrimitiveVariableMap())
	Renders some text.
virtual void	sphere (float radius, float zMin, float zMax, float thetaMax, const IECore::PrimitiveVariableMap &primVars)
virtual void	image (const Imath::Box2i &dataWindow, const Imath::Box2i &displayWindow, const IECore::PrimitiveVariableMap &primVars)
virtual void	mesh (IECore::ConstIntVectorDataPtr vertsPerFace, IECore::ConstIntVectorDataPtr vertIds, const std::string &interpolation, const IECore::PrimitiveVariableMap &primVars)
virtual void	nurbs (int uOrder, IECore::ConstFloatVectorDataPtr uKnot, float uMin, float uMax, int vOrder, IECore::ConstFloatVectorDataPtr vKnot, float vMin, float vMax, const IECore::PrimitiveVariableMap &primVars)
virtual void	patchMesh (const IECore::CubicBasisf &uBasis, const IECore::CubicBasisf &vBasis, int nu, bool uPeriodic, int nv, bool vPeriodic, const IECore::PrimitiveVariableMap &primVars)
	Render a patch mesh.
virtual void	geometry (const std::string &type, const IECore::CompoundDataMap &topology, const IECore::PrimitiveVariableMap &primVars)
	Generic call for specifying renderer specify geometry types.
virtual void	procedural (IECore::Renderer::ProceduralPtr proc)
virtual void	instanceBegin (const std::string &name, const IECore::CompoundDataMap &parameters)
	Starts the description of a portion of a scene to be instanced.
virtual void	instanceEnd ()
	Ends the description of an instance.
virtual void	instance (const std::string &name)
virtual IECore::DataPtr	command (const std::string &name, const IECore::CompoundDataMap &parameters)

---

Detailed Description

An IECore::Renderer subclass which renders through the renderman interface.

Threading:

Scenes should be described to this class from a single thread. However, when rendering live (with a Renderer constructed with Renderer( "" )), procedurals may be expanded concurrently in multiple threads, and in this case each procedural will see a separate Renderer instance to provide thread safety.

---

Constructor & Destructor Documentation

IECoreRI::Renderer::Renderer

(

)

Creates a Renderer that will always render to the RiContext which is active at the time a given function is called.

Reimplemented from IECore::Renderer.

IECoreRI::Renderer::Renderer

(

const std::string &

name

)

Creates a Renderer that will create a new RiContext with a call to RiBegin( name.c_str() ) and will subsequently always render to that context. If the empty string is passed then RiBegin( 0 ) is called to actually render the scene rather than create a rib.

---

Member Function Documentation

virtual void IECoreRI::Renderer::attributeBegin

(

)

[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().

Implements IECore::Renderer.

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

Standard parameters supported :

• "resolution"
• "screenWindow"
• "cropWindow"
• "projection"
• "projection:fov"
• "clippingPlanes"
• "shutter"

Implementation specific parameters supported :

• "transform" M44fData()
  This overrides the transform specified via the transform*() calls below. It's provided to work around a bug that prevents RxTransform() from working when in RIB output mode.

  Deprecated:

  The "transform" parameter should no longer be used as the bug in 3delight which required it has now been fixed.

• "projection:*"
  All parameters matching this naming convention are passed to the RiProjection call.

• "ri:hider" StringData()
  

• "ri:hider:*"
  All parameters matching this naming convention are passed to an RiHider call.

• "ri:outputNow" BoolData false
  The renderman interface and the IECore::Renderer interface differ in their interpretation of transforms before worldBegin, and the IECore::Renderer spec says that the last camera specified is the one to render through whereas the renderman specification has only a single camera (ignoring all that nasty frame camera stuff). For these reasons it's necessary for the IECoreRI::Renderer to store the camera and output it in the worldBegin() call. This is no good if the Renderer instance is being used to specify just part of a scene (without a world block). This hacky parameter is therefore provided to cause the immediate output of the camera to support this situation.

Todo:

Support moving cameras, and named cameras using RiCamera.

Implements IECore::Renderer.

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

Supports the following commands :

"ri:readArchive" Expects a single StringData parameter called "name", and calls RiReadArchive with it.

Todo:

Make a VisibleRenderable subclass to encapsulate a call to this.

"objectBegin" "ri:objectBegin" Calls RiObjectBegin. Expects a single StringData parameter called "name", which can be used in a later call to command( "ri:objectInstance" ) to instance the object.

"objectEnd" "ri:objectEnd" Calls RiObjectEnd.

"objectInstance" "ri:objectInstance" Calls RiObjectInstance. Expects a single StringData parameter called "name", which refers to a name previously passed to command( "ri:objectBegin" ).

Deprecated:

Use the dedicated instancing methods instead of the objectInstance commands

"ri:archiveRecord" Makes a call to RiArchiveRecord(). Expects StringData parameters called "type" and "record".

"ri:illuminate" Calls RiIlluminate. Expects a StringData parameter called "handle" and a BoolData parameter called "state" with the light state. This is provided as a stopgap until the Renderer base class specifies an specific illuminate method.

Deprecated:

Use the illuminate method instead of the ri:illuminate command.

Implements IECore::Renderer.

virtual void IECoreRI::Renderer::disk	(	float	radius,
		float	z,
		float	thetaMax,
		const IECore::PrimitiveVariableMap &	primVars
	)		[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.

Implements IECore::Renderer.

virtual void IECoreRI::Renderer::display	(	const std::string &	name,
		const std::string &	type,
		const std::string &	data,
		const IECore::CompoundDataMap &	parameters
	)		[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.

Implements IECore::Renderer.

virtual IECore::ConstDataPtr IECoreRI::Renderer::getAttribute

(

const std::string &

name

)

const [virtual]

Currently supported attributes :

• "doubleSided"
• "rightHandedOrientation"
• "name"
• "user:*"
• "ri:shadingRate"
  
• "ri:matte"
  
• "ri:*:*"
  Supports all attributes for which the RxAttribute query works.

Implements IECore::Renderer.

virtual IECore::ConstDataPtr IECoreRI::Renderer::getOption

(

const std::string &

name

)

const [virtual]

Currently supported options :

"camera:resolution" V2iData "camera:shutter" "shutter" V2fData() "user:*" "ri:*" Queries of this form use the Rx API and therefore only work for options supported by that API.

Implements IECore::Renderer.

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

Renders an image.

Todo:

Clarify the intended use of dataWindow and displayWindow.

Implements IECore::Renderer.

virtual void IECoreRI::Renderer::instance

(

const std::string &

name

)

[virtual]

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

Implements IECore::Renderer.

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

Renders interpolation types of "linear" as RiPointsGeneralPolygons and "catmullClark" as RiSubdivisionMesh. Supports an optional "tags" primitive variable of type CompoundData and interpolation Constant, which is used to specify tags for the RiSubdivisionMesh call. This should contain the following children :

StringVectorData "names" IntVectorData "nArgs" FloatVectorData "floats" IntVectorData "integers"

Todo:

Consider how we might standardise a means of storing tags explicitly on the mesh rather than as primitive variables.

virtual void IECoreRI::Renderer::motionBegin

(

const std::set< float > &

times

)

[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.

Implements IECore::Renderer.

virtual void IECoreRI::Renderer::motionEnd

(

)

[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.

Implements IECore::Renderer.

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

Standard attributes supported :

• "color"
  Mapped to an RiColor call.

• "opacity"
  Mapped to an RiOpacity call.

• "doubleSided"
  Mapped to an RiSides call.

• "rightHandedOrientation"
  Implemented via RiOrientation.

• "name"
  Mapped to an RiAttribute "identifier" "name" call.

• "user:*"
  

Implementation specific attributes :

• "ri:*:*" Data
  Passed to an RiAttribute call.

• "ri:*" CompoundData
  Passed to an RiAttribute call. This allows multiple attribute values to be specified in one setAttribute() call.

• "ri:shadingRate" FloatData
  Passed to RiShadingRate.

• "ri:matte" BoolData
  Passed to RiMatte.

• "ri:color" Color3fData
  

  Deprecated:

  Use "color" in preference to "ri:color"

• "ri:opacity" Color3fData
  

  Deprecated:

  Use "opacity" in preference to "ri:opacity"

• "ri:sides" IntData
  Passed to RiSides

  Deprecated:

  Use "doubleSided" in preference to "ri:sides"

• "ri:geometricApproximation:motionFactor" and ri:geometricApproximation:focusFactor" FloatData
  Passed to RiGeometricApproximation.

• "ri:subsurface" CompoundData
  3delight gets upset if subsurface attributes aren't all specified as a group and in the right order. This is a problem as we can't specify order in the AttributeState or Group objects (see todo items there). We therefore support their specification as a single CompoundData, and ensure that they are specified in an appropriate order.

  Todo:

  Do the todo items in IECore::Group and IECore::AttributeState and deprecate the ri:subsurface call.

• "ri:detail" Box3fData
  Passed to RiDetail.

• "ri:detailRange" FloatVectorData
  Passed to RiDetailRange. The FloatVectorData must have length 4.

  Todo:

  Consider whether or not we should have a standard LOD mechanism defined in IECore.

virtual void IECoreRI::Renderer::setOption	(	const std::string &	name,
		IECore::ConstDataPtr	value
	)		[virtual]

Standard options supported :

• "searchPath:font"

Implementation specific options :

• "ri:searchpath:shader" StringData()
  A colon separated list of paths to search for shaders on.

• "ri:pixelSamples" V2iData()
  Passed to an RiPixelSamples call.

• "ri:*:*"
  Passed to an RiOption call.

virtual void IECoreRI::Renderer::setTransform

(

const std::string &

coordinateSystem

)

[virtual]

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

Implements IECore::Renderer.

virtual void IECoreRI::Renderer::shader	(	const std::string &	type,
		const std::string &	name,
		const IECore::CompoundDataMap &	parameters
	)		[virtual]

If type is "surface" or "ri:surface" then calls RiSurfaceV. If type is "displacement" or "ri:displacement" then calls RiDisplacementV. If type is "atmosphere" or "ri:atmosphere" then calls RiDisplacementV. If type is "interior" or "ri:interior" then calls RiInteriorV. If type is "exterior" or "ri:exterior" then calls RiExteriorV. If type is "deformation" or "ri:deformation" then calls RiDeformationV. If type is "shader" or "ri:shader" then calls RiShader. In this case you must specify a handle as a StringData parameter named "__handle".

Implements IECore::Renderer.

virtual void IECoreRI::Renderer::sphere	(	float	radius,
		float	zMin,
		float	zMax,
		float	thetaMax,
		const IECore::PrimitiveVariableMap &	primVars
	)		[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.

Implements IECore::Renderer.

virtual void IECoreRI::Renderer::transformBegin

(

)

[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.

Implements IECore::Renderer.

virtual void IECoreRI::Renderer::worldBegin

(

)

[virtual]

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

Implements IECore::Renderer.

---

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

• include/IECoreRI/Renderer.h