0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002
0003 .. _field-order:
0004
0005 ***********
0006 Field Order
0007 ***********
0008
0009 We have to distinguish between progressive and interlaced video.
0010 Progressive video transmits all lines of a video image sequentially.
0011 Interlaced video divides an image into two fields, containing only the
0012 odd and even lines of the image, respectively. Alternating the so called
0013 odd and even field are transmitted, and due to a small delay between
0014 fields a cathode ray TV displays the lines interleaved, yielding the
0015 original frame. This curious technique was invented because at refresh
0016 rates similar to film the image would fade out too quickly. Transmitting
0017 fields reduces the flicker without the necessity of doubling the frame
0018 rate and with it the bandwidth required for each channel.
0019
0020 It is important to understand a video camera does not expose one frame
0021 at a time, merely transmitting the frames separated into fields. The
0022 fields are in fact captured at two different instances in time. An
0023 object on screen may well move between one field and the next. For
0024 applications analysing motion it is of paramount importance to recognize
0025 which field of a frame is older, the *temporal order*.
0026
0027 When the driver provides or accepts images field by field rather than
0028 interleaved, it is also important applications understand how the fields
0029 combine to frames. We distinguish between top (aka odd) and bottom (aka
0030 even) fields, the *spatial order*: The first line of the top field is
0031 the first line of an interlaced frame, the first line of the bottom
0032 field is the second line of that frame.
0033
0034 However because fields were captured one after the other, arguing
0035 whether a frame commences with the top or bottom field is pointless. Any
0036 two successive top and bottom, or bottom and top fields yield a valid
0037 frame. Only when the source was progressive to begin with, e. g. when
0038 transferring film to video, two fields may come from the same frame,
0039 creating a natural order.
0040
0041 Counter to intuition the top field is not necessarily the older field.
0042 Whether the older field contains the top or bottom lines is a convention
0043 determined by the video standard. Hence the distinction between temporal
0044 and spatial order of fields. The diagrams below should make this
0045 clearer.
0046
0047 In V4L it is assumed that all video cameras transmit fields on the media
0048 bus in the same order they were captured, so if the top field was
0049 captured first (is the older field), the top field is also transmitted
0050 first on the bus.
0051
0052 All video capture and output devices must report the current field
0053 order. Some drivers may permit the selection of a different order, to
0054 this end applications initialize the ``field`` field of struct
0055 :c:type:`v4l2_pix_format` before calling the
0056 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. If this is not desired it
0057 should have the value ``V4L2_FIELD_ANY`` (0).
0058
0059
0060 enum v4l2_field
0061 ===============
0062
0063 .. c:type:: v4l2_field
0064
0065 .. tabularcolumns:: |p{5.8cm}|p{0.6cm}|p{10.9cm}|
0066
0067 .. cssclass:: longtable
0068
0069 .. flat-table::
0070 :header-rows: 0
0071 :stub-columns: 0
0072 :widths: 3 1 4
0073
0074 * - ``V4L2_FIELD_ANY``
0075 - 0
0076 - Applications request this field order when any field format
0077 is acceptable. Drivers choose depending on hardware capabilities or
0078 e.g. the requested image size, and return the actual field order.
0079 Drivers must never return ``V4L2_FIELD_ANY``.
0080 If multiple field orders are possible the
0081 driver must choose one of the possible field orders during
0082 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` or
0083 :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>`. struct
0084 :c:type:`v4l2_buffer` ``field`` can never be
0085 ``V4L2_FIELD_ANY``.
0086 * - ``V4L2_FIELD_NONE``
0087 - 1
0088 - Images are in progressive (frame-based) format, not interlaced
0089 (field-based).
0090 * - ``V4L2_FIELD_TOP``
0091 - 2
0092 - Images consist of the top (aka odd) field only.
0093 * - ``V4L2_FIELD_BOTTOM``
0094 - 3
0095 - Images consist of the bottom (aka even) field only. Applications
0096 may wish to prevent a device from capturing interlaced images
0097 because they will have "comb" or "feathering" artefacts around
0098 moving objects.
0099 * - ``V4L2_FIELD_INTERLACED``
0100 - 4
0101 - Images contain both fields, interleaved line by line. The temporal
0102 order of the fields (whether the top or bottom field is older)
0103 depends on the current video standard. In M/NTSC the bottom
0104 field is the older field. In all other standards the top field
0105 is the older field.
0106 * - ``V4L2_FIELD_SEQ_TB``
0107 - 5
0108 - Images contain both fields, the top field lines are stored first
0109 in memory, immediately followed by the bottom field lines. Fields
0110 are always stored in temporal order, the older one first in
0111 memory. Image sizes refer to the frame, not fields.
0112 * - ``V4L2_FIELD_SEQ_BT``
0113 - 6
0114 - Images contain both fields, the bottom field lines are stored
0115 first in memory, immediately followed by the top field lines.
0116 Fields are always stored in temporal order, the older one first in
0117 memory. Image sizes refer to the frame, not fields.
0118 * - ``V4L2_FIELD_ALTERNATE``
0119 - 7
0120 - The two fields of a frame are passed in separate buffers, in
0121 temporal order, i. e. the older one first. To indicate the field
0122 parity (whether the current field is a top or bottom field) the
0123 driver or application, depending on data direction, must set
0124 struct :c:type:`v4l2_buffer` ``field`` to
0125 ``V4L2_FIELD_TOP`` or ``V4L2_FIELD_BOTTOM``. Any two successive
0126 fields pair to build a frame. If fields are successive, without
0127 any dropped fields between them (fields can drop individually),
0128 can be determined from the struct
0129 :c:type:`v4l2_buffer` ``sequence`` field. This
0130 format cannot be selected when using the read/write I/O method
0131 since there is no way to communicate if a field was a top or
0132 bottom field.
0133 * - ``V4L2_FIELD_INTERLACED_TB``
0134 - 8
0135 - Images contain both fields, interleaved line by line, top field
0136 first. The top field is the older field.
0137 * - ``V4L2_FIELD_INTERLACED_BT``
0138 - 9
0139 - Images contain both fields, interleaved line by line, top field
0140 first. The bottom field is the older field.
0141
0142
0143
0144 .. _fieldseq-tb:
0145
0146 Field Order, Top Field First Transmitted
0147 ========================================
0148
0149 .. kernel-figure:: fieldseq_tb.svg
0150 :alt: fieldseq_tb.svg
0151 :align: center
0152
0153 Field Order, Top Field First Transmitted
0154
0155
0156 .. _fieldseq-bt:
0157
0158 Field Order, Bottom Field First Transmitted
0159 ===========================================
0160
0161 .. kernel-figure:: fieldseq_bt.svg
0162 :alt: fieldseq_bt.svg
0163 :align: center
0164
0165 Field Order, Bottom Field First Transmitted
