OpenCL™规范 5.5.1.1. 获取和释放外部内存对象

最新推荐文章于 2024-06-21 09:48:38 发布

꧁白杨树下꧂

最新推荐文章于 2024-06-21 09:48:38 发布

阅读量52

点赞数

分类专栏： openCL 文章标签： opencl

原文链接：https://registry.khronos.org/OpenCL/specs/3.0-unified/html/OpenCL_API.html#acquiring-external-memory

版权

openCL 专栏收录该内容

162 篇文章 12 订阅

订阅专栏

5.5.1.1. Acquiring and Releasing External Memory Objects

5.5.1.1. 获取和释放外部内存对象

To enqueue a command to acquire OpenCL memory objects created from external memory handles, call the function

要将获取从外部内存句柄创建的OpenCL内存对象的命令排入队列，请调用函数

// Provided by cl_khr_external_memory
cl_int clEnqueueAcquireExternalMemObjectsKHR(
    cl_command_queue command_queue,
    cl_uint num_mem_objects,
    const cl_mem* mem_objects,
    cl_uint num_events_in_wait_list,
    const cl_event* event_wait_list,
    cl_event* event);

clEnqueueAcquireExternalMemObjectsKHR is provided by the cl_khr_external_memory extension.

clEnqueueAcquireExternalMemObjectsKHR由cl_khr_external_memory扩展提供。

command_queue specifies a valid command-queue.
command_queue指定一个有效的命令队列。
num_mem_objects specifies the number of memory objects to acquire.
num_mem_objects指定要获取的内存对象的数量。
mem_objects points to a list of valid memory objects.
mem_objects指向有效内存对象的列表。
num_events_in_wait_list specifies the number of events in event_wait_list.
num_events_in_wait_list指定event_wait_list中的事件数。
event_wait_list points to the list of events that need to complete before clEnqueueAcquireExternalMemObjectsKHR can be executed. If event_wait_list is NULL, then clEnqueueAcquireExternalMemObjectsKHR does not explicitly 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. The context associated with events in event_wait_list and that of command_queue must be the same.
event_wait_list指向在执行clEnqueueAcquireExternalMemObjectsKHR之前需要完成的事件列表。如果event_wait_list为NULL，则clEnqueueAcquireExternalMemObjectsKHR不会显式等待任何事件完成。如果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_wait_list中的事件相关联的上下文和command_queue中的上下文必须相同。
event returns an event object that identifies this particular command and can be used to query or queue a wait for this particular command to complete. event can be NULL in which case it will not be possible for the application to query the status of this command or queue a wait for this command to complete.
event返回一个事件对象，该对象标识此特定命令，并可用于查询或排队等待此特定命令完成。事件可以为NULL，在这种情况下，应用程序将无法查询此命令的状态或排队等待此命令完成。

Applications must acquire the memory objects that are created using external handles before they can be used by any OpenCL commands queued to a command-queue. Behavior is undefined if a memory object created from an external memory handle is used by an OpenCL command queued to a command-queue without being acquired. This is to guarantee that the state of the memory objects is up-to-date and they are accessible to OpenCL. See “Example with Acquire / Release” for more details on how to use this API.

应用程序必须先获取使用外部句柄创建的内存对象，然后才能被排队到命令队列的任何OpenCL命令使用。如果从外部内存句柄创建的内存对象被排队到命令队列的OpenCL命令使用而未被获取，则行为是未定义的。这是为了保证内存对象的状态是最新的，并且OpenCL可以访问这些对象。有关如何使用此API的更多详细信息，请参阅“获取/发布示例”。

If num_mem_objects is 0 and mem_objects is NULL, the command will trivially succeed after its event dependencies are satisfied and will update its completion event.

如果num_mem_objects为0，mem_objects是NULL，则在满足其事件依赖关系后，该命令将非常成功，并将更新其完成事件。

clEnqueueAcquireExternalMemObjectsKHR returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:

如果函数执行成功，clEnqueueAcquireExternalMemObjectsKHR将返回CL_SUCCESS。否则，它将返回以下错误之一：

CL_INVALID_VALUE if num_mem_objects is zero and mem_objects is not a NULL value, or if num_mem_objects is greater than 0 and mem_objects is NULL.
CL_INVALID_VALUE如果num_mem_objects为零且mem_objects不是NULL值，或者如果num_mem _objects大于0且mem_objects为NULL。
CL_INVALID_MEM_OBJECT if any of the memory objects in mem_objects is not a valid OpenCL memory object created using an external memory handle.
CL_INVALID_MEM_OBJECT，如果mem_objects中的任何内存对象不是使用外部内存句柄创建的有效OpenCL内存对象。
CL_INVALID_COMMAND_QUEUE
- if command_queue is not a valid command-queue, or
- 如果command_queue不是有效的命令队列，或者
- if device associated with command_queue is not one of the devices specified by CL_MEM_DEVICE_HANDLE_LIST_KHR at the time of creating one or more of mem_objects, or ** if one or more of mem_objects belong to a context that does not contain a device associated with command_queue.
- 如果与command_queue关联的设备在创建一个或多个mem_objects时不是CL_MEM_DEVICE_HANDLE_LIST_KHR指定的设备之一，或者**如果一个或更多mem_objects属于不包含与command_ queue关联设备的上下文。
CL_INVALID_EVENT_WAIT_LIST
- if event_wait_list is NULL and num_events_in_wait_list is not 0, or
- 如果event_wait_list为NULL并且num_events_in_wait_list不为0，或者
- if event_wait_list is not NULL and num_events_in_wait_list is 0, or
- 如果event_wait_list不为NULL并且num_events_in_wait_list为0，或者
- if event objects in event_wait_list are not valid events.
- 如果event_wait_list中的事件对象不是有效的事件。
CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST if the execution status of any of the events in event_wait_list is a negative integer value.
如果event_wait_list中任何事件的执行状态为负整数值，则CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST。
CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
CL_OUT_OF_RESOURCES，如果在设备上分配OpenCL实现所需的资源失败。
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 enqueue a command to release OpenCL memory objects created from external memory handles, call the function

要将释放从外部内存句柄创建的OpenCL内存对象的命令排入队列，请调用函数

// Provided by cl_khr_external_memory
cl_int clEnqueueReleaseExternalMemObjectsKHR(
    cl_command_queue command_queue,
    cl_uint num_mem_objects,
    const cl_mem* mem_objects,
    cl_uint num_events_in_wait_list,
    const cl_event* event_wait_list,
    cl_event* event);

command_queue specifies a valid command-queue.
command_queue指定一个有效的命令队列。
num_mem_objects specifies the number of memory objects to release.
num_mem_objects指定要释放的内存对象数。
mem_objects points to a list of valid memory objects.
mem_objects指向有效内存对象的列表。
num_events_in_wait_list specifies the number of events in event_wait_list.
num_events_in_wait_list指定event_wait_list中的事件数。
event_wait_list points to the list of events that need to complete before clEnqueueReleaseExternalMemObjectsKHR can be executed. If event_wait_list is NULL, then clEnqueueReleaseExternalMemObjectsKHR 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. The context associated with events in event_wait_list and that of command_queue must be the same.
event_wait_list指向在执行clEnqueueReleaseExternalMemObjectsKHR之前需要完成的事件列表。如果event_wait_list为NULL，则clEnqueueReleaseExternalMemObjectsKHR不等待任何事件完成。如果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_wait_list中的事件相关联的上下文和command_queue中的上下文必须相同。
event returns an event object that identifies this particular command and can be used to query or queue a wait for this particular command to complete. event can be NULL in which case it will not be possible for the application to query the status of this command or queue a wait for this command to complete.
event返回一个事件对象，该对象标识此特定命令，并可用于查询或排队等待此特定命令完成。事件可以为NULL，在这种情况下，应用程序将无法查询此命令的状态或排队等待此命令完成。

Applications must release the memory objects that are acquired using clEnqueueReleaseExternalMemObjectsKHR before using them through any commands in the other API. This is to guarantee that the state of memory objects is up-to-date and they are accessible to the other API. See “Example with Acquire / Release” provided in Sample Code for more details on how to use this API.

在通过其他API中的任何命令使用内存对象之前，应用程序必须释放使用clEnqueueReleaseExternalMemObjectsKHR获取的内存对象。这是为了保证内存对象的状态是最新的，并且其他API可以访问它们。有关如何使用此API的更多详细信息，请参阅示例代码中提供的“获取/发布示例”。

If num_mem_objects is 0 and mem_objects is NULL, the command will trivially succeed after its event dependencies are satisfied and will update its completion event.

如果num_mem_objects为0，mem_objects是NULL，则在满足其事件依赖关系后，该命令将非常成功，并将更新其完成事件。

clEnqueueReleaseExternalMemObjectsKHR returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:

如果函数执行成功，clEnqueueReleaseExternalMemObjectsKHR将返回CL_SUCCESS。否则，它将返回以下错误之一：

CL_INVALID_VALUE if num_mem_objects is zero and mem_objects is not a NULL value, or if num_mem_objects is greater than 0 and mem_objects is NULL.
CL_INVALID_VALUE如果num_mem_objects为零且mem_objects不是NULL值，或者如果num_mem _objects大于0且mem_objects为NULL。
CL_INVALID_MEM_OBJECT if any of the memory objects in mem_objects is not a valid OpenCL memory object created using an external memory handle.
CL_INVALID_MEM_OBJECT，如果mem_objects中的任何内存对象不是使用外部内存句柄创建的有效OpenCL内存对象。
CL_INVALID_COMMAND_QUEUE
- if command_queue is not a valid command-queue, or
- 如果command_queue不是有效的命令队列，或者
- if device associated with command_queue is not one of the devices specified by CL_MEM_DEVICE_HANDLE_LIST_KHR at the time of creating one or more of mem_objects, or
- 如果在创建一个或多个mem_objects时，与command_queue关联的设备不是CL_MEM_DEVICE_HANDLE_LIST_KHR指定的设备之一，或者
- if one or more of mem_objects belong to a context that does not contain a device associated with command_queue.
- 如果一个或多个mem_objects属于不包含与command_queue相关联的设备的上下文。
CL_INVALID_EVENT_WAIT_LIST
- if event_wait_list is NULL and num_events_in_wait_list is not 0, or
- 如果event_wait_list为NULL并且num_events_in_wait_list不为0，或者
- if event_wait_list is not NULL and num_events_in_wait_list is 0, or
- 如果event_wait_list不为NULL并且num_events_in_wait_list为0，或者
- if event objects in event_wait_list are not valid events.
- 如果event_wait_list中的事件对象不是有效的事件。
CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST if the execution status of any of the events in event_wait_list is a negative integer value.
如果event_wait_list中任何事件的执行状态为负整数值，则CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST。
CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
CL_OUT_OF_RESOURCES，如果在设备上分配OpenCL实现所需的资源失败。
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实现所需的资源失败。