OpenCL™规范 5.5.13. 在Direct3D 11和OpenCL上下文之间共享从Direct3D 11资源创建的内存对象

5.5.13. Sharing Memory Objects Created From Direct3D 11 Resources Between Direct3D 11 and OpenCL Contexts

5.5.13. 在Direct3D 11和OpenCL上下文之间共享从Direct3D 11资源创建的内存对象

To acquire OpenCL memory objects that have been created from Direct3D 11 resources, call the function

要获取从Direct3D11资源创建的OpenCL内存对象，请调用函数

// Provided by cl_khr_d3d11_sharing
cl_int clEnqueueAcquireD3D11ObjectsKHR(
    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);

clEnqueueAcquireD3D11ObjectsKHR is provided by the cl_khr_d3d11_sharing extension. clEnqueueAcquireD3D11ObjectsKHR由cl_khr_d3d11_sharing扩展提供。

• command_queue is a valid command-queue.

• command_queue是一个有效的命令队列。

• num_objects is the number of memory objects to be acquired in mem_objects.

• num_objects是要在mem_objects中获取的内存对象的数量。

• mem_objects is a pointer to a list of OpenCL memory objects that were created from Direct3D 11 resources.

• mem_objects是指向从Direct3D11资源创建的OpenCL内存对象列表的指针。

• 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_wait_list和num_events_in_wait_list指定在执行此特定命令之前需要完成的事件。如果event_wait_list为NULL，则此特定命令不等待任何事件完成。如果event_wait_list为NULL，则num_events_in_wait_list必须为0。如果event_wait_list不为NULL，则event_wail_list指向的事件列表必须有效，并且num_events_in_wait_list必须大于0。event_wait_list中指定的事件充当同步点。

• 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.

• event返回一个事件对象，该对象标识此命令，可用于查询或等待此命令完成。如果事件为NULL或排队不成功，则不会创建任何事件，因此无法查询此命令的状态或等待此命令完成。如果event_wait_list和event不为NULL，则event不能引用event_wail_list数组的元素。

The Direct3D 11 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.

Direct3D 11对象由与command_queue相关联的OpenCL上下文获取，并且因此可以由与OpenCL上下文相关联的所有命令队列使用。

OpenCL memory objects created from Direct3D 11 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 11 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_D3D11_RESOURCE_NOT_ACQUIRED_KHR.

​从Direct3D 11资源创建的OpenCL内存对象必须先获取，然后才能被排队到命令队列的任何OpenCL命令使用。如果使用从Direct3D 11资源创建的OpenCL内存对象，而OpenCL当前未获取该对象，则该行为未定义。实现可能会使尝试使用该OpenCL内存对象的命令的执行失败，并将其相关联的事件的执行状态设置为CL_D3D11_RESOURCE_NOT_ACQUIRED_KHR。

If CL_CONTEXT_INTEROP_USER_SYNC is not specified as CL_TRUE during context creation, clEnqueueAcquireD3D11ObjectsKHR provides the synchronization guarantee that any Direct3D 11 calls involving the interop device(s) used in the OpenCL context made before clEnqueueAcquireD3D11ObjectsKHR 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 11 calls involving the interop device(s) used in the OpenCL context made before clEnqueueAcquireD3D11ObjectsKHR is called have completed before calling clEnqueueAcquireD3D11ObjectsKHR.

​如果在上下文创建过程中未将CL_CONTEXT_INTEROP_USER_SYNC指定为CL_TRUE，则clEnqueueAcquireD3D11ObjectsKHR提供同步保证，即在调用clEnqueueAcquireD3D11ObjectsKHR之前进行的涉及OpenCL上下文中使用的互操作设备的任何Direct3D 11调用将在事件报告完成之前以及在command_queue中发布的任何后续OpenCL工作开始执行之前完成执行。如果上下文是使用将CL_CONTEXT_INTEROP_USER_SYNC指定为CL_TRUE的属性创建的，则用户负责确保在调用clEnqueueAcquireD3D11ObjectsKHR之前进行的涉及OpenCL上下文中使用的互操作设备的任何Direct3D 11调用在调用clenqueueAcquire3D11ObjectsKHR之前已完成。

clEnqueueAcquireD3D11ObjectsKHR 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:

​如果函数执行成功，clEnqueueAcquireD3D11ObjectsKHR将返回CL_SUCCESS。如果num_objects是0，mem_objects为NULL，则函数不执行任何操作并返回CL_SUCCESS。否则，它将返回以下错误之一：

• CL_INVALID_VALUE if num_objects is zero and mem_objects is not a NULL value or if num_objects > 0 and mem_objects is NULL.

• CL_INVALID_VALUE如果num_objects为零且mem_objects不是NULL值，或者如果num_oobjects>0且mem_objects为NULL。

• 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 11 resources.

• CL_INVALID_MEM_OBJECT如果mem_objects中的内存对象不是有效的OpenCL内存对象，或者如果mem_oobjects中的存储对象不是从Direct3D 11资源创建的。

• CL_INVALID_COMMAND_QUEUE if command_queue is not a valid command-queue.

• CL_INVALID_COMMAND_QUEUE（如果command_queue不是有效的命令队列）。

• CL_INVALID_CONTEXT if context associated with command_queue was not created from an Direct3D 11 context.

• CL_INVALID_CONTEXT，如果与command_queue关联的上下文不是从Direct3D 11上下文创建的。

• CL_D3D11_RESOURCE_ALREADY_ACQUIRED_KHR if memory objects in mem_objects have previously been acquired using clEnqueueAcquireD3D11ObjectsKHR but have not been released using clEnqueueReleaseD3D11ObjectsKHR.

• CL_D3D11_RESOURCE_ALREADY_CQUIRED_KHR如果mem_objects中的内存对象先前已使用clEnqueueAcquireD3D11ObjectsKHR获取，但尚未使用clEnQueueReleaseD3D11ObjectsKHR释放。

• CL_INVALID_EVENT_WAIT_LIST if event_wait_list is NULL and num_events_in_wait_list > 0, or event_wait_list is not NULL and num_events_in_wait_list is 0, or if event objects in event_wait_list are not valid events.

• CL_INVALID_EVENT_WAIT_LIST如果event_wait_list为NULL且num_events_in_wait_list >0，或者event_wait_list不为NULL且num_events_in_wait_list为0，或者如果event_wait_list中的事件对象不是有效事件。

• CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

• CL_OUT_OF_HOST_MEMORY，如果在主机上分配OpenCL实现所需的资源失败。

To release OpenCL memory objects that have been created from Direct3D 11 resources, call the function

要释放从Direct3D11资源创建的OpenCL内存对象，请调用函数

// Provided by cl_khr_d3d11_sharing
cl_int clEnqueueReleaseD3D11ObjectsKHR(
    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);

clEnqueueReleaseD3D11ObjectsKHR is provided by the cl_khr_d3d11_sharing extension. clEnqueueReleaseD3D11ObjectsKHR由cl_khr_d3d11_sharing扩展提供。

• num_objects is the number of memory objects to be released in mem_objects.

• num_objects是要在mem_objects中释放的内存对象的数量。

• mem_objects is a pointer to a list of OpenCL memory objects that were created from Direct3D 11 resources.

• mem_objects是指向从Direct3D11资源创建的OpenCL内存对象列表的指针。

• 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_wait_list和num_events_in_wait_list指定在执行此特定命令之前需要完成的事件。如果event_wait_list为NULL，则此特定命令不等待任何事件完成。如果event_wait_list为NULL，则num_events_in_wait_list必须为0。如果event_wait_list不为NULL，则event_wail_list指向的事件列表必须有效，并且num_events_in_wait_list必须大于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.

• event返回一个事件对象，该对象标识此命令，可用于查询或等待此命令完成。如果事件为NULL或排队不成功，则不会创建任何事件，因此无法查询此命令的状态或等待此命令完成。如果event_wait_list和event不为NULL，则event不能引用event_wail_list数组的元素。

The Direct3D 11 objects are released by the OpenCL context associated with command_queue.

Direct3D 11对象由与command_queue相关联的OpenCL上下文释放。

OpenCL memory objects created from Direct3D 11 resources which have been acquired by OpenCL must be released by OpenCL before they may be accessed by Direct3D 11. Accessing a Direct3D 11 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.

从已经被OpenCL获取的Direct3D 11资源创建的OpenCL存储器对象必须在它们可以被Direct3D 11访问之前被OpenCL释放。在获取Direct3D 11资源对应的OpenCL内存对象时访问该资源是错误的，并将导致未定义的行为，包括但不限于可能的OpenCL错误、数据损坏和程序终止。

If CL_CONTEXT_INTEROP_USER_SYNC is not specified as CL_TRUE during context creation, clEnqueueReleaseD3D11ObjectsKHR provides the synchronization guarantee that any calls to Direct3D 11 calls involving the interop device(s) used in the OpenCL context made after the call to clEnqueueReleaseD3D11ObjectsKHR 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 11 calls involving the interop device(s) used in the OpenCL context made after clEnqueueReleaseD3D11ObjectsKHR will not start executing until after event returned by clEnqueueReleaseD3D11ObjectsKHR reports completion.

​如果在上下文创建期间未将CL_CONTEXT_INTEROP_USER_SYNC指定为CL_TRUE，则clEnqueueReleaseD3D11ObjectsKHR提供同步保证，即在调用clEnqueueRelease D3D11objectsKHR之后对Direct3D 11调用的任何涉及OpenCL上下文中使用的互操作设备的调用都将不会开始执行，直到event_wait_list中的所有事件都完成，并且所有已提交到command_queue的工作都完成执行之后。如果创建的上下文具有将CL_context_INTEROP_USER_SYNC指定为CL_TRUE的属性，则用户有责任确保在clEnqueueReleaseD3D11ObjectsKHR返回的事件报告完成之前，任何涉及OpenCL上下文中使用的互操作设备的Direct3D 11调用都不会开始执行。

clEnqueueReleaseD3D11ObjectsKHR 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:

​如果函数执行成功，clEnqueueReleaseD3D11ObjectsKHR将返回CL_SUCCESS。如果num_objects为0，mem_objects是NULL，则函数不执行任何操作并返回CL_SUCCESS。否则，它将返回以下错误之一：

• CL_INVALID_VALUE if num_objects is zero and mem_objects is not a NULL value or if num_objects > 0 and mem_objects is NULL.

• CL_INVALID_VALUE如果num_objects为零且mem_objects不是NULL值，或者如果num_oobjects>0且mem_oobjects为NULL。

• 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 11 resources.

• CL_INVALID_MEM_OBJECT如果mem_objects中的内存对象不是有效的OpenCL内存对象，或者如果mem_oobjects中的存储对象不是从Direct3D 11资源创建的。

• CL_INVALID_COMMAND_QUEUE if command_queue is not a valid command-queue.

• CL_INVALID_COMMAND_QUEUE（如果command_queue不是有效的命令队列）。

• CL_INVALID_CONTEXT if context associated with command_queue was not created from a Direct3D 11 device.

• CL_INVALID_CONTEXT，如果与命令队列相关联的上下文不是从Direct3D 11设备创建的。

• CL_D3D11_RESOURCE_NOT_ACQUIRED_KHR if memory objects in mem_objects have not previously been acquired using clEnqueueAcquireD3D11ObjectsKHR, or have been released using clEnqueueReleaseD3D11ObjectsKHR since the last time that they were acquired.

• CL_D3D11_RESOURCE_NOT_ACQUIRED_KHR如果mem_objects中的内存对象以前未使用clEnqueueAcquireD3D11ObjectsKHR获取，或者自上次获取以来已使用clEnQueueReleaseD3D11ObjectsKHR释放。

• CL_INVALID_EVENT_WAIT_LIST if event_wait_list is NULL and num_events_in_wait_list > 0, or event_wait_list is not NULL and num_events_in_wait_list> is 0, or if event objects in event_wait_list are not valid events.

• CL_INVALID_EVENT_WAIT_LIST如果event_wait_list为NULL且num_events_in_wait_list>0，或者event_wait_list不为NULL且num_events_in_wait_list>为0，或者如果event_wait_list中的事件对象不是有效事件。

• CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

• CL_OUT_OF_HOST_MEMORY，如果在主机上分配OpenCL实现所需的资源失败。