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