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