1.. -*- coding: utf-8; mode: rst -*- 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 47All video capture and output devices must report the current field 48order. Some drivers may permit the selection of a different order, to 49this end applications initialize the ``field`` field of struct 50:c:type:`v4l2_pix_format` before calling the 51:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. If this is not desired it 52should have the value ``V4L2_FIELD_ANY`` (0). 53 54 55enum v4l2_field 56=============== 57 58.. c:type:: v4l2_field 59 60.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| 61 62.. flat-table:: 63 :header-rows: 0 64 :stub-columns: 0 65 :widths: 3 1 4 66 67 * - ``V4L2_FIELD_ANY`` 68 - 0 69 - Applications request this field order when any one of the 70 ``V4L2_FIELD_NONE``, ``V4L2_FIELD_TOP``, ``V4L2_FIELD_BOTTOM``, or 71 ``V4L2_FIELD_INTERLACED`` formats is acceptable. Drivers choose 72 depending on hardware capabilities or e. g. the requested image 73 size, and return the actual field order. Drivers must never return 74 ``V4L2_FIELD_ANY``. If multiple field orders are possible the 75 driver must choose one of the possible field orders during 76 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` or 77 :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>`. struct 78 :c:type:`v4l2_buffer` ``field`` can never be 79 ``V4L2_FIELD_ANY``. 80 * - ``V4L2_FIELD_NONE`` 81 - 1 82 - Images are in progressive format, not interlaced. The driver may 83 also indicate this order when it cannot distinguish between 84 ``V4L2_FIELD_TOP`` and ``V4L2_FIELD_BOTTOM``. 85 * - ``V4L2_FIELD_TOP`` 86 - 2 87 - Images consist of the top (aka odd) field only. 88 * - ``V4L2_FIELD_BOTTOM`` 89 - 3 90 - Images consist of the bottom (aka even) field only. Applications 91 may wish to prevent a device from capturing interlaced images 92 because they will have "comb" or "feathering" artefacts around 93 moving objects. 94 * - ``V4L2_FIELD_INTERLACED`` 95 - 4 96 - Images contain both fields, interleaved line by line. The temporal 97 order of the fields (whether the top or bottom field is first 98 transmitted) depends on the current video standard. M/NTSC 99 transmits the bottom field first, all other standards the top 100 field first. 101 * - ``V4L2_FIELD_SEQ_TB`` 102 - 5 103 - Images contain both fields, the top field lines are stored first 104 in memory, immediately followed by the bottom field lines. Fields 105 are always stored in temporal order, the older one first in 106 memory. Image sizes refer to the frame, not fields. 107 * - ``V4L2_FIELD_SEQ_BT`` 108 - 6 109 - Images contain both fields, the bottom field lines are stored 110 first in memory, immediately followed by the top field lines. 111 Fields are always stored in temporal order, the older one first in 112 memory. Image sizes refer to the frame, not fields. 113 * - ``V4L2_FIELD_ALTERNATE`` 114 - 7 115 - The two fields of a frame are passed in separate buffers, in 116 temporal order, i. e. the older one first. To indicate the field 117 parity (whether the current field is a top or bottom field) the 118 driver or application, depending on data direction, must set 119 struct :c:type:`v4l2_buffer` ``field`` to 120 ``V4L2_FIELD_TOP`` or ``V4L2_FIELD_BOTTOM``. Any two successive 121 fields pair to build a frame. If fields are successive, without 122 any dropped fields between them (fields can drop individually), 123 can be determined from the struct 124 :c:type:`v4l2_buffer` ``sequence`` field. This 125 format cannot be selected when using the read/write I/O method 126 since there is no way to communicate if a field was a top or 127 bottom field. 128 * - ``V4L2_FIELD_INTERLACED_TB`` 129 - 8 130 - Images contain both fields, interleaved line by line, top field 131 first. The top field is transmitted first. 132 * - ``V4L2_FIELD_INTERLACED_BT`` 133 - 9 134 - Images contain both fields, interleaved line by line, top field 135 first. The bottom field is transmitted first. 136 137 138 139.. _fieldseq-tb: 140 141Field Order, Top Field First Transmitted 142======================================== 143 144.. kernel-figure:: fieldseq_tb.svg 145 :alt: fieldseq_tb.svg 146 :align: center 147 148 Field Order, Top Field First Transmitted 149 150 151.. _fieldseq-bt: 152 153Field Order, Bottom Field First Transmitted 154=========================================== 155 156.. kernel-figure:: fieldseq_bt.svg 157 :alt: fieldseq_bt.svg 158 :align: center 159 160 Field Order, Bottom Field First Transmitted 161
