From 250691c6a20ae5bf391d26a36fe1468c4b0e3023 Mon Sep 17 00:00:00 2001 From: Jeremy Kemp Date: Tue, 24 Nov 2020 16:11:16 +0000 Subject: [PATCH] Updated old and added new IMG extensions. (#90) * Added IMG HTML extension files. * Redirect previously published IMG extensions to their new HTML files. * Added extension 66: cl_img_generate_mipmap. * Added extension 67: cl_img_mem_properties. * Updated clext.php with update IMG extensions. * Alphabetise IMG extension ordering. * Update txt versions of IMG extensions to signpost the HTML version. --- extensions/clext.php | 10 +- extensions/img/cl_img_cached_allocations.html | 1063 +++++++++++++ extensions/img/cl_img_cached_allocations.txt | 99 +- extensions/img/cl_img_generate_mipmap.html | 1124 ++++++++++++++ extensions/img/cl_img_mem_properties.html | 1047 +++++++++++++ extensions/img/cl_img_use_gralloc_ptr.html | 1329 +++++++++++++++++ extensions/img/cl_img_use_gralloc_ptr.txt | 340 +---- extensions/img/cl_img_yuv_image.html | 1103 ++++++++++++++ extensions/img/cl_img_yuv_image.txt | 106 +- extensions/registry.py | 16 +- 10 files changed, 5707 insertions(+), 530 deletions(-) create mode 100644 extensions/img/cl_img_cached_allocations.html create mode 100644 extensions/img/cl_img_generate_mipmap.html create mode 100644 extensions/img/cl_img_mem_properties.html create mode 100644 extensions/img/cl_img_use_gralloc_ptr.html create mode 100644 extensions/img/cl_img_yuv_image.html diff --git a/extensions/clext.php b/extensions/clext.php index aa5f0250..b6d58b63 100644 --- a/extensions/clext.php +++ b/extensions/clext.php @@ -85,11 +85,11 @@
  • cl_intel_required_subgroup_size
    • -
  • cl_img_cached_allocations +
  • cl_img_cached_allocations
    • -
  • cl_img_use_gralloc_ptr +
  • cl_img_use_gralloc_ptr
    • -
  • cl_img_yuv_image +
  • cl_img_yuv_image
  • cl_intel_driver_diagnostics
    • @@ -129,4 +129,8 @@
  • cl_intel_mem_force_host_memory
    • +
  • cl_img_generate_mipmap +
    • +
  • cl_img_mem_properties +
    • diff --git a/extensions/img/cl_img_cached_allocations.html b/extensions/img/cl_img_cached_allocations.html new file mode 100644 index 00000000..054cbf8d --- /dev/null +++ b/extensions/img/cl_img_cached_allocations.html @@ -0,0 +1,1063 @@ + + + + + + + +cl_img_cached_allocations + + + + + + + + + +
    +
    +

    Name Strings

    +
    +
    +

    cl_img_cached_allocations

    +
    +
    +
    +
    +

    Contact

    +
    +
    +

    Imagination Technologies Developer Forum:
    +https://forums.imgtec.com/

    +
    +
    +

    Jeremy Kemp, Imagination Technologies (Jeremy.Kemp 'at' imgtec.com)

    +
    +
    +
    +
    +

    Contributors

    +
    +
    +

    Robert Quill, Imagination Technologies.
    +Jeremy Kemp, Imagination Technologies.

    +
    +
    +
    +
    +

    Notice

    +
    +
    +

    Copyright (c) 2020 Imagination Technologies Ltd. All Rights Reserved.

    +
    +
    +
    +
    +

    Status

    +
    +
    +

    Shipping

    +
    +
    +
    +
    +

    Version

    +
    +
    +

    Built On: 2020-11-10
    +Version: 1.0.0

    +
    +
    +
    +
    +

    Dependencies

    +
    +
    +

    Requires OpenCL version 1.2 or later.

    +
    +
    +

    This extension is written against the wording of the OpenCL 3.0 +Specification.

    +
    +
    +
    +
    +

    Overview

    +
    +
    +

    This extension extends the functionality provided by +clCreateBuffer and clCreateImage to allow the OpenCL +implementation to allocate memory on the device which +is also cached on the host CPU.

    +
    +
    +
    +
    +

    New API Enums

    +
    +
    +

    Accepted value for the flags parameter to clCreateBuffer and clCreateImage:

    +
    +
    +
    +
    CL_MEM_USE_UNCACHED_CPU_MEMORY_IMG (1 << 26)
+CL_MEM_USE_CACHED_CPU_MEMORY_IMG   (1 << 27)
    +
    +
    +
    +
    +
    +

    Modifications to the OpenCL API Specification

    +
    +
    +
    +
    (Modify Section 5.2, Buffer Objects)
    +
    +
    +
    +
    +
    +
    (Add the following to Table 5, List of supported memory flag values)
    +
    +
    +
    +
    +
    +
    +
    + ++++ + + + + + + + + + + + + + + + + +
    Memory FlagsDescription

    CL_MEM_USE_UNCACHED_CPU_MEMORY_IMG

    If this flag is specified it means that the application wants the OpenCL implementation to allocate memory on the device so that it is not cached when accessed on the host.

    CL_MEM_USE_CACHED_CPU_MEMORY_IMG

    If this flag is specified it means that the application wants the OpenCL implementation to allocate memory on the device so that it is cached when accessed on the host.

    +
    +
    + +
    +
    +
    +
    +
    +

    Issues

    +
    +
    +
      +
    1. +

      This extension may or may not improve performance; it depends on the +specific use-case. It is most likely to improve performance in cases +where the buffer or image is mapped using clEnqueueMapBuffer/Image +and some processing is then performed on the host-side. Whether the +allocation flag improves performance depends on whether the overhead +of cache flushes is greater than the performance gain from cached +memory accessing when doing the host-side processing. It’s recommended +to apply the flag on case-by-case basis to see if it improves your +use-case.

      +
      +
      +
      +

      INFORMATION

      +
      +
      +
      +
      2. +
    +
    +
    +
    +
    +

    Revision History

    +
    + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    VersionDateAuthorChanges

    1.0.0

    2020-11-09

    Jeremy Kemp

    Refreshed to AsciiDoc. Updated Contributors. Updated copyright notice. Updated the OpenCL spec which this extension spec is written against.

    0.2.0

    2014-10-09

    Robert Quill

    Update overview section to say that the extension also supports images. Add more detail to the overview section.

    0.1.0

    2014-10-07

    Robert Quill

    Initial revision.

    +
    +
    +
    + + + + + + \ No newline at end of file diff --git a/extensions/img/cl_img_cached_allocations.txt b/extensions/img/cl_img_cached_allocations.txt index a79cc9ac..d435a0f4 100644 --- a/extensions/img/cl_img_cached_allocations.txt +++ b/extensions/img/cl_img_cached_allocations.txt @@ -1,96 +1,11 @@ -Name +The cl_img_cached_allocations.txt extension is no longer authored in plain text. - IMG_cached_allocations +Please refer to the HTML extension specification instead, +which may be found here: -Name Strings +https://www.khronos.org/registry/OpenCL/extensions/img/cl_img_cached_allocations.html - cl_img_cached_allocations +The asciidoc source for this extension specification may +be found here: -Contributors - - Jeremy Kemp - -Contacts - - Jeremy Kemp, Imagination Technologies (jeremy.kemp 'at' imgtec.com) - -Status - - Unapproved. - -Version - - Revision: #3, Nov 6, 2014 - -Number - - OpenCL Extension #44 - -Dependencies - - Requires OpenCL version 1.2 or later. - - This extension is written against the wording of the OpenCL 1.2 - Specification. - -Overview - - This extension extends the functionality provided by - clCreateBuffer and clCreateImage to allow the OpenCL - implementation to allocate memory on the device which - is also cached on the host CPU. - -Glossary - - None - -New Types - - None - -New Procedures and Functions - - None - -New Tokens - - CL_MEM_USE_UNCACHED_CPU_MEMORY_IMG (1 << 26) - - CL_MEM_USE_CACHED_CPU_MEMORY_IMG (1 << 27) - -Additions to Chapter 5 of the OpenCL 1.2 Specification (Memory Objects) - - In Table 5.3, page 69, add the following text as a new row in the table: - - "CL_MEM_USE_UNCACHED_CPU_MEMORY_IMG - - If this flag is specified it means that the application wants the - OpenCL implementation to allocate memory on the device so that it - is not cached when accessed on the host." - - In Table 5.3, page 69, add the following text as a new row in the table: - - "CL_MEM_USE_CACHED_CPU_MEMORY_IMG - - If this flag is specified it means that the application wants the - OpenCL implementation to allocate memory on the device so that it - is cached when accessed on the host." - -Issues - - 1. This extension may or may not improve performance; it depends on the - specific use-case. It is most likely to improve performance in cases - where the buffer or image is mapped using clEnqueueMapBuffer/Image - and some processing is then performed on the host-side. Whether the - allocation flag improves performance depends on whether the overhead - of cache flushes is greater than the performance gain from cached - memory accessing when doing the host-side processing. It's recommended - to apply the flag on case-by-case basis to see if it improves your - use-case. - -Revision History - -#2 - Update overview section to say that the extension also supports images. - Add more detail to the overview section. - -#1 - Initial revision. +https://github.com/KhronosGroup/OpenCL-Docs/blob/master/extensions/cl_img_cached_allocations.asciidoc \ No newline at end of file diff --git a/extensions/img/cl_img_generate_mipmap.html b/extensions/img/cl_img_generate_mipmap.html new file mode 100644 index 00000000..51d54b07 --- /dev/null +++ b/extensions/img/cl_img_generate_mipmap.html @@ -0,0 +1,1124 @@ + + + + + + + +cl_img_generate_mipmap + + + + + + + + + +
    +
    +

    Name Strings

    +
    +
    +

    cl_img_generate_mipmap

    +
    +
    +
    +
    +

    Contact

    +
    +
    +

    Imagination Technologies Developer Forum:
    +https://forums.imgtec.com/

    +
    +
    +

    Jeremy Kemp, Imagination Technologies (Jeremy.Kemp 'at' imgtec.com)

    +
    +
    +
    +
    +

    Contributors

    +
    +
    +

    Kim Svensson, Imagination Technologies.
    +Timothy Smith, Imagination Technologies.
    +Robert Quill, Imagination Technologies.
    +Jeremy Kemp, Imagination Technologies.

    +
    +
    +
    +
    +

    Notice

    +
    +
    +

    Copyright (c) 2020 Imagination Technologies Ltd. All Rights Reserved.

    +
    +
    +
    +
    +

    Status

    +
    +
    +

    Shipping

    +
    +
    +
    +
    +

    Version

    +
    +
    +

    Built On: 2020-11-23
    +Version: 1.0.0

    +
    +
    +
    +
    +

    Dependencies

    +
    +
    +

    Requires the cl_khr_mipmap_image extension.

    +
    +
    +

    This extension is written against the wording of the OpenCL 3.0 Specification.

    +
    +
    +
    +
    +

    Overview

    +
    +
    +

    This extension adds the functionality to generate mipmap images from a source image and thus avoid having to generate and import mipmapped images from the host or through the cl_khr_gl_sharing extension.

    +
    +
    +
    +
    +

    New API Types

    +
    +
    +
    +
    typedef cl_uint cl_mipmap_filter_mode_img;
    +
    +
    +
    +
    +
    +

    New API Enums

    +
    +
    +

    Values accepted with cl_mipmap_filter_mode_img:

    +
    +
    +
    +
    CL_MIPMAP_FILTER_ANY_IMG 0x0
+CL_MIPMAP_FILTER_BOX_IMG 0x1
    +
    +
    +
    +

    New command types cl_command_type:

    +
    +
    +
    +
    CL_COMMAND_GENERATE_MIPMAP_IMG 0x40D6
    +
    +
    +
    +
    +
    +

    New API Functions

    +
    +
    +
    +
    cl_int CL_API_CALL clEnqueueGenerateMipmapIMG(
+    cl_command_queue command_queue,
+    cl_mem src_image,
+    cl_mem dst_image,
+    cl_mipmap_filter_mode_img mipmap_filter_mode,
+    const size_t *array_region,
+    const size_t *mip_region,
+    cl_uint num_events_in_wait_list,
+    const cl_event *event_wait_list,
+    cl_event *event);
    +
    +
    +
    +
    +
    +

    Modifications to the OpenCL API Specification

    +
    +
    +
    +
    (Modify Section 5.3, Image Objects)
    +
    +
    +
    +
    (Add a new Section 5.3.8, Generating Mipmap Levels)
    +
    +
    +
    +
    +

    The function

    +
    +
    +
    +
    cl_int CL_API_CALL clEnqueueGenerateMipmapIMG(
+    cl_command_queue command_queue,
+    cl_mem src_image,
+    cl_mem dst_image,
+    cl_mipmap_filter_mode_img mipmap_filter_mode,
+    const size_t *array_region,
+    const size_t *mip_region,
+    cl_uint num_events_in_wait_list,
+    const cl_event *event_wait_list,
+    cl_event *event);
    +
    +
    +
    +

    is used to generate mipmap levels from a source image to a destination image. This allows for seamless mipmap level generation without involving the host to generate them, as that would involve reading back the image, generate its mipmap levels and then upload it to the device again. This reduces bandwidth cost of generating mipmap levels as no host copy is needed and may improve the speed of generating mipmap levels. The source image and destination image can be the same image in order to reduce programming and memory overhead. As with the extension for mipmaps, the size of the image must be a power of 2.

    +
    +
    +

    command_queue is a valid command-queue.

    +
    +
    +

    src_image, dst_image refer to a valid 1D, 2D, 3D image or a 1D image array, 2D image array objects. Where the src_image refer to the image where the mipmaps will be sourced from and dst_image is the image where the mipmaps will be generated to. The width, height, depth and image_array_size where applicable, must be the same for the src_image and dst_image. The image types of src_image and dst_image must be the same, therefore dst_image cannot be a 2D image if the src_image is of the type 2D image array. The image_channel_order and image_channel_data_type must be the same for both images. The src_image and dst_image can be the same image object to avoid unnecessary memory allocations.

    +
    +
    +

    mipmap_filter_mode refer to the filter mode to generate the mipmap levels with. CL_MIPMAP_FILTER_ANY_IMG allows the device to use any filter mode it deems necessary, whilst CL_MIPMAP_FILTER_BOX_IMG uses a box filter to sample down the image.

    +
    +
    +

    array_region Defines the (n,m) image range in a 1D and 2D image array to generate. If the src_image and dst_image is of the types 1D, 2D and 3D image, array_region must be NULL.

    +
    +
    +

    mip_region Defines the (n,m) region of mipmap levels to generate in dst_image. Where (n) defines the start of the region and (m) the end of region. If mip_region is NULL, all mipmap layers in dst_image will be generated. The (n) starting region must range from 0 to equal to the (m) end region whilst the (m) end region must range from 1 to one less than the maximum number of mipmap layers in dst_image, as mipmap layer indexing starts at 0. Setting mip_region[0] to 0 means that the mipmap layer 0 of src_image will be copied to mipmap layer 0 of dst_image. If src_image and dst_image is the same image and mip_region[0] = 0, no copy of layer 0 will occur and only generation of mipmaps would be executed.

    +
    +
    +

    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.

    +
    +
    +

    clEnqueueGenerateMipmapIMG returns CL_SUCCESS if the function is executed successfully, otherwise it returns one of the following errors:

    +
    +
    +
      +
    • +

      CL_INVALID_COMMAND_QUEUE if command_queue is not a valid host command-queue.

      +
      • +
    • +

      CL_INVALID_MEM_OBJECT if src_image or dst_image are not a valid image object.

      +
      • +
    • +

      CL_INVALID_MEM_OBJECT if src_image and dst_image have different image type.

      +
      • +
    • +

      CL_INVALID_IMAGE_FORMAT_DESCRIPTOR if src_image and dst_image have different image_channel_order or image_channel_data_type.

      +
      • +
    • +

      CL_INVALID_IMAGE_SIZE if src_image and dst_image have different image size in mipmap layer 0, if the images are of image array type and have different image array size.

      +
      • +
    • +

      CL_INVALID_CONTEXT if the context associated with command_queue, src_image and dst_image are not the same or if the context associated with command_queue and events in event_wait_list are not the same.

      +
      • +
    • +

      CL_INVALID_MIP_LEVEL if mip_region[0] is greater than mip_region[1], or if mip_region[0] is less than 0, or if mip_region[1] is less than 1, or if mip_region[1] is greater than the number of mipmap levels in dst_image.

      +
      • +
    • +

      CL_INVALID_VALUE if the images are not of the type image array and array_region is not NULL, or the images are of type image array and array_region is NULL.

      +
      • +
    • +

      CL_INVALID_VALUE if the images are of type image array and array_region refer to a range outside of the available range in dst_image and src_image, or if array_region[0] is greater than array_region[1].

      +
      • +
    • +

      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_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.

      +
      • +
    • +

      CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

      +
      • +
    +
    +
    +
    +
    +
    +
    +
    +
    +
    +
    +
    +
    +

    Revision History

    +
    + ++++++ + + + + + + + + + + + + + + + + + + + + + + +
    VersionDateAuthorChanges

    1.0.0

    2020-11-10

    Jeremy Kemp

    Refreshed to AsciiDoc. Updated Contributors. Updated copyright notice. Updated the OpenCL spec which this extension spec is written against. Updated dependencies.

    0.1.0

    2017-06-26

    Robert Quill

    Initial revision.

    +
    +
    +
    + + + + + + \ No newline at end of file diff --git a/extensions/img/cl_img_mem_properties.html b/extensions/img/cl_img_mem_properties.html new file mode 100644 index 00000000..421e31f4 --- /dev/null +++ b/extensions/img/cl_img_mem_properties.html @@ -0,0 +1,1047 @@ + + + + + + + +cl_img_mem_properties + + + + + + + + + +
    +
    +

    Name Strings

    +
    +
    +

    cl_img_mem_properties

    +
    +
    +
    +
    +

    Contact

    +
    +
    +

    Imagination Technologies Developer Forum:
    +https://forums.imgtec.com/

    +
    +
    +

    Jeremy Kemp, Imagination Technologies (Jeremy.Kemp 'at' imgtec.com)

    +
    +
    +
    +
    +

    Contributors

    +
    +
    +

    Jeremy Kemp, Imagination Technologies.
    +Anitha Raj, Imagination Technologies.

    +
    +
    +
    +
    +

    Notice

    +
    +
    +

    Copyright (c) 2020 Imagination Technologies Ltd. All Rights Reserved.

    +
    +
    +
    +
    +

    Status

    +
    +
    +

    Shipping

    +
    +
    +
    +
    +

    Version

    +
    +
    +

    Built On: 2020-11-23
    +Version: 1.0.0

    +
    +
    +
    +
    +

    Dependencies

    +
    +
    +

    This extension requires OpenCL 3.0 or later.

    +
    +
    +
    +
    +

    Overview

    +
    +
    +

    This extension provides additional properties that can be passed to clCreateBufferWithProperties.

    +
    +
    +
    +
    +

    New API Types

    +
    +
    +
    +
    typedef cl_bitfield cl_mem_alloc_flags_img;
    +
    +
    +
    +
    +
    +

    New API Enums

    +
    +
    +

    Accepted propertie(s) for the properties parameter to clCreateBufferWithProperties:

    +
    +
    +
    +
    #define CL_MEM_ALLOC_FLAGS_IMG 0x40D7
    +
    +
    +
    +

    Accepted values for cl_mem_alloc_flags_img:

    +
    +
    +
    +
    #define CL_MEM_ALLOC_RELAX_REQUIREMENTS_IMG (1 << 0)
    +
    +
    +
    +
    +
    +

    Modifications to the OpenCL API Specification

    +
    +
    +
    +
    (Modify Section 5.2.1, Creating Buffer Objects)
    +
    +
    +
    +
    +
    +
    Add Table: List of supported properties when passed to clCreateBufferWithProperties
    +
    + +++++ + + + + + + + + + + + + + + +
    PropertyProperty ValueDescription

    CL_MEM_ALLOC_FLAGS_IMG

    cl_mem_alloc_flags_img

    CL_MEM_ALLOC_RELAX_REQUIREMENTS_IMG - On platforms with limited amounts of global memory available it may be desirable to request an allocation larger than the maximum amount reported by the implementation via CL_DEVICE_MAX_MEM_ALLOC_SIZE if there is sufficient knowledge about the entire system. +This property allows an application to request buffer objects that are larger than CL_DEVICE_MAX_MEM_ALLOC_SIZE.

    +
    +
    (Replace the following error value)
    +
    +
    +
      +
    • +

      CL_INVALID_BUFFER_SIZE if size is 0 or if size is greater than CL_DEVICE_MAX_MEM_ALLOC_SIZE for all devices in context.

      +
      +

      with

      +
      +
      • +
    • +

      CL_INVALID_BUFFER_SIZE if size is 0.

      +
      • +
    +
    +
    +
    +
    +
    +
    +
    +
    +
    +
    +
    +
    +

    Revision History

    +
    + ++++++ + + + + + + + + + + + + + + + + +
    VersionDateAuthorChanges

    1.0.0

    2020-08-18

    Jeremy Kemp

    Initial revision.

    +
    +
    +
    + + + + + + \ No newline at end of file diff --git a/extensions/img/cl_img_use_gralloc_ptr.html b/extensions/img/cl_img_use_gralloc_ptr.html new file mode 100644 index 00000000..08abd8ee --- /dev/null +++ b/extensions/img/cl_img_use_gralloc_ptr.html @@ -0,0 +1,1329 @@ + + + + + + + +cl_img_use_gralloc_ptr + + + + + + + + + +
    +
    +

    Name Strings

    +
    +
    +

    cl_img_use_gralloc_ptr

    +
    +
    +
    +
    +

    Contact

    +
    +
    +

    Imagination Technologies Developer Forum:
    +https://forums.imgtec.com/

    +
    +
    +

    Jeremy Kemp, Imagination Technologies (Jeremy.Kemp 'at' imgtec.com)

    +
    +
    +
    +
    +

    Contributors

    +
    +
    +

    Robert Quill, Imagination Technologies.
    +Paul Fradgley, Imagination Technologies.
    +Jeremy Kemp, Imagination Technologies.

    +
    +
    +
    +
    +

    Notice

    +
    +
    +

    Copyright (c) 2020 Imagination Technologies Ltd. All Rights Reserved.

    +
    +
    +
    +
    +

    Status

    +
    +
    +

    Shipping

    +
    +
    +
    +
    +

    Version

    +
    +
    +

    Built On: 2020-11-10
    +Version: 1.0.0

    +
    +
    +
    +
    +

    Dependencies

    +
    +
    +

    Requires OpenCL version 1.2 or later. Android OS is required.

    +
    +
    +

    This extension is written against the wording of the OpenCL 3.0 +Specification.

    +
    +
    +
    +
    +

    Overview

    +
    +
    +

    This extension extends the functionality provided by clCreateBuffer and clCreateImage. +It allows applications to pass an Android memory allocation to these functions and thus avoid having to copy data back and forth between the host and the device.

    +
    +
    +
    +
    +

    New API Enums

    +
    +
    +

    New command types cl_command_type:

    +
    +
    +
    +
    CL_COMMAND_ACQUIRE_GRALLOC_OBJECTS_IMG 0x40D2
+CL_COMMAND_RELEASE_GRALLOC_OBJECTS_IMG 0x40D3
    +
    +
    +
    +

    New error codes:

    +
    +
    +
    +
    CL_GRALLOC_RESOURCE_NOT_ACQUIRED_IMG 0x40D4
+CL_INVALID_GRALLOC_OBJECT_IMG        0x40D5
    +
    +
    +
    +

    Accepted value for the flags parameter to clCreateBuffer and clCreateImage:

    +
    +
    +
    +
    CL_MEM_USE_GRALLOC_PTR_IMG (1 << 28)
    +
    +
    +
    +
    +
    +

    New API Functions

    +
    +
    +
    +
    cl_int CL_API_CALL clEnqueueAcquireGrallocObjectsIMG(
+    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 CL_API_CALL clEnqueueReleaseGrallocObjectsIMG(
+    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);
    +
    +
    +
    +
    +
    +

    Modifications to the OpenCL API Specification

    +
    +
    +
    +
    (Modify Section 5.2, Buffer Objects)
    +
    +
    +
    +
    +
    +
    (Add the following to Table 5, List of supported memory flag values)
    +
    + ++++ + + + + + + + + + + + + +
    Memory FlagsDescription

    CL_MEM_USE_GRALLOC_PTR_IMG

    This flag is only valid of host_ptr is not NULL. The value given in host_ptr is an Android memory allocation.

    +

    If this flag is specified to clCreateBuffer, then host_ptr must be an Android buffer_handle_t. It means that the application wants the OpenCL implementation to use memory referenced by the buffer_handle_t as the storage bits for the memory object.

    +

    If this flag is specified to clCreateImage, then host_ptr must be an Android ANativeWindowBuffer. It means that the application wants the OpenCL implementation to use memory referenced by the ANativeWindowBuffer as the storage bits for the memory object.

    +

    size must be 0 if this flag is set when given to clCreateBuffer. The size of the buffer is determined from the size of the Android allocation.

    +
    +
    (Add the following to Section 5.2.1, Creating Buffer Objects)
    +
    +
    +
    +
    (Add the following error conditions to the list after this section)
    +
    +

    CL_INVALID_BUFER_SIZE if size is non-zero and flags contains CL_MEM_USE_GRALLOC_PTR_IMG.

    +
    +
    (Replace the following paragraph)
    +
    +

    CL_INVALID_HOST_PTR if host_ptr is NULL and CL_MEM_USE_HOST_PTR or CL_MEM_COPY_HOST_PTR are set in flags or if host_ptr is not NULL but CL_MEM_COPY_HOST_PTR or CL_MEM_USE_HOST_PTR are not set in flags.

    +
    +

    with

    +
    +
    +

    CL_INVALID_HOST_PTR if host_ptr is NULL and CL_MEM_USE_HOST_PTR, CL_MEM_COPY_HOST_PTR or CL_MEM_USE_GRALLOC_PTR_IMG are set in flags or if host_ptr is not NULL but CL_MEM_COPY_HOST_PTR, CL_MEM_USE_HOST_PTR or CL_MEM_USE_GRALLOC_PTR_IMG are not set in flags.

    +
    +
    +
    +
    +
    +
    +
    +
    +
    +
    +
    (Modify Section 5.3, Image Objects)
    +
    +
    +
    +
    +
    +
    (Add the following to Section 5.3.1, Creating Image Objects)
    +
    +
    +
    +
    (Replace the following paragraph)
    +
    +

    CL_INVALID_IMAGE_DESCRIPTOR if values specified in image_desc are not valid or if image_desc is NULL.

    +
    +

    with

    +
    +
    +

    CL_INVALID_IMAGE_DESCRIPTOR if image_desc is NULL and flags does not contain CL_MEM_USE_GRALLOC_PTR_IMG, or if image_desc is not NULL and flags contains CL_MEM_USE_GRALLOC_PTR_IMG, or if values specified in image_desc are not valid.

    +
    +
    +
    (Replace the following paragraph)
    +
    +

    CL_INVALID_HOST_PTR if host_ptr is NULL and CL_MEM_USE_HOST_PTR or CL_MEM_COPY_HOST_PTR are set in flags or if host_ptr is not NULL but CL_MEM_COPY_HOST_PTR or CL_MEM_USE_HOST_PTR are not set in flags.

    +
    +

    with

    +
    +
    +

    CL_INVALID_HOST_PTR if host_ptr is NULL and CL_MEM_USE_HOST_PTR, CL_MEM_COPY_HOST_PTR or CL_MEM_USE_GRALLOC_PTR_IMG are set in flags or if host_ptr is not NULL but CL_MEM_COPY_HOST_PTR, CL_MEM_USE_HOST_PTR or CL_MEM_USE_GRALLOC_PTR_IMG are not set in flags.

    +
    +
    +
    +
    +
    +
    +
    +
    +
    +
    +
    (Add a new Section 5.16, Sharing OpenCL and Gralloc Objects)
    +
    +
    +
    +
    (Add a new Section 5.16.1, Synchronizing OpenCL and Android Access to Shared Gralloc Objects)
    +
    +

    In order to ensure data integrity, the application is responsible for synchronizing access to shared CL/gralloc objects by their respective APIs. Failure to provide such synchronization may result in race conditions and other undefined behaviour including non-portability between implementations.

    +
    +

    Prior to calling clEnqueueAcquireGrallocObjectsIMG, the application must ensure that any pending operations which access the objects specified in mem_objects have completed. This may be accomplished in a portable way by ceasing all client operations on the resource. Implementations may offer more efficient synchronization methods, such as synchronisation primitives or fence operations.

    +
    +
    +

    Similarly, after calling clEnqueueReleaseGrallocObjectsIMG, the application is responsible for ensuring that any pending OpenCL operations which access the objects specified in mem_objects have completed prior to executing subsequent commands in other APIs which reference these objects. This may be accomplished in a portable way by calling clWaitForEvents with the event object returned by clEnqueueReleaseGrallocObjects, or by calling clFinish. As above, some implementations may offer more efficient methods.

    +
    +
    +

    Attempting to access the data store of a gralloc allocation after it has been acquired by OpenCL and before it has been released will result in undefined behaviour. Similarly, attempting to access a shared gralloc object from OpenCL before it has been acquired by the OpenCL command queue or after it has been released, will result in undefined behaviour.

    +
    +
    +
    (Add a new Section 5.16.2, Sharing Memory Objects Created From Gralloc Resources With OpenCL Contexts)
    +
    +
    +
    +
    +

    The function

    +
    +
    +
    +
    cl_int CL_API_CALL clEnqueueAcquireGrallocObjectsIMG(
+    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 gralloc resources. The gralloc 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 gralloc 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 gralloc resource is used while it is not currently acquired by OpenCL, the call attempting to use that OpenCL memory object will return CL_GRALLOC_RESOURCE_NOT_ACQUIRED_IMG.

    +
    +
    +

    This function has no affect on memory objects in mem_objects that have already been acquired, ignoring them silently. The function returns CL_SUCCESS even if all of the memory objects are ignored in this way.

    +
    +
    +

    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 gralloc resources, within the context associate with command_queue.

    +
    +
    +

    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.

    +
    +
    +

    clEnqueueAcquireGrallocObjectsIMG 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 in the context associated with command_queue.

      +
      • +
    • +

      CL_INVALID_GRALLOC_OBJECT_IMG if memory objects in mem_objects have not been created from gralloc resources.

      +
      • +
    • +

      CL_INVALID_COMMAND_QUEUE if command_queue is not a valid command-queue.

      +
      • +
    • +

      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_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.

      +
      • +
    • +

      CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

      +
      • +
    • +

      CL_INVALID_OPERATION if the queue on which the command is enqueued is associated with a device which does not support cl_img_use_gralloc_ptr.

      +
      • +
    +
    +
    +

    The function

    +
    +
    +
    +
    cl_int CL_API_CALL clEnqueueReleaseGrallocObjectsIMG(
+    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 gralloc resources. The gralloc objects are released by the OpenCL context associated with command_queue.

    +
    +
    +

    OpenCL memory objects created from gralloc resources which have been acquired by OpenCL must be released by OpenCL before they may be accessed by Android client APIs. Accessing a gralloc resource while its corresponding OpenCL memory object is acquired is in error and will result in undefined behaviour, including but not limited to possible OpenCL errors, data corruption, and program termination.

    +
    +
    +

    command_queue is a valid command-queue.

    +
    +
    +

    mem_objects is a pointer to a list of OpenCL memory objects that were created from gralloc resources, within the context associated with command_queue.

    +
    +
    +

    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.

    +
    +
    +

    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.

    +
    +
    +

    clEnqueueReleaseGrallocObjectsIMG 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 in the context associated with command_queue.

      +
      • +
    • +

      CL_INVALID_GRALLOC_OBJECT_IMG if memory objects in mem_objects have not been created from gralloc resources.

      +
      • +
    • +

      CL_INVALID_COMMAND_QUEUE if command_queue is not a valid command-queue.

      +
      • +
    • +

      CL_GRALLOC_RESOURCE_NOT_ACQUIRED_IMG if memory objects in mem_objects have not previously acquired with clEnqueueAcquireGrallocObjectsIMG, or have been released using clEnqueueReleaseGrallocObjectsIMG 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_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.

      +
      • +
    • +

      CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

      +
      • +
    +
    +
    +
    +
    +
    +
    +
    +
    +
    +
    +
    +
    +

    Issues

    +
    +
    +
      +
    1. +

      This extension does not support reference counting of the images, so the onus is on the application to behave sensibly and not release the underlying cl_mem object while the gralloc object is still being used.

      +
      +
      +
      +

      INFORMATION

      +
      +
      +
      +
      2. +
    2. +

      In order to ensure data integrity, the application is responsible for synchronizing access to shared CL/gralloc objects by their respective APIs. Failure to provide such synchronization may result in race conditions and other undefined behaviour. This may be accomplished by calling clWaitForEvents with the event objects returned by any OpenCL commands which use the shared image object or by calling clFinish.

      +
      +
      +
      +

      INFORMATION

      +
      +
      +
      +
      3. +
    3. +

      Currently restricted to buffer objects.

      +
      +
      +
      +

      RESOLVED

      +
      +
      +
      +
      4. +
    +
    +
    +
    +
    +

    Revision History

    +
    + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    VersionDateAuthorChanges

    1.0.0

    2020-11-10

    Jeremy Kemp

    Refreshed to AsciiDoc. Updated Contributors. Updated copyright notice. Updated the OpenCL spec which this extension spec is written against. Spelling fixes.

    0.2.0

    2017-10-17

    Paul Fradgley

    Added support for images.

    0.1.0

    2014-08-08

    Robert Quill

    Initial revision.

    +
    +
    +
    + + + + + + \ No newline at end of file diff --git a/extensions/img/cl_img_use_gralloc_ptr.txt b/extensions/img/cl_img_use_gralloc_ptr.txt index deb7f6b8..87f3c874 100644 --- a/extensions/img/cl_img_use_gralloc_ptr.txt +++ b/extensions/img/cl_img_use_gralloc_ptr.txt @@ -1,337 +1,11 @@ -Name +The cl_img_use_gralloc_ptr.txt extension is no longer authored in plain text. - IMG_use_gralloc_ptr +Please refer to the HTML extension specification instead, +which may be found here: -Name Strings +https://www.khronos.org/registry/OpenCL/extensions/img/cl_img_use_gralloc_ptr.html - cl_img_use_gralloc_ptr +The asciidoc source for this extension specification may +be found here: -Contributors - - Robert Quill - -Contacts - - Rob Quill, Imagination Technologies (robert.quill 'at' imgtec.com) - -Status - - Unapproved. - -Version - - Revision: #8, Dec 16, 2013 - -Number - - OpenCL Extension #45 - -Dependencies - - Requires OpenCL version 1.2 or later. Android OS is required. - - This extension is written against the wording of the OpenCL 1.2 - Specification. - -Overview - - This extension extends the functionality provided by clCreateBuffer. - It allows applications to pass an Android gralloc memory allocation to these functions - and thus avoid having to copy data back and forth between the host and the device. - -Glossary - - See https://source.android.com/devices/graphics/architecture.html for a - description of the Android gralloc API. - -New Types - - None - -New Procedures and Functions - - cl_int clEnqueueAcquireGrallocObjectsIMG(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 clEnqueueReleaseGrallocObjectsIMG(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); - -New Tokens - - New error codes: - - CL_GRALLOC_RESOURCE_NOT_ACQUIRED_IMG 0x40D4 - CL_INVALID_GRALLOC_OBJECT_IMG 0x40D5 - - New command types: - - CL_COMMAND_ACQUIRE_GRALLOC_OBJECTS_IMG 0x40D2 - CL_COMMAND_RELEASE_GRALLOC_OBJECTS_IMG 0x40D3 - - -Additions to Chapter 5 of the OpenCL 1.2 Specification (Memory Objects) - - In Table 5.3, page 69, add the following text as a new row in the table: - - "CL_MEM_USE_GRALLOC_PTR_IMG - - This flag is only valid of is non-NULL. The value given in - is an Android buffer_handle_t. - - If this flag is specified it means that the application wants the - OpenCL implementation to use memory referenced by the buffer_handle_t - as the storage bits for the memory object. - - must be 0 if this flag is set. The size of the buffer is determined - from the size of the gralloc allocation. - - This flag is only valid when using clCreateBuffer." - - Add the following error conditions to the list after this section: - - clCreateBuffer returns a valid non-zero 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_BUUFER_SIZE - - if is non-zero and contains CL_MEM_USE_GRALLOC_PTR_IMG" - - Replace the follow paragraph: - - "CL_INVALID_HOST_PTR if host_ptr is NULL and CL_MEM_USE_HOST_PTR or - CL_MEM_COPY_HOST_PTR are set in flags or if host_ptr is not NULL but - CL_MEM_COPY_HOST_PTR or CL_MEM_USE_HOST_PTR are not set in flags." - - with: - - "CL_INVALID_HOST_PTR if host_ptr is NULL and CL_MEM_USE_HOST_PTR, - CL_MEM_COPY_HOST_PTR or CL_MEM_USE_GRALLOC_PTR_IMG are set in flags - or if host_ptr is not NULL but CL_MEM_COPY_HOST_PTR, CL_MEM_USE_HOST_PTR - or CL_MEM_USE_GRALLOC_PTR_IMG are not set in flags." - - - Add: - - "9.19 Sharing OpenCL and gralloc objects - - 9.19.1 Synchronizing OpenCL and Android Access to Shared Gralloc Objects - - In order to ensure data integrity, the application is responsible for - synchronizing access to shared CL/gralloc objects by their respective APIs. - Failure to provide such synchronization may result in race conditions and - other undefined behavior including non-portability between implementations. - - Prior to calling clEnqueueAcquireGrallocObjectsIMG, the application must - ensure that any pending operations which access the objects specified in - mem_objects have completed. This may be accomplished in a portable way by - ceasing all client operations on the resource. Implementations may offer - more efficient synchronization methods, such as synchronisation primitives - or fence operations. - - Similarly, after calling clEnqueueReleaseGrallocObjectsIMG, the application - is responsible for ensuring that any pending OpenCL operations which access - the objects specified in mem_objects have completed prior to executing - subsequent commands in other APIs which reference these objects. This may - be accomplished in a portable way by calling clWaitForEvents with the event - object returned by clEnqueueReleaseGrallocObjects, or by calling clFinish. As - above, some implementations may offer more efficient methods. - - Attempting to access the data store of a gralloc allocation after it has - been acquired by OpenCL and before it has been released will result in - undefined behavior. Similarly, attempting to access a shared gralloc - object from OpenCL before it has been acquired by the OpenCL command queue - or after it has been released, will result in undefined behavior. - - - 9.19.2 Sharing memory objects created from gralloc resources with OpenCL contexts - - The function - - cl_int clEnqueueAcquireGrallocObjectsIMG( - 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 - gralloc resources. The gralloc objects are acquired by the OpenCL context - associated with and can therefore be used by all - command-queues associated with the OpenCL context. - - OpenCL memory objects created from gralloc 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 gralloc - resource is used while it is not currently acquired by OpenCL, the - call attempting to use that OpenCL memory object will return - CL_GRALLOC_RESOURCE_NOT_ACQUIRED_IMG. - - This function has no affect on memory objects in - that have already been acquired, ignoring them silently. The - function returns CL_SUCCESS even if all of the memory objects are - ignored in this way. - - is a valid command-queue. - - is the number of memory objects to be acquired in - . - - is a pointer to a list of OpenCL memory objects that - were created from gralloc resources, within the context associate with - . - - and specify events that - need to complete before this particular command can be executed. If - is NULL, then this particular command does not - wait on any event to complete. If is NULL, - must be 0. If is not - NULL, the list of events pointed to by must be - valid and must be greater than 0. The - events specified in act as synchronization points. - - 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. 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. - - clEnqueueAcquireGrallocObjectsIMG returns CL_SUCCESS if the function is - executed successfully. If is 0 and is - NULL then the function does nothing and returns CL_SUCCESS. Otherwise it - returns one of the following errors: - - * CL_INVALID_VALUE if is zero and is - not a NULL value or if > 0 and is - NULL. - - * CL_INVALID_MEM_OBJECT if memory objects in are not - valid OpenCL memory objects in the context associated with - . - - * CL_INVALID_GRALLOC_OBJECT_IMG if memory objects in have - not been created from gralloc resources. - - * CL_INVALID_COMMAND_QUEUE if is not a valid - command-queue. - - * CL_INVALID_EVENT_WAIT_LIST if is NULL and - > 0, or is not NULL - and is 0, or if event objects in - are not valid events. - - * CL_OUT_OF_RESOURCES if there is a failure to allocate resources - required by the OpenCL implementation on the device. - - * CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources - required by the OpenCL implementation on the host. - - * CL_INVALID_OPERATION if the queue on which the command is enqueued - is associated with a device which does not support cl_img_use_gralloc_ptr. - - The function - - cl_int clEnqueueReleaseGrallocObjectsIMG( - 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 - gralloc resources. The gralloc objects are released by the OpenCL context - associated with . - - OpenCL memory objects created from gralloc resources which have been - acquired by OpenCL must be released by OpenCL before they may be - accessed by Android client APIs. Accessing a gralloc 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. - - is a valid command-queue. - - is a pointer to a list of OpenCL memory objects that - were created from gralloc resources, within the context associated with - . - - and specify events that - need to complete before this particular command can be executed. If - is NULL, then this particular command does not - wait on any event to complete. If is NULL, - must be 0. If is not - NULL, the list of events pointed to by must be - valid and must be greater than 0. - - 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. 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. - - clEnqueueReleaseGrallocObjectsIMG returns CL_SUCCESS if the function - is executed successfully. If is 0 and is - NULL the function does nothing and returns CL_SUCCESS. Otherwise it - returns one of the following errors: - - * CL_INVALID_VALUE if is zero and is - not a NULL value or if > 0 and is - NULL. - - * CL_INVALID_MEM_OBJECT if memory objects in are not - valid OpenCL memory objects in the context associated with - . - - * CL_INVALID_GRALLOC_OBJECT_IMG if memory objects in have - not been created from gralloc resources. - - * CL_INVALID_COMMAND_QUEUE if is not a valid - command-queue. - - * CL_GRALLOC_RESOURCE_NOT_ACQUIRED_IMG if memory objects in - have not previously acquired with - clEnqueueAcquireGrallocObjectsIMG, or have been released using - clEnqueueReleaseGrallocObjectsIMG since the last time that they were - acquired. - - * CL_INVALID_EVENT_WAIT_LIST if is NULL and - > 0, or is not NULL - and is 0, or if event objects in - are not valid events. - - * CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the - OpenCL implementation on the device. - - * CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources - required by the OpenCL implementation on the host. - " - -Issues - - 1. This extension does not support reference counting - of the images, so the onus is on the application to behave - sensibly and not release the underlying cl_mem object while the - gralloc object is still being used. - - 2. In order to ensure data integrity, the application is responsible for - synchronizing access to shared CL/gralloc objects by their respective - APIs. Failure to provide such synchronization may result in race - conditions and other undefined behavior. This may be accomplished by - calling clWaitForEvents with the event objects returned by any OpenCL - commands which use the shared image object or by calling clFinish. - - 3. Currently restricted to buffer objects. - -Revision History - -#1 - Initial revision. +https://github.com/KhronosGroup/OpenCL-Docs/blob/master/extensions/cl_img_use_gralloc_ptr.asciidoc \ No newline at end of file diff --git a/extensions/img/cl_img_yuv_image.html b/extensions/img/cl_img_yuv_image.html new file mode 100644 index 00000000..1e3a6e04 --- /dev/null +++ b/extensions/img/cl_img_yuv_image.html @@ -0,0 +1,1103 @@ + + + + + + + +cl_img_yuv_image + + + + + + + + + +
    +
    +

    Name Strings

    +
    +
    +

    cl_img_yuv_image

    +
    +
    +
    +
    +

    Contact

    +
    +
    +

    Imagination Technologies Developer Forum:
    +https://forums.imgtec.com/

    +
    +
    +

    Jeremy Kemp, Imagination Technologies (Jeremy.Kemp 'at' imgtec.com)

    +
    +
    +
    +
    +

    Contributors

    +
    +
    +

    James Laverack, Imagination Technologies.
    +Robert Quill, Imagination Technologies.
    +Jeremy Kemp, Imagination Technologies.

    +
    +
    +
    +
    +

    Notice

    +
    +
    +

    Copyright (c) 2020 Imagination Technologies Ltd. All Rights Reserved.

    +
    +
    +
    +
    +

    Status

    +
    +
    +

    Shipping

    +
    +
    +
    +
    +

    Version

    +
    +
    +

    Built On: 2020-11-10
    +Version: 1.0.0

    +
    +
    +
    +
    +

    Dependencies

    +
    +
    +

    Requires OpenCL version 1.2 or later.

    +
    +
    +

    This extension is written against the wording of the OpenCL 3.0 Specification.

    +
    +
    +
    +
    +

    Overview

    +
    +
    +

    This extension provides new image formats to read YUV images, such as those provided by cameras on mobile devices.

    +
    +
    +
    +
    +

    New API Enums

    +
    +
    +

    New values accepted for the image_channel_order member in cl_image_format:

    +
    +
    +
    +
    CL_NV21_IMG 0x40D0
+CL_YV12_IMG 0x40D1
    +
    +
    +
    +
    +
    +

    Modifications to the OpenCL API Specification

    +
    +
    +
    +
    (Modify Section 5.3, Image Objects)
    +
    +
    +
    +
    +
    +
    (Add the following to return conditions to Section 5.3.1, Creating Image Objects)
    +
    +
    +
      +
    • +

      CL_INVALID_IMAGE_SIZE if the image_channel_order is CL_NV21_IMG or CL_YV12_IMG and image dimensions specified in image_desc are not supported for all devices in context.

      +
      • +
    • +

      CL_INVALID_VALUE if the image_channel_order is CL_NV21_IMG or CL_YV12_IMG and the image_desc is not CL_MEM_OBJECT_IMAGE2D.

      +
      • +
    +
    +
    +
    (Add the following to Table 16, Image Format Descriptor)
    +
    +
    + ++++ + + + + + + + + + + + + +
    Image Channel OrderDescription

    CL_NV21_IMG, CL_YV12_IMG

    This format can only be used if image_channel_data_type is CL_UNORM_INT8.

    +
    +
    +
    (Add the following to return conditions to Section 5.3.3, Reading, Writing and Copying Image Objects)
    +
    +
    +
      +
    • +

      CL_INVALID_VALUE if image_channel_order is CL_NV21_IMG or CL_YV12_IMG and the region is not the full size of the image and/or the origin is not (0, 0).

      +
      • +
    +
    +
    +
    (Add the following to return conditions to Section 5.3.4, Filling Image Objects)
    +
    +
    +
      +
    • +

      CL_IMAGE_FORMAT_NOT_SUPPORTED if image_channel_order is CL_NV21_IMG or CL_YV12_IMG.

      +
      • +
    +
    +
    +
    (Add the following to return conditions to Section 5.3.6, Mapping Image Objects)
    +
    +
    +
      +
    • +

      CL_INVALID_VALUE if image_channel_order is CL_NV21_IMG or CL_YV12_IMG and the region is not the full size of the image and/or the origin is not (0, 0).

      +
      • +
    +
    +
    +
    +
    +
    +
    +
    +
    +
    +
    +
    +
    +

    Modifications to the OpenCL C Specification

    +
    +
    +
    +
    (Modify Section 8.2, Addressing and Filter Modes)
    +
    +
    +
    +
    (Replace the following paragraph)
    +
    +

    If the sampler is specified as using unnormalized coordinates (floating-point or integer coordinates), filter mode set to CLK_FILTER_NEAREST and addressing mode set to one of the following modes - CLK_ADDRESS_NONE, CLK_ADDRESS_CLAMP_TO_EDGE or CLK_ADDRESS_CLAMP, the location of the image element in the image given by (i,j,k) will be computed without any loss of precision.

    +
    +

    with

    +
    +
    +

    If the sampler is specified as using unnormalized coordinates (floating-point or integer coordinates), filter mode set to CLK_FILTER_NEAREST and addressing mode set to one of the following modes - CLK_ADDRESS_NONE, CLK_ADDRESS_CLAMP_TO_EDGE or CLK_ADDRESS_CLAMP, and image_channel_order is not CL_NV21_IMG or CL_YV12_IMG, the location of the image element in the image given by (i,j,k) will be computed without any loss of precision.

    +
    +
    +
    +
    +
    +
    +
    +
    +
    +
    +

    Revision History

    +
    + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    VersionDateAuthorChanges

    1.0.0

    2020-11-10

    Jeremy Kemp

    Refreshed to AsciiDoc. Updated Contributors. Updated copyright notice. Updated the OpenCL spec which this extension spec is written against.

    0.3.0

    2018-05-23

    GitHub User H1Gdev

    Remove duplicate 'for' in cl_img_yuv_image.txt.

    0.2.0

    2017-10-17

    James Laverack & Robert Quill

    Replace CL_NV21 and CL_YV12 with CL_NV21_IMG and CL_YV12_IMG respectively.

    0.1.0

    2014-05-02

    James Laverack

    Initial revision.

    +
    +
    +
    + + + + + + \ No newline at end of file diff --git a/extensions/img/cl_img_yuv_image.txt b/extensions/img/cl_img_yuv_image.txt index a455d196..62edad35 100644 --- a/extensions/img/cl_img_yuv_image.txt +++ b/extensions/img/cl_img_yuv_image.txt @@ -1,103 +1,11 @@ -Name +The cl_img_yuv_image.txt extension is no longer authored in plain text. - IMG_yuv_image +Please refer to the HTML extension specification instead, +which may be found here: -Name Strings +https://www.khronos.org/registry/OpenCL/extensions/img/cl_img_yuv_image.html - cl_img_yuv_image +The asciidoc source for this extension specification may +be found here: -Contributors - - James Laverack - Rob Quill - -Contacts - - James Laverack, Imagination Technoligies (james.laverack 'at' imgtec.com) - Rob Quill, Imagination Technoligies (robert.quill 'at' imgtec.com) - -Status - - Approved. - -Version - - Revision: #3, May 23th, 2018 - -Number - - OpenCL Extension #46 - -Dependencies - - Requires OpenCL version 1.2 or later. - - This extension is written against the wording of the OpenCL 1.2 - Specification. - -Overview - - This extension provides new image formats to read YUV images, such - as those provided by cameras on mobile devices. - -New Tokens - - New image channel order enums: - - CL_NV21_IMG 0x40D0 - CL_YV12_IMG 0x40D1 - -Additions to Chapter 5 of the OpenCL 1.2 Specification (Image Objects) - - In Section 5.3.1, page 93, append the following to the list of error - conditions for clCreateImage: - - "CL_INVALID_IMAGE_SIZE if the image_channel_order is CL_NV21_IMG or CL_YV12_IMG - and image dimensions specified in image_desc are not supported for - all devices in context." - - "CL_INVALID_VALUE if the image_channel_order is CL_NV21_IMG or CL_YV12_IMG and - the image_desc is not CL_MEM_OBJECT_IMAGE2D." - - In Section 5.3.1.1, page 94, add the following to Table 5.6: - - "CL_NV21_IMG, CL_YV12_IMG. This format can only be used if channel - data type = CL_UNORM_INT8" - - In Section 5.3.3, page 102, append the following to the list of error - conditions for clEnqueueReadImage and clEnququWriteImage: - - "CL_INVALID_VALUE if image_channel_order is CL_NV21_IMG or CL_YV12_IMG and the region - is not the full size of the image and/or the origin is not (0, 0)." - - In Section 5.3.4, page 108, append the following to the list of error - conditions for clEnqueueFillImage: - - "CL_IMAGE_FORMAT_NOT_SUPPORTED if image_channel_order is CL_NV21_IMG or - CL_YV12_IMG." - - In Section 5.3.6, page 116, append the following to the list of error - conditions for clEnqueueMapImage: - - "CL_INVALID_VALUE if image_channel_order is CL_NV21_IMG or CL_YV12_IMG and the region - is not the full size of the image and/or the origin is not (0, 0)." - -Additions to Chapter 8 of the OpenCL 1.2 Specification (Addressing and Filter Modes) - - In Section 8.2, page 335, replace the first paragraph of the Note with the following - text: - - "If the sampler is specified as using unnormalized coordinates (floating-point or integer - coordinates), filter mode set to CLK_FILTER_NEAREST and addressing mode set to one of the - following modes - CLK_ADDRESS_NONE, CLK_ADDRESS_CLAMP_TO_EDGE or - CLK_ADDRESS_CLAMP, and image_channel_order is not CL_NV21_IMG or CL_YV12_IMG then the location - of the image element in the image given by (i, j, k) in section 8.2 will be computed - without any loss of precision." - -Revision History - -#1 - Initial revision. - -#2 - Replace CL_NV21 and CL_YV12 with CL_NV21_IMG and CL_YV12_IMG respectively. - -#3 - Remove duplicate 'for'. +https://github.com/KhronosGroup/OpenCL-Docs/blob/master/extensions/cl_img_yuv_image.asciidoc \ No newline at end of file diff --git a/extensions/registry.py b/extensions/registry.py index 55ebc484..3ce9ddd8 100644 --- a/extensions/registry.py +++ b/extensions/registry.py @@ -114,17 +114,27 @@ 'cl_img_cached_allocations' : { 'number' : 44, 'flags' : { 'public' }, - 'url' : 'extensions/img/cl_img_cached_allocations.txt', + 'url' : 'extensions/img/cl_img_cached_allocations.html', + }, + 'cl_img_generate_mipmap' : { + 'number' : 66, + 'flags' : { 'public' }, + 'url' : 'extensions/img/cl_img_generate_mipmap.html', + }, + 'cl_img_mem_properties' : { + 'number' : 67, + 'flags' : { 'public' }, + 'url' : 'extensions/img/cl_img_mem_properties.html', }, 'cl_img_use_gralloc_ptr' : { 'number' : 45, 'flags' : { 'public' }, - 'url' : 'extensions/img/cl_img_use_gralloc_ptr.txt', + 'url' : 'extensions/img/cl_img_use_gralloc_ptr.html', }, 'cl_img_yuv_image' : { 'number' : 46, 'flags' : { 'public' }, - 'url' : 'extensions/img/cl_img_yuv_image.txt', + 'url' : 'extensions/img/cl_img_yuv_image.html', }, 'cl_intel_accelerator' : { 'number' : 24,