Detailed Description

OptiX public API declarations D3D9 interop.

Author: NVIDIA Corporation OptiX public API declarations for D3D9 interoperability

Typedefs
typedef struct IDirect3DDevice9	IDirect3DDevice9

typedef struct IDirect3DResource9	IDirect3DResource9

Functions
RTresult RTAPI	rtContextSetD3D9Device (RTcontext context, IDirect3DDevice9 *device)

RTresult RTAPI	rtDeviceGetD3D9Device (int device, const char pszAdapterName)

RTresult RTAPI	rtBufferCreateFromD3D9Resource (RTcontext context, unsigned int bufferdesc, IDirect3DResource9 resource, RTbuffer buffer)

RTresult RTAPI	rtTextureSamplerCreateFromD3D9Resource (RTcontext context, IDirect3DResource9 resource, RTtexturesampler textureSampler)

RTresult RTAPI	rtBufferGetD3D9Resource (RTbuffer buffer, IDirect3DResource9 **resource)

RTresult RTAPI	rtTextureSamplerGetD3D9Resource (RTtexturesampler textureSampler, IDirect3DResource9 **pResource)

RTresult RTAPI	rtBufferD3D9Register (RTbuffer buffer)

RTresult RTAPI	rtBufferD3D9Unregister (RTbuffer buffer)

RTresult RTAPI	rtTextureSamplerD3D9Register (RTtexturesampler textureSampler)

RTresult RTAPI	rtTextureSamplerD3D9Unregister (RTtexturesampler textureSampler)

Typedef Documentation

typedef struct IDirect3DDevice9 IDirect3DDevice9

IDirect3DDevice9 structure

typedef struct IDirect3DResource9 IDirect3DResource9

IDirect3DResource9 structure

Function Documentation

RTresult RTAPI rtBufferCreateFromD3D9Resource	(	RTcontext	context,
		unsigned int	bufferdesc,
		IDirect3DResource9 *	resource,
		RTbuffer *	buffer
	)

Creates a new buffer object from a D3D9 resource.

Description

rtBufferCreateFromD3D9Resource 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 D3D9 buffer types are:

IDirect3DVertexBuffer9
IDirect3DIndexBuffer9

These buffers can be used to share data with D3D9; changes of the content in buffer, either done by D3D9 or OptiX, will be reflected automatically in both APIs. If the size, or format, of a D3D9 buffer is changed, appropriate OptiX calls have to be used to update buffer accordingly. OptiX keeps only a reference to D3D9 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]	context	The context to create the buffer in
[in]	bufferdesc	Bitwise or combination of the type and flags of the new buffer
[in]	resource	The D3D9 resource handle for use in OptiX
[out]	buffer	The return handle for the buffer object

Return values

Relevant return values:

History

rtBufferCreateFromD3D9Resource was introduced in OptiX 2.0.

See also rtBufferCreate, rtBufferDestroy

RTresult RTAPI rtBufferD3D9Register ( RTbuffer buffer )

Declares a D3D9 buffer as immutable and accessible by OptiX.

Description

An OptiX buffer in an unregistered state can be registered to OptiX again via rtBufferD3D9Register. Once registered, properties like the size of the original D3D9 resource cannot be modified anymore. Calls to the corresponding D3D9 functions will return with an error code. However, the data of the D3D9 resource can still be read and written by the appropriate D3D9 commands. When a buffer is already in a registered state rtBufferD3D9Register 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] buffer The handle for the buffer object

Return values

Relevant return values:

History

rtBufferD3D9Register was introduced in OptiX 2.0.

RTresult RTAPI rtBufferD3D9Unregister ( RTbuffer buffer )

Declares a D3D9 buffer as mutable and inaccessible by OptiX.

Description

An OptiX buffer in a registered state can be unregistered via rtBufferD3D9Register. Once unregistered, properties like the size of the original D3D9 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 rtBufferD3D9Unregister will return RT_ERROR_RESOURCE_NOT_REGISTERED.

Parameters

[in] buffer The handle for the buffer object

Return values

Relevant return values:

History

rtBufferD3D9Unregister was introduced in OptiX 2.0.

RTresult RTAPI rtBufferGetD3D9Resource	(	RTbuffer	buffer,
		IDirect3DResource9 **	resource
	)

Gets the D3D9 resource associated with this buffer.

Description

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

Parameters

[in]	buffer	The buffer to be queried for its D3D9 resource
[out]	resource	The return handle for the resource

Return values

Relevant return values:

History

rtBufferGetD3D9Resource was introduced in OptiX 2.0.

See also rtBufferCreateFromD3D9Resource

RTresult RTAPI rtContextSetD3D9Device	(	RTcontext	context,
		IDirect3DDevice9 *	device
	)

Binds a D3D9 device to a context and enables interop.

Description

rtContextSetD3D9Device binds device to context and enables D3D9 interop capabilities in context. This function must be executed once for context before any call to rtBufferCreateFromD3D9Resource or rtTextureSamplerCreateFromD3D9Resource 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]	context	The context to bind the device with
[in]	device	The D3D9 device to be used for interop with the associated context

Return values

Relevant return values:

History

rtContextSetD3D9Device was introduced in OptiX 2.0.

RTresult RTAPI rtDeviceGetD3D9Device	(	int *	device,
		const char *	pszAdapterName
	)

Returns the OptiX device number associated with the specified name of a D3D9 adapter.

Description

rtDeviceGetD3D9Device returns in device the OptiX device ID of the adapter represented by pszAdapterName. pszAdapterName is the DeviceName field in the D3DADAPTER_IDENTIFIER9 struct. In combination with rtContextSetDevices, this function can be used to restrict OptiX to use only one device. The same device the D3D9 commands will be sent to.

This function is only supported on Windows platforms.

Parameters

[in]	device	A handle to the memory location where the OptiX device ordinal associated with pszAdapterName will be stored
[out]	pszAdapterName	The name of an adapter as can be found in the DeviceName field in the D3DADAPTER_IDENTIFIER9 struct

Return values

Relevant return values:

History

rtDeviceGetD3D9Device was introduced in OptiX 2.5.

See also rtDeviceGetDeviceCount

RTresult RTAPI rtTextureSamplerCreateFromD3D9Resource	(	RTcontext	context,
		IDirect3DResource9 *	resource,
		RTtexturesampler *	textureSampler
	)

Creates a new texture sampler object from a D3D9 resource.

Description

rtTextureSamplerCreateFromD3D9Resource 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 D3D9 texture types are:

IDirect3DSurface9
(derivatives of) IDirect3DBaseTexture9

These texture samplers can be used to share data with D3D9; changes of the content and size of texturesampler done by D3D9 will be reflected automatically in OptiX. Currently texture sampler data are read only in OptiX programs. OptiX keeps only a reference to D3D9 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 D3D9 resource. Furthermore no buffer objects can be queried. Please refer to the InteropTypes for a complete list of supported texture formats.

Parameters

[in]	context	The context to create the texture sampler in
[in]	resource	The D3D9 resource handle for use in OptiX
[out]	textureSampler	The return handle for the texture sampler object

Return values

Relevant return values:

History

rtTextureSamplerCreateFromD3D9Resource was introduced in OptiX 2.0.

RTresult RTAPI rtTextureSamplerD3D9Register ( RTtexturesampler textureSampler )

Declares a D3D9 texture as immutable and accessible by OptiX.

Description

An OptiX texture sampler in an unregistered state can be registered to OptiX again via rtTextureSamplerD3D9Register. Once registered, properties like the size of the original D3D9 resource cannot be modified anymore. Calls to the corresponding D3D9 functions will return with an error code. However, the data of the D3D9 resource can still be read and written by the appropriate D3D9 commands. When a texture sampler is already in a registered state rtTextureSamplerD3D9Register 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] textureSampler The handle for the texture object

Return values

Relevant return values:

History

rtTextureSamplerD3D9Register was introduced in OptiX 2.0.

RTresult RTAPI rtTextureSamplerD3D9Unregister ( RTtexturesampler textureSampler )

Declares a D3D9 texture as mutable and inaccessible by OptiX.

Description

An OptiX texture sampler in a registered state can be unregistered via rtTextureSamplerD3D9Unregister. Once unregistered, properties like the size of the original D3D9 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 rtBufferD3D9Unregister will return RT_ERROR_RESOURCE_NOT_REGISTERED.

Parameters

[in] textureSampler The handle for the texture object

Return values

Relevant return values:

History

rtTextureSamplerD3D9Unregister was introduced in OptiX 2.0.

RTresult RTAPI rtTextureSamplerGetD3D9Resource	(	RTtexturesampler	textureSampler,
		IDirect3DResource9 **	pResource
	)

Gets the D3D9 resource associated with this texture sampler.

Description

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

Parameters

[in]	textureSampler	The texture sampler to be queried for its D3D9 resource
[out]	pResource	The return handle for the resource

Return values

Relevant return values:

History

rtTextureSamplerGetD3D9Resource was introduced in OptiX 2.0.

See also rtBufferCreateFromD3D9Resource

Detailed Description

Typedefs

Functions

Typedef Documentation

Function Documentation