| 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. |
