| Name String |
| |
| cl_intel_dx9_media_sharing |
| |
| Contributors |
| |
| Ben Asbaugh, Intel |
| |
| Contact |
| |
| Ben Asbaugh, Intel (ben.ashbaugh 'at' intel.com) |
| |
| IP Status |
| |
| TBD |
| |
| Version |
| |
| Version 6, October 18, 2011 |
| |
| Number |
| |
| OpenCL Extension #14 |
| |
| Status |
| |
| Final Draft |
| |
| Extension Type |
| |
| OpenCL platform extension |
| |
| Dependencies |
| |
| OpenCL 1.0 is required and a DirectX 9 implementation supporting |
| sharing of surfaces with OpenCL is required. This extension is written |
| against revision 48 of the OpenCL 1.0 specification. |
| |
| This extension is modified by cl_intel_packed_yuv. |
| |
| Overview |
| |
| The goal of this extension is to provide interoperability between |
| OpenCL and DirectX 9, specifically DirectX 9 media surfaces. 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 clGetDeviceIDsFromDX9INTEL( |
| cl_platform_id platform, |
| cl_dx9_device_source_intel dx9_device_source, |
| void *dx9_object, |
| cl_dx9_device_set_intel dx9_device_set, |
| cl_uint num_entries, |
| cl_device_id *devices, |
| cl_uint *num_devices) |
| |
| cl_mem clCreateFromDX9MediaSurfaceINTEL( |
| cl_context context, |
| cl_mem_flags flags, |
| IDirect3DSurface9 *resource, |
| HANDLE shared_handle, |
| UINT plane, |
| cl_int *errcode_ret) |
| |
| cl_int clEnqueueAcquireDX9ObjectsINTEL( |
| 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 clEnqueueReleaseDX9ObjectsINTEL( |
| 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 DirectX 9 device source in the <dx9_device_source> |
| parameter of clGetDeviceIDsFromDX9INTEL: |
| |
| CL_D3D9_DEVICE_INTEL 0x4022 |
| CL_D3D9EX_DEVICE_INTEL 0x4070 |
| CL_DXVA_DEVICE_INTEL 0x4071 |
| |
| Accepted as a set of DirectX 9 devices in the <dx9_device_set> parameter |
| of clGetDeviceIDsFromDX9INTEL: |
| |
| CL_PREFERRED_DEVICES_FOR_DX9_INTEL 0x4024 |
| CL_ALL_DEVICES_FOR_DX9_INTEL 0x4025 |
| |
| Accepted as a property name in the <properties> parameter of |
| clCreateContext and clCreateContextFromType: |
| |
| CL_CONTEXT_D3D9_DEVICE_INTEL 0x4026 |
| CL_CONTEXT_D3D9EX_DEVICE_INTEL 0x4072 |
| CL_CONTEXT_DXVA_DEVICE_INTEL 0x4073 |
| |
| Accepted as the property being queried in the <param_name> |
| parameter of clGetMemObjectInfo: |
| |
| CL_MEM_DX9_RESOURCE_INTEL 0x4027 |
| CL_MEM_DX9_SHARED_HANDLE_INTEL 0x4074 |
| |
| Accepted as the property being queried in the <param_name> |
| parameter of clGetImageInfo: |
| |
| CL_IMAGE_DX9_PLANE_INTEL 0x4075 |
| |
| Returned in the <param_value> parameter of clGetEventInfo when |
| <param_name> is CL_EVENT_COMMAND_TYPE: |
| |
| CL_COMMAND_ACQUIRE_DX9_OBJECTS_INTEL 0x402A |
| CL_COMMAND_RELEASE_DX9_OBJECTS_INTEL 0x402B |
| |
| Returned by clCreateContext and clCreateContextFromType if the DirectX 9 |
| device specified for interoperability is not compatible with the devices |
| against which the context is to be created: |
| |
| CL_INVALID_DX9_DEVICE_INTEL -1010 |
| |
| Returned by clCreateFromDX9MediaSurfaceINTEL when <resource> is not a DirectX |
| 9 resource of the required type, by clGetMemObjectInfo when <param_name> |
| is CL_MEM_DX9_RESOURCE_INTEL or CL_MEM_DX9_SHARED_HANDLE_INTEL when <memobj> |
| was not created from a DirectX 9 resource, and from clGetImageInfo when |
| <param_name> is CL_IMAGE_DX9_PLANE_INTEL and <image> was not created from |
| a DirectX 9 resource: |
| |
| CL_INVALID_DX9_RESOURCE_INTEL -1011 |
| |
| Returned by clEnqueueAcquireDX9ObjectsINTEL when any of <mem_objects> are |
| currently acquired by OpenCL: |
| |
| CL_DX9_RESOURCE_ALREADY_ACQUIRED_INTEL -1012 |
| |
| Returned by clEnqueueReleaseDX9ObjectsINTEL when any of <mem_objects> are |
| not currently acquired by OpenCL: |
| |
| CL_DX9_RESOURCE_NOT_ACQUIRED_INTEL -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 which to create the OpenCL |
| context. |
| |
| CL_CONTEXT_D3D9_DEVICE_INTEL IDirect3DDevice9* NULL Specifies an |
| IDirect3DDevice9* |
| to use for DirectX 9 |
| interoperabilty." |
| |
| CL_CONTEXT_D3D9EX_DEVICE_INTEL IDirect3DDevice9Ex* NULL Specifies an |
| IDirect3DDevice9Ex* |
| to use for DirectX 9 |
| interoperabilty." |
| |
| CL_CONTEXT_DXVA_DEVICE_INTEL IDXVAHD_Device* NULL Specifies an |
| IDXVAHD_Device* |
| to use for DirectX 9 |
| interoperabilty." |
| --------------------------------------------------------------------------------------" |
| |
| Add to the list of errors for clCreateContext: |
| |
| "* CL_INVALID_DX9_DEVICE_INTEL if any of the values of the properties |
| CL_CONTEXT_D3D9_DEVICE_INTEL, CL_CONTEXT_D3D9EX_DEVICE_INTEL, or |
| CL_CONTEXT_DXVA_DEVICE_INTEL are non-NULL and do not specify a valid |
| DirectX 9 device with which the cl_device_ids against which this context |
| is to be created may interoperate. |
| |
| * CL_INVALID_OPERATION if DirectX 9 interoperability is specified by |
| setting CL_CONTEXT_D3D9_DEVICE_INTEL, CL_CONTEXT_D3D9EX_DEVICE_INTEL, or |
| CL_CONTEXT_DXVA_DEVICE_INTEL to a non-NULL value, and interoperability |
| with any other 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_DX9_RESOURCE_INTEL if <param_name> is CL_MEM_DX9_RESOURCE_INTEL |
| or CL_MEM_DX9_SHARED_HANDLE_INTEL and <memobj> was not created from a |
| DirectX 9 resource using clCreateFromDX9MediaSurfaceIntel." |
| |
| Extend table 5.8 to include the following entries: |
| |
| ------------------------------------------------------------------------------ |
| cl_mem_info Return type Info. returned in param_value |
| ----------- --------------- ----------------------------- |
| CL_MEM_DX9_RESOURCE_INTEL IDirect3DResource9* If <memobj> was created from a |
| DirectX 9 resource using |
| clCreateFromDX9MediaSurfaceINTEL, |
| returns the <resource> argument |
| specified when <memobj> was |
| created. |
| |
| CL_MEM_DX9_SHARED_HANDLE_INTEL HANDLE If <memobj> was created from a |
| DirectX 9 resource using |
| clCreateFromDX9MediaSurfaceINTEL, |
| returns the <shared_handle> |
| 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_DX9_RESOURCE_INTEL if <param_name> is CL_IMAGE_DX9_PLANE_INTEL |
| and <image> was not created from a DirectX 9 resource using |
| clCreateFromDX9MediaSurfaceINTEL." |
| |
| Extend table 5.9 to include the following entry: |
| |
| ----------------------------------------------------------------------- |
| cl_image_info Return type Info. returned in param_value |
| ------------- ----------- ----------------------------- |
| CL_IMAGE_DX9_PLANE_INTEL UINT If <image> was created using |
| clCreateFromDX9MediaSurfaceINTEL, |
| returns the <plane> 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_DX9_OBJECTS_INTEL |
| CL_COMMAND_RELEASE_DX9_OBJECTS_INTEL |
| |
| Add new section 9.13 |
| |
| 9.13 Sharing Memory Objects with DirectX 9 Media Resources |
| |
| This section discusses OpenCL functions that allow applications to use |
| DirectX 9 media resources as OpenCL memory objects. This allows efficient |
| sharing of data between OpenCL and DirectX 9. The OpenCL API may be |
| used to execute kernels that read and/or write memory objects that are |
| also DirectX 9 resources. An OpenCL image object may be created from |
| a DirectX 9 media surface resource. OpenCL memory objects may be created |
| from DirectX 9 objects if and only if the OpenCL context has been created |
| from a DirectX 9 device. |
| |
| 9.13.1 Querying OpenCL Devices Corresponding to DirectX 9 Devices |
| |
| The OpenCL devices corresponding to a DirectX 9 device may be queried. |
| The OpenCL devices corresponding to a DirectX 9 device will be a subset |
| of the OpenCL devices corresponding to the adapter against which the |
| DirectX 9 device was created. |
| |
| The OpenCL devices corresponding to a DirectX 9 device may be queried |
| using the function |
| |
| cl_int clGetDeviceIDsFromDX9INTEL( |
| cl_platform_id platform, |
| cl_dx9_device_source_intel dx9_device_source, |
| void *dx9_object, |
| cl_dx9_device_set_intel dx9_device_set, |
| cl_uint num_entries, |
| cl_device_id *devices, |
| cl_uint *num_devices) |
| |
| <platform> refers to the platform ID returned by clGetPlatformIDs. |
| |
| <dx9_device_source> specifies the type of <dx9_object>, and must be |
| one of the values shown in table 9.13.1.1. |
| |
| <dx9_object> specifies the object whose corresponding OpenCL devices |
| are being queried. The type of <dx9_object> must be as specified in |
| table 9.13.1.1. |
| |
| <dx9_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 minimum of the value specified by |
| <num_entries> and the number of OpenCL devices corresponding to |
| <dx9_object>. |
| |
| <num_devices> returns the number of OpenCL devices available that |
| correspond to <dx9_object>. If <num_devices> is NULL, this argument |
| is ignored. |
| |
| clGetDeviceIDsFromDX9INTEL 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 <dx9_device_source> is not a valid value, |
| <dx9_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 |
| <dx9_object> were found. |
| |
| -------------------------------------------------------------------- |
| cl_dx9_device_source_intel Type of <dx9_object> |
| --------------------------- -------------------- |
| CL_D3D9_DEVICE_INTEL IDirect3DDevice9 * |
| |
| CL_D3D9EX_DEVICE_INTEL IDirect3DDevice9Ex * |
| |
| CL_DXVA_DEVICE_INTEL IDXVAHD_Device * |
| -------------------------------------------------------------------- |
| Table 9.13.1.1: Types used to specify the object whose corresponding |
| OpenCL devices are being queried by clGetDeviceIDsFromDX9INTEL. |
| |
| -------------------------------------------------------------------- |
| cl_dx9_device_set_intel Devices returned in <devices> |
| ------------------------ ----------------------------- |
| CL_PREFERRED_DEVICES_FOR_DX9_INTEL The OpenCL devices associated with |
| the specified DirectX 9 object. |
| |
| CL_ALL_DEVICES_FOR_DX9_INTEL All OpenCL devices which may |
| interoperate with the specified |
| DirectX 9 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 |
| clGetDeviceIDsFromDX9INTEL. |
| |
| 9.13.2 Lifetime of Shared Resources |
| |
| An OpenCL memory object created from a DirectX 9 resource remains |
| valid as long as the corresponding DirectX 9 resource has not been |
| deleted. If the DirectX 9 resource is deleted through the DirectX |
| 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 DirectX 9 device |
| specified via the context create parameter CL_CONTEXT_D3D9_DEVICE_INTEL, |
| CL_CONTEXT_D3D9EX_DEVICE_INTEL, or CL_CONTEXT_DXVA_DEVICE_INTEL will |
| increment the internal DirectX reference count on the specified DirectX 9 |
| device. The internal DirectX reference count on that DirectX 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 DirectX 9 device from which the OpenCL context |
| was created. If the DirectX 9 device is deleted through the DirectX 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.4 Sharing DirectX 9 Media Surface Resources as OpenCL Image Objects |
| |
| The function |
| |
| cl_mem clCreateFromDX9MediaSurfaceINTEL( |
| cl_context context, |
| cl_mem_flags flags, |
| IDirect3DSurface9 *resource, |
| HANDLE shared_handle, |
| UINT plane, |
| cl_int *errcode_ret) |
| |
| creates an OpenCL 2D image object from a DirectX 9 media surface or a |
| plane of a DirectX 9 media surface. |
| |
| <context> is a valid OpenCL context created from a DirectX 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 DirectX 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. |
| |
| <shared_handle> is the shared handle of the <resource> used to share |
| the surface between devices. If the <shared_handle> is NULL, the |
| <resource> is still valid but there may be a performance improvement |
| by providing a <shared_handle>. |
| |
| <plane> is the plane of <resource> to share, for planar surface |
| formats. |
| |
| <errcode_ret> will return an appropriate error code. If |
| <errcode_ret> is NULL, no error code is returned. |
| |
| clCreateFromDX9MediaSurfaceINTEL 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 <plane> is not a valid plane of <resource>. |
| |
| * CL_INVALID_DX9_RESOURCE_INTEL if <resource> is not a DirectX 9 |
| surface created in D3DPOOL_DEFAULT, if a cl_mem from |
| <resource> and <plane> has already been created, or if <context> |
| was not created against the same DirectX 9 device from which |
| <resource> was created. |
| |
| * CL_INVALID_IMAGE_FORMAT_DESCRIPTOR if the DirectX 9 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 the <plane> of <resource>. The |
| channel type and order of the returned OpenCL 2D image object is |
| determined by the format and <plane> of <resource> by table 9.13.4.1. |
| |
| This call will increment the internal DirectX reference count on |
| <resource>. The internal DirectX reference count on <resource> |
| will be decremented when the OpenCL reference count on the returned |
| OpenCL memory object drops to zero. |
| |
| ------------------------------------------------------------------ |
| DirectX 9 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_A 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_A8L8 CL_RG CL_UNORM_INT8 |
| |
| D3DFMT_A32B32G32R32F CL_RGBA CL_FLOAT |
| D3DFMT_A16B16G16R16F CL_RGBA CL_HALF_FLOAT |
| D3DFMT_A16B16G16R16 CL_RGBA CL_UNORM_INT16 |
| D3DFMT_A8B8G8R8 CL_RGBA CL_UNORM_INT8 |
| D3DFMT_X8B8G8R8 CL_RGBA CL_UNORM_INT8 |
| D3DFMT_A8R8G8B8 CL_BGRA CL_UNORM_INT8 |
| D3DFMT_X8R8G8B8 CL_BGRA CL_UNORM_INT8 |
| |
| MAKEFOURCC(?N?,?V?,?1?,?2?),Plane0 CL_R CL_UNORM_INT8 |
| MAKEFOURCC(?N?,?V?,?1?,?2?),Plane1 CL_RG CL_UNORM_INT8 |
| |
| MAKEFOURCC(?Y?,?V?,?1?,?2?),Plane0 CL_R CL_UNORM_INT8 |
| MAKEFOURCC(?Y?,?V?,?1?,?2?),Plane1 CL_R CL_UNORM_INT8 |
| MAKEFOURCC(?Y?,?V?,?1?,?2?),Plane2 CL_R CL_UNORM_INT8 |
| ------------------------------------------------------------------ |
| Table 9.13.4.1: List of DirectX 9 and corresponding OpenCL Image |
| Formats. |
| |
| For the NV12 surface format, plane 0 corresponds to the Y channel |
| data and plane 1 corresponds to the UV channel data. For the YV12 |
| surface format, plane 0 corresponds to the Y channel data, plane 1 |
| corresponds to the V channel data, and plane 2 corresponds to the |
| U channel data. |
| |
| 9.13.5 Querying properties of memory objects created from |
| DirectX 9 resources. |
| |
| Properties of media objects created from DirectX 9 resources may be queried |
| using clGetMemObjectInfo and clGetImageInfo with <param_name> |
| CL_MEM_DX9_RESOURCE_INTEL, CL_MEM_DX9_SHARED_HANDLE_INTEL, and |
| CL_IMAGE_DX9_PLANE_INTEL as described in section 5.2.9. |
| |
| 9.13.6 Sharing memory objects created from DirectX 9 resources between |
| DirectX 9 and OpenCL contexts |
| |
| The function |
| |
| cl_int clEnqueueAcquireDX9ObjectsINTEL( |
| 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 |
| DirectX 9 resources. The DirectX 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 DirectX 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 DirectX 9 |
| resource is used while it is not currently acquired by OpenCL, the call |
| attempting to use that OpenCL memory object will return |
| CL_DX9_RESOURCE_NOT_ACQUIRED_INTEL. |
| |
| clEnqueueAcquireDX9ObjectsINTEL provides the synchronization guarantee |
| that any DirectX 9 calls made before clEnqueueAcquireDX9ObjectsINTEL 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 DirectX 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. |
| |
| clEnqueueAcquireDX9ObjectsINTEL 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 DirectX 9 resources. |
| |
| * CL_INVALID_COMMAND_QUEUE if <command_queue> is not a valid |
| command-queue. |
| |
| * CL_INVALID_CONTEXT if the context associated with <command_queue> |
| was not created from a DirectX 9 device. |
| |
| * CL_DX9_RESOURCE_ALREADY_ACQUIRED_INTEL if memory objects in |
| <mem_objects> have previously been acquired using |
| clEnqueueAcquireDX9ObjectsINTEL but have not been released |
| using clEnqueueReleaseDX9ObjectsINTEL. |
| |
| * 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 clEnqueueReleaseDX9ObjectsINTEL( |
| 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 |
| DirectX 9 resources. The DirectX 9 objects are released by the |
| OpenCL context associated with <command_queue>. |
| |
| OpenCL memory objects created from DirectX 9 resources which have |
| been acquired by OpenCL must be released by OpenCL before they may be |
| accessed by DirectX 9. Accessing a DirectX 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. |
| |
| clEnqueueReleaseDX9ObjectsINTEL provides the synchronization guarantee |
| that any calls to DirectX 9 made after the call to |
| clEnqueueReleaseDX9ObjectsINTEL 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 DirectX 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. |
| |
| clEnqueueReleaseDX9ObjectsINTEL 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 DirectX 9 resources. |
| |
| * CL_INVALID_COMMAND_QUEUE if <command_queue> is not a valid |
| command-queue. |
| |
| * CL_INVALID_CONTEXT if the context associated with <command_queue> |
| was not created from a DirectX 9 device. |
| |
| * CL_DX9_RESOURCE_NOT_ACQUIRED_INTEL if memory objects in |
| <mem_objects> have not previously been acquired using |
| clEnqueueAcquireDX9ObjectsINTEL, or have already been released |
| using clEnqueueReleaseDX9ObjectsINTEL 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. |
| |
| Interactions with cl_intel_packed_yuv: |
| |
| If cl_intel_packed_yuv is present, additional formats are available |
| in table 9.13.4.1: |
| |
| ------------------------------------------------------------------ |
| DirectX 9 Format cl_channel_order cl_channel_type |
| ------------------------------ ---------------- --------------- |
| D3DFMT_YUY2 CL_YUYV_INTEL CL_UNORM_INT8 |
| D3DFMT_UYVY CL_UYVY_INTEL CL_UNORM_INT8 |
| MAKEFOURCC(?Y?,?V?,?Y?,?U?) CL_YVYU_INTEL CL_UNORM_INT8 |
| MAKEFOURCC(?V?,?Y?,?U?,?Y?) CL_VYUY_INTEL CL_UNORM_INT8 |
| ------------------------------------------------------------------ |
| Table 9.13.4.1: List of DirectX 9 and corresponding OpenCL Image |
| Formats. |
| |
| Issues |
| |
| 1) Should we use an enumerant to describe which plane of a planar YUV |
| image we want to share or an integer? |
| |
| CLOSED: An integer is sufficient. |
| |
| 2) How should the API for this extension interact / coexist with |
| other D3D9 interop extensions? Should it? |
| |
| CLOSED: There are no other INTEL supported extensions for D3D9 interop. |
| |
| Revision History |
| |
| Version 6, 2011/10/18 (Ben Ashbaugh) ? Bugfix, need to use the FOURCC |
| code for YVYU and VYUY instead of G8R8_G8B8 and R8G8_B8G8. |
| Version 5, 2011/10/03 (Ben Ashbaugh) ? Final cleanup. Renamed |
| enumerants and entry points DX9 vs. D3D9. |
| Version 4, 2011/09/06 (Ben Ashbaugh) ? Updated table of D3D formats, |
| removed paragraph about channel swizzling. |
| Version 3, 2011/07/29 (Ben Ashbaugh) ? Added enumerant values. |
| Version 2, 2011/07/20 (Ben Ashbaugh) ? Since this will be an Intel |
| vendor extension, added the INTEL suffix to all entry points and |
| enumerants added by this extension. |
| Version 1, 2011/05/20 (Ben Ashbaugh) - Initial version after the Bremen |
| Khronos face-to-face. This version only contains functionality |
| necessary to interoperate with Direct3D 9 media surfaces. |
