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