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