Detailed Description

This object is provided as the source object available from the RendererContext for a Plugin-based cus_render Custom Renderer object.

See also:: PluginRegistrar::RegisterRenderer

Since:: 6.01

#include <xsi_renderer.h>

Inheritance diagram for Renderer:

[legend]

List of all members.

Public Member Functions
	Renderer ()
	~Renderer ()
	Renderer (const CRef &in_ref)
	Renderer (const Renderer &in_obj)
bool	IsA (siClassID in_ClassID) const
siClassID	GetClassID () const
Renderer &	operator= (const Renderer &in_obj)
Renderer &	operator= (const CRef &in_ref)
CStatus	PutProcessTypes (const CLongArray &in_types)
CLongArray	GetProcessTypes ()
bool	HasProcessType (siRenderProcessType in_eProcessType)
CStatus	PutArchiveFormat (const CString &in_strName, const CString &in_strExtension, bool in_bMultiFrame)
CStatus	GetArchiveFormat (CString &out_strName, CString &out_strExtension, bool &out_bMultiFrame)
CStatus	PutObjectArchiveFormat (const CString &in_strName, const CString &in_strExtension, bool in_bMultiFrame, bool in_bDisplayProxy)
CStatus	GetObjectArchiveFormat (CString &out_strName, CString &out_strExtension, bool &out_bMultiFrame, bool &out_bDisplayProxy)
CStatus	AddProperty (siRenderPropertyType in_eType, const CString &in_strName)
CString	GetPropertyName (siRenderPropertyType in_eType, bool in_bScriptingName=false)
CStatus	AddOutputImageFormat (const CString &in_strName, const CString &in_strExtension)
CStatus	GetOutputImageFormats (CStringArray &out_names, CStringArray &out_extensions)
CStatus	AddOutputImageFormatSubType (siRenderChannelType in_eChannelType, const CString &in_strDataType, siImageBitDepth in_eBitDepth)
CStatus	GetOutputImageFormatSubTypes (const CString &in_strName, CLongArray &out_channelTypes, CStringArray &out_dataTypes, CLongArray &out_bitDepths)
CStatus	AddDefaultChannel (const CString &in_strName, siRenderChannelType in_eChannelType)
CStatus	GetDefaultChannels (CStringArray &out_names, CLongArray &out_channelTypes)
CString	GetVersionString ()
CStatus	LockSceneData ()
CStatus	UnlockSceneData ()

Constructor & Destructor Documentation

Renderer ( )

Default constructor.

~Renderer ( )

Default destructor.

Renderer ( const CRef & in_ref )

Constructor.

Parameters:

in_ref constant reference object.

Renderer ( const Renderer & in_obj )

Copy constructor.

Parameters:

in_obj constant class object.

Member Function Documentation

bool IsA ( siClassID in_ClassID ) const [virtual]

Returns true if a given class type is compatible with this API class.

Parameters:

in_ClassID class type.

Returns:: true if the class is compatible, false otherwise.

Reimplemented from SIObject.

siClassID GetClassID ( ) const [virtual]

Returns the type of the API class.

Returns:: The class type.

Reimplemented from SIObject.

Renderer& operator= ( const Renderer & in_obj )

Creates an object from another object.

Parameters:

in_obj constant class object.

Returns:: The new Renderer object.

Renderer& operator= ( const CRef & in_ref )

Creates an object from a reference object. The newly created object is set to empty if the input reference object is not compatible.

Parameters:

in_ref constant class object.

Returns:: The new Renderer object.

Reimplemented from SIObject.

CStatus PutProcessTypes ( const CLongArray & in_types )

Sets the types of processes this rendering engine can handle as a list of siRenderProcessType enumeration values.

Note:: This function should only be called from the renderer's cb_Renderer_Init Init callback. In any other callback it has no effect.

Parameters:

in_types List of process types supported by this renderer.

Returns:: CStatus::OK Process types set successfully; CStatus::Fail No valid process types given.; CStatus::AccessDenied Not in initialization mode.

CLongArray GetProcessTypes ( )

Returns all the process types that this renderer supports as a list of siRenderProcessType enumeration values.

Returns:: List of process types supported by this renderer.

bool HasProcessType ( siRenderProcessType in_eProcessType )

Returns true if this renderer supports a specific process types.

Parameters:

in_eProcessType The process type to query (one of the siRenderProcessType enum values)

Returns:: Boolean indicating whether the given process type is supported.

CStatus PutArchiveFormat	(	const CString &	in_strName,
		const CString &	in_strExtension,
		bool	in_bMultiFrame
	)

Sets the name of the scene archive format and the default extension if the renderer supports scene render archives. The caller can also indicate whether the scene archive format supports multi-frame output to a single archive file.

Note:: This function should only be called from the renderer's cb_Renderer_Init Init callback. In any other callback it has no effect.

Parameters:

in_strName	The name of the format to use. This is used for display purposes, such as browsing.
in_strExtension	The standard file extension used for the format. This is appended automatically when creating archive output file paths from the archive filename template.
in_bMultiFrame	True if the archive format supports multiple frames in a single file. Otherwise XSI always writes out separate files for each frame.

Returns:: CStatus::OK Archive settings set successfully.; CStatus::AccessDenied Not in initialization mode.

CStatus GetArchiveFormat	(	CString &	out_strName,
		CString &	out_strExtension,
		bool &	out_bMultiFrame
	)

Returns the name, file extension and multi-frame capability of the scene archive format used by this renderer.

Note:: This function should only be called if the renderer supports the siRenderProcessExportArchive process type.

Return values:

out_strName	The name of the scene archive format.
out_strExtension	The filename extension that's used for the format.
out_bMultiFrame	True if the archive supports multiple frames in a single file.

Returns:: CStatus::OK Archive settings retrieved successfully.; CStatus::Fail The renderer does not support the siRenderProcessExportArchive process type.

CStatus PutObjectArchiveFormat	(	const CString &	in_strName,
		const CString &	in_strExtension,
		bool	in_bMultiFrame,
		bool	in_bDisplayProxy
	)

Sets the name of the object archive format and the default extension if the renderer supports object render archives. The caller can also indicate whether the object archive format supports multi-frame output to a single archive file; and whether the archive export can generate images representing the contents of the object archive, for display purposes.

Note:: This function should only be called from the renderer's cb_Renderer_Init Init callback. In any other callback it has no effect.

Parameters:

in_strName	The name of the format to use. This is used for display purposes, such as browsing.
in_strExtension	The standard file extension used for the format. This is appended automatically when creating archive output file paths from the archive filename template.
in_bMultiFrame	True if the archive format supports multiple frames in a single file. Otherwise XSI always writes out separate files for each frame.
in_bDisplayProxy	True if the archive export can generate low-resolution proxy images for a viewport display of the object archive. There should be three images, projected on the XY, XZ and YZ axes, and covering the entire bounding box of the object archive's contents.

Returns:: CStatus::OK Archive settings set successfully.; CStatus::AccessDenied Not in initialization mode.

CStatus GetObjectArchiveFormat	(	CString &	out_strName,
		CString &	out_strExtension,
		bool &	out_bMultiFrame,
		bool &	out_bDisplayProxy
	)

Returns the name, file extension, multi-frame and display proxy capability of the object archive format used by this renderer.

Note:: This function should only be called if the renderer supports the siRenderProcessExportObjectArchive process type.

Return values:

out_strName	The name of the scene archive format.
out_strExtension	The filename extension that's used for the format.
out_bMultiFrame	True if the archive supports multiple frames in a single file.
out_bDisplayProxy	True if the renderer can generate display proxies with the archive.

Returns:: CStatus::OK Archive settings retrieved successfully.; CStatus::Fail The renderer does not support the siRenderProcessExportObjectArchive process type.

CStatus AddProperty	(	siRenderPropertyType	in_eType,
		const CString &	in_strName
	)

Adds a new property that should be created for the specified type. The last property added for a specified type will be the one used.

Note:: This function should only be called from the renderer's cb_Renderer_Init Init callback. In any other callback it has no effect.

Parameters:

in_eType	The type of render property associated with the property given.
in_strName	The name of the property to create for the render property type.

Returns:: CStatus::OK Property type added successfully.; CStatus::AccessDenied Not in initialization mode.

CString GetPropertyName	(	siRenderPropertyType	in_eType,
		bool	in_bScriptingName = `false`
	)

Returns the object or scripting name of the given renderer property. This can be used with SceneItem.GetProperties to get the appropriate property from the Pass, PassContainer and others.

Parameters:

in_eType	Specific renderer property name to retrieve.
in_bScriptingName	Whether to get the scripting name or not.

Returns:: The name of the property.

CStatus AddOutputImageFormat	(	const CString &	in_strName,
		const CString &	in_strExtension
	)

Adds a new output image format that is supported by this renderer. The format will be available to the user to select for controlling which output format to write the rendered framebuffers out as. Used with Renderer::AddOutputImageFormatSubType to create a complete output image format description.

Note:: This function should only be called from the renderer's cb_Renderer_Init Init callback. In any other callback it has no effect.

Parameters:

in_strName	The name of the format as shown to the user.
in_strExtension	The format's extension.

Returns:: CStatus::OK Image format definition begin accepted.; CStatus::AccessDenied Not in initialization mode.

CStatus GetOutputImageFormats	(	CStringArray &	out_names,
		CStringArray &	out_extensions
	)

Returns all output image formats registered by this renderer as a pair of equal-sized lists, containing the format name and the associated filename extension. Items at the same index on the two lists should be taken together.

Return values:

out_names	The names of the output image formats.
out_extensions	The filename extensions used for the output iamage formats.

Returns:: CStatus::OK

CStatus AddOutputImageFormatSubType	(	siRenderChannelType	in_eChannelType,
		const CString &	in_strDataType,
		siImageBitDepth	in_eBitDepth
	)

Adds a new sub-type to the image format. The sub-type is based on a render channel type and controls which formats, and sub-types thereof, will be offered to the user based on the render channel type of the render channel on which a framebuffer is based.

Note:: This function should only be called from the renderer's cb_Renderer_Init Init callback. In any other callback it has no effect.

Parameters:

in_eChannelType	Render channel type to associate this image format sub-type with.
in_strDataType	The data type being output from the render channel.
in_eBitDepth	The resolution of each individual component of the data type.

Returns:: CStatus::OK Sub-type successfully added.; CStatus::AccessDenied Not in initialization mode or an output image format has not been added yet.

CStatus GetOutputImageFormatSubTypes	(	const CString &	in_strName,
		CLongArray &	out_channelTypes,
		CStringArray &	out_dataTypes,
		CLongArray &	out_bitDepths
	)

Returns all image format sub-types for a given output image format. Either the format name or its extension can be used to look up the sub-type data. The sub-types are returned as three lists of equal size containing the channel type the sub-type applies to, the data type and the bitdepth the image format can be written out as for the given channel type. Items on each list at the same index should be taken together.

Parameters:

in_strName Either the name or the filename extension of a registered output image format for this renderer.

Return values:

out_channelTypes	The channel types list.
out_dataTypes	The data types list.
out_bitDepths	The resolution of each individual component of the data type.

CStatus AddDefaultChannel	(	const CString &	in_strName,
		siRenderChannelType	in_eChannelType
	)

Adds a new default channel for this renderer. A default channel is a render channel which is automatically filled in by the renderer if it has been added with a framebuffer to a given pass.

Note:: This function should only be called from the renderer's cb_Renderer_Init Init callback. In any other callback it has no effect.

Parameters:

in_strName	The name of the default channel being added.
in_eChannelType	The channel type of the default channel being added.

Returns:: CStatus::OK Default channel successfully added.; CStatus::AccessDenied Not in initialization mode.

CStatus GetDefaultChannels	(	CStringArray &	out_names,
		CLongArray &	out_channelTypes
	)

Returns all default channels registered by this renderer as a pair of equal-sized lists, containing the channel name and the channel type. Items at the same index on the two lists should be taken together.

Return values:

out_names	The names of the default channels.
out_channelTypes	The channel types of the respective default channels.

Returns:: CStatus::OK

CString GetVersionString ( )

Get the renderer's version identifier. The version identifier has no specific format and should only be used to disambiguate different versions of the renderer. This is useful to keep separate the plugin's and the rendering engine's version identifiers.

Note:: If a custom renderer does not support the version query callback, this will return the plugin's major.minor version instead.

Returns:: The renderer's version identifier.

CStatus LockSceneData ( )

Locks the scene data from modification while the render data is being pushed. It is very important that this function be called before any other SDK access function is called, otherwise other running threads could potentially modify the data while the rendering thread is trying to access it.

If the function returns CStatus::Abort the render callback should return with CStatus::Abort to indicate to the render controller that an abort has been successfully received. In that case Renderer::UnlockSceneData should not be called, since the lock has been rejected anyway.

Note:: This function should only be called from the renderer's cb_Renderer_Process Process and cb_Renderer_Cleanup Cleanup callbacks. In any other callback it has no effect.

Returns:: CStatus::OK The scene data is locked.; CStatus::Abort The rendering engine is being aborted and should return immediately.; CStatus::AccessDenied Not rendering.

CStatus UnlockSceneData ( )

Unlocks the scene data after locking. It is important that Renderer::LockSceneData be paired with this function, otherwise the scene database could be left locked after the render process is done, leaving XSI in a locked up state.

Note:: This function should only be called from the renderer's cb_Renderer_Process Process and cb_Renderer_Cleanup Cleanup callbacks. In any other callback it has no effect.

Returns:: CStatus:OK The scene data is now unlocked.; CStatus::AccessDenied Not rendering.

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

xsi_renderer.h

Detailed Description

Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation