166 lines · plain
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later2 3.. _field-order:4 5***********6Field Order7***********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 the12odd and even lines of the image, respectively. Alternating the so called13odd and even field are transmitted, and due to a small delay between14fields a cathode ray TV displays the lines interleaved, yielding the15original frame. This curious technique was invented because at refresh16rates similar to film the image would fade out too quickly. Transmitting17fields reduces the flicker without the necessity of doubling the frame18rate and with it the bandwidth required for each channel.19 20It is important to understand a video camera does not expose one frame21at a time, merely transmitting the frames separated into fields. The22fields are in fact captured at two different instances in time. An23object on screen may well move between one field and the next. For24applications analysing motion it is of paramount importance to recognize25which field of a frame is older, the *temporal order*.26 27When the driver provides or accepts images field by field rather than28interleaved, it is also important applications understand how the fields29combine to frames. We distinguish between top (aka odd) and bottom (aka30even) fields, the *spatial order*: The first line of the top field is31the first line of an interlaced frame, the first line of the bottom32field is the second line of that frame.33 34However because fields were captured one after the other, arguing35whether a frame commences with the top or bottom field is pointless. Any36two successive top and bottom, or bottom and top fields yield a valid37frame. Only when the source was progressive to begin with, e. g. when38transferring 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 convention43determined by the video standard. Hence the distinction between temporal44and spatial order of fields. The diagrams below should make this45clearer.46 47In V4L it is assumed that all video cameras transmit fields on the media48bus in the same order they were captured, so if the top field was49captured first (is the older field), the top field is also transmitted50first on the bus.51 52All video capture and output devices must report the current field53order. Some drivers may permit the selection of a different order, to54this end applications initialize the ``field`` field of struct55:c:type:`v4l2_pix_format` before calling the56:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. If this is not desired it57should have the value ``V4L2_FIELD_ANY`` (0).58 59 60enum v4l2_field61===============62 63.. c:type:: v4l2_field64 65.. tabularcolumns:: |p{5.8cm}|p{0.6cm}|p{10.9cm}|66 67.. cssclass:: longtable68 69.. flat-table::70 :header-rows: 071 :stub-columns: 072 :widths: 3 1 473 74 * - ``V4L2_FIELD_ANY``75 - 076 - Applications request this field order when any field format77 is acceptable. Drivers choose depending on hardware capabilities or78 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 the81 driver must choose one of the possible field orders during82 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` or83 :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>`. struct84 :c:type:`v4l2_buffer` ``field`` can never be85 ``V4L2_FIELD_ANY``.86 * - ``V4L2_FIELD_NONE``87 - 188 - Images are in progressive (frame-based) format, not interlaced89 (field-based).90 * - ``V4L2_FIELD_TOP``91 - 292 - Images consist of the top (aka odd) field only.93 * - ``V4L2_FIELD_BOTTOM``94 - 395 - Images consist of the bottom (aka even) field only. Applications96 may wish to prevent a device from capturing interlaced images97 because they will have "comb" or "feathering" artefacts around98 moving objects.99 * - ``V4L2_FIELD_INTERLACED``100 - 4101 - Images contain both fields, interleaved line by line. The temporal102 order of the fields (whether the top or bottom field is older)103 depends on the current video standard. In M/NTSC the bottom104 field is the older field. In all other standards the top field105 is the older field.106 * - ``V4L2_FIELD_SEQ_TB``107 - 5108 - Images contain both fields, the top field lines are stored first109 in memory, immediately followed by the bottom field lines. Fields110 are always stored in temporal order, the older one first in111 memory. Image sizes refer to the frame, not fields.112 * - ``V4L2_FIELD_SEQ_BT``113 - 6114 - Images contain both fields, the bottom field lines are stored115 first in memory, immediately followed by the top field lines.116 Fields are always stored in temporal order, the older one first in117 memory. Image sizes refer to the frame, not fields.118 * - ``V4L2_FIELD_ALTERNATE``119 - 7120 - The two fields of a frame are passed in separate buffers, in121 temporal order, i. e. the older one first. To indicate the field122 parity (whether the current field is a top or bottom field) the123 driver or application, depending on data direction, must set124 struct :c:type:`v4l2_buffer` ``field`` to125 ``V4L2_FIELD_TOP`` or ``V4L2_FIELD_BOTTOM``. Any two successive126 fields pair to build a frame. If fields are successive, without127 any dropped fields between them (fields can drop individually),128 can be determined from the struct129 :c:type:`v4l2_buffer` ``sequence`` field. This130 format cannot be selected when using the read/write I/O method131 since there is no way to communicate if a field was a top or132 bottom field.133 * - ``V4L2_FIELD_INTERLACED_TB``134 - 8135 - Images contain both fields, interleaved line by line, top field136 first. The top field is the older field.137 * - ``V4L2_FIELD_INTERLACED_BT``138 - 9139 - Images contain both fields, interleaved line by line, top field140 first. The bottom field is the older field.141 142 143 144.. _fieldseq-tb:145 146Field Order, Top Field First Transmitted147========================================148 149.. kernel-figure:: fieldseq_tb.svg150 :alt: fieldseq_tb.svg151 :align: center152 153 Field Order, Top Field First Transmitted154 155 156.. _fieldseq-bt:157 158Field Order, Bottom Field First Transmitted159===========================================160 161.. kernel-figure:: fieldseq_bt.svg162 :alt: fieldseq_bt.svg163 :align: center164 165 Field Order, Bottom Field First Transmitted166