optix_gl_interop.h File Reference

Detailed Description

OptiX public API declarations GLInterop.

Author

NVIDIA Corporation OptiX public API declarations for GL interoperability

Go to the source code of this file.

Typedefs
typedef void *	HGPUNV

Functions
RTresult RTAPI	rtBufferCreateFromGLBO (RTcontext context, unsigned int bufferdesc, unsigned int glId, RTbuffer *buffer)
RTresult RTAPI	rtTextureSamplerCreateFromGLImage (RTcontext context, unsigned int glId, RTgltarget target, RTtexturesampler *textureSampler)
RTresult RTAPI	rtBufferGetGLBOId (RTbuffer buffer, unsigned int *glId)
RTresult RTAPI	rtTextureSamplerGetGLImageId (RTtexturesampler textureSampler, unsigned int *glId)
RTresult RTAPI	rtBufferGLRegister (RTbuffer buffer)
RTresult RTAPI	rtBufferGLUnregister (RTbuffer buffer)
RTresult RTAPI	rtTextureSamplerGLRegister (RTtexturesampler textureSampler)
RTresult RTAPI	rtTextureSamplerGLUnregister (RTtexturesampler textureSampler)
RTresult RTAPI	rtDeviceGetWGLDevice (int *device, HGPUNV gpu)

Function Documentation

RTresult RTAPI rtBufferCreateFromGLBO	(	RTcontext	context,
		unsigned int	bufferdesc,
		unsigned int	glId,
		RTbuffer *	buffer
	)

Creates a new buffer object from an OpenGL buffer object.

Description

rtBufferCreateFromGLBO allocates and returns a handle to a new buffer object in *buffer associated with context. Supported OpenGL buffer types are:

• Pixel Buffer Objects
• Vertex Buffer Objects

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

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

• RT_BUFFER_INPUT
• RT_BUFFER_OUTPUT
• RT_BUFFER_INPUT_OUTPUT

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]	glId	The OpenGL image object resource handle for use in OptiX
[out]	buffer	The return handle for the buffer object

Return values

Relevant return values:

• RT_SUCCESS
• RT_ERROR_INVALID_CONTEXT
• RT_ERROR_INVALID_VALUE
• RT_ERROR_MEMORY_ALLOCATION_FAILED

History

rtBufferCreateFromGLBO was introduced in OptiX 1.0.

See also rtBufferCreate, rtBufferDestroy

RTresult RTAPI rtBufferGetGLBOId	(	RTbuffer	buffer,
		unsigned int *	glId
	)

Gets the OpenGL Buffer Object ID associated with this buffer.

Description

rtBufferGetGLBOId stores the OpenGL buffer object id in *gl_id if buffer was created with rtBufferCreateFromGLBO. If buffer was not created from an OpenGL Buffer Object *gl_id will be 0 after the call and RT_ERROR_INVALID_VALUE is returned.

Parameters

[in]	buffer	The buffer to be queried for its OpenGL buffer object id
[in]	glId	The return handle for the id

Return values

Relevant return values:

• RT_SUCCESS
• RT_ERROR_INVALID_CONTEXT
• RT_ERROR_INVALID_VALUE
• RT_ERROR_MEMORY_ALLOCATION_FAILED

History

rtBufferGetGLBOId was introduced in OptiX 1.0.

See also rtBufferCreateFromGLBO

RTresult RTAPI rtBufferGLRegister

(

RTbuffer

buffer

)

Declares an OpenGL buffer as immutable and accessible by OptiX.

Description

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

Parameters

[in]

buffer

The handle for the buffer object

Return values

Relevant return values:

• RT_SUCCESS
• RT_ERROR_INVALID_CONTEXT
• RT_ERROR_INVALID_VALUE
• RT_ERROR_RESOURCE_ALREADY_REGISTERED

History

rtBufferGLRegister was introduced in OptiX 2.0.

See also rtBufferCreateFromGLBO, rtBufferGLUnregister

RTresult RTAPI rtBufferGLUnregister

(

RTbuffer

buffer

)

Declares an OpenGL buffer as mutable and inaccessible by OptiX.

Description

Once unregistered, properties like the size of the original GL buffer can be changed. As long as a buffer object is unregistered, OptiX will not be able to access the data and calls will fail with RT_ERROR_INVALID_VALUE. Returns RT_ERROR_RESOURCE_NOT_REGISTERED if buffer is already unregistered. An OptiX buffer in an unregistered state can be registered to OptiX again via rtBufferGLRegister.

Parameters

[in]

buffer

The handle for the buffer object

Return values

Relevant return values:

• RT_SUCCESS
• RT_ERROR_INVALID_CONTEXT
• RT_ERROR_INVALID_VALUE
• RT_ERROR_RESOURCE_NOT_REGISTERED

History

rtBufferGLUnregister was introduced in OptiX 2.0.

See also rtBufferCreateFromGLBO, rtBufferGLRegister

RTresult RTAPI rtDeviceGetWGLDevice	(	int *	device,
		HGPUNV	gpu
	)

returns the OptiX device number associated with the specified GPU

Description

rtDeviceGetWGLDevice returns in device the OptiX device ID of the GPU represented by gpu. gpu is returned from WGL_NV_gpu_affinity, an OpenGL extension. This enables OptiX to create a context on the same GPU that OpenGL commands will be sent to, improving OpenGL interoperation efficiency.

Parameters

[out]	device	A handle to the memory location where the OptiX device ordinal associated with gpu will be stored
[in]	gpu	A handle to a GPU as returned from the WGL_NV_gpu_affinity OpenGL extension

Return values

Relevant return values:

• RT_SUCCESS
• RT_ERROR_INVALID_VALUE

History

rtDeviceGetWGLDevice was introduced in OptiX 1.0.

See also rtDeviceGetDeviceCount, WGL_NV_gpu_affinity

RTresult RTAPI rtTextureSamplerCreateFromGLImage	(	RTcontext	context,
		unsigned int	glId,
		RTgltarget	target,
		RTtexturesampler *	textureSampler
	)

Creates a new texture sampler object from an OpenGL image.

Description

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

Renderbuffers

• GL_TEXTURE_2D
• GL_TEXTURE_2D_RECT
• GL_TEXTURE_3D

These types are reflected by target:

• RT_TARGET_GL_RENDER_BUFFER
• RT_TARGET_GL_TEXTURE_1D
• RT_TARGET_GL_TEXTURE_2D
• RT_TARGET_GL_TEXTURE_RECTANGLE
• RT_TARGET_GL_TEXTURE_3D
• RT_TARGET_GL_TEXTURE_1D_ARRAY
• RT_TARGET_GL_TEXTURE_2D_ARRAY
• RT_TARGET_GL_TEXTURE_CUBE_MAP
• RT_TARGET_GL_TEXTURE_CUBE_MAP_ARRAY

Supported attachment points for renderbuffers are:

• GL_COLOR_ATTACHMENT<NUM>

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

The array size and number of mipmap levels can't be changed for texture samplers that encapsulate a GL image. Furthermore no buffer objects can be queried.

Currently OptiX supports only a limited number of internal OpenGL texture formats. Texture formats with an internal type of float, e.g. GL_RGBA32F, and many integer formats are supported. Depth formats as well as multisample buffers are also currently not supported. Please refer to the InteropTypes section for a complete list of supported texture formats.

Parameters

[in]	context	The context to create the buffer in
[in]	glId	The OpenGL image object resoure handle for use in OptiX
[in]	target	The OpenGL target
[out]	textureSampler	The return handle for the texture sampler object

Return values

Relevant return values:

• RT_SUCCESS
• RT_ERROR_INVALID_CONTEXT
• RT_ERROR_INVALID_VALUE
• RT_ERROR_MEMORY_ALLOCATION_FAILED

History

rtTextureSamplerCreateFromGLImage was introduced in OptiX 2.0.

See also rtTextureSamplerCreate, rtTextureSamplerDestroy

RTresult RTAPI rtTextureSamplerGetGLImageId	(	RTtexturesampler	textureSampler,
		unsigned int *	glId
	)

Gets the OpenGL image object id associated with this texture sampler.

Description

rtTextureSamplerGetGLImageId stores the OpenGL image object id in *gl_id if textureSampler was created with rtTextureSamplerCreateFromGLImage. If textureSampler was not created from an OpenGL image object gl_id will be 0 after the call and RT_ERROR_INVALID_VALUE is returned.

Parameters

[in]	textureSampler	The texture sampler to be queried for its OpenGL buffer object id
[in]	glId	The return handle for the id

Return values

Relevant return values:

• RT_SUCCESS
• RT_ERROR_INVALID_CONTEXT
• RT_ERROR_INVALID_VALUE
• RT_ERROR_MEMORY_ALLOCATION_FAILED

History

rtTextureSamplerGetGLImageId was introduced in OptiX 2.0.

See also rtTextureSamplerCreateFromGLImage

RTresult RTAPI rtTextureSamplerGLRegister

(

RTtexturesampler

textureSampler

)

Declares an OpenGL texture as immutable and accessible by OptiX.

Description

Registers an OpenGL texture as accessible by OptiX. Once registered, properties like the size of the original GL texture cannot be modified anymore. Calls to the corresponding GL functions will return with an error code. However, the pixel data of the GL texture can still be read and written by the appropriate GL commands. Returns RT_ERROR_RESOURCE_ALREADY_REGISTERED if textureSampler is already registered. A texture sampler must be registered in order to be used by OptiX. Otherwise, RT_ERROR_INVALID_VALUE is returned. An OptiX texture sampler in a registered state can be unregistered via rtTextureSamplerGLUnregister.

Parameters

[in]

textureSampler

The handle for the texture object

Return values

Relevant return values:

• RT_SUCCESS
• RT_ERROR_INVALID_CONTEXT
• RT_ERROR_INVALID_VALUE
• RT_ERROR_RESOURCE_ALREADY_REGISTERED

History

rtTextureSamplerGLRegister was introduced in OptiX 2.0.

See also rtTextureSamplerCreateFromGLImage, rtTextureSamplerGLUnregister

RTresult RTAPI rtTextureSamplerGLUnregister

(

RTtexturesampler

textureSampler

)

Declares an OpenGL texture as mutable and inaccessible by OptiX.

Description

Once unregistered, properties like the size of the original GL texture can be changed. As long as a texture is unregistered, OptiX will not be able to access the pixel data and calls will fail with RT_ERROR_INVALID_VALUE. Returns RT_ERROR_RESOURCE_NOT_REGISTERED if textureSampler is already unregistered. An OptiX texture sampler in an unregistered state can be registered to OptiX again via rtTextureSamplerGLRegister.

Parameters

[in]

textureSampler

The handle for the texture object

Return values

Relevant return values:

• RT_SUCCESS
• RT_ERROR_INVALID_CONTEXT
• RT_ERROR_INVALID_VALUE
• RT_ERROR_RESOURCE_NOT_REGISTERED

History

rtTextureSamplerGLUnregister was introduced in OptiX 2.0.

See also rtTextureSamplerCreateFromGLImage, rtTextureSamplerGLRegister