IECoreGL::Renderer Class Reference

#include <Renderer.h>

Inheritance diagram for IECoreGL::Renderer:

List of all members.

Public Member Functions
	IE_CORE_DECLARERUNTIMETYPEDEXTENSION (IECoreGL::Renderer, RendererTypeId, IECore::Renderer)
virtual void	setOption (const std::string &name, IECore::ConstDataPtr value)
virtual IECore::ConstDataPtr	getOption (const std::string &name) const
	Get the value of a previously set option.
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.
ScenePtr	scene ()
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
	Return the value of the named attribute.
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)
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)
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)
ShaderManager *	shaderManager ()
TextureLoader *	textureLoader ()

---

Detailed Description

The IECoreGL::Renderer class implements the IECore::Renderer interface to allow rendering to OpenGL. Immediate mode rendering allows the generation of images and deferred mode rendering allows scenes to be captured for later interactive display.

---

Member Function Documentation

virtual void IECoreGL::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 IECoreGL::Renderer::camera	(	const std::string &	name,
		const IECore::CompoundDataMap &	parameters
	)		[virtual]

Standard parameters supported :

• "resolution"
• "projection" (orthographic and perspective)
• "projection:fov"
• "resolution"
• "screenWindow"
• "clippingPlanes"

Implements IECore::Renderer.

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

Commands implemented

"removeObject"
Expects a StringData parameter named "name", which specifies the name of an object to remove from the scene. This only has any effect in deferred mode. "editBegin"
This parameter-less command marks the start of an edit to an existing scene, and should be called before any other changes are made when re-using an existing renderer, that has already reached worldEnd. "editEnd"
This parameter-less command marks the end of an edit to an existing scene, and should be called after other changes have been made when re-using an existing renderer. Note that if a scene has been drawn with renderer->scene()->render() prior to this edit, then it is essential that editEnd is called by the same thread on which drawing was performed, so that GL resources can be released in the appropriate context. "editQuery"
This parameter-less command returns BoolData( true ) if an edit is in progress, and BoolData( false ) otherwise.

Todo:

Consider generalising an interface for scene edits and making it a standard part of the documentation in IECore. Any such interface should take into account support for PRMan's new rerendering API.

Implements IECore::Renderer.

virtual void IECoreGL::Renderer::curves	(	const IECore::CubicBasisf &	basis,
		bool	periodic,
		IECore::ConstIntVectorDataPtr	numVertices,
		const IECore::PrimitiveVariableMap &	primVars
	)		[virtual]

Supports the following primitive variables :

Vertex V3fVectorData "P" Constant FloatData "width"

virtual void IECoreGL::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 IECoreGL::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 void IECoreGL::Renderer::geometry	(	const std::string &	type,
		const IECore::CompoundDataMap &	topology,
		const IECore::PrimitiveVariableMap &	primVars
	)		[virtual]

Supports the following geometry types with the specified topology data :

"sphere" "radius" FloatData 1 "zMin" FloatData -1 "zMax" FloatData 1 "thetaMax" FloatData 360

Deprecated:

Use the sphere() method instead.

Implements IECore::Renderer.

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

Supports the following image formats specified as primitive variables :

"R", "G", "B", "A" : UCharVectorData "R", "G", "B", "A" : CharVectorData "R", "G", "B", "A" : UIntVectorData "R", "G", "B", "A" : IntVectorData "R", "G", "B", "A" : HalfVectorData "R", "G", "B", "A" : FloatVectorData "R", "G", "B", "A" : DoubleVectorData

As a convenience the names "r", "g", "b", "a" or "red", "green", "blue", "alpha" can appear in place of "R", "G", "B", "A".

Currently assumes dataWindow==displayWindow.

Implements IECore::Renderer.

virtual void IECoreGL::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 IECoreGL::Renderer::mesh	(	IECore::ConstIntVectorDataPtr	vertsPerFace,
		IECore::ConstIntVectorDataPtr	vertIds,
		const std::string &	interpolation,
		const IECore::PrimitiveVariableMap &	primVars
	)		[virtual]

All meshes are treated as having interpolation=="linear".

Todo:

Support normals and st.

virtual void IECoreGL::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 IECoreGL::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 IECoreGL::Renderer::points	(	size_t	numPoints,
		const IECore::PrimitiveVariableMap &	primVars
	)		[virtual]

Supports the following primitive variables :

Vertex V3fVectorData "P"

Uniform StringData "type" Used to determine how the points are rendered. Supported types are :

"gl:point" Rendered as GL_POINTS

"particle" (the default) "disk" "blobby" Rendered as camera facing disks. The "width" and "constantwidth" variables are supported. Blobby is provided for vague compatibility with the IECoreRI::RIRenderer and 3delight.

"patch" Rendered as camera facing patches. Supports the "width" and "constantwidth" variables and in addition the "patchaspectratio" and "patchrotation" variables. See the 3delight documentation for a description of how these can be used.

"sphere" Rendered as spheres. Supports "width" and "constantwidth" variables to define the sizes of the spheres.

Constant FloatData "constantwidth"

Vertex|Varying FloatVectorData "width"

Constant|Vertex|Varying FloatData|FloatVectorData "patchaspectratio" Constant|Vertex|Varying FloatData|FloatVectorData "patchrotation" These two are used only by the "patch" type.

Implements IECore::Renderer.

ScenePtr IECoreGL::Renderer::scene

(

)

When in deferred mode (see setOption above), this method will return the Scene that was generated.

Threading:

The Renderer tries very hard not to need a GL context to operate in when in deferred mode. This allows it to evaluate multiple procedurals concurrently in separate threads (GL wants only one threading talking to a context). When the scene is rendered for the first time it will instantiate various OpenGL resources (textures and shaders and the like) in the current GL context. It is therefore important that the scene is destroyed from the same thread that renders it, so that the resources are released in the correct context. As the resources are also shared by caches (TextureLoaders and ShaderManagers) in the Renderer, it is also important that the renderer is destroyed from this same thread.

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

Standard attributes supported :

• "color"
  Sets the rgb components of the current OpenGL color.
• "opacity"
  Sets the alpha component of the current OpenGL color to the average of the rgb components of opacity.

• "doubleSided"
• "rightHandedOrientation"
• "name"

• "user:*"

Implementation specific attributes :

• "gl:color" Color4fData Color4f( 1.0f ) Sets the current OpenGL color including the alpha component.

Implementation specific shading attributes :

• "gl:shade:transparent" BoolData false
  Signifies that shading may result in transparent results. This is necessary as it's nontrivial to determine this information by querying the shader, and other parts of the system may need to know when transparency is present - for example to trigger depth sorting.

Implementation specific primitive style attributes :

• "gl:primitive:wireframe" BoolData false
  Draw a wireframe for each primitive.

• "gl:primitive:wireframeWidth" FloatData 1.0f
  The line width of the wireframe of the primitive.

• "gl:primitive:wireframeColor" Color4fData
  The color of the wireframes drawn.

• "gl:primitive:bound" BoolData false
  Draw a bounding box for each primitive.

• "gl:primitive:boundColor" Color4fData
  The color of the bounding boxes drawn.

• "gl:primitive:solid" BoolData true
  Draw each primitive solid.

• "gl:primitive:outline" BoolData false
  Draw an outline for each primitive. Note that the results of having this on with filled mode off will probably be undesirable.

• "gl:primitive:outlineColor" Color4fData
  The color of the outlines drawn.

• "gl:primitive:outlineWidth" FloatData 1.0f
  The line width of the outlines of the primitive.

• "gl:primitive:points" BoolData false
  Draw the vertices of each primitive as points.

• "gl:primitive:pointWidth" FloatData 1.0f
  The width of the points used to draw vertices.

• "gl:primitive:pointColor" Color4fData
  The color of the points drawn.

• "gl:primitive:sortForTransparency" BoolData true
  Causes the individual components of a primitive to be sorted in depth when the "gl:shade:transparent" attribute is true. This is currently supported only by the points primitive.

Implementation specific points primitive attributes :

• "gl:pointsPrimitive:useGLPoints" StringData "forGLPoints"
  Can be used to force the use of lightweight glPoints representation of points primitives with types other than "gl:point". Valid values are :
  
  "forGLPoints"
  Use lightweight points only if type is "gl:point"
  
  "forParticlesAndDisks"
  Use lightweight points as a stand in for particle and disk types.
  
  "forAll"
  Use lightweight points as a stand in for all point types.
  
  

• "gl:pointsPrimitive:glPointWidth" FloatData 1.0f
  The size of the points (in pixels) used when rendering lightweight points.

Implementation specific curves primitive attributes :

• "gl:curvesPrimitive:useGLLines" BoolData false
  When this is true then lightweight OpenGL line primitives are used for representing curves.

• "gl:curvesPrimitive:glLineWidth" FloatData 1.0f
  Specifies the line width (in pixels) which is used when rendering lightweight line primitives.

• "gl:curvesPrimitive:ignoreBasis" BoolData false
  When this is true, all curves are rendered as if they were linear.

Implementation specific text primitive attributes :

• "gl:textPrimitive:type" StringData "mesh"
  Controls the basic method used for text rendering. A value of "mesh" specifies that text primitives are rendered as triangulated meshes, and a value of "sprite" specifies rendering as textured planes. The former allows completely customisable shading using the current shader, whereas the latter is shaded constantly using the current colour, but may offer better anti-aliasing and/or speed.

Implementation specific blending attributes :

• "gl:blend:srcFactor" StringData "srcAlpha"
  
• "gl:blend:dstFactor" StringData "oneMinusSrcAlpha"
  These attributes are mapped onto calls to glBlendFunc. They accept only the values below, which correspond directly to one of the GLenum blending values.
  
  "zero"
  "one"
  "srcColor"
  "oneMinusSrcColor"
  "dstColor"
  "oneMinusDstColor"
  "srcAlpha"
  "oneMinusSrcAlpha"
  "dstAlpha"
  "oneMinusDstAlpha"
  "constantColor"
  "oneMinusConstantColor"
  "constantAlpha"
  "oneMinusConstantAlpha"
  

• "gl:blend:color" Color4fData 1 1 1 1
  Used to specify glBlendColor(), only taking effect when using either "constantColor" or "oneMinusConstantColor" for one or other of the blend factors above.

• "gl:blend:equation" StringData "add"
  Controls how the src and dst values are combined after being weighted by srcFactor and dstFactor - this maps onto a call to glBlendEquation. Valid values are listed below, and map directly onto the corresponding GLenum values.
  
  "add"
  "subtract"
  "reverseSubtract"
  "min"
  "max"
  

Implementation specific antialiasing attributes :

• "gl:smoothing:points" BoolData false
  
• "gl:smoothing:lines" BoolData false
  
• "gl:smoothing:polygons" BoolData false
  These attributes enable GL_POINT_SMOOTH, GL_LINE_SMOOTH and GL_POLYGON_SMOOTH respectively.

Implementation specific procedural attributes :

• "gl:procedural:reentrant" BoolData true
  When true, procedurals may be evaluated in multiple parallel threads. When false they will be evaluated from the same thread they were specified from.

  Implementation specific depth buffer attributes :

• "gl:depthTest" BoolData true
  Maps to glEnable/Disable GL_DEPTH_TEST

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

Standard options supported :

• "searchPath:font"

Implementation specific options supported :

"gl:mode" StringData Valid values are "immediate" or "deferred". In immediate mode rendering is performed in a streaming fashion, drawing each primitive as it is specified. In deferred mode rendering is performed by building a Scene object which can be retrieved for further use by using the scene() method after the render is complete. Future versions may support advanced features such as motion blur and depth of field when in deferred mode but not in immediate mode.

"searchPath:shader" StringData "gl:searchPath:shader" StringData Specifies a set of colon separated paths on which to search for GLSL shaders. The default value is obtained from the environment variable IECOREGL_SHADER_PATHS.

"searchPath:shaderInclude" StringData "gl:searchPath:shaderInclude" StringData Specifies a set of colon separated paths on which to search for include files for GLSL shaders. The default value is obtained from the environment variable IECOREGL_SHADER_INCLUDE_PATHS.

"searchPath:texture" StringData "gl:searchPath:texture" StringData Specifies a set of colon separated paths on which to search for textures. The default value is obtained from the environment variable IECOREGL_TEXTURE_PATHS. Any image file format for which an IECore::Reader is available is suitable for use as a texture.

"shutter" V2fData

"gl:drawCoordinateSystems" BoolData false When this is true, coordinate systems created with the coordinateSystem() method will be visualised.

virtual void IECoreGL::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 IECoreGL::Renderer::shader	(	const std::string &	type,
		const std::string &	name,
		const IECore::CompoundDataMap &	parameters
	)		[virtual]

Supports only shader type "surface" or "gl:surface", looking for "name.vert" and "name.frag" GLSL source files in the paths defined by the "searchPath:shader" option. Alternatively if the parameter list contains "gl:vertexSource" and/or a "gl:fragmentSource" StringData then a new shader is created using the source provided. For shaders with sampler2D parameters, texture files for these parameters may be specified by passing the filename to an image as StringData.

Todo:

Add support for "textureParameterName:filter" and "textureParameterName:wrap" parameters which set wrapping and filtering on a ShaderStateComponent.

Implements IECore::Renderer.

ShaderManager* IECoreGL::Renderer::shaderManager

(

)

Returns the internal ShaderManager object used to manage the shaders from this renderer. If called before worldBegin it returns 0.

virtual void IECoreGL::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.

TextureLoader* IECoreGL::Renderer::textureLoader

(

)

Returns the internal TextureLoader object. If called before worldBegin it returns 0.

virtual void IECoreGL::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 IECoreGL::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/IECoreGL/Renderer.h