| Name String | |
| cl_nv_d3d9_sharing | |
| Version | |
| Version 2, January 6, 2010 | |
| Number | |
| OpenCL Extension #2 | |
| Status | |
| Unknown | |
| Extension Type | |
| OpenCL platform extension | |
| Dependencies | |
| OpenCL 1.0 is required and a Direct3D 9 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 9. This is designed to function analogously to | |
| the OpenGL interoperability as defined in the OpenCL 1.0 | |
| specification and accompanying extensions. | |
| New Procedures and Functions | |
| cl_int clGetDeviceIDsFromD3D9NV( | |
| cl_platform_id platform, | |
| cl_d3d9_device_source_nv d3d_device_source, | |
| void *d3d_object, | |
| cl_d3d9_device_set_nv d3d_device_set, | |
| cl_uint num_entries, | |
| cl_device_id *devices, | |
| cl_uint *num_devices) | |
| cl_mem clCreateFromD3D9VertexBufferNV( | |
| cl_context context, | |
| cl_mem_flags flags, | |
| IDirect3DVertexBuffer9 *resource, | |
| cl_int *errcode_ret) | |
| cl_mem clCreateFromD3D9IndexBufferNV( | |
| cl_context context, | |
| cl_mem_flags flags, | |
| IDirect3DIndexBuffer9 *resource, | |
| cl_int *errcode_ret) | |
| cl_mem clCreateFromD3D9SurfaceNV( | |
| cl_context context, | |
| cl_mem_flags flags, | |
| IDirect3DSurface9 *resource, | |
| cl_int *errcode_ret) | |
| cl_mem clCreateFromD3D9TextureNV( | |
| cl_context context, | |
| cl_mem_flags flags, | |
| IDirect3DTexture9 *resource, | |
| UINT miplevel, | |
| cl_int *errcode_ret) | |
| cl_mem clCreateFromD3D9CubeTextureNV( | |
| cl_context context, | |
| cl_mem_flags flags, | |
| IDirect3DCubeTexture9 *resource, | |
| D3DCUBEMAP_FACES facetype, | |
| UINT miplevel, | |
| cl_int *errcode_ret) | |
| cl_mem clCreateFromD3D9VolumeTextureNV( | |
| cl_context context, | |
| cl_mem_flags flags, | |
| IDirect3DVolumeTexture9 *resource, | |
| UINT miplevel, | |
| cl_int *errcode_ret) | |
| cl_int clEnqueueAcquireD3D9ObjectsNV( | |
| 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 clEnqueueReleaseD3D9ObjectsNV( | |
| 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 9 device source in the <d3d_device_source> | |
| parameter of clGetDeviceIDsFromD3D9NV: | |
| CL_D3D9_DEVICE_NV 0x4022 | |
| CL_D3D9_ADAPTER_NAME_NV 0x4023 | |
| Accepted as a set of Direct3D 9 devices in the <d3d_device_set> parameter | |
| of clGetDeviceIDsFromD3D9NV: | |
| CL_PREFERRED_DEVICES_FOR_D3D9_NV 0x4024 | |
| CL_ALL_DEVICES_FOR_D3D9_NV 0x4025 | |
| Accepted as a property name in the <properties> parameter of | |
| clCreateContext and clCreateContextFromType: | |
| CL_CONTEXT_D3D9_DEVICE_NV 0x4026 | |
| Accepted as the property being queried in the <param_name> | |
| parameter of clGetMemObjectInfo: | |
| CL_MEM_D3D9_RESOURCE_NV 0x4027 | |
| Accepted as the property being queried in the <param_name> | |
| parameter of clGetImageInfo: | |
| CL_IMAGE_D3D9_FACE_NV 0x4028 | |
| CL_IMAGE_D3D9_LEVEL_NV 0x4029 | |
| Returned in the <param_value> parameter of clGetEventInfo when | |
| <param_name> is CL_EVENT_COMMAND_TYPE: | |
| CL_COMMAND_ACQUIRE_D3D9_OBJECTS_NV 0x402A | |
| CL_COMMAND_RELEASE_D3D9_OBJECTS_NV 0x402B | |
| Returned by clCreateContext and clCreateContextFromType if the Direct3D 9 | |
| device specified for interoperability is not compatible with the devices | |
| against which the context is to be created: | |
| CL_INVALID_D3D9_DEVICE_NV -1010 | |
| Returned by clCreateFromD3D9VertexBufferNV, clCreateFromD3D9IndexBufferNV | |
| clCreateFromD3D9SurfaceNV, clCreateFromD3D9TextureNV, | |
| clCreateFromD3D9CubeTextureNV, and clCreateFromD3D9VolumeTextureNV when | |
| <resource> is not a Direct3D 9 resource of the required type: | |
| CL_INVALID_D3D9_RESOURCE_NV -1011 | |
| Returned by clEnqueueAcquireD3D9ObjectsNV when any of <mem_objects> are | |
| currently acquired by OpenCL: | |
| CL_D3D9_RESOURCE_ALREADY_ACQUIRED_NV -1012 | |
| Returned by clEnqueueReleaseD3D9ObjectsNV when any of <mem_objects> are | |
| not currently acquired by OpenCL: | |
| CL_D3D9_RESOURCE_NOT_ACQUIRED_NV -1013 | |
| 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_D3D9_DEVICE_NV IDirect3DDevice9* NULL Specifies the IDirect3DDevice9* | |
| to use for Direct3D 9 | |
| interoperabilty." | |
| --------------------------------------------------------------------------------------" | |
| Add to the list of errors for clCreateContext: | |
| "* CL_INVALID_D3D9_DEVICE_NV if the value of the property | |
| CL_CONTEXT_D3D9_DEVICE_NV is non-NULL and does not specify a valid | |
| Direct3D 9 device with which the cl_device_ids against which this context | |
| is to be created may interoperate. | |
| * CL_INVALID_OPERATION if Direct3D 9 interoperability is specified by | |
| setting CL_INVALID_D3D9_DEVICE_NV 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. | |
| 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_D3D9_RESOURCE_NV if <param_name> is CL_MEM_D3D9_RESOURCE_NV | |
| and <memobj> was not created from a Direct3D 9 resource." | |
| Extend table 5.8 to include the following entry. | |
| ----------------------------------------------------------------------- | |
| cl_mem_info Return type Info. returned in param_value | |
| ----------- --------------- ----------------------------- | |
| CL_MEM_D3D9_RESOURCE_NV IDirect3DResource9* | |
| If <memobj> was created from a | |
| Direct3D 9 resource using | |
| clCreateFromD3D9VertexBufferNV, | |
| clCreateFromD3D9IndexBufferNV, | |
| clCreateFromD3D9SurfaceNV, | |
| clCreateFromD3D9TextureNV, | |
| clCreateFromD3D9CubeTextureNV, or | |
| clCreateFromD3D9VolumeTextureNV, | |
| 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_D3D9_RESOURCE_NV if <param_name> is CL_MEM_D3D9_LEVEL_NV | |
| and <image> was not created from a Direct3D 9 resource using | |
| clCreateFromD3D9TextureNV, clCreateFromD3D9CubeTextureNV, or | |
| clCreateFromD3D9VolumeTextureNV or if <param_name> is | |
| CL_MEM_D3D9_FACE_NV and <image> was not created from a Direct3D 9 | |
| resource using clCreateFromD3D9CubeTextureNV." | |
| Extend table 5.9 to include the following entry. | |
| ----------------------------------------------------------------------- | |
| cl_image_info Return type Info. returned in param_value | |
| ------------- ----------- ----------------------------- | |
| CL_IMAGE_D3D9_LEVEL_NV UINT If <image> was created using | |
| clCreateFromD3D9TextureNV, | |
| clCreateFromD3D9CubeTextureNV, or | |
| clCreateFromD3D9VolumeTextureNV, | |
| returns the <miplevel> argument | |
| specified when <image> was | |
| created. | |
| CL_IMAGE_D3D9_FACE_NV D3DCUBEMAP_FACES If <image> was created using | |
| clCreateFromD3D9CubeTextureNV, | |
| returns the <facetype> 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_D3D9_OBJECTS_NV | |
| CL_COMMAND_RELEASE_D3D9_OBJECTS_NV | |
| Add new section 9.13 | |
| 9.13 Sharing Memory Objects with Direct3D 9 Resources | |
| This section discusses OpenCL functions that allow applications to use | |
| Direct3D 9 resources as OpenCL memory objects. This allows efficient | |
| sharing of data between OpenCL and Direct3D 9. The OpenCL API may be | |
| used to execute kernels that read and/or write memory objects that are | |
| also Direct3D 9 resources. An OpenCL image object may be created from | |
| a Direct3D 9 texture or surface resource. An OpenCL buffer object may | |
| be created from a Direct3D 9 buffer resource. OpenCL memory objects | |
| may be created from Direct3D 9 objects if and only if the OpenCL context | |
| has been created from a Direct3D 9 device. | |
| 9.13.1 Querying OpenCL Devices Corresponding to Direct3D 9 Devices | |
| The OpenCL devices corresponding to a Direct3D 9 device may be queried. | |
| The OpenCL devices corresponding to an adapter name may also be | |
| queried. The OpenCL devices corresponding to a Direct3D 9 device will | |
| be a subset of the OpenCL devices corresponding to the adapter | |
| against which the Direct3D 9 device was created. | |
| The OpenCL devices corresponding to a Direct3D 9 device or adapter | |
| name may be queried using the function | |
| cl_int clGetDeviceIDsFromD3D9NV( | |
| cl_platform_id platform, | |
| cl_d3d9_device_source_nv d3d_device_source, | |
| void *d3d_object, | |
| cl_d3d9_device_set_nv 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. | |
| clGetDeviceIDsFromD3D9NV 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_d3d9_device_source_nv Type of <d3d_object> | |
| ------------------------ -------------------- | |
| CL_D3D9_DEVICE_NV IDirect3DDevice9 * | |
| CL_D3D9_ADAPTER_NAME_NV char[] | |
| -------------------------------------------------------------------- | |
| Table 9.13.1.1: Types used to specify the object whose corresponding | |
| OpenCL devices are being queried by clGetDeviceIDsFromD3D9NV. | |
| -------------------------------------------------------------------- | |
| cl_d3d9_device_set_nv Devices returned in <devices> | |
| ------------------------ ----------------------------- | |
| CL_PREFERRED_DEVICES_FOR_D3D9_NV The OpenCL devices associated with | |
| the specified Direct3D object. | |
| CL_ALL_DEVICES_FOR_D3D9_NV 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 | |
| clGetDeviceIDsFromD3D9NV. | |
| 9.13.2 Lifetime of Shared Resources | |
| An OpenCL memory object created from a Direct3D 9 resource remains | |
| valid as long as the corresponding Direct3D 9 resource has not been | |
| deleted. If the Direct3D 9 resource is deleted through the Direct3D | |
| 9 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 9 device | |
| specified via the context create parameter CL_CONTEXT_D3D9_DEVICE_NV | |
| will increment the internal Direct3D reference count on the specified | |
| Direct3D 9 device. The internal Direct3D reference count on that | |
| Direct3D 9 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 9 device from which the OpenCL context | |
| was created. If the Direct3D 9 device is deleted through the Direct3D 9 | |
| 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 9 Buffer Resources as OpenCL Buffer Objects | |
| The function | |
| cl_mem clCreateFromD3D9VertexBufferNV( | |
| cl_context context, | |
| cl_mem_flags flags, | |
| IDirect3DVertexBuffer9 *resource, | |
| cl_int *errcode_ret) | |
| creates an OpenCL buffer object from a Direct3D 9 vertex buffer. | |
| <context> is a valid OpenCL context created from a Direct3D 9 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 9 vertex buffer to share. | |
| <errcode_ret> will return an appropriate error code. If | |
| <errcode_ret> is NULL, no error code is returned. | |
| clCreateFromD3D9VertexBufferNV 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_D3D9_RESOURCE_NV if <resource> is not a Direct3D 9 | |
| vertex buffer created in D3DPOOL_DEFAULT, if a cl_mem from | |
| <resource> has already been created, or if <context> was not | |
| created against the same Direct3D 9 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. | |
| The function | |
| cl_mem clCreateFromD3D9IndexBufferNV( | |
| cl_context context, | |
| cl_mem_flags flags, | |
| IDirect3DIndexBuffer9 *resource, | |
| cl_int *errcode_ret) | |
| creates an OpenCL buffer object from a Direct3D 9 index buffer. | |
| <context> is a valid OpenCL context created from a Direct3D 9 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 9 index buffer to share. | |
| <errcode_ret> will return an appropriate error code. If | |
| <errcode_ret> is NULL, no error code is returned. | |
| clCreateFromD3D9IndexBufferNV 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_D3D9_RESOURCE_NV if <resource> is not a Direct3D 9 | |
| index buffer created in D3DPOOL_DEFAULT, if a cl_mem from | |
| <resource> has already been created, or if <context> was not | |
| created against the same Direct3D 9 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 9 Texture and Surface Resources as OpenCL | |
| Image Objects | |
| The function | |
| cl_mem clCreateFromD3D9SurfaceNV( | |
| cl_context context, | |
| cl_mem_flags flags, | |
| IDirect3DSurface9 *resource, | |
| cl_int *errcode_ret) | |
| creates an OpenCL 2D image object from a Direct3D 9 surface. | |
| <context> is a valid OpenCL context created from a Direct3D 9 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 9 surface to share. This | |
| surface must be a stand-alone surface which exports the interface | |
| IDirect3DResource9, and not a level of an IDirect3DTexture9 or a | |
| face of a level of an IDirect3DCubeTexture9. | |
| <errcode_ret> will return an appropriate error code. If | |
| <errcode_ret> is NULL, no error code is returned. | |
| clCreateFromD3D9SurfaceNV returns a valid non-zero OpenCL 2D image | |
| object and <errcode_ret> is set to CL_SUCCESS if the OpenCL 2D 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. | |
| * CL_INVALID_D3D9_RESOURCE_NV if <resource> is not a Direct3D 9 | |
| surface created in D3DPOOL_DEFAULT, if a cl_mem from | |
| <resource> has already been created, or if <context> was not | |
| created against the same Direct3D 9 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 <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 clCreateFromD3D9TextureNV( | |
| cl_context context, | |
| cl_mem_flags flags, | |
| IDirect3DTexture9 *resource, | |
| UINT miplevel, | |
| cl_int *errcode_ret) | |
| creates an OpenCL 2D image object from a level of a Direct3D 9 texture. | |
| <context> is a valid OpenCL context created from a Direct3D 9 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 9 texture to share. | |
| <miplevel> is the mipmap level of <resource> to share. | |
| <errcode_ret> will return an appropriate error code. If | |
| <errcode_ret> is NULL, no error code is returned. | |
| clCreateFromD3D9TextureNV returns a valid non-zero OpenCL 2D image | |
| object and <errcode_ret> is set to CL_SUCCESS if the OpenCL 2D 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 <miplevel> is not a valid mipmap level of <resource>. | |
| * CL_INVALID_D3D9_RESOURCE_NV if <resource> is not a Direct3D 9 | |
| texture created in D3DPOOL_DEFAULT, if a cl_mem from | |
| mipmap level <miplevel> of <resource> has already been created, | |
| or if <context> was not created against the same Direct3D 9 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 mipmap level <miplevel> 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 clCreateFromD3D9CubeTextureNV( | |
| cl_context context, | |
| cl_mem_flags flags, | |
| IDirect3DCubeTexture9 *resource, | |
| D3DCUBEMAP_FACES facetype, | |
| UINT miplevel, | |
| cl_int *errcode_ret) | |
| creates an OpenCL 2D image object from a face of a level of a | |
| Direct3D 9 cube texture. | |
| <context> is a valid OpenCL context created from a Direct3D 9 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 9 cube texture to share. | |
| <facetype> is the face of <resource> to share. | |
| <miplevel> is the mipmap level of <resource> to share. | |
| <errcode_ret> will return an appropriate error code. If | |
| <errcode_ret> is NULL, no error code is returned. | |
| clCreateFromD3D9CubeTextureNV returns a valid non-zero OpenCL 2D image | |
| object and <errcode_ret> is set to CL_SUCCESS if the OpenCL 2D 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, | |
| if <miplevel> is not a valid mipmap level of <resource>, or if | |
| <facetype> is not a valid cube face. | |
| * CL_INVALID_D3D9_RESOURCE_NV if <resource> is not a Direct3D 9 | |
| cube texture created in D3DPOOL_DEFAULT, if a cl_mem from | |
| cube face <facetype> and mipmap level <miplevel> of <resource> | |
| has already been created, or if <context> was not created against | |
| the same Direct3D 9 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 mipmap level <miplevel> 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 clCreateFromD3D9VolumeTextureNV( | |
| cl_context context, | |
| cl_mem_flags flags, | |
| IDirect3DVolumeTexture9 *resource, | |
| UINT miplevel, | |
| cl_int *errcode_ret) | |
| creates an OpenCL 3D image object from a face of a level of a | |
| Direct3D 9 volume texture. | |
| <context> is a valid OpenCL context created from a Direct3D 9 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 9 volume texture to share. | |
| <miplevel> is the mipmap level of <resource> to share. | |
| <errcode_ret> will return an appropriate error code. If | |
| <errcode_ret> is NULL, no error code is returned. | |
| clCreateFromD3D9VolumeTextureNV returns a valid non-zero OpenCL 3D | |
| image object and <errcode_ret> is set to CL_SUCCESS if the OpenCL | |
| 3D 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 <miplevel> is not a valid mipmap level of <resource>. | |
| * CL_INVALID_D3D9_RESOURCE_NV if <resource> is not a Direct3D 9 | |
| volume texture created in D3DPOOL_DEFAULT, if a cl_mem from | |
| mipmap level <miplevel> of <resource> has already been created, | |
| or if <context> was not created against the same Direct3D 9 | |
| 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 returned OpenCL 3D image object are | |
| determined by the width, height, and depth of mipmap level <miplevel> 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. | |
| ------------------------------------------------------------------ | |
| D3D Format cl_channel_order cl_channel_type | |
| ------------------------------ ---------------- --------------- | |
| D3DFMT_R32F CL_R CL_FLOAT | |
| D3DFMT_R16F CL_R CL_HALF_FLOAT | |
| D3DFMT_L16 CL_R CL_UNORM_INT16 | |
| D3DFMT_A8 CL_R CL_UNORM_INT8 | |
| D3DFMT_L8 CL_R CL_UNORM_INT8 | |
| D3DFMT_G32R32F CL_RG CL_FLOAT | |
| D3DFMT_G16R16F CL_RG CL_HALF_FLOAT | |
| D3DFMT_G16R16 CL_RG CL_UNORM_INT16 | |
| D3DFMT_V16U16 CL_RG CL_SNORM_INT16 | |
| D3DFMT_A8L8 CL_RG CL_UNORM_INT8 | |
| D3DFMT_V8U8 CL_RG CL_SNORM_INT8 | |
| D3DFMT_A32B32G32R32F CL_RGBA CL_FLOAT | |
| D3DFMT_A16B16G16R16F CL_RGBA CL_HALF_FLOAT | |
| D3DFMT_A16B16G16R16 CL_RGBA CL_UNORM_INT16 | |
| D3DFMT_Q16W16V16U16 CL_RGBA CL_SNORM_INT16 | |
| D3DFMT_A8B8G8R8 CL_RGBA CL_UNORM_INT8 | |
| D3DFMT_X8B8G8R8 CL_RGBA CL_UNORM_INT8 | |
| D3DFMT_A8R8G8B8 CL_RGBA CL_UNORM_INT8 | |
| D3DFMT_X8R8G8B8 CL_RGBA CL_UNORM_INT8 | |
| D3DFMT_Q8W8V8U8 CL_RGBA CL_SNORM_INT8 | |
| ------------------------------------------------------------------ | |
| Table 9.13.4.1: List of Direct3D 9 and corresponding OpenCL Image | |
| Formats. | |
| Note that the channel order is literal and makes no effort to swizzle | |
| the channels so that the OpenCL channel order matches the Direct3D 9 | |
| channel order. For example, for a texture of format | |
| D3DFMT_A32B32G32R32F, the OpenCL red component will correspond to the | |
| Direct3D alpha component, the OpenCL green component will correspond | |
| to the Direct3D blue component, and so on. | |
| 9.13.5 Querying Direct3D properties of memory objects created from | |
| Direct3D 9 resources. | |
| Properties of Direct3D 9 objects may be queried using clGetMemObjectInfo | |
| and clGetImageInfo with <param_name> CL_MEM_D3D9_RESOURCE_NV, | |
| CL_IMAGE_D3D9_LEVEL_NV, and CL_IMAGE_D3D9_FACE_NV as described in | |
| section 5.2.9. | |
| 9.13.6 Sharing memory objects created from Direct3D 9 resources between | |
| Direct3D 9 and OpenCL contexts | |
| The function | |
| cl_int clEnqueueAcquireD3D9ObjectsNV( | |
| 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 9 resources. The Direct3D 9 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 9 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 9 | |
| resource is used while it is not currently acquired by OpenCL, the call | |
| attempting to use that OpenCL memory object will return | |
| CL_D3D9_RESOURCE_NOT_ACQUIRED_NV. | |
| clEnqueueAcquireD3D9ObjectsNV provides the synchronization guarantee | |
| that any Direct3D 9 calls made before clEnqueueAcquireD3D9ObjectsNV 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 9 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. | |
| clEnqueueAcquireD3D9ObjectsNV 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 9 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 9 device. | |
| * CL_D3D9_RESOURCE_ALREADY_ACQUIRED_NV if memory objects in | |
| <mem_objects> have previously been acquired using | |
| clEnqueueAcquireD3D9ObjectsNV but have not been released | |
| using clEnqueueReleaseD3D9ObjectsNV. | |
| * 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 clEnqueueReleaseD3D9ObjectsNV( | |
| 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 9 resources. The Direct3D 9 objects are released by the | |
| OpenCL context associated with <command_queue>. | |
| OpenCL memory objects created from Direct3D 9 resources which have | |
| been acquired by OpenCL must be released by OpenCL before they may be | |
| accessed by Direct3D 9. Accessing a Direct3D 9 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. | |
| clEnqueueReleaseD3D9ObjectsNV provides the synchronization guarantee | |
| that any calls to Direct3D 9 made after the call to | |
| clEnqueueReleaseD3D9ObjectsNV 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 9 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. | |
| clEnqueueReleaseExternalObjectsNV 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 9 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 9 device. | |
| * CL_D3D9_RESOURCE_NOT_ACQUIRED_NV if memory objects in | |
| <mem_objects> have not previously | |
| clEnqueueAcquireD3D9ObjectsNV, or have been released using | |
| clEnqueueReleaseD3D9ObjectsNV 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. | |
| Revision History | |
| Version 2, 2010/01/06 (Jon Leech) - add missing extension template | |
| fields and publish in the Khronos Registry. | |
| Version 1, 2009/12/07 - branched from draft of cl_nv_d3d10_sharing. |