diff options
Diffstat (limited to 'Documentation/media/uapi/v4l/field-order.rst')
| -rw-r--r-- | Documentation/media/uapi/v4l/field-order.rst | 196 |
1 files changed, 74 insertions, 122 deletions
diff --git a/Documentation/media/uapi/v4l/field-order.rst b/Documentation/media/uapi/v4l/field-order.rst index 979fedbb2bda..50779a67c3fd 100644 --- a/Documentation/media/uapi/v4l/field-order.rst +++ b/Documentation/media/uapi/v4l/field-order.rst @@ -47,140 +47,92 @@ clearer. All video capture and output devices must report the current field order. Some drivers may permit the selection of a different order, to this end applications initialize the ``field`` field of struct -:ref:`v4l2_pix_format <v4l2-pix-format>` before calling the +:c:type:`v4l2_pix_format` before calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. If this is not desired it should have the value ``V4L2_FIELD_ANY`` (0). -.. _v4l2-field: - enum v4l2_field =============== +.. c:type:: v4l2_field + +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| + .. flat-table:: :header-rows: 0 :stub-columns: 0 :widths: 3 1 4 - - - .. row 1 - - - ``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 - driver must choose one of the possible field orders during - :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` or - :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>`. struct - :ref:`v4l2_buffer <v4l2-buffer>` ``field`` can never be - ``V4L2_FIELD_ANY``. - - - .. row 2 - - - ``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``. - - - .. row 3 - - - ``V4L2_FIELD_TOP`` - - - 2 - - - Images consist of the top (aka odd) field only. - - - .. row 4 - - - ``V4L2_FIELD_BOTTOM`` - - - 3 - - - Images consist of the bottom (aka even) field only. Applications - may wish to prevent a device from capturing interlaced images - because they will have "comb" or "feathering" artefacts around - moving objects. - - - .. row 5 - - - ``V4L2_FIELD_INTERLACED`` - - - 4 - - - Images contain both fields, interleaved line by line. The temporal - order of the fields (whether the top or bottom field is first - transmitted) depends on the current video standard. M/NTSC - transmits the bottom field first, all other standards the top - field first. - - - .. row 6 - - - ``V4L2_FIELD_SEQ_TB`` - - - 5 - - - Images contain both fields, the top field lines are stored first - in memory, immediately followed by the bottom field lines. Fields - are always stored in temporal order, the older one first in - memory. Image sizes refer to the frame, not fields. - - - .. row 7 - - - ``V4L2_FIELD_SEQ_BT`` - - - 6 - - - Images contain both fields, the bottom field lines are stored - first in memory, immediately followed by the top field lines. - Fields are always stored in temporal order, the older one first in - memory. Image sizes refer to the frame, not fields. - - - .. row 8 - - - ``V4L2_FIELD_ALTERNATE`` - - - 7 - - - The two fields of a frame are passed in separate buffers, in - temporal order, i. e. the older one first. To indicate the field - parity (whether the current field is a top or bottom field) the - driver or application, depending on data direction, must set - struct :ref:`v4l2_buffer <v4l2-buffer>` ``field`` to - ``V4L2_FIELD_TOP`` or ``V4L2_FIELD_BOTTOM``. Any two successive - fields pair to build a frame. If fields are successive, without - any dropped fields between them (fields can drop individually), - can be determined from the struct - :ref:`v4l2_buffer <v4l2-buffer>` ``sequence`` field. This - format cannot be selected when using the read/write I/O method - since there is no way to communicate if a field was a top or - bottom field. - - - .. row 9 - - - ``V4L2_FIELD_INTERLACED_TB`` - - - 8 - - - Images contain both fields, interleaved line by line, top field - first. The top field is transmitted first. - - - .. row 10 - - - ``V4L2_FIELD_INTERLACED_BT`` - - - 9 - - - Images contain both fields, interleaved line by line, top field - first. The bottom field is transmitted first. + * - ``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 + driver must choose one of the possible field orders during + :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` or + :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>`. struct + :c:type:`v4l2_buffer` ``field`` can never be + ``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``. + * - ``V4L2_FIELD_TOP`` + - 2 + - Images consist of the top (aka odd) field only. + * - ``V4L2_FIELD_BOTTOM`` + - 3 + - Images consist of the bottom (aka even) field only. Applications + may wish to prevent a device from capturing interlaced images + because they will have "comb" or "feathering" artefacts around + moving objects. + * - ``V4L2_FIELD_INTERLACED`` + - 4 + - Images contain both fields, interleaved line by line. The temporal + order of the fields (whether the top or bottom field is first + transmitted) depends on the current video standard. M/NTSC + transmits the bottom field first, all other standards the top + field first. + * - ``V4L2_FIELD_SEQ_TB`` + - 5 + - Images contain both fields, the top field lines are stored first + in memory, immediately followed by the bottom field lines. Fields + are always stored in temporal order, the older one first in + memory. Image sizes refer to the frame, not fields. + * - ``V4L2_FIELD_SEQ_BT`` + - 6 + - Images contain both fields, the bottom field lines are stored + first in memory, immediately followed by the top field lines. + Fields are always stored in temporal order, the older one first in + memory. Image sizes refer to the frame, not fields. + * - ``V4L2_FIELD_ALTERNATE`` + - 7 + - The two fields of a frame are passed in separate buffers, in + temporal order, i. e. the older one first. To indicate the field + parity (whether the current field is a top or bottom field) the + driver or application, depending on data direction, must set + struct :c:type:`v4l2_buffer` ``field`` to + ``V4L2_FIELD_TOP`` or ``V4L2_FIELD_BOTTOM``. Any two successive + fields pair to build a frame. If fields are successive, without + any dropped fields between them (fields can drop individually), + can be determined from the struct + :c:type:`v4l2_buffer` ``sequence`` field. This + format cannot be selected when using the read/write I/O method + since there is no way to communicate if a field was a top or + bottom field. + * - ``V4L2_FIELD_INTERLACED_TB`` + - 8 + - Images contain both fields, interleaved line by line, top field + first. The top field is transmitted first. + * - ``V4L2_FIELD_INTERLACED_BT`` + - 9 + - Images contain both fields, interleaved line by line, top field + first. The bottom field is transmitted first. |