An interface to a renderer instance. More...

#include <Riley.h>

Public Member Functions
virtual	~Riley ()

virtual void	Render (RenderViewList const &renderViews, RtParamList const &renderOptions)=0
	Rendering Process APIs. More...

virtual StopResult	RequestUpdate ()=0
	Requests the renderer to stop. More...

virtual StopResult	Stop ()=0
	Requests the renderer to stop. More...

virtual bool	SetRenderSettings (RtParamList const &renderOptions)=0
	Sets the rendering process settings. More...

virtual bool	SetRenderMetadata (CameraId id, RtParamList const &metadata)=0
	Sets metadata associated with a given riley entity. More...

virtual bool	SetRenderMetadata (GeometryPrototypeId groupId, GeometryInstanceId id, RtParamList const &metadata)=0

virtual bool	SetRenderMetadata (GeometryPrototypeId id, RtParamList const &metadata)=0

virtual bool	SetRenderMetadata (MaterialId id, RtParamList const &metadata)=0

virtual bool	SetRenderMetadata (DisplacementId id, RtParamList const &metadata)=0

virtual bool	SetRenderMetadata (IntegratorId id, RtParamList const &metadata)=0

virtual bool	SetRenderMetadata (LightInstanceId id, RtParamList const &metadata)=0

virtual bool	SetRenderMetadata (LightShaderId id, RtParamList const &metadata)=0

virtual bool	SetRenderMetadata (CoordinateSystemId id, RtParamList const &metadata)=0

virtual bool	SetRenderMetadata (RenderOutputId id, RtParamList const &metadata)=0

virtual bool	SetRenderMetadata (RenderTargetId id, RtParamList const &metadata)=0

virtual bool	SetRenderMetadata (DisplayId id, RtParamList const &metadata)=0

virtual void	SetOptions (RtParamList const &sceneOptions)=0
	Scene Manipulation APIs. More...

virtual void	InvalidateTexture (RtUString const filename)=0
	Indicates that a texture file has been modified, and should be flushed from the texture cache. More...

virtual RenderOutputId	CreateRenderOutput (UserId userId, RtUString name, RenderOutputType type, RtUString source, RtUString accumulationRule, RtUString filter, FilterSize const &filterSize, float relativePixelVariance, RtParamList const &params)=0
	Creates a render output. More...

virtual RenderOutputResult	ModifyRenderOutput (RenderOutputId renderOutput, RtUString const name, RenderOutputType const type, RtUString const source, RtUString const accumulationRule, RtUString const filter, FilterSize const filterSize, float const relativePixelVariance, RtParamList const params)=0
	Modifies attributes of a render output. More...

virtual RenderOutputResult	DeleteRenderOutput (RenderOutputId renderOutput)=0
	Deletes a render output. More...

virtual RenderTargetId	CreateRenderTarget (UserId userId, RenderOutputList const &renderOutputs, Extent const &extent, RtUString filterMode, float pixelVariance, RtParamList const &params)=0
	Creates a render target containing storage for all of the given render outputs. More...

virtual RenderTargetResult	ModifyRenderTarget (RenderTargetId renderTarget, RenderOutputList const renderOutputs, Extent const extent, RtUString const filterMode, float const pixelVariance, RtParamList const *params)=0
	Modifies attributes of a render target. More...

virtual RenderTargetResult	DeleteRenderTarget (RenderTargetId renderTarget)=0
	Deletes a render target and frees its storage. More...

virtual DisplayId	CreateDisplay (UserId userId, RenderTargetId renderTarget, RtUString name, RtUString driver, RenderOutputList const &renderOutputs, RtParamList const &driverParams)=0
	Creates a display and attach it to a render target. More...

virtual DisplayResult	ModifyDisplay (DisplayId display, RenderTargetId const renderTarget, RtUString const name, RtUString const driver, RenderOutputList const renderOutputs, RtParamList const *driverParams)=0
	Modifies attributes of a display. More...

virtual DisplayResult	DeleteDisplay (DisplayId display)=0
	Closes a display and detach it from its render target. More...

virtual RenderViewId	CreateRenderView (UserId userId, RenderTargetId renderTargetId, CameraId cameraId, IntegratorId integratorId, DisplayFilterList const &displayFilters, SampleFilterList const &sampleFilters, RtParamList const &params)=0
	Creates a render view. More...

virtual RenderViewResult	ModifyRenderView (RenderViewId renderViewId, RenderTargetId const renderTargetId, CameraId const cameraId, IntegratorId const integratorId, DisplayFilterList const displayFilters, SampleFilterList const sampleFilters, RtParamList const params)=0
	Modifies attributes of a render view. More...

virtual RenderViewResult	DeleteRenderView (RenderViewId renderViewId)=0
	Deletes a render view. More...

virtual DisplayFilterId	CreateDisplayFilter (UserId userId, ShadingNetwork const &displayFilter, RtParamList const &attributes)=0
	Creates a display filter from a shading network. More...

virtual DisplayFilterResult	ModifyDisplayFilter (DisplayFilterId displayFilterId, ShadingNetwork const displayFilter, RtParamList const attributes)=0
	Modifies a display filter. More...

virtual DisplayFilterResult	DeleteDisplayFilter (DisplayFilterId displayFilterId)=0
	Deletes the specified display filter. More...

virtual SampleFilterId	CreateSampleFilter (UserId userId, ShadingNetwork const &sampleFilter, RtParamList const &attributes)=0
	Creates a sample filter from a shading network. More...

virtual SampleFilterResult	ModifySampleFilter (SampleFilterId sampleFilterId, ShadingNetwork const sampleFilter, RtParamList const attributes)=0
	Modifies a sample filter. More...

virtual SampleFilterResult	DeleteSampleFilter (SampleFilterId sampleFilterId)=0
	Deletes the specified sample filter. More...

virtual CameraId	CreateCamera (UserId userId, RtUString name, ShadingNode const &projection, Transform const &xform, RtParamList const &properties)=0
	Creates a named camera from a projection shader, transform and list of properties. More...

virtual CameraResult	ModifyCamera (CameraId cameraId, ShadingNode const projection, Transform const xform, RtParamList const *properties)=0
	Sets a new projection shader, transform and list of camera properties for the given camera. More...

virtual void	DeleteCamera (CameraId cameraId)=0
	Deletes the specified camera. More...

virtual ClippingPlaneId	CreateClippingPlane (Transform const &xform, RtParamList const &params)=0

virtual ClippingPlaneResult	ModifyClippingPlane (ClippingPlaneId clippingPlaneId, Transform const xform, RtParamList const params)=0

virtual ClippingPlaneResult	DeleteClippingPlane (ClippingPlaneId clippingPlaneId)=0

virtual void	SetDefaultDicingCamera (CameraId cameraId)=0
	Sets the specified camera as active. More...

virtual IntegratorId	CreateIntegrator (UserId userId, ShadingNode const &integratorNode)=0
	Creates an integrator from an integrator shading node. More...

virtual IntegratorResult	ModifyIntegrator (IntegratorId integratorId, ShadingNode const *integratorNode)=0
	Modifies an integrator. More...

virtual IntegratorResult	DeleteIntegrator (IntegratorId integratorId)=0
	Deletes the specified integrator. More...

virtual CoordinateSystemId	CreateCoordinateSystem (UserId userId, Transform const &xform, RtParamList const &attributes)=0
	Creates a coordinate system from a transform and a set of attributes. More...

virtual CoordinateSystemResult	ModifyCoordinateSystem (CoordinateSystemId coordsysId, Transform const xform, RtParamList const attributes)=0
	Creates a coordinate system from a transform and a set of attributes. More...

virtual void	DeleteCoordinateSystem (CoordinateSystemId coordsysId)=0
	Deletes the specified coordinate system. More...

virtual DisplacementId	CreateDisplacement (UserId userId, ShadingNetwork const &displacement, RtParamList const &attributes)=0
	Creates a displacement from a shading network. More...

virtual DisplacementResult	ModifyDisplacement (DisplacementId displacementId, ShadingNetwork const displacement, RtParamList const attributes)=0
	Modifies a displacement. More...

virtual void	DeleteDisplacement (DisplacementId displacementId)=0
	Deletes the specified displacement. More...

virtual LightShaderId	CreateLightShader (UserId userId, ShadingNetwork const &light, ShadingNetwork const &lightFilter)=0
	Creates a light shader. More...

virtual LightShaderResult	ModifyLightShader (LightShaderId lightShaderId, ShadingNetwork const light, ShadingNetwork const lightFilter)=0
	Modifies a light shader. More...

virtual void	DeleteLightShader (LightShaderId lightShaderId)=0
	Deletes the specified light shader. More...

virtual MaterialId	CreateMaterial (UserId userId, ShadingNetwork const &bxdf, RtParamList const &attributes)=0
	Creates a material from a list of shading nodes. More...

virtual MaterialResult	ModifyMaterial (MaterialId materialId, ShadingNetwork const bxdf, RtParamList const attributes)=0
	Modifies a material. More...

virtual void	DeleteMaterial (MaterialId materialId)=0
	Deletes the specified material. More...

virtual GeometryPrototypeId	CreateGeometryPrototype (UserId userId, RtUString type, DisplacementId displacementId, RtPrimVarList const &primvars)=0
	Creates a geometry prototype. More...

virtual GeometryPrototypeResult	ModifyGeometryPrototype (RtUString type, GeometryPrototypeId geoPrototypeId, DisplacementId const displacementId, RtPrimVarList const primvars)=0
	Modifies a geometry prototype. More...

virtual void	DeleteGeometryPrototype (GeometryPrototypeId geoPrototypeId)=0
	Deletes the specified geometry prototype. More...

virtual GeometryInstanceId	CreateGeometryInstance (UserId userId, GeometryPrototypeId groupPrototypeId, GeometryPrototypeId geoPrototypeId, MaterialId materialId, CoordinateSystemList const &coordsysList, Transform const &xform, RtParamList const &attributes)=0
	Creates a new instance of a geometry prototype. More...

virtual GeometryInstanceResult	ModifyGeometryInstance (GeometryPrototypeId groupPrototypeId, GeometryInstanceId instanceId, MaterialId const materialId, CoordinateSystemList const coordsysList, Transform const xform, RtParamList const attributes)=0
	Modifies properties on the provided geometry instance. More...

virtual void	DeleteGeometryInstance (GeometryPrototypeId groupPrototypeId, GeometryInstanceId instanceId)=0
	Deletes the specified geometry instance. More...

virtual LightInstanceId	CreateLightInstance (UserId userId, GeometryPrototypeId groupPrototypeId, GeometryPrototypeId geoPrototypeId, MaterialId materialId, LightShaderId lightShaderId, CoordinateSystemList const &coordsysList, Transform const &xform, RtParamList const &attributes)=0
	Creates a new instance of a geometric light. More...

virtual LightInstanceResult	ModifyLightInstance (GeometryPrototypeId groupPrototypeId, LightInstanceId lightInstanceId, MaterialId const materialId, LightShaderId const lightShaderId, CoordinateSystemList const coordsysList, Transform const xform, RtParamList const *attributes)=0
	Modifies properties on the provided instance of a geometric light. More...

virtual void	DeleteLightInstance (GeometryPrototypeId groupPrototypeId, LightInstanceId lightInstanceId)=0
	Deletes the specified instance of a geometric light. More...

virtual void	CreateGeometryInstances (GeometryInstanceCreateList const &instances, GeometryInstanceIdList &ids)=0
	Creates new instances of a geometry prototype. More...

virtual void	ModifyGeometryInstances (GeometryInstanceModifyList const &instances, GeometryInstanceResultList &results)=0
	Modifies instances of a geometry prototype. More...

virtual void	DeleteGeometryInstances (GeometryInstanceDeleteList const &instances)=0
	Deletes the specified geometry instances. More...

virtual void	CreateLightInstances (LightInstanceCreateList const &instances, LightInstanceIdList &ids)=0
	Creates new instances of a geometric light. More...

virtual void	ModifyLightInstances (LightInstanceModifyList const &instances, LightInstanceResultList &results)=0
	Modifies instances of a geometric light. More...

virtual void	DeleteLightInstances (LightInstanceDeleteList const &instances)=0
	Deletes the specified geometric light instances. More...

Detailed Description

An interface to a renderer instance.

The APIs allow callers to configure a physically based renderer, and create / modify / delete rendering entities.

Constructor & Destructor Documentation

virtual Riley::~Riley ( )

inlinevirtual

Member Function Documentation

virtual CameraId Riley::CreateCamera	(	UserId	userId,
		RtUString	name,
		ShadingNode const &	projection,
		Transform const &	xform,
		RtParamList const &	properties
	)

pure virtual

Creates a named camera from a projection shader, transform and list of properties.

Parameters

[in]	userId	External user-specified id to be passed through the renderer without use or modification.
[in]	name	The name of the camera. Camera names currently have to be unique across all cameras. Attempting to create a camera name that is already in use is undefined behavior.
[in]	projection	The projection shader for the camera. The projection shader will be called to modify camera rays when they are created for path tracing.
[in]	xform	The camera to world transform.
[in]	properties	The camera model description. Mandatory: Optional: 'nearClip' (float): near clipping distance 'farClip' (float): near clipping distance Rix::k_focusregion (float): Rix::k_dofaspect (float): dof aspect ratio 'apertureNSides' (int): 'apertureAngle' (float): 'apertureRoundness' (float): 'apertureDensity' (float): 'shutterOpenTime' (float): beginning of normalized shutter interval 'shutterCloseTime' (float): end of normalized shutter interval Rix::k_shutteropening (float[8] [c1 c2 d1 d2 e1 e2 f1 f2): additional control points

Returns: A camera id which can be used to modify and delete the camera.

virtual ClippingPlaneId Riley::CreateClippingPlane	(	Transform const &	xform,
		RtParamList const &	params
	)

pure virtual

virtual CoordinateSystemId Riley::CreateCoordinateSystem	(	UserId	userId,
		Transform const &	xform,
		RtParamList const &	attributes
	)

pure virtual

Creates a coordinate system from a transform and a set of attributes.

Parameters

[in]	userId	External user-specified id to be passed through the renderer without use or modification.
[in]	xform	The transform associated with the coordinate system.
[in]	attributes	The "name" attribute is used to identify this coordinate system in later lookups such as shading.

Returns: A coordinate system id which can be used to modify and delete the coordinate system.

virtual DisplacementId Riley::CreateDisplacement	(	UserId	userId,
		ShadingNetwork const &	displacement,
		RtParamList const &	attributes
	)

pure virtual

Creates a displacement from a shading network.

Parameters

[in]	userId	External user-specified id to be passed through the renderer without use or modification.
[in]	displacement	A displacement shading network.

Returns: A displacement id which can be used to modify and delete the displacement.

virtual DisplayId Riley::CreateDisplay	(	UserId	userId,
		RenderTargetId	renderTarget,
		RtUString	name,
		RtUString	driver,
		RenderOutputList const &	renderOutputs,
		RtParamList const &	driverParams
	)

pure virtual

Creates a display and attach it to a render target.

Opens a connection to the display driver.

Parameters

[in]	userId	External user-specified id to be passed through the renderer without use or modification.
[in]	renderTarget	The render target to which the display will be attached.
[in]	name	The name of the display.
[in]	driver	The name of the display driver that will consume the render outputs.
[in]	renderOutputs	The ids of the outputs of a render target the display will consume. The ids are not required to be in the same order as the outputs on the RenderTarget. If the id list is empty, all outputs will be consumed.
[in]	driverParams	Parameters passed to the display driver.

virtual DisplayFilterId Riley::CreateDisplayFilter	(	UserId	userId,
		ShadingNetwork const &	displayFilter,
		RtParamList const &	attributes
	)

pure virtual

Creates a display filter from a shading network.

Parameters

[in]	userId	External user-specified id to be passed through the renderer without use or modification.
[in]	displayFilter	A display filter shading network.
[in]	attributes	Attributes associated with the shading network.

Returns: A display filter id which can be used to modify and delete the filter.

virtual GeometryInstanceId Riley::CreateGeometryInstance	(	UserId	userId,
		GeometryPrototypeId	groupPrototypeId,
		GeometryPrototypeId	geoPrototypeId,
		MaterialId	materialId,
		CoordinateSystemList const &	coordsysList,
		Transform const &	xform,
		RtParamList const &	attributes
	)

pure virtual

Creates a new instance of a geometry prototype.

Parameters

[in]	userId	External user-specified id to be passed through the renderer without use or modification.
[in]	groupPrototypeId	Identifies the geometry prototype group to which the instance will be added. May be GeometryPrototypeId::k_InvalidId, signifying the instance will belong to no group.
[in]	geoPrototypeId	The geometry prototype that will be instantiated.
[in]	materialId	The material to be assigned to the geometry instance.
[in]	coordsysList
[in]	xform	The object to world transform for the instance.
[in]	attributes	The attribute set for the geometry instance.

Returns: A geometry instance id which can be used to modify and delete the geometry instance.

virtual void Riley::CreateGeometryInstances	(	GeometryInstanceCreateList const &	instances,
		GeometryInstanceIdList &	ids
	)

pure virtual

Creates new instances of a geometry prototype.

The caller is responsible for allocating the arrays for both the input instances array as well as the output ids array prior to invoking this method, and the caller is also responsible for freeing any memory that they allocated. The caller should ensure that the same DSO/DLL that allocates the memory also frees the buffers (since different malloc or other allocators may be in place in different plugins). This routine will verify that the input and output array sizes are equal, or else report an error without performing any work.

Parameters

[in]	instances	Information about the batch of instances to be created. See the `GeometryInstanceCreateData` struct documentation for additional details about each input field.
[out]	ids	The geometry instance ids which can be used to modify and delete the geometry instances. The caller is responsible for allocating and freeing all memory for both the input and output parameters to this method in the same plugin. If the size of `ids` does not match the size of `instances` an error is reported and no instances are created.

virtual GeometryPrototypeId Riley::CreateGeometryPrototype	(	UserId	userId,
		RtUString	type,
		DisplacementId	displacementId,
		RtPrimVarList const &	primvars
	)

pure virtual

Creates a geometry prototype.

Parameters

[in]	userId	External user-specified id to be passed through the renderer without use or modification.
[in]	type	The type of geometry to create.
[in]	displacementId	Specifies a displacement to be assigned to the geometry prototype. May be `DisplacementId::k_InvalidId`, signifying no displacement.
[in]	primvars	A complete description of the primitive variables for the geometry prototype.

Returns: A geometry prototype id which can be used to modify and delete the geometry prototype.

virtual IntegratorId Riley::CreateIntegrator	(	UserId	userId,
		ShadingNode const &	integratorNode
	)

pure virtual

Creates an integrator from an integrator shading node.

Parameters

[in]	userId	External user-specified id to be passed through the renderer without use or modification.
[in]	integratorNode	A shading node which must be of type k_Integrator.

Returns: An integrator id.

virtual LightInstanceId Riley::CreateLightInstance	(	UserId	userId,
		GeometryPrototypeId	groupPrototypeId,
		GeometryPrototypeId	geoPrototypeId,
		MaterialId	materialId,
		LightShaderId	lightShaderId,
		CoordinateSystemList const &	coordsysList,
		Transform const &	xform,
		RtParamList const &	attributes
	)

pure virtual

Creates a new instance of a geometric light.

Parameters

[in]	userId	External user-specified id to be passed through the renderer without use or modification.
[in]	groupPrototypeId	Identifies the geometry prototype group to which the instance will be added. May be GeometryPrototypeId::k_InvalidId, signifying the instance will belong to no group.
[in]	geoPrototypeId	The geometry prototype that will be instantiated. This must be a handle returned from `CreateGeometryPrototype()`.
[in]	materialId	The material to be assigned to the geometry instance.
[in]	lightShaderId	The light shader to be assigned to the geometry instance.
[in]	coordsysList
[in]	xform	The object to world transform for the instance.
[in]	attributes	The attribute set for the geometry instance.

Returns: A light instance id which can be used to modify and delete the light instance.

virtual void Riley::CreateLightInstances	(	LightInstanceCreateList const &	instances,
		LightInstanceIdList &	ids
	)

pure virtual

Creates new instances of a geometric light.

The caller is responsible for allocating the arrays for both the input instances array as well as the output ids array prior to invoking this method, and the caller is also responsible for freeing any memory that they allocated. The caller should ensure that the same DSO/DLL that allocates the memory also frees the buffers (since different malloc or other allocators may be in place in different plugins). This routine will verify that the input and output array sizes are equal, or else report an error without performing any work.

Parameters

[in]	instances	Information about the batch of instances to be created. See the `LightInstanceCreateData` struct documentation for additional details about each input field.
[out]	ids	The light instance ids which can be used to modify and delete the light instances. The caller is responsible for allocating and freeing all memory for both the input and output parameters to this method in the same plugin. If the size of `ids` does not match the size of `instances` an error is reported and no instances are created.

virtual LightShaderId Riley::CreateLightShader	(	UserId	userId,
		ShadingNetwork const &	light,
		ShadingNetwork const &	lightFilter
	)

pure virtual

Creates a light shader.

Parameters

[in]	userId	External user-specified id to be passed through the renderer without use or modification.
[in]	light	A light shading network.
[in]	lightFilter	A light filter shading network.

Returns: A light shader id which can be used to modify and delete the light shader.

virtual MaterialId Riley::CreateMaterial	(	UserId	userId,
		ShadingNetwork const &	bxdf,
		RtParamList const &	attributes
	)

pure virtual

Creates a material from a list of shading nodes.

Parameters

[in]	userId	External user-specified id to be passed through the renderer without use or modification.
[in]	bxdf	A bxdf shading network. Additionally, if the (network's) last bxdf node's paramlist contains the parameter `k_materialid`, the following will happen: the first time such a case is encountered, the returned riley::MaterialId will be stored in a global map, associated with the materialId string parameter any other time, the entire material description will be ignored, and CreateMaterial will return the corresponding riley::MaterialId stored in the map

Returns: A material id which can be used to modify and delete the material.

virtual RenderOutputId Riley::CreateRenderOutput	(	UserId	userId,
		RtUString	name,
		RenderOutputType	type,
		RtUString	source,
		RtUString	accumulationRule,
		RtUString	filter,
		FilterSize const &	filterSize,
		float	relativePixelVariance,
		RtParamList const &	params
	)

pure virtual

Creates a render output.

Describes the data format for an output of a render.

Parameters

[in]	userId	External user-specified id to be passed through the renderer without use or modification.
[in]	name	The name of the output.
[in]	type	The data type of the output.
[in]	source	The source of the output.
[in]	accumulationRule	supported rules: {"filter", "average", "min", "max", "zmin", "zmax", "sum", "variance", "mse", "even", "odd"} If set to "filter" the pixel filter function defined by "filter" is used.
[in]	filter	supported filters: {Rix::k_gaussian, Rix::k_box, Rix::k_triangle, Rix::k_catmullrom, Rix::k_separablecatmullrom, Rix::k_blackmanharris, Rix::k_mitchell, Rix::k_sinc, Rix::k_bessel, Rix::k_disk, Rix::k_lanczos}
[in]	filterSize	Filter size in pixels.

If the "filterMode" of the render target is set to "importance", all outputs of the render target with a "filter" accumulation rule will use the filter of the first render output provided to the render target.

Parameters

[in]	relativePixelVariance
[in]	params	Optional parameters. remap: float[3] (may be removed soon): shadowthreshold: float (threshold passed to PxrShadowDisplayFilter) filedatatype: string (recommendation for the output type (float/half) when written to a file)

virtual RenderTargetId Riley::CreateRenderTarget	(	UserId	userId,
		RenderOutputList const &	renderOutputs,
		Extent const &	extent,
		RtUString	filterMode,
		float	pixelVariance,
		RtParamList const &	params
	)

pure virtual

Creates a render target containing storage for all of the given render outputs.

Parameters

[in]	userId	External user-specified id to be passed through the renderer without use or modification.
[in]	renderOutputs	The render outputs used by the render target.
[in]	extent	Width, height, and depth of the outputs. 2D Images have 0 depth.
[in]	filterMode	{"importance", "weighted"}
[in]	pixelVariance	Pixel variance.
[in]	params	Optional parameters.

virtual RenderViewId Riley::CreateRenderView	(	UserId	userId,
		RenderTargetId	renderTargetId,
		CameraId	cameraId,
		IntegratorId	integratorId,
		DisplayFilterList const &	displayFilters,
		SampleFilterList const &	sampleFilters,
		RtParamList const &	params
	)

pure virtual

Creates a render view.

The render view binds together several entities that can then be passed to Render() to generate a picture.

Parameters

[in]	userId	External user-specified id to be passed through the renderer without use or modification.
[in]	renderTargetId	The render target to bind to the render view.
[in]	cameraId	The camera to bind to the render view. Current Riley implementations require a unique cameraId to be used across the render views.
[in]	integratorId	The integrator to bind to the render view.
[in]	displayFilters	A list of display filters to be bound to the render view. This parameter is currently ignored.
[in]	sampleFilters	A list of sample filters to be bound to the render view. This parameter is currently ignored.

Returns: A render view id which can be used to modify and delete the render view.

virtual SampleFilterId Riley::CreateSampleFilter	(	UserId	userId,
		ShadingNetwork const &	sampleFilter,
		RtParamList const &	attributes
	)

pure virtual

Creates a sample filter from a shading network.

Parameters

[in]	userId	External user-specified id to be passed through the renderer without use or modification.
[in]	sampleFilter	A sample filter shading network.
[in]	attributes	Attributes associated with the shading network.

Returns: A sample filter id which can be used to modify and delete the filter.

virtual void Riley::DeleteCamera ( CameraId cameraId)

pure virtual

Deletes the specified camera.

Parameters

[in] cameraId Identifies the camera to delete.

virtual ClippingPlaneResult Riley::DeleteClippingPlane ( ClippingPlaneId clippingPlaneId)

pure virtual

virtual void Riley::DeleteCoordinateSystem ( CoordinateSystemId coordsysId)

pure virtual

Deletes the specified coordinate system.

Parameters

[in] coordsysId Identifies the coordinate system to delete.

virtual void Riley::DeleteDisplacement ( DisplacementId displacementId)

pure virtual

Deletes the specified displacement.

Parameters

[in] displacementId Identifies the displacement to delete.

virtual DisplayResult Riley::DeleteDisplay ( DisplayId display)

pure virtual

Closes a display and detach it from its render target.

Closes the connection to the display driver. The id is no longer valid.

Parameters

[in] display The display to close.

virtual DisplayFilterResult Riley::DeleteDisplayFilter ( DisplayFilterId displayFilterId)

pure virtual

Deletes the specified display filter.

Parameters

[in] displayFilterId Identifies the display filter to delete.

virtual void Riley::DeleteGeometryInstance	(	GeometryPrototypeId	groupPrototypeId,
		GeometryInstanceId	instanceId
	)

pure virtual

Deletes the specified geometry instance.

Parameters

[in]	groupPrototypeId	Identifies the geometry prototype group to which the instance currently belongs. May be GeometryPrototypeId::k_InvalidId, signifying the instance belongs to no group.
[in]	instanceId	Identifies the geometry instance to delete.

virtual void Riley::DeleteGeometryInstances ( GeometryInstanceDeleteList const & instances)

pure virtual

Deletes the specified geometry instances.

The caller is responsible for allocating the array for the input instances array prior to invoking this method, and the caller is also responsible for freeing any memory that they allocated. The caller should ensure that the same DSO/DLL that allocates the memory also frees the buffer (since different malloc or other allocators may be in place in different plugins).

Parameters

[in] instances Information about the batch of instances to be deleted. See the GeometryInstanceDeleteData struct documentation for additional details about each input field.

virtual void Riley::DeleteGeometryPrototype ( GeometryPrototypeId geoPrototypeId)

pure virtual

Deletes the specified geometry prototype.

Parameters

[in] geoPrototypeId Identifies the geometry prototype to delete.

virtual IntegratorResult Riley::DeleteIntegrator ( IntegratorId integratorId)

pure virtual

Deletes the specified integrator.

Parameters

[in] integratorId Identifies the integrator to delete.

virtual void Riley::DeleteLightInstance	(	GeometryPrototypeId	groupPrototypeId,
		LightInstanceId	lightInstanceId
	)

pure virtual

Deletes the specified instance of a geometric light.

Parameters

[in]	groupPrototypeId	Identifies the geometry prototype group to which the instance currently belongs. May be GeometryPrototypeId::k_InvalidId, signifying the instance belongs to no group.
[in]	lightInstanceId	Identifies the geometric light instance to delete.

virtual void Riley::DeleteLightInstances ( LightInstanceDeleteList const & instances)

pure virtual

Deletes the specified geometric light instances.

The caller is responsible for allocating the array for the input instances array prior to invoking this method, and the caller is also responsible for freeing any memory that they allocated. The caller should ensure that the same DSO/DLL that allocates the memory also frees the buffer (since different malloc or other allocators may be in place in different plugins).

Parameters

[in] instances Information about the batch of instances to be deleted. See the GeometryInstanceDeleteData struct documentation for additional details about each input field.

virtual void Riley::DeleteLightShader ( LightShaderId lightShaderId)

pure virtual

Deletes the specified light shader.

Parameters

[in] lightShaderId Identifies the light shader to delete. Providing an id that has not been returned from CreateLightShader(), or deleting a light shader that has already been deleted, results in undefined behavior.

virtual void Riley::DeleteMaterial ( MaterialId materialId)

pure virtual

Deletes the specified material.

Parameters

[in] materialId Identifies the material to delete.

virtual RenderOutputResult Riley::DeleteRenderOutput ( RenderOutputId renderOutput)

pure virtual

Deletes a render output.

After this call, the id is no longer valid. A render output may not be deleted if there any render target still using it.

Parameters

[in] renderOutput Render output to delete.

virtual RenderTargetResult Riley::DeleteRenderTarget ( RenderTargetId renderTarget)

pure virtual

Deletes a render target and frees its storage.

After this call, the id is no longer valid. A render target may not be deleted if there are any displays attached to it.

Parameters

[in] renderTarget The render target to delete.

virtual RenderViewResult Riley::DeleteRenderView ( RenderViewId renderViewId)

pure virtual

Deletes a render view.

Parameters

[in] renderViewId The render view to delete.

virtual SampleFilterResult Riley::DeleteSampleFilter ( SampleFilterId sampleFilterId)

pure virtual

Deletes the specified sample filter.

Parameters

[in] sampleFilterId Identifies the sample filter to delete.

virtual void Riley::InvalidateTexture ( RtUString const filename)

pure virtual

Indicates that a texture file has been modified, and should be flushed from the texture cache.

This is considered a scene edit and should not be called while Render() is running.

Parameters

[in] filename The texture file name. This should be an absolute path.

virtual CameraResult Riley::ModifyCamera	(	CameraId	cameraId,
		ShadingNode const *	projection,
		Transform const *	xform,
		RtParamList const *	properties
	)

pure virtual

Sets a new projection shader, transform and list of camera properties for the given camera.

It is possible to pass nullptr for any of the parameter sets and this will apply no modification to the parameter set. That is, ModifyCamera(id, nullptr, nullptr, nullptr) has no side effects.

Parameters

[in]	cameraId	Identifies the camera for which properties will be changed.
[in]	projection	An optional new projection shader for the camera. This parameter is optional but, if provided, will replace the current projection shader bound to the camera.
[in]	xform	An optional camera to world transform that replaces the current camera to world transform.
[in]	properties	An optional argument which if non-null, provides a new camera model description for the camera.

Returns: A CameraResult value indicating success or failure.

virtual ClippingPlaneResult Riley::ModifyClippingPlane	(	ClippingPlaneId	clippingPlaneId,
		Transform const *	xform,
		RtParamList const *	params
	)

pure virtual

virtual CoordinateSystemResult Riley::ModifyCoordinateSystem	(	CoordinateSystemId	coordsysId,
		Transform const *	xform,
		RtParamList const *	attributes
	)

pure virtual

Creates a coordinate system from a transform and a set of attributes.

Parameters

[in]	coordsysId	Identifies the coordinate system to modify.
[in]	xform
[in]	attributes

Returns: A CoordinateSystemResult value indicating success or failure.

virtual DisplacementResult Riley::ModifyDisplacement	(	DisplacementId	displacementId,
		ShadingNetwork const *	displacement,
		RtParamList const *	attributes
	)

pure virtual

Modifies a displacement.

Parameters

[in]	shadingNodes	A displacement shading network.
[in]	displacementId	Identifies the displacement to be modified,.
[in]	displacement	An optional displacement shading network.

Returns: A DisplacementResult value. If k_Error is returned, the displacement was not successfully modified. If k_Success is returned, the displacement was successfully modified. If k_ResendPrimVars is returned, the displacement was successfully modified; in addition, the caller should immediately issue a ModifyGeometryPrototype() for all associated geometry prototypes.

virtual DisplayResult Riley::ModifyDisplay	(	DisplayId	display,
		RenderTargetId const *	renderTarget,
		RtUString const *	name,
		RtUString const *	driver,
		RenderOutputList const *	renderOutputs,
		RtParamList const *	driverParams
	)

pure virtual

Modifies attributes of a display.

Uses the same parameterization as CreateDisplay(). If a parameter is nullptr, it is not modified.

Parameters

[in] display The display to modify.

virtual DisplayFilterResult Riley::ModifyDisplayFilter	(	DisplayFilterId	displayFilterId,
		ShadingNetwork const *	displayFilter,
		RtParamList const *	attributes
	)

pure virtual

Modifies a display filter.

Parameters

[in]	displayFilterId	Identifies the display filter to be modified.
[in]	displayFilter	An optional display filter shading network.
[in]	attributes	Optional attributes associated with the shading network.

Returns: A DisplayFilterResult value. If k_Error is returned, the display filter was not successfully modified. If k_Success is returned, the display filter was successfully modified.

virtual GeometryInstanceResult Riley::ModifyGeometryInstance	(	GeometryPrototypeId	groupPrototypeId,
		GeometryInstanceId	instanceId,
		MaterialId const *	materialId,
		CoordinateSystemList const *	coordsysList,
		Transform const *	xform,
		RtParamList const *	attributes
	)

pure virtual

Modifies properties on the provided geometry instance.

If a null pointer is passed for materialId, coordsys, xform or attributes then that specific property set will remain unmodified. Thus, ModifyGeometryInstance()(groupId, instanceId, nullptr, nullptr, nullptr, nullptr) has no side-effects.

Parameters

[in]	groupPrototypeId	Identifies the geometry prototype group in which the instance currently belongs. May be GeometryPrototypeId::k_InvalidId, signifying the instance belongs to no group.
[in]	instanceId	The geometry instance handle that will be modified.
[in]	materialId	If non-null, specifies a new material to be assigned to the geometry instance.
[in]	coordsysList
[in]	xform	If non-null, assigns a new object to world transform for the instance.
[in]	attributes	If non-null, specifies a new attribute set for the geometry instance. It is expected that if provided, the attributes are a complete description, as it will completely overwrite the existing set of attributes.

Returns: A GeometryInstanceResult value. If k_Error is returned, the instance was not successfully modified. If k_Success is returned, the instance was successfully modified. If k_ResendPrimVars is returned, the instance was successfully modified; in addition, the caller should immediately issue a ModifyGeometryPrototype() for all associated geometry prototypes.

virtual void Riley::ModifyGeometryInstances	(	GeometryInstanceModifyList const &	instances,
		GeometryInstanceResultList &	results
	)

pure virtual

Modifies instances of a geometry prototype.

The caller is responsible for allocating the arrays for both the input instances array as well as the output results array prior to invoking this method, and the caller is also responsible for freeing any memory that they allocated. The caller should ensure that the same DSO/DLL that allocates the memory also frees the buffers (since different malloc or other allocators may be in place in different plugins). This routine will verify that the input and output array sizes are equal, or else report an error without performing any work.

Parameters

[in]	instances	Information about the batch of instances to be modified. See the `GeometryInstanceModifyData` struct documentation for additional details about each input field.
[out]	results	The `GeometryInstanceResult` values for each instance. If `k_Error` is returned, the instance was not successfully modified. If `k_Success` is returned, the instance was successfully modified. If `k_ResendPrimVars` is returned, the instance was successfully modified; in addition, the caller should immediately issue a `ModifyGeometryPrototype()` for all associated geometry prototypes. The caller is responsible for allocating and freeing all memory for both the input and output parameters to this method in the same plugin. If the size of `results` does not match the size of `instances` an error is reported and no instances are modified.

virtual GeometryPrototypeResult Riley::ModifyGeometryPrototype	(	RtUString	type,
		GeometryPrototypeId	geoPrototypeId,
		DisplacementId const *	displacementId,
		RtPrimVarList const *	primvars
	)

pure virtual

Modifies a geometry prototype.

Parameters

[in]	type	The type of the geometry.
[in]	geoPrototypeId	The geometry prototype that will be modified.
[in]	displacementId	If non-null, changes the displacement shader assigned to the geometry prototype. May be `DisplacementId::k_InvalidId`, signifying no displacement.
[in]	primvars	If non-null, specifies a new set of primvars for the geometry prototype. It is expected that if provided, the primvars are a complete description, as it will completely overwrite the existing set of primvars.

Returns: A GeometryPrototypeResult value. If k_Error is returned, the geometry prototype was not successfully modified. If k_Success is returned, the geometry prototype was successfully modified. If k_ResendPrimVars is returned, the geometry prototype properties were successfully modified; in addition, the caller should immediately reissue the ModifyGeometryPrototype() call, and include the full primvars for the prototype.

virtual IntegratorResult Riley::ModifyIntegrator	(	IntegratorId	integratorId,
		ShadingNode const *	integratorNode
	)

pure virtual

Modifies an integrator.

Parameters

[in]	integratorId	Identifies the integrator to be modified.
[in]	integratorNode	A shading node with the same properties as the `integratorNode` parameter to `CreateIntegrator()`.

Returns: A IntegratorResult value. If k_Error is returned, the integrator was not successfully modified. If k_Success is returned, the integrator was successfully modified.

virtual LightInstanceResult Riley::ModifyLightInstance	(	GeometryPrototypeId	groupPrototypeId,
		LightInstanceId	lightInstanceId,
		MaterialId const *	materialId,
		LightShaderId const *	lightShaderId,
		CoordinateSystemList const *	coordsysList,
		Transform const *	xform,
		RtParamList const *	attributes
	)

pure virtual

Modifies properties on the provided instance of a geometric light.

If a null pointer is passed for materialId, lightShaderId, coordsys, xform or attributes then that specific property set will remain unmodified. Thus, ModifyLightInstance()(groupId, lightId, nullptr, nullptr, nullptr, nullptr, nullptr) has no side-effects.

Parameters

[in]	groupPrototypeId	Identifies the geometry prototype group in which the instance currently belongs. May be GeometryPrototypeId::k_InvalidId, signifying the instance belongs to no group.
[in]	lightInstanceId	The geometry light instance handle that will be modified. This must be a handle returned from `CreateLightInstance()`.
[in]	materialId	If non-null, specifies a new material to be assigned to the geometry instance.
[in]	lightShaderId	If non-null, specifies a new light shader to be assigned to the geometry instance.
[in]	coordsysList
[in]	xform	If non-null, assigns a new object to world transform for the instance.
[in]	attributes	If non-null, specifies a new attribute set for the geometry instance. It is expected that if provided, the attributes are a complete description, as it will completely overwrite the existing set of attributes.

Returns: A LightInstanceResult value. If k_Error is returned, the light instance was not successfully modified. If k_Success is returned, the light instance was successfully modified. If k_ResendPrimVars is returned, the light instance was successfully modified; in addition, the caller should immediately issue a ModifyGeometryPrototype() for all associated geometry prototypes.

virtual void Riley::ModifyLightInstances	(	LightInstanceModifyList const &	instances,
		LightInstanceResultList &	results
	)

pure virtual

Modifies instances of a geometric light.

The caller is responsible for allocating the arrays for both the input instances array as well as the output results array prior to invoking this method, and the caller is also responsible for freeing any memory that they allocated. The caller should ensure that the same DSO/DLL that allocates the memory also frees the buffers (since different malloc or other allocators may be in place in different plugins). This routine will verify that the input and output array sizes are equal, or else report an error without performing any work.

Parameters

[in]	instances	Information about the batch of instances to be modified. See the `LightInstanceModifyData` struct documentation for additional details about each input field.
[out]	results	The `LightInstanceResult` values for each instance. If `k_Error` is returned, the light instance was not successfully modified. If `k_Success` is returned, the light instance was successfully modified. If `k_ResendPrimVars` is returned, the light instance was successfully modified; in addition, the caller should immediately issue a `ModifyGeometryPrototype()` for all associated geometry prototypes. The caller is responsible for allocating and freeing all memory for both the input and output parameters to this method in the same plugin. If the size of `results` does not match the size of `instances` an error is reported and no instances are modified.

virtual LightShaderResult Riley::ModifyLightShader	(	LightShaderId	lightShaderId,
		ShadingNetwork const *	light,
		ShadingNetwork const *	lightFilter
	)

pure virtual

Modifies a light shader.

Parameters

[in]	lightShaderId	Identifies the light shader to be modified.
[in]	light	An optional light shading network.
[in]	lightFilter	An optional light filter shading network.

Returns: A LightShaderResult value. If k_Error is returned, the light shader was not successfully modified. If k_Success is returned, the light shader was successfully modified. If k_ResendPrimVars is returned, the light shader was successfully modified; in addition, the caller should immediately issue a ModifyGeometryPrototype() for all associated geometry prototypes.

virtual MaterialResult Riley::ModifyMaterial	(	MaterialId	materialId,
		ShadingNetwork const *	bxdf,
		RtParamList const *	attributes
	)

pure virtual

Modifies a material.

Parameters

[in]	materialId	Identifies the material to be modified.
[in]	bxdf	An optional bxdf shading network.

Returns: A MaterialResult value. If k_Error is returned, the material was not successfully modified. If k_Success is returned, the material was successfully modified. If k_ResendPrimVars is returned, the material was successfully modified; in addition, the caller should immediately issue a ModifyGeometryPrototype() for all associated geometry prototypes.

virtual RenderOutputResult Riley::ModifyRenderOutput	(	RenderOutputId	renderOutput,
		RtUString const *	name,
		RenderOutputType const *	type,
		RtUString const *	source,
		RtUString const *	accumulationRule,
		RtUString const *	filter,
		FilterSize const *	filterSize,
		float const *	relativePixelVariance,
		RtParamList const *	params
	)

pure virtual

Modifies attributes of a render output.

Uses the same parameterization as CreateRenderOutput(). If a parameter is nullptr, it is not modified.

virtual RenderTargetResult Riley::ModifyRenderTarget	(	RenderTargetId	renderTarget,
		RenderOutputList const *	renderOutputs,
		Extent const *	extent,
		RtUString const *	filterMode,
		float const *	pixelVariance,
		RtParamList const *	params
	)

pure virtual

Modifies attributes of a render target.

Uses the same parameterization as CreateRenderTarget(). If a parameter is nullptr, it is not modified.

Parameters

[in] renderTarget The renderTarget to modify.

virtual RenderViewResult Riley::ModifyRenderView	(	RenderViewId	renderViewId,
		RenderTargetId const *	renderTargetId,
		CameraId const *	cameraId,
		IntegratorId const *	integratorId,
		DisplayFilterList const *	displayFilters,
		SampleFilterList const *	sampleFilters,
		RtParamList const *	params
	)

pure virtual

Modifies attributes of a render view.

Uses the same parameterization as CreateRenderView(). If a parameter is nullptr, it is not modified.

Parameters

[in] renderViewId The render view to modify.

virtual SampleFilterResult Riley::ModifySampleFilter	(	SampleFilterId	sampleFilterId,
		ShadingNetwork const *	sampleFilter,
		RtParamList const *	attributes
	)

pure virtual

Modifies a sample filter.

Parameters

[in]	sampleFilterId	Identifies the sample filter to be modified.
[in]	sampleFilter	An optional sample filter shading network.
[in]	attributes	Optional attributes associated with the shading network.

Returns: A SampleFilterResult value. If k_Error is returned, the sample filter was not successfully modified. If k_Success is returned, the sample filter was successfully modified.

virtual void Riley::Render	(	RenderViewList const &	renderViews,
		RtParamList const &	renderOptions
	)

pure virtual

Rendering Process APIs.

The following APIs are used to manipulate a rendering process started by calling Render():

stop the currently running render
modify properties of the currently running render
modify the metadata associated with existing riley entities.

Editing rendering process options and/or entity metadata does not affect the contents of the render outputs (i.e. framebuffer contents).Renders one or more views of a scene. Render() will run to completion unless:

it is stopped by an external signal
the application indicates it would like to edit the scene by calling Stop() (blocking) or RequestUpdate() (non-blocking)
the render call is configured to return after a fixed interval specified in either iterations or time (e.g. checkpointing)

Parameters

[in]

renderOptions

Render options shared by all render views. These options may change for each Render() call. Currently supported:

"renderMode" (string):
- "batch": The render will be optimized for best offline rendering performance.
- "interactive" : The render is expected to be interrupted for edits and will be optimized for interactive responsiveness.

virtual StopResult Riley::RequestUpdate ( )

pure virtual

Requests the renderer to stop.

This call is non-blocking. The Render() call will return at some later time when the renderer is ready to synchronize scene edits.

Returns: riley::StopResult::k_Success if the renderer was rendering riley::StopResult::k_NotRendering otherwise

virtual void Riley::SetDefaultDicingCamera ( CameraId cameraId)

pure virtual

Sets the specified camera as active.

Parameters

[in] cameraId Identifies the default camera to be used for dicing. Providing an id that has not been returned from CreateCamera(), or deleting a camera that has already been deleted, results in undefined behavior.

virtual void Riley::SetOptions ( RtParamList const & sceneOptions)

pure virtual

Scene Manipulation APIs.

The following APIs are used to provide and/or modify the scene description. They can only be called during the editing phase (i.e. when Render() is not running).

Editing the scene description is expected to affect the render outputs.Sets the scene options. These are options that are part of the scene description, and may affect the render outputs. Current Riley implementations require SetOptions() to be the first call made before any other scene manipulation. Additionally, only a small subset of options edits are currently supported.

Parameters

[in] sceneOptions Scene Options.

virtual bool Riley::SetRenderMetadata	(	CameraId	id,
		RtParamList const &	metadata
	)

pure virtual

Sets metadata associated with a given riley entity.

This metadata shouldn't affect the render outputs, and can be modified during a render.

Returns: true If the render process edits are supported. false If the render process edits are not supported.

virtual bool Riley::SetRenderMetadata	(	GeometryPrototypeId	groupId,
		GeometryInstanceId	id,
		RtParamList const &	metadata
	)

pure virtual

virtual bool Riley::SetRenderMetadata	(	GeometryPrototypeId	id,
		RtParamList const &	metadata
	)

pure virtual

virtual bool Riley::SetRenderMetadata	(	MaterialId	id,
		RtParamList const &	metadata
	)

pure virtual

virtual bool Riley::SetRenderMetadata	(	DisplacementId	id,
		RtParamList const &	metadata
	)

pure virtual

virtual bool Riley::SetRenderMetadata	(	IntegratorId	id,
		RtParamList const &	metadata
	)

pure virtual

virtual bool Riley::SetRenderMetadata	(	LightInstanceId	id,
		RtParamList const &	metadata
	)

pure virtual

virtual bool Riley::SetRenderMetadata	(	LightShaderId	id,
		RtParamList const &	metadata
	)

pure virtual

virtual bool Riley::SetRenderMetadata	(	CoordinateSystemId	id,
		RtParamList const &	metadata
	)

pure virtual

virtual bool Riley::SetRenderMetadata	(	RenderOutputId	id,
		RtParamList const &	metadata
	)

pure virtual

virtual bool Riley::SetRenderMetadata	(	RenderTargetId	id,
		RtParamList const &	metadata
	)

pure virtual

virtual bool Riley::SetRenderMetadata	(	DisplayId	id,
		RtParamList const &	metadata
	)

pure virtual

virtual bool Riley::SetRenderSettings ( RtParamList const & renderOptions)

pure virtual

Sets the rendering process settings.

These are settings that only affects the current rendering process. They shouldn't affect the render outputs, and can be modified during a render.

Returns: true If the render process setting edits are supported. false If the render process setting edits are not supported.

virtual StopResult Riley::Stop ( )

pure virtual

Requests the renderer to stop.

This call is blocking, and returns after the Render() call has returned.

Returns: riley::StopResult::k_Success if the renderer was rendering riley::StopResult::k_NotRendering otherwise

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

Riley.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation