Name String

    cl_nv_d3d9_sharing

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 1, 2009/12/07 - branched from draft of cl_nv_d3d10_sharing.
