OpenCL™规范 5.5.15. 获取、释放和同步对共享OpenCL/OpenGL内存对象的访问

5.5.15. Acquiring, Releasing, and Synchronizing Access to Shared OpenCL/OpenGL Memory Objects

5.5.15. 获取、释放和同步对共享OpenCL/OpenGL内存对象的访问

To acquire OpenCL memory objects that have been created from OpenGL objects, call the function

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

// Provided by cl_khr_gl_sharing
cl_int clEnqueueAcquireGLObjects(
    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);

clEnqueueAcquireGLObjects is provided by the cl_khr_gl_sharing extension. clEnqueueAcquireGLObjects由cl_khr_gl_sharing扩展提供。

• command_queue is a valid command-queue. All devices used to create the OpenCL context associated with command_queue must support acquiring shared OpenCL/OpenGL objects. This constraint is enforced at context creation time.

• command_queue是一个有效的命令队列。用于创建与command_queue关联的OpenCL上下文的所有设备都必须支持获取共享的OpenCL/OpenGL对象。此约束在上下文创建时强制执行。

• 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 correspond to OpenGL objects.

• mem_objects是指向与OpenGL对象相对应的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 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返回一个标识此命令的事件对象，可用于查询wait以等待此命令完成。如果事件为NULL或排队不成功，则不会创建任何事件，因此无法查询此命令的状态或等待此命令完成。如果event_wait_list和event不为NULL，则event不能引用event_wail_list数组的元素。

If an OpenGL context is bound to the current thread, then any OpenGL commands which

如果OpenGL上下文绑定到当前线程，则任何OpenGL命令

1.affect or access the contents of a memory object listed in the mem_objects list, and

1.影响或访问mem_objects列表中列出的内存对象的内容，以及

2.were issued on that OpenGL context prior to the call to clEnqueueAcquireGLObjects

2.在调用clEnqueueAcquireGLObjects之前在该OpenGL上下文上发布

will complete before execution of any OpenCL commands following the clEnqueueAcquireGLObjects which affect or access any of those memory objects. If a non-NULL event object is returned, it will report completion only after completion of such OpenGL commands.

将在执行clEnqueueAcquireGLObjects之后的任何OpenCL命令之前完成，这些命令会影响或访问这些内存对象中的任何一个。如果返回非NULL事件对象，则只有在完成此类OpenGL命令后，它才会报告完成。

These objects need to be acquired before they can be used by any OpenCL commands queued to a command-queue or the behaviour is undefined. The OpenGL 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命令使用这些对象之前，需要获取这些对象，或者行为未定义。OpenGL对象由与command_queue相关联的OpenCL上下文获取，因此可以由与OpenCL上下文相关联的所有命令队列使用。

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

​如果函数执行成功，clEnqueueAcquireGLObjects将返回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_objects>0且mem_objects为NULL。

• CL_INVALID_MEM_OBJECT if memory objects in mem_objects are not valid OpenCL memory objects.

• CL_INVALID_MEM_OBJECT如果mem_objects中的内存对象不是有效的OpenCL内存对象。

• 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 OpenGL context

• CL_INVALID_CONTEXT如果与command_queue关联的上下文不是从OpenGL上下文创建的

• CL_INVALID_GL_OBJECT if memory objects in mem_objects have not been created from an OpenGL object(s).

• CL_INVALID_GL_OBJECT（如果mem_objects中的内存对象不是从OpenGL对象创建的）。

• 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_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 release OpenCL memory objects that have been created from OpenGL objects, call the function

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

// Provided by cl_khr_gl_sharing
cl_int clEnqueueReleaseGLObjects(
    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);

clEnqueueReleaseGLObjects is provided by the cl_khr_gl_sharing extension. clEnqueueReleaseGLObjects由cl_khr_gl_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 correspond to OpenGL objects.

• mem_objects是指向与OpenGL对象相对应的OpenCL内存对象列表的指针。

• event_wait_list and num_events_in_wait_list specify events that need to complete before this 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数组的元素。

If an OpenGL context is bound to the current thread, then then any OpenGL commands which

如果OpenGL上下文绑定到当前线程，则任何OpenGL命令

1.affect or access the contents of the memory objects listed in the mem_objects list, and

1.影响或访问mem_objects列表中列出的内存对象的内容，以及

2.are issued on that context after the call to clEnqueueReleaseGLObjects

2.在调用clEnqueueReleaseGLObjects之后在该上下文中发出

will not execute until after execution of any OpenCL commands preceding the

在执行之前的任何OpenCL命令之后才会执行

clEnqueueReleaseGLObjects which affect or access any of those memory objects. If a non-NULL event object is returned, it will report completion before execution of such OpenGL commands.

clEnqueueReleaseGLObjects，它影响或访问任何这些内存对象。如果返回非NULL事件对象，它将在执行此类OpenGL命令之前报告完成。

These objects need to be released before they can be used by OpenGL. The OpenGL objects are released by the OpenCL context associated with command_queue.

在OpenGL使用这些对象之前，需要先释放这些对象。OpenGL对象由与command_queue关联的OpenCL上下文释放。

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

​如果函数执行成功，clEnqueueReleaseGLObjects将返回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_objects>0且mem_objects为NULL。

• CL_INVALID_MEM_OBJECT if memory objects in mem_objects are not valid OpenCL memory objects.

• CL_INVALID_MEM_OBJECT如果mem_objects中的内存对象不是有效的OpenCL内存对象。

• 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 OpenGL context

• CL_INVALID_CONTEXT如果与command_queue关联的上下文不是从OpenGL上下文创建的

• CL_INVALID_GL_OBJECT if memory objects in mem_objects have not been created from an OpenGL object(s).

• CL_INVALID_GL_OBJECT（如果mem_objects中的内存对象不是从OpenGL对象创建的）。

• 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_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实现所需的资源失败。