Re: [RFC PATCH] Docbook/media: improve data_offset/bytesused documentation

[Hans Verkuil <hverkuil@xs4all.nl>]

On 07/21/2014 03:30 PM, Nicolas Dufresne wrote:
> Le lundi 21 juillet 2014 à 15:16 +0200, Hans Verkuil a écrit :
>> +             Note that data_offset is included in <structfield>bytesused</structfield>.
>> +             So the size of the image in the plane is
>> +             <structfield>bytesused</structfield>-<structfield>data_offset</structfield> at
>> +             offset <structfield>data_offset</structfield> from the start of the plane.
> 
> This seem like messing applications a lot. Let's say you have a well
> known format, NV12, but your driver add some customer header at the
> beginning. Pretty much all the application in the world would work just
> fine ignoring that header, but in fact most of them will not work,
> because bytesused is including the header. Considering this wasn't
> documented before, I would strongly suggest to keep the bytesused as
> being the size for the format know by everyone.

1) data_offset applies *only* to drivers that use the multiplanar API (i.e. have
V4L2_CAP_VIDEO_CAPTURE/OUTPUT/M2M_MPLANE set). The older single planar API is not
touched by this. So only applications that can handle the mp API should take
data_offset into account.

2) I don't see how it matters whether or not bytesused includes the data_offset.
With a non-zero data_offset and an application that doesn't understand data_offset
it will be wrong either way. In the case of V4L2 'bytesused' has always been the
amount of data that is stored in the buffer. It makes no assumptions on what that
data contains. And that's not going to change.

I've added this patch to a pull request to at least get the documentation fixed,
because the documentation was really not clear on this topic, so that's a real
bug.

Regards,

	Hans