OpenCL™规范 5.13.3. 导出信号量外部句柄

5.13.3. Exporting Semaphore External Handles

5.13.3. 导出信号量外部句柄

To export an external handle from a semaphore, call the function

要从信号量导出外部句柄，请调用以下函数

// Provided by cl_khr_external_semaphore
cl_int clGetSemaphoreHandleForTypeKHR(
    cl_semaphore_khr sema_object,
    cl_device_id device,
    cl_external_semaphore_handle_type_khr handle_type,
    size_t handle_size,
    void* handle_ptr,
    size_t* handle_size_ret);

• sema_object specifies a valid semaphore object with exportable properties.

• sema_object指定了一个具有可导出属性的有效信号量对象。

• device specifies a valid device for which a semaphore handle is being requested.

• device指定了一个请求信号量句柄的有效设备。

• handle_type specifies the type of semaphore handle that should be returned for this exportable sema_object, and must be one of the values specified when sema_object was created.

• handle_type指定应为此可导出sema_object返回的信号量句柄的类型，并且必须是创建sema_object时指定的值之一。

• handle_size specifies the size of memory pointed by handle_ptr.

• handle_size指定handle_ptr指向的内存大小。

• handle_ptr is a pointer to memory where the exported external handle is returned. If param_value is NULL, it is ignored.

• handle_ptr是一个指向返回导出外部句柄的内存的指针。如果param_value为NULL，则忽略它。

• handle_size_ret returns the actual size in bytes for the external handle. If handle_size_ret is NULL, it is ignored.

• handle_size_ret返回外部句柄的实际大小（以字节为单位）。如果handle_size_ret为NULL，则忽略它。

clGetSemaphoreHandleForTypeKHR returns CL_SUCCESS if the semaphore handle is queried successfully. Otherwise, it returns one of the following errors:

​如果成功查询信号量句柄，clGetSemaphoreHandleForTypeKHR将返回CL_SUCCESS。否则，它将返回以下错误之一：

• CL_INVALID_SEMAPHORE_KHR

  • if sema_object is not a valid semaphore

  • 如果sema_object不是有效的信号量

  • if sema_object is not exportable

  • 如果sema_object不可导出

• CL_INVALID_DEVICE

  • if device is not a valid device, or

  • 如果device 不是有效设备，或

  • if sema_object belongs to a context that is not associated with device, or

  • 如果sema_object属于与device无关的上下文，或者

  • if sema_object can not be shared with device.

  • 如果sema_object不能与设备共享。

• CL_INVALID_VALUE if the requested external semaphore handle type was not specified when sema_object was created.

• 如果在创建sema_object时未指定请求的外部信号量句柄类型，则返回CL_INVALID_VALUE。

• CL_INVALID_VALUE if handle_size is less than the size needed to store the returned handle.

• 如果handle_size小于存储返回句柄所需的大小，则返回CL_INVALID_VALUE。

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