Radeon ProRender

rprContextCreateInstance

Creates a new instance of an rpr_shape (aka mesh) object.

A shape can be either a mesh or an instance. An instance is intended to re-use geometry with different transforms and shader settings. You could, therefore, create a single leaf mesh and then generate 1000 instances of that leaf with varying transforms and shaders. In this case only one copy of the geometry would be created (instead of 1001).

rpr_status rprContextCreateInstance( rpr_context context,
  rpr_shape shape,
  rpr_shape * out_instance);

Parameters

Parameter Description
context The context to create an instance for.
shape The parent shape to be instantiated.
out_instance A pointer to the created instance object.

Notes

Although instances are a good way to economise on storage requirements, this is not the only benefit they convey. Instances can also help to significantly improve performance at run time.

Like most ray tracers, AMD Radeon ProRender preprocesses a scene in order to build an acceleration structure before rendering begins. The more geometry involved, the longer it takes to build this structure and the longer it will take to traverse at each render pass.

Using instances allows AMD Radeon ProRender to streamline its acceleration structure. The savings, particularly on large, geometry-heavy scenes can be significant.

Output

A pointer to an instance object.

Return

Returns RPR_SUCCESS in case of success, or RPR_ERROR code if a problem was encountered.

To learn how to handle errors in AMD Radeon ProRender SDK, see Error Handling.

Errors

Possible error codes:

  • RPR_ERROR_OUT_OF_SYSTEM_MEMORY
  • RPR_ERROR_OUT_OF_VIDEO_MEMORY
  • RPR_ERROR_INVALID_PARAMETER