Documentation/media/uapi/v4l/field-order.rst - third_party/kernel - Git at Google

 .. Permission is granted to copy, distribute and/or modify this
 .. document under the terms of the GNU Free Documentation License,
 .. Version 1.1 or any later version published by the Free Software
 .. Foundation, with no Invariant Sections, no Front-Cover Texts
 .. and no Back-Cover Texts. A copy of the license is included at
 .. Documentation/media/uapi/fdl-appendix.rst.
 ..
 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections

 .. _field-order:

 ***********
 Field Order
 ***********

 We have to distinguish between progressive and interlaced video.
 Progressive video transmits all lines of a video image sequentially.
 Interlaced video divides an image into two fields, containing only the
 odd and even lines of the image, respectively. Alternating the so called
 odd and even field are transmitted, and due to a small delay between
 fields a cathode ray TV displays the lines interleaved, yielding the
 original frame. This curious technique was invented because at refresh
 rates similar to film the image would fade out too quickly. Transmitting
 fields reduces the flicker without the necessity of doubling the frame
 rate and with it the bandwidth required for each channel.

 It is important to understand a video camera does not expose one frame
 at a time, merely transmitting the frames separated into fields. The
 fields are in fact captured at two different instances in time. An
 object on screen may well move between one field and the next. For
 applications analysing motion it is of paramount importance to recognize
 which field of a frame is older, the *temporal order*.

 When the driver provides or accepts images field by field rather than
 interleaved, it is also important applications understand how the fields
 combine to frames. We distinguish between top (aka odd) and bottom (aka
 even) fields, the *spatial order*: The first line of the top field is
 the first line of an interlaced frame, the first line of the bottom
 field is the second line of that frame.

 However because fields were captured one after the other, arguing
 whether a frame commences with the top or bottom field is pointless. Any
 two successive top and bottom, or bottom and top fields yield a valid
 frame. Only when the source was progressive to begin with, e. g. when
 transferring film to video, two fields may come from the same frame,
 creating a natural order.

 Counter to intuition the top field is not necessarily the older field.
 Whether the older field contains the top or bottom lines is a convention
 determined by the video standard. Hence the distinction between temporal
 and spatial order of fields. The diagrams below should make this
 clearer.

 In V4L it is assumed that all video cameras transmit fields on the media
 bus in the same order they were captured, so if the top field was
 captured first (is the older field), the top field is also transmitted
 first on the bus.

 All video capture and output devices must report the current field
 order. Some drivers may permit the selection of a different order, to
 this end applications initialize the ``field`` field of struct
 :c:type:`v4l2_pix_format` before calling the
 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. If this is not desired it
 should have the value ``V4L2_FIELD_ANY`` (0).


 enum v4l2_field
 ===============

 .. c:type:: v4l2_field

 .. tabularcolumns:: |p{5.8cm}|p{0.6cm}|p{11.1cm}|

 .. cssclass:: longtable

 .. flat-table::
     :header-rows:  0
     :stub-columns: 0
     :widths:       3 1 4

     * - ``V4L2_FIELD_ANY``
       - 0
       - Applications request this field order when any field format
 	is acceptable. Drivers choose depending on hardware capabilities or
 	e.g. the requested image size, and return the actual field order.
 	Drivers must never return ``V4L2_FIELD_ANY``.
 	If multiple field orders are possible the
 	driver must choose one of the possible field orders during
 	:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` or
 	:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>`. struct
 	:c:type:`v4l2_buffer` ``field`` can never be
 	``V4L2_FIELD_ANY``.
     * - ``V4L2_FIELD_NONE``
       - 1
       - Images are in progressive (frame-based) format, not interlaced
         (field-based).
     * - ``V4L2_FIELD_TOP``
       - 2
       - Images consist of the top (aka odd) field only.
     * - ``V4L2_FIELD_BOTTOM``
       - 3
       - Images consist of the bottom (aka even) field only. Applications
 	may wish to prevent a device from capturing interlaced images
 	because they will have "comb" or "feathering" artefacts around
 	moving objects.
     * - ``V4L2_FIELD_INTERLACED``
       - 4
       - Images contain both fields, interleaved line by line. The temporal
 	order of the fields (whether the top or bottom field is older)
 	depends on the current video standard. In M/NTSC the bottom
 	field is the older field. In all other standards the top field
 	is the older field.
     * - ``V4L2_FIELD_SEQ_TB``
       - 5
       - Images contain both fields, the top field lines are stored first
 	in memory, immediately followed by the bottom field lines. Fields
 	are always stored in temporal order, the older one first in
 	memory. Image sizes refer to the frame, not fields.
     * - ``V4L2_FIELD_SEQ_BT``
       - 6
       - Images contain both fields, the bottom field lines are stored
 	first in memory, immediately followed by the top field lines.
 	Fields are always stored in temporal order, the older one first in
 	memory. Image sizes refer to the frame, not fields.
     * - ``V4L2_FIELD_ALTERNATE``
       - 7
       - The two fields of a frame are passed in separate buffers, in
 	temporal order, i. e. the older one first. To indicate the field
 	parity (whether the current field is a top or bottom field) the
 	driver or application, depending on data direction, must set
 	struct :c:type:`v4l2_buffer` ``field`` to
 	``V4L2_FIELD_TOP`` or ``V4L2_FIELD_BOTTOM``. Any two successive
 	fields pair to build a frame. If fields are successive, without
 	any dropped fields between them (fields can drop individually),
 	can be determined from the struct
 	:c:type:`v4l2_buffer` ``sequence`` field. This
 	format cannot be selected when using the read/write I/O method
 	since there is no way to communicate if a field was a top or
 	bottom field.
     * - ``V4L2_FIELD_INTERLACED_TB``
       - 8
       - Images contain both fields, interleaved line by line, top field
 	first. The top field is the older field.
     * - ``V4L2_FIELD_INTERLACED_BT``
       - 9
       - Images contain both fields, interleaved line by line, top field
 	first. The bottom field is the older field.


 .. _fieldseq-tb:

 Field Order, Top Field First Transmitted
 ========================================

 .. kernel-figure:: fieldseq_tb.svg
     :alt:    fieldseq_tb.svg
     :align:  center

     Field Order, Top Field First Transmitted


 .. _fieldseq-bt:

 Field Order, Bottom Field First Transmitted
 ===========================================

 .. kernel-figure:: fieldseq_bt.svg
     :alt:    fieldseq_bt.svg
     :align:  center

     Field Order, Bottom Field First Transmitted
	.. Permission is granted to copy, distribute and/or modify this
	.. document under the terms of the GNU Free Documentation License,
	.. Version 1.1 or any later version published by the Free Software
	.. Foundation, with no Invariant Sections, no Front-Cover Texts
	.. and no Back-Cover Texts. A copy of the license is included at
	.. Documentation/media/uapi/fdl-appendix.rst.
	..
	.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections

	.. _field-order:

	***********
	Field Order
	***********

	We have to distinguish between progressive and interlaced video.
	Progressive video transmits all lines of a video image sequentially.
	Interlaced video divides an image into two fields, containing only the
	odd and even lines of the image, respectively. Alternating the so called
	odd and even field are transmitted, and due to a small delay between
	fields a cathode ray TV displays the lines interleaved, yielding the
	original frame. This curious technique was invented because at refresh
	rates similar to film the image would fade out too quickly. Transmitting
	fields reduces the flicker without the necessity of doubling the frame
	rate and with it the bandwidth required for each channel.

	It is important to understand a video camera does not expose one frame
	at a time, merely transmitting the frames separated into fields. The
	fields are in fact captured at two different instances in time. An
	object on screen may well move between one field and the next. For
	applications analysing motion it is of paramount importance to recognize
	which field of a frame is older, the temporal order.

	When the driver provides or accepts images field by field rather than
	interleaved, it is also important applications understand how the fields
	combine to frames. We distinguish between top (aka odd) and bottom (aka
	even) fields, the spatial order: The first line of the top field is
	the first line of an interlaced frame, the first line of the bottom
	field is the second line of that frame.

	However because fields were captured one after the other, arguing
	whether a frame commences with the top or bottom field is pointless. Any
	two successive top and bottom, or bottom and top fields yield a valid
	frame. Only when the source was progressive to begin with, e. g. when
	transferring film to video, two fields may come from the same frame,
	creating a natural order.

	Counter to intuition the top field is not necessarily the older field.
	Whether the older field contains the top or bottom lines is a convention
	determined by the video standard. Hence the distinction between temporal
	and spatial order of fields. The diagrams below should make this
	clearer.

	In V4L it is assumed that all video cameras transmit fields on the media
	bus in the same order they were captured, so if the top field was
	captured first (is the older field), the top field is also transmitted
	first on the bus.

	All video capture and output devices must report the current field
	order. Some drivers may permit the selection of a different order, to
	this end applications initialize the ``field`` field of struct
	:c:type:`v4l2_pix_format` before calling the
	:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. If this is not desired it
	should have the value ``V4L2_FIELD_ANY`` (0).


	enum v4l2_field
	===============

	.. c:type:: v4l2_field

	.. tabularcolumns:: \|p{5.8cm}\|p{0.6cm}\|p{11.1cm}\|

	.. cssclass:: longtable

	.. flat-table::
	:header-rows: 0
	:stub-columns: 0
	:widths: 3 1 4

	* - ``V4L2_FIELD_ANY``
	- 0
	- Applications request this field order when any field format
	is acceptable. Drivers choose depending on hardware capabilities or
	e.g. the requested image size, and return the actual field order.
	Drivers must never return ``V4L2_FIELD_ANY``.
	If multiple field orders are possible the
	driver must choose one of the possible field orders during
	:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` or
	:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>`. struct
	:c:type:`v4l2_buffer` ``field`` can never be
	``V4L2_FIELD_ANY``.
	* - ``V4L2_FIELD_NONE``
	- 1
	- Images are in progressive (frame-based) format, not interlaced
	(field-based).
	* - ``V4L2_FIELD_TOP``
	- 2
	- Images consist of the top (aka odd) field only.
	* - ``V4L2_FIELD_BOTTOM``
	- 3
	- Images consist of the bottom (aka even) field only. Applications
	may wish to prevent a device from capturing interlaced images
	because they will have "comb" or "feathering" artefacts around
	moving objects.
	* - ``V4L2_FIELD_INTERLACED``
	- 4
	- Images contain both fields, interleaved line by line. The temporal
	order of the fields (whether the top or bottom field is older)
	depends on the current video standard. In M/NTSC the bottom
	field is the older field. In all other standards the top field
	is the older field.
	* - ``V4L2_FIELD_SEQ_TB``
	- 5
	- Images contain both fields, the top field lines are stored first
	in memory, immediately followed by the bottom field lines. Fields
	are always stored in temporal order, the older one first in
	memory. Image sizes refer to the frame, not fields.
	* - ``V4L2_FIELD_SEQ_BT``
	- 6
	- Images contain both fields, the bottom field lines are stored
	first in memory, immediately followed by the top field lines.
	Fields are always stored in temporal order, the older one first in
	memory. Image sizes refer to the frame, not fields.
	* - ``V4L2_FIELD_ALTERNATE``
	- 7
	- The two fields of a frame are passed in separate buffers, in
	temporal order, i. e. the older one first. To indicate the field
	parity (whether the current field is a top or bottom field) the
	driver or application, depending on data direction, must set
	struct :c:type:`v4l2_buffer` ``field`` to
	``V4L2_FIELD_TOP`` or ``V4L2_FIELD_BOTTOM``. Any two successive
	fields pair to build a frame. If fields are successive, without
	any dropped fields between them (fields can drop individually),
	can be determined from the struct
	:c:type:`v4l2_buffer` ``sequence`` field. This
	format cannot be selected when using the read/write I/O method
	since there is no way to communicate if a field was a top or
	bottom field.
	* - ``V4L2_FIELD_INTERLACED_TB``
	- 8
	- Images contain both fields, interleaved line by line, top field
	first. The top field is the older field.
	* - ``V4L2_FIELD_INTERLACED_BT``
	- 9
	- Images contain both fields, interleaved line by line, top field
	first. The bottom field is the older field.



	.. _fieldseq-tb:

	Field Order, Top Field First Transmitted
	========================================

	.. kernel-figure:: fieldseq_tb.svg
	:alt: fieldseq_tb.svg
	:align: center

	Field Order, Top Field First Transmitted


	.. _fieldseq-bt:

	Field Order, Bottom Field First Transmitted
	===========================================

	.. kernel-figure:: fieldseq_bt.svg
	:alt: fieldseq_bt.svg
	:align: center

	Field Order, Bottom Field First Transmitted