signpost KHR text extensions to the OpenCL Extension Spec (#63)
affects cl_khr_icd, cl_khr_d3d10_sharing, and cl_khr_gl_sharing
diff --git a/extensions/khr/cl_khr_d3d10_sharing.txt b/extensions/khr/cl_khr_d3d10_sharing.txt
index 0635e72..2e3f289 100644
--- a/extensions/khr/cl_khr_d3d10_sharing.txt
+++ b/extensions/khr/cl_khr_d3d10_sharing.txt
@@ -1,914 +1,12 @@
-Name String
+The normative cl_khr_d3d10_sharing specification is now in the
+OpenCL Extension Specification and is no longer authored in
+plain text.
- cl_khr_d3d10_sharing
+Please refer to the OpenCL Extension Specification on the
+OpenCL Registry:
-Contact
+https://www.khronos.org/registry/OpenCL/
- Mike Houston, Advanced Micro Devices, Inc. ( michael.houston 'at' amd.com )
- Christopher Cameron, NVIDIA Corporation ( chcameron 'at' nvidia.com )
+The Asciidoc source for this extension may be found here:
-Contributors
-
- Christopher Cameron (Nvidia)
- Ben Gaster (AMD)
- Michael Gold (Nvidia)
- Mike Houston (AMD)
- John Kessenich (Intel)
- Christopher Lamb (Nvidia)
- Victor Odintsov (AMD)
- Ofer Rosenberg (Intel)
-
-Version
-
- Version 9, March 31, 2010
-
-Number
-
- OpenCL Extension #6
-
-Status
-
- Complete. Version 7 approved by the OpenCL Working Group.
- Ratified by the Khronos Promoters, February 26, 2010.
-
-Extension Type
-
- OpenCL platform extension
-
-Dependencies
-
- OpenCL 1.0 is required. This extension is written against the OpenCL
- 1.0-rev48 Specification.
-
- A Direct3D 10 implementation supporting sharing of buffer and
- texture objects with OpenCL is required.
-
-Overview
-
- The goal of this extension is to provide interoperability between
- OpenCL and Direct3D 10. This is designed to function analogously to
- the OpenGL interoperability as defined in the OpenCL 1.0
- specification and accompanying extensions.
-
-Header File
-
- Interfaces for this extension are provided in cl_d3d10.h .
-
-New Procedures and Functions
-
- 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,
- cl_mem *mem_objects,
- cl_uint num_events_in_wait_list,
- const cl_event *event_wait_list,
- cl_event *event)
-
-New Tokens
-
- Accepted as a Direct3D 10 device source in the <d3d_device_source>
- parameter of clGetDeviceIDsFromD3D10KHR:
-
- CL_D3D10_DEVICE_KHR 0x4010
- CL_D3D10_DXGI_ADAPTER_KHR 0x4011
-
- Accepted as a set of Direct3D 10 devices in the <d3d_device_set> parameter
- of clGetDeviceIDsFromD3D10KHR:
-
- CL_PREFERRED_DEVICES_FOR_D3D10_KHR 0x4012
- CL_ALL_DEVICES_FOR_D3D10_KHR 0x4013
-
- Accepted as a property name in the <properties> parameter of
- clCreateContext and clCreateContextFromType:
-
- CL_CONTEXT_D3D10_DEVICE_KHR 0x4014
-
- Accepted as a property name in the <param_name> parameter of
- clGetContextInfo:
-
- CL_CONTEXT_D3D10_PREFER_SHARED_RESOURCES_KHR 0x402C
-
- Accepted as the property being queried in the <param_name>
- parameter of clGetMemObjectInfo:
-
- CL_MEM_D3D10_RESOURCE_KHR 0x4015
-
- Accepted as the property being queried in the <param_name>
- parameter of clGetImageInfo:
-
- CL_IMAGE_D3D10_SUBRESOURCE_KHR 0x4016
-
- Returned in the <param_value> parameter of clGetEventInfo when
- <param_name> is CL_EVENT_COMMAND_TYPE:
-
- CL_COMMAND_ACQUIRE_D3D10_OBJECTS_KHR 0x4017
- CL_COMMAND_RELEASE_D3D10_OBJECTS_KHR 0x4018
-
- 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 -1002
-
- 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 -1003
-
- Returned by clEnqueueAcquireD3D10ObjectsKHR when any of <mem_objects> are
- currently acquired by OpenCL
-
- CL_D3D10_RESOURCE_ALREADY_ACQUIRED_KHR -1004
-
- Returned by clEnqueueReleaseD3D10ObjectsKHR when any of <mem_objects> are
- not currently acquired by OpenCL
-
- CL_D3D10_RESOURCE_NOT_ACQUIRED_KHR -1005
-
-Additions to Chapter 4 of the OpenCL 1.0 Specification
-
- In section 4.3, 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.4) 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."
-
- Replace existing table 4.4 with:
-
- "--------------------------------------------------------------------------------------
- cl_context_properties Value type Default value Description
- --------------------- ---------- ------------- -----------
- CL_CONTEXT_PLATFORM cl_platform_id NULL Specifies the cl_platform_id
- on whic to create the OpenCL
- context.
- CL_CONTEXT_D3D10_DEVICE_KHR ID3D10Device* NULL Specifies the ID3D10Device*
- to use for Direct3D 10
- interoperabilty."
- --------------------------------------------------------------------------------------"
-
- 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-NULL and 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-NULL value, 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.5:
-
- "--------------------------------------------------------------------------------------
- cl_context_info Return Type Information returned in param_value
- --------------------- ----------- -----------------------------------
- CL_CONTEXT_D3D10_PREFER_SHARED_RESOURCES_KHR
- cl_bool 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."
- --------------------------------------------------------------------------------------"
-
-Additions to Chapter 5 of the OpenCL 1.0 Specification
-
- 5.2.9 Memory Object Queries
-
- Change the last paragraph before table 5.8 to read
-
- "clGetMemObjectInfo returns CL_SUCCESS if the function is executed successfully.
- Otherwise it returns one of the following errors:
-
- * CL_INVALID_VALUE if <param_name> is not valid, or if the size in bytes
- specified by <param_value_size> is less than the size of the return type as
- described in table 5.8 and <param_value> is not NULL.
-
- * CL_INVALID_MEM_OBJECT if <memobj> is a not a valid memory object.
-
- * 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.8 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.
-
- Change the last paragraph before table 5.9 to read
-
- "clGetImageInfo returns CL_SUCCESS if the function is executed successfully.
- Otherwise it returns one of the following errors:
-
- * CL_INVALID_VALUE if <param_name> is not valid, or if the size in bytes
- specified by <param_value_size> is less than the size of the return type as
- described in table 5.9 and <param_value> is not NULL.
-
- * CL_INVALID_MEM_OBJECT if <image> is a not a valid image object.
-
- * CL_INVALID_D3D10_RESOURCE_KHR if <param_name> is CL_MEM_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 ID3D10Resource* If <image> was created using
- clCreateFromD3D10Texture2DKHR, or
- clCreateFromD3D10Texture3DKHR,
- returns the <subresource> argument
- specified when <image> was
- created.
-
- 5.7 Event Objects
-
- Add to Table 5.15 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
-
-Add new section 9.13
-
- 9.13 Sharing Memory Objects with Direct3D 10 Resources
-
- 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.
-
- 9.13.1 Querying OpenCL Devices Corresponding to Direct3D 10 Devices
-
- 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
-
- 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)
-
- <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 table 9.13.1.1.
-
- <d3d_object> specifies the object whose corresponding OpenCL devices
- are being queried. The type of <d3d_object> must be as specified in
- table 9.13.1.1.
-
- <cl_device_set> specifies the set of devices to return, and must be
- one of the values shown in table 9.13.1.2.
-
- <num_entries> is the number of cl_device_id 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 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 mininum 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> are NULL.
-
- * CL_DEVICE_NOT_FOUND if no OpenCL devices that correspond to
- <d3d_object> were found.
-
- --------------------------------------------------------------------
- cl_d3d_device_source_khr Type of <d3d_object>
- ------------------------ --------------------
- CL_D3D10_DEVICE_KHR ID3D10Device *
- CL_D3D10_DXGI_ADAPTER_KHR IDXGIAdapter *
- --------------------------------------------------------------------
- Table 9.13.1.1: Types used to specify the object whose corresponding
- OpenCL devices are being queried by clGetDeviceIDsFromD3D10KHR.
-
- --------------------------------------------------------------------
- cl_d3d_device_set_khr Devices returned in <devices>
- ------------------------ -----------------------------
- CL_PREFERRED_DEVICES_FOR_D3D10_KHR The 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.
- --------------------------------------------------------------------
- Table 9.13.1.2: Sets of devices queriable using
- clGetDeviceIDsFromD3D10KHR.
-
- 9.13.2 Lifetime of Shared Objects
-
- 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 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.
-
- 9.13.3 Sharing Direct3D 10 Buffer Resources as OpenCL Buffer Objects
-
- The function
-
- cl_mem clCreateFromD3D10BufferKHR(
- cl_context context,
- cl_mem_flags flags,
- ID3D10Buffer *resource,
- int *errcode_ret)
-
- 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 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.
-
- 9.13.4 Sharing Direct3D 10 Texture and Resources as OpenCL Image
- Objects
-
- The function
-
- cl_mem clCreateFromD3D10Texture2DKHR(
- cl_context context,
- cl_mem_flags flags,
- ID3D10Texture2D *resource,
- UINT subresource,
- int *errcode_ret)
-
- 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 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 table 9.13.4.1.
-
- * 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 table 9.13.4.1.
-
- 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
-
- cl_mem clCreateFromD3D10Texture3DKHR(
- cl_context context,
- cl_mem_flags flags,
- ID3D10Texture3D *resource,
- UINT subresource,
- int *errcode_ret)
-
- 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 a cl_mem 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 table 9.13.4.1.
-
- * 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 return 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 table 9.13.4.1.
-
- 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_channel_order cl_channel_type
- ------------------------------ ---------------- ---------------
- DXGI_FORMAT_R32G32B32A32_FLOAT CL_RGBA CL_FLOAT
- DXGI_FORMAT_R32G32B32A32_UINT CL_RGBA CL_UNSIGNED_INT32
- DXGI_FORMAT_R32G32B32A32_SINT CL_RGBA CL_SIGNED_INT32
- DXGI_FORMAT_R16G16B16A16_FLOAT CL_RGBA CL_HALF_FLOAT
- DXGI_FORMAT_R16G16B16A16_UNORM CL_RGBA CL_UNORM_INT16
- DXGI_FORMAT_R16G16B16A16_UINT CL_RGBA CL_UNSIGNED_INT16
- DXGI_FORMAT_R16G16B16A16_SNORM CL_RGBA CL_SNORM_INT16
- DXGI_FORMAT_R16G16B16A16_SINT CL_RGBA CL_SIGNED_INT16
- DXGI_FORMAT_R8G8B8A8_UNORM CL_RGBA CL_UNORM_INT8
- DXGI_FORMAT_R8G8B8A8_UINT CL_RGBA CL_UNSIGNED_INT8
- DXGI_FORMAT_R8G8B8A8_SNORM CL_RGBA CL_SNORM_INT8
- DXGI_FORMAT_R8G8B8A8_SINT CL_RGBA CL_SIGNED_INT8
- DXGI_FORMAT_R32G32_FLOAT CL_RG CL_FLOAT
- DXGI_FORMAT_R32G32_UINT CL_RG CL_UNSIGNED_INT32
- DXGI_FORMAT_R32G32_SINT CL_RG CL_SIGNED_INT32
- DXGI_FORMAT_R16G16_FLOAT CL_RG CL_HALF_FLOAT
- DXGI_FORMAT_R16G16_UNORM CL_RG CL_UNORM_INT16
- DXGI_FORMAT_R16G16_UINT CL_RG CL_UNSIGNED_INT16
- DXGI_FORMAT_R16G16_SNORM CL_RG CL_SNORM_INT16
- DXGI_FORMAT_R16G16_SINT CL_RG CL_SIGNED_INT16
- DXGI_FORMAT_R8G8_UNORM CL_RG CL_UNORM_INT8
- DXGI_FORMAT_R8G8_UINT CL_RG CL_UNSIGNED_INT8
- DXGI_FORMAT_R8G8_SNORM CL_RG CL_SNORM_INT8
- DXGI_FORMAT_R8G8_SINT CL_RG CL_SIGNED_INT8
- DXGI_FORMAT_R32_FLOAT CL_R CL_FLOAT
- DXGI_FORMAT_R32_UINT CL_R CL_UNSIGNED_INT32
- DXGI_FORMAT_R32_SINT CL_R CL_SIGNED_INT32
- DXGI_FORMAT_R16_FLOAT CL_R CL_HALF_FLOAT
- DXGI_FORMAT_R16_UNORM CL_R CL_UNORM_INT16
- DXGI_FORMAT_R16_UINT CL_R CL_UNSIGNED_INT16
- DXGI_FORMAT_R16_SNORM CL_R CL_SNORM_INT16
- DXGI_FORMAT_R16_SINT CL_R CL_SIGNED_INT16
- DXGI_FORMAT_R8_UNORM CL_R CL_UNORM_INT8
- DXGI_FORMAT_R8_UINT CL_R CL_UNSIGNED_INT8
- DXGI_FORMAT_R8_SNORM CL_R CL_SNORM_INT8
- DXGI_FORMAT_R8_SINT CL_R CL_SIGNED_INT8
- ------------------------------------------------------------------
- Table 9.13.4.1: List of Direct3D 10 and corresponding OpenCL Image
- Formats
-
- 9.13.5 Querying Direct3D properties of memory objects created from
- Direct3D 10 resources.
-
- 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 as described in section 5.2.9.
-
- 9.13.6 Sharing memory objects created from Direct3D 10 resources between
- Direct3D 10 and OpenCL contexts
-
- The function
-
- 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)
-
- 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 call
- attempting to use that OpenCL memory object will return
- CL_D3D10_RESOURCE_NOT_ACQUIRED_KHR.
-
- clEnqueueAcquireD3D10ObjectsKHR provides the synchronization guarantee
- that any Direct3D 10 calls 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.
-
- <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 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.
-
- 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 NULL value or if <num_objects> > 0 and <mem_objects> is
- 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 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 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_OUT_OF_HOST_MEMORY if there is a failure to allocate resources
- required by the OpenCL implementation on the host.
-
- The function
-
- 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)
-
- 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.
-
- clEnqueueReleaseD3D10ObjectsKHR provides the synchronization guarantee
- that any calls to Direct3D 10 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.
-
- <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. The
- events specified in
-
- <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.
-
- 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 NULL value or if <num_objects> > 0 and <mem_objects> is
- 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 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
- 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 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_OUT_OF_HOST_MEMORY if there is a failure to allocate resources
- required by the OpenCL implementation on the host.
-
-Issues
-
- 1) 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.
-
- 2) 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: required 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.
-
- 3) Texture1D support
-
- There is not a matching CL type, so do we want to
- support this and map to buffer or Texture2D? If so the command might
- correspond to the 2D / 3D versions:
-
- cl_mem clCreateFromD3D10Texture1D(cl_context context,
- cl_mem_flags flags,
- ID3D10Texture2D *resource,
- UINT subresource,
- int *errcode_ret)
-
- RESOLVED: We will not add support for ID3D10Texture1D objects unless
- a corresponding OpenCL 1D Image type is created.
-
- 4) 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 sematics 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 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.
-
-Revision History
-
- Version 9, 2010/03/31 (Jon Leech) - cleanup for publication. Update
- Status and Header File fields with final approved information. Fix
- clEnqueueReleaseExternalObjectsKHR->clEnqueueReleaseD3D10ObjectsKHR
- typo.
-
- Version 8, 2010/02/08 (Christopher Cameron) - fix typos and add
- enumerant values.
-
- Version 7, 2009/12/14 (Christopher Cameron) - resolve issue 2 by
- adding CL_CONTEXT_D3D10_PREFER_SHARED_RESOURCES_KHR query.
-
- Version 6, 2009/12/01 (Christopher Cameron) - clarify error
- codes and behavior of clContextCreate with CL_CONTEXT_D3D10_DEVICE.
-
- Version 5, 2009/11/30 (Christopher Cameron) - clarify object
- lifetime, add KHR decoration to symbols, clarify size and format of
- shared objects, clarify acquire/release semantics mark issues as
- resolved.
-
- Version 4, 2009/11/23 (Christopher Cameron) - add synchronization
- guarantees for clEnqueueAcquireD3D10Objects and
- clEnqueueReleaseD3D10Objects.
-
- Version 3, 2009/11/20 (Christopher Cameron) - add device/adapter
- query function clGetDeviceIDsFromD3D10KHR. Add prohibition on
- D3D10_USAGE_IMMUTABLE and multisample textures to guarantee a
- consistent image format (e.g, how should a 2x multisampled texture
- appear to OpenCL), add support for querying
- CL_MEM_D3D10_RESOURCE_KHR and CL_IMAGE_D3D10_SUBRESOURCE_KHR. Add
- image format conversion table. Minor tweaks of names, formatting.
- Change extension name to cl_khr_d3d10_sharing to match OpenGL.
-
- Version 2, 2009/09/08 (Jon Leech) - tweak spec to match CL extension
- template structurally, some minor reformatting and reflowing of
- text. Move clCreateFromD3D10Texture1D from the New Functions section
- into issue 3. Update section numbering to be against OpenCL 1.0 rev
- 47.
-
- Version 1, 2009/08/31 (Michael Houston) - initial extension
- specification based on discussion in bug 3663.
+https://github.com/KhronosGroup/OpenCL-Docs/blob/master/ext/cl_khr_d3d10_sharing.txt
diff --git a/extensions/khr/cl_khr_gl_sharing.txt b/extensions/khr/cl_khr_gl_sharing.txt
index 89b7718..893e460 100644
--- a/extensions/khr/cl_khr_gl_sharing.txt
+++ b/extensions/khr/cl_khr_gl_sharing.txt
@@ -1,543 +1,14 @@
-Name Strings
+The normative cl_khr_gl_sharing specification is now in the
+OpenCL Extension Specification and is no longer authored in
+plain text.
- cl_khr_gl_sharing
+Please refer to the OpenCL Extension Specification on the
+OpenCL Registry:
-Version
+https://www.khronos.org/registry/OpenCL/
- Version 15, March 10, 2010
+The Asciidoc source for this extension may be found here:
-Number
-
- OpenCL Extension #1
-
-Status
-
- Complete. Version 10 approved by the OpenCL Working Group.
- Ratified by the Khronos Promoters, August 28, 2009.
-
-Extension Type
-
- OpenCL platform extension
-
-Dependencies
-
- OpenCL 1.0 is required. This extension is written against the OpenCL
- 1.0 revision 47 specification draft.
-
- An OpenGL implementation supporting buffer objects and sharing of
- texture and buffer object images with OpenCL is required.
-
- This extension is included in the OpenCL 1.0 specification as
- section 9.11 for reference purposes. However, the normative version
- of the extension, as approved by the OpenCL Working Group, will
- always be the separate cl_khr_gl_sharing.txt document in the Khronos
- API Registry.
-
-Overview
-
- OpenCL defines how to share image data with texture and buffer
- objects in a parallel OpenGL implementation, but does not define how
- the association between an OpenCL context and an OpenGL context or
- share group is established. This extension defines optional
- attributes to OpenCL context creation routines which associate a GL
- context or share group object with a newly created OpenGL context.
-
-Header File
-
- This extension's interfaces are defined in cl_gl.h .
-
-New Types
-
- typedef cl_uint cl_gl_context_info;
-
-New Procedures and Functions
-
- cl_int clGetGLContextInfoKHR(const cl_context_properties *properties,
- cl_gl_context_info param_name,
- size_t param_value_size,
- void *param_value,
- size_t *param_value_size_ret);
-
-New Tokens
-
- Returned by clCreateContext, clCreateContextFromType, and
- clGetGLContextInfoKHR when an invalid OpenGL context or share group
- object handle is specified in <properties>:
-
- CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR -1000
-
- Accepted as the <param_name> argument of clGetGLContextInfoKHR:
-
- CL_CURRENT_DEVICE_FOR_GL_CONTEXT_KHR 0x2006
- CL_DEVICES_FOR_GL_CONTEXT_KHR 0x2007
-
- Accepted as an attribute name in the 'properties' argument of
- clCreateContext and clCreateContextFromType:
-
- CL_GL_CONTEXT_KHR 0x2008
- CL_EGL_DISPLAY_KHR 0x2009
- CL_GLX_DISPLAY_KHR 0x200A
- CL_WGL_HDC_KHR 0x200B
- CL_CGL_SHAREGROUP_KHR 0x200C
-
-Additions to Chapter 4 of the OpenCL 1.0 Specification
-
- In section 4.3, replace the description of <properties> under
- clCreateContext on page 38 with:
-
- "<properties> points to an <attribute list>, which is a array of
- ordered <attribute name, value> pairs terminated with zero. If an
- attribute is not specified in <properties>, then its default value
- (listed in table 4.4) 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.
-
- If the CL_CONTEXT_PLATFORM attribute is not specified, or is
- specified with the default value of NULL, the selected platform is
- implementation-defined.
-
- Other attributes control sharing of OpenCL memory objects with
- OpenGL buffer, texture, and renderbuffer objects as described in
- section 9.12. Depending on the platform-specific API used to bind
- OpenGL contexts to the window system, the following attributes may
- be set to identify an OpenGL context:
-
- * When the CGL binding API is supported, the attribute
- CL_CGL_SHAREGROUP_KHR should be set to a CGLShareGroup handle to
- a CGL share group object.
-
- * When the EGL binding API is supported, the attribute
- CL_GL_CONTEXT_KHR should be set to an EGLContext handle to an
- OpenGL ES or OpenGL context, and the attribute
- CL_EGL_DISPLAY_KHR should be set to the EGLDisplay handle of the
- display used to create the OpenGL ES or OpenGL context.
-
- * When the GLX binding API is supported, the attribute
- CL_GL_CONTEXT_KHR should be set to a GLXContext handle to an
- OpenGL context, and the attribute CL_GLX_DISPLAY_KHR should be
- set to the Display handle of the X Window System display used to
- create the OpenGL context.
-
- * When the WGL binding API is supported, the attribute
- CL_GL_CONTEXT_KHR should be set to an HGLRC handle to an OpenGL
- context, and the attribute CL_WGL_HDC_KHR should be set to the
- HDC handle of the display used to create the OpenGL context.
-
- Memory objects created in the context so specified may be shared
- with the specified OpenGL or OpenGL ES context (as well as with any
- other OpenGL contexts on the share list of that context, according
- to the description of sharing in the GLX 1.4 and EGL 1.4
- Specifications, and the WGL documentation for OpenGL implementations
- on Microsoft Windows), or with the explicitly identified OpenGL
- share group for CGL. If no OpenGL or OpenGL ES context or share
- group is specified in the attribute list, then memory objects may
- not be shared, and calling any of the commands in section 9.12 will
- result in a CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR error."
-
- Replace existing table 4.4 with:
-
- "-------------------------------------------------------------------------
- Attribute Name Allowed Values Description
- (cl_context (default value
- properties enum) is in *bold*)
- --------------------- ------------------ -----------------------------
- CL_CONTEXT_PLATFORM *NULL*, Specifies the platform to
- cl_platform_id create the OpenCL context on
- pointer
- CL_GL_CONTEXT_KHR *0*, OpenGL context to associate
- OpenGL context the OpenCL context with
- handle
- CL_CGL_SHAREGROUP_KHR *0*, CGL share group to associate
- CGL share group the OpenCL context with
- handle
- CL_EGL_DISPLAY_KHR *EGL_NO_DISPLAY*, EGLDisplay an OpenGL context
- EGLDisplay handle was created with respect to
- CL_GLX_DISPLAY_KHR *None* X Display an OpenGL context
- X Display handle was created with respect to
- CL_WGL_HDC_KHR *0*, HDC an OpenGL context
- HDC handle was created with respect to
- ------------------------------------------------------------------------
- Table 4.4: Context creation attributes"
-
- Add to the list of errors for clCreateContext:
-
- "* CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR if a context was specified
- by any of the following means:
-
- * A context was specified for an EGL-based OpenGL ES or OpenGL
- implementation by setting the attributes CL_GL_CONTEXT_KHR and
- CL_EGL_DISPLAY_KHR
- * A context was specified for a GLX-based OpenGL implementation by
- setting the attributes CL_GL_CONTEXT_KHR and CL_GLX_DISPLAY_KHR
- * A context was specified for a WGL-based OpenGL implementation by
- setting the attributes CL_GL_CONTEXT_KHR and CL_WGL_HDC_KHR
-
- and any of the following conditions hold:
-
- * The specified display and context attributes do not identify a
- valid OpenGL or OpenGL ES context
- * The specified context does not support buffer and renderbuffer
- objects.
- * The specified context is not compatible with the OpenCL context
- being created (for example, it exists in a physically distinct
- address space, such as another hardware device; or it does not
- support sharing data with OpenCL due to implementation
- restrictions).
-
- * CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR if a share group was
- specified for a CGL-based OpenGL implementation by setting the
- attribute CL_CGL_SHAREGROUP_KHR, and the specified share group
- does not identify a valid CGL share group object.
-
- * CL_INVALID_OPERATION if a context or share group object was
- specified for one of CGL, EGL, GLX, or WGL and any of the
- following conditions hold:
-
- * The OpenGL implementation does not support the window-system
- binding API for which a context or share group objects was
- specified.
- * More than one of the attributes CL_CGL_SHAREGROUP_KHR,
- CL_EGL_DISPLAY_KHR, CL_GLX_DISPLAY_KHR, and CL_WGL_HDC_KHR is
- set to a non-default value.
- * Both of the attributes CL_CGL_SHAREGROUP_KHR and
- CL_GL_CONTEXT_KHR are set to non-default values.
- * Any of the devices specified in the <devices> argument cannot
- support OpenCL objects which share the data store of an OpenGL
- object, as described in section 9.12."
-
- Replace the description of <properties> under
- clCreateContextFromType with:
-
- "<properties> points to an attribute list whose format and valid
- contents are identical to the <properties> argument of
- clCreateContext."
-
- Add to the list of errors for clCreateContextFromType the same new
- errors described above for clCreateContext.
-
-Additions to Section 9.12 (Sharing Memory Objects...) of the OpenCL 1.0
-Specification
-
- Add new section 9.12.7:
-
- "9.12.7 Querying devices corresponding to OpenGL contexts
-
- OpenCL device(s) corresponding to an OpenGL context may be queried.
- Such a device may not always exist (for example, if an OpenGL
- context is specified on a GPU not supporting OpenCL command queues,
- but which does support shared CL/GL objects), and if it does exist,
- may change over time. When such a device does exist, acquiring and
- releasing shared CL/GL objects may be faster on a command queue
- corresponding to this device than on command queues corresponding to
- other devices available to an OpenCL context. To query the currently
- corresponding device, use the function
-
- cl_int clGetGLContextInfoKHR(const cl_context_properties *properties,
- cl_gl_context_info param_name,
- size_t param_value_size,
- void *param_value,
- size_t *param_value_size_ret);
-
- <properties> points to an attribute list whose format and valid
- contents are identical to the <properties> argument of
- clCreateContext. <properties> must identify a single valid GL
- context or GL share group object.
-
- <param_name> is a constant that specifies the GL context information
- to query, and must be one of the values shown in table 9.ctxprop.
-
- <param_value> is a pointer to memory where the result of the query
- is returned as described in table 9.ctxprop. If <param_value> is
- NULL, it is ignored.
-
- <param_value_size> specifies the size in bytes of memory pointed to
- by <param_value>. This size must be greater than or equal to the
- size of the return type described in table 9.ctxprop.
-
- <param_value_size_ret> returns the actual size in bytes of data
- being queried by <param_value>. If <param_value_size_ret> is NULL,
- it is ignored.
-
- --------------------------------------------------------------------
- param_name,
- return type info. returned in param_value
- ----------- --------------------------------------------
- CL_CURRENT_DEVICE_FOR_GL_CONTEXT_KHR,
- cl_device_id CL device currently associated with the
- specified OpenGL context
-
- CL_DEVICES_FOR_GL_CONTEXT_KHR,
- cl_device_id[] List of all CL devices which may be
- associated with the specified OpenGL context
- --------------------------------------------------------------------
- Table 9.ctxprop: GL context information that can be queried with
- clGetGLContextInfoKHR
-
- clGetGLContextInfoKHR returns CL_SUCCESS if the function is executed
- successfully. If no device(s) exist corresponding to <param_name>,
- the call will not fail, but the value of <param_value_size_ret> will
- be zero.
-
- clGetGLContextInfoKHR returns CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR
- if a context was specified by any of the following means:
- * A context was specified for an EGL-based OpenGL ES or OpenGL
- implementation by setting the attributes CL_GL_CONTEXT_KHR and
- CL_EGL_DISPLAY_KHR
- * A context was specified for a GLX-based OpenGL implementation by
- setting the attributes CL_GL_CONTEXT_KHR and CL_GLX_DISPLAY_KHR
- * A context was specified for a WGL-based OpenGL implementation by
- setting the attributes CL_GL_CONTEXT_KHR and CL_WGL_HDC_KHR
- and any of the following conditions hold:
- * The specified display and context attributes do not identify a
- valid OpenGL or OpenGL ES context
- * The specified context does not support buffer and renderbuffer
- objects.
- * The specified context is not compatible with the OpenCL context
- being created (for example, it exists in a physically distinct
- address space, such as another hardware device; or it does not
- support sharing data with OpenCL due to implementation
- restrictions).
-
- clGetGLContextInfoKHR returns CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR
- if a share group was specified for a CGL-based OpenGL implementation
- by setting the attribute CL_CGL_SHAREGROUP_KHR, and the specified
- share group does not identify a valid CGL share group object.
-
- clGetGLContextInfoKHR returns CL_INVALID_OPERATION if a context was
- specified as described above and any of the following conditions
- hold:
- * A context or share group object was specified for one of CGL,
- EGL, GLX, or WGL and the OpenGL implementation does not support
- that window-system binding API.
- * More than one of the attributes CL_CGL_SHAREGROUP_KHR,
- CL_EGL_DISPLAY_KHR, CL_GLX_DISPLAY_KHR, and CL_WGL_HDC_KHR is
- set to a non-default value.
- * Both of the attributes CL_CGL_SHAREGROUP_KHR and
- CL_GL_CONTEXT_KHR are set to non-default values.
- * Any of the devices specified in the <devices> argument cannot
- support OpenCL objects which share the data store of an OpenGL
- object, as described in section 9.12.
-
- clGetGLContextInfoKHR returns CL_INVALID_VALUE if an attribute name
- other than CL_GL_CONTEXT_KHR, CL_CGL_SHAREGROUP_KHR,
- CL_EGL_DISPLAY_KHR, CL_GLX_DISPLAY_KHR, or CL_WGL_HDC_KHR (as
- described in table 4.4) is specified in <properties>, or if the same
- property name is specified more than once.
-
- Additionally, clGetGLContextInfoKHR returns CL_INVALID_VALUE if
- <param_name> is not one of the values listed in table 9.ctxprop, or
- if the size in bytes specified by <param_value_size> is less than
- the size of the return type shown in table 9.ctxprop, and
- <param_value> is not a NULL value."
-
-Issues
-
- 1) How should the OpenGL context be identified when creating an
- associated OpenCL context?
-
- RESOLVED: by using a (display,context handle) attribute pair to
- identify an arbitrary OpenGL or OpenGL ES context with respect to
- one of the window-system binding layers EGL, GLX, or WGL, or a share
- group handle to identify a CGL share group. If a context is
- specified, it need not be current to the thread calling
- clCreateContext*.
-
- A previously suggested approach would use a single boolean attribute
- CL_USE_GL_CONTEXT_KHR to allow creating a context associated with the
- currently bound OpenGL context. This may still be implemented as a
- separate extension, and might allow more efficient Acquire/Release
- behavior in the special case where they are being executed in the
- same thread as the bound GL context used to create the CL context.
-
- 2) What should the format of an attribute list be?
-
- After considerable discussion in bug 4340, we think we can live with
- a list of <attribute name,value> pairs terminated by zero. The list
- is passed as 'cl_context_properties *properties', where
- cl_context_properties is typedefed to be 'intptr_t' in cl.h.
-
- This effectively allows encoding all scalar integer, pointer, and
- handle values in the host API into the argument list and is
- analogous to the structure and type of EGL attribute lists. NULL
- attribute lists are also allowed. Again as for EGL, any attributes
- not explicitly passed in the list will take on a defined default
- value that does something reasonable.
-
- Experience with EGL, GLX, and WGL has shown attribute lists to be a
- sufficiently flexible and general mechanism to serve the needs of
- management calls such as context creation. It is not completely
- general (encoding floating-point and non-scalar attribute values is
- not straightforward), and other approaches were suggested in bug
- 4340 such as opaque attribute lists with getter/setter methods, or
- arrays of varadic structures.
-
- 3) What's the behavior of an associated OpenGL or OpenCL context when
- using resources defined by the other associated context, and that
- context is destroyed?
-
- RESOLVED: As described in section 9.12, OpenCL objects place a
- reference on the data store underlying the corresponding GL object
- when they're created. The GL name corresponding to that data store
- may be deleted, but the data store itself remains so long as any CL
- object has a reference to it.
-
- However, destroying all GL contexts in the share group corresponding
- to a CL context results in implementation-dependent behavior when
- using a corresponding CL object, up to and including program
- termination.
-
- 4) How about sharing with D3D?
-
- Sharing between D3D and OpenCL should use the same attribute list
- mechanism, though obviously with different parameters, and be
- exposed as a similar parallel OpenCL extension. There may be an
- interaction between that extension and this one since it's not yet
- clear if it will be possible to create a CL context simultaneously
- sharing GL and D3D objects.
-
- 5) Under what conditions will context creation fail due to sharing?
-
- RESOLVED: Several cross-platform failure conditions are described
- (GL context or CGL share group doesn't exist, GL context doesn't
- support types of GL objects required by the section 9.12 interfaces,
- GL context implementation doesn't allow sharing), but additional
- failures may result due to implementation-dependent reasons and
- should be added to this extension as such failures are discovered.
- Sharing between OpenCL and OpenGL requires integration at the driver
- internals level.
-
- 6) What command queues can clEnqueueAcquire/ReleaseGLObjects be placed
- on?
-
- RESOLVED: All command queues. This restriction is enforced at
- context creation time. If any device passed to context creation
- cannot support shared CL/GL objects, context creation will fail with
- a CL_INVALID_OPERATION error.
-
- 7) How can applications determine which command queue to place an
- Acquire/Release on?
-
- RESOLVED: The clGetGLContextInfoKHR returns either the CL device
- currently corresponding to a specified GL context (typically the
- display it's running on), or a list of all the CL devices the
- specified context might run on (potentially useful in multiheaded /
- "virtual screen" environments). This command is not simply placed in
- section 9.12 because it relies on the same property-list method of
- specifying a GL context introduced by this extension.
-
- If no devices are returned, it means that the GL context exists on
- an older GPU not capable of running OpenCL, but still capable of
- sharing objects between GL running on that GPU and CL running
- elsewhere.
-
- 8) What is the meaning of the CL_DEVICES_FOR_GL_CONTEXT_KHR query?
-
- RESOLVED: the list of all CL devices that may ever be associated
- with a specific GL context. On platforms such as MacOS X,
- the "virtual screen" concept allows multiple GPUs to back a single
- virtual display. Similar functionality might be implemented on other
- windowing systems, such as a transparent heterogenous multiheaded X
- server. Therefore the exact meaning of this query is interpreted
- relative to the binding layer API in use.
-
- 9) Miscellaneous issues during syncing of version 12 with the OpenCL
- 1.0 revision 47 spec language and the minor changes Affie made
- including this extension as section 9.11 of that spec:
-
- - rev47 spec numbers table 9.ctxprop as "9.7" but this may depends
- on the core spec revision.
- - rev47 spec uses 'cl_context' as the return type for
- clGetGLContextInfoKHR param names, but cl_device_id /
- cl_device_id[] are the proper types.
- - rev47 spec omits the paragraph describing CL_SUCCESS return from
- clGetGLContextInfoKHR.
-
-Sample Code
-
- None yet.
-
-Conformance Tests
-
- None yet. The conformance suite's GL/CL interop testing will
- probably make use of this extension in time.
-
-Revision History
-
- Version 15, 2010/03/10 (Jon Leech) - Add missing "Header File"
- section now that the extension headers have been published.
-
- Version 14, 2009/12/02 (Jon Leech) - Add missing "New Types" section
- with cl_gl_context_info type definition (public bug 239).
-
- Version 13, 2009/10/02 (Jon Leech) - Fix typo (CL_CONTEXT_PROPERTY
- -> CL_CONTEXT_PLATFORM) and list a default value of NULL for this
- attribute in table 4.4.
-
- Version 12, 2009/10/01 (Jon Leech) - Change value for
- CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR from -63 to -1000, to be in a
- new range of extension error codes instead of in the core API error
- codes. Sync up spec language with movement of Appendix B to Section
- 9.12 of the latest 1.0 specification update and modify existing
- table 4.4 instead of adding a new table. Moved clGetGLContextInfoKHR
- into a new subsection 9.12.7 and added the same INVALID_VALUE error
- for badly formed attribute lists (repeated properties) as
- clCreateContext, to encourage consistent treatment of attribute
- lists everywhere they're used. Reduced number of quote marks around
- new spec language.
-
- Version 11, 2009/09/02 (Jon Leech) - Fix capitalization of the name
- string. Note that this is not purely a cosmetic change.
- Implementations should not ship with the Version 10 and earlier
- capitalization. Update status to note approval by the Promoters.
-
- Version 10, 2009/08/27 (Jon Leech) - Add 'const' attribute to
- clGetGLContextInfoKHR <properties> parameter.
-
- Version 9, 2009/07/06 (Jon Leech) - Fix minor typos. Assign
- enumerant values. Change CL_INVALID_GL_CONTEXT_KHR error to
- CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR so it can apply to either
- contexts or share group objects. Expand full text of error conditions
- for clGetGLContextInfoKHR. Resolve all issues still marked
- UNRESOLVED with the currently defined behaviors. Rename
- CL_CURRENT_DEVICE_FOR_GL_CONTEXT_KHR and
- CL_DEVICES_FOR_GL_CONTEXT_KHR to drop "DISPLAY" and remove the
- Apple-specific CGL_ prefix.
-
- Version 8, 2009/06/15 (Jon Leech) - remove unused OpenCL context
- argument from clGetGLContextInfoKHR and fix type of param_name
- argument, based on discussion in bug 4340. Fix minor typos.
-
- Version 7, 2009/04/27 (Jon Leech) - add "extension type", fill in a
- few more fields from the prototype extension template, and tag this
- as a platform extension.
-
- Version 6, 2009/04/21 (Jon Leech) - add CGL share group to attribute
- list, expand errors section, rename CL_INVALID_CONTEXT to
- CL_INVALID_GL_CONTEXT_KHR, fix some minor spec language errors.
- Change extension name from use_gl_context to gl_sharing.
-
- Version 5, 2009/04/20 (Jon Leech) - add new functions & tokens to
- the summary section at the top. Add KHR suffix to tokens for
- specifying WGL/GLX/EGL context attributes. No functionality
- changes relative to version 4.
-
- Version 4, 2009/04/13 (Jon Leech) - add error on context creation if
- an unrecognized attribute name is specified. Replace
- clGetCurrentGLDevice with clGetGLContextInfoKHR based on equivalent
- Apple functionality. Update issue 7 and add issues 8/9.
-
- Version 3, 2009/03/24 (Jon Leech) - add error on context creation if
- devices not supporting GL sharing are specified. Resolve issues 3
- and 6 as agreed in discussion last week. Add issue 7 for which
- command queues an Acquire/Release should be placed on and add
- proposed clGetCurrentGLDevice query.
-
- Version 2, 2009/02/17 (Jon Leech) - revise proposal to identify the
- OpenGL context using an explicit handle, rather than using the
- currently bound context. Revised issues 1 and 3 to match, and added
- issue 6 suggesting changes to the "base" GL interop interace in
- Appendix B.
+https://github.com/KhronosGroup/OpenCL-Docs/blob/master/ext/cl_khr_gl_sharing__context.txt
+https://github.com/KhronosGroup/OpenCL-Docs/blob/master/ext/cl_khr_gl_sharing__memobjs.txt
- Version 1, 2009/01/29 (Jon Leech) - initial extension specification
- based on discussion in bug 4340.
diff --git a/extensions/khr/cl_khr_icd.txt b/extensions/khr/cl_khr_icd.txt
index 5ee8cc8..6dda605 100644
--- a/extensions/khr/cl_khr_icd.txt
+++ b/extensions/khr/cl_khr_icd.txt
@@ -1,381 +1,12 @@
-Name Strings
+The normative cl_khr_icd specification is now in the OpenCL
+Extension Specification and is no longer authored in plain
+text.
- cl_khr_icd
+Please refer to the OpenCL Extension Specification on the
+OpenCL Registry:
-Contributors
+https://www.khronos.org/registry/OpenCL/
- Ben Ashbaugh
- Christopher Cameron
- Benedict Gaster
- Michael Houston
- John Kessenich
- Christopher Lamb
- Laurent Morichetti
- Aftab Munshi
- Ofer Rosenberg
+The Asciidoc source for this extension may be found here:
-IP Status
-
- No known claims.
-
-Version
-
- Version 8, August 8, 2017
-
-Number
-
- OpenCL Extension #5
-
-Status
-
- Ratified by the Khronos Promoters, January 29, 2010
-
-Extension Type
-
- OpenCL platform extension
-
-Dependencies
-
- OpenCL 1.0 is required.
-
-Overview
-
- This extension defines a simple mechanism through which the Khronos
- installable client driver loader (ICD Loader) may expose multiple
- separate vendor installable client drivers (Vendor ICDs) for
- OpenCL. An application written against the ICD Loader will be able to
- access all cl_platform_ids exposed by all vendor implementations
- with the ICD Loader acting as a demultiplexor.
-
-Inferring Vendors From Function Calls from Arguments
-
- At every OpenCL function call, the ICD Loader infers the Vendor ICD
- function to call from the arguments to the function. An object is
- said to be ICD compatible if it is of the following structure:
-
- struct _cl_<object>
- {
- struct _cl_icd_dispatch *dispatch;
- // ... remainder of internal data
- };
-
- <object> is one of platform_id, device_id, context, command_queue,
- mem, program, kernel, event, or sampler.
-
- The structure _cl_icd_dispatch is a function pointer dispatch
- table which is used to direct calls to a particular vendor
- implementation. All objects created from ICD compatible objects
- must be ICD compatible.
-
- A link to source code which defines the entries in the function
- table structure _cl_icd_dispatch is available in the Sample
- Code section of this document. The order of the functions in
- _cl_icd_dispatch is determined by the ICD Loader's source. The ICD
- Loader's source's _cl_icd_dispatch table is to be appended to only.
-
- Functions which do not have an argument from which the vendor
- implementation may be inferred are ignored, with the exception
- of clGetExtensionFunctionAddress which is described below.
-
-ICD Data
-
- A Vendor ICD is defined by two pieces of data.
-
- The Vendor ICD library specifies a library which contains the
- OpenCL entrypoints for the vendor's OpenCL implementation. The
- vendor ICD's library file name should include the vendor name, or
- a vendor-specific implementation identifier.
-
- The Vendor ICD extension suffix is a short string which specifies
- the default suffix for extensions implemented only by that vendor.
- See Additions to Chapter 9 for details on the mechanism through
- which this is accomplished. The vendor suffix string is optional.
-
-ICD Loader Vendor Enumeration on Windows
-
- To enumerate Vendor ICDs on Windows, the ICD Loader will first
- scan for REG_SZ string values in the "Display Adapter" and
- "Software Components" HKR registry keys. The exact registry
- keys to scan should be obtained via PnP Configuration Manager
- APIs, but will look like:
-
- For 64-bit ICDs:
-
- HKLM\SYSTEM\CurrentControlSet\Control\Class\
- {Display Adapter GUID}\{Instance ID}\OpenCLDriverName, or
-
- HKLM\SYSTEM\CurrentControlSet\Control\Class\
- {Software Component GUID}\{Instance ID}\OpenCLDriverName
-
- For 32-bit ICDs:
-
- HKLM\SYSTEM\CurrentControlSet\Control\Class\
- {Display Adapter GUID}\{Instance ID}\OpenCLDriverNameWoW, or
-
- HKLM\SYSTEM\CurrentControlSet\Control\Class\
- {Software Component GUID}\{Instance ID}\OpenCLDriverNameWoW
-
- These registry values contain the path to the Vendor ICD library.
- For example, if the registry contains the value:
-
- [HKLM\SYSTEM\CurrentControlSet\Control\Class\{GUID}\{Instance}]
- "OpenCLDriverName"="c:\\vendor a\\vndra_ocl.dll"
-
- Then the ICD loader will open the Vendor ICD library:
-
- "c:\vendor a\vndra_ocl.dll"
-
- The ICD Loader will also scan for REG_DWORD values in the registry
- key:
-
- HKLM\SOFTWARE\Khronos\OpenCL\Vendors
-
- For each registry value in this key which has data set to 0, the
- ICD Loader will open the Vendor ICD library specified by the name
- of the registry value.
-
- For example, if the registry contains the value:
-
- [HKLM\SOFTWARE\Khronos\OpenCL\Vendors]
- "c:\\vendor a\\vndra_ocl.dll"=dword:00000000
-
- Then the ICD will open the Vendor ICD library:
-
- "c:\vendor a\vndra_ocl.dll"
-
-ICD Loader Vendor Enumeration on Linux
-
- To enumerate vendor ICDs on Linux, the ICD Loader scans
- the files the path /etc/OpenCL/vendors. For each
- file in this path, the ICD Loader opens the file as a text
- file. The expected format for the file is a single line of
- text which specifies the Vendor ICD's library. The ICD
- Loader will attempt to open that file as a shared object
- using dlopen(). Note that the library specified may be an
- absolute path or just a file name.
-
- For example, if the following file exists
- /etc/OpenCL/vendors/VendorA.icd
- and contains the text
- libVendorAOpenCL.so
- then the ICD Loader will load the library "libVendorAOpenCL.so"
-
-Adding a Vendor Library
-
- Upon successfully loading a Vendor ICD's library, the
- ICD Loader queries the following functions from the library:
- clIcdGetPlatformIDsKHR, clGetPlatformInfo, and
- clGetExtensionFunctionAddress. If any of these functions
- are not present then the ICD Loader will close and ignore
- the library.
-
- Next the ICD Loader queries available ICD-enabled
- platforms in the library using clIcdGetPlatformIDsKHR.
- For each of these platforms, the ICD Loader queries the
- platform's extension string to verify that cl_khr_icd is
- supported, then queries the platform's Vendor ICD extension
- suffix using clGetPlatformInfo with the value
- CL_PLATFORM_ICD_SUFFIX_KHR.
-
- If any of these steps fail, the ICD Loader will ignore the
- Vendor ICD and continue on to the next.
-
-New Procedures and Functions
-
- cl_int clIcdGetPlatformIDsKHR(
- cl_uint num_entries,
- cl_platform_id *platforms,
- cl_uint *num_platforms);
-
-New Tokens
-
- Accepted as <param_name> to the function clGetPlatformInfo
-
- CL_PLATFORM_ICD_SUFFIX_KHR 0x0920
-
- Returned by clGetPlatformIDs when no platforms are found
-
- CL_PLATFORM_NOT_FOUND_KHR -1001
-
-
-Additions to Chapter 4 of the OpenCL 1.0.48 Specification
-
- In section 4.1, replace the description of the return values of
- clGetPlatformIDs with:
-
- "clGetPlatformIDs returns CL_SUCCESS if the function is executed
- successfully and there are a non zero number of platforms available.
- It returns CL_PLATFORM_NOT_FOUND_KHR if zero platforms are
- available. It returns CL_INVALID_VALUE if <num_entries> is
- equal to zero and <platforms> is not NULL or if both <num_platforms>
- and <platforms> are NULL."
-
- In section 4.1, add the following after the description of
- clGetPlatforms:
-
- "The list of platforms accessible through the Khronos ICD Loader
- can be obtained using the following function
-
- cl_int clIcdGetPlatformIDsKHR(
- cl_uint num_entries,
- cl_platform_id *platforms,
- cl_uint *num_platforms);
-
- <num_entries> is the number of cl_platform_id entries that can be
- added to <platforms>. If <platforms> is not NULL, then
- <num_entries> must be greater than zero.
-
- <platforms> returns a list of OpenCL platforms available for access
- through the Khronos ICD Loader. The cl_platform_id values returned in
- <platform> are ICD compatible and can be used to identify a
- specific OpenCL platform. If the <platforms> argument is NULL,
- then this argument is ignored. The number of OpenCL platforms
- returned is the minimum of the value specified by num_entries or
- the number of OpenCL platforms available.
-
- <num_platforms> returns the number of OpenCL platforms available.
- If <num_platforms> is NULL, then this argument is ignored.
-
- clIcdGetPlatformIDsKHR returns CL_SUCCESS if the function is executed
- successfully and there are a non zero number of platforms available.
- It returns CL_PLATFORM_NOT_FOUND_KHR if zero platforms are
- available. It returns CL_INVALID_VALUE if <num_entries> is
- equal to zero and <platforms> is not NULL or if both <num_platforms>
- and <platforms> are NULL."
-
- Add the following to table 4.1:
-
- "--------------------------------------------------------------------
- cl_platform_info Return Type Description
- ---------------- ----------- ----------------------------
- CL_PLATFORM_ICD_SUFFIX_KHR char[] Then function name suffix
- used to identify extension
- functions to be directed to
- this platform by the ICD
- Loader."
-
-Additions to Chapter 9 of the OpenCL 1.0.48 Specification
-
- Add the following paragraph to the end of Section 9.2:
-
- "For functions supported by the ICD Loader,
- clGetExtensionFunctionAddress will return the function pointer of
- the ICD Loader implementation. For extension functions which the ICD
- Loader is unaware of, the function clGetExtensionFunctionAddress
- will determine the vendor implementation to return based on the
- string passed in. The ICD Loader will return the result from
- querying clGetExtensionFunctionAddress on the vendor ICD enumerated
- by the ICD Loader whose ICD suffix is a suffix of the function name
- being queried. If no such vendor exists or the suffix of the
- function is KHR or EXT then clGetExtensionFunctionAddress will
- return NULL."
-
-Interactions with other extensions
-
- None.
-
-Issues
-
- 1. Some OpenCL functions do not take an object argument from which
- their vendor library may be identified (e.g, clUnloadCompiler),
- how will they be handled?
-
- RESOLVED: Such functions will be a NOOP for all calls through the
- ICD.
-
- 2. How are OpenCL extension to be handled?
-
- RESOLVED: OpenCL extension functions may be added to the ICD as
- soon as they are implemented by any vendor. The suffix mechanism
- provides access for vendor extensions which are not yet added to
- the ICD.
-
- 3: How will the ICD handle a NULL cl_platform_id?
-
- RESOLVED: The NULL platform is not supported by the ICD.
-
- 4. There exists no mechanism to unload the ICD, should there be
- one?
-
- RESOLVED: As there is no standard mechanism for unloading a vendor
- implementation, do not add one for the ICD.
-
-Sample Code
-
- The official source for the ICD loader is available on github, here:
- https://github.com/KhronosGroup/OpenCL-ICD-Loader
-
- An abbreviated version of the _cl_icd_dispatch structure is
- as follows.
-
- struct _cl_icd_dispatch
- {
- CL_API_ENTRY cl_int (CL_API_CALL *clGetPlatformIDs)(
- cl_uint num_entries,
- cl_platform_id * platforms,
- cl_uint * num_platforms) CL_API_SUFFIX__VERSION_1_0;
-
- CL_API_ENTRY cl_int (CL_API_CALL *clGetPlatformInfo)(
- cl_platform_id platform,
- cl_platform_info param_name,
- size_t param_value_size,
- void * param_value,
- size_t * param_value_size_ret) CL_API_SUFFIX__VERSION_1_0;
-
- /* ...continues... */
- }
-
- As an example of this mechanism in action, consider the function
- clCreateCommandQueue. The implementation of this function in the
- ICD Loader is as follows
-
- cl_command_queue clCreateCommandQueue(
- cl_context context,
- cl_device_id device,
- cl_command_queue_properties properties,
- cl_int * errcode_ret)
- {
- return context->dispatch->clCreateCommandQueue(
- context,
- device,
- properties,
- errcode_ret);
- }
-
-Conformance Tests
-
- A vendor supports cl_khr_icd if conformance may be run successfully
- on their platform through the ICD Loader.
-
-Revision History
-
- Version 8, 2017/08/08 (Ben Ashbaugh) - updated to include HKR
- as a scanned registry key for Windows, added github link for ICD
- loader source code.
-
- Version 7, 2010/03/02 (Jon Leech) - fix typos for
- clGetExtensionFunctionAddress (public bug 258), reflow a paragraph
- with very long lines.
-
- Version 6, 2010/02/17 (Jon Leech) - remove URLs pointing to
- resources available only to Khronos members, since this
- was causing confusion to outside readers of the extension
- spec.
-
- Version 5, 2009/12/08 (Christopher Cameron) - Clarify language
- of ICD Loader versus Vendor ICD, update Linux enumeration to
- reflect bug and email discussion.
-
- Version 4, 2009/11/10 (Christopher Cameron) - Fix typos.
-
- Version 3, 2009/11/05 (Christopher Cameron) - update Linux and
- Windows enumeration to use directories and registry values.
- Change suffix information to come from platform query. Add
- error code for clGetPlatformIDs when there are no platforms.
-
- Version 2, 2009/11/02 (Christopher Cameron) - update Linux
- enumeration to use INI file format. Some cleanup of sections.
- Update on ICD unload function.
-
- Version 1, 2009/09/20 (Christopher Cameron) - initial extension
- specification (see also Khronos bug 5391)
+https://github.com/KhronosGroup/OpenCL-Docs/blob/master/ext/cl_khr_icd.txt
\ No newline at end of file
