NVIDIA OptiX 6.0 API nvidia_logo_transpbg.gif Up
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
GroupNode functions

Functions

RTresult RTAPI rtGroupCreate (RTcontext context, RTgroup *group)
 
RTresult RTAPI rtGroupDestroy (RTgroup group)
 
RTresult RTAPI rtGroupValidate (RTgroup group)
 
RTresult RTAPI rtGroupGetContext (RTgroup group, RTcontext *context)
 
RTresult RTAPI rtGroupSetAcceleration (RTgroup group, RTacceleration acceleration)
 
RTresult RTAPI rtGroupSetVisibilityMask (RTgroup group, RTvisibilitymask mask)
 
RTresult RTAPI rtGroupGetVisibilityMask (RTgroup group, RTvisibilitymask *mask)
 
RTresult RTAPI rtGroupGetAcceleration (RTgroup group, RTacceleration *acceleration)
 
RTresult RTAPI rtGroupSetChildCount (RTgroup group, unsigned int count)
 
RTresult RTAPI rtGroupGetChildCount (RTgroup group, unsigned int *count)
 
RTresult RTAPI rtGroupSetChild (RTgroup group, unsigned int index, RTobject child)
 
RTresult RTAPI rtGroupGetChild (RTgroup group, unsigned int index, RTobject *child)
 
RTresult RTAPI rtGroupGetChildType (RTgroup group, unsigned int index, RTobjecttype *type)
 

Detailed Description

Functions related to an OptiX Group node.

Function Documentation

RTresult RTAPI rtGroupCreate ( RTcontext  context,
RTgroup group 
)

Creates a new group.

Description

rtGroupCreate creates a new group within a context. context specifies the target context, and should be a value returned by rtContextCreate. Sets *group to the handle of a newly created group within context. Returns RT_ERROR_INVALID_VALUE if group is NULL.

Parameters
[in]contextSpecifies a context within which to create a new group
[out]groupReturns a newly created group

Return values

Relevant return values:

History

rtGroupCreate was introduced in OptiX 1.0.

See also rtGroupDestroy, rtContextCreate

RTresult RTAPI rtGroupDestroy ( RTgroup  group)

Destroys a group node.

Description

rtGroupDestroy removes group from its context and deletes it. group should be a value returned by rtGroupCreate. No child graph nodes are destroyed. After the call, group is no longer a valid handle.

Parameters
[in]groupHandle of the group node to destroy

Return values

Relevant return values:

History

rtGroupDestroy was introduced in OptiX 1.0.

See also rtGroupCreate

RTresult RTAPI rtGroupGetAcceleration ( RTgroup  group,
RTacceleration acceleration 
)

Returns the acceleration structure attached to a group.

Description

rtGroupGetAcceleration returns the acceleration structure attached to a group using rtGroupSetAcceleration. If no acceleration structure has previously been set, *acceleration is set to NULL.

Parameters
[in]groupThe group handle
[out]accelerationThe returned acceleration structure object

Return values

Relevant return values:

History

rtGroupGetAcceleration was introduced in OptiX 1.0.

See also rtGroupSetAcceleration, rtAccelerationCreate

RTresult RTAPI rtGroupGetChild ( RTgroup  group,
unsigned int  index,
RTobject child 
)

Returns a child node of a group.

Description

rtGroupGetChild returns the child object at slot index of the parent group. If no child has been assigned to the given slot, *child is set to NULL. Returns RT_ERROR_INVALID_VALUE if given an invalid child index or NULL pointer.

Parameters
[in]groupThe parent group handle
[in]indexThe index of the child slot to query
[out]childThe returned child object

Return values

Relevant return values:

History

rtGroupGetChild was introduced in OptiX 1.0.

See also rtGroupSetChild, rtGroupSetChildCount, rtGroupGetChildCount, rtGroupGetChildType

RTresult RTAPI rtGroupGetChildCount ( RTgroup  group,
unsigned int *  count 
)

Returns the number of child slots for a group.

Description

rtGroupGetChildCount returns the number of child slots allocated using rtGroupSetChildCount. This includes empty slots which may not yet have actual children assigned by rtGroupSetChild. Returns RT_ERROR_INVALID_VALUE if given a NULL pointer.

Parameters
[in]groupThe parent group handle
[out]countReturned number of child slots

Return values

Relevant return values:

History

rtGroupGetChildCount was introduced in OptiX 1.0.

See also rtGroupSetChild, rtGroupGetChild, rtGroupSetChildCount, rtGroupGetChildType

RTresult RTAPI rtGroupGetChildType ( RTgroup  group,
unsigned int  index,
RTobjecttype type 
)

Get the type of a group child.

Description

rtGroupGetChildType returns the type of the group child at slot index. If no child is associated with the given index, *type is set to RT_OBJECTTYPE_UNKNOWN and RT_ERROR_INVALID_VALUE is returned. Returns RT_ERROR_INVALID_VALUE if given a NULL pointer.

Parameters
[in]groupThe parent group handle
[in]indexThe index of the child slot to query
[out]typeThe returned child type

Return values

Relevant return values:

History

rtGroupGetChildType was introduced in OptiX 1.0.

See also rtGroupSetChild, rtGroupGetChild, rtGroupSetChildCount, rtGroupGetChildCount

RTresult RTAPI rtGroupGetContext ( RTgroup  group,
RTcontext context 
)

Returns the context associated with a group.

Description

rtGroupGetContext queries a group for its associated context. group specifies the group to query, and must be a value returned by rtGroupCreate. Sets *context to the context associated with group.

Parameters
[in]groupSpecifies the group to query
[out]contextReturns the context associated with the group

Return values

Relevant return values:

History

rtGroupGetContext was introduced in OptiX 1.0.

See also rtContextCreate, rtGroupCreate

RTresult RTAPI rtGroupGetVisibilityMask ( RTgroup  group,
RTvisibilitymask mask 
)

Retrieves the visibility mask of a group.

Description See rtGroupSetVisibilityMask for details.

Parameters
[in]groupThe group handle
[out]maskA set of bits for which rays will intersect the group

Return values

Relevant return values:

History

rtGroupGetVisibilityMask was introduced in OptiX 6.0.

See also rtGeometryGroupGetVisibilityMask, rtGroupSetVisibilityMask, rtTrace

RTresult RTAPI rtGroupSetAcceleration ( RTgroup  group,
RTacceleration  acceleration 
)

Set the acceleration structure for a group.

Description

rtGroupSetAcceleration attaches an acceleration structure to a group. The acceleration structure must have been previously created using rtAccelerationCreate. Every group is required to have an acceleration structure assigned in order to pass validation. The acceleration structure will be built over the children of the group. For example, if an acceleration structure is attached to a group that has a selector, a geometry group, and a transform child, the acceleration structure will be built over the bounding volumes of these three objects.

Note that it is legal to attach a single RTacceleration object to multiple groups, as long as the underlying bounds of the children are the same. For example, if another group has three children which are known to have the same bounding volumes as the ones in the example above, the two groups can share an acceleration structure, thus saving build time. This is true even if the details of the children, such as the actual type of a node or its geometry content, differ from the first set of group children. All that is required is for a child node at a given index to have the same bounds as the other group's child node at the same index.

Sharing an acceleration structure this way corresponds to attaching an acceleration structure to multiple geometry groups at lower graph levels using rtGeometryGroupSetAcceleration.

Parameters
[in]groupThe group handle
[in]accelerationThe acceleration structure to attach to the group

Return values

Relevant return values:

History

rtGroupSetAcceleration was introduced in OptiX 1.0.

See also rtGroupGetAcceleration, rtAccelerationCreate, rtGeometryGroupSetAcceleration

RTresult RTAPI rtGroupSetChild ( RTgroup  group,
unsigned int  index,
RTobject  child 
)

Attaches a child node to a group.

Description

Attaches a new child node child to the parent node group. index specifies the number of the slot where the child node gets attached. A sufficient number of slots must be allocated using rtGroupSetChildCount. Legal child node types are RTgroup, RTselector, RTgeometrygroup, and RTtransform.

Parameters
[in]groupThe parent group handle
[in]indexThe index in the parent's child slot array
[in]childThe child node to be attached. Can be of type {RTgroup, RTselector, RTgeometrygroup, RTtransform}

Return values

Relevant return values:

History

rtGroupSetChild was introduced in OptiX 1.0.

See also rtGroupSetChildCount, rtGroupGetChildCount, rtGroupGetChild, rtGroupGetChildType

RTresult RTAPI rtGroupSetChildCount ( RTgroup  group,
unsigned int  count 
)

Sets the number of child nodes to be attached to the group.

Description

rtGroupSetChildCount specifies the number of child slots in this group. Potentially existing links to children at indices greater than count-1 are removed. If the call increases the number of slots, the newly created slots are empty and need to be filled using rtGroupSetChild before validation.

Parameters
[in]groupThe parent group handle
[in]countNumber of child slots to allocate for the group

Return values

Relevant return values:

History

rtGroupSetChildCount was introduced in OptiX 1.0.

See also rtGroupGetChild, rtGroupGetChildCount, rtGroupGetChildType, rtGroupSetChild

RTresult RTAPI rtGroupSetVisibilityMask ( RTgroup  group,
RTvisibilitymask  mask 
)

Sets the visibility mask for a group.

Description Geometry is intersected by rays if the ray's RTvisibilitymask shares at least one bit with the geometry's mask. This mechanism allows for a number of user-defined visibility groups that can be excluded from certain types of rays as needed.

Note that the

Precondition
mask is currently limited to 8 bits.
Parameters
[in]groupThe group handle
[in]maskA set of bits for which rays will intersect the group

Return values

Relevant return values:

History

rtGroupSetVisibilityMask was introduced in OptiX 6.0.

See also rtGeometryGroupSetVisibilityMask, rtGroupGetVisibilityMask, rtTrace

RTresult RTAPI rtGroupValidate ( RTgroup  group)

Verifies the state of the group.

Description

rtGroupValidate checks group for completeness. If group or any of the objects attached to group are not valid, returns RT_ERROR_INVALID_VALUE.

Parameters
[in]groupSpecifies the group to be validated

Return values

Relevant return values:

History

rtGroupValidate was introduced in OptiX 1.0.

See also rtGroupCreate