From 823a633eeb7775171cbb9f423401316504745dc7 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Tue, 23 Apr 2019 10:05:09 -0400 Subject: media: field-order.rst: clarify FIELD_ANY and FIELD_NONE Rephrased the FIELD_ANY description: rather than explicitly list field values, just say 'when any field format is acceptable'. The list of FIELD values was outdated, so it was a bit confusing. The FIELD_NONE description said that 'The driver may also indicate this order when it cannot distinguish between V4L2_FIELD_TOP and V4L2_FIELD_BOTTOM'. This is false, NONE really means a full frame and userspace depends on that. So drop this line completely. There are no drivers that do this anyway. FIELD_TOP/BOTTOM/ALTERNATE indicate that the number of lines in the buffer are that of a field, not frame, so returning NONE here would cause huge problems. Finally attempt to clarify 'progressive' and 'interlaced' a little bit. Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/uapi/v4l/field-order.rst | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) (limited to 'Documentation/media') diff --git a/Documentation/media/uapi/v4l/field-order.rst b/Documentation/media/uapi/v4l/field-order.rst index 3fb473e3b8e2..d640e922a974 100644 --- a/Documentation/media/uapi/v4l/field-order.rst +++ b/Documentation/media/uapi/v4l/field-order.rst @@ -75,12 +75,11 @@ enum v4l2_field * - ``V4L2_FIELD_ANY`` - 0 - - Applications request this field order when any one of the - ``V4L2_FIELD_NONE``, ``V4L2_FIELD_TOP``, ``V4L2_FIELD_BOTTOM``, or - ``V4L2_FIELD_INTERLACED`` formats is acceptable. Drivers choose - depending on hardware capabilities or e. g. the requested image - size, and return the actual field order. Drivers must never return - ``V4L2_FIELD_ANY``. If multiple field orders are possible the + - Applications request this field order when any field format + is acceptable. Drivers choose depending on hardware capabilities or + e.g. the requested image size, and return the actual field order. + Drivers must never return ``V4L2_FIELD_ANY``. + If multiple field orders are possible the driver must choose one of the possible field orders during :ref:`VIDIOC_S_FMT ` or :ref:`VIDIOC_TRY_FMT `. struct @@ -88,9 +87,8 @@ enum v4l2_field ``V4L2_FIELD_ANY``. * - ``V4L2_FIELD_NONE`` - 1 - - Images are in progressive format, not interlaced. The driver may - also indicate this order when it cannot distinguish between - ``V4L2_FIELD_TOP`` and ``V4L2_FIELD_BOTTOM``. + - Images are in progressive (frame-based) format, not interlaced + (field-based). * - ``V4L2_FIELD_TOP`` - 2 - Images consist of the top (aka odd) field only. -- cgit v1.2.3-55-g7522