This section describes the cl_khr_d3d10_sharing extension. The goal of this extension is to provide interoperability between OpenCL and Direct3D 10.
cl_int clGetDeviceIDsFromD3D10KHR(cl_platform_id platform,
cl_d3d10_device_source_khr d3d_device_source,
void *d3d_object,
cl_d3d10_device_set_khr d3d_device_set,
cl_uint num_entries,
cl_device_id *devices,
cl_uint *num_devices);
cl_mem clCreateFromD3D10BufferKHR(cl_context context,
cl_mem_flags flags,
ID3D10Buffer *resource,
cl_int *errcode_ret);
cl_mem clCreateFromD3D10Texture2DKHR(cl_context context,
cl_mem_flags flags,
ID3D10Texture2D *resource,
UINT subresource,
cl_int *errcode_ret);
cl_mem clCreateFromD3D10Texture3DKHR(cl_context context,
cl_mem_flags flags,
ID3D10Texture3D *resource,
UINT subresource,
cl_int *errcode_ret);
cl_int clEnqueueAcquireD3D10ObjectsKHR(cl_command_queue command_queue,
cl_uint num_objects,
const cl_mem *mem_objects,
cl_uint num_events_in_wait_list,
const cl_event *event_wait_list,
cl_event *event);
cl_int clEnqueueReleaseD3D10ObjectsKHR(cl_command_queue command_queue,
cl_uint num_objects,
const cl_mem *mem_objects,
cl_uint num_events_in_wait_list,
const cl_event *event_wait_list,
cl_event *event);Accepted as a Direct3D 10 device source in the d3d_device_source parameter of {clGetDeviceIDsFromD3D10KHR}:
CL_D3D10_DEVICE_KHR CL_D3D10_DXGI_ADAPTER_KHR
Accepted as a set of Direct3D 10 devices in the d3d_device_set parameter of {clGetDeviceIDsFromD3D10KHR}:
CL_PREFERRED_DEVICES_FOR_D3D10_KHR CL_ALL_DEVICES_FOR_D3D10_KHR
Accepted as a property name in the properties parameter of {clCreateContext} and {clCreateContextFromType}:
CL_CONTEXT_D3D10_DEVICE_KHR
Accepted as a property name in the param_name parameter of {clGetContextInfo}:
CL_CONTEXT_D3D10_PREFER_SHARED_RESOURCES_KHR
Accepted as the property being queried in the param_name parameter of {clGetMemObjectInfo}:
CL_MEM_D3D10_RESOURCE_KHR
Accepted as the property being queried in the param_name parameter of {clGetImageInfo}:
CL_IMAGE_D3D10_SUBRESOURCE_KHR
Returned in the param_value parameter of {clGetEventInfo} when param_name is {CL_EVENT_COMMAND_TYPE}:
CL_COMMAND_ACQUIRE_D3D10_OBJECTS_KHR CL_COMMAND_RELEASE_D3D10_OBJECTS_KHR
Returned by {clCreateContext} and {clCreateContextFromType} if the Direct3D 10 device specified for interoperability is not compatible with the devices against which the context is to be created:
CL_INVALID_D3D10_DEVICE_KHR
Returned by {clCreateFromD3D10BufferKHR} when resource is not a Direct3D 10 buffer object, and by {clCreateFromD3D10Texture2DKHR} and {clCreateFromD3D10Texture3DKHR} when resource is not a Direct3D 10 texture object:
CL_INVALID_D3D10_RESOURCE_KHR
Returned by {clEnqueueAcquireD3D10ObjectsKHR} when any of mem_objects are currently acquired by OpenCL:
CL_D3D10_RESOURCE_ALREADY_ACQUIRED_KHR
Returned by {clEnqueueReleaseD3D10ObjectsKHR} when any of mem_objects are not currently acquired by OpenCL:
CL_D3D10_RESOURCE_NOT_ACQUIRED_KHR
In section 4.4, replace the description of properties under {clCreateContext} with:
"properties specifies a list of context property names and their
corresponding values.
Each property is followed immediately by the corresponding desired value.
The list is terminated with zero.
If a property is not specified in properties, then its default value
(listed in table 4.5) is used (it is said to be specified implicitly).
If properties is NULL or empty (points to a list whose first value is
zero), all attributes take on their default values."
Add the following to table 4.5:
| cl_context_properties enum | Property value | Description |
|---|---|---|
{CL_CONTEXT_D3D10_DEVICE_KHR} |
ID3D10Device * |
Specifies the ID3D10Device * to use for Direct3D 10 interoperability. The default value is |
Add to the list of errors for {clCreateContext}:
-
{CL_INVALID_D3D10_DEVICE_KHR} if the value of the property {CL_CONTEXT_D3D10_DEVICE_KHR} is non-
NULLand does not specify a valid Direct3D 10 device with which the cl_device_ids against which this context is to be created may interoperate. -
{CL_INVALID_OPERATION} if Direct3D 10 interoperability is specified by setting {CL_INVALID_D3D10_DEVICE_KHR} to a non-
NULLvalue, and interoperability with another graphics API is also specified.
Add to the list of errors for {clCreateContextFromType} the same new errors described above for {clCreateContext}.
Add the following row to table 4.6:
| cl_context_info | Return Type | Information returned in param_value |
|---|---|---|
{CL_CONTEXT_D3D10_PREFER_SHARED_RESOURCES_KHR} |
{cl_bool_TYPE} |
Returns {CL_TRUE} if Direct3D 10 resources created as shared by setting MiscFlags to include D3D10_RESOURCE_MISC_SHARED will perform faster when shared with OpenCL, compared with resources which have not set this flag. Otherwise returns {CL_FALSE}. |
Add to the list of errors for {clGetMemObjectInfo}:
-
{CL_INVALID_D3D10_RESOURCE_KHR} if param_name is {CL_MEM_D3D10_RESOURCE_KHR} and memobj was not created by the function {clCreateFromD3D10BufferKHR}, {clCreateFromD3D10Texture2DKHR}, or {clCreateFromD3D10Texture3DKHR}.
Extend table 5.12 to include the following entry.
| cl_mem_info | Return type | Info. returned in param_value |
|---|---|---|
{CL_MEM_D3D10_RESOURCE_KHR} |
ID3D10Resource * |
If memobj was created using {clCreateFromD3D10BufferKHR}, {clCreateFromD3D10Texture2DKHR}, or {clCreateFromD3D10Texture3DKHR}, returns the resource argument specified when memobj was created. |
Add to the list of errors for {clGetImageInfo}:
-
{CL_INVALID_D3D10_RESOURCE_KHR} if param_name is {CL_IMAGE_D3D10_SUBRESOURCE_KHR} and image was not created by the function {clCreateFromD3D10Texture2DKHR}, or {clCreateFromD3D10Texture3DKHR}.
Extend table 5.9 to include the following entry.
| cl_image_info | Return type | Info. returned in param_value |
|---|---|---|
{CL_IMAGE_D3D10_SUBRESOURCE_KHR} |
UINT |
If image was created using {clCreateFromD3D10Texture2DKHR}, or {clCreateFromD3D10Texture3DKHR}, returns the subresource argument specified when image was created. |
Add to table 5.22 in the Info returned in <param_value> column for cl_event_info = {CL_EVENT_COMMAND_TYPE}:
CL_COMMAND_ACQUIRE_D3D10_OBJECTS_KHR CL_COMMAND_RELEASE_D3D10_OBJECTS_KHR
This section discusses OpenCL functions that allow applications to use Direct3D 10 resources as OpenCL memory objects. This allows efficient sharing of data between OpenCL and Direct3D 10. The OpenCL API may be used to execute kernels that read and/or write memory objects that are also Direct3D 10 resources. An OpenCL image object may be created from a Direct3D 10 texture resource. An OpenCL buffer object may be created from a Direct3D 10 buffer resource. OpenCL memory objects may be created from Direct3D 10 objects if and only if the OpenCL context has been created from a Direct3D 10 device.
The OpenCL devices corresponding to a Direct3D 10 device may be queried. The OpenCL devices corresponding to a DXGI adapter may also be queried. The OpenCL devices corresponding to a Direct3D 10 device will be a subset of the OpenCL devices corresponding to the DXGI adapter against which the Direct3D 10 device was created.
The OpenCL devices corresponding to a Direct3D 10 device or a DXGI device may be queried using the function
platform refers to the platform ID returned by {clGetPlatformIDs}.
d3d_device_source specifies the type of d3d_object, and must be one of the values shown in the table below.
d3d_object specifies the object whose corresponding OpenCL devices are being queried. The type of d3d_object must be as specified in the table below.
d3d_device_set specifies the set of devices to return, and must be one of the values shown in the table below.
num_entries is the number of {cl_device_id_TYPE} entries that can be added to
devices.
If devices is not NULL then num_entries must be greater than zero.
devices returns a list of OpenCL devices found.
The {cl_device_id_TYPE} values returned in devices can be used to identify a
specific OpenCL device.
If devices is NULL, this argument is ignored.
The number of OpenCL devices returned is the minimum of the value specified
by num_entries and the number of OpenCL devices corresponding to
d3d_object.
num_devices returns the number of OpenCL devices available that correspond
to d3d_object.
If num_devices is NULL, this argument is ignored.
{clGetDeviceIDsFromD3D10KHR} returns {CL_SUCCESS} if the function is executed successfully. Otherwise it may return
-
{CL_INVALID_PLATFORM} if platform is not a valid platform.
-
{CL_INVALID_VALUE} if d3d_device_source is not a valid value, d3d_device_set is not a valid value, num_entries is equal to zero and devices is not
NULL, or if both num_devices and devices areNULL. -
{CL_DEVICE_NOT_FOUND} if no OpenCL devices that correspond to d3d_object were found.
| {cl_d3d10_device_source_khr_TYPE} | Type of d3d_object |
|---|---|
{CL_D3D10_DEVICE_KHR} |
ID3D10Device * |
{CL_D3D10_DXGI_ADAPTER_KHR} |
IDXGIAdapter * |
| {cl_d3d10_device_set_khr_TYPE} | Devices returned in devices |
|---|---|
{CL_PREFERRED_DEVICES_FOR_D3D10_KHR} |
The preferred OpenCL devices associated with the specified Direct3D object. |
{CL_ALL_DEVICES_FOR_D3D10_KHR} |
All OpenCL devices which may interoperate with the specified Direct3D object. Performance of sharing data on these devices may be considerably less than on the preferred devices. |
An OpenCL memory object created from a Direct3D 10 resource remains valid as long as the corresponding Direct3D 10 resource has not been deleted. If the Direct3D 10 resource is deleted through the Direct3D 10 API, subsequent use of the OpenCL memory object will result in undefined behavior, including but not limited to possible OpenCL errors, data corruption, and program termination.
The successful creation of a {cl_context_TYPE} against a Direct3D 10 device specified via the context create parameter {CL_CONTEXT_D3D10_DEVICE_KHR} will increment the internal Direct3D reference count on the specified Direct3D 10 device. The internal Direct3D reference count on that Direct3D 10 device will be decremented when the OpenCL reference count on the returned OpenCL context drops to zero.
The OpenCL context and corresponding command-queues are dependent on the existence of the Direct3D 10 device from which the OpenCL context was created. If the Direct3D 10 device is deleted through the Direct3D 10 API, subsequent use of the OpenCL context will result in undefined behavior, including but not limited to possible OpenCL errors, data corruption, and program termination.
The function
creates an OpenCL buffer object from a Direct3D 10 buffer.
context is a valid OpenCL context created from a Direct3D 10 device.
flags is a bit-field that is used to specify usage information. Refer to table 5.3 for a description of flags. Only {CL_MEM_READ_ONLY}, {CL_MEM_WRITE_ONLY} and {CL_MEM_READ_WRITE} values specified in table 5.3 can be used.
resource is a pointer to the Direct3D 10 buffer to share.
errcode_ret will return an appropriate error code.
If errcode_ret is NULL, no error code is returned.
{clCreateFromD3D10BufferKHR} returns a valid non-zero OpenCL buffer object
and errcode_ret is set to {CL_SUCCESS} if the buffer object is created
successfully.
Otherwise, it returns a NULL value with one of the following error values
returned in errcode_ret:
-
{CL_INVALID_CONTEXT} if context is not a valid context.
-
{CL_INVALID_VALUE} if values specified in flags are not valid.
-
{CL_INVALID_D3D10_RESOURCE_KHR} if resource is not a Direct3D 10 buffer resource, if resource was created with the D3D10_USAGE flag D3D10_USAGE_IMMUTABLE, if a {cl_mem_TYPE} from resource has already been created using {clCreateFromD3D10BufferKHR}, or if context was not created against the same Direct3D 10 device from which resource was created.
-
{CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources required by the OpenCL implementation on the host.
The size of the returned OpenCL buffer object is the same as the size of resource. This call will increment the internal Direct3D reference count on resource. The internal Direct3D reference count on resource will be decremented when the OpenCL reference count on the returned OpenCL memory object drops to zero.
The function
creates an OpenCL 2D image object from a subresource of a Direct3D 10 2D texture.
context is a valid OpenCL context created from a Direct3D 10 device.
flags is a bit-field that is used to specify usage information. Refer to table 5.3 for a description of flags. Only {CL_MEM_READ_ONLY}, {CL_MEM_WRITE_ONLY} and {CL_MEM_READ_WRITE} values specified in table 5.3 can be used.
resource is a pointer to the Direct3D 10 2D texture to share.
subresource is the subresource of resource to share.
errcode_ret will return an appropriate error code.
If errcode_ret is NULL, no error code is returned.
{clCreateFromD3D10Texture2DKHR} returns a valid non-zero OpenCL image object
and errcode_ret is set to {CL_SUCCESS} if the image object is created
successfully.
Otherwise, it returns a NULL value with one of the following error values
returned in errcode_ret:
-
{CL_INVALID_CONTEXT} if context is not a valid context.
-
{CL_INVALID_VALUE} if values specified in flags are not valid or if subresource is not a valid subresource index for resource.
-
{CL_INVALID_D3D10_RESOURCE_KHR} if resource is not a Direct3D 10 texture resource, if resource was created with the D3D10_USAGE flag D3D10_USAGE_IMMUTABLE, if resource is a multisampled texture, if a {cl_mem_TYPE} from subresource subresource of resource has already been created using {clCreateFromD3D10Texture2DKHR}, or if context was not created against the same Direct3D 10 device from which resource was created.
-
{CL_INVALID_IMAGE_FORMAT_DESCRIPTOR} if the Direct3D 10 texture format of resource is not listed in the table Direct3D 10 formats and corresponding OpenCL image formats or if the Direct3D 10 texture format of resource does not map to a supported OpenCL image format.
-
{CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources required by the OpenCL implementation on the host.
The width and height of the returned OpenCL 2D image object are determined by the width and height of subresource subresource of resource. The channel type and order of the returned OpenCL 2D image object is determined by the format of resource by the table Direct3D 10 formats and corresponding OpenCL image formats.
This call will increment the internal Direct3D reference count on resource. The internal Direct3D reference count on resource will be decremented when the OpenCL reference count on the returned OpenCL memory object drops to zero.
The function
creates an OpenCL 3D image object from a subresource of a Direct3D 10 3D texture.
context is a valid OpenCL context created from a Direct3D 10 device.
flags is a bit-field that is used to specify usage information. Refer to table 5.3 for a description of flags. Only {CL_MEM_READ_ONLY}, {CL_MEM_WRITE_ONLY} and {CL_MEM_READ_WRITE} values specified in table 5.3 can be used.
resource is a pointer to the Direct3D 10 3D texture to share.
subresource is the subresource of resource to share.
errcode_ret will return an appropriate error code.
If errcode_ret is NULL, no error code is returned.
{clCreateFromD3D10Texture3DKHR} returns a valid non-zero OpenCL image object
and errcode_ret is set to {CL_SUCCESS} if the image object is created
successfully.
Otherwise, it returns a NULL value with one of the following error values
returned in errcode_ret:
-
{CL_INVALID_CONTEXT} if context is not a valid context.
-
{CL_INVALID_VALUE} if values specified in flags are not valid or if subresource is not a valid subresource index for resource.
-
{CL_INVALID_D3D10_RESOURCE_KHR} if resource is not a Direct3D 10 texture resource, if resource was created with the D3D10_USAGE flag D3D10_USAGE_IMMUTABLE, if resource is a multisampled texture, if a {cl_mem_TYPE} from subresource subresource of resource has already been created using {clCreateFromD3D10Texture3DKHR}, or if context was not created against the same Direct3D 10 device from which resource was created.
-
{CL_INVALID_IMAGE_FORMAT_DESCRIPTOR} if the Direct3D 10 texture format of resource is not listed in the table Direct3D 10 formats and corresponding OpenCL image formats or if the Direct3D 10 texture format of resource does not map to a supported OpenCL image format.
-
{CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources required by the OpenCL implementation on the host.
The width, height and depth of the returned OpenCL 3D image object are determined by the width, height and depth of subresource subresource of resource. The channel type and order of the returned OpenCL 3D image object is determined by the format of resource by the table Direct3D 10 formats and corresponding OpenCL image formats.
This call will increment the internal Direct3D reference count on resource. The internal Direct3D reference count on resource will be decremented when the OpenCL reference count on the returned OpenCL memory object drops to zero.
| DXGI format | CL image format (channel order, channel data type) |
|---|---|
DXGI_FORMAT_R32G32B32A32_FLOAT |
|
DXGI_FORMAT_R32G32B32A32_UINT |
|
DXGI_FORMAT_R32G32B32A32_SINT |
|
DXGI_FORMAT_R16G16B16A16_FLOAT |
|
DXGI_FORMAT_R16G16B16A16_UNORM |
|
DXGI_FORMAT_R16G16B16A16_UINT |
|
DXGI_FORMAT_R16G16B16A16_SNORM |
|
DXGI_FORMAT_R16G16B16A16_SINT |
|
DXGI_FORMAT_B8G8R8A8_UNORM |
|
DXGI_FORMAT_R8G8B8A8_UNORM |
|
DXGI_FORMAT_R8G8B8A8_UINT |
|
DXGI_FORMAT_R8G8B8A8_SNORM |
|
DXGI_FORMAT_R8G8B8A8_SINT |
|
DXGI_FORMAT_R32G32_FLOAT |
|
DXGI_FORMAT_R32G32_UINT |
|
DXGI_FORMAT_R32G32_SINT |
|
DXGI_FORMAT_R16G16_FLOAT |
|
DXGI_FORMAT_R16G16_UNORM |
|
DXGI_FORMAT_R16G16_UINT |
|
DXGI_FORMAT_R16G16_SNORM |
|
DXGI_FORMAT_R16G16_SINT |
|
DXGI_FORMAT_R8G8_UNORM |
|
DXGI_FORMAT_R8G8_UINT |
|
DXGI_FORMAT_R8G8_SNORM |
|
DXGI_FORMAT_R8G8_SINT |
|
DXGI_FORMAT_R32_FLOAT |
|
DXGI_FORMAT_R32_UINT |
|
DXGI_FORMAT_R32_SINT |
|
DXGI_FORMAT_R16_FLOAT |
|
DXGI_FORMAT_R16_UNORM |
|
DXGI_FORMAT_R16_UINT |
|
DXGI_FORMAT_R16_SNORM |
|
DXGI_FORMAT_R16_SINT |
|
DXGI_FORMAT_R8_UNORM |
|
DXGI_FORMAT_R8_UINT |
|
DXGI_FORMAT_R8_SNORM |
|
DXGI_FORMAT_R8_SINT |
|
Properties of Direct3D 10 objects may be queried using {clGetMemObjectInfo} and {clGetImageInfo} with param_name {CL_MEM_D3D10_RESOURCE_KHR} and {CL_IMAGE_D3D10_SUBRESOURCE_KHR} respectively as described in sections 5.4.3 and 5.3.6.
The function
is used to acquire OpenCL memory objects that have been created from Direct3D 10 resources. The Direct3D 10 objects are acquired by the OpenCL context associated with command_queue and can therefore be used by all command-queues associated with the OpenCL context.
OpenCL memory objects created from Direct3D 10 resources must be acquired before they can be used by any OpenCL commands queued to a command-queue. If an OpenCL memory object created from a Direct3D 10 resource is used while it is not currently acquired by OpenCL, the behavior is undefined. Implementations may fail the execution of commands attempting to use that OpenCL memory object and set their associated event’s execution status to {CL_D3D10_RESOURCE_NOT_ACQUIRED_KHR}.
If {CL_CONTEXT_INTEROP_USER_SYNC} is not specified as {CL_TRUE} during context creation, {clEnqueueAcquireD3D10ObjectsKHR} provides the synchronization guarantee that any Direct3D 10 calls involving the interop device(s) used in the OpenCL context made before {clEnqueueAcquireD3D10ObjectsKHR} is called will complete executing before event reports completion and before the execution of any subsequent OpenCL work issued in command_queue begins. If the context was created with properties specifying {CL_CONTEXT_INTEROP_USER_SYNC} as {CL_TRUE}, the user is responsible for guaranteeing that any Direct3D 10 calls involving the interop device(s) used in the OpenCL context made before {clEnqueueAcquireD3D10ObjectsKHR} is called have completed before calling {clEnqueueAcquireD3D10ObjectsKHR}.
command_queue is a valid command-queue.
num_objects is the number of memory objects to be acquired in mem_objects.
mem_objects is a pointer to a list of OpenCL memory objects that were created from Direct3D 10 resources.
event_wait_list and num_events_in_wait_list specify events that need to
complete before this particular command can be executed.
If event_wait_list is NULL, then this particular command does not wait
on any event to complete.
If event_wait_list is NULL, num_events_in_wait_list must be 0.
If event_wait_list is not NULL, the list of events pointed to by
event_wait_list must be valid and num_events_in_wait_list must be
greater than 0.
The events specified in event_wait_list act as synchronization points.
event returns an event object that identifies this command and
can be used to query or wait for this command to complete.
If event is NULL or the enqueue is unsuccessful, no event will be
created and therefore it will not be possible to query the status of this
command or to wait for this command to complete.
If event_wait_list and event are not NULL, event must not refer
to an element of the event_wait_list array.
{clEnqueueAcquireD3D10ObjectsKHR} returns {CL_SUCCESS} if the function is
executed successfully.
If num_objects is 0 and mem_objects is NULL then the function does
nothing and returns {CL_SUCCESS}.
Otherwise it returns one of the following errors:
-
{CL_INVALID_VALUE} if num_objects is zero and mem_objects is not a
NULLvalue or if num_objects > 0 and mem_objects isNULL. -
{CL_INVALID_MEM_OBJECT} if memory objects in mem_objects are not valid OpenCL memory objects or if memory objects in mem_objects have not been created from Direct3D 10 resources.
-
{CL_INVALID_COMMAND_QUEUE} if command_queue is not a valid command-queue.
-
{CL_INVALID_CONTEXT} if context associated with command_queue was not created from an Direct3D 10 context.
-
{CL_D3D10_RESOURCE_ALREADY_ACQUIRED_KHR} if memory objects in mem_objects have previously been acquired using {clEnqueueAcquireD3D10ObjectsKHR} but have not been released using {clEnqueueReleaseD3D10ObjectsKHR}.
-
{CL_INVALID_EVENT_WAIT_LIST} if event_wait_list is
NULLand num_events_in_wait_list > 0, or event_wait_list is notNULLand num_events_in_wait_list is 0, or if event objects in event_wait_list are not valid events. -
{CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources required by the OpenCL implementation on the host.
The function
is used to release OpenCL memory objects that have been created from Direct3D 10 resources. The Direct3D 10 objects are released by the OpenCL context associated with command_queue.
OpenCL memory objects created from Direct3D 10 resources which have been acquired by OpenCL must be released by OpenCL before they may be accessed by Direct3D 10. Accessing a Direct3D 10 resource while its corresponding OpenCL memory object is acquired is in error and will result in undefined behavior, including but not limited to possible OpenCL errors, data corruption, and program termination.
If {CL_CONTEXT_INTEROP_USER_SYNC} is not specified as {CL_TRUE} during context creation, {clEnqueueReleaseD3D10ObjectsKHR} provides the synchronization guarantee that any calls to Direct3D 10 calls involving the interop device(s) used in the OpenCL context made after the call to {clEnqueueReleaseD3D10ObjectsKHR} will not start executing until after all events in event_wait_list are complete and all work already submitted to command_queue completes execution. If the context was created with properties specifying {CL_CONTEXT_INTEROP_USER_SYNC} as {CL_TRUE}, the user is responsible for guaranteeing that any Direct3D 10 calls involving the interop device(s) used in the OpenCL context made after {clEnqueueReleaseD3D10ObjectsKHR} will not start executing until after event returned by {clEnqueueReleaseD3D10ObjectsKHR} reports completion.
num_objects is the number of memory objects to be released in mem_objects.
mem_objects is a pointer to a list of OpenCL memory objects that were created from Direct3D 10 resources.
event_wait_list and num_events_in_wait_list specify events that need to
complete before this particular command can be executed.
If event_wait_list is NULL, then this particular command does not wait
on any event to complete.
If event_wait_list is NULL, num_events_in_wait_list must be 0.
If event_wait_list is not NULL, the list of events pointed to by
event_wait_list must be valid and num_events_in_wait_list must be
greater than 0.
event returns an event object that identifies this command and
can be used to query or wait for this command to complete.
If event is NULL or the enqueue is unsuccessful, no event will be
created and therefore it will not be possible to query the status of this
command or to wait for this command to complete.
If event_wait_list and event are not NULL, event must not refer
to an element of the event_wait_list array.
{clEnqueueReleaseD3D10ObjectsKHR} returns {CL_SUCCESS} if the function is
executed successfully.
If num_objects is 0 and mem_objects is NULL the function does nothing
and returns {CL_SUCCESS}.
Otherwise it returns one of the following errors:
-
{CL_INVALID_VALUE} if num_objects is zero and mem_objects is not a
NULLvalue or if num_objects > 0 and mem_objects isNULL. -
{CL_INVALID_MEM_OBJECT} if memory objects in mem_objects are not valid OpenCL memory objects or if memory objects in mem_objects have not been created from Direct3D 10 resources.
-
{CL_INVALID_COMMAND_QUEUE} if command_queue is not a valid command-queue.
-
{CL_INVALID_CONTEXT} if context associated with command_queue was not created from a Direct3D 10 device.
-
{CL_D3D10_RESOURCE_NOT_ACQUIRED_KHR} if memory objects in mem_objects have not previously been acquired using {clEnqueueAcquireD3D10ObjectsKHR}, or have been released using {clEnqueueReleaseD3D10ObjectsKHR} since the last time that they were acquired.
-
{CL_INVALID_EVENT_WAIT_LIST} if event_wait_list is
NULLand num_events_in_wait_list > 0, or event_wait_list is notNULLand num_events_in_wait_list> is 0, or if event objects in event_wait_list are not valid events. -
{CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources required by the OpenCL implementation on the host.
The following table describes the event command types for the OpenCL commands to acquire and release OpenCL memory objects that have been created from Direct3D 10 objects:
| Events Created By | Event Command Type |
|---|---|
{clEnqueueAcquireD3D10ObjectsKHR} |
{CL_COMMAND_ACQUIRE_D3D10_OBJECTS_KHR_anchor} |
{clEnqueueReleaseD3D10ObjectsKHR} |
{CL_COMMAND_RELEASE_D3D10_OBJECTS_KHR_anchor} |
-
Should this extension be KHR or EXT?
PROPOSED: KHR. If this extension is to be approved by Khronos then it should be KHR, otherwise EXT. Not all platforms can support this extension, but that is also true of OpenGL interop.
RESOLVED: KHR.
-
Requiring SharedHandle on ID3D10Resource
Requiring this can largely simplify things at the DDI level and make some implementations faster. However, the DirectX spec only defines the shared handle for a subset of the resources we would like to support:
D3D10_RESOURCE_MISC_SHARED - Enables the sharing of resource data between two or more Direct3D devices. The only resources that can be shared are 2D non-mipmapped textures.
PROPOSED A: Add wording to the spec about some implementations needing the resource setup as shared:
“Some implementations may require the resource to be shared on the D3D10 side of the API”
If we do that, do we need another enum to describe this failure case?
PROPOSED B: Require that all implementations support both shared and non-shared resources. The restrictions prohibiting multisample textures and the flag D3D10_USAGE_IMMUTABLE guarantee software access to all shareable resources.
RESOLVED: Require that implementations support both D3D10_RESOURCE_MISC_SHARED being set and not set. Add the query for {CL_CONTEXT_D3D10_PREFER_SHARED_RESOURCES_KHR} to determine on a per-context basis which method will be faster.
-
Texture1D support
There is not a matching CL type, so do we want to support this and map to buffer or Texture2D?
RESOLVED: We will not add support for ID3D10Texture1D objects unless a corresponding OpenCL 1D Image type is created.
-
CL/D3D10 queries
The GL interop has {clGetGLObjectInfo} and {clGetGLTextureInfo}. It is unclear if these are needed on the D3D10 interop side since the D3D10 spec makes these queries trivial on the D3D10 object itself. Also, not all of the semantics of the GL call map across.
PROPOSED: Add the {clGetMemObjectInfo} and {clGetImageInfo} parameter names {CL_MEM_D3D10_RESOURCE_KHR} and {CL_IMAGE_D3D10_SUBRESOURCE_KHR} to query the D3D10 resource from which a {cl_mem_TYPE} was created. From this data, any D3D10 side information may be queried using the D3D10 API.
RESOLVED: We will use {clGetMemObjectInfo} and {clGetImageInfo} to access this information.