KhronosGroup / KhronosGroup/OpenCL-Docs

Clarify pitch semantics for 2D image from buffer

Open
#674 14 comments 0 reactions 1 assignee Claimed by @bashbaug View on GitHub
OpenCL API Spec
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.