KhronosGroup / KhronosGroup/OpenCL-Docs
Clarify pitch semantics for 2D image from buffer
- Dominant language
- Python
- Stars
- 420
- Forks
- 131
- Avg merge
- 5d 13h
- Merged PRs (30d)
- 11
Description
For 2D images created from buffers in `clCreateImage`, the following train of logic leads to the conclusion that the row pitch must be set to zero in all cases:
1. CL_MEM_USE_HOST_PTR or CL_MEM_ALLOC_HOST_PTR or CL_MEM_COPY_HOST_PTR are not valid flags for images created from other memory objects
2. _host_ptr_ must be NULL if those flags are not present:
**CL_INVALID_HOST_PTR if _host_ptr_ is NULL and CL_MEM_USE_HOST_PTR or CL_MEM_COPY_HOST_PTR are set in _flags_ or if _host_ptr_ is not NULL but CL_MEM_COPY_HOST_PTR or CL_MEM_USE_HOST_PTR are not set in _flags_.**
Although the 2D image does inherit HOST_PTR flag settings from the buffer object, the language here seems to refer to the actual italicized argument _flags_, not the inherited flag values.
3. _image_row_pitch_ must be set to 0 if _host_ptr_ is NULL
But the last sentence of the _image_row_pitch_ description conflicts with that conclusion by suggesting that the pitch can be specified:
**For a 2D image created from a buffer, 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 the buffer specified by _mem_object_ that support images.**
Questions:
1. Does the last sentence in the _image_row_pitch_ description override item 3 above (ie, _image_row_pitch_ doesn't need to be 0 in the image from buffer case when the _mem_object_ buffer had a CL_MEM_*_HOST_PTR flag)?
2. How is the pitch computed when _image_row_pitch_ is 0 in this case? The sentence
**If host_ptr is not NULL and image_row_pitch = 0, image_row_pitch is calculated as image_width × size of element in bytes.**
doesn't apply since _host_ptr_ is NULL in this case. One possible reading is that the computation forces the row pitch to a multiple of the alignment, but that is imprecise and doesn't give the app a guarantee of what multiple would be chosen as the actual pitch.
Contributor guide
Assessment
This issue has not been assessed yet.