Public Member Functions
Renderer Class Reference

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:
Inheritance graph
[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: