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

Detailed Description

OptiX public API declarations D3D11 interop.

Author
NVIDIA Corporation OptiX public API declarations for D3D11 interoperability

Go to the source code of this file.

Typedefs

typedef struct IDXGIAdapter IDXGIAdapter
 
typedef struct ID3D11Device ID3D11Device
 
typedef struct ID3D11Resource ID3D11Resource
 

Functions

RTresult RTAPI rtContextSetD3D11Device (RTcontext context, ID3D11Device *device)
 
RTresult RTAPI rtDeviceGetD3D11Device (int *device, IDXGIAdapter *pAdapter)
 
RTresult RTAPI rtBufferCreateFromD3D11Resource (RTcontext context, unsigned int bufferdesc, ID3D11Resource *resource, RTbuffer *buffer)
 
RTresult RTAPI rtTextureSamplerCreateFromD3D11Resource (RTcontext context, ID3D11Resource *resource, RTtexturesampler *textureSampler)
 
RTresult RTAPI rtBufferGetD3D11Resource (RTbuffer buffer, ID3D11Resource **resource)
 
RTresult RTAPI rtTextureSamplerGetD3D11Resource (RTtexturesampler textureSampler, ID3D11Resource **resource)
 
RTresult RTAPI rtBufferD3D11Register (RTbuffer buffer)
 
RTresult RTAPI rtBufferD3D11Unregister (RTbuffer buffer)
 
RTresult RTAPI rtTextureSamplerD3D11Register (RTtexturesampler textureSampler)
 
RTresult RTAPI rtTextureSamplerD3D11Unregister (RTtexturesampler textureSampler)
 

Function Documentation

RTresult RTAPI rtBufferCreateFromD3D11Resource ( RTcontext  context,
unsigned int  bufferdesc,
ID3D11Resource *  resource,
RTbuffer buffer 
)

Creates a new buffer object from a D3D11 resource.

Description

rtBufferCreateFromD3D11Resource allocates and returns a handle to a new buffer object in *buffer associated with context. If the allocated size of the D3D resource is 0, RT_ERROR_MEMORY_ALLOCATION_FAILED will be returned. Supported D3D11 buffer types are:

  • ID3D11Buffer

These buffers can be used to share data with D3D11; changes of the content in buffer, either done by D3D11 or OptiX, will be reflected automatically in both APIs. If the size, or format, of a D3D11 buffer is changed, appropriate OptiX calls have to be used to update buffer accordingly. OptiX keeps only a reference to D3D11 data, when buffer is destroyed, the state of resource is unaltered.

The type of this buffer is specified by one of the following values in bufferdesc:

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.

Flags can be used to optimize data transfers between the host and it's devices. Currently no flags are supported for interop buffers.

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

Return values

Relevant return values:

History

rtBufferCreateFromD3D11Resource was introduced in OptiX 2.0.

See also rtBufferCreate, rtBufferDestroy

RTresult RTAPI rtBufferD3D11Register ( RTbuffer  buffer)

Declares a D3D11 buffer as immutable and accessible by OptiX.

Description

An OptiX buffer in an unregistered state can be registered to OptiX again via rtBufferD3D11Register. Once registered, properties like the size of the original D3D11 resource cannot be modified anymore. Calls to the corresponding D3D11 functions will return with an error code. However, the data of the D3D11 resource can still be read and written by the appropriate D3D11 commands. When a buffer is already in a registered state rtBufferD3D11Register will return RT_ERROR_RESOURCE_ALREADY_REGISTERED. A resource must be registered in order to be used by OptiX. If a resource is not registered RT_ERROR_INVALID_VALUE will be returned.

Parameters
[in]bufferThe handle for the buffer object

Return values

Relevant return values:

History

rtBufferD3D11Register was introduced in OptiX 2.0.

See also rtBufferCreateFromD3D11Resource

RTresult RTAPI rtBufferD3D11Unregister ( RTbuffer  buffer)

Declares a D3D11 buffer as mutable and inaccessible by OptiX.

Description

An OptiX buffer in a registered state can be unregistered via rtBufferD3D11Register. Once unregistered, properties like the size of the original D3D11 resource can be changed. As long as a resource is unregistered, OptiX will not be able to access the data and will fail with RT_ERROR_INVALID_VALUE. When a buffer is already in an unregistered state rtBufferD3D11Unregister will return RT_ERROR_RESOURCE_NOT_REGISTERED.

Parameters
[in]bufferThe handle for the buffer object

Return values

Relevant return values:

History

rtBufferD3D11Unregister was introduced in OptiX 2.0.

See also rtBufferCreateFromD3D11Resource

RTresult RTAPI rtBufferGetD3D11Resource ( RTbuffer  buffer,
ID3D11Resource **  resource 
)

Gets the D3D11 resource associated with this buffer.

Description

rtBufferGetD3D11Resource stores the D3D11 resource pointer in **resource if buffer was created with rtBufferCreateFromD3D11Resource. If buffer was not created from a D3D11 resource **resource will be 0 after the call and RT_ERROR_INVALID_VALUE is returned.

Parameters
[in]bufferThe buffer to be queried for its D3D11 resource
[out]resourceThe return handle for the resource

Return values

Relevant return values:

History

rtBufferGetD3D11Resource was introduced in OptiX 2.0.

See also rtBufferCreateFromD3D11Resource

RTresult RTAPI rtContextSetD3D11Device ( RTcontext  context,
ID3D11Device *  device 
)

Binds a D3D11 device to a context and enables interop.

Description

rtContextSetD3D11Device binds device to context and enables D3D11 interop capabilities in context. This function must be executed once for context before any call to rtBufferCreateFromD3D11Resource or rtTextureSamplerCreateFromD3D11Resource can take place. A context can only be bound to one device. Once device is bound to context, the binding is immutable and remains upon destruction of context.

Parameters
[in]contextThe context to bind the device with
[in]deviceThe D3D11 device to be used for interop with the associated context

Return values

Relevant return values:

History

rtContextSetD3D11Device was introduced in OptiX 2.0.

See also rtBufferCreateFromD3D11Resource, rtTextureSamplerCreateFromD3D11Resource

RTresult RTAPI rtDeviceGetD3D11Device ( int *  device,
IDXGIAdapter *  pAdapter 
)

Returns the OptiX device number associated with the pointer to a D3D11 adapter.

Description

rtDeviceGetD3D11Device returns in device the OptiX device ID of the adapter represented by D3D11Device. D3D11Device is a pointer returned from D3D11CreateDeviceAndSwapChain. In combination with rtContextSetDevices, this function can be used to restrict OptiX to use only one device. The same device the D3D11 commands will be sent to.

This function is only supported on Windows platforms.

Parameters
[in]deviceA handle to the memory location where the OptiX device ordinal associated with D3D11Device will be stored
[in]pAdapterA pointer to an ID3D11Device as returned from D3D11CreateDeviceAndSwapChain

Return values

Relevant return values:

History

rtDeviceGetD3D11Device was introduced in OptiX 2.5.

See also rtDeviceGetDeviceCount

RTresult RTAPI rtTextureSamplerCreateFromD3D11Resource ( RTcontext  context,
ID3D11Resource *  resource,
RTtexturesampler textureSampler 
)

Creates a new texture sampler object from a D3D11 resource.

Description

rtTextureSamplerCreateFromD3D11Resource allocates and returns a handle to a new texture sampler object in *texturesampler associated with context. If the allocated size of the D3D resource is 0, RT_ERROR_MEMORY_ALLOCATION_FAILED will be returned. Supported D3D11 texture types are:

  • ID3D11Texture1D
  • ID3D11Texture2D
  • ID3D11Texture3D

These texture samplers can be used to share data with D3D11; changes of the content and size of texturesampler done by D3D11 will be reflected automatically in OptiX. Currently texture sampler data are read only in OptiX programs. OptiX keeps only a reference to D3D11 data, when texturesampler is destroyed, the state of the resource is unaltered.

The array size and number of mipmap levels can't be changed for texture samplers that encapsulate a D3D11 resource. Furthermore no buffer objects can be queried. Please refer to the InteropTypes for a complete list of supported texture formats.

Parameters
[in]contextThe context to create the texture sampler in
[in]resourceThe D3D11 resource handle for use in OptiX
[out]textureSamplerThe return handle for the texture sampler object

Return values

Relevant return values:

History

rtTextureSamplerCreateFromD3D11Resource was introduced in OptiX 2.0.

See also rtTextureSamplerCreate, rtTextureSamplerDestroy

RTresult RTAPI rtTextureSamplerD3D11Register ( RTtexturesampler  textureSampler)

Declares a D3D11 texture as immutable and accessible by OptiX.

Description

An OptiX texture sampler in an unregistered state can be registered to OptiX again via rtTextureSamplerD3D11Register. Once registered, properties like the size of the original D3D11 resource cannot be modified anymore. Calls to the corresponding D3D11 functions will return with an error code. However, the data of the D3D11 resource can still be read and written by the appropriate D3D11 commands. When a texture sampler is already in a registered state rtTextureSamplerD3D11Register will return RT_ERROR_RESOURCE_ALREADY_REGISTERED. A resource must be registered in order to be used by OptiX. If a resource is not registered RT_ERROR_INVALID_VALUE will be returned.

Parameters
[in]textureSamplerThe handle for the texture object

Return values

Relevant return values:

History

rtTextureSamplerD3D11Register was introduced in OptiX 2.0.

See also rtTextureSamplerCreateFromD3D11Resource

RTresult RTAPI rtTextureSamplerD3D11Unregister ( RTtexturesampler  textureSampler)

Declares a D3D11 texture as mutable and inaccessible by OptiX.

Description

An OptiX texture sampler in a registered state can be unregistered via rtTextureSamplerD3D11Unregister. Once unregistered, properties like the size of the original D3D11 resource can be changed. As long as a resource is unregistered, OptiX will not be able to access the data and will fail with RT_ERROR_INVALID_VALUE. When a buffer is already in an unregistered state rtBufferD3D11Unregister will return RT_ERROR_RESOURCE_NOT_REGISTERED.

Parameters
[in]textureSamplerThe handle for the texture object

Return values

Relevant return values:

History

rtTextureSamplerD3D11Unregister was introduced in OptiX 2.0.

See also rtTextureSamplerCreateFromD3D11Resource

RTresult RTAPI rtTextureSamplerGetD3D11Resource ( RTtexturesampler  textureSampler,
ID3D11Resource **  resource 
)

Gets the D3D11 resource associated with this texture sampler.

Description

rtTextureSamplerGetD3D11Resource stores the D3D11 resource pointer in **resource if sampler was created with rtTextureSamplerGetD3D11Resource. If sampler was not created from a D3D11 resource resource will be 0 after the call and RT_ERROR_INVALID_VALUE is returned

Parameters
[in]textureSamplerThe texture sampler to be queried for its D3D11 resource
[out]resourceThe return handle for the resource

Return values

Relevant return values:

History

rtTextureSamplerGetD3D11Resource was introduced in OptiX 2.0.

See also rtBufferCreateFromD3D11Resource