Commit | Line | Data |
---|---|---|
5377d91f MH |
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 | |
af4a4d0d | 51 | :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. If this is not desired it |
5377d91f MH |
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 | |
0579e6e3 MCC |
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``. | |
5377d91f MH |
80 | |
81 | - .. row 2 | |
82 | ||
83 | - ``V4L2_FIELD_NONE`` | |
84 | ||
85 | - 1 | |
86 | ||
87 | - Images are in progressive format, not interlaced. The driver may | |
0579e6e3 MCC |
88 | also indicate this order when it cannot distinguish between |
89 | ``V4L2_FIELD_TOP`` and ``V4L2_FIELD_BOTTOM``. | |
5377d91f MH |
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 | |
0579e6e3 MCC |
106 | may wish to prevent a device from capturing interlaced images |
107 | because they will have "comb" or "feathering" artefacts around | |
108 | moving objects. | |
5377d91f MH |
109 | |
110 | - .. row 5 | |
111 | ||
112 | - ``V4L2_FIELD_INTERLACED`` | |
113 | ||
114 | - 4 | |
115 | ||
116 | - Images contain both fields, interleaved line by line. The temporal | |
0579e6e3 MCC |
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. | |
5377d91f MH |
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 | |
0579e6e3 MCC |
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. | |
5377d91f MH |
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 | |
0579e6e3 MCC |
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. | |
5377d91f MH |
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 | |
0579e6e3 MCC |
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. | |
5377d91f MH |
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 | |
0579e6e3 | 171 | first. The top field is transmitted first. |
5377d91f MH |
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 | |
0579e6e3 | 180 | first. The bottom field is transmitted first. |
5377d91f MH |
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 |