Documentation/linux_tv/media/v4l/field-order.rst

   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 .. ------------------------------------------------------------------------------