OptiX  3.9
NVIDIA OptiX Acceleration Engine
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
Typedefs | Functions
optix_cuda_interop.h File Reference

Detailed Description

OptiX public API declarations CUDAInterop.

Author
NVIDIA Corporation OptiX public API declarations for CUDA interoperability

Go to the source code of this file.

Typedefs

typedef unsigned int CUdeviceptr
 

Functions

RTresult RTAPI rtBufferCreateForCUDA (RTcontext context, unsigned int bufferdesc, RTbuffer *buffer)
 
RTresult RTAPI rtBufferGetDevicePointer (RTbuffer buffer, unsigned int optix_device_number, void **device_pointer)
 
RTresult RTAPI rtBufferMarkDirty (RTbuffer buffer)
 
RTresult RTAPI rtBufferSetDevicePointer (RTbuffer buffer, unsigned int optix_device_number, CUdeviceptr device_pointer)
 

Function Documentation

RTresult RTAPI rtBufferCreateForCUDA ( RTcontext  context,
unsigned int  bufferdesc,
RTbuffer buffer 
)

Creates a new buffer object that will later rely on user-side CUDA allocation.

Description

rtBufferCreateForCUDA allocates and returns a new handle to a new buffer object in *buffer associated with context. This buffer will function like a normal OptiX buffer created with rtBufferCreate, except OptiX will not allocate or upload data for it.

After a buffer object has been created with rtBufferCreateForCUDA, the user needs to call rtBufferSetDevicePointer to provide one or more device pointers to the buffer data. When the user provides a single device's data pointer for a buffer prior to calling rtContextLaunch, OptiX will allocate memory on the other devices and copy the data there. Setting pointers for more than one but fewer than all devices is not supported.

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. OptiX must then synchronize the new buffer contents 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.

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.

The supported flags are:

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 be never visible on the host side.

Parameters
[in]contextThe context to create the buffer in
[in]bufferdescBitwise or combination of the type and flags of the new buffer
[out]bufferThe return handle for the buffer object

Return values

Relevant return values:

History

rtBufferCreateForCUDA was introduced in OptiX 3.0.

See also rtBufferCreate, rtBufferSetDevicePointer, rtBufferMarkDirty, rtBufferDestroy

RTresult RTAPI rtBufferGetDevicePointer ( RTbuffer  buffer,
unsigned int  optix_device_number,
void **  device_pointer 
)

Gets the pointer to the buffer's data on the given device.

Description

rtBufferGetDevicePointer returns the pointer to the data of buffer on device optix_device_number in **device_pointer.

If rtBufferGetDevicePointer has been called for a single device for a given buffer, the user can change the buffer's content on that device. OptiX must then synchronize the new buffer contents 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.

Parameters
[in]bufferThe buffer to be queried for its device pointer
[in]optix_device_numberThe number of OptiX device
[out]device_pointerThe return handle to the buffer's device pointer

Return values

Relevant return values:

History

rtBufferGetDevicePointer was introduced in OptiX 3.0.

See also rtBufferMarkDirty, rtBufferSetDevicePointer

RTresult RTAPI rtBufferMarkDirty ( RTbuffer  buffer)

Sets a buffer as dirty.

Description

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. OptiX must then synchronize the new buffer contents 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.

Note that RT_BUFFER_COPY_ON_DIRTY currently only applies to CUDA Interop buffers (buffers for which the application has a device pointer).

Parameters
[in]bufferThe buffer to be marked dirty

Return values

Relevant return values:

History

rtBufferMarkDirty was introduced in OptiX 3.0.

See also rtBufferGetDevicePointer, rtBufferSetDevicePointer, RT_BUFFER_COPY_ON_DIRTY

RTresult RTAPI rtBufferSetDevicePointer ( RTbuffer  buffer,
unsigned int  optix_device_number,
CUdeviceptr  device_pointer 
)

Sets the pointer to the buffer's data on the given device.

Description

rtBufferSetDevicePointer sets the pointer to the data of buffer on device optix_device_number to device_pointer.

The buffer needs to be allocated with rtBufferCreateForCUDA in order for the call to rtBufferSetDevicePointer to be valid. Likewise, before providing a device pointer for the buffer, the application must first specify the size and format of the buffer.

If rtBufferSetDevicePointer has been called for a single device for a given buffer, the user can change the buffer's content on that device. OptiX must then synchronize the new buffer contents 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.

Parameters
[in]bufferThe buffer for which the device pointer is to be set
[in]optix_device_numberThe number of OptiX device
[in]device_pointerThe pointer to the data on the specified device

Return values

Relevant return values:

History

rtBufferSetDevicePointer was introduced in OptiX 3.0.

See also rtBufferMarkDirty, rtBufferGetDevicePointer