CL_INVALID_IMAGE_FORMAT_DESCRIPTOR error condition

[bashbaug]

Found while refactoring the error conditions for clCreateImageWithProperties:

There is currently an error condition that is specified to return CL_INVALID_IMAGE_FORMAT_DESCRIPTOR:

if an image is created from a buffer and the row pitch, or slice pitch, if the cl_ext_image_from_buffer extension is supported, or base address alignment do not follow the rules described for creating an image from a buffer.

None of the values described in this error condition are part of the image format descriptor (cl_image_format), though. Should this error condition be CL_INVALID_IMAGE_DESCRIPTOR instead?

Originally posted by @bashbaug in https://github.com/KhronosGroup/OpenCL-Docs/pull/1367#discussion_r2124490694

[bashbaug]

I looked at this a bit more after the discussion in the September 2nd teleconference and the problem actually goes back much further than cl_ext_image_from_buffer: If I go all the way back to the OpenCL 1.2 Extension Specification, in the text for cl_khr_image2d_from_buffer we have:

The pitch specified (or computed if pitch specified is 0) must be a multiple of the maximum of the CL_DEVICE_IMAGE_PITCH_ALIGNMENT value for all devices in the context associated with image_desc->buffer and that support images. Otherwise, clCreateImage returns a NULL value with errcode_ret set to CL_INVALID_IMAGE_FORMAT_DESCRIPTOR.

Similar text is also present in the OpenCL 2.x specs after cl_khr_image2d_from_buffer became a core feature:

CL_INVALID_IMAGE_FORMAT_DESCRIPTOR if a 2D image is created from a buffer and the row pitch and base address alignment does not follow the rules described for creating a 2D image from a buffer

Since the problem goes back so far I don't think we'll be able to fix this in a new version of the spec or the cl_ext_image_from_buffer extension. If that's the case:

1. Do we still want to track any TODOs in the asciidoc spec source?
2. Should we consider documenting the odd error code, say via a spec footnote, or is this overkill?