cl_img_generate

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

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

Version	Date	Author	Changes
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.