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