Debian Codegraph @

Documentation/userspace-api/media/v4l/field-order.rst

raw
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