Missing Spec Descriptions for CL_UNORM_SHORT_565 and CL_UNORM_SHORT_555

[bashbaug]

The OpenCL C and SPIR-V environment specs are missing descriptions in many places regarding the CL_UNORM_SHORT_565 and CL_UNORM_SHORT_555 image channel orders.

For example:

• OpenCL C Section 8.3 Conversion Rules does not describe how CL_UNORM_SHORT_565 or CL_UNORM_SHORT_555 channels are converted to or from a float, precision requirements for the conversion, and any special conversion values.
• The descriptions of the read_image and write_image built-in functions do not describe any cases for CL_UNORM_SHORT_565 or CL_UNORM_SHORT_555.

A few descriptions are also missing for CL_UNORM_INT_101010 and CL_UNORM_INT_101010_2, that should be fixed at the same time.

[kpet]

See point 2 on related #171 as well.

[b-sumner]

There's been some question about exactly which bits in the 16 bit word correspond to R, G, and B as well, so we may want to cover that too. Similarly for 101010 and 101010_2.

[StuartDBrady]

@b-sumner, that seems to be defined in the OpenCL 2.x specifications § 5.3.1.1 Image Format Descriptor, as follows:

For CL_UNORM_SHORT_565, R is in bits 15:11, G is in bits 10:5 and B is in bits 4:0. For CL_UNORM_SHORT_555, bit 15 is undefined, R is in bits 14:10, G in bits 9:5 and B in bits 4:0. For CL_UNORM_INT_101010, bits 31:30 are undefined, R is in bits 29:20, G in bits 19:10 and B in bits 9:0. For CL_UNORM_INT_101010_2, R is in bits 31:22, G in bits 21:12, B in bits 11:2 and A in bits 1:0.

Are the spec changes that are needed limited to the OpenCL C spec and the SPIR-V environment spec, or are wider changes needed?

[joshqti]

Can we revisit this issue? I also noticed it is missing from the spec.

[kpet]

Just bumped into this again. We are missing conversion rules for CL_UNORM_INT_101010_2 in both the OpenCL C and SPIR-V environment specifications. We will also need rules for #1223 either as part of that PR or later on depending on how we want to proceed.

[bashbaug]

Could we do this in two steps?

1. I think there are a bunch of obvious and non-contentious omissions, where CL_UNORM_SHORT_565 and CL_UNORM_SHORT_555 are just plain missing. Basic idea would be to find these (say, by searching for CL_UNORM_INT8) and fix them first.
2. There are also some places though which may need additional discussion, say for the image format conversion rules. These might be more contentious, and may benefit from other changes first (e.g. fix minor bugs regarding image conversion rules #319).

I think we could easily do (1) for the next spec release, but (2) may take more time.

[kpet]

Happy to do this in steps but I have to confess I'm mainly after the more contentious side of CL_UNORM_INT_101010_2 for now. Maybe we could discuss how to best divide and conquer in the next teleconference?

[bashbaug]

There are a bunch of places in the spec that refer to "the pre-defined packed formats". Example:

read_imagef returns floating-point values in the range [0.0, 1.0] for image objects created with image_channel_data_type set to one of the pre-defined packed formats or CL_UNORM_INT8, or CL_UNORM_INT16.

The API spec debatably defines what is considered a "pre-defined packed format", but we could probably do a bit better here:

image_channel_data_type values of CL_UNORM_SHORT_565, CL_UNORM_SHORT_555, CL_UNORM_INT_101010, and CL_UNORM_INT_101010_2 are special cases of packed image formats where the channels of each element are packed into a single unsigned short or unsigned int.

Is the notion of "pre-defined packed image formats" useful, or should we list all of the relevant image formats explicitly instead? The benefit of listing them all explicitly is that they're easily findable if you grep the spec. The disadvantage is that more places in the spec need to be updated when a new pre-defined packed format gets added (see #1223).