Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame] | 1 | .. -*- coding: utf-8; mode: rst -*- |
| 2 | |
| 3 | .. _field-order: |
| 4 | |
| 5 | *********** |
| 6 | Field Order |
| 7 | *********** |
| 8 | |
| 9 | We have to distinguish between progressive and interlaced video. |
| 10 | Progressive video transmits all lines of a video image sequentially. |
| 11 | Interlaced video divides an image into two fields, containing only the |
| 12 | odd and even lines of the image, respectively. Alternating the so called |
| 13 | odd and even field are transmitted, and due to a small delay between |
| 14 | fields a cathode ray TV displays the lines interleaved, yielding the |
| 15 | original frame. This curious technique was invented because at refresh |
| 16 | rates similar to film the image would fade out too quickly. Transmitting |
| 17 | fields reduces the flicker without the necessity of doubling the frame |
| 18 | rate and with it the bandwidth required for each channel. |
| 19 | |
| 20 | It is important to understand a video camera does not expose one frame |
| 21 | at a time, merely transmitting the frames separated into fields. The |
| 22 | fields are in fact captured at two different instances in time. An |
| 23 | object on screen may well move between one field and the next. For |
| 24 | applications analysing motion it is of paramount importance to recognize |
| 25 | which field of a frame is older, the *temporal order*. |
| 26 | |
| 27 | When the driver provides or accepts images field by field rather than |
| 28 | interleaved, it is also important applications understand how the fields |
| 29 | combine to frames. We distinguish between top (aka odd) and bottom (aka |
| 30 | even) fields, the *spatial order*: The first line of the top field is |
| 31 | the first line of an interlaced frame, the first line of the bottom |
| 32 | field is the second line of that frame. |
| 33 | |
| 34 | However because fields were captured one after the other, arguing |
| 35 | whether a frame commences with the top or bottom field is pointless. Any |
| 36 | two successive top and bottom, or bottom and top fields yield a valid |
| 37 | frame. Only when the source was progressive to begin with, e. g. when |
| 38 | transferring film to video, two fields may come from the same frame, |
| 39 | creating a natural order. |
| 40 | |
| 41 | Counter to intuition the top field is not necessarily the older field. |
| 42 | Whether the older field contains the top or bottom lines is a convention |
| 43 | determined by the video standard. Hence the distinction between temporal |
| 44 | and spatial order of fields. The diagrams below should make this |
| 45 | clearer. |
| 46 | |
| 47 | All video capture and output devices must report the current field |
| 48 | order. Some drivers may permit the selection of a different order, to |
| 49 | this end applications initialize the ``field`` field of struct |
| 50 | :ref:`v4l2_pix_format <v4l2-pix-format>` before calling the |
| 51 | :ref:`VIDIOC_S_FMT <vidioc-g-fmt>` ioctl. If this is not desired it |
| 52 | should have the value ``V4L2_FIELD_ANY`` (0). |
| 53 | |
| 54 | |
| 55 | .. _v4l2-field: |
| 56 | |
| 57 | .. flat-table:: enum v4l2_field |
| 58 | :header-rows: 0 |
| 59 | :stub-columns: 0 |
| 60 | :widths: 3 1 4 |
| 61 | |
| 62 | |
| 63 | - .. row 1 |
| 64 | |
| 65 | - ``V4L2_FIELD_ANY`` |
| 66 | |
| 67 | - 0 |
| 68 | |
| 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 | :ref:`v4l2_buffer <v4l2-buffer>` ``field`` can never be |
| 79 | ``V4L2_FIELD_ANY``. |
| 80 | |
| 81 | - .. row 2 |
| 82 | |
| 83 | - ``V4L2_FIELD_NONE`` |
| 84 | |
| 85 | - 1 |
| 86 | |
| 87 | - Images are in progressive format, not interlaced. The driver may |
| 88 | also indicate this order when it cannot distinguish between |
| 89 | ``V4L2_FIELD_TOP`` and ``V4L2_FIELD_BOTTOM``. |
| 90 | |
| 91 | - .. row 3 |
| 92 | |
| 93 | - ``V4L2_FIELD_TOP`` |
| 94 | |
| 95 | - 2 |
| 96 | |
| 97 | - Images consist of the top (aka odd) field only. |
| 98 | |
| 99 | - .. row 4 |
| 100 | |
| 101 | - ``V4L2_FIELD_BOTTOM`` |
| 102 | |
| 103 | - 3 |
| 104 | |
| 105 | - Images consist of the bottom (aka even) field only. Applications |
| 106 | may wish to prevent a device from capturing interlaced images |
| 107 | because they will have "comb" or "feathering" artefacts around |
| 108 | moving objects. |
| 109 | |
| 110 | - .. row 5 |
| 111 | |
| 112 | - ``V4L2_FIELD_INTERLACED`` |
| 113 | |
| 114 | - 4 |
| 115 | |
| 116 | - Images contain both fields, interleaved line by line. The temporal |
| 117 | order of the fields (whether the top or bottom field is first |
| 118 | transmitted) depends on the current video standard. M/NTSC |
| 119 | transmits the bottom field first, all other standards the top |
| 120 | field first. |
| 121 | |
| 122 | - .. row 6 |
| 123 | |
| 124 | - ``V4L2_FIELD_SEQ_TB`` |
| 125 | |
| 126 | - 5 |
| 127 | |
| 128 | - Images contain both fields, the top field lines are stored first |
| 129 | in memory, immediately followed by the bottom field lines. Fields |
| 130 | are always stored in temporal order, the older one first in |
| 131 | memory. Image sizes refer to the frame, not fields. |
| 132 | |
| 133 | - .. row 7 |
| 134 | |
| 135 | - ``V4L2_FIELD_SEQ_BT`` |
| 136 | |
| 137 | - 6 |
| 138 | |
| 139 | - Images contain both fields, the bottom field lines are stored |
| 140 | first in memory, immediately followed by the top field lines. |
| 141 | Fields are always stored in temporal order, the older one first in |
| 142 | memory. Image sizes refer to the frame, not fields. |
| 143 | |
| 144 | - .. row 8 |
| 145 | |
| 146 | - ``V4L2_FIELD_ALTERNATE`` |
| 147 | |
| 148 | - 7 |
| 149 | |
| 150 | - The two fields of a frame are passed in separate buffers, in |
| 151 | temporal order, i. e. the older one first. To indicate the field |
| 152 | parity (whether the current field is a top or bottom field) the |
| 153 | driver or application, depending on data direction, must set |
| 154 | struct :ref:`v4l2_buffer <v4l2-buffer>` ``field`` to |
| 155 | ``V4L2_FIELD_TOP`` or ``V4L2_FIELD_BOTTOM``. Any two successive |
| 156 | fields pair to build a frame. If fields are successive, without |
| 157 | any dropped fields between them (fields can drop individually), |
| 158 | can be determined from the struct |
| 159 | :ref:`v4l2_buffer <v4l2-buffer>` ``sequence`` field. This |
| 160 | format cannot be selected when using the read/write I/O method |
| 161 | since there is no way to communicate if a field was a top or |
| 162 | bottom field. |
| 163 | |
| 164 | - .. row 9 |
| 165 | |
| 166 | - ``V4L2_FIELD_INTERLACED_TB`` |
| 167 | |
| 168 | - 8 |
| 169 | |
| 170 | - Images contain both fields, interleaved line by line, top field |
| 171 | first. The top field is transmitted first. |
| 172 | |
| 173 | - .. row 10 |
| 174 | |
| 175 | - ``V4L2_FIELD_INTERLACED_BT`` |
| 176 | |
| 177 | - 9 |
| 178 | |
| 179 | - Images contain both fields, interleaved line by line, top field |
| 180 | first. The bottom field is transmitted first. |
| 181 | |
| 182 | |
| 183 | |
| 184 | .. _fieldseq-tb: |
| 185 | |
| 186 | .. figure:: field-order_files/fieldseq_tb.* |
| 187 | :alt: fieldseq_tb.pdf / fieldseq_tb.gif |
| 188 | :align: center |
| 189 | |
| 190 | Field Order, Top Field First Transmitted |
| 191 | |
| 192 | |
| 193 | .. _fieldseq-bt: |
| 194 | |
| 195 | .. figure:: field-order_files/fieldseq_bt.* |
| 196 | :alt: fieldseq_bt.pdf / fieldseq_bt.gif |
| 197 | :align: center |
| 198 | |
| 199 | Field Order, Bottom Field First Transmitted |
| 200 | |
| 201 | |
| 202 | |
| 203 | |
| 204 | .. ------------------------------------------------------------------------------ |
| 205 | .. This file was automatically converted from DocBook-XML with the dbxml |
| 206 | .. library (https://github.com/return42/sphkerneldoc). The origin XML comes |
| 207 | .. from the linux kernel, refer to: |
| 208 | .. |
| 209 | .. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook |
| 210 | .. ------------------------------------------------------------------------------ |