KhronosGroup / KhronosGroup/OpenCL-Docs
The fill_color parameter to clEnqueueFillImage underspecified
- Dominant language
- Python
- Stars
- 420
- Forks
- 131
- Avg merge
- 5d 13h
- Merged PRs (30d)
- 11
Description
The spec currently reads
>The fill color. The fill color is a four component RGBA floating-point color value if the image channel data type is not an unnormalized signed and unsigned integer type, is a four component signed integer value if the image channel data type is an unnormalized signed integer type and is a four component unsigned integer value if the image channel data type is an unormalized unsigned integer type. The fill color will be converted to the appropriate image channel format and order associated with image.
Missing from the specification are:
1. An exact description of types. It is possible to deduce that the parameter is essentially a union between a floating-point value and a signed and an unsigned integer value. The size of the integers is completely unspecified. Vulkan defines an explicit type for this:
```
typedef union VkClearColorValue {
float float32[4];
int32_t int32[4];
uint32_t uint32[4];
} VkClearColorValue;
```
Is that something we'd want to do? I think we could still introduce it without breaking compatibility (the function parameter would have to remain declared as `void*` though).
2. The behaviour for normalized formats isn't really described. It can be deduced from other sections of the spec but this shouldn't be a guessing game. I suggest we add a table of image channel data types with a short description of the field of the union that is used and the conversion rules.
Contributor guide
Research direction
Start with the clEnqueueFillImage fill_color specification text and review the related image channel data type and conversion sections. Compare the proposed VkClearColorValue fields with the existing OpenCL API wording. Done means the specification defines the value types and clearly states normalized-format conversion behavior, ideally in a table.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100