OptiX
3.9
NVIDIA OptiX Acceleration Engine
|
OptiX public API.
Go to the source code of this file.
Macros | |
#define | RTAPI __declspec(dllimport) |
Typedefs | |
typedef unsigned int | RTsize |
typedef struct RTacceleration_api * | RTacceleration |
typedef struct RTbuffer_api * | RTbuffer |
typedef struct RTcontext_api * | RTcontext |
typedef struct RTgeometry_api * | RTgeometry |
typedef struct RTgeometryinstance_api * | RTgeometryinstance |
typedef struct RTgeometrygroup_api * | RTgeometrygroup |
typedef struct RTgroup_api * | RTgroup |
typedef struct RTmaterial_api * | RTmaterial |
typedef struct RTprogram_api * | RTprogram |
typedef struct RTselector_api * | RTselector |
typedef struct RTtexturesampler_api * | RTtexturesampler |
typedef struct RTtransform_api * | RTtransform |
typedef struct RTvariable_api * | RTvariable |
typedef void * | RTobject |
typedef struct RTremotedevice_api * | RTremotedevice |
typedef int(* | RTtimeoutcallback )(void) |
typedef struct RTacceleration_api* RTacceleration |
Opaque type to handle Acceleration Structures - Note that the *_api type should never be used directly. Only the typedef target name will be guaranteed to remain unchanged
typedef struct RTbuffer_api* RTbuffer |
Opaque type to handle Buffers - Note that the *_api type should never be used directly. Only the typedef target name will be guaranteed to remain unchanged
typedef struct RTcontext_api* RTcontext |
Opaque type to handle Contexts - Note that the *_api type should never be used directly. Only the typedef target name will be guaranteed to remain unchanged
typedef struct RTgeometry_api* RTgeometry |
Opaque type to handle Geometry - Note that the *_api type should never be used directly. Only the typedef target name will be guaranteed to remain unchanged
typedef struct RTgeometrygroup_api* RTgeometrygroup |
Opaque type to handle Geometry Group - Note that the *_api type should never be used directly. Only the typedef target name will be guaranteed to remain unchanged
typedef struct RTgeometryinstance_api* RTgeometryinstance |
Opaque type to handle Geometry Instance - Note that the *_api type should never be used directly. Only the typedef target name will be guaranteed to remain unchanged
typedef struct RTgroup_api* RTgroup |
Opaque type to handle Group - Note that the *_api type should never be used directly. Only the typedef target name will be guaranteed to remain unchanged
typedef struct RTmaterial_api* RTmaterial |
Opaque type to handle Material - Note that the *_api type should never be used directly. Only the typedef target name will be guaranteed to remain unchanged
typedef void* RTobject |
Opaque type to handle Object - Note that the *_api type should never be used directly. Only the typedef target name will be guaranteed to remain unchanged
typedef struct RTprogram_api* RTprogram |
Opaque type to handle Program - Note that the *_api type should never be used directly. Only the typedef target name will be guaranteed to remain unchanged
typedef struct RTremotedevice_api* RTremotedevice |
Opaque type to handle RemoteDevice - Note that the *_api type should never be used directly. Only the typedef target name will be guaranteed to remain unchanged
typedef struct RTselector_api* RTselector |
Opaque type to handle Selector - Note that the *_api type should never be used directly. Only the typedef target name will be guaranteed to remain unchanged
typedef struct RTtexturesampler_api* RTtexturesampler |
Opaque type to handle Texture Sampler - Note that the *_api type should never be used directly. Only the typedef target name will be guaranteed to remain unchanged
typedef int(* RTtimeoutcallback)(void) |
Callback signature for use with rtContextSetTimeoutCallback. Return 1 to ask for abort, 0 to continue.
typedef struct RTtransform_api* RTtransform |
Opaque type to handle Transform - Note that the *_api type should never be used directly. Only the typedef target name will be guaranteed to remain unchanged
typedef struct RTvariable_api* RTvariable |
Opaque type to handle Variable - Note that the *_api type should never be used directly. Only the typedef target name will be guaranteed to remain unchanged
RTresult RTAPI rtAccelerationCreate | ( | RTcontext | context, |
RTacceleration * | acceleration | ||
) |
Creates a new acceleration structure.
Description
rtAccelerationCreate creates a new ray tracing acceleration structure within a context. An acceleration structure is used by attaching it to a group or geometry group by calling rtGroupSetAcceleration or rtGeometryGroupSetAcceleration. Note that an acceleration structure can be shared by attaching it to multiple groups or geometry groups if the underlying geometric structures are the same, see rtGroupSetAcceleration and rtGeometryGroupSetAcceleration for more details. A newly created acceleration structure is initially in dirty state. Sets *acceleration to the handle of a newly created acceleration structure within context. Returns RT_ERROR_INVALID_VALUE if acceleration is NULL.
[in] | context | Specifies a context within which to create a new acceleration structure |
[out] | acceleration | Returns the newly created acceleration structure |
Return values
Relevant return values:
History
rtAccelerationCreate was introduced in OptiX 1.0.
See also rtAccelerationDestroy, rtContextCreate, rtAccelerationMarkDirty, rtAccelerationIsDirty, rtGroupSetAcceleration, rtGeometryGroupSetAcceleration
RTresult RTAPI rtAccelerationDestroy | ( | RTacceleration | acceleration | ) |
Destroys an acceleration structure object.
Description
rtAccelerationDestroy removes acceleration from its context and deletes it. acceleration should be a value returned by rtAccelerationCreate. After the call, acceleration is no longer a valid handle.
[in] | acceleration | Handle of the acceleration structure to destroy |
Return values
Relevant return values:
History
rtAccelerationDestroy was introduced in OptiX 1.0.
See also rtAccelerationCreate
RTresult RTAPI rtAccelerationGetBuilder | ( | RTacceleration | acceleration, |
const char ** | return_string | ||
) |
Query the current builder from an acceleration structure.
Description
rtAccelerationGetBuilder returns the name of the builder currently used in the acceleration structure acceleration. If no builder has been set for acceleration, an empty string is returned. return_string will be set to point to the returned string. The memory return_string points to will be valid until the next API call that returns a string.
[in] | acceleration | The acceleration structure handle |
[out] | return_string | Return string buffer |
Return values
Relevant return values:
History
rtAccelerationGetBuilder was introduced in OptiX 1.0.
See also rtAccelerationSetBuilder
RTresult RTAPI rtAccelerationGetContext | ( | RTacceleration | acceleration, |
RTcontext * | context | ||
) |
Returns the context associated with an acceleration structure.
Description
rtAccelerationGetContext queries an acceleration structure for its associated context. The context handle is returned in *context.
[in] | acceleration | The acceleration structure handle |
[out] | context | Returns the context associated with the acceleration structure |
Return values
Relevant return values:
History
rtAccelerationGetContext was introduced in OptiX 1.0.
See also rtAccelerationCreate
RTresult RTAPI rtAccelerationGetData | ( | RTacceleration | acceleration, |
void * | data | ||
) |
Retrieves acceleration structure data.
Description
rtAccelerationGetData retrieves the full state of the acceleration object, and copies it to the memory region pointed to by data. Sufficient memory must be available to hold the entire state. Use rtAccelerationGetDataSize to query the required memory size.
The returned data from this call is valid input data for rtAccelerationSetData.
If acceleration is marked dirty, this call is invalid and will return RT_ERROR_INVALID_VALUE.
[in] | acceleration | The acceleration structure handle |
[out] | data | Pointer to a memory region to be filled with the state of acceleration |
Return values
Relevant return values:
History
rtAccelerationGetData was introduced in OptiX 1.0.
RTresult RTAPI rtAccelerationGetDataSize | ( | RTacceleration | acceleration, |
RTsize * | size | ||
) |
Returns the size of the data to be retrieved from an acceleration structure.
Description
rtAccelerationGetDataSize queries the size of the data that will be returned on a subsequent call to rtAccelerationGetData. The size in bytes will be written to *size. The returned value is guaranteed to be valid only if no other function using the handle acceleration is made before rtAccelerationGetData.
If acceleration is marked dirty, this call is invalid and will return RT_ERROR_INVALID_VALUE.
[in] | acceleration | The acceleration structure handle |
[out] | size | The returned size of the data in bytes |
Return values
Relevant return values:
History
rtAccelerationGetDataSize was introduced in OptiX 1.0.
See also rtAccelerationGetData, rtAccelerationSetData
RTresult RTAPI rtAccelerationGetProperty | ( | RTacceleration | acceleration, |
const char * | name, | ||
const char ** | return_string | ||
) |
Queries an acceleration structure property.
Description
rtAccelerationGetProperty returns the value of the acceleration structure property name. See rtAccelerationSetProperty for a list of supported properties. If the property name is not found, an empty string is returned. return_string will be set to point to the returned string. The memory return_string points to will be valid until the next API call that returns a string.
[in] | acceleration | The acceleration structure handle |
[in] | name | The name of the property to be queried |
[out] | return_string | Return string buffer |
Return values
Relevant return values:
History
rtAccelerationGetProperty was introduced in OptiX 1.0.
See also rtAccelerationSetProperty, rtAccelerationSetBuilder, rtAccelerationSetTraverser
RTresult RTAPI rtAccelerationGetTraverser | ( | RTacceleration | acceleration, |
const char ** | return_string | ||
) |
Query the current traverser from an acceleration structure.
Description
rtAccelerationGetTraverser returns the name of the traverser currently used in the acceleration structure acceleration. If no traverser has been set for acceleration, an empty string is returned. return_string will be set to point to the returned string. The memory return_string points to will be valid until the next API call that returns a string.
[in] | acceleration | The acceleration structure handle |
[out] | return_string | Return string buffer |
Return values
Relevant return values:
History
rtAccelerationGetTraverser was introduced in OptiX 1.0.
See also rtAccelerationSetTraverser
RTresult RTAPI rtAccelerationIsDirty | ( | RTacceleration | acceleration, |
int * | dirty | ||
) |
Returns the dirty flag of an acceleration structure.
Description
rtAccelerationIsDirty returns whether the acceleration structure is currently marked dirty. If the flag is set, a nonzero value will be returned in *dirty. Otherwise, zero is returned.
Any acceleration structure which is marked dirty will be rebuilt on a call to one of the rtContextLaunch functions, and its dirty flag will be reset. The dirty flag will also be reset on a sucessful call to rtAccelerationSetData.
An acceleration structure which is not marked dirty will never be rebuilt, even if associated groups, geometry, properties, or any other values have changed.
Initially after creation, acceleration structures are marked dirty.
[in] | acceleration | The acceleration structure handle |
[out] | dirty | Returned dirty flag |
Return values
Relevant return values:
History
rtAccelerationIsDirty was introduced in OptiX 1.0.
See also rtAccelerationMarkDirty, rtAccelerationSetData, rtContextLaunch
RTresult RTAPI rtAccelerationMarkDirty | ( | RTacceleration | acceleration | ) |
Marks an acceleration structure as dirty.
Description
rtAccelerationMarkDirty sets the dirty flag for acceleration.
Any acceleration structure which is marked dirty will be rebuilt on a call to one of the rtContextLaunch functions, and its dirty flag will be reset. The dirty flag will also be reset on a sucessful call to rtAccelerationSetData.
An acceleration structure which is not marked dirty will never be rebuilt, even if associated groups, geometry, properties, or any other values have changed.
Initially after creation, acceleration structures are marked dirty.
[in] | acceleration | The acceleration structure handle |
Return values
Relevant return values:
History
rtAccelerationMarkDirty was introduced in OptiX 1.0.
See also rtAccelerationIsDirty, rtAccelerationSetData, rtContextLaunch
RTresult RTAPI rtAccelerationSetBuilder | ( | RTacceleration | acceleration, |
const char * | builder | ||
) |
Specifies the builder to be used for an acceleration structure.
Description
rtAccelerationSetBuilder specifies the method used to construct the ray tracing acceleration structure represented by acceleration. A builder must be set for the acceleration structure to pass validation. The current builder can be changed at any time, including after a call to rtContextLaunch. In this case, data previously computed for the acceleration structure is invalidated and the acceleration will be marked dirty.
An acceleration structure is only valid with a correct pair of builder and traverser. The traverser type is specified using rtAccelerationSetTraverser. For a list of valid combinations of builders and traversers, see below. For a description of the individual traversers, see rtAccelerationSetTraverser.
builder can take one of the following values:
[in] | acceleration | The acceleration structure handle |
[in] | builder | String value specifying the builder type |
Return values
Relevant return values:
History
rtAccelerationSetBuilder was introduced in OptiX 1.0.
See also rtAccelerationGetBuilder, rtAccelerationSetTraverser, rtAccelerationSetProperty
RTresult RTAPI rtAccelerationSetData | ( | RTacceleration | acceleration, |
const void * | data, | ||
RTsize | size | ||
) |
Sets the state of an acceleration structure.
Description
rtAccelerationSetData sets the full state of the acceleration object, including builder and traverser type as well as properties, as defined by data. The memory pointed to by data must be unaltered values previously retrieved from a (potentially different) acceleration structure handle. This mechanism is useful for implementing caching mechanisms, especially when using high quality structures which are expensive to build.
Note that no check is performed on whether the contents of data match the actual underlying geometry on which the acceleration structure is used. If the children of associated groups or geometry groups differ in number of children, layout of bounding boxes, or geometry, then behavior after this call is undefined.
This call returns RT_ERROR_VERSION_MISMATCH if the specified data was retrieved from a different, incompatible version of OptiX. In this case, the state of acceleration is not changed.
If the call is successful, the dirty flag of acceleration will be cleared.
[in] | acceleration | The acceleration structure handle |
[in] | data | Pointer to data containing the serialized state |
[in] | size | The size in bytes of the buffer pointed to by data |
Return values
Relevant return values:
History
rtAccelerationSetData was introduced in OptiX 1.0.
RTresult RTAPI rtAccelerationSetProperty | ( | RTacceleration | acceleration, |
const char * | name, | ||
const char * | value | ||
) |
Sets an acceleration structure property.
Description
rtAccelerationSetProperty sets a named property value for an acceleration structure. Properties can be used to fine tune the way an acceleration structure is built, in order to achieve faster build times or better ray tracing performance. Properties are evaluated and applied by the acceleration structure during build time, and different builders recognize different properties. Setting a property will never fail as long as acceleration is a valid handle. Properties that are not recognized by an acceleration structure will be ignored.
The following is a list of the properties used by the individual builders:
[in] | acceleration | The acceleration structure handle |
[in] | name | String value specifying the name of the property |
[in] | value | String value specifying the value of the property |
Return values
Relevant return values:
History
rtAccelerationSetProperty was introduced in OptiX 1.0.
See also rtAccelerationGetProperty, rtAccelerationSetBuilder, rtAccelerationSetTraverser
RTresult RTAPI rtAccelerationSetTraverser | ( | RTacceleration | acceleration, |
const char * | traverser | ||
) |
Specifies the traverser to be used for an acceleration structure.
Description
rtAccelerationSetTraverser specifies the method used to traverse the ray tracing acceleration structure represented by acceleration. A traverser must be set for the acceleration structure to pass validation. The current active traverser can be changed at any time.
An acceleration structure is only valid with a correct pair of builder and traverser. The builder type is specified using rtAccelerationSetBuilder. For a list of valid combinations of builders and traversers, see below. For a description of the individual builders, see rtAccelerationSetBuilder.
traverser can take one of the following values:
[in] | acceleration | The acceleration structure handle |
[in] | traverser | String value specifying the traverser type |
Return values
Relevant return values:
History
rtAccelerationSetTraverser was introduced in OptiX 1.0.
See also rtAccelerationGetTraverser, rtAccelerationSetBuilder, rtAccelerationSetProperty
RTresult RTAPI rtAccelerationValidate | ( | RTacceleration | acceleration | ) |
Validates the state of an acceleration structure.
Description
rtAccelerationValidate checks acceleration for completeness. If acceleration is not valid, returns RT_ERROR_INVALID_VALUE.
[in] | acceleration | The acceleration structure handle |
Return values
Relevant return values:
History
rtAccelerationValidate was introduced in OptiX 1.0.
See also rtAccelerationCreate
Bind a stream buffer to an output buffer source.
Description
Binds an output buffer to a progressive stream. The output buffer thereby becomes the data source for the stream. To form a valid output/stream pair, the stream buffer must be of format RT_FORMAT_UNSIGNED_BYTE4, and the output buffer must be of format RT_FORMAT_FLOAT3 or RT_FORMAT_FLOAT4. The use of RT_FORMAT_FLOAT4 is recommended for performance reasons, even if the fourth component is unused. The output buffer must be of type RT_BUFFER_OUTPUT; it may not be of type RT_BUFFER_INPUT_OUTPUT.
[in] | stream | The stream buffer for which the source is to be specified |
[in] | source | The output buffer to function as the stream's source |
Return values
Relevant return values:
History
rtBufferBindProgressiveStream was introduced in OptiX 3.8.
See also rtBufferCreate rtBufferSetAttribute rtBufferGetAttribute
Creates a new buffer object.
Description
rtBufferCreate allocates and returns a new handle to a new buffer object in *buffer associated with context. The backing storage of the buffer is managed by OptiX. A buffer is specified by a bitwise or combination of a type and flags in bufferdesc. The supported types are:
The type values are used to specify the direction of data flow from the host to the OptiX devices. RT_BUFFER_INPUT specifies that the host may only write to the buffer and the device may only read from the buffer. RT_BUFFER_OUTPUT specifies the opposite, read only access on the host and write only access on the device. Devices and the host may read and write from buffers of type RT_BUFFER_INPUT_OUTPUT. Reading or writing to a buffer of the incorrect type (e.g., the host writing to a buffer of type RT_BUFFER_OUTPUT) is undefined. RT_BUFFER_PROGRESSIVE_STREAM is used to receive stream updates generated by progressive launches (see rtContextLaunchProgressive2D).
The supported flags are:
If RT_BUFFER_LAYERED flag is set, buffer depth specifies the number of layers, not the depth of a 3D buffer. If RT_BUFFER_CUBEMAP flag is set, buffer depth specifies the number of cube faces, not the depth of a 3D buffer. See details in rtBufferSetSize3D
Flags can be used to optimize data transfers between the host and its devices. The flag RT_BUFFER_GPU_LOCAL can only be used in combination with RT_BUFFER_INPUT_OUTPUT. RT_BUFFER_INPUT_OUTPUT and RT_BUFFER_GPU_LOCAL used together specify a buffer that allows the host to only write, and the device to read and write data. The written data will never be visible on the host side and will generally not be visible or other devices.
If rtBufferSetDevicePointer or rtBufferGetDevicePointer have been called for a single device for a given buffer, the user can change the buffer's content on that device. The new buffer contents must be synchronized to all devices. These synchronization copies occur at every rtContextLaunch, unless the buffer is declared with RT_BUFFER_COPY_ON_DIRTY. In this case, use rtBufferMarkDirty to notify OptiX that the buffer has been dirtied and must be synchronized.
Returns RT_ERROR_INVALID_VALUE if buffer is NULL.
[in] | context | The context to create the buffer in |
[in] | bufferdesc | Bitwise or combination of the type and flags of the new buffer |
[out] | buffer | The return handle for the buffer object |
Return values
Relevant return values:
History
rtBufferCreate was introduced in OptiX 1.0.
RT_BUFFER_GPU_LOCAL was introduced in OptiX 2.0.
See also rtBufferCreateFromGLBO, rtBufferDestroy, rtBufferMarkDirty rtBufferBindProgressiveStream
Destroys a buffer object.
Description
rtBufferDestroy removes buffer from its context and deletes it. buffer should be a value returned by rtBufferCreate. After the call, buffer is no longer a valid handle. Any API object that referenced buffer will have its reference invalidated.
[in] | buffer | Handle of the buffer to destroy |
Return values
Relevant return values:
History
rtBufferDestroy was introduced in OptiX 1.0.
See also rtBufferCreate, rtBufferCreateFromGLBO
RTresult RTAPI rtBufferGetAttribute | ( | RTbuffer | buffer, |
RTbufferattribute | attrib, | ||
RTsize | size, | ||
void * | p | ||
) |
Query a buffer attribute.
Description
rtBufferGetAttribute is used to query buffer attributes. For a list of available attributes, please refer to rtBufferSetAttribute.
[in] | buffer | The buffer to query the attribute from |
[in] | attrib | The attribute to query |
[in] | size | The size of the attribute value, in bytes. For string attributes, this is the maximum buffer size the returned string will use (including a terminating null character). |
[out] | p | Pointer to the attribute value to be filled in. Must point to valid memory of at least size bytes. |
Return values
Relevant return values:
History
rtBufferGetAttribute was introduced in OptiX 3.8.
See also rtBufferSetAttribute
Returns the context object that created this buffer.
Description
rtBufferGetContext returns a handle to the context that created buffer in *context. If *context is NULL, returns RT_ERROR_INVALID_VALUE.
[in] | buffer | The buffer to be queried for its context |
[out] | context | The return handle for the buffer's context |
Return values
Relevant return values:
History
rtBufferGetContext was introduced in OptiX 1.0.
See also rtContextCreate
Gets the dimensionality of this buffer object.
Description
rtBufferGetDimensionality returns the dimensionality of buffer in *dimensionality. The value returned will be one of 1, 2 or 3, corresponding to 1D, 2D and 3D buffers, respectively.
[in] | buffer | The buffer to be queried for its dimensionality |
[out] | dimensionality | The return handle for the buffer's dimensionality |
Return values
Relevant return values:
History
rtBufferGetDimensionality was introduced in OptiX 1.0.
See also rtBufferSetSize{1-2-3}D
Returns the size of a buffer's individual elements.
Description
rtBufferGetElementSize queries the size of a buffer's elements. The target buffer is specified by buffer, which should be a value returned by rtBufferCreate. The size, in bytes, of the buffer's individual elements is returned in *element_size_return. Returns RT_ERROR_INVALID_VALUE if given a NULL pointer.
[in] | buffer | Specifies the buffer to be queried |
[out] | size_of_element | Returns the size of the buffer's individual elements |
Return values
Relevant return values:
History
rtBufferGetElementSize was introduced in OptiX 1.0.
See also rtBufferSetElementSize, rtBufferCreate
Gets the format of this buffer.
Description
rtBufferGetFormat returns, in *format, the format of buffer. See rtBufferSetFormat for a listing of RTbuffer values.
[in] | buffer | The buffer to be queried for its format |
[out] | format | The return handle for the buffer's format |
Return values
Relevant return values:
History
rtBufferGetFormat was introduced in OptiX 1.0.
See also rtBufferSetFormat, rtBufferGetFormat
Gets an id suitable for use with buffers of buffers.
Description
rtBufferGetId returns an ID for the provided buffer. The returned ID is used on the device to reference the buffer. It needs to be copied into a buffer of type RT_FORMAT_BUFFER_ID or used in a rtBufferId object.. If *buffer_id is NULL or the buffer is not a valid RTbuffer, returns RT_ERROR_INVALID_VALUE. RT_BUFFER_ID_NULL can be used as a sentinal for a non-existent buffer, since this value will never be returned as a valid buffer id.
[in] | buffer | The buffer to be queried for its id |
[out] | buffer_id | The returned ID of the buffer |
Return values
Relevant return values:
History
rtBufferGetId was introduced in OptiX 3.5.
See also rtContextGetBufferFromId
Gets the number of mipmap levels of this buffer object.
Description
rtBufferGetMipLevelCount returns the number of mipmap levels. Default number of MIP levels is 1.
[in] | buffer | The buffer to be queried for its number of mipmap levels |
[out] | level | The return number of mipmap levels |
Return values
Relevant return values:
History
rtBufferGetMipLevelCount was introduced in OptiX 3.9.
See also rtBufferSetMipLevelCount, rtBufferSetSize1D, rtBufferSetSize2D, rtBufferSetSize3D, rtBufferSetSizev, rtBufferGetMipLevelSize1D, rtBufferGetMipLevelSize2D, rtBufferGetMipLevelSize3D, rtBufferGetSize1D, rtBufferGetSize2D, rtBufferGetSize3D, rtBufferGetSizev
Gets the width of buffer specific MIP level.
Description
rtBufferGetMipLevelSize1D stores the width of buffer in *width.
[in] | buffer | The buffer to be queried for its dimensions |
[in] | level | The buffer MIP level index to be queried for its dimensions |
[out] | width | The return handle for the buffer's width Return values |
Relevant return values:
History
rtBufferGetMipLevelSize1D was introduced in OptiX 3.9.
See also rtBufferSetMipLevelCount, rtBufferSetSize1D, rtBufferSetSize2D, rtBufferSetSize3D, rtBufferSetSizev, rtBufferGetMipLevelSize2D, rtBufferGetMipLevelSize3D, rtBufferGetMipLevelCount, rtBufferGetSize1D, rtBufferGetSize2D, rtBufferGetSize3D, rtBufferGetSizev
RTresult RTAPI rtBufferGetMipLevelSize2D | ( | RTbuffer | buffer, |
unsigned int | level, | ||
RTsize * | width, | ||
RTsize * | height | ||
) |
Gets the width, height of buffer specific MIP level.
Description
rtBufferGetMipLevelSize2D stores the width, height of buffer in *width and *height respectively.
[in] | buffer | The buffer to be queried for its dimensions |
[in] | level | The buffer MIP level index to be queried for its dimensions |
[out] | width | The return handle for the buffer's width |
[out] | height | The return handle for the buffer's height Return values |
Relevant return values:
History
rtBufferGetMipLevelSize2D was introduced in OptiX 3.9.
See also rtBufferSetMipLevelCount, rtBufferSetSize1D, rtBufferSetSize2D, rtBufferSetSize3D, rtBufferSetSizev, rtBufferGetMipLevelSize1D, rtBufferGetMipLevelSize3D, rtBufferGetMipLevelCount, rtBufferGetSize1D, rtBufferGetSize2D, rtBufferGetSize3D, rtBufferGetSizev
RTresult RTAPI rtBufferGetMipLevelSize3D | ( | RTbuffer | buffer, |
unsigned int | level, | ||
RTsize * | width, | ||
RTsize * | height, | ||
RTsize * | depth | ||
) |
Gets the width, height and depth of buffer specific MIP level.
Description
rtBufferGetMipLevelSize3D stores the width, height and depth of buffer in *width, *height and *depth, respectively.
[in] | buffer | The buffer to be queried for its dimensions |
[in] | level | The buffer MIP level index to be queried for its dimensions |
[out] | width | The return handle for the buffer's width |
[out] | height | The return handle for the buffer's height |
[out] | depth | The return handle for the buffer's depth Return values |
Relevant return values:
History
rtBufferGetMipLevelSize3D was introduced in OptiX 3.9.
See also rtBufferSetMipLevelCount, rtBufferSetSize1D, rtBufferSetSize2D, rtBufferSetSize3D, rtBufferSetSizev, rtBufferGetMipLevelSize1D, rtBufferGetMipLevelSize2D, rtBufferGetMipLevelCount, rtBufferGetSize1D, rtBufferGetSize2D, rtBufferGetSize3D, rtBufferGetSizev
RTresult RTAPI rtBufferGetProgressiveUpdateReady | ( | RTbuffer | buffer, |
int * | ready, | ||
unsigned int * | subframe_count, | ||
unsigned int * | max_subframes | ||
) |
Check whether stream buffer content has been updated by a Progressive Launch.
Description
Returns whether or not the result of a progressive launch in buffer has been updated since the last time this function was called. A client application should use this call in its main render/display loop to poll for frame refreshes after initiating a progressive launch. If subframe_count and max_subframes are non-null, they will be filled with the corresponding counters if and only if ready returns 1.
Note that this call does not stop a progressive render.
[in] | buffer | The stream buffer to be queried |
[out] | ready | Ready flag. Will be set to 1 if an update is available, or 0 if no update is available. |
[out] | subframe_count | The number of subframes accumulated in the latest result |
[out] | max_subframes | The max_subframes parameter as specified in the call to rtContextLaunchProgressive2D |
Return values
Relevant return values:
History
rtBufferGetProgressiveUpdateReady was introduced in OptiX 3.8.
See also rtContextLaunchProgressive2D
Get the width of this buffer.
Description
rtBufferGetSize1D stores the width of buffer in *width.
[in] | buffer | The buffer to be queried for its dimensions |
[out] | width | The return handle for the buffer's width |
Return values
Relevant return values:
History
rtBufferGetSize1D was introduced in OptiX 1.0.
See also rtBufferSetMipLevelCount, rtBufferSetSize1D, rtBufferSetSize2D, rtBufferSetSize3D, rtBufferSetSizev, rtBufferGetMipLevelSize1D, rtBufferGetMipLevelSize2D, rtBufferGetMipLevelSize3D, rtBufferGetMipLevelCount, rtBufferGetSize2D, rtBufferGetSize3D, rtBufferGetSizev
Gets the width and height of this buffer.
Description
rtBufferGetSize2D stores the width and height of buffer in *width and *height, respectively.
[in] | buffer | The buffer to be queried for its dimensions |
[out] | width | The return handle for the buffer's width |
[out] | height | The return handle for the buffer's height |
Return values
Relevant return values:
History
rtBufferGetSize2D was introduced in OptiX 1.0.
See also rtBufferSetMipLevelCount, rtBufferSetSize1D, rtBufferSetSize2D, rtBufferSetSize3D, rtBufferSetSizev, rtBufferGetMipLevelSize1D, rtBufferGetMipLevelSize2D, rtBufferGetMipLevelSize3D, rtBufferGetMipLevelCount, rtBufferGetSize1D, rtBufferGetSize3D, rtBufferGetSizev
RTresult RTAPI rtBufferGetSize3D | ( | RTbuffer | buffer, |
RTsize * | width, | ||
RTsize * | height, | ||
RTsize * | depth | ||
) |
Gets the width, height and depth of this buffer.
Description
rtBufferGetSize3D stores the width, height and depth of buffer in *width, *height and *depth, respectively.
[in] | buffer | The buffer to be queried for its dimensions |
[out] | width | The return handle for the buffer's width |
[out] | height | The return handle for the buffer's height |
[out] | depth | The return handle for the buffer's depth |
Return values
Relevant return values:
History
rtBufferGetSize3D was introduced in OptiX 1.0.
See also rtBufferSetMipLevelCount, rtBufferSetSize1D, rtBufferSetSize2D, rtBufferSetSize3D, rtBufferSetSizev, rtBufferGetMipLevelSize1D, rtBufferGetMipLevelSize2D, rtBufferGetMipLevelSize3D, rtBufferGetMipLevelCount, rtBufferGetSize1D, rtBufferGetSize2D, rtBufferGetSizev
Gets the dimensions of this buffer.
Description
rtBufferGetSizev stores the dimensions of buffer in *dims. The number of dimensions returned is specified by dimensionality. The storage at dims must be large enough to hold the number of requested buffer dimensions.
[in] | buffer | The buffer to be queried for its dimensions |
[in] | dimensionality | The number of requested dimensions |
[out] | dims | The array of dimensions to store to |
Return values
Relevant return values:
History
rtBufferGetSizev was introduced in OptiX 1.0.
See also rtBufferSetMipLevelCount, rtBufferSetSize1D, rtBufferSetSize2D, rtBufferSetSize3D, rtBufferSetSizev, rtBufferGetMipLevelSize1D, rtBufferGetMipLevelSize2D, rtBufferGetMipLevelSize3D, rtBufferGetMipLevelCount, rtBufferGetSize1D, rtBufferGetSize2D, rtBufferGetSize3D
Maps a buffer object to the host.
Description
rtBufferMap returns a pointer, accessible by the host, in *user_pointer that contains a mapped copy of the contents of buffer. The memory pointed to by *user_pointer can be written to or read from, depending on the type of buffer. For example, this code snippet demonstrates creating and filling an input buffer with floats.
If buffer has already been mapped, returns RT_ERROR_ALREADY_MAPPED.
Note that this call does not stop a progressive render if called on a stream buffer.
[in] | buffer | The buffer to be mapped |
[out] | user_pointer | Return handle to a user pointer where the buffer will be mapped to |
Return values
Relevant return values:
History
rtBufferMap was introduced in OptiX 1.0.
See also rtBufferUnmap, rtBufferMapEx, rtBufferUnmapEx
RTresult RTAPI rtBufferMapEx | ( | RTbuffer | buffer, |
unsigned int | map_flags, | ||
unsigned int | level, | ||
void * | user_owned, | ||
void ** | optix_owned | ||
) |
Maps mipmap level of buffer object to the host.
Description
rtBufferMapEx returns a pointer, accessible by the host, in *optix_owned if user_owned is null overwise user_owned is used for the mapping the contents of level. rtBufferMap is equivalent to rtBufferMapEx with level = 0 and RT_BUFFER_MAP_READ_WRITE flag and user_owned = NULL.
Note that this call does not stop a progressive render if called on a stream buffer.
[in] | buffer | The buffer to be mapped |
[in] | map_flag | Declare access pattern to the mapped buffer memory. Not supported yet and must be RT_BUFFER_MAP_READ_WRITE. |
[in] | level | The mipmap level to be mapped |
[in] | user_owned | Preallocated memory for mapping, can be null, then it is allocated internally. Not supported yet and must be NULL. |
[out] | optix_owned | Return handle to a user pointer where the buffer will be mapped to |
The supported flags are:
Return values
Relevant return values:
History
rtBufferMapEx was introduced in OptiX 3.9.
See also rtBufferMap, rtBufferUnmap, rtBufferUnmapEx
RTresult RTAPI rtBufferSetAttribute | ( | RTbuffer | buffer, |
RTbufferattribute | attrib, | ||
RTsize | size, | ||
void * | p | ||
) |
Set a buffer attribute.
Description
Sets a buffer attribute. Currently, all available attributes refer to stream buffers only, and attempting to set them on a non-stream buffer will generate an error.
Each attribute can have a different size. The sizes are given in the following list:
RT_BUFFER_ATTRIBUTE_STREAM_FORMAT sets the encoding format used for streams sent over the network, specified as a string. The default is "auto". Various other common stream and image formats are available (e.g. "h264", "png"). This attribute has no effect if the progressive API is used locally.
RT_BUFFER_ATTRIBUTE_STREAM_BITRATE sets the target bitrate for streams sent over the network, if the stream format supports it. The data is specified as a 32-bit integer. The default is 5000000. This attribute has no effect if the progressive API is used locally or if the stream format does not support variable bitrates.
RT_BUFFER_ATTRIBUTE_STREAM_FPS sets the target update rate per second for streams sent over the network, if the stream format supports it. The data is specified as a 32-bit integer. The default is 30. This attribute has no effect if the progressive API is used locally or if the stream format does not support variable framerates.
RT_BUFFER_ATTRIBUTE_STREAM_GAMMA sets the gamma value for the built-in tonemapping operator. The data is specified as a 32-bit float, the default is 1.0. Tonemapping is executed before encoding the accumulated output into the stream, i.e. on the server side if remote rendering is used. See the section on Buffers below for more details.
[in] | buffer | The buffer on which to set the attribute |
[in] | attrib | The attribute to set |
[in] | size | The size of the attribute value, in bytes |
[in] | p | Pointer to the attribute value |
Return values
Relevant return values:
History
rtBufferSetAttribute was introduced in OptiX 3.8.
See also rtBufferGetAttribute
Modifies the size in bytes of a buffer's individual elements.
Description
rtBufferSetElementSize modifies the size in bytes of a buffer's user-formatted elements. The target buffer is specified by buffer, which should be a value returned by rtBufferCreate and should have format RT_FORMAT_USER. The new size of the buffer's individual elements is specified by element_size and should not be 0. If the buffer has format RT_FORMAT_USER, and element_size is not 0, then the buffer's individual element size is set to element_size and all storage associated with the buffer is reset. Otherwise, this call has no effect and returns either RT_ERROR_TYPE_MISMATCH if the buffer does not have format RT_FORMAT_USER or RT_ERROR_INVALID_VALUE if the buffer has format RT_FORMAT_USER but element_size is 0.
[in] | buffer | Specifies the buffer to be modified |
[in] | size_of_element | Specifies the new size in bytes of the buffer's individual elements |
Return values
Relevant return values:
History
rtBufferSetElementSize was introduced in OptiX 1.0.
See also rtBufferGetElementSize, rtBufferCreate
Sets the format of this buffer.
Description
rtBufferSetFormat changes the format of buffer to the specified value. The data elements of the buffer will have the specified type and can either be vector formats, or a user-defined type whose size is specified with rtBufferSetElementSize. Possible values for format are:
[in] | buffer | The buffer to have its format set |
[in] | format | The target format of the buffer |
Return values
Relevant return values:
History
rtBufferSetFormat was introduced in OptiX 1.0.
See also rtBufferSetFormat, rtBufferGetFormat, rtBufferGetFormat, rtBufferGetElementSize, rtBufferSetElementSize
Sets the MIP level count of a buffer.
Description
rtBufferSetMipLevelCount sets the number of MIP levels to levels. Default number of MIP levels is 1. Fails with RT_ERROR_ALREADY_MAPPED if called on a buffer that is mapped.
[in] | buffer | The buffer to be resized |
[in] | width | The width of the resized buffer |
[in] | levels | Number of mip levels |
Return values
Relevant return values:
History
rtBufferSetMipLevelCount was introduced in OptiX 3.9.
See also rtBufferSetSize1D, rtBufferSetSize2D, rtBufferSetSize3D, rtBufferSetSizev, rtBufferGetMipLevelSize1D, rtBufferGetMipLevelSize2D, rtBufferGetMipLevelSize3D, rtBufferGetMipLevelCount, rtBufferGetSize1D, rtBufferGetSize2D, rtBufferGetSize3D, rtBufferGetSizev
Sets the width and dimensionality of this buffer.
Description
rtBufferSetSize1D sets the dimensionality of buffer to 1 and sets its width to width. Fails with RT_ERROR_ALREADY_MAPPED if called on a buffer that is mapped.
[in] | buffer | The buffer to be resized |
[in] | width | The width of the resized buffer |
Return values
Relevant return values:
History
rtBufferSetSize1D was introduced in OptiX 1.0.
See also rtBufferSetMipLevelCount, rtBufferSetSize2D, rtBufferSetSize3D, rtBufferSetSizev, rtBufferGetMipLevelSize1D, rtBufferGetMipLevelSize2D, rtBufferGetMipLevelSize3D, rtBufferGetMipLevelCount, rtBufferGetSize1D, rtBufferGetSize2D, rtBufferGetSize3D, rtBufferGetSizev
Sets the width, height and dimensionality of this buffer.
Description
rtBufferSetSize2D sets the dimensionality of buffer to 2 and sets its width and height to width and height, respectively. If width or height is zero, they both must be zero. Fails with RT_ERROR_ALREADY_MAPPED if called on a buffer that is mapped.
[in] | buffer | The buffer to be resized |
[in] | width | The width of the resized buffer |
[in] | height | The height of the resized buffer |
Return values
Relevant return values:
History
rtBufferSetSize2D was introduced in OptiX 1.0.
See also rtBufferSetMipLevelCount, rtBufferSetSize1D, rtBufferSetSize3D, rtBufferSetSizev, rtBufferGetMipLevelSize1D, rtBufferGetMipLevelSize2D, rtBufferGetMipLevelSize3D, rtBufferGetMipLevelCount, rtBufferGetSize1D, rtBufferGetSize2D, rtBufferGetSize3D, rtBufferGetSizev
Sets the width, height, depth and dimensionality of a buffer.
Description
rtBufferSetSize3D sets the dimensionality of buffer to 3 and sets its width, height and depth to width, height and depth, respectively. If width, height or depth is zero, they all must be zero.
A 1D layered mipmapped buffer is allocated if height is 1 and the RT_BUFFER_LAYERED flag was set at buffer creating. The number of layers is determined by the depth. A 2D layered mipmapped buffer is allocated if the RT_BUFFER_LAYERED flag was set at buffer creating. The number of layers is determined by the depth. A cubemap mipmapped buffer is allocated if the RT_BUFFER_CUBEMAP flag was set at buffer creating. width must be equal to height and the number of cube faces is determined by the depth, it must be six or a multiple of six, if the RT_BUFFER_LAYERED flag was also set. Layered, mipmapped and cubemap buffers are supported only as texture buffers.
Fails with RT_ERROR_ALREADY_MAPPED if called on a buffer that is mapped.
[in] | buffer | The buffer to be resized |
[in] | width | The width of the resized buffer |
[in] | height | The height of the resized buffer |
[in] | depth | The depth of the resized buffer |
Return values
Relevant return values:
History
rtBufferSetSize3D was introduced in OptiX 1.0.
See also rtBufferSetMipLevelCount, rtBufferSetSize1D, rtBufferSetSize2D, rtBufferSetSizev, rtBufferGetMipLevelSize1D, rtBufferGetMipLevelSize2D, rtBufferGetMipLevelSize3D, rtBufferGetMipLevelCount, rtBufferGetSize1D, rtBufferGetSize2D, rtBufferGetSize3D, rtBufferGetSizev
RTresult RTAPI rtBufferSetSizev | ( | RTbuffer | buffer, |
unsigned int | dimensionality, | ||
const RTsize * | dims | ||
) |
Sets the dimensionality and dimensions of a buffer.
Description
rtBufferSetSizev sets the dimensionality of buffer to dimensionality and sets the dimensions of the buffer to the values stored at *dims, which must contain a number of values equal to dimensionality. If any of values of dims is zero they must all be zero.
[in] | buffer | The buffer to be resized |
[in] | dimensionality | The dimensionality the buffer will be resized to |
[in] | dims | The array of sizes for the dimension of the resize |
Return values
Relevant return values:
History
rtBufferSetSizev was introduced in OptiX 1.0.
See also rtBufferSetMipLevelCount, rtBufferSetSize1D, rtBufferSetSize2D, rtBufferSetSize3D, rtBufferGetMipLevelSize1D, rtBufferGetMipLevelSize2D, rtBufferGetMipLevelSize3D, rtBufferGetMipLevelCount, rtBufferGetSize1D, rtBufferGetSize2D, rtBufferGetSize3D, rtBufferGetSizev
Unmaps a buffer's storage from the host.
Description
rtBufferUnmap unmaps a buffer from the host after a call to rtBufferMap. rtContextLaunch cannot be called while buffers are still mapped to the host. A call to rtBufferUnmap that does not follow a matching rtBufferMap call will return RT_ERROR_INVALID_VALUE.
Note that this call does not stop a progressive render if called with a stream buffer.
[in] | buffer | The buffer to unmap |
Return values
Relevant return values:
History
rtBufferUnmap was introduced in OptiX 1.0.
See also rtBufferMap, rtBufferMapEx, rtBufferUnmapEx
Unmaps mipmap level storage from the host.
Description
rtBufferUnmapEx unmaps buffer level from the host after a call to rtBufferMapEx. rtContextLaunch cannot be called while buffers are still mapped to the host. A call to rtBufferUnmapEx that does not follow a matching rtBufferMapEx call will return RT_ERROR_INVALID_VALUE. rtBufferUnmap is equivalent to rtBufferUnmapEx with level = 0.
Note that this call does not stop a progressive render if called with a stream buffer.
[in] | buffer | The buffer to unmap |
[in] | level | The mipmap level to unmap |
Return values
Relevant return values:
History
rtBufferUnmapEx was introduced in OptiX 3.9.
See also rtBufferMap, rtBufferUnmap, rtBufferMapEx
Validates the state of a buffer.
Description
rtBufferValidate checks buffer for completeness. If buffer has not had its dimensionality, size or format set, this call will return RT_ERROR_INVALID_CONTEXT.
[in] | buffer | The buffer to validate |
Return values
Relevant return values:
History
rtBufferValidate was introduced in OptiX 1.0.
See also rtBufferCreate, rtBufferCreateFromGLBO rtContextValidate
Compiles a context object.
Description
rtContextCompile creates a final computation kernel from the given context's programs and scene hierarchy. This kernel will be executed upon subsequent invocations of rtContextLaunch.
Calling rtContextCompile is not strictly necessary since any changes to the scene specification or programs will cause an internal compilation upon the next rtContextLaunch call. rtContextCompile allows the application to control when the compilation work occurs.
Conversely, if no changes to the scene specification or programs have occurred since the last compilation, rtContextCompile and rtContextLaunch will not perform a recompilation.
[in] | context | The context to be compiled |
Return values
Relevant return values:
History
rtContextCompile was introduced in OptiX 1.0.
See also rtContextLaunch
Creates a new context object.
Description
rtContextCreate allocates and returns a handle to a new context object. Returns RT_ERROR_INVALID_VALUE if passed a NULL pointer.
[out] | context | Handle to context for return value |
Return values
Relevant return values:
History
rtContextCreate was introduced in OptiX 1.0.
See also
RTresult RTAPI rtContextDeclareVariable | ( | RTcontext | context, |
const char * | name, | ||
RTvariable * | v | ||
) |
Declares a new named variable associated with this context.
Description
rtContextDeclareVariable - Declares a new variable named name and associated with this context. Only a single variable of a given name can exist for a given context and any attempt to create multiple variables with the same name will cause a failure with a return value of RT_ERROR_VARIABLE_REDECLARED. Returns RT_ERROR_INVALID_VALUE if passed a NULL pointer. Return RT_ERROR_ILLEGAL_SYMBOL if name is not syntactically valid.
[in] | context | The context node to which the variable will be attached |
[in] | name | The name that identifies the variable to be queried |
[out] | v | Pointer to variable handle used to return the new object |
Return values
Relevant return values:
History
rtContextDeclareVariable was introduced in OptiX 1.0.
See also rtGeometryDeclareVariable, rtGeometryInstanceDeclareVariable, rtMaterialDeclareVariable, rtProgramDeclareVariable, rtSelectorDeclareVariable, rtContextGetVariable, rtContextGetVariableCount, rtContextQueryVariable, rtContextRemoveVariable
Destroys a context and frees all associated resources.
Description
rtContextDestroy frees all resources, including OptiX objects, associated with this object. Returns RT_ERROR_INVALID_VALUE if passed a NULL context. RT_ERROR_LAUNCH_FAILED may be returned if a previous call to rtContextLaunch failed.
[in] | context | Handle of the context to destroy |
Return values
Relevant return values:
History
rtContextDestroy was introduced in OptiX 1.0.
See also rtContextCreate
RTresult RTAPI rtContextGetAttribute | ( | RTcontext | context, |
RTcontextattribute | attrib, | ||
RTsize | size, | ||
void * | p | ||
) |
Returns an attribute specific to an OptiX context.
Description
rtContextGetAttribute returns in p the value of the per context attribute specified by attrib.
Each attribute can have a different size. The sizes are given in the following list:
RT_CONTEXT_ATTRIBUTE_MAX_TEXTURE_COUNT queries the maximum number of textures handled by OptiX. For OptiX versions below 2.5 this value depends on the number of textures supported by CUDA.
RT_CONTEXT_ATTRIBUTE_CPU_NUM_THREADS queries the number of host CPU threads OptiX can use for various tasks.
RT_CONTEXT_ATTRIBUTE_USED_HOST_MEMORY queries the amount of host memory allocated by OptiX.
RT_CONTEXT_ATTRIBUTE_GPU_PAGING_ACTIVE queries if software paging of device memory has been turned on by the context. The returned value is a boolean, where 1 means that paging is currently active.
RT_CONTEXT_ATTRIBUTE_GPU_PAGING_FORCED_OFF queries if software paging has been prohibited by the user. The returned value is a boolean, where 0 means that OptiX is allowed to activate paging if necessary, 1 means that paging is always off.
RT_CONTEXT_ATTRIBUTE_AVAILABLE_DEVICE_MEMORY queries the amount of free device memory.
Some attributes are used to get per device information. In contrast to rtDeviceGetAttribute, these attributes are determined by the context and are therefore queried through the context. This is done by summing the attribute with the OptiX ordinal number when querying the attribute. The following are per device attributes.
RT_CONTEXT_ATTRIBUTE_AVAILABLE_DEVICE_MEMORY
[in] | context | The context object to be queried |
[in] | attrib | Attribute to query |
[in] | size | Size of the attribute being queried. Parameter p must have at least this much memory allocated |
[out] | p | Return pointer where the value of the attribute will be copied into. This must point to at least size bytes of memory |
Return values
Relevant return values:
History
rtContextGetAttribute was introduced in OptiX 2.0.
See also rtContextGetDeviceCount, rtContextSetAttribute, rtDeviceGetAttribute
Gets an RTbuffer corresponding to the buffer id.
Description
rtContextGetBufferFromId returns a handle to the buffer in *buffer corresponding to the buffer_id supplied. If buffer_id does not map to a valid buffer handle, *buffer is NULL or if context is invalid, returns RT_ERROR_INVALID_VALUE.
[in] | context | The context the buffer should be originated from |
[in] | buffer_id | The ID of the buffer to query |
[out] | buffer | The return handle for the buffer object corresponding to the buffer_id |
Return values
Relevant return values:
History
rtContextGetBufferFromId was introduced in OptiX 3.5.
See also rtBufferGetId
Query the number of devices currently being used.
Description
rtContextGetDeviceCount - Query the number of devices currently being used.
[in] | context | The context containing the devices |
[out] | count | Return parameter for the device count |
Return values
Relevant return values:
History
rtContextGetDeviceCount was introduced in OptiX 2.0.
See also rtContextSetDevices, rtContextGetDevices
Retrieve a list of hardware devices being used by the kernel.
Description
rtContextGetDevices retrieves a list of hardware devices used during execution of the subsequent trace kernels.
[in] | context | The context to which the hardware list is applied |
[out] | devices | Return parameter for the list of devices. The memory must be able to hold entries numbering least the number of devices as returned by rtContextGetDeviceCount |
Return values
Relevant return values:
History
rtContextGetDevices was introduced in OptiX 2.0.
See also rtContextSetDevices, rtContextGetDeviceCount
Query the number of entry points for this context.
Description
rtContextGetEntryPointCount passes back the number of entry points associated with this context in num_entry_points. Returns RT_ERROR_INVALID_VALUE if passed a NULL pointer.
[in] | context | The context node to be queried |
[out] | num_entry_points | Return parameter for passing back the entry point count |
Return values
Relevant return values:
History
rtContextGetEntryPointCount was introduced in OptiX 1.0.
See also rtContextSetEntryPointCount
void RTAPI rtContextGetErrorString | ( | RTcontext | context, |
RTresult | code, | ||
const char ** | return_string | ||
) |
Returns the error string associated with a given error.
Description
rtContextGetErrorString return a descriptive string given an error code. If context is valid and additional information is available from the last OptiX failure, it will be appended to the generic error code description. return_string will be set to point to this string. The memory return_string points to will be valid until the next API call that returns a string.
[in] | context | The context object to be queried, or NULL |
[in] | code | The error code to be converted to string |
[out] | return_string | The return parameter for the error string |
Return values
rtContextGetErrorString does not return a value
History
rtContextGetErrorString was introduced in OptiX 1.0.
See also
RTresult RTAPI rtContextGetExceptionEnabled | ( | RTcontext | context, |
RTexception | exception, | ||
int * | enabled | ||
) |
Query whether a specified exception is enabled.
Description
rtContextGetExceptionEnabled passes back 1 in *enabled if the given exception is enabled, 0 otherwise. exception specifies the type of exception to be queried. For a list of available types, see rtContextSetExceptionEnabled. If exception is RT_EXCEPTION_ALL, enabled is set to 1 only if all possible exceptions are enabled.
[in] | context | The context to be queried |
[in] | exception | The exception of which to query the state |
[out] | enabled | Return parameter to store whether the exception is enabled |
Return values
Relevant return values:
History
rtContextGetExceptionEnabled was introduced in OptiX 1.1.
See also rtContextSetExceptionEnabled, rtContextSetExceptionProgram, rtContextGetExceptionProgram, rtGetExceptionCode, rtThrow, rtPrintExceptionDetails
RTresult RTAPI rtContextGetExceptionProgram | ( | RTcontext | context, |
unsigned int | entry_point_index, | ||
RTprogram * | program | ||
) |
Queries the exception program associated with the given context and entry point.
Description
rtContextGetExceptionProgram passes back the exception program associated with the given context and entry point. This program is set via rtContextSetExceptionProgram. Returns RT_ERROR_INVALID_VALUE if given an invalid entry point index or NULL pointer.
[in] | context | The context node associated with the exception program |
[in] | entry_point_index | The entry point index for the desired exception program |
[out] | program | Return parameter to store the exception program |
Return values
Relevant return values:
History
rtContextGetExceptionProgram was introduced in OptiX 1.0.
See also rtContextSetExceptionProgram, rtContextSetEntryPointCount, rtContextSetExceptionEnabled, rtContextGetExceptionEnabled, rtGetExceptionCode, rtThrow, rtPrintExceptionDetails
RTresult RTAPI rtContextGetMissProgram | ( | RTcontext | context, |
unsigned int | ray_type_index, | ||
RTprogram * | program | ||
) |
Queries the miss program associated with the given context and ray type.
Description
rtContextGetMissProgram passes back the miss program associated with the given context and ray type. This program is set via rtContextSetMissProgram. Returns RT_ERROR_INVALID_VALUE if given an invalid ray type index or a NULL pointer.
[in] | context | The context node associated with the miss program |
[in] | ray_type_index | The ray type index for the desired miss program |
[out] | program | Return parameter to store the miss program |
Return values
Relevant return values:
History
rtContextGetMissProgram was introduced in OptiX 1.0.
Get the current size of the print buffer.
Description
rtContextGetPrintBufferSize is used to query the buffer size available to hold data generated by rtPrintf. Returns RT_ERROR_INVALID_VALUE if passed a NULL pointer.
[in] | context | The context from which to query the print buffer size |
[out] | buffer_size_bytes | The returned print buffer size in bytes |
Return values
Relevant return values:
History
rtContextGetPrintBufferSize was introduced in OptiX 1.0.
See also rtPrintf, rtContextSetPrintEnabled, rtContextGetPrintEnabled, rtContextSetPrintBufferSize, rtContextSetPrintLaunchIndex, rtContextGetPrintLaunchIndex
Query whether text printing from programs is enabled.
Description
rtContextGetPrintEnabled passes back 1 if text printing from programs through rtPrintf is currently enabled for this context; 0 otherwise. Returns RT_ERROR_INVALID_VALUE if passed a NULL pointer.
[in] | context | The context to be queried |
[out] | enabled | Return parameter to store whether printing is enabled |
Return values
Relevant return values:
History
rtContextGetPrintEnabled was introduced in OptiX 1.0.
See also rtPrintf, rtContextSetPrintEnabled, rtContextSetPrintBufferSize, rtContextGetPrintBufferSize, rtContextSetPrintLaunchIndex, rtContextGetPrintLaunchIndex
Gets the active print launch index.
Description
rtContextGetPrintLaunchIndex is used to query for which launch indices rtPrintf generates output. The initial value of (x,y,z) is (-1,-1,-1), which generates output for all indices.
[in] | context | The context from which to query the print launch index |
[out] | x | Returns the launch index in the x dimension to which the output of rtPrintf invocations is limited. Will not be written to if a NULL pointer is passed |
[out] | y | Returns the launch index in the y dimension to which the output of rtPrintf invocations is limited. Will not be written to if a NULL pointer is passed |
[out] | z | Returns the launch index in the z dimension to which the output of rtPrintf invocations is limited. Will not be written to if a NULL pointer is passed |
Return values
Relevant return values:
History
rtContextGetPrintLaunchIndex was introduced in OptiX 1.0.
See also rtPrintf, rtContextGetPrintEnabled, rtContextSetPrintEnabled, rtContextSetPrintBufferSize, rtContextGetPrintBufferSize, rtContextSetPrintLaunchIndex
Gets an RTprogram corresponding to the program id.
Description
rtContextGetProgramFromId returns a handle to the program in *program corresponding to the program_id supplied. If program_id is not a valid program handle, *program is set to NULL. Returns RT_ERROR_INVALID_VALUE if context is invalid or program_id is not a valid program handle.
[in] | context | The context the program should be originated from |
[in] | program_id | The ID of the program to query |
[out] | program | The return handle for the program object corresponding to the program_id |
Return values
Relevant return values:
History
rtContextGetProgramFromId was introduced in OptiX 3.6.
See also rtProgramGetId
RTresult RTAPI rtContextGetRayGenerationProgram | ( | RTcontext | context, |
unsigned int | entry_point_index, | ||
RTprogram * | program | ||
) |
Queries the ray generation program associated with the given context and entry point.
Description
rtContextGetRayGenerationProgram passes back the ray generation program associated with the given context and entry point. This program is set via rtContextSetRayGenerationProgram. Returns RT_ERROR_INVALID_VALUE if given an invalid entry point index or NULL pointer.
[in] | context | The context node associated with the ray generation program |
[in] | entry_point_index | The entry point index for the desired ray generation program |
[out] | program | Return parameter to store the ray generation program |
Return values
Relevant return values:
History
rtContextGetRayGenerationProgram was introduced in OptiX 1.0.
See also rtContextSetRayGenerationProgram
Query the number of ray types associated with this context.
Description
rtContextGetRayTypeCount passes back the number of entry points associated with this context in num_ray_types. Returns RT_ERROR_INVALID_VALUE if passed a NULL pointer.
[in] | context | The context node to be queried |
[out] | num_ray_types | Return parameter to store the number of ray types |
Return values
Relevant return values:
History
rtContextGetRayTypeCount was introduced in OptiX 1.0.
See also rtContextSetRayTypeCount
Query whether the given context is currently running.
Description
This function is currently unimplemented and it is provided as a placeholder for a future implementation.
[in] | context | The context node to be queried |
[out] | running | Return parameter to store the running state |
Return values
Since unimplemented, this function will always throw an assertion failure.
History
rtContextGetRunningState was introduced in OptiX 1.0.
See also rtContextLaunch1D, rtContextLaunch2D, rtContextLaunch3D
Query the stack size for this context.
Description
rtContextGetStackSize passes back the stack size associated with this context in stack_size_bytes. Returns RT_ERROR_INVALID_VALUE if passed a NULL pointer.
[in] | context | The context node to be queried |
[out] | stack_size_bytes | Return parameter to store the size of the stack |
Return values
Relevant return values:
History
rtContextGetStackSize was introduced in OptiX 1.0.
See also rtContextSetStackSize
RTresult RTAPI rtContextGetTextureSamplerFromId | ( | RTcontext | context, |
int | sampler_id, | ||
RTtexturesampler * | sampler | ||
) |
Gets an RTtexturesampler corresponding to the texture id.
Description
rtTextureSamplerGetId returns a handle to the texture sampler in *sampler corresponding to the sampler_id supplied. If sampler_id does not map to a valid texture handle, *sampler is NULL or if context is invalid, returns RT_ERROR_INVALID_VALUE.
[in] | context | The context the sampler should be originated from |
[in] | sampler_id | The ID of the sampler to query |
[out] | sampler | The return handle for the sampler object corresponding to the sampler_id |
Return values
Relevant return values:
History
rtContextGetTextureSamplerFromId was introduced in OptiX 3.5.
See also rtTextureSamplerGetId
RTresult RTAPI rtContextGetVariable | ( | RTcontext | context, |
unsigned int | index, | ||
RTvariable * | v | ||
) |
Queries an indexed variable associated with this context.
Description
rtContextGetVariable queries the variable at position index in the variable array from context and stores the result in the parameter v. A variable must be declared first with rtContextDeclareVariable and index must be in the range [0, rtContextGetVariableCount -1].
[in] | context | The context node to be queried for an indexed variable |
[in] | index | The index that identifies the variable to be queried |
[out] | v | Return value to store the queried variable |
Return values
Relevant return values:
History
rtContextGetVariable was introduced in OptiX 1.0.
See also rtGeometryGetVariable, rtGeometryInstanceGetVariable, rtMaterialGetVariable, rtProgramGetVariable, rtSelectorGetVariable, rtContextDeclareVariable, rtContextGetVariableCount, rtContextQueryVariable, rtContextRemoveVariable
Returns the number of variables associated with this context.
Description
rtContextGetVariableCount returns the number of variables that are currently attached to context. Returns RT_ERROR_INVALID_VALUE if passed a NULL pointer.
[in] | context | The context to be queried for number of attached variables |
[out] | count | Return parameter to store the number of variables |
Return values
Relevant return values:
History
rtContextGetVariableCount was introduced in OptiX 1.0.
See also rtGeometryGetVariableCount, rtGeometryInstanceGetVariableCount, rtMaterialGetVariableCount, rtProgramGetVariableCount, rtSelectorGetVariable, rtContextDeclareVariable, rtContextGetVariable, rtContextQueryVariable, rtContextRemoveVariable
RTresult RTAPI rtContextLaunch1D | ( | RTcontext | context, |
unsigned int | entry_point_index, | ||
RTsize | image_width | ||
) |
Executes the computation kernel for a given context.
Description
rtContextLaunch functions execute the computation kernel associated with the given context. If the context has not yet been compiled, or if the context has been modified since the last compile, rtContextLaunch will recompile the kernel internally. Acceleration structures of the context which are marked dirty will be updated and their dirty flags will be cleared. Similarly, validation will occur if necessary. The ray generation program specified by entry_point_index will be invoked once for every element (pixel or voxel) of the computation grid specified by image_width, image_height, and image_depth.
Return values
Relevant return values:
History
rtContextLaunch was introduced in OptiX 1.0.
See also rtContextGetRunningState, rtContextCompile, rtContextValidate
[in] | context | The context to be executed |
[in] | entry_point_index | The initial entry point into kernel |
[in] | image_width | Width of the computation grid |
RTresult RTAPI rtContextLaunch2D | ( | RTcontext | context, |
unsigned int | entry_point_index, | ||
RTsize | image_width, | ||
RTsize | image_height | ||
) |
[in] | context | The context to be executed |
[in] | entry_point_index | The initial entry point into kernel |
[in] | image_width | Width of the computation grid |
[in] | image_height | Height of the computation grid |
RTresult RTAPI rtContextLaunch3D | ( | RTcontext | context, |
unsigned int | entry_point_index, | ||
RTsize | image_width, | ||
RTsize | image_height, | ||
RTsize | image_depth | ||
) |
[in] | context | The context to be executed |
[in] | entry_point_index | The initial entry point into kernel |
[in] | image_width | Width of the computation grid |
[in] | image_height | Height of the computation grid |
[in] | image_depth | Depth of the computation grid |
RTresult RTAPI rtContextLaunchProgressive2D | ( | RTcontext | context, |
unsigned int | entry_index, | ||
RTsize | width, | ||
RTsize | height, | ||
unsigned int | max_subframes | ||
) |
Executes a Progressive Launch for a given context.
Description
Starts the (potentially parallel) generation of subframes for progressive rendering. If max_subframes is zero, there is no limit on the number of subframes generated. The generated subframes are automatically composited into a single result and streamed to the client at regular intervals, where they can be read by mapping an associated stream buffer. An application can therefore initiate a progressive launch, and then repeatedly map and display the contents of the stream buffer in order to visualize the progressive refinement of the image.
The call is nonblocking. A polling approach should be used to decide when to map and display the stream buffer contents (see rtBufferGetProgressiveUpdateReady). If a progressive launch is already in progress at the time of the call and its parameters match the initial launch, the call has no effect. Otherwise, the accumulated result will be reset and a new progressive launch will be started.
If any other OptiX function is called while a progressive launch is in progress, it will cause the launch to stop generating new subframes (however, subframes that have already been generated and are currently in flight may still arrive at the client). The only exceptions to this rule are the operations to map a stream buffer, issuing another progressive launch with unchanged parameters, and polling for an update. Those exceptions do not cause the progressive launch to stop generating subframes.
There is no guarantee that the call actually produces any subframes, especially if rtContextLaunchProgressive2D and other OptiX commands are called in short succession. For example, during an animation, rtVariableSet calls may be tightly interleaved with progressive launches, and when rendering remotely the server may decide to skip some of the launches in order to avoid a large backlog in the command pipeline.
[in] | context | The context in which the launch is to be executed |
[in] | entry_index | The initial entry point into kernel |
[in] | width | Width of the computation grid |
[in] | height | Height of the computation grid |
[in] | max_subframes | The maximum number of subframes to be generated. Set to zero to generate an unlimited number of subframes |
Return values
Relevant return values:
History
rtContextLaunchProgressive2D was introduced in OptiX 3.8.
See also rtContextStopProgressive rtBufferGetProgressiveUpdateReady
RTresult RTAPI rtContextQueryVariable | ( | RTcontext | context, |
const char * | name, | ||
RTvariable * | v | ||
) |
Returns a named variable associated with this context.
Description
rtContextQueryVariable queries a variable identified by the string name from context and stores the result in *v. A variable must be declared with rtContextDeclareVariable before it can be queried, otherwise *v will be set to NULL. RT_ERROR_INVALID_VALUE will be returned if name or v is NULL.
[in] | context | The context node to query a variable from |
[in] | name | The name that identifies the variable to be queried |
[out] | v | Return value to store the queried variable |
Return values
Relevant return values:
History
rtContextQueryVariable was introduced in OptiX 1.0.
See also rtGeometryQueryVariable, rtGeometryInstanceQueryVariable, rtMaterialQueryVariable, rtProgramQueryVariable, rtSelectorQueryVariable, rtContextDeclareVariable, rtContextGetVariableCount, rtContextGetVariable, rtContextRemoveVariable
RTresult RTAPI rtContextRemoveVariable | ( | RTcontext | context, |
RTvariable | v | ||
) |
Removes a variable from the given context.
Description
rtContextRemoveVariable removes variable v from context if present. Returns RT_ERROR_VARIABLE_NOT_FOUND if the variable is not attached to this context. Returns RT_ERROR_INVALID_VALUE if passed an invalid variable.
[in] | context | The context node from which to remove a variable |
[in] | v | The variable to be removed |
Return values
Relevant return values:
History
rtContextRemoveVariable was introduced in OptiX 1.0.
See also rtGeometryRemoveVariable, rtGeometryInstanceRemoveVariable, rtMaterialRemoveVariable, rtProgramRemoveVariable, rtSelectorRemoveVariable, rtContextDeclareVariable, rtContextGetVariable, rtContextGetVariableCount, rtContextQueryVariable,
RTresult RTAPI rtContextSetAttribute | ( | RTcontext | context, |
RTcontextattribute | attrib, | ||
RTsize | size, | ||
void * | p | ||
) |
Set an attribute specific to an OptiX context.
Description
rtContextSetAttribute sets p as the value of the per context attribute specified by attrib.
Each attribute can have a different size. The sizes are given in the following list:
RT_CONTEXT_ATTRIBUTE_CPU_NUM_THREADS sets the number of host CPU threads OptiX can use for various tasks.
RT_CONTEXT_ATTRIBUTE_GPU_PAGING_FORCED_OFF prohibits software paging of device memory. A value of 0 means that OptiX is allowed to activate paging if necessary, 1 means that paging is always off. Note that currently paging cannot be disabled once it has been activated.
[in] | context | The context object to be modified |
[in] | attrib | Attribute to set |
[in] | size | Size of the attribute being set |
[in] | p | Pointer to where the value of the attribute will be copied from. This must point to at least size bytes of memory |
Return values
Relevant return values:
History
rtContextSetAttribute was introduced in OptiX 2.5.
See also rtContextGetAttribute
Specify a list of hardware devices to be used by the kernel.
Description
rtContextSetDevices specifies a list of hardware devices to be used during execution of the subsequent trace kernels.
[in] | context | The context to which the hardware list is applied |
[in] | count | The number of devices in the list |
[in] | devices | The list of devices |
Return values
Relevant return values:
History
rtContextSetDevices was introduced in OptiX 1.0.
See also rtContextGetDevices, rtContextGetDeviceCount
Set the number of entry points for a given context.
Description
rtContextSetEntryPointCount sets the number of entry points associated with the given context to num_entry_points.
[in] | context | The context to be modified |
[in] | num_entry_points | The number of entry points to use |
Return values
Relevant return values:
History
rtContextSetEntryPointCount was introduced in OptiX 1.0.
See also rtContextGetEntryPointCount
RTresult RTAPI rtContextSetExceptionEnabled | ( | RTcontext | context, |
RTexception | exception, | ||
int | enabled | ||
) |
Enable or disable an exception.
Description
rtContextSetExceptionEnabled is used to enable or disable specific exceptions. If an exception is enabled, the exception condition is checked for at runtime, and the exception program is invoked if the condition is met. The exception program can query the type of the caught exception by calling rtGetExceptionCode. exception may take one of the following values:
RT_EXCEPTION_TEXTURE_ID_INVALID verifies that every access of a texture id is valid, including use of RT_TEXTURE_ID_NULL and IDs out of bounds.
RT_EXCEPTION_BUFFER_ID_INVALID verifies that every access of a buffer id is valid, including use of RT_BUFFER_ID_NULL and IDs out of bounds.
RT_EXCEPTION_INDEX_OUT_OF_BOUNDS checks that rtIntersectChild and rtReportIntersection are called with a valid index.
RT_EXCEPTION_STACK_OVERFLOW checks the runtime stack against overflow. The most common cause for an overflow is a too deep rtTrace recursion tree.
RT_EXCEPTION_BUFFER_INDEX_OUT_OF_BOUNDS checks every read and write access to rtBuffer objects to be within valid bounds.
RT_EXCEPTION_INVALID_RAY checks the each ray's origin and direction values against NaNs and infinity values.
RT_EXCEPTION_INTERNAL_ERROR indicates an unexpected internal error in the runtime.
RT_EXCEPTION_USER is used to enable or disable all user-defined exceptions. The reserved range of exception codes for user-defined exceptions starts at RT_EXCEPTION_USER (0x400) and ends at 0xFFFF. See rtThrow for more information.
RT_EXCEPTION_ALL is a placeholder value which can be used to enable or disable all possible exceptions with a single call to rtContextSetExceptionEnabled.
By default, RT_EXCEPTION_STACK_OVERFLOW is enabled and all other exceptions are disabled.
[in] | context | The context for which the exception is to be enabled or disabled |
[in] | exception | The exception which is to be enabled or disabled |
[in] | enabled | Nonzero to enable the exception, 0 to disable the exception |
Return values
Relevant return values:
History
rtContextSetExceptionEnabled was introduced in OptiX 1.1.
See also rtContextGetExceptionEnabled, rtContextSetExceptionProgram, rtContextGetExceptionProgram, rtGetExceptionCode, rtThrow, rtPrintExceptionDetails
RTresult RTAPI rtContextSetExceptionProgram | ( | RTcontext | context, |
unsigned int | entry_point_index, | ||
RTprogram | program | ||
) |
Specifies the exception program for a given context entry point.
Description
rtContextSetExceptionProgram sets context's exception program at entry point entry_point_index. RT_ERROR_INVALID_VALUE is returned if entry_point_index is outside of the range [0, rtContextGetEntryPointCount -1].
[in] | context | The context node to which the exception program will be added |
[in] | entry_point_index | The entry point the program will be associated with |
[in] | program | The exception program |
Return values
Relevant return values:
History
rtContextSetExceptionProgram was introduced in OptiX 1.0.
See also rtContextGetEntryPointCount, rtContextGetExceptionProgram rtContextSetExceptionEnabled, rtContextGetExceptionEnabled, rtGetExceptionCode, rtThrow, rtPrintExceptionDetails
RTresult RTAPI rtContextSetMissProgram | ( | RTcontext | context, |
unsigned int | ray_type_index, | ||
RTprogram | program | ||
) |
Specifies the miss program for a given context ray type.
Description
rtContextSetMissProgram sets context's miss program associated with ray type ray_type_index. RT_ERROR_INVALID_VALUE is returned if ray_type_index is outside of the range [0, rtContextGetRayTypeCount -1].
[in] | context | The context node to which the miss program will be added |
[in] | ray_type_index | The ray type the program will be associated with |
[in] | program | The miss program |
Return values
Relevant return values:
History
rtContextSetMissProgram was introduced in OptiX 1.0.
Set the size of the print buffer.
Description
rtContextSetPrintBufferSize is used to set the buffer size available to hold data generated by rtPrintf. The default size is 65536 bytes.
[in] | context | The context for which to set the print buffer size |
[in] | buffer_size_bytes | The print buffer size in bytes |
Return values
Relevant return values:
History
rtContextSetPrintBufferSize was introduced in OptiX 1.0.
See also rtPrintf, rtContextSetPrintEnabled, rtContextGetPrintEnabled, rtContextGetPrintBufferSize, rtContextSetPrintLaunchIndex, rtContextGetPrintLaunchIndex
Enable or disable text printing from programs.
Description
rtContextSetPrintEnabled is used to control whether text printing in programs through rtPrintf is currently enabled for this context.
[in] | context | The context for which printing is to be enabled or disabled |
[in] | enabled | Setting this parameter to a nonzero value enables printing, 0 disables printing |
Return values
Relevant return values:
History
rtContextSetPrintEnabled was introduced in OptiX 1.0.
See also rtPrintf, rtContextGetPrintEnabled, rtContextSetPrintBufferSize, rtContextGetPrintBufferSize, rtContextSetPrintLaunchIndex, rtContextGetPrintLaunchIndex
Sets the active launch index to limit text output.
Description
rtContextSetPrintLaunchIndex is used to control for which launch indices rtPrintf generates output. The initial value of (x,y,z) is (-1,-1,-1), which generates output for all indices.
[in] | context | The context for which to set the print launch index |
[in] | x | The launch index in the x dimension to which to limit the output of rtPrintf invocations. If set to -1, output is generated for all launch indices in the x dimension |
[in] | y | The launch index in the y dimension to which to limit the output of rtPrintf invocations. If set to -1, output is generated for all launch indices in the y dimension |
[in] | z | The launch index in the z dimension to which to limit the output of rtPrintf invocations. If set to -1, output is generated for all launch indices in the z dimension |
Return values
Relevant return values:
History
rtContextSetPrintLaunchIndex was introduced in OptiX 1.0.
See also rtPrintf, rtContextGetPrintEnabled, rtContextSetPrintEnabled, rtContextSetPrintBufferSize, rtContextGetPrintBufferSize, rtContextGetPrintLaunchIndex
RTresult RTAPI rtContextSetRayGenerationProgram | ( | RTcontext | context, |
unsigned int | entry_point_index, | ||
RTprogram | program | ||
) |
Specifies the ray generation program for a given context entry point.
Description
rtContextSetRayGenerationProgram sets context's ray generation program at entry point entry_point_index. RT_ERROR_INVALID_VALUE is returned if entry_point_index is outside of the range [0, rtContextGetEntryPointCount -1].
[in] | context | The context node to which the exception program will be added |
[in] | entry_point_index | The entry point the program will be associated with |
[in] | program | The ray generation program |
Return values
Relevant return values:
History
rtContextSetRayGenerationProgram was introduced in OptiX 1.0.
See also rtContextGetEntryPointCount, rtContextGetRayGenerationProgram
Sets the number of ray types for a given context.
Description
rtContextSetRayTypeCount Sets the number of ray types associated with the given context.
[in] | context | The context node |
[in] | num_ray_types | The number of ray types to be used |
Return values
Relevant return values:
History
rtContextSetRayTypeCount was introduced in OptiX 1.0.
See also rtContextGetRayTypeCount
RTresult RTAPI rtContextSetRemoteDevice | ( | RTcontext | context, |
RTremotedevice | remote_dev | ||
) |
Enable rendering on a remote device.
Description
Associates a context with a remote device. If successful, any further OptiX calls will be directed to the remote device and executed there. The context must be an empty, newly created context. In other words, in order to use a context remotely, the call to rtContextSetRemoteDevice should immediately follow the call to rtContextCreate.
Note that a context that was used for remote rendering cannot be re-used for local rendering by changing devices. However, the Progressive API (that is, rtContextLaunchProgressive2D, stream buffers, etc.) can be used locally by simply not creating a remote device and not calling rtContextSetRemoteDevice.
Only a single remote device can be associated with a context. Switching between different remote devices is not supported.
[in] | context | Newly created context to use on the remote device |
[in] | remote_dev | Remote device on which rendering is to be executed |
Return values
Relevant return values:
History
rtContextSetRemoteDevice was introduced in OptiX 3.8.
See also rtRemoteDeviceCreate rtRemoteDeviceGetAttribute rtRemoteDeviceReserve rtContextLaunchProgressive2D
Set the stack size for a given context.
Description
rtContextSetStackSize sets the stack size for the given context to stack_size_bytes bytes. Returns RT_ERROR_INVALID_VALUE if context is not valid.
[in] | context | The context node to be modified |
[in] | stack_size_bytes | The desired stack size in bytes |
Return values
Relevant return values:
History
rtContextSetStackSize was introduced in OptiX 1.0.
See also rtContextGetStackSize
RTresult RTAPI rtContextSetTimeoutCallback | ( | RTcontext | context, |
RTtimeoutcallback | callback, | ||
double | min_polling_seconds | ||
) |
Side timeout callback function.
Description
rtContextSetTimeoutCallback sets an application-side callback function callback and a time interval min_polling_seconds in seconds. Long-running OptiX API calls such as rtContextCompile and rtContextLaunch call the callback function about every min_polling_seconds seconds. The core purpose of a timeout callback function is to give the application a chance to do whatever it might need to do frequently, such as handling GUI events.
If the callback function returns true, the API call tries to abort, leaving the context in a clean but unfinished state. Output buffers are left in an unpredictable state. In case an OptiX API call is terminated by a callback function, it returns RT_TIMEOUT_CALLBACK.
As a side effect, timeout functions also help control the OptiX kernel run-time. This can in some cases prevent OptiX kernel launches from running so long that they cause driver timeouts. For example, if min_polling_seconds is 0.5 seconds then once the kernel has been running for 0.5 seconds it won't start any new launch indices (calls to a ray generation program). Thus, if the driver's timeout is 2 seconds (the default on Windows), then a launch index may take up to 1.5 seconds without triggering a driver timeout.
RTtimeoutcallback is defined as int (*RTtimeoutcallback)(void).
To unregister a callback function, callback needs to be set to NULL and min_polling_seconds to 0.
Only one timeout callback function can be specified at any time.
Returns RT_ERROR_INVALID_VALUE if context is not valid, if min_polling_seconds is negative, if callback is NULL but min_polling_seconds is not 0, or if callback is not NULL but min_polling_seconds is 0.
[in] | context | The context node to be modified |
[in] | callback | The function to be called |
[in] | min_polling_seconds | The timeout interval after which the function is called |
Return values
Relevant return values:
History
rtContextSetTimeoutCallback was introduced in OptiX 2.5.
See also rtContextCompile, rtContextLaunch
Stops a Progressive Launch.
Description
If a progressive launch is currently in progress, calling rtContextStopProgressive terminates it. Otherwise, the call has no effect. If a launch is stopped using this function, no further subframes will arrive at the client, even if they have already been generated by the server and are currently in flight.
This call should only be used if the application must guarantee that frames generated by previous progressive launches won't be accessed. Do not call rtContextStopProgressive in the main rendering loop if the goal is only to change OptiX state (e.g. rtVariable values). The call is unnecessary in that case and will degrade performance.
[in] | context | The context associated with the progressive launch |
Return values
Relevant return values:
History
rtContextStopProgressive was introduced in OptiX 3.8.
See also rtContextLaunchProgressive2D
Checks the given context for valid internal state.
Description
rtContextValidate checks the the given context and all of its associated OptiX objects for a valid state. These checks include tests for presence of necessary programs (e.g. an intersection program for a geometry node), invalid internal state such as NULL children in graph nodes, and presence of variables required by all specified programs. rtContextGetErrorString can be used to retrieve a description of a validation failure.
[in] | context | The context to be validated |
Return values
Relevant return values:
History
rtContextValidate was introduced in OptiX 1.0.
See also rtContextGetErrorString
RTresult RTAPI rtDeviceGetAttribute | ( | int | ordinal, |
RTdeviceattribute | attrib, | ||
RTsize | size, | ||
void * | p | ||
) |
Returns an attribute specific to an OptiX device.
Description
rtDeviceGetAttribute returns in p the value of the per device attribute specified by attrib for device ordinal.
Each attribute can have a different size. The sizes are given in the following list:
[in] | ordinal | OptiX device ordinal |
[in] | attrib | Attribute to query |
[in] | size | Size of the attribute being queried. Parameter p must have at least this much memory allocated |
[out] | p | Return pointer where the value of the attribute will be copied into. This must point to at least size bytes of memory |
Return values
Relevant return values:
History
rtDeviceGetAttribute was introduced in OptiX 2.0. RT_DEVICE_ATTRIBUTE_TCC_DRIVER was introduced in OptiX 3.0. RT_DEVICE_ATTRIBUTE_CUDA_DEVICE_ORDINAL was introduced in OptiX 3.0.
See also rtDeviceGetDeviceCount, rtContextGetAttribute
RTresult RTAPI rtDeviceGetDeviceCount | ( | unsigned int * | count | ) |
Returns the number of OptiX capable devices.
Description
rtDeviceGetDeviceCount returns in count the number of compute devices that are available in the host system and will be used by OptiX.
[out] | count | Number devices available for OptiX |
Return values
Relevant return values:
History
rtDeviceGetDeviceCount was introduced in OptiX 1.0.
See also rtGetVersion
RTresult RTAPI rtGeometryCreate | ( | RTcontext | context, |
RTgeometry * | geometry | ||
) |
Creates a new geometry node.
Description
rtGeometryCreate creates a new geometry node within a context. context specifies the target context, and should be a value returned by rtContextCreate. Sets *geometry to the handle of a newly created geometry within context. Returns RT_ERROR_INVALID_VALUE if geometry is NULL.
[in] | context | Specifies the rendering context of the Geometry node |
[out] | geometry | New Geometry node handle |
Return values
Relevant return values:
History
rtGeometryCreate was introduced in OptiX 1.0.
See also rtGeometryDestroy, rtGeometrySetBoundingBoxProgram, rtGeometrySetIntersectionProgram
RTresult RTAPI rtGeometryDeclareVariable | ( | RTgeometry | geometry, |
const char * | name, | ||
RTvariable * | v | ||
) |
Declares a new named variable associated with a geometry instance.
Description
rtGeometryDeclareVariable declares a new variable associated with a geometry node. geometry specifies the target geometry node, and should be a value returned by rtGeometryCreate. name specifies the name of the variable, and should be a NULL-terminated string. If there is currently no variable associated with geometry named name, a new variable named name will be created and associated with geometry. Returns the handle of the newly-created variable in *v or NULL otherwise. After declaration, the variable can be queried with rtGeometryQueryVariable or rtGeometryGetVariable. A declared variable does not have a type until its value is set with one of the rtVariableSet functions. Once a variable is set, its type cannot be changed anymore.
[in] | geometry | Specifies the associated Geometry node |
[in] | name | The name that identifies the variable |
[out] | v | Returns a handle to a newly declared variable |
Return values
Relevant return values:
History
rtGeometryDeclareVariable was introduced in OptiX 1.0.
See also Variables, rtGeometryQueryVariable, rtGeometryGetVariable, rtGeometryRemoveVariable
RTresult RTAPI rtGeometryDestroy | ( | RTgeometry | geometry | ) |
Destroys a geometry node.
Description
rtGeometryDestroy removes geometry from its context and deletes it. geometry should be a value returned by rtGeometryCreate. Associated variables declared via rtGeometryDeclareVariable are destroyed, but no child graph nodes are destroyed. After the call, geometry is no longer a valid handle.
[in] | geometry | Handle of the geometry node to destroy |
Return values
Relevant return values:
History
rtGeometryDestroy was introduced in OptiX 1.0.
See also rtGeometryCreate, rtGeometrySetPrimitiveCount, rtGeometryGetPrimitiveCount
RTresult RTAPI rtGeometryGetBoundingBoxProgram | ( | RTgeometry | geometry, |
RTprogram * | program | ||
) |
Returns the attached bounding box program.
Description
rtGeometryGetBoundingBoxProgram returns the handle program for the attached bounding box program of geometry.
[in] | geometry | Geometry node handle from which to query program |
[out] | program | Handle to attached bounding box program |
Return values
Relevant return values:
History
rtGeometryGetBoundingBoxProgram was introduced in OptiX 1.0.
See also rtGeometrySetBoundingBoxProgram
RTresult RTAPI rtGeometryGetContext | ( | RTgeometry | geometry, |
RTcontext * | context | ||
) |
Returns the context associated with a geometry node.
Description
rtGeometryGetContext queries a geometry node for its associated context. geometry specifies the geometry node to query, and should be a value returned by rtGeometryCreate. Sets *context to the context associated with geometry.
[in] | geometry | Specifies the geometry to query |
[out] | context | The context associated with geometry |
Return values
Relevant return values:
History
rtGeometryGetContext was introduced in OptiX 1.0.
See also rtGeometryCreate
RTresult RTAPI rtGeometryGetIntersectionProgram | ( | RTgeometry | geometry, |
RTprogram * | program | ||
) |
Returns the attached intersection program.
Description
rtGeometryGetIntersectionProgram returns in program a handle of the attached intersection program.
[in] | geometry | Geometry node handle to query program |
[out] | program | Handle to attached intersection program |
Return values
Relevant return values:
History
rtGeometryGetIntersectionProgram was introduced in OptiX 1.0.
See also rtGeometrySetIntersectionProgram, rtProgramCreateFromPTXFile, rtProgramCreateFromPTXString
RTresult RTAPI rtGeometryGetPrimitiveCount | ( | RTgeometry | geometry, |
unsigned int * | num_primitives | ||
) |
Returns the number of primitives.
Description
rtGeometryGetPrimitiveCount returns for geometry the number of set primitives. The number of primitvies can be set with rtGeometryGetPrimitiveCount.
[in] | geometry | Geometry node to query from the number of primitives |
[out] | num_primitives | Number of primitives |
Return values
Relevant return values:
History
rtGeometryGetPrimitiveCount was introduced in OptiX 1.0.
See also rtGeometrySetPrimitiveCount
RTresult RTAPI rtGeometryGetPrimitiveIndexOffset | ( | RTgeometry | geometry, |
unsigned int * | index_offset | ||
) |
Returns the current primitive index offset.
Description
rtGeometryGetPrimitiveIndexOffset returns for geometry the primitive index offset. The primitive index offset can be set with rtGeometrySetPrimitiveIndexOffset.
[in] | geometry | Geometry node to query for the primitive index offset |
[out] | index_offset | Primitive index offset |
Return values
Relevant return values:
History
rtGeometryGetPrimitiveIndexOffset was introduced in OptiX 3.5.
See also rtGeometrySetPrimitiveIndexOffset
RTresult RTAPI rtGeometryGetVariable | ( | RTgeometry | geometry, |
unsigned int | index, | ||
RTvariable * | v | ||
) |
Returns a handle to an indexed variable of a geometry node.
Description
rtGeometryGetVariable queries the handle of a geometry node's indexed variable. geometry specifies the target geometry and should be a value returned by rtGeometryCreate. index specifies the index of the variable, and should be a value less than rtGeometryGetVariableCount. If index is the index of a variable attached to geometry, returns its handle in *v or NULL otherwise. *v must be declared first with rtGeometryDeclareVariable before it can be queried.
[in] | geometry | The geometry node from which to query a variable |
[in] | index | The index that identifies the variable to be queried |
[out] | v | Returns handle to indexed variable |
Return values
Relevant return values:
History
rtGeometryGetVariable was introduced in OptiX 1.0.
See also rtGeometryDeclareVariable, rtGeometryGetVariableCount, rtGeometryRemoveVariable, rtGeometryQueryVariable
RTresult RTAPI rtGeometryGetVariableCount | ( | RTgeometry | geometry, |
unsigned int * | count | ||
) |
Returns the number of attached variables.
Description
rtGeometryGetVariableCount queries the number of variables attached to a geometry node. geometry specifies the geometry node, and should be a value returned by rtGeometryCreate. After the call, the number of variables attached to geometry is returned to *count.
[in] | geometry | The Geometry node to query from the number of attached variables |
[out] | count | Returns the number of attached variables |
Return values
Relevant return values:
History
rtGeometryGetVariableCount was introduced in OptiX 1.0.
See also rtGeometryGetVariableCount, rtGeometryDeclareVariable, rtGeometryRemoveVariable
RTresult RTAPI rtGeometryGroupCreate | ( | RTcontext | context, |
RTgeometrygroup * | geometrygroup | ||
) |
Creates a new geometry group.
Description
rtGeometryGroupCreate creates a new geometry group within a context. context specifies the target context, and should be a value returned by rtContextCreate. Sets *geometrygroup to the handle of a newly created geometry group within context. Returns RT_ERROR_INVALID_VALUE if geometrygroup is NULL.
[in] | context | Specifies a context within which to create a new geometry group |
[out] | geometrygroup | Returns a newly created geometry group |
Return values
Relevant return values:
History
rtGeometryGroupCreate was introduced in OptiX 1.0.
See also rtGeometryGroupDestroy, rtContextCreate
RTresult RTAPI rtGeometryGroupDestroy | ( | RTgeometrygroup | geometrygroup | ) |
Destroys a geometry group node.
Description
rtGeometryGroupDestroy removes geometrygroup from its context and deletes it. geometrygroup should be a value returned by rtGeometryGroupCreate. No child graph nodes are destroyed. After the call, geometrygroup is no longer a valid handle.
[in] | geometrygroup | Handle of the geometry group node to destroy |
Return values
Relevant return values:
History
rtGeometryGroupDestroy was introduced in OptiX 1.0.
See also rtGeometryGroupCreate
RTresult RTAPI rtGeometryGroupGetAcceleration | ( | RTgeometrygroup | geometrygroup, |
RTacceleration * | acceleration | ||
) |
Returns the acceleration structure attached to a geometry group.
Description
rtGeometryGroupGetAcceleration returns the acceleration structure attached to a geometry group using rtGeometryGroupSetAcceleration. If no acceleration structure has previously been set, *acceleration is set to NULL.
[in] | geometrygroup | The geometry group handle |
[out] | acceleration | The returned acceleration structure object |
Return values
Relevant return values:
History
rtGeometryGroupGetAcceleration was introduced in OptiX 1.0.
See also rtGeometryGroupSetAcceleration, rtAccelerationCreate
RTresult RTAPI rtGeometryGroupGetChild | ( | RTgeometrygroup | geometrygroup, |
unsigned int | index, | ||
RTgeometryinstance * | geometryinstance | ||
) |
Returns a child node of a geometry group.
Description
rtGeometryGroupGetChild returns the child geometry instance at slot index of the parent geometrygroup. If no child has been assigned to the given slot, *geometryinstance is set to NULL. Returns RT_ERROR_INVALID_VALUE if given an invalid child index or NULL pointer.
[in] | geometrygroup | The parent geometry group handle |
[in] | index | The index of the child slot to query |
[out] | geometryinstance | The returned child geometry instance |
Return values
Relevant return values:
History
rtGeometryGroupGetChild was introduced in OptiX 1.0.
See also rtGeometryGroupSetChild, rtGeometryGroupSetChildCount, rtGeometryGroupGetChildCount,
RTresult RTAPI rtGeometryGroupGetChildCount | ( | RTgeometrygroup | geometrygroup, |
unsigned int * | count | ||
) |
Returns the number of child slots for a group.
Description
rtGeometryGroupGetChildCount returns the number of child slots allocated using rtGeometryGroupSetChildCount. This includes empty slots which may not yet have actual children assigned by rtGeometryGroupSetChild.
[in] | geometrygroup | The parent geometry group handle |
[out] | count | Returned number of child slots |
Return values
Relevant return values:
History
rtGeometryGroupGetChildCount was introduced in OptiX 1.0.
See also rtGeometryGroupSetChild, rtGeometryGroupGetChild, rtGeometryGroupSetChildCount
RTresult RTAPI rtGeometryGroupGetContext | ( | RTgeometrygroup | geometrygroup, |
RTcontext * | context | ||
) |
Returns the context associated with a geometry group.
Description
rtGeometryGroupGetContext queries a geometry group for its associated context. geometrygroup specifies the geometry group to query, and must be a value returned by rtGeometryGroupCreate. Sets *context to the context associated with geometrygroup.
[in] | geometrygroup | Specifies the geometry group to query |
[out] | context | Returns the context associated with the geometry group |
Return values
Relevant return values:
History
rtGeometryGroupGetContext was introduced in OptiX 1.0.
See also rtContextCreate, rtGeometryGroupCreate
RTresult RTAPI rtGeometryGroupSetAcceleration | ( | RTgeometrygroup | geometrygroup, |
RTacceleration | acceleration | ||
) |
Set the acceleration structure for a group.
Description
rtGeometryGroupSetAcceleration attaches an acceleration structure to a geometry group. The acceleration structure must have been previously created using rtAccelerationCreate. Every geometry group is required to have an acceleration structure assigned in order to pass validation. The acceleration structure will be built over the primitives contained in all children of the geometry group. This enables a single acceleration structure to be built over primitives of multiple geometry instances. Note that it is legal to attach a single RTacceleration object to multiple geometry groups, as long as the underlying geometry of all children is the same. This corresponds to attaching an acceleration structure to multiple groups at higher graph levels using rtGroupSetAcceleration.
[in] | geometrygroup | The geometry group handle |
[in] | acceleration | The acceleration structure to attach to the geometry group |
Return values
Relevant return values:
History
rtGeometryGroupSetAcceleration was introduced in OptiX 1.0.
See also rtGeometryGroupGetAcceleration, rtAccelerationCreate, rtGroupSetAcceleration
RTresult RTAPI rtGeometryGroupSetChild | ( | RTgeometrygroup | geometrygroup, |
unsigned int | index, | ||
RTgeometryinstance | geometryinstance | ||
) |
Attaches a child node to a geometry group.
Description
rtGeometryGroupSetChild attaches a new child node geometryinstance to the parent node geometrygroup. index specifies the number of the slot where the child node gets attached. The index value must be lower than the number previously set by rtGeometryGroupSetChildCount.
[in] | geometrygroup | The parent geometry group handle |
[in] | index | The index in the parent's child slot array |
[in] | geometryinstance | The child node to be attached |
Return values
Relevant return values:
History
rtGeometryGroupSetChild was introduced in OptiX 1.0.
See also rtGeometryGroupSetChildCount, rtGeometryGroupGetChildCount, rtGeometryGroupGetChild
RTresult RTAPI rtGeometryGroupSetChildCount | ( | RTgeometrygroup | geometrygroup, |
unsigned int | count | ||
) |
Sets the number of child nodes to be attached to the group.
Description
rtGeometryGroupSetChildCount specifies the number of child slots in this geometry 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 rtGeometryGroupSetChild before validation.
[in] | geometrygroup | The parent geometry group handle |
[in] | count | Number of child slots to allocate for the geometry group |
Return values
Relevant return values:
History
rtGeometryGroupSetChildCount was introduced in OptiX 1.0.
See also rtGeometryGroupGetChild, rtGeometryGroupGetChildCount rtGeometryGroupSetChild
RTresult RTAPI rtGeometryGroupValidate | ( | RTgeometrygroup | geometrygroup | ) |
Validates the state of the geometry group.
Description
rtGeometryGroupValidate checks geometrygroup for completeness. If geometrygroup or any of the objects attached to geometrygroup are not valid, returns RT_ERROR_INVALID_VALUE.
[in] | geometrygroup | Specifies the geometry group to be validated |
Return values
Relevant return values:
History
rtGeometryGroupValidate was introduced in OptiX 1.0.
See also rtGeometryGroupCreate
RTresult RTAPI rtGeometryInstanceCreate | ( | RTcontext | context, |
RTgeometryinstance * | geometryinstance | ||
) |
Creates a new geometry instance node.
Description
rtGeometryInstanceCreate creates a new geometry instance node within a context. context specifies the target context, and should be a value returned by rtContextCreate. Sets *geometryinstance to the handle of a newly created geometry instance within context. Returns RT_ERROR_INVALID_VALUE if geometryinstance is NULL.
[in] | context | Specifies the rendering context of the GeometryInstance node |
[out] | geometryinstance | New GeometryInstance node handle |
Return values
Relevant return values:
History
rtGeometryInstanceCreate was introduced in OptiX 1.0.
See also rtGeometryInstanceDestroy, rtGeometryInstanceDestroy, rtGeometryInstanceGetContext
RTresult RTAPI rtGeometryInstanceDeclareVariable | ( | RTgeometryinstance | geometryinstance, |
const char * | name, | ||
RTvariable * | v | ||
) |
Declares a new named variable associated with a geometry node.
Description
rtGeometryInstanceDeclareVariable declares a new variable associated with a geometry instance node. geometryinstance specifies the target geometry node, and should be a value returned by rtGeometryInstanceCreate. name specifies the name of the variable, and should be a NULL-terminated string. If there is currently no variable associated with geometryinstance named name, a new variable named name will be created and associated with geometryinstance. After the call, *v will be set to the handle of the newly-created variable. Otherwise, *v will be set to NULL. After declaration, the variable can be queried with rtGeometryInstanceQueryVariable or rtGeometryInstanceGetVariable. A declared variable does not have a type until its value is set with one of the rtVariableSet functions. Once a variable is set, its type cannot be changed anymore.
[in] | geometryinstance | Specifies the associated GeometryInstance node |
[in] | name | The name that identifies the variable |
[out] | v | Returns a handle to a newly declared variable |
Return values
Relevant return values:
History
rtGeometryInstanceDeclareVariable was introduced in OptiX 1.0.
See also Variables, rtGeometryInstanceQueryVariable, rtGeometryInstanceGetVariable, rtGeometryInstanceRemoveVariable
RTresult RTAPI rtGeometryInstanceDestroy | ( | RTgeometryinstance | geometryinstance | ) |
Destroys a geometry instance node.
Description
rtGeometryInstanceDestroy removes geometryinstance from its context and deletes it. geometryinstance should be a value returned by rtGeometryInstanceCreate. Associated variables declared via rtGeometryInstanceDeclareVariable are destroyed, but no child graph nodes are destroyed. After the call, geometryinstance is no longer a valid handle.
[in] | geometryinstance | Handle of the geometry instance node to destroy |
Return values
Relevant return values:
History
rtGeometryInstanceDestroy was introduced in OptiX 1.0.
See also rtGeometryInstanceCreate
RTresult RTAPI rtGeometryInstanceGetContext | ( | RTgeometryinstance | geometryinstance, |
RTcontext * | context | ||
) |
Returns the context associated with a geometry instance node.
Description
rtGeometryInstanceGetContext queries a geometry instance node for its associated context. geometryinstance specifies the geometry node to query, and should be a value returned by rtGeometryInstanceCreate. Sets *context to the context associated with geometryinstance.
[in] | geometryinstance | Specifies the geometry instance |
[out] | context | Handle for queried context |
Return values
Relevant return values:
History
rtGeometryInstanceGetContext was introduced in OptiX 1.0.
See also rtGeometryInstanceGetContext
RTresult RTAPI rtGeometryInstanceGetGeometry | ( | RTgeometryinstance | geometryinstance, |
RTgeometry * | geometry | ||
) |
Returns the attached Geometry node.
Description
rtGeometryInstanceGetGeometry sets geometry to the handle of the attached Geometry node. If no Geometry node is attached, RT_ERROR_INVALID_VALUE is returned, else RT_SUCCESS.
[in] | geometryinstance | GeometryInstance node handle to query geometry |
[out] | geometry | Handle to attached Geometry node |
Return values
Relevant return values:
History
rtGeometryInstanceGetGeometry was introduced in OptiX 1.0.
See also rtGeometryInstanceCreate, rtGeometryInstanceDestroy, rtGeometryInstanceValidate, rtGeometryInstanceSetGeometry
RTresult RTAPI rtGeometryInstanceGetMaterial | ( | RTgeometryinstance | geometryinstance, |
unsigned int | index, | ||
RTmaterial * | material | ||
) |
Returns a material handle.
Description
rtGeometryInstanceGetMaterial returns handle material for the Material node at position index in the material list of geometryinstance. Returns RT_ERROR_INVALID_VALUE if index is invalid.
[in] | geometryinstance | GeometryInstance node handle to query material |
[in] | index | Index of material |
[out] | material | Handle to material |
Return values
Relevant return values:
History
rtGeometryInstanceGetMaterial was introduced in OptiX 1.0.
See also rtGeometryInstanceGetMaterialCount, rtGeometryInstanceSetMaterial
RTresult RTAPI rtGeometryInstanceGetMaterialCount | ( | RTgeometryinstance | geometryinstance, |
unsigned int * | count | ||
) |
Returns the number of attached materials.
Description
rtGeometryInstanceGetMaterialCount returns for geometryinstance the number of attached Material nodes count. The number of materies can be set with rtGeometryInstanceSetMaterialCount.
[in] | geometryinstance | GeometryInstance node to query from the number of materials |
[out] | count | Number of attached materials |
Return values
Relevant return values:
History
rtGeometryInstanceGetMaterialCount was introduced in OptiX 1.0.
See also rtGeometryInstanceSetMaterialCount
RTresult RTAPI rtGeometryInstanceGetVariable | ( | RTgeometryinstance | geometryinstance, |
unsigned int | index, | ||
RTvariable * | v | ||
) |
Returns a handle to an indexed variable of a geometry instance node.
Description
rtGeometryInstanceGetVariable queries the handle of a geometry instance's indexed variable. geometryinstance specifies the target geometry instance and should be a value returned by rtGeometryInstanceCreate. index specifies the index of the variable, and should be a value less than rtGeometryInstanceGetVariableCount. If index is the index of a variable attached to geometryinstance, returns a handle to that variable in *v, and NULL otherwise. *v must be declared first with rtGeometryInstanceDeclareVariable before it can be queried.
[in] | geometryinstance | The GeometryInstance node from which to query a variable |
[in] | index | The index that identifies the variable to be queried |
[out] | v | Returns handle to indexed variable |
Return values
Relevant return values:
History
rtGeometryInstanceGetVariable was introduced in OptiX 1.0.
See also rtGeometryDeclareVariable, rtGeometryGetVariableCount, rtGeometryRemoveVariable, rtGeometryQueryVariable
RTresult RTAPI rtGeometryInstanceGetVariableCount | ( | RTgeometryinstance | geometryinstance, |
unsigned int * | count | ||
) |
Returns the number of attached variables.
Description
rtGeometryInstanceGetVariableCount queries the number of variables attached to a geometry instance. geometryinstance specifies the geometry instance, and should be a value returned by rtGeometryInstanceCreate. After the call, the number of variables attached to geometryinstance is returned to *count.
[in] | geometryinstance | The GeometryInstance node to query from the number of attached variables |
[out] | count | Returns the number of attached variables |
Return values
Relevant return values:
History
rtGeometryInstanceGetVariableCount was introduced in OptiX 1.0.
See also rtGeometryInstanceGetVariableCount, rtGeometryInstanceDeclareVariable, rtGeometryInstanceRemoveVariable
RTresult RTAPI rtGeometryInstanceQueryVariable | ( | RTgeometryinstance | geometryinstance, |
const char * | name, | ||
RTvariable * | v | ||
) |
Returns a handle to a named variable of a geometry node.
Description
rtGeometryInstanceQueryVariable queries the handle of a geometry instance node's named variable. geometryinstance specifies the target geometry instance node, as returned by rtGeometryInstanceCreate. name specifies the name of the variable, and should be a NULL -terminated string. If name is the name of a variable attached to geometryinstance, returns a handle to that variable in *v, otherwise NULL. Geometry instance variables have to be declared with rtGeometryInstanceDeclareVariable before they can be queried.
[in] | geometryinstance | The GeometryInstance node to query from a variable |
[in] | name | The name that identifies the variable to be queried |
[out] | v | Returns the named variable |
Return values
Relevant return values:
History
rtGeometryInstanceQueryVariable was introduced in OptiX 1.0.
See also rtGeometryInstanceDeclareVariable, rtGeometryInstanceRemoveVariable, rtGeometryInstanceGetVariableCount, rtGeometryInstanceGetVariable
RTresult RTAPI rtGeometryInstanceRemoveVariable | ( | RTgeometryinstance | geometryinstance, |
RTvariable | v | ||
) |
Removes a named variable from a geometry instance node.
Description
rtGeometryInstanceRemoveVariable removes a named variable from a geometry instance. The target geometry instance is specified by geometryinstance, which should be a value returned by rtGeometryInstanceCreate. The variable to be removed is specified by v, which should be a value returned by rtGeometryInstanceDeclareVariable. Once a variable has been removed from this geometry instance, another variable with the same name as the removed variable may be declared.
[in] | geometryinstance | The GeometryInstance node from which to remove a variable |
[in] | v | The variable to be removed |
Return values
Relevant return values:
History
rtGeometryInstanceRemoveVariable was introduced in OptiX 1.0.
See also rtContextRemoveVariable, rtGeometryInstanceDeclareVariable
RTresult RTAPI rtGeometryInstanceSetGeometry | ( | RTgeometryinstance | geometryinstance, |
RTgeometry | geometry | ||
) |
Attaches a Geometry node.
Description
rtGeometryInstanceSetGeometry attaches a Geometry node to a GeometryInstance. Only one Geometry node can be attached to a GeometryInstance. However, it is at any time possible to attach a different Geometry node.
[in] | geometryinstance | GeometryInstance node handle to attach geometry |
[in] | geometry | Geometry handle to attach to geometryinstance |
Return values
Relevant return values:
History
rtGeometryInstanceSetGeometry was introduced in OptiX 1.0.
See also rtGeometryInstanceGetGeometry
RTresult RTAPI rtGeometryInstanceSetMaterial | ( | RTgeometryinstance | geometryinstance, |
unsigned int | index, | ||
RTmaterial | material | ||
) |
Sets a material.
Description
rtGeometryInstanceSetMaterial attaches material to geometryinstance at position index in its internal Material node list. index must be in the range 0 to rtGeometryInstanceGetMaterialCount - 1.
[in] | geometryinstance | GeometryInstance node for which to set a material |
[in] | index | Index into the material list |
[in] | material | Material handle to attach to geometryinstance |
Return values
Relevant return values:
History
rtGeometryInstanceSetMaterial was introduced in OptiX 1.0.
See also rtGeometryInstanceGetMaterialCount, rtGeometryInstanceSetMaterialCount
RTresult RTAPI rtGeometryInstanceSetMaterialCount | ( | RTgeometryinstance | geometryinstance, |
unsigned int | count | ||
) |
Sets the number of materials.
Description
rtGeometryInstanceSetMaterialCount sets the number of materials count that will be attached to geometryinstance. The number of attached materials can be changed at any time. Increasing the number of materials will not modify already assigned materials. Decreasing the number of materials will not modify the remaining already assigned materials.
[in] | geometryinstance | GeometryInstance node to set number of materials |
[in] | count | Number of materials to be set |
Return values
Relevant return values:
History
rtGeometryInstanceSetMaterialCount was introduced in OptiX 1.0.
See also rtGeometryInstanceGetMaterialCount
RTresult RTAPI rtGeometryInstanceValidate | ( | RTgeometryinstance | geometryinstance | ) |
Checks a GeometryInstance node for internal consistency.
Description
rtGeometryInstanceValidate checks geometryinstance for completeness. If geomertryinstance or any of the objects attached to geometry are not valid, returns RT_ERROR_INVALID_VALUE.
[in] | geometryinstance | GeometryInstance node of a model sub-tree to be validated |
Return values
Relevant return values:
History
rtGeometryInstanceValidate was introduced in OptiX 1.0.
See also rtGeometryInstanceCreate
RTresult RTAPI rtGeometryIsDirty | ( | RTgeometry | geometry, |
int * | dirty | ||
) |
Returns the dirty flag.
Description
rtGeometryIsDirty returns the dirty flag of geometry. The dirty flag for geometry nodes can be set with rtGeometryMarkDirty. By default the flag is 1 for a new geometry node, indicating dirty. After a call to rtContextLaunch the flag is automatically set to 0. When the dirty flag is set, the geometry data is uploaded automatically to the device while a rtContextLaunch call.
[in] | geometry | The geometry node to query from the dirty flag |
[out] | dirty | Dirty flag |
Return values
Relevant return values:
History
rtGeometryIsDirty was introduced in OptiX 1.0.
See also rtContextLaunch, rtGeometryMarkDirty
RTresult RTAPI rtGeometryMarkDirty | ( | RTgeometry | geometry | ) |
Sets the dirty flag.
Description
rtGeometryMarkDirty sets for geometry the dirty flag. By default the dirty flag is set for a new Geometry node. After a call to rtContextLaunch the flag is automatically cleared. When the dirty flag is set, the geometry data is uploaded automatically to the device while a rtContextLaunch call.
[in] | geometry | The geometry node to mark as dirty |
Return values
Relevant return values:
History
rtGeometryMarkDirty was introduced in OptiX 1.0.
See also rtGeometryIsDirty
RTresult RTAPI rtGeometryQueryVariable | ( | RTgeometry | geometry, |
const char * | name, | ||
RTvariable * | v | ||
) |
Returns a handle to a named variable of a geometry node.
Description
rtGeometryQueryVariable queries the handle of a geometry node's named variable. geometry specifies the target geometry node and should be a value returned by rtGeometryCreate. name specifies the name of the variable, and should be a NULL-terminated string. If name is the name of a variable attached to geometry, returns a handle to that variable in *v or NULL otherwise. Geometry variables must be declared with rtGeometryDeclareVariable before they can be queried.
[in] | geometry | The geometry node to query from a variable |
[in] | name | The name that identifies the variable to be queried |
[out] | v | Returns the named variable |
Return values
Relevant return values:
History
rtGeometryQueryVariable was introduced in OptiX 1.0.
See also rtGeometryDeclareVariable, rtGeometryRemoveVariable, rtGeometryGetVariableCount, rtGeometryGetVariable
RTresult RTAPI rtGeometryRemoveVariable | ( | RTgeometry | geometry, |
RTvariable | v | ||
) |
Removes a named variable from a geometry node.
Description
rtGeometryRemoveVariable removes a named variable from a geometry node. The target geometry is specified by geometry, which should be a value returned by rtGeometryCreate. The variable to remove is specified by v, which should be a value returned by rtGeometryDeclareVariable. Once a variable has been removed from this geometry node, another variable with the same name as the removed variable may be declared.
[in] | geometry | The geometry node from which to remove a variable |
[in] | v | The variable to be removed |
Return values
Relevant return values:
History
rtGeometryRemoveVariable was introduced in OptiX 1.0.
See also rtContextRemoveVariable
RTresult RTAPI rtGeometrySetBoundingBoxProgram | ( | RTgeometry | geometry, |
RTprogram | program | ||
) |
Sets the bounding box program.
Description
rtGeometrySetBoundingBoxProgram sets for geometry the program that computes an axis aligned bounding box for each attached primitive to geometry. RTprogram's can be either generated with rtProgramCreateFromPTXFile or rtProgramCreateFromPTXString. A bounding box program is mandatory for every geometry node.
[in] | geometry | The geometry node for which to set the bounding box program |
[in] | program | Handle to the bounding box program |
Return values
Relevant return values:
History
rtGeometrySetBoundingBoxProgram was introduced in OptiX 1.0.
See also rtGeometryGetBoundingBoxProgram, rtProgramCreateFromPTXFile, rtProgramCreateFromPTXString
RTresult RTAPI rtGeometrySetIntersectionProgram | ( | RTgeometry | geometry, |
RTprogram | program | ||
) |
Sets the intersection program.
Description
rtGeometrySetIntersectionProgram sets for geometry the program that performs ray primitive intersections. RTprogram's can be either generated with rtProgramCreateFromPTXFile or rtProgramCreateFromPTXString. An intersection program is mandatory for every geometry node.
[in] | geometry | The geometry node for which to set the intersection program |
[in] | program | A handle to the ray primitive intersection program |
Return values
Relevant return values:
History
rtGeometrySetIntersectionProgram was introduced in OptiX 1.0.
See also rtGeometryGetIntersectionProgram, rtProgramCreateFromPTXFile, rtProgramCreateFromPTXString
RTresult RTAPI rtGeometrySetPrimitiveCount | ( | RTgeometry | geometry, |
unsigned int | num_primitives | ||
) |
Sets the number of primitives.
Description
rtGeometrySetPrimitiveCount sets the number of primitives num_primitives in geometry.
[in] | geometry | The geometry node for which to set the number of primitives |
[in] | num_primitives | The number of primitives |
Return values
Relevant return values:
History
rtGeometrySetPrimitiveCount was introduced in OptiX 1.0.
See also rtGeometryGetPrimitiveCount
RTresult RTAPI rtGeometrySetPrimitiveIndexOffset | ( | RTgeometry | geometry, |
unsigned int | index_offset | ||
) |
Sets the primitive index offset.
Description
rtGeometrySetPrimitiveIndexOffset sets the primitive index offset index_offset in geometry. In the past, a Geometry object's primitive index range always started at zero (e.g., a Geometry with N primitives would have a primitive index range of [0,N-1]). The index offset is used to allow Geometry objects to have primitive index ranges starting at non-zero positions (e.g., a Geometry with N primtives and and index offset of M would have a primitive index range of [M,M+N-1]). This feature enables the sharing of vertex index buffers between multiple Geometry objects.
[in] | geometry | The geometry node for which to set the primitive index offset |
[in] | index_offset | The primitive index offset |
Return values
Relevant return values:
History
rtGeometrySetPrimitiveIndexOffset was introduced in OptiX 3.5.
See also rtGeometryGetPrimitiveIndexOffset
RTresult RTAPI rtGeometryValidate | ( | RTgeometry | geometry | ) |
Validates the geometry nodes integrity.
Description
rtGeometryValidate checks geometry for completeness. If geometry or any of the objects attached to geometry are not valid, returns RT_ERROR_INVALID_VALUE.
[in] | geometry | The geometry node to be validated |
Return values
Relevant return values:
History
rtGeometryValidate was introduced in OptiX 1.0.
See also rtContextValidate
RTresult RTAPI rtGetVersion | ( | unsigned int * | version | ) |
Returns the current OptiX version.
Description
rtGetVersion returns in version a numerically comparable version number of the current OptiX library.
[out] | version | OptiX version number |
Return values
Relevant return values:
History
rtGetVersion was introduced in OptiX 1.0.
See also rtDeviceGetDeviceCount
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.
[in] | context | Specifies a context within which to create a new group |
[out] | group | Returns a newly created group |
Return values
Relevant return values:
History
rtGroupCreate was introduced in OptiX 1.0.
See also rtGroupDestroy, rtContextCreate
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.
[in] | group | Handle 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.
[in] | group | The group handle |
[out] | acceleration | The returned acceleration structure object |
Return values
Relevant return values:
History
rtGroupGetAcceleration was introduced in OptiX 1.0.
See also rtGroupSetAcceleration, rtAccelerationCreate
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.
[in] | group | The parent group handle |
[in] | index | The index of the child slot to query |
[out] | child | The returned child object |
Return values
Relevant return values:
History
rtGroupGetChild was introduced in OptiX 1.0.
See also rtGroupSetChild, rtGroupSetChildCount, rtGroupGetChildCount, rtGroupGetChildType
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.
[in] | group | The parent group handle |
[out] | count | Returned 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.
[in] | group | The parent group handle |
[in] | index | The index of the child slot to query |
[out] | type | The returned child type |
Return values
Relevant return values:
History
rtGroupGetChildType was introduced in OptiX 1.0.
See also rtGroupSetChild, rtGroupGetChild, rtGroupSetChildCount, rtGroupGetChildCount
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.
[in] | group | Specifies the group to query |
[out] | context | Returns 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 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.
[in] | group | The group handle |
[in] | acceleration | The 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
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.
[in] | group | The parent group handle |
[in] | index | The index in the parent's child slot array |
[in] | child | The 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
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.
[in] | group | The parent group handle |
[in] | count | Number 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
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.
[in] | group | Specifies the group to be validated |
Return values
Relevant return values:
History
rtGroupValidate was introduced in OptiX 1.0.
See also rtGroupCreate
RTresult RTAPI rtMaterialCreate | ( | RTcontext | context, |
RTmaterial * | material | ||
) |
Creates a new material.
Description
rtMaterialCreate creates a new material within a context. context specifies the target context, as returned by rtContextCreate. Sets *material to the handle of a newly created material within context. Returns RT_ERROR_INVALID_VALUE if material is NULL.
[in] | context | Specifies a context within which to create a new material |
[out] | material | Returns a newly created material |
Return values
Relevant return values:
History
rtMaterialCreate was introduced in OptiX 1.0.
See also rtMaterialDestroy, rtContextCreate
RTresult RTAPI rtMaterialDeclareVariable | ( | RTmaterial | material, |
const char * | name, | ||
RTvariable * | v | ||
) |
Declares a new named variable to be associated with a material.
Description
rtMaterialDeclareVariable declares a new variable to be associated with a material. material specifies the target material, and should be a value returned by rtMaterialCreate. name specifies the name of the variable, and should be a NULL-terminated string. If there is currently no variable associated with material named name, and v is not NULL, a new variable named name will be created and associated with material and *v will be set to the handle of the newly-created variable. Otherwise, this call has no effect and returns either RT_ERROR_INVALID_VALUE if either name or v is NULL or RT_ERROR_VARIABLE_REDECLARED if name is the name of an existing variable associated with the material.
[in] | material | Specifies the material to modify |
[in] | name | Specifies the name of the variable |
[out] | v | Returns a handle to a newly declared variable |
Return values
Relevant return values:
History
rtMaterialDeclareVariable was introduced in OptiX 1.0.
See also rtMaterialGetVariable, rtMaterialQueryVariable, rtMaterialCreate
RTresult RTAPI rtMaterialDestroy | ( | RTmaterial | material | ) |
Destroys a material object.
Description
rtMaterialDestroy removes material from its context and deletes it. material should be a value returned by rtMaterialCreate. Associated variables declared via rtMaterialDeclareVariable are destroyed, but no child graph nodes are destroyed. After the call, material is no longer a valid handle.
[in] | material | Handle of the material node to destroy |
Return values
Relevant return values:
History
rtMaterialDestroy was introduced in OptiX 1.0.
See also rtMaterialCreate
RTresult RTAPI rtMaterialGetAnyHitProgram | ( | RTmaterial | material, |
unsigned int | ray_type_index, | ||
RTprogram * | program | ||
) |
Returns the any hit program associated with a (material, ray type) tuple.
Description
rtMaterialGetAnyHitProgram queries the any hit program associated with a (material, ray type) tuple. material specifies the material of interest and should be a value returned by rtMaterialCreate. ray_type_index specifies the target ray type and should be a value less than the value returned by rtContextGetRayTypeCount. if all parameters are valid, *program sets to the handle of the any hit program associated with the tuple (material, ray_type_index). Otherwise, the call has no effect and returns RT_ERROR_INVALID_VALUE.
[in] | material | Specifies the material of the (material, ray type) tuple to query |
[in] | ray_type_index | Specifies the type of ray of the (material, ray type) tuple to query |
[out] | program | Returns the any hit program associated with the (material, ray type) tuple |
Return values
Relevant return values:
History
rtMaterialGetAnyHitProgram was introduced in OptiX 1.0.
See also rtMaterialSetAnyHitProgram, rtMaterialCreate, rtContextGetRayTypeCount
RTresult RTAPI rtMaterialGetClosestHitProgram | ( | RTmaterial | material, |
unsigned int | ray_type_index, | ||
RTprogram * | program | ||
) |
Returns the closest hit program associated with a (material, ray type) tuple.
Description
rtMaterialGetClosestHitProgram queries the closest hit program associated with a (material, ray type) tuple. material specifies the material of interest and should be a value returned by rtMaterialCreate. ray_type_index specifies the target ray type and should be a value less than the value returned by rtContextGetRayTypeCount. If all parameters are valid, *program sets to the handle of the any hit program associated with the tuple (material, ray_type_index). Otherwise, the call has no effect and returns RT_ERROR_INVALID_VALUE.
[in] | material | Specifies the material of the (material, ray type) tuple to query |
[in] | ray_type_index | Specifies the type of ray of the (material, ray type) tuple to query |
[out] | program | Returns the closest hit program associated with the (material, ray type) tuple |
Return values
Relevant return values:
History
rtMaterialGetClosestHitProgram was introduced in OptiX 1.0.
See also rtMaterialSetClosestHitProgram, rtMaterialCreate, rtContextGetRayTypeCount
RTresult RTAPI rtMaterialGetContext | ( | RTmaterial | material, |
RTcontext * | context | ||
) |
Returns the context associated with a material.
Description
rtMaterialGetContext queries a material for its associated context. material specifies the material to query, and should be a value returned by rtMaterialCreate. If both parameters are valid, *context sets to the context associated with material. Otherwise, the call has no effect and returns RT_ERROR_INVALID_VALUE.
[in] | material | Specifies the material to query |
[out] | context | Returns the context associated with the material |
Return values
Relevant return values:
History
rtMaterialGetContext was introduced in OptiX 1.0.
See also rtMaterialCreate
RTresult RTAPI rtMaterialGetVariable | ( | RTmaterial | material, |
unsigned int | index, | ||
RTvariable * | v | ||
) |
Returns a handle to an indexed variable of a material.
Description
rtMaterialGetVariable queries the handle of a material's indexed variable. material specifies the target material and should be a value returned by rtMaterialCreate. index specifies the index of the variable, and should be a value less than rtMaterialGetVariableCount. If material is a valid material and index is the index of a variable attached to material, *v is set to a handle to that variable. Otherwise, *v is set to NULL and either RT_ERROR_INVALID_VALUE or RT_ERROR_VARIABLE_NOT_FOUND is returned depending on the validity of material, or index, respectively.
[in] | material | Specifies the material to query |
[in] | index | Specifies the index of the variable to query |
[out] | v | Returns the indexed variable |
Return values
Relevant return values:
History
rtMaterialGetVariable was introduced in OptiX 1.0.
See also rtMaterialQueryVariable, rtMaterialGetVariableCount, rtMaterialCreate
RTresult RTAPI rtMaterialGetVariableCount | ( | RTmaterial | material, |
unsigned int * | count | ||
) |
Returns the number of variables attached to a material.
Description
rtMaterialGetVariableCount queries the number of variables attached to a material. material specifies the material, and should be a value returned by rtMaterialCreate. After the call, if both parameters are valid, the number of variables attached to material is returned to *count. Otherwise, the call has no effect and returns RT_ERROR_INVALID_VALUE.
[in] | material | Specifies the material to query |
[out] | count | Returns the number of variables |
Return values
Relevant return values:
History
rtMaterialGetVariableCount was introduced in OptiX 1.0.
See also rtMaterialCreate
RTresult RTAPI rtMaterialQueryVariable | ( | RTmaterial | material, |
const char * | name, | ||
RTvariable * | v | ||
) |
Queries for the existence of a named variable of a material.
Description
rtMaterialQueryVariable queries for the existence of a material's named variable. material specifies the target material and should be a value returned by rtMaterialCreate. name specifies the name of the variable, and should be a NULL-terminated string. If material is a valid material and name is the name of a variable attached to material, *v is set to a handle to that variable after the call. Otherwise, *v is set to NULL. If material is not a valid material, returns RT_ERROR_INVALID_VALUE.
[in] | material | Specifies the material to query |
[in] | name | Specifies the name of the variable to query |
[out] | v | Returns a the named variable, if it exists |
Return values
Relevant return values:
History
rtMaterialQueryVariable was introduced in OptiX 1.0.
See also rtMaterialGetVariable, rtMaterialCreate
RTresult RTAPI rtMaterialRemoveVariable | ( | RTmaterial | material, |
RTvariable | v | ||
) |
Removes a variable from a material.
Description
rtMaterialRemoveVariable removes a variable from a material. The material of interest is specified by material, which should be a value returned by rtMaterialCreate. The variable to remove is specified by v, which should be a value returned by rtMaterialDeclareVariable. Once a variable has been removed from this material, another variable with the same name as the removed variable may be declared. If material does not refer to a valid material, this call has no effect and returns RT_ERROR_INVALID_VALUE. If v is not a valid variable or does not belong to material, this call has no effect and returns RT_ERROR_INVALID_VALUE or RT_ERROR_VARIABLE_NOT_FOUND, respectively.
[in] | material | Specifies the material to modify |
[in] | v | Specifies the variable to remove |
Return values
Relevant return values:
History
rtMaterialRemoveVariable was introduced in OptiX 1.0.
See also rtMaterialDeclareVariable, rtMaterialCreate
RTresult RTAPI rtMaterialSetAnyHitProgram | ( | RTmaterial | material, |
unsigned int | ray_type_index, | ||
RTprogram | program | ||
) |
Sets the any hit program associated with a (material, ray type) tuple.
Description
rtMaterialSetAnyHitProgram specifies an any hit program to associate with a (material, ray type) tuple. material specifies the target material and should be a value returned by rtMaterialCreate. ray_type_index specifies the type of ray to which the program applies and should be a value less than the value returned by rtContextGetRayTypeCount. program specifies the target any hit program which applies to the tuple (material, ray_type_index) and should be a value returned by either rtProgramCreateFromPTXString or rtProgramCreateFromPTXFile.
[in] | material | Specifies the material of the (material, ray type) tuple to modify |
[in] | ray_type_index | Specifies the type of ray of the (material, ray type) tuple to modify |
[in] | program | Specifies the any hit program to associate with the (material, ray type) tuple |
Return values
Relevant return values:
History
rtMaterialSetAnyHitProgram was introduced in OptiX 1.0.
See also rtMaterialGetAnyHitProgram, rtMaterialCreate, rtContextGetRayTypeCount, rtProgramCreateFromPTXString, rtProgramCreateFromPTXFile
RTresult RTAPI rtMaterialSetClosestHitProgram | ( | RTmaterial | material, |
unsigned int | ray_type_index, | ||
RTprogram | program | ||
) |
Sets the closest hit program associated with a (material, ray type) tuple.
Description
rtMaterialSetClosestHitProgram specifies a closest hit program to associate with a (material, ray type) tuple. material specifies the material of interest and should be a value returned by rtMaterialCreate. ray_type_index specifies the type of ray to which the program applies and should be a value less than the value returned by rtContextGetRayTypeCount. program specifies the target closest hit program which applies to the tuple (material, ray_type_index) and should be a value returned by either rtProgramCreateFromPTXString or rtProgramCreateFromPTXFile.
[in] | material | Specifies the material of the (material, ray type) tuple to modify |
[in] | ray_type_index | Specifies the ray type of the (material, ray type) tuple to modify |
[in] | program | Specifies the closest hit program to associate with the (material, ray type) tuple |
Return values
Relevant return values:
History
rtMaterialSetClosestHitProgram was introduced in OptiX 1.0.
See also rtMaterialGetClosestHitProgram, rtMaterialCreate, rtContextGetRayTypeCount, rtProgramCreateFromPTXString, rtProgramCreateFromPTXFile
RTresult RTAPI rtMaterialValidate | ( | RTmaterial | material | ) |
Verifies the state of a material.
Description
rtMaterialValidate checks material for completeness. If material or any of the objects attached to material are not valid, returns RT_ERROR_INVALID_VALUE.
[in] | material | Specifies the material to be validated |
Return values
Relevant return values:
History
rtMaterialValidate was introduced in OptiX 1.0.
See also rtMaterialCreate
RTresult RTAPI rtProgramCreateFromPTXFile | ( | RTcontext | context, |
const char * | filename, | ||
const char * | program_name, | ||
RTprogram * | program | ||
) |
Creates a new program object.
Description
rtProgramCreateFromPTXFile allocates and returns a handle to a new program object. The program is created from PTX code held in filename from function program_name.
[in] | context | The context to create the program in |
[in] | filename | Path to the file containing the PTX code |
[in] | program_name | The name of the PTX function to create the program from |
[in] | program | Handle to the program to be created |
Return values
Relevant return values:
History
rtProgramCreateFromPTXFile was introduced in OptiX 1.0.
See also RT_PROGRAM, rtProgramCreateFromPTXString, rtProgramDestroy
RTresult RTAPI rtProgramCreateFromPTXString | ( | RTcontext | context, |
const char * | ptx, | ||
const char * | program_name, | ||
RTprogram * | program | ||
) |
Creates a new program object.
Description
rtProgramCreateFromPTXString allocates and returns a handle to a new program object. The program is created from PTX code held in the NULL-terminated string ptx from function program_name.
[in] | context | The context to create the program in |
[in] | ptx | The string containing the PTX code |
[in] | program_name | The name of the PTX function to create the program from |
[in] | program | Handle to the program to be created |
Return values
Relevant return values:
History
rtProgramCreateFromPTXString was introduced in OptiX 1.0.
See also RT_PROGRAM, rtProgramCreateFromPTXFile, rtProgramDestroy
RTresult RTAPI rtProgramDeclareVariable | ( | RTprogram | program, |
const char * | name, | ||
RTvariable * | v | ||
) |
Declares a new named variable associated with a program.
Description
rtProgramDeclareVariable declares a new variable, name, and associates it with the program. A variable can only be declared with the same name once on the program. Any attempt to declare multiple variables with the same name will cause the call to fail and return RT_ERROR_VARIABLE_REDECLARED. If name orv is NULL returns RT_ERROR_INVALID_VALUE.
[in] | program | The program the declared variable will be attached to |
[in] | name | The name of the variable to be created |
[out] | v | Return handle to the variable to be created |
Return values
Relevant return values:
History
rtProgramDeclareVariable was introduced in OptiX 1.0.
See also rtProgramRemoveVariable, rtProgramGetVariable, rtProgramGetVariableCount, rtProgramQueryVariable
Destroys a program object.
Description
rtProgramDestroy removes program from its context and deletes it. program should be a value returned by rtProgramCreate*. Associated variables declared via rtProgramDeclareVariable are destroyed. After the call, program is no longer a valid handle.
[in] | program | Handle of the program to destroy |
Return values
Relevant return values:
History
rtProgramDestroy was introduced in OptiX 1.0.
See also rtProgramCreateFromPTXFile, rtProgramCreateFromPTXString
Gets the context object that created a program.
Description
rtProgramGetContext returns a handle to the context object that was used to create program. Returns RT_ERROR_INVALID_VALUE if context is NULL.
[in] | program | The program to be queried for its context object |
[out] | context | The return handle for the requested context object |
Return values
Relevant return values:
History
rtProgramGetContext was introduced in OptiX 1.0.
See also rtContextCreate
Returns the ID for the Program object.
Description
rtProgramGetId returns an ID for the provided program. The returned ID is used to reference program from device code. If program_id is NULL or the program is not a valid RTprogram, returns RT_ERROR_INVALID_VALUE. RT_PROGRAM_ID_NULL can be used as a sentinel for a non-existent program, since this value will never be returned as a valid program id.
[in] | program | The program to be queried for its id |
[out] | program_id | The returned ID of the program. |
Return values
Relevant return values:
History
rtProgramGetId was introduced in OptiX 3.6.
See also rtContextGetProgramFromId
RTresult RTAPI rtProgramGetVariable | ( | RTprogram | program, |
unsigned int | index, | ||
RTvariable * | v | ||
) |
Returns a handle to a variable attached to a program by index.
Description
rtProgramGetVariable returns a handle to a variable in *v attached to program with rtProgramDeclareVariable by index. index must be between 0 and one less than the value returned by rtProgramGetVariableCount. The order in which variables are enumerated is not constant and may change as variables are attached and removed from the program object.
[in] | program | The program to be queried for the indexed variable object |
[in] | index | The index of the variable to return |
[out] | v | Return handle to the variable object specified by the index |
Return values
Relevant return values:
History
rtProgramGetVariable was introduced in OptiX 1.0.
See also rtProgramDeclareVariable, rtProgramRemoveVariable, rtProgramGetVariableCount, rtProgramQueryVariable
Returns the number of variables attached to a program.
Description
rtProgramGetVariableCount returns, in *count, the number of variable objects that have been attached to program.
[in] | program | The program to be queried for its variable count |
[out] | count | The return handle for the number of variables attached to this program |
Return values
Relevant return values:
History
rtProgramGetVariableCount was introduced in OptiX 1.0.
See also rtProgramDeclareVariable, rtProgramRemoveVariable, rtProgramGetVariable, rtProgramQueryVariable
RTresult RTAPI rtProgramQueryVariable | ( | RTprogram | program, |
const char * | name, | ||
RTvariable * | v | ||
) |
Returns a handle to the named variable attached to a program.
Description
rtProgramQueryVariable returns a handle to a variable object, in *v, attached to program referenced by the NULL-terminated string name. If name is not the name of a variable attached to program, *v will be NULL after the call.
[in] | program | The program to be queried for the named variable |
[in] | name | The name of the program to be queried for |
[out] | v | The return handle to the variable object |
program | Handle to the program to be created |
Return values
Relevant return values:
History
rtProgramQueryVariable was introduced in OptiX 1.0.
See also rtProgramDeclareVariable, rtProgramRemoveVariable, rtProgramGetVariable, rtProgramGetVariableCount
RTresult RTAPI rtProgramRemoveVariable | ( | RTprogram | program, |
RTvariable | v | ||
) |
Removes the named variable from a program.
Description
rtProgramRemoveVariable removes variable v from the program object. Once a variable has been removed from this program, another variable with the same name as the removed variable may be declared.
[in] | program | The program to remove the variable from |
[in] | v | The variable to remove |
Return values
Relevant return values:
History
rtProgramRemoveVariable was introduced in OptiX 1.0.
See also rtProgramDeclareVariable, rtProgramGetVariable, rtProgramGetVariableCount, rtProgramQueryVariable
Validates the state of a program.
Description
rtProgramValidate checks program for completeness. If program or any of the objects attached to program are not valid, returns RT_ERROR_INVALID_CONTEXT.
[in] | program | The program to be validated |
Return values
Relevant return values:
History
rtProgramValidate was introduced in OptiX 1.0.
See also rtProgramCreateFromPTXFile, rtProgramCreateFromPTXString
RTresult RTAPI rtRemoteDeviceCreate | ( | const char * | url, |
const char * | username, | ||
const char * | password, | ||
RTremotedevice * | remote_dev | ||
) |
Create a device for remote rendering on VCAs.
Description
Establishes a connection to a remote OptiX device, e.g. a VCA or cluster of VCAs. This opens a connection to the cluster manager software running at address, using username and password as authentication strings. address is a WebSocket URL of the form "ws://localhost:80" or "wss://localhost:443", username and password as plain text strings for authenticating on the remote device. If successful, it initializes a new RTremotedevice object.
In order to use this newly created remote device, a rendering instance needs to be configured by selecting a software configuration and reserving a number of nodes in the VCA. See rtRemoteDeviceReserve for more details.
After a rendering instance is properly initialized, a remote device must be associated with a context to be used. Calling rtContextSetDevices creates this association. Any further OptiX calls will be directed to the remote device.
[in] | url | The WebSocket URL to connect to |
[in] | username | Username in plain text |
[in] | password | Password in plain text |
[out] | remote_dev | A handle to the new remote device object |
Return values
Relevant return values:
History
rtRemoteDeviceCreate was introduced in OptiX 3.8.
See also rtRemoteDeviceDestroy rtRemoteDeviceGetAttribute rtRemoteDeviceReserve rtRemoteDeviceRelease rtContextSetRemoteDevice
RTresult RTAPI rtRemoteDeviceDestroy | ( | RTremotedevice | remote_dev | ) |
Destroys a remote device.
Description
Closes the network connection to the remote device and destroys the corresponding RTremotedevice object.
[in] | remote_dev | The remote device object to destroy |
Return values
Relevant return values:
History
rtRemoteDeviceDestroy was introduced in OptiX 3.8.
See also rtRemoteDeviceCreate rtRemoteDeviceGetAttribute rtRemoteDeviceReserve rtRemoteDeviceRelease rtContextSetRemoteDevice
RTresult RTAPI rtRemoteDeviceGetAttribute | ( | RTremotedevice | remote_dev, |
RTremotedeviceattribute | attrib, | ||
RTsize | size, | ||
void * | p | ||
) |
Queries attributes of a remote device.
Description
In order to gather information about a remote device, several attributes can be queried through rtRemoteDeviceGetAttribute.
Each attribute can have a different size. The sizes are given in the following list:
The following attributes can be queried when a remote device is connected:
The following attributes require a valid reservation to be queried:
RT_REMOTEDEVICE_ATTRIBUTE_CLUSTER_URL The URL of the Cluster Manager associated with this remote device.
RT_REMOTEDEVICE_ATTRIBUTE_HEAD_NODE_URL The URL of the rendering instance being used, once it has been reserved and initialized.
RT_REMOTEDEVICE_ATTRIBUTE_NUM_CONFIGURATIONS Number of compatible software configurations available in the remote device.
RT_REMOTEDEVICE_ATTRIBUTE_CONFIGURATIONS Base entry for a list of compatible software configurations in the device. A configuration is a text description for a software package installed in the remote device, intended as a guide to the user in selecting from the pool of compatible configurations. This list is already filtered and it only contains entries on the remote device compatible with the client library being used. Each entry can be accessed as the attribute (RT_REMOTEDEVICE_ATTRIBUTE_CONFIGURATIONS + index), with index being zero-based. The configuration description for the given index is copied into the destination buffer. A suggested size for the destination buffer is 256 characters. The number of entries in the list is given by the value of RT_REMOTEDEVICE_ATTRIBUTE_NUM_CONFIGURATIONS. Only configurations compatible with the client version being used are listed.
RT_REMOTEDEVICE_ATTRIBUTE_STATUS Returns the current status of the remote device, as one of the following:
RT_REMOTEDEVICE_ATTRIBUTE_NUM_TOTAL_NODES Total number of nodes in the cluster of VCAs.
RT_REMOTEDEVICE_ATTRIBUTE_NUM_FREE_NODES Number of free nodes available.
RT_REMOTEDEVICE_ATTRIBUTE_NUM_RESERVED_NODES Number of nodes used by the current reservation.
RT_REMOTEDEVICE_ATTRIBUTE_NUM_GPUS Number of GPUs used by the current reservation.
RT_REMOTEDEVICE_ATTRIBUTE_NAME Common name assigned the Remote Device.
RT_REMOTEDEVICE_ATTRIBUTE_GPU_TOTAL_MEMORY Total amount of memory on each GPU, in bytes.
[in] | remote_dev | The remote device to query |
Return values
Relevant return values:
History
rtRemoteDeviceGetAttribute was introduced in OptiX 3.8.
See also rtRemoteDeviceCreate rtRemoteDeviceReserve rtRemoteDeviceRelease rtContextSetRemoteDevice
RTresult RTAPI rtRemoteDeviceRelease | ( | RTremotedevice | remote_dev | ) |
Release reserved nodes on a remote device.
Description
Releases an existing reservation on the remote device. The rendering instance on the remote device is destroyed, and all its remote context information is lost. Further OptiX calls will no longer be directed to the device. A new reservation can take place.
[in] | remote_dev | The remote device on which the reservation was made |
Return values
Relevant return values:
History
rtRemoteDeviceRelease was introduced in OptiX 3.8.
See also rtRemoteDeviceCreate rtRemoteDeviceGetAttribute rtRemoteDeviceReserve rtContextSetRemoteDevice
RTresult RTAPI rtRemoteDeviceReserve | ( | RTremotedevice | remote_dev, |
unsigned int | num_nodes, | ||
unsigned int | configuration | ||
) |
Reserve nodes for rendering on a remote device.
Description
Reserves nodes in the remote device to form a rendering instance. Receives num_nodes as the number of nodes to reserve, and configuration as the index of the software package to use for the created instance. Both the number of available nodes and the list of available configurations in a remote device can be retrieved by rtRemoteDeviceGetAttribute.
After successfully reserving the nodes, the RT_REMOTEDEVICE_ATTRIBUTE_STATUS attribute should be polled repeatedly. The rendering instance is ready for use when that attribute is set to RT_REMOTE_DEVICE_STATUS_READY.
Only a single reservation per remote device and user can exist at any given time (i.e. a user can have only one rendering instance per remote device). This includes reservations performed through other means, like previous runs that were not properly released, or manual reservations over the cluster manager web interface.
[in] | remote_dev | The remote device on which to reserve nodes |
[in] | num_nodes | The number of nodes to reserve |
[in] | configuration | The index of the software configuration to use |
Return values
Relevant return values:
History
rtRemoteDeviceReserve was introduced in OptiX 3.8.
See also rtRemoteDeviceCreate rtRemoteDeviceGetAttribute rtRemoteDeviceRelease rtContextSetRemoteDevice
RTresult RTAPI rtSelectorCreate | ( | RTcontext | context, |
RTselector * | selector | ||
) |
Creates a Selector node.
Description
Creates a new Selector node within context. After calling rtSelectorCreate the new node is in a "raw" state. For the node to be functional, a visit program must be assigned using rtSelectorSetVisitProgram. Furthermore, a number of (zero or more) children can be attached by using rtSelectorSetChildCount and rtSelectorSetChild. Sets *selector to the handle of a newly created selector within context. Returns RT_ERROR_INVALID_VALUE if selector is NULL.
[in] | context | Specifies the rendering context of the Selector node |
[out] | selector | New Selector node handle |
Return values
Relevant return values:
History
rtSelectorCreate was introduced in OptiX 1.0.
See also rtSelectorDestroy, rtSelectorValidate, rtSelectorGetContext, rtSelectorSetVisitProgram, rtSelectorSetChildCount, rtSelectorSetChild
RTresult RTAPI rtSelectorDeclareVariable | ( | RTselector | selector, |
const char * | name, | ||
RTvariable * | v | ||
) |
Declares a variable associated with a Selector node.
Description
Declares a new variable identified by name, and associates it with the Selector node selector. The new variable handle is returned in v. After declaration, a variable does not have a type until its value is set by an rtVariableSet{...} function. Once a variable type has been set, it cannot be changed, i.e., only rtVariableSet{...} functions of the same type can be used to change the value of the variable.
[in] | selector | Selector node handle |
[in] | name | Variable identifier |
[out] | v | New variable handle |
Return values
Relevant return values:
History
rtSelectorDeclareVariable was introduced in OptiX 1.0.
See also rtSelectorQueryVariable, rtSelectorRemoveVariable, rtSelectorGetVariableCount, rtSelectorGetVariable, rtVariableSet{...}
RTresult RTAPI rtSelectorDestroy | ( | RTselector | selector | ) |
Destroys a selector node.
Description
rtSelectorDestroy removes selector from its context and deletes it. selector should be a value returned by rtSelectorCreate. Associated variables declared via rtSelectorDeclareVariable are destroyed, but no child graph nodes are destroyed. After the call, selector is no longer a valid handle.
[in] | selector | Handle of the selector node to destroy |
Return values
Relevant return values:
History
rtSelectorDestroy was introduced in OptiX 1.0.
See also rtSelectorCreate, rtSelectorValidate, rtSelectorGetContext
RTresult RTAPI rtSelectorGetChild | ( | RTselector | selector, |
unsigned int | index, | ||
RTobject * | child | ||
) |
Returns a child node that is attached to a Selector node.
Description
rtSelectorGetChild returns in child a handle of the child node currently attached to selector at slot index. The index value must be lower than the number previously set by rtSelectorSetChildCount, thus it must be in the range from 0 to rtSelectorGetChildCount - 1. The returned pointer is of generic type RTobject and needs to be cast to the actual child type, which can be RTgroup, RTselector, RTgeometrygroup, or RTtransform. The actual type of child can be queried using rtSelectorGetChildType;
[in] | selector | Selector node handle |
[in] | index | Child node index |
[out] | child | Child node handle. Can be {RTgroup, RTselector, RTgeometrygroup, RTtransform} |
Return values
Relevant return values:
History
rtSelectorGetChild was introduced in OptiX 1.0.
See also rtSelectorSetChildCount, rtSelectorGetChildCount, rtSelectorSetChild, rtSelectorGetChildType
RTresult RTAPI rtSelectorGetChildCount | ( | RTselector | selector, |
unsigned int * | count | ||
) |
Returns the number of child node slots of a Selector node.
Description
rtSelectorGetChildCount returns in count the number of child node slots that have been previously reserved for the Selector node selector by rtSelectorSetChildCount. The value of count does not reflect the actual number of child nodes that have so far been attached to the Selector node using rtSelectorSetChild.
[in] | selector | Selector node handle |
[out] | count | Number of child node slots reserved for selector |
Return values
Relevant return values:
History
rtSelectorGetChildCount was introduced in OptiX 1.0.
See also rtSelectorSetChildCount, rtSelectorSetChild, rtSelectorGetChild, rtSelectorGetChildType
RTresult RTAPI rtSelectorGetChildType | ( | RTselector | selector, |
unsigned int | index, | ||
RTobjecttype * | type | ||
) |
Returns type information about a Selector child node.
Description
rtSelectorGetChildType queries the type of the child node attached to selector 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. The returned type is one of:
RT_OBJECTTYPE_GROUP RT_OBJECTTYPE_GEOMETRY_GROUP RT_OBJECTTYPE_TRANSFORM RT_OBJECTTYPE_SELECTOR
[in] | selector | Selector node handle |
[in] | index | Child node index |
[out] | type | Type of the child node |
Return values
Relevant return values:
History
rtSelectorGetChildType was introduced in OptiX 1.0.
See also rtSelectorSetChildCount, rtSelectorGetChildCount, rtSelectorSetChild, rtSelectorGetChild
RTresult RTAPI rtSelectorGetContext | ( | RTselector | selector, |
RTcontext * | context | ||
) |
Returns the context of a Selector node.
Description
rtSelectorGetContext returns in context the rendering context in which the Selector node selector has been created.
[in] | selector | Selector node handle |
[out] | context | The context, selector belongs to |
Return values
Relevant return values:
History
rtSelectorGetContext was introduced in OptiX 1.0.
See also rtSelectorCreate, rtSelectorDestroy, rtSelectorValidate
RTresult RTAPI rtSelectorGetVariable | ( | RTselector | selector, |
unsigned int | index, | ||
RTvariable * | v | ||
) |
Returns a variable associated with a Selector node.
Description
Returns in v a handle to the variable located at position index in the Selectors's variable array. index is a sequential number depending on the order of variable declarations. The index must be in the range from 0 to rtSelectorGetVariableCount - 1. The current value of a variable can be retrieved from its handle by using an appropriate rtVariableGet{...} function matching the variable's type.
[in] | selector | Selector node handle |
[in] | index | Variable index |
[out] | v | Variable handle |
Return values
Relevant return values:
History
rtSelectorGetVariable was introduced in OptiX 1.0.
See also rtSelectorDeclareVariable, rtSelectorQueryVariable, rtSelectorRemoveVariable, rtSelectorGetVariableCount, rtVariableGet{...}
RTresult RTAPI rtSelectorGetVariableCount | ( | RTselector | selector, |
unsigned int * | count | ||
) |
Returns the number of variables attached to a Selector node.
Description
rtSelectorGetVariableCount returns in count the number of variables that are currently attached to the Selector node selector.
[in] | selector | Selector node handle |
[out] | count | Number of variables associated with selector |
Return values
Relevant return values:
History
rtSelectorGetVariableCount was introduced in OptiX 1.0.
See also rtSelectorDeclareVariable, rtSelectorQueryVariable, rtSelectorRemoveVariable, rtSelectorGetVariable
RTresult RTAPI rtSelectorGetVisitProgram | ( | RTselector | selector, |
RTprogram * | program | ||
) |
Returns the currently assigned visit program.
Description
rtSelectorGetVisitProgram returns in program a handle of the visit program curently bound to selector.
[in] | selector | Selector node handle |
[out] | program | Current visit progam assigned to selector |
Return values
Relevant return values:
History
rtSelectorGetVisitProgram was introduced in OptiX 1.0.
See also rtSelectorSetVisitProgram
RTresult RTAPI rtSelectorQueryVariable | ( | RTselector | selector, |
const char * | name, | ||
RTvariable * | v | ||
) |
Returns a variable associated with a Selector node.
Description
Returns in v a handle to the variable identified by name, which is associated with the Selector node selector. The current value of a variable can be retrieved from its handle by using an appropriate rtVariableGet{...} function matching the variable's type.
[in] | selector | Selector node handle |
[in] | name | Variable identifier |
[out] | v | Variable handle |
Return values
Relevant return values:
History
rtSelectorQueryVariable was introduced in OptiX 1.0.
See also rtSelectorDeclareVariable, rtSelectorRemoveVariable, rtSelectorGetVariableCount, rtSelectorGetVariable, rtVariableGet{...}
RTresult RTAPI rtSelectorRemoveVariable | ( | RTselector | selector, |
RTvariable | v | ||
) |
Removes a variable from a Selector node.
Description
rtSelectorRemoveVariable removes the variable v from the Selector node selector and deletes it. The handle v must be considered invalid afterwards.
[in] | selector | Selector node handle |
[in] | v | Variable handle |
Return values
Relevant return values:
History
rtSelectorRemoveVariable was introduced in OptiX 1.0.
See also rtSelectorDeclareVariable, rtSelectorQueryVariable, rtSelectorGetVariableCount, rtSelectorGetVariable
RTresult RTAPI rtSelectorSetChild | ( | RTselector | selector, |
unsigned int | index, | ||
RTobject | child | ||
) |
Attaches a child node to a Selector node.
Description
Attaches a new child node child to the parent node selector. index specifies the number of the slot where the child node gets attached. The index value must be lower than the number previously set by rtSelectorSetChildCount, thus it must be in the range from 0 to rtSelectorGetChildCount -1. Legal child node types are RTgroup, RTselector, RTgeometrygroup, and RTtransform.
[in] | selector | Selector node handle |
[in] | index | Index of the parent slot the node child gets attached to |
[in] | child | Child node to be attached. Can be {RTgroup, RTselector, RTgeometrygroup, RTtransform} |
Return values
Relevant return values:
History
rtSelectorSetChild was introduced in OptiX 1.0.
See also rtSelectorSetChildCount, rtSelectorGetChildCount, rtSelectorGetChild, rtSelectorGetChildType
RTresult RTAPI rtSelectorSetChildCount | ( | RTselector | selector, |
unsigned int | count | ||
) |
Specifies the number of child nodes to be attached to a Selector node.
Description
rtSelectorSetChildCount allocates a number of children slots, i.e., it pre-defines the exact number of child nodes the parent Selector node selector will have. Child nodes have to be attached to the Selector node using rtSelectorSetChild. Empty slots will cause a validation error.
[in] | selector | Selector node handle |
[in] | count | Number of child nodes to be attached to selector |
Return values
Relevant return values:
History
rtSelectorSetChildCount was introduced in OptiX 1.0.
See also rtSelectorValidate, rtSelectorGetChildCount, rtSelectorSetChild, rtSelectorGetChild, rtSelectorGetChildType
RTresult RTAPI rtSelectorSetVisitProgram | ( | RTselector | selector, |
RTprogram | program | ||
) |
Assigns a visit program to a Selector node.
Description
rtSelectorSetVisitProgram specifies a visit program that is executed when the Selector node selector gets visited by a ray during traversal of the model graph. A visit program steers how traversal of the Selectors's children is performed. It usually chooses only a single child to continue traversal, but is also allowed to process zero or multiple children. Programs can be created from PTX files using rtProgramCreateFromPTXFile.
[in] | selector | Selector node handle |
[in] | program | Program handle associated with a visit program |
Return values
Relevant return values:
History
rtSelectorSetVisitProgram was introduced in OptiX 1.0.
See also rtSelectorGetVisitProgram, rtProgramCreateFromPTXFile
RTresult RTAPI rtSelectorValidate | ( | RTselector | selector | ) |
Checks a Selector node for internal consistency.
Description
rtSelectorValidate recursively checks consistency of the Selector node selector and its children, i.e., it tries to validate the whole model sub-tree with selector as root. For a Selector node to be valid, it must be assigned a visit program, and the number of its children must match the number specified by rtSelectorSetChildCount.
[in] | selector | Selector root node of a model sub-tree to be validated |
Return values
Relevant return values:
History
rtSelectorValidate was introduced in OptiX 1.0.
See also rtSelectorCreate, rtSelectorDestroy, rtSelectorGetContext, rtSelectorSetVisitProgram, rtSelectorSetChildCount, rtSelectorSetChild
RTresult RTAPI rtTextureSamplerCreate | ( | RTcontext | context, |
RTtexturesampler * | texturesampler | ||
) |
Creates a new texture sampler object.
Description
rtTextureSamplerCreate allocates a texture sampler object. Sets *texturesampler to the handle of a newly created texture sampler within context. Returns RT_ERROR_INVALID_VALUE if texturesampler is NULL.
[in] | context | The context the texture sampler object will be created in |
[out] | texturesampler | The return handle to the new texture sampler object |
Return values
Relevant return values:
History
rtTextureSamplerCreate was introduced in OptiX 1.0.
See also rtTextureSamplerDestroy
RTresult RTAPI rtTextureSamplerDestroy | ( | RTtexturesampler | texturesampler | ) |
Destroys a texture sampler object.
Description
rtTextureSamplerDestroy removes texturesampler from its context and deletes it. texturesampler should be a value returned by rtTextureSamplerCreate. After the call, texturesampler is no longer a valid handle. Any API object that referenced texturesampler will have its reference invalidated.
[in] | texturesampler | Handle of the texture sampler to destroy |
Return values
Relevant return values:
History
rtTextureSamplerDestroy was introduced in OptiX 1.0.
See also rtTextureSamplerCreate
RTresult RTAPI rtTextureSamplerGetArraySize | ( | RTtexturesampler | texturesampler, |
unsigned int * | num_textures_in_array | ||
) |
Gets the number of array slices present in a texture sampler.
Deprecated in OptiX 3.9
Description
rtTextureSamplerGetArraySize gets the number of texture array slices in texturesampler and stores it in *num_textures_in_array.
[in] | texturesampler | The texture sampler object to be queried |
[out] | num_textures_in_array | The return handle for the number of texture slices the texture sampler |
Return values
Relevant return values:
History
rtTextureSamplerGetArraySize was introduced in OptiX 1.0.
See also rtTextureSamplerSetArraySize
RTresult RTAPI rtTextureSamplerGetBuffer | ( | RTtexturesampler | texturesampler, |
unsigned int | deprecated0, | ||
unsigned int | deprecated1, | ||
RTbuffer * | buffer | ||
) |
Gets a buffer object handle from a texture sampler.
Deprecated
Description
rtTextureSamplerGetBuffer gets a buffer object from texturesampler and stores it in *buffer.
[in] | texturesampler | The texture sampler object to be queried for the buffer |
[in] | deprecated0 | Must be 0 |
[in] | deprecated1 | Must be 0 |
[out] | buffer | The return handle to the buffer attached to the texture sampler |
Return values
Relevant return values:
History
rtTextureSamplerGetBuffer was introduced in OptiX 1.0.
See also rtTextureSamplerSetBuffer
RTresult RTAPI rtTextureSamplerGetContext | ( | RTtexturesampler | texturesampler, |
RTcontext * | context | ||
) |
Gets the context object that created this texture sampler.
Description
rtTextureSamplerGetContext returns a handle to the context object that was used to create texturesampler. If context is NULL, returns RT_ERROR_INVALID_VALUE.
[in] | texturesampler | The texture sampler object to be queried for its context |
[out] | context | The return handle for the context object of the texture sampler |
Return values
Relevant return values:
History
rtTextureSamplerGetContext was introduced in OptiX 1.0.
See also rtContextCreate
RTresult RTAPI rtTextureSamplerGetFilteringModes | ( | RTtexturesampler | texturesampler, |
RTfiltermode * | minification, | ||
RTfiltermode * | magnification, | ||
RTfiltermode * | mipmapping | ||
) |
Gets the filtering modes of a texture sampler.
Description
rtTextureSamplerGetFilteringModes gets the minification, magnification and MIP mapping filtering modes from texturesampler and stores them in *minification, *magnification and *mipmapping, respectively. See rtTextureSamplerSetFilteringModes for the values RTfiltermode may take.
[in] | texturesampler | The texture sampler object to be queried |
[out] | minification | The return handle for the minification filtering mode of the texture sampler |
[out] | magnification | The return handle for the magnification filtering mode of the texture sampler |
[out] | mipmapping | The return handle for the MIP mapping filtering mode of the texture sampler |
Return values
Relevant return values:
History
rtTextureSamplerGetFilteringModes was introduced in OptiX 1.0.
See also rtTextureSamplerSetFilteringModes
RTresult RTAPI rtTextureSamplerGetId | ( | RTtexturesampler | texturesampler, |
int * | texture_id | ||
) |
Returns the texture ID of this texture sampler.
Description
rtTextureSamplerGetId returns a handle to the texture sampler texturesampler to be used in OptiX programs on the device to reference the associated texture. The returned ID cannot be used on the host side. If texture_id is NULL, returns RT_ERROR_INVALID_VALUE.
[in] | texturesampler | The texture sampler object to be queried for its ID |
[out] | texture_id | The returned device-side texture ID of the texture sampler |
Return values
Relevant return values:
History
rtTextureSamplerGetId was introduced in OptiX 3.0.
See also rtTextureSamplerCreate
RTresult RTAPI rtTextureSamplerGetIndexingMode | ( | RTtexturesampler | texturesampler, |
RTtextureindexmode * | indexmode | ||
) |
Gets the indexing mode of a texture sampler.
Description
rtTextureSamplerGetIndexingMode gets the indexing mode of texturesampler and stores it in *indexmode. See rtTextureSamplerSetIndexingMode for the values RTtextureindexmode may take.
[in] | texturesampler | The texture sampler object to be queried |
[out] | indexmode | The return handle for the indexing mode of the texture sampler |
Return values
Relevant return values:
History
rtTextureSamplerGetIndexingMode was introduced in OptiX 1.0.
See also rtTextureSamplerSetIndexingMode
RTresult RTAPI rtTextureSamplerGetMaxAnisotropy | ( | RTtexturesampler | texturesampler, |
float * | value | ||
) |
Gets the maximum anisotropy level for a texture sampler.
Description
rtTextureSamplerGetMaxAnisotropy gets the maximum anisotropy level for texturesampler and stores it in *value.
[in] | texturesampler | The texture sampler object to be queried |
[out] | value | The return handle for the maximum anisotropy level of the texture sampler |
Return values
Relevant return values:
History
rtTextureSamplerGetMaxAnisotropy was introduced in OptiX 1.0.
See also rtTextureSamplerSetMaxAnisotropy
RTresult RTAPI rtTextureSamplerGetMipLevelBias | ( | RTtexturesampler | texturesampler, |
float * | value | ||
) |
Gets the mipmap offset for a texture sampler.
Description
rtTextureSamplerGetMipLevelBias gets the mipmap offset for texturesampler and stores it in *value.
[in] | texturesampler | The texture sampler object to be queried |
[out] | value | The return handle for the mipmap offset of the texture sampler |
Return values
Relevant return values:
History
rtTextureSamplerGetMipLevelBias was introduced in OptiX 3.9.
See also rtTextureSamplerSetMipLevelBias
RTresult RTAPI rtTextureSamplerGetMipLevelClamp | ( | RTtexturesampler | texturesampler, |
float * | minLevel, | ||
float * | maxLevel | ||
) |
Gets the minimum and the maximum MIP level access range for a texture sampler.
Description
rtTextureSamplerGetMipLevelClamp gets the minimum and the maximum MIP level access range for texturesampler and stores it in *minLevel and maxLevel.
[in] | texturesampler | The texture sampler object to be queried |
[out] | minLevel | The return handle for the minimum mipmap level of the texture sampler |
[out] | maxLevel | The return handle for the maximum mipmap level of the texture sampler |
Return values
Relevant return values:
History
rtTextureSamplerGetMipLevelClamp was introduced in OptiX 3.9.
See also rtTextureSamplerSetMipLevelClamp
RTresult RTAPI rtTextureSamplerGetMipLevelCount | ( | RTtexturesampler | texturesampler, |
unsigned int * | num_mip_levels | ||
) |
Gets the number of MIP levels in a texture sampler.
Deprecated in OptiX 3.9
Description
rtTextureSamplerGetMipLevelCount gets the number of MIP levels contained in texturesampler and stores it in *num_mip_levels.
[in] | texturesampler | The texture sampler object to be queried |
[out] | num_mip_levels | The return handle for the number of MIP levels in the texture sampler |
Return values
Relevant return values:
History
rtTextureSamplerGetMipLevelCount was introduced in OptiX 1.0.
See also rtTextureSamplerSetMipLevelCount
RTresult RTAPI rtTextureSamplerGetReadMode | ( | RTtexturesampler | texturesampler, |
RTtexturereadmode * | readmode | ||
) |
Gets the read mode of a texture sampler.
Description
rtTextureSamplerGetReadMode gets the read mode of texturesampler and stores it in *readmode. See rtTextureSamplerSetReadMode for a list of values RTtexturereadmode can take.
[in] | texturesampler | The texture sampler object to be queried |
[out] | readmode | The return handle for the read mode of the texture sampler |
Return values
Relevant return values:
History
rtTextureSamplerGetReadMode was introduced in OptiX 1.0.
See also rtTextureSamplerSetReadMode
RTresult RTAPI rtTextureSamplerGetWrapMode | ( | RTtexturesampler | texturesampler, |
unsigned int | dimension, | ||
RTwrapmode * | wrapmode | ||
) |
Gets the wrap mode of a texture sampler.
Description
rtTextureSamplerGetWrapMode gets the texture wrapping mode of texturesampler and stores it in *wrapmode. See rtTextureSamplerSetWrapMode for a list of values RTwrapmode can take.
[in] | texturesampler | The texture sampler object to be queried |
[in] | dimension | Dimension for the wrapping |
[out] | wrapmode | The return handle for the wrap mode of the texture sampler |
Return values
Relevant return values:
History
rtTextureSamplerGetWrapMode was introduced in OptiX 1.0.
See also rtTextureSamplerSetWrapMode
RTresult RTAPI rtTextureSamplerSetArraySize | ( | RTtexturesampler | texturesampler, |
unsigned int | num_textures_in_array | ||
) |
Sets the array size of a texture sampler.
Deprecated in OptiX 3.9
Description
rtTextureSamplerSetArraySize specifies the number of texture array slices present in texturesampler as num_textures_in_array. After changing the number of slices in the array, buffers must be reassociated with texturesampler via rtTextureSamplerSetBuffer.
[in] | texturesampler | The texture sampler object to be changed |
[in] | num_textures_in_array | The new number of array slices of the texture sampler |
Return values
Relevant return values:
History
rtTextureSamplerSetArraySize was introduced in OptiX 1.0.
See also rtTextureSamplerGetArraySize
RTresult RTAPI rtTextureSamplerSetBuffer | ( | RTtexturesampler | texturesampler, |
unsigned int | deprecated0, | ||
unsigned int | deprecated1, | ||
RTbuffer | buffer | ||
) |
Attaches a buffer object to a texture sampler.
Deprecated in OptiX 3.9
Description
rtTextureSamplerSetBuffer attaches buffer to texturesampler.
[in] | texturesampler | The texture sampler object that will contain the buffer |
[in] | deprecated0 | Must be 0 |
[in] | deprecated1 | Must be 0 |
[in] | buffer | The buffer to be attached to the texture sampler |
Return values
Relevant return values:
History
rtTextureSamplerSetBuffer was introduced in OptiX 1.0.
See also rtTextureSamplerGetBuffer
RTresult RTAPI rtTextureSamplerSetFilteringModes | ( | RTtexturesampler | texturesampler, |
RTfiltermode | minification, | ||
RTfiltermode | magnification, | ||
RTfiltermode | mipmapping | ||
) |
Sets the filtering modes of a texture sampler.
Description
rtTextureSamplerSetFilteringModes sets the minification, magnification and MIP mapping filter modes for texturesampler. RTfiltermode must be one of the following values:
These filter modes specify how the texture sampler will interpolate buffer data that has been attached to it. minification and magnification must be one of RT_FILTER_NEAREST or RT_FILTER_LINEAR. mipmapping may be any of the three values but must be RT_FILTER_NONE if the texture sampler contains only a single MIP level or one of RT_FILTER_NEAREST or RT_FILTER_LINEAR if the texture sampler contains more than one MIP level.
[in] | texturesampler | The texture sampler object to be changed |
[in] | minification | The new minification filter mode of the texture sampler |
[in] | magnification | The new magnification filter mode of the texture sampler |
[in] | mipmapping | The new MIP mapping filter mode of the texture sampler |
Return values
Relevant return values:
History
rtTextureSamplerSetFilteringModes was introduced in OptiX 1.0.
See also rtTextureSamplerGetFilteringModes
RTresult RTAPI rtTextureSamplerSetIndexingMode | ( | RTtexturesampler | texturesampler, |
RTtextureindexmode | indexmode | ||
) |
Sets whether texture coordinates for this texture sampler are normalized.
Description
rtTextureSamplerSetIndexingMode sets the indexing mode of texturesampler to indexmode. indexmode can take on one of the following values:
These values are used to control the interpretation of texture coordinates. If the index mode is set to RT_TEXTURE_INDEX_NORMALIZED_COORDINATES, the texture is parameterized over [0,1]. If the index mode is set to RT_TEXTURE_INDEX_ARRAY_INDEX then texture coordinates are interpreted as array indices into the contents of the underlying buffer objects.
[in] | texturesampler | The texture sampler object to be changed |
[in] | indexmode | The new indexing mode of the texture sampler |
Return values
Relevant return values:
History
rtTextureSamplerSetIndexingMode was introduced in OptiX 1.0.
See also rtTextureSamplerGetIndexingMode
RTresult RTAPI rtTextureSamplerSetMaxAnisotropy | ( | RTtexturesampler | texturesampler, |
float | value | ||
) |
Sets the maximum anisotropy of a texture sampler.
Description
rtTextureSamplerSetMaxAnisotropy sets the maximum anisotropy of texturesampler to value. A float value specifies the maximum anisotropy ratio to be used when doing anisotropic filtering. This value will be clamped to the range [1,16]
[in] | texturesampler | The texture sampler object to be changed |
[in] | value | The new maximum anisotropy level of the texture sampler |
Return values
Relevant return values:
History
rtTextureSamplerSetMaxAnisotropy was introduced in OptiX 1.0.
See also rtTextureSamplerGetMaxAnisotropy
RTresult RTAPI rtTextureSamplerSetMipLevelBias | ( | RTtexturesampler | texturesampler, |
float | value | ||
) |
Sets the mipmap offset of a texture sampler.
Description
rtTextureSamplerSetMipLevelBias sets the offset to be applied to the calculated mipmap level.
[in] | texturesampler | The texture sampler object to be changed |
[in] | value | The new mipmap offset of the texture sampler |
Return values
Relevant return values:
History
rtTextureSamplerSetMipLevelBias was introduced in OptiX 3.9.
See also rtTextureSamplerGetMipLevelBias
RTresult RTAPI rtTextureSamplerSetMipLevelClamp | ( | RTtexturesampler | texturesampler, |
float | minLevel, | ||
float | maxLevel | ||
) |
Sets the minimum and the maximum MIP level access range of a texture sampler.
Description
rtTextureSamplerSetMipLevelClamp sets lower end and the upper end of the MIP level range to clamp access to.
[in] | texturesampler | The texture sampler object to be changed |
[in] | minLevel | The new minimum mipmap level of the texture sampler |
[in] | maxLevel | The new maximum mipmap level of the texture sampler |
Return values
Relevant return values:
History
rtTextureSamplerSetMipLevelClamp was introduced in OptiX 3.9.
See also rtTextureSamplerGetMipLevelClamp
RTresult RTAPI rtTextureSamplerSetMipLevelCount | ( | RTtexturesampler | texturesampler, |
unsigned int | num_mip_levels | ||
) |
Sets the number of MIP levels in a texture sampler.
Deprecated in OptiX 3.9
Description
rtTextureSamplerSetMipLevelCount sets the number of MIP levels in texturesampler to num_mip_levels.
[in] | texturesampler | The texture sampler object to be changed |
[in] | num_mip_levels | The new number of MIP levels of the texture sampler |
Return values
Relevant return values:
History
rtTextureSamplerSetMipLevelCount was introduced in OptiX 1.0.
See also rtTextureSamplerGetMipLevelCount
RTresult RTAPI rtTextureSamplerSetReadMode | ( | RTtexturesampler | texturesampler, |
RTtexturereadmode | readmode | ||
) |
Sets the read mode of a texture sampler.
Description
rtTextureSamplerSetReadMode sets the data read mode of texturesampler to readmode. readmode can take one of the following values:
RT_TEXTURE_READ_ELEMENT_TYPE_SRGB and RT_TEXTURE_READ_NORMALIZED_FLOAT_SRGB were introduced in OptiX 3.9 and apply sRGB to linear conversion during texture read for 8-bit integer buffer formats. readmode controls the returned value of the texture sampler when it is used to sample textures. RT_TEXTURE_READ_ELEMENT_TYPE will return data of the type of the underlying buffer objects. RT_TEXTURE_READ_NORMALIZED_FLOAT will return floating point values normalized by the range of the underlying type. If the underlying type is floating point, RT_TEXTURE_READ_NORMALIZED_FLOAT and RT_TEXTURE_READ_ELEMENT_TYPE are equivalent, always returning the unmodified floating point value.
For example, a texture sampler that samples a buffer of type RT_FORMAT_UNSIGNED_BYTE with a read mode of RT_TEXTURE_READ_NORMALIZED_FLOAT will convert integral values from the range [0,255] to floating point values in the range [0,1] automatically as the buffer is sampled from.
[in] | texturesampler | The texture sampler object to be changed |
[in] | readmode | The new read mode of the texture sampler |
Return values
Relevant return values:
History
rtTextureSamplerSetReadMode was introduced in OptiX 1.0.
See also rtTextureSamplerGetReadMode
RTresult RTAPI rtTextureSamplerSetWrapMode | ( | RTtexturesampler | texturesampler, |
unsigned int | dimension, | ||
RTwrapmode | wrapmode | ||
) |
Sets the wrapping mode of a texture sampler.
Description
rtTextureSamplerSetWrapMode sets the wrapping mode of texturesampler to wrapmode for the texture dimension specified by dimension. wrapmode can take one of the following values:
The wrapping mode controls the behavior of the texture sampler as texture coordinates wrap around the range specified by the indexing mode. These values mirror the CUDA behavior of textures. See CUDA programming guide for details.
[in] | texturesampler | The texture sampler object to be changed |
[in] | dimension | Dimension of the texture |
[in] | wrapmode | The new wrap mode of the texture sampler |
Return values
Relevant return values:
History
rtTextureSamplerSetWrapMode was introduced in OptiX 1.0. RT_WRAP_MIRROR and RT_WRAP_CLAMP_TO_BORDER were introduced in OptiX 3.0.
See also rtTextureSamplerGetWrapMode
RTresult RTAPI rtTextureSamplerValidate | ( | RTtexturesampler | texturesampler | ) |
Validates the state of a texture sampler.
Description
rtTextureSamplerValidate checks texturesampler for completeness. If texturesampler does not have buffers attached to all of its MIP levels and array slices or if the filtering modes are incompatible with the current MIP level and array slice configuration then returns RT_ERROR_INVALID_CONTEXT.
[in] | texturesampler | The texture sampler to be validated |
Return values
Relevant return values:
History
rtTextureSamplerValidate was introduced in OptiX 1.0.
See also rtContextValidate
RTresult RTAPI rtTransformCreate | ( | RTcontext | context, |
RTtransform * | transform | ||
) |
Creates a new Transform node.
Description
Creates a new Transform node within the given context. For the node to be functional, a child node must be attached using rtTransformSetChild. A transformation matrix can be associated with the transform node with rtTransformSetMatrix. Sets *transform to the handle of a newly created transform within context. Returns RT_ERROR_INVALID_VALUE if transform is NULL.
[in] | context | Specifies the rendering context of the Transform node |
[out] | transform | New Transform node handle |
Return values
Relevant return values:
History
rtTransformCreate was introduced in OptiX 1.0.
See also rtTransformDestroy, rtTransformValidate, rtTransformGetContext, rtTransformSetMatrix, rtTransformGetMatrix, rtTransformSetChild, rtTransformGetChild, rtTransformGetChildType
RTresult RTAPI rtTransformDestroy | ( | RTtransform | transform | ) |
Destroys a transform node.
Description
rtTransformDestroy removes transform from its context and deletes it. transform should be a value returned by rtTransformCreate. No child graph nodes are destroyed. After the call, transform is no longer a valid handle.
[in] | transform | Handle of the transform node to destroy |
Return values
Relevant return values:
History
rtTransformDestroy was introduced in OptiX 1.0.
See also rtTransformCreate, rtTransformValidate, rtTransformGetContext
RTresult RTAPI rtTransformGetChild | ( | RTtransform | transform, |
RTobject * | child | ||
) |
Returns the child node that is attached to a Transform node.
Description
rtTransformGetChild returns in child a handle of the child node currently attached to transform. The returned pointer is of generic type RTobject and needs to be cast to the actual child type, which can be RTgroup, RTselector, RTgeometrygroup, or RTtransform. The actual type of child can be queried using rtTransformGetChildType. Returns RT_ERROR_INVALID_VALUE if given a NULL pointer.
[in] | transform | Transform node handle |
[out] | child | Child node handle. Can be {RTgroup, RTselector, RTgeometrygroup, RTtransform} |
Return values
Relevant return values:
History
rtTransformGetChild was introduced in OptiX 1.0.
See also rtTransformSetChild, rtTransformGetChildType
RTresult RTAPI rtTransformGetChildType | ( | RTtransform | transform, |
RTobjecttype * | type | ||
) |
Returns type information about a Transform child node.
Description
rtTransformGetChildType queries the type of the child node attached to transform. If no child is attached, *type is set to RT_OBJECTTYPE_UNKNOWN and RT_ERROR_INVALID_VALUE is returned. Returns RT_ERROR_INVALID_VALUE if given a NULL pointer. The returned type is one of:
[in] | transform | Transform node handle |
[out] | type | Type of the child node |
Return values
Relevant return values:
History
rtTransformGetChildType was introduced in OptiX 1.0.
See also rtTransformSetChild, rtTransformGetChild
RTresult RTAPI rtTransformGetContext | ( | RTtransform | transform, |
RTcontext * | context | ||
) |
Returns the context of a Transform node.
Description
rtTransformGetContext queries a transform node for its associated context. transform specifies the transform node to query, and should be a value returned by rtTransformCreate. Sets *context to the context associated with transform.
[in] | transform | Transform node handle |
[out] | context | The context associated with transform |
Return values
Relevant return values:
History
rtTransformGetContext was introduced in OptiX 1.0.
See also rtTransformCreate, rtTransformDestroy, rtTransformValidate
RTresult RTAPI rtTransformGetMatrix | ( | RTtransform | transform, |
int | transpose, | ||
float * | matrix, | ||
float * | inverse_matrix | ||
) |
Returns the affine matrix and its inverse associated with a Transform node.
Description
rtTransformGetMatrix returns in matrix the affine matrix that is currently used to perform a transformation of the geometry contained in the sub-tree with transform as root. The corresponding inverse matrix will be retured in inverse_matrix. One or both pointers are allowed to be NULL. If transpose is 0, matrices are returned in row-major format, i.e., matrix rows are contiguously laid out in memory. If transpose is non-zero, matrices are returned in column-major format. If non-NULL, matrix pointers must point to a float array of at least 16 elements.
[in] | transform | Transform node handle |
[in] | transpose | Flag indicating whether matrix and inverse_matrix should be transposed |
[out] | matrix | Affine matrix (4x4 float array) |
[out] | inverse_matrix | Inverted form of matrix |
Return values
Relevant return values:
History
rtTransformGetMatrix was introduced in OptiX 1.0.
See also rtTransformSetMatrix
RTresult RTAPI rtTransformSetChild | ( | RTtransform | transform, |
RTobject | child | ||
) |
Attaches a child node to a Transform node.
Description
Attaches a child node child to the parent node transform. Legal child node types are RTgroup, RTselector, RTgeometrygroup, and RTtransform. A transform node must have exactly one child. If a tranformation matrix has been attached to transform with rtTransformSetMatrix, it is effective on the model sub-tree with child as root node.
[in] | transform | Transform node handle |
[in] | child | Child node to be attached. Can be {RTgroup, RTselector, RTgeometrygroup, RTtransform} |
Return values
Relevant return values:
History
rtTransformSetChild was introduced in OptiX 1.0.
See also rtTransformSetMatrix, rtTransformGetChild, rtTransformGetChildType
RTresult RTAPI rtTransformSetMatrix | ( | RTtransform | transform, |
int | transpose, | ||
const float * | matrix, | ||
const float * | inverse_matrix | ||
) |
Associates an affine transformation matrix with a Transform node.
Description
rtTransformSetMatrix associates a 4x4 matrix with the Transform node transform. The provided transformation matrix results in a corresponding affine transformation of all geometry contained in the sub-tree with transform as root. At least one of the pointers matrix and inverse_matrix must be non-NULL. If exactly one pointer is valid, the other matrix will be computed. If both are valid, the matrices will be used as-is. If transpose is 0, source matrices are expected to be in row-major format, i.e., matrix rows are contiguously laid out in memory:
float matrix[4*4] = { a11, a12, a13, a14, a21, a22, a23, a24, a31, a32, a33, a34, a41, a42, a43, a44 };
Here, the translational elements a14, a24, and a34 are at the 4th, 8th, and 12th position the matrix array. If the supplied matrices are in column-major format, a non-0 transpose flag can be used to trigger an automatic transpose of the input matrices.
[in] | transform | Transform node handle |
[in] | transpose | Flag indicating whether matrix and inverse_matrix should be transposed |
[in] | matrix | Affine matrix (4x4 float array) |
[in] | inverse_matrix | Inverted form of matrix |
Return values
Relevant return values:
History
rtTransformSetMatrix was introduced in OptiX 1.0.
See also rtTransformGetMatrix
RTresult RTAPI rtTransformValidate | ( | RTtransform | transform | ) |
Checks a Transform node for internal consistency.
Description
rtTransformValidate recursively checks consistency of the Transform node transform and its child, i.e., it tries to validate the whole model sub-tree with transform as root. For a Transform node to be valid, it must have a child node attached. It is, however, not required to explicitly set a transformation matrix. Without a specified transformation matrix, the identity matrix is applied.
[in] | transform | Transform root node of a model sub-tree to be validated |
Return values
Relevant return values:
History
rtTransformValidate was introduced in OptiX 1.0.
See also rtTransformCreate, rtTransformDestroy, rtTransformGetContext, rtTransformSetMatrix, rtTransformSetChild
RTresult RTAPI rtVariableGet1f | ( | RTvariable | v, |
float * | f1 | ||
) |
Functions designed to modify the value of a program variable.
Description
rtVariableGet functions return the value of a program variable or variable array. The target variable is specificed by v.
The commands rtVariableGet{1-2-3-4}{f-i-ui}v are used to query the value of a program variable specified by v using the pointers passed as arguments as return locations for each component of the vector-typed variable. The number specified in the command should match the number of components in the data type of the specified program variable (e.g., 1 for float, int, unsigned int; 2 for float2, int2, uint2, etc.). The suffix f indicates that floating-point values are expected to be returned, the suffix i indicates that integer values are expected, and the suffix ui indicates that unsigned integer values are expected, and this type should also match the data type of the specified program variable. The f variants of this function should be used to query values for program variables defined as float, float2, float3, float4, or arrays of these. The i variants of this function should be used to query values for program variables defined as int, int2, int3, int4, or arrays of these. The ui variants of this function should be used to query values for program variables defined as unsigned int, uint2, uint3, uint4, or arrays of these. The v variants of this function should be used to return the program variable's value to the array specified by parameter v. In this case, the array v should be large enough to accommodate all of the program variable's components.
The commands rtVariableGetMatrix{2-3-4}x{2-3-4}fv are used to query the value of a program variable whose data type is a matrix. The numbers in the command names are interpreted as the dimensionality of the matrix. For example, 2x4 indicates a 2 x 4 matrix with 2 columns and 4 rows (i.e., 8 values). If transpose is 0, the matrix is returned in row major order, otherwise in column major order.
Return values
Relevant return values:
History
rtVariableGet were introduced in OptiX 1.0.
See also rtVariableSet, rtVariableGetType, rtContextDeclareVariable
[in] | v | Specifies the program variable whose value is to be returned |
[in] | f1 | Float value to be returned |
RTresult RTAPI rtVariableGet1fv | ( | RTvariable | v, |
float * | f | ||
) |
[in] | v | Specifies the program variable whose value is to be returned |
[in] | f | Array of float value(s) to be returned |
RTresult RTAPI rtVariableGet1i | ( | RTvariable | v, |
int * | i1 | ||
) |
[in] | v | Specifies the program variable whose value is to be returned |
[in] | i1 | Integer value to be returned |
RTresult RTAPI rtVariableGet1iv | ( | RTvariable | v, |
int * | i | ||
) |
[in] | v | Specifies the program variable whose value is to be returned |
[in] | i | Array of integer values to be returned |
RTresult RTAPI rtVariableGet1ui | ( | RTvariable | v, |
unsigned int * | u1 | ||
) |
[in] | v | Specifies the program variable whose value is to be returned |
[in] | u1 | Unsigned integer value to be returned |
RTresult RTAPI rtVariableGet1uiv | ( | RTvariable | v, |
unsigned int * | u | ||
) |
[in] | v | Specifies the program variable whose value is to be returned |
[in] | u | Array of unsigned integer values to be returned |
RTresult RTAPI rtVariableGet2f | ( | RTvariable | v, |
float * | f1, | ||
float * | f2 | ||
) |
[in] | v | Specifies the program variable whose value is to be returned |
[in] | f1 | Float value to be returned |
[in] | f2 | Float value to be returned |
RTresult RTAPI rtVariableGet2fv | ( | RTvariable | v, |
float * | f | ||
) |
[in] | v | Specifies the program variable whose value is to be returned |
[in] | f | Array of float value(s) to be returned |
RTresult RTAPI rtVariableGet2i | ( | RTvariable | v, |
int * | i1, | ||
int * | i2 | ||
) |
[in] | v | Specifies the program variable whose value is to be returned |
[in] | i1 | Integer value to be returned |
[in] | i2 | Integer value to be returned |
RTresult RTAPI rtVariableGet2iv | ( | RTvariable | v, |
int * | i | ||
) |
[in] | v | Specifies the program variable whose value is to be returned |
[in] | i | Array of integer values to be returned |
RTresult RTAPI rtVariableGet2ui | ( | RTvariable | v, |
unsigned int * | u1, | ||
unsigned int * | u2 | ||
) |
[in] | v | Specifies the program variable whose value is to be returned |
[in] | u1 | Unsigned integer value to be returned |
[in] | u2 | Unsigned integer value to be returned |
RTresult RTAPI rtVariableGet2uiv | ( | RTvariable | v, |
unsigned int * | u | ||
) |
[in] | v | Specifies the program variable whose value is to be returned |
[in] | u | Array of unsigned integer values to be returned |
RTresult RTAPI rtVariableGet3f | ( | RTvariable | v, |
float * | f1, | ||
float * | f2, | ||
float * | f3 | ||
) |
[in] | v | Specifies the program variable whose value is to be returned |
[in] | f1 | Float value to be returned |
[in] | f2 | Float value to be returned |
[in] | f3 | Float value to be returned |
RTresult RTAPI rtVariableGet3fv | ( | RTvariable | v, |
float * | f | ||
) |
[in] | v | Specifies the program variable whose value is to be returned |
[in] | f | Array of float value(s) to be returned |
RTresult RTAPI rtVariableGet3i | ( | RTvariable | v, |
int * | i1, | ||
int * | i2, | ||
int * | i3 | ||
) |
[in] | v | Specifies the program variable whose value is to be returned |
[in] | i1 | Integer value to be returned |
[in] | i2 | Integer value to be returned |
[in] | i3 | Integer value to be returned |
RTresult RTAPI rtVariableGet3iv | ( | RTvariable | v, |
int * | i | ||
) |
[in] | v | Specifies the program variable whose value is to be returned |
[in] | i | Array of integer values to be returned |
RTresult RTAPI rtVariableGet3ui | ( | RTvariable | v, |
unsigned int * | u1, | ||
unsigned int * | u2, | ||
unsigned int * | u3 | ||
) |
[in] | v | Specifies the program variable whose value is to be returned |
[in] | u1 | Unsigned integer value to be returned |
[in] | u2 | Unsigned integer value to be returned |
[in] | u3 | Unsigned integer value to be returned |
RTresult RTAPI rtVariableGet3uiv | ( | RTvariable | v, |
unsigned int * | u | ||
) |
[in] | v | Specifies the program variable whose value is to be returned |
[in] | u | Array of unsigned integer values to be returned |
RTresult RTAPI rtVariableGet4f | ( | RTvariable | v, |
float * | f1, | ||
float * | f2, | ||
float * | f3, | ||
float * | f4 | ||
) |
[in] | v | Specifies the program variable whose value is to be returned |
[in] | f1 | Float value to be returned |
[in] | f2 | Float value to be returned |
[in] | f3 | Float value to be returned |
[in] | f4 | Float value to be returned |
RTresult RTAPI rtVariableGet4fv | ( | RTvariable | v, |
float * | f | ||
) |
[in] | v | Specifies the program variable whose value is to be returned |
[in] | f | Array of float value(s) to be returned |
RTresult RTAPI rtVariableGet4i | ( | RTvariable | v, |
int * | i1, | ||
int * | i2, | ||
int * | i3, | ||
int * | i4 | ||
) |
[in] | v | Specifies the program variable whose value is to be returned |
[in] | i1 | Integer value to be returned |
[in] | i2 | Integer value to be returned |
[in] | i3 | Integer value to be returned |
[in] | i4 | Integer value to be returned |
RTresult RTAPI rtVariableGet4iv | ( | RTvariable | v, |
int * | i | ||
) |
[in] | v | Specifies the program variable whose value is to be returned |
[in] | i | Array of integer values to be returned |
RTresult RTAPI rtVariableGet4ui | ( | RTvariable | v, |
unsigned int * | u1, | ||
unsigned int * | u2, | ||
unsigned int * | u3, | ||
unsigned int * | u4 | ||
) |
[in] | v | Specifies the program variable whose value is to be returned |
[in] | u1 | Unsigned integer value to be returned |
[in] | u2 | Unsigned integer value to be returned |
[in] | u3 | Unsigned integer value to be returned |
[in] | u4 | Unsigned integer value to be returned |
RTresult RTAPI rtVariableGet4uiv | ( | RTvariable | v, |
unsigned int * | u | ||
) |
[in] | v | Specifies the program variable whose value is to be returned |
[in] | u | Array of unsigned integer values to be returned |
RTresult RTAPI rtVariableGetAnnotation | ( | RTvariable | v, |
const char ** | annotation_return | ||
) |
Queries the annotation string of a program variable.
Description
rtVariableGetAnnotation queries a program variable's annotation string. A pointer to the string containing the annotation is returned in *annotation_return. If v is not a valid variable, this call sets *annotation_return to NULL and returns RT_ERROR_INVALID_VALUE. *annotation_return will point to valid memory until another API function that returns a string is called.
[in] | v | Specifies the program variable to be queried |
[out] | annotation_return | Returns the program variable's annotation string |
Return values
Relevant return values:
History
rtVariableGetAnnotation was introduced in OptiX 1.0.
See also rtDeclareVariable, rtDeclareAnnotation
RTresult RTAPI rtVariableGetContext | ( | RTvariable | v, |
RTcontext * | context | ||
) |
Returns the context associated with a program variable.
Description
rtVariableGetContext queries the context associated with a program variable. The target variable is specified by v. The context of the program variable is returned to *context if the pointer context is not NULL. If v is not a valid variable, *context is set to NULL and RT_ERROR_INVALID_VALUE is returned.
[in] | v | Specifies the program variable to be queried |
[out] | context | Returns the context associated with the program variable |
Return values
Relevant return values:
History
rtVariableGetContext was introduced in OptiX 1.0.
See also rtContextDeclareVariable
RTresult RTAPI rtVariableGetMatrix2x2fv | ( | RTvariable | v, |
int | transpose, | ||
float * | m | ||
) |
[in] | v | Specifies the program variable whose value is to be returned |
[in] | transpose | Specify(ies) row-major or column-major order |
[in] | m | Array of float values to be returned |
RTresult RTAPI rtVariableGetMatrix2x3fv | ( | RTvariable | v, |
int | transpose, | ||
float * | m | ||
) |
[in] | v | Specifies the program variable whose value is to be returned |
[in] | transpose | Specify(ies) row-major or column-major order |
[in] | m | Array of float values to be returned |
RTresult RTAPI rtVariableGetMatrix2x4fv | ( | RTvariable | v, |
int | transpose, | ||
float * | m | ||
) |
[in] | v | Specifies the program variable whose value is to be returned |
[in] | transpose | Specify(ies) row-major or column-major order |
[in] | m | Array of float values to be returned |
RTresult RTAPI rtVariableGetMatrix3x2fv | ( | RTvariable | v, |
int | transpose, | ||
float * | m | ||
) |
[in] | v | Specifies the program variable whose value is to be returned |
[in] | transpose | Specify(ies) row-major or column-major order |
[in] | m | Array of float values to be returned |
RTresult RTAPI rtVariableGetMatrix3x3fv | ( | RTvariable | v, |
int | transpose, | ||
float * | m | ||
) |
[in] | v | Specifies the program variable whose value is to be returned |
[in] | transpose | Specify(ies) row-major or column-major order |
[in] | m | Array of float values to be returned |
RTresult RTAPI rtVariableGetMatrix3x4fv | ( | RTvariable | v, |
int | transpose, | ||
float * | m | ||
) |
[in] | v | Specifies the program variable whose value is to be returned |
[in] | transpose | Specify(ies) row-major or column-major order |
[in] | m | Array of float values to be returned |
RTresult RTAPI rtVariableGetMatrix4x2fv | ( | RTvariable | v, |
int | transpose, | ||
float * | m | ||
) |
[in] | v | Specifies the program variable whose value is to be returned |
[in] | transpose | Specify(ies) row-major or column-major order |
[in] | m | Array of float values to be returned |
RTresult RTAPI rtVariableGetMatrix4x3fv | ( | RTvariable | v, |
int | transpose, | ||
float * | m | ||
) |
[in] | v | Specifies the program variable whose value is to be returned |
[in] | transpose | Specify(ies) row-major or column-major order |
[in] | m | Array of float values to be returned |
RTresult RTAPI rtVariableGetMatrix4x4fv | ( | RTvariable | v, |
int | transpose, | ||
float * | m | ||
) |
[in] | v | Specifies the program variable whose value is to be returned |
[in] | transpose | Specify(ies) row-major or column-major order |
[in] | m | Array of float values to be returned |
RTresult RTAPI rtVariableGetName | ( | RTvariable | v, |
const char ** | name_return | ||
) |
Queries the name of a program variable.
Description
Queries a program variable's name. The variable of interest is specified by variable, which should be a value returned by rtContextDeclareVariable. A pointer to the string containing the name of the variable is returned in *name_return. If v is not a valid variable, this call sets *name_return to NULL and returns RT_ERROR_INVALID_VALUE. *name_return will point to valid memory until another API function that returns a string is called.
[in] | v | Specifies the program variable to be queried |
[out] | name_return | Returns the program variable's name |
Return values
Relevant return values:
History
rtVariableGetName was introduced in OptiX 1.0.
See also rtContextDeclareVariable
RTresult RTAPI rtVariableGetObject | ( | RTvariable | v, |
RTobject * | object | ||
) |
Returns the value of a OptiX object program variable.
Description
rtVariableGetObject queries the value of a program variable whose data type is a OptiX object. The target variable is specified by v. The value of the program variable is returned in *object. The concrete type of the program variable can be queried using rtVariableGetType, and the RTobject handle returned by rtVariableGetObject may safely be cast to an OptiX handle of corresponding type. If v is not a valid variable, this call sets *object to NULL and returns RT_ERROR_INVALID_VALUE.
[in] | v | Specifies the program variable to be queried |
[out] | object | Returns the value of the program variable |
Return values
Relevant return values:
History
rtVariableGetObject was introduced in OptiX 1.0.
See also rtVariableSetObject, rtVariableGetType, rtContextDeclareVariable
RTresult RTAPI rtVariableGetSize | ( | RTvariable | v, |
RTsize * | size | ||
) |
Queries the size, in bytes, of a variable.
Description
rtVariableGetSize queries a declared program variable for its size in bytes. This is most often used to query the size of a variable that has a user-defined type. Builtin types (int, float, unsigned int, etc.) may be queried, but object typed variables, such as buffers, texture samplers and graph nodes, cannot be queried and will return RT_ERROR_INVALID_VALUE.
[in] | v | Specifies the program variable to be queried |
[out] | size | Specifies a pointer where the size of the variable, in bytes, will be returned |
Return values
Relevant return values:
History
rtVariableGetSize was introduced in OptiX 1.0.
RTresult RTAPI rtVariableGetType | ( | RTvariable | v, |
RTobjecttype * | type_return | ||
) |
Returns type information about a program variable.
Description
rtVariableGetType queries a program variable's type. The variable of interest is specified by v. The program variable's type enumeration is returned in *type_return, if it is not NULL. It is one of the following:
Sets *type_return to RT_OBJECTTYPE_UNKNOWN if v is not a valid variable. Returns RT_ERROR_INVALID_VALUE if given a NULL pointer.
[in] | v | Specifies the program variable to be queried |
[out] | type_return | Returns the type of the program variable |
Return values
Relevant return values:
History
rtVariableGetType was introduced in OptiX 1.0.
See also rtContextDeclareVariable
RTresult RTAPI rtVariableGetUserData | ( | RTvariable | v, |
RTsize | size, | ||
void * | ptr | ||
) |
Defined.
Description
rtVariableGetUserData queries the value of a program variable whose data type is user-defined. The variable of interest is specified by v. The size of the variable's value must match the value given by the parameter size. The value of the program variable is copied to the memory region pointed to by ptr. The storage at location ptr must be large enough to accommodate all of the program variable's value data. If v is not a valid variable, this call has no effect and returns RT_ERROR_INVALID_VALUE.
[in] | v | Specifies the program variable to be queried |
[in] | size | Specifies the size of the program variable, in bytes |
[out] | ptr | Location in which to store the value of the variable |
Return values
Relevant return values:
History
rtVariableGetUserData was introduced in OptiX 1.0.
RTresult RTAPI rtVariableSet1f | ( | RTvariable | v, |
float | f1 | ||
) |
Functions designed to modify the value of a program variable.
Description
rtVariableSet functions modify the value of a program variable or variable array. The target variable is specificed by v, which should be a value returned by rtContextGetVariable.
The commands rtVariableSet{1-2-3-4}{f-i-ui}v are used to modify the value of a program variable specified by v using the values passed as arguments. The number specified in the command should match the number of components in the data type of the specified program variable (e.g., 1 for float, int, unsigned int; 2 for float2, int2, uint2, etc.). The suffix f indicates that v has floating point type, the suffix i indicates that v has integral type, and the suffix ui indicates that that v has unsigned integral type. The v variants of this function should be used to load the program variable's value from the array specified by parameter v. In this case, the array v should contain as many elements as there are program variable components.
The commands rtVariableSetMatrix{2-3-4}x{2-3-4}fv are used to modify the value of a program variable whose data type is a matrix. The numbers in the command names are the number of rows and columns, respectively. For example, 2x4 indicates a matrix with 2 rows and 4 columns (i.e., 8 values). If transpose is 0, the matrix is specified in row-major order, otherwise in column-major order or, equivalently, as a matrix with the number of rows and columns swapped in row-major order.
If v is not a valid variable, these calls have no effect and return RT_ERROR_INVALID_VALUE
Return values
Relevant return values:
History
rtVariableSet were introduced in OptiX 1.0.
See also rtVariableGet, rtVariableSet, rtDeclareVariable
[in] | v | Specifies the program variable to be modified |
[in] | f1 | Specifies the new float value of the program variable |
RTresult RTAPI rtVariableSet1fv | ( | RTvariable | v, |
const float * | f | ||
) |
[in] | v | Specifies the program variable to be modified |
[in] | f | Array of float values to set the variable to |
RTresult RTAPI rtVariableSet1i | ( | RTvariable | v, |
int | i1 | ||
) |
[in] | v | Specifies the program variable to be modified |
[in] | i1 | Specifies the new integer value of the program variable |
RTresult RTAPI rtVariableSet1iv | ( | RTvariable | v, |
const int * | i | ||
) |
[in] | v | Specifies the program variable to be modified |
[in] | i | Array of integer values to set the variable to |
RTresult RTAPI rtVariableSet1ui | ( | RTvariable | v, |
unsigned int | u1 | ||
) |
[in] | v | Specifies the program variable to be modified |
[in] | u1 | Specifies the new unsigned integer value of the program variable |
RTresult RTAPI rtVariableSet1uiv | ( | RTvariable | v, |
const unsigned int * | u | ||
) |
[in] | v | Specifies the program variable to be modified |
[in] | u | Array of unsigned integer values to set the variable to |
RTresult RTAPI rtVariableSet2f | ( | RTvariable | v, |
float | f1, | ||
float | f2 | ||
) |
[in] | v | Specifies the program variable to be modified |
[in] | f1 | Specifies the new float value of the program variable |
[in] | f2 | Specifies the new float value of the program variable |
RTresult RTAPI rtVariableSet2fv | ( | RTvariable | v, |
const float * | f | ||
) |
[in] | v | Specifies the program variable to be modified |
[in] | f | Array of float values to set the variable to |
RTresult RTAPI rtVariableSet2i | ( | RTvariable | v, |
int | i1, | ||
int | i2 | ||
) |
[in] | v | Specifies the program variable to be modified |
[in] | i1 | Specifies the new integer value of the program variable |
[in] | i2 | Specifies the new integer value of the program variable |
RTresult RTAPI rtVariableSet2iv | ( | RTvariable | v, |
const int * | i | ||
) |
[in] | v | Specifies the program variable to be modified |
[in] | i | Array of integer values to set the variable to |
RTresult RTAPI rtVariableSet2ui | ( | RTvariable | v, |
unsigned int | u1, | ||
unsigned int | u2 | ||
) |
[in] | v | Specifies the program variable to be modified |
[in] | u1 | Specifies the new unsigned integer value of the program variable |
[in] | u2 | Specifies the new unsigned integer value of the program variable |
RTresult RTAPI rtVariableSet2uiv | ( | RTvariable | v, |
const unsigned int * | u | ||
) |
[in] | v | Specifies the program variable to be modified |
[in] | u | Array of unsigned integer values to set the variable to |
RTresult RTAPI rtVariableSet3f | ( | RTvariable | v, |
float | f1, | ||
float | f2, | ||
float | f3 | ||
) |
[in] | v | Specifies the program variable to be modified |
[in] | f1 | Specifies the new float value of the program variable |
[in] | f2 | Specifies the new float value of the program variable |
[in] | f3 | Specifies the new float value of the program variable |
RTresult RTAPI rtVariableSet3fv | ( | RTvariable | v, |
const float * | f | ||
) |
[in] | v | Specifies the program variable to be modified |
[in] | f | Array of float values to set the variable to |
RTresult RTAPI rtVariableSet3i | ( | RTvariable | v, |
int | i1, | ||
int | i2, | ||
int | i3 | ||
) |
[in] | v | Specifies the program variable to be modified |
[in] | i1 | Specifies the new integer value of the program variable |
[in] | i2 | Specifies the new integer value of the program variable |
[in] | i3 | Specifies the new integer value of the program variable |
RTresult RTAPI rtVariableSet3iv | ( | RTvariable | v, |
const int * | i | ||
) |
[in] | v | Specifies the program variable to be modified |
[in] | i | Array of integer values to set the variable to |
RTresult RTAPI rtVariableSet3ui | ( | RTvariable | v, |
unsigned int | u1, | ||
unsigned int | u2, | ||
unsigned int | u3 | ||
) |
[in] | v | Specifies the program variable to be modified |
[in] | u1 | Specifies the new unsigned integer value of the program variable |
[in] | u2 | Specifies the new unsigned integer value of the program variable |
[in] | u3 | Specifies the new unsigned integer value of the program variable |
RTresult RTAPI rtVariableSet3uiv | ( | RTvariable | v, |
const unsigned int * | u | ||
) |
[in] | v | Specifies the program variable to be modified |
[in] | u | Array of unsigned integer values to set the variable to |
RTresult RTAPI rtVariableSet4f | ( | RTvariable | v, |
float | f1, | ||
float | f2, | ||
float | f3, | ||
float | f4 | ||
) |
[in] | v | Specifies the program variable to be modified |
[in] | f1 | Specifies the new float value of the program variable |
[in] | f2 | Specifies the new float value of the program variable |
[in] | f3 | Specifies the new float value of the program variable |
[in] | f4 | Specifies the new float value of the program variable |
RTresult RTAPI rtVariableSet4fv | ( | RTvariable | v, |
const float * | f | ||
) |
[in] | v | Specifies the program variable to be modified |
[in] | f | Array of float values to set the variable to |
RTresult RTAPI rtVariableSet4i | ( | RTvariable | v, |
int | i1, | ||
int | i2, | ||
int | i3, | ||
int | i4 | ||
) |
[in] | v | Specifies the program variable to be modified |
[in] | i1 | Specifies the new integer value of the program variable |
[in] | i2 | Specifies the new integer value of the program variable |
[in] | i3 | Specifies the new integer value of the program variable |
[in] | i4 | Specifies the new integer value of the program variable |
RTresult RTAPI rtVariableSet4iv | ( | RTvariable | v, |
const int * | i | ||
) |
[in] | v | Specifies the program variable to be modified |
[in] | i | Array of integer values to set the variable to |
RTresult RTAPI rtVariableSet4ui | ( | RTvariable | v, |
unsigned int | u1, | ||
unsigned int | u2, | ||
unsigned int | u3, | ||
unsigned int | u4 | ||
) |
[in] | v | Specifies the program variable to be modified |
[in] | u1 | Specifies the new unsigned integer value of the program variable |
[in] | u2 | Specifies the new unsigned integer value of the program variable |
[in] | u3 | Specifies the new unsigned integer value of the program variable |
[in] | u4 | Specifies the new unsigned integer value of the program variable |
RTresult RTAPI rtVariableSet4uiv | ( | RTvariable | v, |
const unsigned int * | u | ||
) |
[in] | v | Specifies the program variable to be modified |
[in] | u | Array of unsigned integer values to set the variable to |
RTresult RTAPI rtVariableSetMatrix2x2fv | ( | RTvariable | v, |
int | transpose, | ||
const float * | m | ||
) |
[in] | v | Specifies the program variable to be modified |
[in] | transpose | Specifies row-major or column-major order |
[in] | m | Array of float values to set the matrix to |
RTresult RTAPI rtVariableSetMatrix2x3fv | ( | RTvariable | v, |
int | transpose, | ||
const float * | m | ||
) |
[in] | v | Specifies the program variable to be modified |
[in] | transpose | Specifies row-major or column-major order |
[in] | m | Array of float values to set the matrix to |
RTresult RTAPI rtVariableSetMatrix2x4fv | ( | RTvariable | v, |
int | transpose, | ||
const float * | m | ||
) |
[in] | v | Specifies the program variable to be modified |
[in] | transpose | Specifies row-major or column-major order |
[in] | m | Array of float values to set the matrix to |
RTresult RTAPI rtVariableSetMatrix3x2fv | ( | RTvariable | v, |
int | transpose, | ||
const float * | m | ||
) |
[in] | v | Specifies the program variable to be modified |
[in] | transpose | Specifies row-major or column-major order |
[in] | m | Array of float values to set the matrix to |
RTresult RTAPI rtVariableSetMatrix3x3fv | ( | RTvariable | v, |
int | transpose, | ||
const float * | m | ||
) |
[in] | v | Specifies the program variable to be modified |
[in] | transpose | Specifies row-major or column-major order |
[in] | m | Array of float values to set the matrix to |
RTresult RTAPI rtVariableSetMatrix3x4fv | ( | RTvariable | v, |
int | transpose, | ||
const float * | m | ||
) |
[in] | v | Specifies the program variable to be modified |
[in] | transpose | Specifies row-major or column-major order |
[in] | m | Array of float values to set the matrix to |
RTresult RTAPI rtVariableSetMatrix4x2fv | ( | RTvariable | v, |
int | transpose, | ||
const float * | m | ||
) |
[in] | v | Specifies the program variable to be modified |
[in] | transpose | Specifies row-major or column-major order |
[in] | m | Array of float values to set the matrix to |
RTresult RTAPI rtVariableSetMatrix4x3fv | ( | RTvariable | v, |
int | transpose, | ||
const float * | m | ||
) |
[in] | v | Specifies the program variable to be modified |
[in] | transpose | Specifies row-major or column-major order |
[in] | m | Array of float values to set the matrix to |
RTresult RTAPI rtVariableSetMatrix4x4fv | ( | RTvariable | v, |
int | transpose, | ||
const float * | m | ||
) |
[in] | v | Specifies the program variable to be modified |
[in] | transpose | Specifies row-major or column-major order |
[in] | m | Array of float values to set the matrix to |
RTresult RTAPI rtVariableSetObject | ( | RTvariable | v, |
RTobject | object | ||
) |
Sets a program variable value to a OptiX object.
Description
rtVariableSetObject sets a program variable to an OptiX object value. The target variable is specified by v. The new value of the program variable is specified by object. The concrete type of object can be one of RTbuffer, RTtexturesampler, RTgroup, RTprogram, RTselector, RTgeometrygroup, or RTtransform. If v is not a valid variable or object is not a valid OptiX object, this call has no effect and returns RT_ERROR_INVALID_VALUE.
[in] | v | Specifies the program variable to be set |
[in] | object | Specifies the new value of the program variable |
Return values
Relevant return values:
History
rtVariableSetObject was introduced in OptiX 1.0. The ability to bind an RTprogram to a variable was intrduced in OptiX 3.0.
See also rtVariableGetObject, rtContextDeclareVariable
RTresult RTAPI rtVariableSetUserData | ( | RTvariable | v, |
RTsize | size, | ||
const void * | ptr | ||
) |
Defined.
Description
rtVariableSetUserData modifies the value of a program variable whose data type is user-defined. The value copied into the variable is defined by an arbitrary region of memory, pointed to by ptr. The size of the memory region is given by size. The target variable is specified by v. If v is not a valid variable, this call has no effect and returns RT_ERROR_INVALID_VALUE.
[in] | v | Specifies the program variable to be modified |
[in] | size | Specifies the size of the new value, in bytes |
[in] | ptr | Specifies a pointer to the new value of the program variable |
Return values
Relevant return values:
History
rtVariableSetUserData was introduced in OptiX 1.0.