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