KhronosGroup / KhronosGroup/OpenCL-Docs

The fill_color parameter to clEnqueueFillImage underspecified

Open
#171 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.