NVIDIA OptiX 6.5 API nvidia_logo_transpbg.gif Up
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
OptiX CUDA C declarations

Macros

#define rtDeclareVariable(type, name, semantic, annotation)
 
#define rtDeclareAnnotation(variable, annotation)
 
#define rtCallableProgram(return_type, function_name, parameter_list)   rtDeclareVariable(optix::boundCallableProgramId<return_type parameter_list>, function_name,,);
 
#define RT_PROGRAM   __global__
 
#define rtCallableProgramId   optix::callableProgramId
 
#define rtMarkedCallableProgramId   optix::markedCallableProgramId
 
#define rtCallableProgramX   optix::boundCallableProgramId
 

Functions

static __device__ float2 rtGetTriangleBarycentrics ()
 
static __device__ unsigned int rtGetGroupChildIndex ()
 

Detailed Description

Functions designed to declare programs and types used by OptiX device code.

Macro Definition Documentation

#define RT_PROGRAM   __global__

Define an OptiX program.

Description

RT_PROGRAM defines a program program_name with the specified arguments and return value. This function can be bound to a specific program object using rtProgramCreateFromPTXString or rtProgramCreateFromPTXFile, which will subsequently get bound to different programmable binding points.

All programs should have a "void" return type. Bounding box programs will have an argument for the primitive index and the bounding box reference return value (type nvrt::AAbb&). Intersection programs will have a single int primitiveIndex argument. All other programs take zero arguments.

History

RT_PROGRAM was introduced in OptiX 1.0.

See also RT_PROGRAM rtProgramCreateFromPTXFile rtProgramCreateFromPTXString

#define rtCallableProgram (   return_type,
  function_name,
  parameter_list 
)    rtDeclareVariable(optix::boundCallableProgramId<return_type parameter_list>, function_name,,);

Callable Program Declaration.

Description

rtCallableProgram declares callable program name, which will appear to be a callable function with the specified return type and list of arguments. This callable program must be matched against a variable declared on the API object using rtVariableSetObject.

Unless compatibility with SM_10 is needed, new code should #define RT_USE_TEMPLATED_RTCALLABLEPROGRAM and rely on the new templated version of rtCallableProgram.

Example(s):

rtCallableProgram(float3, modColor, (float3, float));
// With RT_USE_TEMPLATED_RTCALLABLEPROGRAM defined
rtDeclareVariable(rtCallableProgram<float3(float3, float)>, modColor);
Parameters
[in]return_typeReturn type of the callable program
[in]function_nameName of the callable program
[in]parameter_listParameter_List of the callable program

History

rtCallableProgram was introduced in OptiX 3.0.

See also rtDeclareVariable rtCallableProgramId rtCallableProgramX

#define rtCallableProgramId   optix::callableProgramId

Callable Program ID Declaration.

Description

rtCallableProgramId declares callable program name, which will appear to be a callable function with the specified return type and list of arguments. This callable program must be matched against a variable declared on the API object of type int.

Example(s):

rtDeclareVariable(rtCallableProgramId<float3(float3, float)>, modColor);
rtBuffer<rtCallableProgramId<float3(float3, float)>, 1> modColors;

History

rtCallableProgramId was introduced in OptiX 3.6.

See also rtCallableProgram rtCallableProgramX rtDeclareVariable rtMarkedCallableProgramId

#define rtCallableProgramX   optix::boundCallableProgramId

Callable Program X Declaration.

Description

rtCallableProgramX declares callable program name, which will appear to be a callable function with the specified return type and list of arguments. This callable program must be matched against a variable declared on the API object using rtVariableSetObject.

Unless compatibility with SM_10 is needed, new code should #define RT_USE_TEMPLATED_RTCALLABLEPROGRAM and rely on the new templated version of rtCallableProgram instead of directly using rtCallableProgramX.

Example(s):

rtDeclareVariable(rtCallableProgramX<float3(float3, float)>, modColor);
// With RT_USE_TEMPLATED_RTCALLABLEPROGRAM defined
rtDeclareVariable(rtCallableProgram<float3(float3, float)>, modColor);

History

rtCallableProgramX was introduced in OptiX 3.6.

See also rtCallableProgram rtCallableProgramId rtDeclareVariable

#define rtDeclareAnnotation (   variable,
  annotation 
)
Value:
namespace rti_internal_annotation { \
__device__ char variable[] = #annotation; \
}

Annotation declaration.

Description

rtDeclareAnnotation sets the annotation annotation of the given variable name. Typically annotations are declared using an argument to rtDeclareVariable, but variables of type rtBuffer and rtTextureSampler are declared using templates, so separate annotation attachment is required.

OptiX does not attempt to interpret the annotation in any way. It is considered metadata for the application to query and interpret in its own way.

Valid annotations

The macro rtDeclareAnnotation uses the C pre-processor's "stringification" feature to turn the literal text of the annotation argument into a string constant. The pre-processor will backslash-escape quotes and backslashes within the text of the annotation. Leading and trailing whitespace will be ignored, and sequences of whitespace in the middle of the text is converted to a single space character in the result. The only restriction the C-PP places on the text is that it may not contain a comma character unless it is either quoted or contained within parens: "," or (,).

Example(s):

rtDeclareAnnotation( tex, this is a test );
annotation = "this is a test"
rtDeclareAnnotation( tex, "this is a test" );
annotation = "\"this is a test\""
rtDeclareAnnotation( tex, float3 a = {1, 2, 3} );
--> Compile Error, no unquoted commas may be present in the annotation
rtDeclareAnnotation( tex, "float3 a = {1, 2, 3}" );
annotation = "\"float3 a = {1, 2, 3}\""
rtDeclareAnnotation( tex, string UIWidget = "slider";
float UIMin = 0.0;
float UIMax = 1.0; );
annotation = "string UIWidget = \"slider\"; float UIMin = 0.0; float UIMax = 1.0;"
Parameters
[in]variableVariable to annotate
[in]annotationAnnotation metadata

History

rtDeclareAnnotation was introduced in OptiX 1.0.

See also rtDeclareVariable, rtVariableGetAnnotation

#define rtDeclareVariable (   type,
  name,
  semantic,
  annotation 
)
Value:
namespace rti_internal_typeinfo { \
__device__ ::rti_internal_typeinfo::rti_typeinfo name = { ::rti_internal_typeinfo::_OPTIX_VARIABLE, sizeof(type)}; \
} \
namespace rti_internal_typename { \
__device__ char name[] = #type; \
} \
namespace rti_internal_typeenum { \
} \
namespace rti_internal_semantic { \
__device__ char name[] = #semantic; \
} \
namespace rti_internal_annotation { \
__device__ char name[] = #annotation; \
} \
__device__ type name

Variable declaration.

Description

rtDeclareVariable declares variable name of the specified type. By default, the variable name will be matched against a variable declared on the API object using the lookup hierarchy for the current program. Using the semanticName, this variable can be bound to internal state, to the payload associated with a ray, or to attributes that are communicated between intersection and material programs. An additional optional annotation can be used to associate application-specific metadata with the variable as well.

type may be a primitive type or a user-defined struct (See rtVariableSetUserData). Except for the ray payload and attributes, the declared variable will be read-only. The variable will be visible to all of the cuda functions defined in the current file. The binding of variables to values on API objects is allowed to vary from one instance to another.

Valid semanticNames

  • rtLaunchIndex - The launch invocation index. Type must be one of unsigned int, uint2, uint3, int, int2, int3 and is read-only.
  • rtLaunchDim - The size of each dimension of the launch. The values range from 1 to the launch size in that dimension. Type must be one of unsigned int, uint2, uint3, int, int2, int3 and is read-only.
  • rtCurrentRay - The currently active ray, valid only when a call to rtTrace is active. The vector is not guaranteed to be normalized. Type must be optix::Ray and is read-only.
  • rtCurrentTime - The current ray time. Type must be float and is read-only.
  • rtIntersectionDistance - The current closest hit distance, valid only when a call to rtTrace is active. Type must be float and is read-only.
  • rtRayPayload - The struct passed into the most recent rtTrace call and is read-write.
  • attribute name - A named attribute passed from the intersection program to a closest-hit or any-hit program. The types must match in both sets of programs. This variable is read-only in the closest-hit or any-hit program and is written in the intersection program.
Parameters
[in]typeType of the variable
[in]nameName of the variable
[in]semanticSemantic name
[in]annotationAnnotation for this variable

History

  • rtDeclareVariable was introduced in OptiX 1.0.
  • rtLaunchDim was introduced in OptiX 2.0.

See also rtDeclareAnnotation, rtVariableGetAnnotation, rtContextDeclareVariable, rtProgramDeclareVariable, rtSelectorDeclareVariable, rtGeometryInstanceDeclareVariable, rtGeometryDeclareVariable, rtMaterialDeclareVariable

#define rtMarkedCallableProgramId   optix::markedCallableProgramId

Marked Callable Program ID Declaration.

Description

rtMarkedCallableProgramId declares callable program name, which will appear to be a callable function with the specified return type and list of arguments. Calls to this callable program can be referenced on the host by the given callSiteName in order to specify the set of callable programs that that may be called at a specific call site. This allows to use bindless callable programs that call rtTrace. Callable programs that call rtTrace need a different call semantic than programs that do not. Specifying the callable programs that may potentially be called at a call site allow OptiX to determine the correct call semantics at each call site. Programs that are declared using rtCallableProgramId may only call trace if they are used in an rtVariable or in a rtBuffer of type rtCallableProgramId. The rtMarkedCallableProgramId type is only available on the device and cannot be used in an rtVariable. Objects of type rtCallableProgramId can be transformed into rtMarkedCallableProgramId by using the appropriate constructor.

Example(s):

// Uses named call site marking, potential callees can be set through the host API,
// needed call semantics will determined based on those.
rtMarkedCallableProgramId<float3(float3, float)> modColor(id, "modColorCall");
// callable1 cannot call rtTrace
rtCallableProgramId<void(void)> callable1(id);
// Create marked callable from callable1. Uses named call site marking.
rtMarkedCallableProgramId<void(void)> markedCallable1(callable1, "callSite1");
// Variables of type rtCallableProgramId use automatic detection of the needed call semantics.
rtDeclareVariable(rtCallableProgramId<void(void)>, callable, ,);
callable();
// Buffers of type rtCallableProgramId use automatic detection of the needed call semantics.
rtBuffer<rtCallableProgramId<void(void)>, 1> programBuffer;
programBuffer[0]();
// Overwrite automatic marking with named marking
rtMarkedCallableProgramId<void(void)> marked(programBuffer[0], "callSite2");
// Use information provided through host API to determine call semantics.
marked();

History

rtCallableProgramId was introduced in OptiX 6.0.

See also rtCallableProgram

Function Documentation

static __device__ unsigned int rtGetGroupChildIndex ( )
inlinestatic

Accessor for child index.

Description

rtGetGroupChildIndex returns the current child index (often referred to as instance index) in a 2-level hierarchy. In a multi-level hierarchy, it refers to the traversed child index of the last group (group only, not to be confused with a geometry group) when traversing the hierarchy top to bottom. In other words, the index equals the i'th child of the last group on the path through the scene graph from root to primitive.

History

See also rtGetPrimitiveIndex()

static __device__ float2 rtGetTriangleBarycentrics ( )
inlinestatic

Accessor for barycentrics for built in triangle intersection.

Description

rtGetTriangleBarycentrics returns the barycentric coordinates of the intersected triangle. This function is only accessible in a program attached as an attribute program to an RTgeometrytriangles object. Barycentrics are defined as follows: barycentrics.xy = (w1, w2) with w0 = 1-w1-w2 such that the attribute value 'a' for any point in the triangle is the weighted combination of the attributes at the vertices: a = w0 * a0 + w1 * a1 + w2 * a2 with a0, a1, a2 being the attributes associated with vertices v0, v1, v2 of the triangle.

History

See also rtGeometryTrianglesSetAttributeProgram