The specification for the cmsDoTransformLineStride/BytesPerPlane{In,Out} could be improved

[mrserb]

The specification for the BytesPerPlaneIn/Out parameters of the cmsDoTransformLineStride is not clear for some cases and probably can be improved. As I understand cmsDoTransformXXX API:

1. "Case 1": If the image does not have any gaps between the pixels and lines -> pixel's stride is equal to the pixel's size and line's stride is equal to the "pixel's size" * "the number of pixels" -> the simple call to the cmsDoTransform() can be used.
2. "Case 2": If the lines in the image have some extra padding bytes then as suggested in the tutorial the cmsDoTransform() can be called in the loop per scanline or the cmsDoTransformLineStride can be used as suggested by the "Fast floating point plugin" doc.
3. "Case 3": If the pixels in the image have some extra padding bytes then cmsDoTransform() can be called in the loop per pixel, or the cmsDoTransformLineStride can be used.

For all cases above I tried to use the cmsDoTransformLineStride function, all its parameters are obvious except the BytesPerPlaneIn/Out. According to the documentation "BytesPerPlaneIn{In,Out}: The distance in bytes from one plane to the next one inside a line. Only applies in planar formats.":

Here are a few questions I think the documentation can clarify:

1. Can these parameters be ignored if "planar formats" are not used? if not then:
2. In the "Case 1" above, inside the cmsDoTransform these values are calculated as the "number of pixels" * "pixel's size" which is just all pixels in the image w/o gaps. But is it possible to calculate this value using the "public" CMSAPI? The PixelSize function used in the cmsDoTransform is not public.
3. What these values should contain for the "Case 2" above, when the line has only one "plane": should it be zero, should it be the "number of pixels in the line" * "pixel's size", or it should be equal to the BytesPerLine{In,Out}?
4. What these values should contain for the "Case 3" above, for example, if the pixels of TYPE_ARGB_8 format have 1-byte gap in between, should the 5 be used, which is "size of the pixel" + "size of the gap"?

Thank you for any clarification, probably I misread some docs.

[mm2]

Fixed in 4a3ceda

[mrserb]

Thank you! The new documentation looks great!

[mrserb]

One more question about the "return" of this function. According to the tutorial in Little CMS2, there are no longer error handlers. When a function fails, it just returns the failure status. And there are many functions that actually return their status, but cmsDoTransformLineStride returns nothing, does it mean that it always passes? (assuming that the pointers/offsets are correct - and the app will just crash if pointers/offsets are incorrect)