The base class for the render plug-in which takes a Katana recipe and converts it into the renderer's language. More...

#include <RenderBase.h>

Inheritance diagram for Foundry::Katana::Render::RenderBase:

Public Member Functions
	RenderBase (Foundry::Katana::FnScenegraphIterator rootIterator, FnAttribute::GroupAttribute arguments)
virtual int	setup ()
virtual int	cleanup ()
virtual void	setRootIterator (Foundry::Katana::FnScenegraphIterator rootIterator)
virtual int	start ()=0
virtual int	pause ()
virtual int	resume ()
virtual int	stop ()
virtual int	startLiveEditing ()
virtual int	stopLiveEditing ()
virtual int	processControlCommand (const std::string &command)
virtual int	queueDataUpdates (FnAttribute::GroupAttribute updateAttribute)
virtual int	applyPendingDataUpdates ()
virtual bool	hasPendingDataUpdates () const
virtual void	configureDiskRenderOutputProcess (DiskRenderOutputProcess &diskRenderOutputProcess, const std::string &outputName, const std::string &outputPath, const std::string &renderMethodName, const float &frameTime) const
Protected Member Functions
Foundry::Katana::FnScenegraphIterator	getRootIterator () const
std::string	getRenderMethodName () const
std::string	findArgument (const std::string &argumentName, const std::string &defaultValue="") const
bool	applyRenderThreadsOverride (int &numberOfRenderThreads) const
std::string	getKatanaBasePath () const
std::string	getKatanaTempDirectory () const
std::string	getKatanaHost () const
float	getRenderTime () const
bool	useRenderPassID () const
std::string	getRenderOutputFile () const
bool	isExpandProceduralActive (bool defaultValue=false) const
std::string	getRenderPluginDirectory () const
std::string	getEnvironmentVariable (const std::string &name) const
template<typename T , typename A >
T	getAttrValue (const FnAttribute::Attribute &attr, const T &defaultValue) const
std::string	getStringAttrValue (const FnAttribute::Attribute &attr, const std::string &defaultValue="") const

Detailed Description

The base class for the render plug-in which takes a Katana recipe and converts it into the renderer's language.

A render plug-in represents a single render process (for a single frame) where the plug-in is instantiated when a render is launched and destroyed when the render is complete or cancelled. The Katana recipe is presented to the render plug-in in the form of a FnScenegraphIterator which allows traversing the scene graph in a deferred manner. The root scene graph iterator is passed to the plug-in's constructor where it is accessible anywhere in the plug-in through Render::RenderBase::getRootIterator. The render arguments are also passed to the constructor but we recommend using the wrapper functions to retrieve the standard arguments.

The plug-in has to extend the Render abstract class and register itself using the DEFINE_RENDER_PLUGIN(class) and REGISTER_PLUGIN(class, name, major_version, minor_version) macros. This will ensure the plug-in is exposed in the UI by its registered name as well as making it available to Katana's render process.

Constructor & Destructor Documentation

Foundry::Katana::Render::RenderBase::RenderBase	(	Foundry::Katana::FnScenegraphIterator	rootIterator,
		FnAttribute::GroupAttribute	arguments
	)		`[inline]`

The render plug-in class is instantiated by the renderboot process which is launched when a render is started through the UI or using the RenderManager.StartRender script function.

Parameters:

rootIterator	The root FnScenegraphIterator used to traverse the scene graph produced by a Katana recipe
arguments	Render arguments (e.g. render time)

See also:: Render::RenderBase::getRootIterator

Member Function Documentation

virtual int Foundry::Katana::Render::RenderBase::applyPendingDataUpdates ( ) [inline, virtual]

Apply one or more live data updates which have been processed by queueDataUpdates. This provides an opportunity to process and queue live update attributes in the update thread and then flush them in the main thread.

This function is called if hasPendingDataUpdates returns true.

Returns:: A zero value if successful, a non-zero value otherwise.

See also:: Render::RenderBase::hasPendingDataUpdates; Render::RenderBase::queueDataUpdates

Reimplemented in CompanyName::Katana::TemplateRenderPlugin.

bool Foundry::Katana::Render::RenderBase::applyRenderThreadsOverride ( int & numberOfRenderThreads ) const [protected]

Update the number of render threads if a 'threads' argument is passed as a render argument. The thread value is passed to the render process in the following cases:

UI mode: The 'interactiveRenderThreads3D' value is used if 'interactiveRenderThreadOverride' is set to 'Yes' in the Preferences dialog under 'application->rendering'.
Batch mode: The thread count is set using the '--threads3d' argument when launching Katana.

Parameters:

numberOfRenderThreads The render thread variable which is subject to the thread override

Returns:: true if an override was applied, false otherwise

virtual int Foundry::Katana::Render::RenderBase::cleanup ( ) [inline, virtual]

Clean up any resources that the render plug-in has allocated.

Returns:: A zero value if successful, a non-zero value otherwise.

virtual void Foundry::Katana::Render::RenderBase::configureDiskRenderOutputProcess	(	DiskRenderOutputProcess &	diskRenderOutputProcess,
		const std::string &	outputName,
		const std::string &	outputPath,
		const std::string &	renderMethodName,
		const float &	frameTime
	)		const `[inline, virtual]`

Provide Katana with information on how to process a given render output which has been defined in a Katana scene using the RenderOutputDefine node. This is only applicable during disk render where the function is called for each render output (port) on the render node.

Note:: The list of available output types is provided by RendererInfo::RendererInfoBase::buildRendererObjectInfo when Katana calls the function using kFnRendererObjectTypeRenderOutput as an object type.

Parameters:

diskRenderOutputProcess	Defines the render action for a given render output as well as pre- and post-commands used in the render process.
outputName	The name of the render output (as defined in the corresponding RenderOutputDefine node).
outputPath	The target location for the render output.
renderMethodName	The render method used to launch the render.
frameTime	The current frame time.

See also:: Render::DiskRenderOutputProcess; Render::RenderAction; Render::CopyRenderAction; Render::CopyAndConvertRenderAction; Render::TemporaryRenderAction; Render::NoOutputRenderAction; Render::RenderSettings::RenderOutputs; Render::RenderSettings::getRenderOutputs; RendererInfo::RendererInfoBase::buildRendererObjectInfo

Reimplemented in ProfilingMockRenderer::RenderPlugin, and CompanyName::Katana::TemplateRenderPlugin.

std::string Foundry::Katana::Render::RenderBase::findArgument	(	const std::string &	argumentName,
		const std::string &	defaultValue = `""`
	)		const `[protected]`

Retrieve a render argument by name. The standard render arguments are accessible through explicit functions but custom live render arguments which have been advertised in the live render tab using the startConfiguration policy type.

Parameters:

argumentName	The name of the render argument that should be retrieved
defaultValue	The value to return in case the argument doesn't exist

Returns:: The render argument value

template<typename T , typename A >

T Foundry::Katana::Render::RenderBase::getAttrValue	(	const FnAttribute::Attribute &	attr,
		const T &	defaultValue
	)		const `[inline, protected]`

A helper function which retrieves and converts the value of an Attribute to a desired standard type. This is useful for instance when collecting custom rendererSettings values from the render outputs, e.g.:

   int mySettings = getAttrValue<int, IntAttribute>(output.rendererSettings["mySettings"], 0);

Parameters:

attr	The Attribute that we want to retrieve the value from
defaultValue	Default value if the attribute is not valid

Returns:: The typed attribute value or the default value if the attribute is not valid

std::string Foundry::Katana::Render::RenderBase::getEnvironmentVariable ( const std::string & name ) const [protected]

Looks up and returns the value of an environment variable by name.

Returns:: The value of the environment variable with the given name.

std::string Foundry::Katana::Render::RenderBase::getKatanaBasePath ( ) const [inline, protected]

Returns:: The base path for Katana

std::string Foundry::Katana::Render::RenderBase::getKatanaHost ( ) const [inline, protected]

Get the host and port of Katana's listener which is started when Katana is launched in UI mode. The listener is used to retrieve image and id data from the renderer plug-in.

Returns:: The host name for Katana's image and id listener

std::string Foundry::Katana::Render::RenderBase::getKatanaTempDirectory ( ) const [inline, protected]

Get the name of the temporary directory Katana creates at startup which is used throughout the session.

Returns:: Katana's temporary directory

std::string Foundry::Katana::Render::RenderBase::getRenderMethodName ( ) const [protected]

Retrieve the render method used to launch the render from the render arguments. The method name is passed to the RenderManager.StartRender function where the list of available methods is declared by RendererInfo::RendererInfoBase::fillRenderMethods in UI mode, and by configureBatchRenderMethod in batch mode, when creating debug outputs, and when rendering dependencies.

Returns:: The render method name used to launch the render process

See also:: RendererInfo::RendererInfoBase::fillRenderMethods; RendererInfo::RendererInfoBase::configureBatchRenderMethod

std::string Foundry::Katana::Render::RenderBase::getRenderOutputFile ( ) const [inline, protected]

Returns the name of a file which Katana expects the render plug-in to create and populate with scene description data and/or debug information. See "Generating a render debug output" in the Katana Developer Guide.

Returns:: The name of the the render debug output file

std::string Foundry::Katana::Render::RenderBase::getRenderPluginDirectory ( ) const [inline, protected]

Returns the directory name where the render plug-in resides on disk.

Returns:: The render plug-in directory

float Foundry::Katana::Render::RenderBase::getRenderTime ( ) const [protected]

Get the render time which is either a value retrieved from the timeline (UI mode), or a single frame from the interval provided by the -t command line argument when launching a batch render.

Returns:: The render time (frame)

Foundry::Katana::FnScenegraphIterator Foundry::Katana::Render::RenderBase::getRootIterator ( ) const [inline, protected]

The scene graph iterator is used to traverse the scene graph and author data to the renderer based on the scene graph type and attributes. The root iterator provides a starting point for the traversal as it contains the entire scene graph as well as any global scene attributes which are by convention assigned to the root location.

Returns:: The iterator for the root scene graph location

std::string Foundry::Katana::Render::RenderBase::getStringAttrValue	(	const FnAttribute::Attribute &	attr,
		const std::string &	defaultValue = `""`
	)		const `[inline, protected]`

A convenience function for retrieving the value of StringAttribute

Parameters:

attr	The StringAttribute that we want to retrieve the value from
defaultValue	Default string value if the attribute is not valid

Returns:: The string value contained in the attribute or the default value if the attribute is not valid

virtual bool Foundry::Katana::Render::RenderBase::hasPendingDataUpdates ( ) const [inline, virtual]

Inform the render process whether it has to flush and apply live updates.

Returns:: true if there are updates which have to be applied, false otherwise

See also:: Render::RenderBase::applyPendingDataUpdates; Render::RenderBase::queueDataUpdates

Reimplemented in CompanyName::Katana::TemplateRenderPlugin.

bool Foundry::Katana::Render::RenderBase::isExpandProceduralActive ( bool defaultValue = false ) const [protected]

This function is used in conjunction with getRenderOutputFile where if a render output file is expected to be generated, and if the renderer supports recursive procedurals, then this determines whether the procedurals should be expanded or not.

Returns:: true if the procedurals should be expanded, false otherwise

See also:: getRenderOutputFile

Note:: A better function name might be shouldExpandProcedurals().

virtual int Foundry::Katana::Render::RenderBase::pause ( ) [inline, virtual]

Interrupt and pause the render process but does not terminate it.

Note:: This is only used during live render when updating regions of interest.

Returns:: A zero value if successful, a non-zero value otherwise.

Reimplemented in CompanyName::Katana::TemplateRenderPlugin.

virtual int Foundry::Katana::Render::RenderBase::processControlCommand ( const std::string & command ) [inline, virtual]

Process a custom live render control command which has been triggered by the user in the live update tab.

Parameters:

command Live render control command

Returns:: A zero value if successful, a non-zero value otherwise.

Reimplemented in CompanyName::Katana::TemplateRenderPlugin.

virtual int Foundry::Katana::Render::RenderBase::queueDataUpdates ( FnAttribute::GroupAttribute updateAttribute ) [inline, virtual]

Process a data update during live render. The update is based on an attribute convention where an update for a single scene graph location is encapsulated by a GroupAttribute. Each attribute update contains the following:

type: root, globals, camera, light, geoMaterial, or a custom type declared as a LiveRenderAPI plugin.
location: The full scene graph location name
attributes: A GroupAttribute containing the update attributes which vary based on the type:
- root: camera (StringAttribute containing the selected camera)
- globals: [rendererName]GlobalStatements
- camera: xform, geometry
- light: xform, material, geometry, mute, info
- geoMaterial: material, info
- (custom): Depends on what attributes were declared for the custom type.

Note:: A useful trick while debugging is to print the XML string for the update attribute to see its contents: updateAttribute.getXML();; This function is called from a separate update thread whereas hasPendingDataUpdates and applyPendingDataUpdates are called in the main render process thread.

Parameters:

updateAttribute A group attribute containing one or more update attributes.

Returns:: A zero value if successful, a non-zero value otherwise.

See also:: Render::RenderBase::hasPendingDataUpdates; Render::RenderBase::applyPendingDataUpdates

Reimplemented in CompanyName::Katana::TemplateRenderPlugin.

virtual int Foundry::Katana::Render::RenderBase::resume ( ) [inline, virtual]

Resume a paused render.

Note:: This is currently never called.

Returns:: A zero value if successful, a non-zero value otherwise.

Reimplemented in CompanyName::Katana::TemplateRenderPlugin.

virtual void Foundry::Katana::Render::RenderBase::setRootIterator ( Foundry::Katana::FnScenegraphIterator rootIterator ) [inline, virtual]

Set the root FnScenegraphIterator to use to traverse the Katana scene graph to the given scene graph iterator.

Parameters:

rootIterator The root FnScenegraphIterator to use.

virtual int Foundry::Katana::Render::RenderBase::setup ( ) [inline, virtual]

Set up the render plug-in so that it is ready to perform one or more renders.

Returns:: A zero value if successful, a non-zero value otherwise.

virtual int Foundry::Katana::Render::RenderBase::start ( ) [pure virtual]

Start a render by traversing the scene graph using FnScenegraphIterator and interpret the locations and attributes into the renderer's language. This function is called at the start of each frame to be rendered. It is possible that this will be called multiple times during the lifetime of the plug-in.

Returns:: A zero value if successful, a non-zero value otherwise.

Implemented in ProfilingMockRenderer::RenderPlugin, and CompanyName::Katana::TemplateRenderPlugin.

virtual int Foundry::Katana::Render::RenderBase::startLiveEditing ( ) [inline, virtual]

Start the live render process. Data updates and control commands will follow.

Returns:: A zero value if successful, a non-zero value otherwise.

Reimplemented in CompanyName::Katana::TemplateRenderPlugin.

virtual int Foundry::Katana::Render::RenderBase::stop ( ) [inline, virtual]

Called at the end of each frame that is rendered. It is possible that this will be called multiple times during the lifetime of the plug-in.

Returns:: A zero value if successful, a non-zero value otherwise.

Reimplemented in ProfilingMockRenderer::RenderPlugin, and CompanyName::Katana::TemplateRenderPlugin.

virtual int Foundry::Katana::Render::RenderBase::stopLiveEditing ( ) [inline, virtual]

Stop the live render process. No further data updates or control commands should be expected.

Returns:: A zero value if successful, a non-zero value otherwise.

Reimplemented in CompanyName::Katana::TemplateRenderPlugin.

bool Foundry::Katana::Render::RenderBase::useRenderPassID ( ) const [protected]

Specifies whether an ID pass should be created. The user guide explains how to activate an ID pass in the monitor and how to use the picker tool.

See "Sending ID pass data to Katana" in the Katana Developer Guide for further information.

Returns:: true if an ID pass should be created, false otherwise

See also:: Render::IdSenderFactory::getNewInstance; Render::IdSenderInterface

Note:: A better function name might be shouldRenderIDPass().

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

RenderBase.h

Foundry::Katana::Render::RenderBase Class ReferenceRenderer API

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Foundry::Katana::Render::RenderBase Class Reference
Renderer API