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