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 | ||
6fa26355 MCC |
57 | enum v4l2_field |
58 | =============== | |
59 | ||
60 | .. flat-table:: | |
5377d91f MH |
61 | :header-rows: 0 |
62 | :stub-columns: 0 | |
63 | :widths: 3 1 4 | |
64 | ||
65 | ||
66 | - .. row 1 | |
67 | ||
68 | - ``V4L2_FIELD_ANY`` | |
69 | ||
70 | - 0 | |
71 | ||
72 | - Applications request this field order when any one of the | |
0579e6e3 MCC |
73 | ``V4L2_FIELD_NONE``, ``V4L2_FIELD_TOP``, ``V4L2_FIELD_BOTTOM``, or |
74 | ``V4L2_FIELD_INTERLACED`` formats is acceptable. Drivers choose | |
75 | depending on hardware capabilities or e. g. the requested image | |
76 | size, and return the actual field order. Drivers must never return | |
77 | ``V4L2_FIELD_ANY``. If multiple field orders are possible the | |
78 | driver must choose one of the possible field orders during | |
79 | :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` or | |
80 | :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>`. struct | |
81 | :ref:`v4l2_buffer <v4l2-buffer>` ``field`` can never be | |
82 | ``V4L2_FIELD_ANY``. | |
5377d91f MH |
83 | |
84 | - .. row 2 | |
85 | ||
86 | - ``V4L2_FIELD_NONE`` | |
87 | ||
88 | - 1 | |
89 | ||
90 | - Images are in progressive format, not interlaced. The driver may | |
0579e6e3 MCC |
91 | also indicate this order when it cannot distinguish between |
92 | ``V4L2_FIELD_TOP`` and ``V4L2_FIELD_BOTTOM``. | |
5377d91f MH |
93 | |
94 | - .. row 3 | |
95 | ||
96 | - ``V4L2_FIELD_TOP`` | |
97 | ||
98 | - 2 | |
99 | ||
100 | - Images consist of the top (aka odd) field only. | |
101 | ||
102 | - .. row 4 | |
103 | ||
104 | - ``V4L2_FIELD_BOTTOM`` | |
105 | ||
106 | - 3 | |
107 | ||
108 | - Images consist of the bottom (aka even) field only. Applications | |
0579e6e3 MCC |
109 | may wish to prevent a device from capturing interlaced images |
110 | because they will have "comb" or "feathering" artefacts around | |
111 | moving objects. | |
5377d91f MH |
112 | |
113 | - .. row 5 | |
114 | ||
115 | - ``V4L2_FIELD_INTERLACED`` | |
116 | ||
117 | - 4 | |
118 | ||
119 | - Images contain both fields, interleaved line by line. The temporal | |
0579e6e3 MCC |
120 | order of the fields (whether the top or bottom field is first |
121 | transmitted) depends on the current video standard. M/NTSC | |
122 | transmits the bottom field first, all other standards the top | |
123 | field first. | |
5377d91f MH |
124 | |
125 | - .. row 6 | |
126 | ||
127 | - ``V4L2_FIELD_SEQ_TB`` | |
128 | ||
129 | - 5 | |
130 | ||
131 | - Images contain both fields, the top field lines are stored first | |
0579e6e3 MCC |
132 | in memory, immediately followed by the bottom field lines. Fields |
133 | are always stored in temporal order, the older one first in | |
134 | memory. Image sizes refer to the frame, not fields. | |
5377d91f MH |
135 | |
136 | - .. row 7 | |
137 | ||
138 | - ``V4L2_FIELD_SEQ_BT`` | |
139 | ||
140 | - 6 | |
141 | ||
142 | - Images contain both fields, the bottom field lines are stored | |
0579e6e3 MCC |
143 | first in memory, immediately followed by the top field lines. |
144 | Fields are always stored in temporal order, the older one first in | |
145 | memory. Image sizes refer to the frame, not fields. | |
5377d91f MH |
146 | |
147 | - .. row 8 | |
148 | ||
149 | - ``V4L2_FIELD_ALTERNATE`` | |
150 | ||
151 | - 7 | |
152 | ||
153 | - The two fields of a frame are passed in separate buffers, in | |
0579e6e3 MCC |
154 | temporal order, i. e. the older one first. To indicate the field |
155 | parity (whether the current field is a top or bottom field) the | |
156 | driver or application, depending on data direction, must set | |
157 | struct :ref:`v4l2_buffer <v4l2-buffer>` ``field`` to | |
158 | ``V4L2_FIELD_TOP`` or ``V4L2_FIELD_BOTTOM``. Any two successive | |
159 | fields pair to build a frame. If fields are successive, without | |
160 | any dropped fields between them (fields can drop individually), | |
161 | can be determined from the struct | |
162 | :ref:`v4l2_buffer <v4l2-buffer>` ``sequence`` field. This | |
163 | format cannot be selected when using the read/write I/O method | |
164 | since there is no way to communicate if a field was a top or | |
165 | bottom field. | |
5377d91f MH |
166 | |
167 | - .. row 9 | |
168 | ||
169 | - ``V4L2_FIELD_INTERLACED_TB`` | |
170 | ||
171 | - 8 | |
172 | ||
173 | - Images contain both fields, interleaved line by line, top field | |
0579e6e3 | 174 | first. The top field is transmitted first. |
5377d91f MH |
175 | |
176 | - .. row 10 | |
177 | ||
178 | - ``V4L2_FIELD_INTERLACED_BT`` | |
179 | ||
180 | - 9 | |
181 | ||
182 | - Images contain both fields, interleaved line by line, top field | |
0579e6e3 | 183 | first. The bottom field is transmitted first. |
5377d91f MH |
184 | |
185 | ||
186 | ||
187 | .. _fieldseq-tb: | |
188 | ||
6fa26355 MCC |
189 | Field Order, Top Field First Transmitted |
190 | ======================================== | |
191 | ||
5377d91f MH |
192 | .. figure:: field-order_files/fieldseq_tb.* |
193 | :alt: fieldseq_tb.pdf / fieldseq_tb.gif | |
194 | :align: center | |
195 | ||
5377d91f MH |
196 | |
197 | .. _fieldseq-bt: | |
198 | ||
6fa26355 MCC |
199 | Field Order, Bottom Field First Transmitted |
200 | =========================================== | |
201 | ||
5377d91f MH |
202 | .. figure:: field-order_files/fieldseq_bt.* |
203 | :alt: fieldseq_bt.pdf / fieldseq_bt.gif | |
204 | :align: center | |
205 |