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