1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2.. c:namespace:: V4L 3 4.. _field-order: 5 6*********** 7Field Order 8*********** 9 10We have to distinguish between progressive and interlaced video. 11Progressive video transmits all lines of a video image sequentially. 12Interlaced video divides an image into two fields, containing only the 13odd and even lines of the image, respectively. Alternating the so called 14odd and even field are transmitted, and due to a small delay between 15fields a cathode ray TV displays the lines interleaved, yielding the 16original frame. This curious technique was invented because at refresh 17rates similar to film the image would fade out too quickly. Transmitting 18fields reduces the flicker without the necessity of doubling the frame 19rate and with it the bandwidth required for each channel. 20 21It is important to understand a video camera does not expose one frame 22at a time, merely transmitting the frames separated into fields. The 23fields are in fact captured at two different instances in time. An 24object on screen may well move between one field and the next. For 25applications analysing motion it is of paramount importance to recognize 26which field of a frame is older, the *temporal order*. 27 28When the driver provides or accepts images field by field rather than 29interleaved, it is also important applications understand how the fields 30combine to frames. We distinguish between top (aka odd) and bottom (aka 31even) fields, the *spatial order*: The first line of the top field is 32the first line of an interlaced frame, the first line of the bottom 33field is the second line of that frame. 34 35However because fields were captured one after the other, arguing 36whether a frame commences with the top or bottom field is pointless. Any 37two successive top and bottom, or bottom and top fields yield a valid 38frame. Only when the source was progressive to begin with, e. g. when 39transferring film to video, two fields may come from the same frame, 40creating a natural order. 41 42Counter to intuition the top field is not necessarily the older field. 43Whether the older field contains the top or bottom lines is a convention 44determined by the video standard. Hence the distinction between temporal 45and spatial order of fields. The diagrams below should make this 46clearer. 47 48In V4L it is assumed that all video cameras transmit fields on the media 49bus in the same order they were captured, so if the top field was 50captured first (is the older field), the top field is also transmitted 51first on the bus. 52 53All video capture and output devices must report the current field 54order. Some drivers may permit the selection of a different order, to 55this end applications initialize the ``field`` field of struct 56:c:type:`v4l2_pix_format` before calling the 57:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. If this is not desired it 58should have the value ``V4L2_FIELD_ANY`` (0). 59 60 61enum v4l2_field 62=============== 63 64.. c:type:: v4l2_field 65 66.. tabularcolumns:: |p{5.8cm}|p{0.6cm}|p{10.9cm}| 67 68.. cssclass:: longtable 69 70.. flat-table:: 71 :header-rows: 0 72 :stub-columns: 0 73 :widths: 3 1 4 74 75 * - ``V4L2_FIELD_ANY`` 76 - 0 77 - Applications request this field order when any field format 78 is acceptable. Drivers choose depending on hardware capabilities or 79 e.g. the requested image size, and return the actual field order. 80 Drivers must never return ``V4L2_FIELD_ANY``. 81 If multiple field orders are possible the 82 driver must choose one of the possible field orders during 83 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` or 84 :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>`. struct 85 :c:type:`v4l2_buffer` ``field`` can never be 86 ``V4L2_FIELD_ANY``. 87 * - ``V4L2_FIELD_NONE`` 88 - 1 89 - Images are in progressive (frame-based) format, not interlaced 90 (field-based). 91 * - ``V4L2_FIELD_TOP`` 92 - 2 93 - Images consist of the top (aka odd) field only. 94 * - ``V4L2_FIELD_BOTTOM`` 95 - 3 96 - Images consist of the bottom (aka even) field only. Applications 97 may wish to prevent a device from capturing interlaced images 98 because they will have "comb" or "feathering" artefacts around 99 moving objects. 100 * - ``V4L2_FIELD_INTERLACED`` 101 - 4 102 - Images contain both fields, interleaved line by line. The temporal 103 order of the fields (whether the top or bottom field is older) 104 depends on the current video standard. In M/NTSC the bottom 105 field is the older field. In all other standards the top field 106 is the older field. 107 * - ``V4L2_FIELD_SEQ_TB`` 108 - 5 109 - Images contain both fields, the top field lines are stored first 110 in memory, immediately followed by the bottom field lines. Fields 111 are always stored in temporal order, the older one first in 112 memory. Image sizes refer to the frame, not fields. 113 * - ``V4L2_FIELD_SEQ_BT`` 114 - 6 115 - Images contain both fields, the bottom field lines are stored 116 first in memory, immediately followed by the top field lines. 117 Fields are always stored in temporal order, the older one first in 118 memory. Image sizes refer to the frame, not fields. 119 * - ``V4L2_FIELD_ALTERNATE`` 120 - 7 121 - The two fields of a frame are passed in separate buffers, in 122 temporal order, i. e. the older one first. To indicate the field 123 parity (whether the current field is a top or bottom field) the 124 driver or application, depending on data direction, must set 125 struct :c:type:`v4l2_buffer` ``field`` to 126 ``V4L2_FIELD_TOP`` or ``V4L2_FIELD_BOTTOM``. Any two successive 127 fields pair to build a frame. If fields are successive, without 128 any dropped fields between them (fields can drop individually), 129 can be determined from the struct 130 :c:type:`v4l2_buffer` ``sequence`` field. This 131 format cannot be selected when using the read/write I/O method 132 since there is no way to communicate if a field was a top or 133 bottom field. 134 * - ``V4L2_FIELD_INTERLACED_TB`` 135 - 8 136 - Images contain both fields, interleaved line by line, top field 137 first. The top field is the older field. 138 * - ``V4L2_FIELD_INTERLACED_BT`` 139 - 9 140 - Images contain both fields, interleaved line by line, top field 141 first. The bottom field is the older field. 142 143 144 145.. _fieldseq-tb: 146 147Field Order, Top Field First Transmitted 148======================================== 149 150.. kernel-figure:: fieldseq_tb.svg 151 :alt: fieldseq_tb.svg 152 :align: center 153 154 Field Order, Top Field First Transmitted 155 156 157.. _fieldseq-bt: 158 159Field Order, Bottom Field First Transmitted 160=========================================== 161 162.. kernel-figure:: fieldseq_bt.svg 163 :alt: fieldseq_bt.svg 164 :align: center 165 166 Field Order, Bottom Field First Transmitted 167
