cmd_sphinx = BUILDDIR=$(BUILDDIR) $(SPHINXBUILD) -b $2 $(ALLSPHINXOPTS) $(BUILDDIR)/$2
htmldocs:
- $(MAKE) BUILDDIR=$(BUILDDIR) -f $(srctree)/Documentation/linux_tv/Makefile $@
+ $(MAKE) BUILDDIR=$(BUILDDIR) -f $(srctree)/Documentation/media/Makefile $@
$(call cmd,sphinx,html)
pdfdocs:
:maxdepth: 2
kernel-documentation
- linux_tv/index
+ media/media_uapi
Indices and tables
==================
+++ /dev/null
-# Generate the *.h.rst files from uAPI headers
-
-PARSER = $(srctree)/Documentation/sphinx/parse-headers.pl
-UAPI = $(srctree)/include/uapi/linux
-SRC_DIR=$(srctree)/Documentation/linux_tv
-
-FILES = audio.h.rst ca.h.rst dmx.h.rst frontend.h.rst net.h.rst video.h.rst \
- videodev2.h.rst
-
-TARGETS := $(addprefix $(BUILDDIR)/, $(FILES))
-
-htmldocs: $(BUILDDIR) ${TARGETS}
-
-$(BUILDDIR):
- $(Q)mkdir -p $@
-
-# Rule to convert a .h file to inline RST documentation
-
-gen_rst = \
- echo ${PARSER} $< $@ $(SRC_DIR)/$(notdir $@).exceptions; \
- ${PARSER} $< $@ $(SRC_DIR)/$(notdir $@).exceptions
-
-quiet_gen_rst = echo ' PARSE $(patsubst $(srctree)/%,%,$<)'; \
- ${PARSER} $< $@ $(SRC_DIR)/$(notdir $@).exceptions
-
-silent_gen_rst = ${gen_rst}
-
-$(BUILDDIR)/audio.h.rst: ${UAPI}/dvb/audio.h ${PARSER} $(SRC_DIR)/audio.h.rst.exceptions
- @$($(quiet)gen_rst)
-
-$(BUILDDIR)/ca.h.rst: ${UAPI}/dvb/ca.h ${PARSER} $(SRC_DIR)/ca.h.rst.exceptions
- @$($(quiet)gen_rst)
-
-$(BUILDDIR)/dmx.h.rst: ${UAPI}/dvb/dmx.h ${PARSER} $(SRC_DIR)/dmx.h.rst.exceptions
- @$($(quiet)gen_rst)
-
-$(BUILDDIR)/frontend.h.rst: ${UAPI}/dvb/frontend.h ${PARSER} $(SRC_DIR)/frontend.h.rst.exceptions
- @$($(quiet)gen_rst)
-
-$(BUILDDIR)/net.h.rst: ${UAPI}/dvb/net.h ${PARSER} $(SRC_DIR)/net.h.rst.exceptions
- @$($(quiet)gen_rst)
-
-$(BUILDDIR)/video.h.rst: ${UAPI}/dvb/video.h ${PARSER} $(SRC_DIR)/video.h.rst.exceptions
- @$($(quiet)gen_rst)
-
-$(BUILDDIR)/videodev2.h.rst: ${UAPI}/videodev2.h ${PARSER} $(SRC_DIR)/videodev2.h.rst.exceptions
- @$($(quiet)gen_rst)
-
-cleandocs:
- -rm ${TARGETS}
+++ /dev/null
-# Ignore header name
-ignore define _DVBAUDIO_H_
-
-# Typedef pointing to structs
-replace typedef audio_karaoke_t audio-karaoke
-
-# Undocumented audio caps, as this is a deprecated API anyway
-ignore define AUDIO_CAP_DTS
-ignore define AUDIO_CAP_LPCM
-ignore define AUDIO_CAP_MP1
-ignore define AUDIO_CAP_MP2
-ignore define AUDIO_CAP_MP3
-ignore define AUDIO_CAP_AAC
-ignore define AUDIO_CAP_OGG
-ignore define AUDIO_CAP_SDDS
-ignore define AUDIO_CAP_AC3
-
-# some typedefs should point to struct/enums
-replace typedef audio_mixer_t audio-mixer
-replace typedef audio_status_t audio-status
+++ /dev/null
-# Ignore header name
-ignore define _DVBCA_H_
-
-# struct ca_slot_info defines
-replace define CA_CI ca-slot-info
-replace define CA_CI_LINK ca-slot-info
-replace define CA_CI_PHYS ca-slot-info
-replace define CA_DESCR ca-slot-info
-replace define CA_SC ca-slot-info
-replace define CA_CI_MODULE_PRESENT ca-slot-info
-replace define CA_CI_MODULE_READY ca-slot-info
-
-# struct ca_descr_info defines
-replace define CA_ECD ca-descr-info
-replace define CA_NDS ca-descr-info
-replace define CA_DSS ca-descr-info
-
-# some typedefs should point to struct/enums
-replace typedef ca_pid_t ca-pid
-replace typedef ca_slot_info_t ca-slot-info
-replace typedef ca_descr_info_t ca-descr-info
-replace typedef ca_caps_t ca-caps
-replace typedef ca_msg_t ca-msg
-replace typedef ca_descr_t ca-descr
+++ /dev/null
-# Ignore header name
-ignore define _UAPI_DVBDMX_H_
-
-# Ignore limit constants
-ignore define DMX_FILTER_SIZE
-
-# dmx-pes-type-t enum symbols
-replace enum dmx_ts_pes dmx-pes-type-t
-replace symbol DMX_PES_AUDIO0 dmx-pes-type-t
-replace symbol DMX_PES_VIDEO0 dmx-pes-type-t
-replace symbol DMX_PES_TELETEXT0 dmx-pes-type-t
-replace symbol DMX_PES_SUBTITLE0 dmx-pes-type-t
-replace symbol DMX_PES_PCR0 dmx-pes-type-t
-replace symbol DMX_PES_AUDIO1 dmx-pes-type-t
-replace symbol DMX_PES_VIDEO1 dmx-pes-type-t
-replace symbol DMX_PES_TELETEXT1 dmx-pes-type-t
-replace symbol DMX_PES_SUBTITLE1 dmx-pes-type-t
-replace symbol DMX_PES_PCR1 dmx-pes-type-t
-replace symbol DMX_PES_AUDIO2 dmx-pes-type-t
-replace symbol DMX_PES_VIDEO2 dmx-pes-type-t
-replace symbol DMX_PES_TELETEXT2 dmx-pes-type-t
-replace symbol DMX_PES_SUBTITLE2 dmx-pes-type-t
-replace symbol DMX_PES_PCR2 dmx-pes-type-t
-replace symbol DMX_PES_AUDIO3 dmx-pes-type-t
-replace symbol DMX_PES_VIDEO3 dmx-pes-type-t
-replace symbol DMX_PES_TELETEXT3 dmx-pes-type-t
-replace symbol DMX_PES_SUBTITLE3 dmx-pes-type-t
-replace symbol DMX_PES_PCR3 dmx-pes-type-t
-replace symbol DMX_PES_OTHER dmx-pes-type-t
-
-# Ignore obsolete symbols
-ignore define DMX_PES_AUDIO
-ignore define DMX_PES_VIDEO
-ignore define DMX_PES_TELETEXT
-ignore define DMX_PES_SUBTITLE
-ignore define DMX_PES_PCR
-
-# dmx_input_t symbols
-replace enum dmx_input dmx-input-t
-replace symbol DMX_IN_FRONTEND dmx-input-t
-replace symbol DMX_IN_DVR dmx-input-t
-
-# dmx_source_t symbols
-replace enum dmx_source dmx-source-t
-replace symbol DMX_SOURCE_FRONT0 dmx-source-t
-replace symbol DMX_SOURCE_FRONT1 dmx-source-t
-replace symbol DMX_SOURCE_FRONT2 dmx-source-t
-replace symbol DMX_SOURCE_FRONT3 dmx-source-t
-replace symbol DMX_SOURCE_DVR0 dmx-source-t
-replace symbol DMX_SOURCE_DVR1 dmx-source-t
-replace symbol DMX_SOURCE_DVR2 dmx-source-t
-replace symbol DMX_SOURCE_DVR3 dmx-source-t
-
-
-# Flags for struct dmx_sct_filter_params
-replace define DMX_CHECK_CRC dmx-sct-filter-params
-replace define DMX_ONESHOT dmx-sct-filter-params
-replace define DMX_IMMEDIATE_START dmx-sct-filter-params
-replace define DMX_KERNEL_CLIENT dmx-sct-filter-params
-
-# some typedefs should point to struct/enums
-replace typedef dmx_caps_t dmx-caps
-replace typedef dmx_filter_t dmx-filter
+++ /dev/null
-# Ignore header name
-ignore define _DVBFRONTEND_H_
-
-# Group layer A-C symbols together
-replace define DTV_ISDBT_LAYERA_FEC dtv-isdbt-layer-fec
-replace define DTV_ISDBT_LAYERB_FEC dtv-isdbt-layer-fec
-replace define DTV_ISDBT_LAYERC_FEC dtv-isdbt-layer-fec
-replace define DTV_ISDBT_LAYERA_MODULATION dtv-isdbt-layer-modulation
-replace define DTV_ISDBT_LAYERB_MODULATION dtv-isdbt-layer-modulation
-replace define DTV_ISDBT_LAYERC_MODULATION dtv-isdbt-layer-modulation
-replace define DTV_ISDBT_LAYERA_SEGMENT_COUNT dtv-isdbt-layer-segment-count
-replace define DTV_ISDBT_LAYERB_SEGMENT_COUNT dtv-isdbt-layer-segment-count
-replace define DTV_ISDBT_LAYERC_SEGMENT_COUNT dtv-isdbt-layer-segment-count
-replace define DTV_ISDBT_LAYERA_TIME_INTERLEAVING dtv-isdbt-layer-time-interleaving
-replace define DTV_ISDBT_LAYERB_TIME_INTERLEAVING dtv-isdbt-layer-time-interleaving
-replace define DTV_ISDBT_LAYERC_TIME_INTERLEAVING dtv-isdbt-layer-time-interleaving
-
-# Ignore legacy defines
-ignore define DTV_ISDBS_TS_ID_LEGACY
-ignore define SYS_DVBC_ANNEX_AC
-ignore define SYS_DMBTH
-
-# Ignore limits
-ignore define DTV_MAX_COMMAND
-ignore define MAX_DTV_STATS
-ignore define DTV_IOCTL_MAX_MSGS
-
-# Stats enum is documented altogether
-replace enum fecap_scale_params frontend-stat-properties
-replace symbol FE_SCALE_COUNTER frontend-stat-properties
-replace symbol FE_SCALE_DECIBEL frontend-stat-properties
-replace symbol FE_SCALE_NOT_AVAILABLE frontend-stat-properties
-replace symbol FE_SCALE_RELATIVE frontend-stat-properties
-
-# the same reference is used for both get and set ioctls
-replace ioctl FE_SET_PROPERTY FE_GET_PROPERTY
-
-# Ignore struct used only internally at Kernel
-ignore struct dtv_cmds_h
-
-# Typedefs that use the enum reference
-replace typedef fe_sec_voltage_t fe-sec-voltage
-
-# Replaces for flag constants
-replace define FE_TUNE_MODE_ONESHOT fe_set_frontend_tune_mode
-replace define LNA_AUTO dtv-lna
-replace define NO_STREAM_ID_FILTER dtv-stream-id
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. include:: <isonum.txt>
-
-##############################
-Linux Media Infrastructure API
-##############################
-
-**Copyright** |copy| 2009-2016 : LinuxTV Developers
-
-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. A copy of
-the license is included in the chapter entitled "GNU Free Documentation
-License".
-
-
-============
-Introduction
-============
-
-This document covers the Linux Kernel to Userspace API's used by video
-and radio streaming devices, including video cameras, analog and digital
-TV receiver cards, AM/FM receiver cards, Software Defined Radio (SDR),
-streaming capture and output devices, codec devices and remote controllers.
-
-A typical media device hardware is shown at
-:ref:`typical_media_device`.
-
-
-.. _typical_media_device:
-
-.. figure:: media_api_files/typical_media_device.*
- :alt: typical_media_device.svg
- :align: center
-
- Typical Media Device
-
-The media infrastructure API was designed to control such devices. It is
-divided into four parts.
-
-The :Ref:`first part <v4l2spec>` covers radio, video capture and output,
-cameras, analog TV devices and codecs.
-
-The :Ref:`second part <dvbapi>` covers the API used for digital TV and
-Internet reception via one of the several digital tv standards. While it
-is called as DVB API, in fact it covers several different video
-standards including DVB-T/T2, DVB-S/S2, DVB-C, ATSC, ISDB-T, ISDB-S,
-DTMB, etc. The complete list of supported standards can be found at
-:ref:`fe-delivery-system-t`.
-
-The :Ref:`third part <remote_controllers>` covers the Remote Controller API.
-
-The :Ref:`fourth part <media_controller>` covers the Media Controller API.
-
-It should also be noted that a media device may also have audio
-components, like mixers, PCM capture, PCM playback, etc, which are
-controlled via ALSA API.
-
-For additional information and for the latest development code, see:
-`https://linuxtv.org <https://linuxtv.org>`__.
-
-For discussing improvements, reporting troubles, sending new drivers,
-etc, please mail to:
-`Linux Media Mailing List (LMML). <http://vger.kernel.org/vger-lists.html#linux-media>`__.
-
-
-.. toctree::
- :maxdepth: 1
-
- media/v4l/v4l2
- media/dvb/dvbapi
- media/rc/remote_controllers
- media/mediactl/media-controller
- media/gen-errors
- media/fdl-appendix
-
-.. only:: html
-
- Retrieval
- =========
-
- * :ref:`genindex`
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _AUDIO_BILINGUAL_CHANNEL_SELECT:
-
-==============================
-AUDIO_BILINGUAL_CHANNEL_SELECT
-==============================
-
-Name
-----
-
-AUDIO_BILINGUAL_CHANNEL_SELECT
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(int fd, int request = AUDIO_BILINGUAL_CHANNEL_SELECT, audio_channel_select_t)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals AUDIO_BILINGUAL_CHANNEL_SELECT for this command.
-
- - .. row 3
-
- - audio_channel_select_t ch
-
- - Select the output format of the audio (mono left/right, stereo).
-
-
-Description
------------
-
-This ioctl is obsolete. Do not use in new drivers. It has been replaced
-by the V4L2 ``V4L2_CID_MPEG_AUDIO_DEC_MULTILINGUAL_PLAYBACK`` control
-for MPEG decoders controlled through V4L2.
-
-This ioctl call asks the Audio Device to select the requested channel
-for bilingual streams if possible.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _AUDIO_CHANNEL_SELECT:
-
-====================
-AUDIO_CHANNEL_SELECT
-====================
-
-Name
-----
-
-AUDIO_CHANNEL_SELECT
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(int fd, int request = AUDIO_CHANNEL_SELECT, audio_channel_select_t)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals AUDIO_CHANNEL_SELECT for this command.
-
- - .. row 3
-
- - audio_channel_select_t ch
-
- - Select the output format of the audio (mono left/right, stereo).
-
-
-Description
------------
-
-This ioctl is for DVB devices only. To control a V4L2 decoder use the
-V4L2 ``V4L2_CID_MPEG_AUDIO_DEC_PLAYBACK`` control instead.
-
-This ioctl call asks the Audio Device to select the requested channel if
-possible.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _AUDIO_CLEAR_BUFFER:
-
-==================
-AUDIO_CLEAR_BUFFER
-==================
-
-Name
-----
-
-AUDIO_CLEAR_BUFFER
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(int fd, int request = AUDIO_CLEAR_BUFFER)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals AUDIO_CLEAR_BUFFER for this command.
-
-
-Description
------------
-
-This ioctl call asks the Audio Device to clear all software and hardware
-buffers of the audio decoder device.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _AUDIO_CONTINUE:
-
-==============
-AUDIO_CONTINUE
-==============
-
-Name
-----
-
-AUDIO_CONTINUE
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(int fd, int request = AUDIO_CONTINUE)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals AUDIO_CONTINUE for this command.
-
-
-Description
------------
-
-This ioctl restarts the decoding and playing process previously paused
-with AUDIO_PAUSE command.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _audio_fclose:
-
-=================
-DVB audio close()
-=================
-
-Name
-----
-
-DVB audio close()
-
-
-Synopsis
---------
-
-.. cpp:function:: int close(int fd)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
-
-Description
------------
-
-This system call closes a previously opened audio device.
-
-
-Return Value
-------------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``EBADF``
-
- - fd is not a valid open file descriptor.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _audio_fopen:
-
-================
-DVB audio open()
-================
-
-Name
-----
-
-DVB audio open()
-
-
-Synopsis
---------
-
-.. cpp:function:: int open(const char *deviceName, int flags)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - const char \*deviceName
-
- - Name of specific audio device.
-
- - .. row 2
-
- - int flags
-
- - A bit-wise OR of the following flags:
-
- - .. row 3
-
- -
- - O_RDONLY read-only access
-
- - .. row 4
-
- -
- - O_RDWR read/write access
-
- - .. row 5
-
- -
- - O_NONBLOCK open in non-blocking mode
-
- - .. row 6
-
- -
- - (blocking mode is the default)
-
-
-Description
------------
-
-This system call opens a named audio device (e.g.
-/dev/dvb/adapter0/audio0) for subsequent use. When an open() call has
-succeeded, the device will be ready for use. The significance of
-blocking or non-blocking mode is described in the documentation for
-functions where there is a difference. It does not affect the semantics
-of the open() call itself. A device opened in blocking mode can later be
-put into non-blocking mode (and vice versa) using the F_SETFL command
-of the fcntl system call. This is a standard system call, documented in
-the Linux manual page for fcntl. Only one user can open the Audio Device
-in O_RDWR mode. All other attempts to open the device in this mode will
-fail, and an error code will be returned. If the Audio Device is opened
-in O_RDONLY mode, the only ioctl call that can be used is
-AUDIO_GET_STATUS. All other call will return with an error code.
-
-
-Return Value
-------------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``ENODEV``
-
- - Device driver not loaded/available.
-
- - .. row 2
-
- - ``EBUSY``
-
- - Device or resource busy.
-
- - .. row 3
-
- - ``EINVAL``
-
- - Invalid argument.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _audio_fwrite:
-
-=================
-DVB audio write()
-=================
-
-Name
-----
-
-DVB audio write()
-
-
-Synopsis
---------
-
-.. cpp:function:: size_t write(int fd, const void *buf, size_t count)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - void \*buf
-
- - Pointer to the buffer containing the PES data.
-
- - .. row 3
-
- - size_t count
-
- - Size of buf.
-
-
-Description
------------
-
-This system call can only be used if AUDIO_SOURCE_MEMORY is selected
-in the ioctl call AUDIO_SELECT_SOURCE. The data provided shall be in
-PES format. If O_NONBLOCK is not specified the function will block
-until buffer space is available. The amount of data to be transferred is
-implied by count.
-
-
-Return Value
-------------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``EPERM``
-
- - Mode AUDIO_SOURCE_MEMORY not selected.
-
- - .. row 2
-
- - ``ENOMEM``
-
- - Attempted to write more data than the internal buffer can hold.
-
- - .. row 3
-
- - ``EBADF``
-
- - fd is not a valid open file descriptor.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _AUDIO_GET_CAPABILITIES:
-
-======================
-AUDIO_GET_CAPABILITIES
-======================
-
-Name
-----
-
-AUDIO_GET_CAPABILITIES
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(int fd, int request = AUDIO_GET_CAPABILITIES, unsigned int *cap)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals AUDIO_GET_CAPABILITIES for this command.
-
- - .. row 3
-
- - unsigned int \*cap
-
- - Returns a bit array of supported sound formats.
-
-
-Description
------------
-
-This ioctl call asks the Audio Device to tell us about the decoding
-capabilities of the audio hardware.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _AUDIO_GET_PTS:
-
-=============
-AUDIO_GET_PTS
-=============
-
-Name
-----
-
-AUDIO_GET_PTS
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(int fd, int request = AUDIO_GET_PTS, __u64 *pts)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals AUDIO_GET_PTS for this command.
-
- - .. row 3
-
- - __u64 \*pts
-
- - Returns the 33-bit timestamp as defined in ITU T-REC-H.222.0 /
- ISO/IEC 13818-1.
-
- The PTS should belong to the currently played frame if possible,
- but may also be a value close to it like the PTS of the last
- decoded frame or the last PTS extracted by the PES parser.
-
-
-Description
------------
-
-This ioctl is obsolete. Do not use in new drivers. If you need this
-functionality, then please contact the linux-media mailing list
-(`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__).
-
-This ioctl call asks the Audio Device to return the current PTS
-timestamp.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _AUDIO_GET_STATUS:
-
-================
-AUDIO_GET_STATUS
-================
-
-Name
-----
-
-AUDIO_GET_STATUS
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(int fd, int request = AUDIO_GET_STATUS, struct audio_status *status)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals AUDIO_GET_STATUS for this command.
-
- - .. row 3
-
- - struct audio_status \*status
-
- - Returns the current state of Audio Device.
-
-
-Description
------------
-
-This ioctl call asks the Audio Device to return the current state of the
-Audio Device.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _AUDIO_PAUSE:
-
-===========
-AUDIO_PAUSE
-===========
-
-Name
-----
-
-AUDIO_PAUSE
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(int fd, int request = AUDIO_PAUSE)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals AUDIO_PAUSE for this command.
-
-
-Description
------------
-
-This ioctl call suspends the audio stream being played. Decoding and
-playing are paused. It is then possible to restart again decoding and
-playing process of the audio stream using AUDIO_CONTINUE command.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _AUDIO_PLAY:
-
-==========
-AUDIO_PLAY
-==========
-
-Name
-----
-
-AUDIO_PLAY
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(int fd, int request = AUDIO_PLAY)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals AUDIO_PLAY for this command.
-
-
-Description
------------
-
-This ioctl call asks the Audio Device to start playing an audio stream
-from the selected source.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _AUDIO_SELECT_SOURCE:
-
-===================
-AUDIO_SELECT_SOURCE
-===================
-
-Name
-----
-
-AUDIO_SELECT_SOURCE
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(int fd, int request = AUDIO_SELECT_SOURCE, audio_stream_source_t source)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals AUDIO_SELECT_SOURCE for this command.
-
- - .. row 3
-
- - audio_stream_source_t source
-
- - Indicates the source that shall be used for the Audio stream.
-
-
-Description
------------
-
-This ioctl call informs the audio device which source shall be used for
-the input data. The possible sources are demux or memory. If
-AUDIO_SOURCE_MEMORY is selected, the data is fed to the Audio Device
-through the write command.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _AUDIO_SET_ATTRIBUTES:
-
-====================
-AUDIO_SET_ATTRIBUTES
-====================
-
-Name
-----
-
-AUDIO_SET_ATTRIBUTES
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(fd, int request = AUDIO_SET_ATTRIBUTES, audio_attributes_t attr )
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals AUDIO_SET_ATTRIBUTES for this command.
-
- - .. row 3
-
- - audio_attributes_t attr
-
- - audio attributes according to section ??
-
-
-Description
------------
-
-This ioctl is intended for DVD playback and allows you to set certain
-information about the audio stream.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``EINVAL``
-
- - attr is not a valid or supported attribute setting.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _AUDIO_SET_AV_SYNC:
-
-=================
-AUDIO_SET_AV_SYNC
-=================
-
-Name
-----
-
-AUDIO_SET_AV_SYNC
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(int fd, int request = AUDIO_SET_AV_SYNC, boolean state)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals AUDIO_AV_SYNC for this command.
-
- - .. row 3
-
- - boolean state
-
- - Tells the DVB subsystem if A/V synchronization shall be ON or OFF.
-
- - .. row 4
-
- -
- - TRUE AV-sync ON
-
- - .. row 5
-
- -
- - FALSE AV-sync OFF
-
-
-Description
------------
-
-This ioctl call asks the Audio Device to turn ON or OFF A/V
-synchronization.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _AUDIO_SET_BYPASS_MODE:
-
-=====================
-AUDIO_SET_BYPASS_MODE
-=====================
-
-Name
-----
-
-AUDIO_SET_BYPASS_MODE
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(int fd, int request = AUDIO_SET_BYPASS_MODE, boolean mode)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals AUDIO_SET_BYPASS_MODE for this command.
-
- - .. row 3
-
- - boolean mode
-
- - Enables or disables the decoding of the current Audio stream in
- the DVB subsystem.
-
- - .. row 4
-
- -
- - TRUE Bypass is disabled
-
- - .. row 5
-
- -
- - FALSE Bypass is enabled
-
-
-Description
------------
-
-This ioctl call asks the Audio Device to bypass the Audio decoder and
-forward the stream without decoding. This mode shall be used if streams
-that can’t be handled by the DVB system shall be decoded. Dolby
-DigitalTM streams are automatically forwarded by the DVB subsystem if
-the hardware can handle it.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _AUDIO_SET_EXT_ID:
-
-================
-AUDIO_SET_EXT_ID
-================
-
-Name
-----
-
-AUDIO_SET_EXT_ID
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(fd, int request = AUDIO_SET_EXT_ID, int id)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals AUDIO_SET_EXT_ID for this command.
-
- - .. row 3
-
- - int id
-
- - audio sub_stream_id
-
-
-Description
------------
-
-This ioctl can be used to set the extension id for MPEG streams in DVD
-playback. Only the first 3 bits are recognized.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``EINVAL``
-
- - id is not a valid id.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _AUDIO_SET_ID:
-
-============
-AUDIO_SET_ID
-============
-
-Name
-----
-
-AUDIO_SET_ID
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(int fd, int request = AUDIO_SET_ID, int id)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals AUDIO_SET_ID for this command.
-
- - .. row 3
-
- - int id
-
- - audio sub-stream id
-
-
-Description
------------
-
-This ioctl selects which sub-stream is to be decoded if a program or
-system stream is sent to the video device. If no audio stream type is
-set the id has to be in [0xC0,0xDF] for MPEG sound, in [0x80,0x87] for
-AC3 and in [0xA0,0xA7] for LPCM. More specifications may follow for
-other stream types. If the stream type is set the id just specifies the
-substream id of the audio stream and only the first 5 bits are
-recognized.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _AUDIO_SET_KARAOKE:
-
-=================
-AUDIO_SET_KARAOKE
-=================
-
-Name
-----
-
-AUDIO_SET_KARAOKE
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(fd, int request = AUDIO_SET_KARAOKE, audio_karaoke_t *karaoke)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals AUDIO_SET_KARAOKE for this command.
-
- - .. row 3
-
- - audio_karaoke_t \*karaoke
-
- - karaoke settings according to section ??.
-
-
-Description
------------
-
-This ioctl allows one to set the mixer settings for a karaoke DVD.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``EINVAL``
-
- - karaoke is not a valid or supported karaoke setting.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _AUDIO_SET_MIXER:
-
-===============
-AUDIO_SET_MIXER
-===============
-
-Name
-----
-
-AUDIO_SET_MIXER
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(int fd, int request = AUDIO_SET_MIXER, audio_mixer_t *mix)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals AUDIO_SET_ID for this command.
-
- - .. row 3
-
- - audio_mixer_t \*mix
-
- - mixer settings.
-
-
-Description
------------
-
-This ioctl lets you adjust the mixer settings of the audio decoder.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _AUDIO_SET_MUTE:
-
-==============
-AUDIO_SET_MUTE
-==============
-
-Name
-----
-
-AUDIO_SET_MUTE
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(int fd, int request = AUDIO_SET_MUTE, boolean state)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals AUDIO_SET_MUTE for this command.
-
- - .. row 3
-
- - boolean state
-
- - Indicates if audio device shall mute or not.
-
- - .. row 4
-
- -
- - TRUE Audio Mute
-
- - .. row 5
-
- -
- - FALSE Audio Un-mute
-
-
-Description
------------
-
-This ioctl is for DVB devices only. To control a V4L2 decoder use the
-V4L2 :ref:`VIDIOC_DECODER_CMD` with the
-``V4L2_DEC_CMD_START_MUTE_AUDIO`` flag instead.
-
-This ioctl call asks the audio device to mute the stream that is
-currently being played.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _AUDIO_SET_STREAMTYPE:
-
-====================
-AUDIO_SET_STREAMTYPE
-====================
-
-Name
-----
-
-AUDIO_SET_STREAMTYPE
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(fd, int request = AUDIO_SET_STREAMTYPE, int type)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals AUDIO_SET_STREAMTYPE for this command.
-
- - .. row 3
-
- - int type
-
- - stream type
-
-
-Description
------------
-
-This ioctl tells the driver which kind of audio stream to expect. This
-is useful if the stream offers several audio sub-streams like LPCM and
-AC3.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``EINVAL``
-
- - type is not a valid or supported stream type.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _AUDIO_STOP:
-
-==========
-AUDIO_STOP
-==========
-
-Name
-----
-
-AUDIO_STOP
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(int fd, int request = AUDIO_STOP)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals AUDIO_STOP for this command.
-
-
-Description
------------
-
-This ioctl call asks the Audio Device to stop playing the current
-stream.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _dvb_audio:
-
-################
-DVB Audio Device
-################
-The DVB audio device controls the MPEG2 audio decoder of the DVB
-hardware. It can be accessed through ``/dev/dvb/adapter?/audio?``. Data
-types and and ioctl definitions can be accessed by including
-``linux/dvb/audio.h`` in your application.
-
-Please note that some DVB cards don’t have their own MPEG decoder, which
-results in the omission of the audio and video device.
-
-These ioctls were also used by V4L2 to control MPEG decoders implemented
-in V4L2. The use of these ioctls for that purpose has been made obsolete
-and proper V4L2 ioctls or controls have been created to replace that
-functionality.
-
-
-.. toctree::
- :maxdepth: 1
-
- audio_data_types
- audio_function_calls
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _audio_data_types:
-
-****************
-Audio Data Types
-****************
-
-This section describes the structures, data types and defines used when
-talking to the audio device.
-
-
-.. _audio-stream-source-t:
-
-audio_stream_source_t
-=====================
-
-The audio stream source is set through the AUDIO_SELECT_SOURCE call
-and can take the following values, depending on whether we are replaying
-from an internal (demux) or external (user write) source.
-
-
-.. code-block:: c
-
- typedef enum {
- AUDIO_SOURCE_DEMUX,
- AUDIO_SOURCE_MEMORY
- } audio_stream_source_t;
-
-AUDIO_SOURCE_DEMUX selects the demultiplexer (fed either by the
-frontend or the DVR device) as the source of the video stream. If
-AUDIO_SOURCE_MEMORY is selected the stream comes from the application
-through the ``write()`` system call.
-
-
-.. _audio-play-state-t:
-
-audio_play_state_t
-==================
-
-The following values can be returned by the AUDIO_GET_STATUS call
-representing the state of audio playback.
-
-
-.. code-block:: c
-
- typedef enum {
- AUDIO_STOPPED,
- AUDIO_PLAYING,
- AUDIO_PAUSED
- } audio_play_state_t;
-
-
-.. _audio-channel-select-t:
-
-audio_channel_select_t
-======================
-
-The audio channel selected via AUDIO_CHANNEL_SELECT is determined by
-the following values.
-
-
-.. code-block:: c
-
- typedef enum {
- AUDIO_STEREO,
- AUDIO_MONO_LEFT,
- AUDIO_MONO_RIGHT,
- AUDIO_MONO,
- AUDIO_STEREO_SWAPPED
- } audio_channel_select_t;
-
-
-.. _audio-status:
-
-struct audio_status
-===================
-
-The AUDIO_GET_STATUS call returns the following structure informing
-about various states of the playback operation.
-
-
-.. code-block:: c
-
- typedef struct audio_status {
- boolean AV_sync_state;
- boolean mute_state;
- audio_play_state_t play_state;
- audio_stream_source_t stream_source;
- audio_channel_select_t channel_select;
- boolean bypass_mode;
- audio_mixer_t mixer_state;
- } audio_status_t;
-
-
-.. _audio-mixer:
-
-struct audio_mixer
-==================
-
-The following structure is used by the AUDIO_SET_MIXER call to set the
-audio volume.
-
-
-.. code-block:: c
-
- typedef struct audio_mixer {
- unsigned int volume_left;
- unsigned int volume_right;
- } audio_mixer_t;
-
-
-.. _audio_encodings:
-
-audio encodings
-===============
-
-A call to AUDIO_GET_CAPABILITIES returns an unsigned integer with the
-following bits set according to the hardwares capabilities.
-
-
-.. code-block:: c
-
- #define AUDIO_CAP_DTS 1
- #define AUDIO_CAP_LPCM 2
- #define AUDIO_CAP_MP1 4
- #define AUDIO_CAP_MP2 8
- #define AUDIO_CAP_MP3 16
- #define AUDIO_CAP_AAC 32
- #define AUDIO_CAP_OGG 64
- #define AUDIO_CAP_SDDS 128
- #define AUDIO_CAP_AC3 256
-
-
-.. _audio-karaoke:
-
-struct audio_karaoke
-====================
-
-The ioctl AUDIO_SET_KARAOKE uses the following format:
-
-
-.. code-block:: c
-
- typedef
- struct audio_karaoke {
- int vocal1;
- int vocal2;
- int melody;
- } audio_karaoke_t;
-
-If Vocal1 or Vocal2 are non-zero, they get mixed into left and right t
-at 70% each. If both, Vocal1 and Vocal2 are non-zero, Vocal1 gets mixed
-into the left channel and Vocal2 into the right channel at 100% each. Ff
-Melody is non-zero, the melody channel gets mixed into left and right.
-
-
-.. _audio-attributes-t:
-
-audio attributes
-================
-
-The following attributes can be set by a call to AUDIO_SET_ATTRIBUTES:
-
-
-.. code-block:: c
-
- typedef uint16_t audio_attributes_t;
- /* bits: descr. */
- /* 15-13 audio coding mode (0=ac3, 2=mpeg1, 3=mpeg2ext, 4=LPCM, 6=DTS, */
- /* 12 multichannel extension */
- /* 11-10 audio type (0=not spec, 1=language included) */
- /* 9- 8 audio application mode (0=not spec, 1=karaoke, 2=surround) */
- /* 7- 6 Quantization / DRC (mpeg audio: 1=DRC exists)(lpcm: 0=16bit, */
- /* 5- 4 Sample frequency fs (0=48kHz, 1=96kHz) */
- /* 2- 0 number of audio channels (n+1 channels) */
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _audio_function_calls:
-
-********************
-Audio Function Calls
-********************
-
-.. toctree::
- :maxdepth: 1
-
- audio-fopen
- audio-fclose
- audio-fwrite
- audio-stop
- audio-play
- audio-pause
- audio-continue
- audio-select-source
- audio-set-mute
- audio-set-av-sync
- audio-set-bypass-mode
- audio-channel-select
- audio-bilingual-channel-select
- audio-get-pts
- audio-get-status
- audio-get-capabilities
- audio-clear-buffer
- audio-set-id
- audio-set-mixer
- audio-set-streamtype
- audio-set-ext-id
- audio-set-attributes
- audio-set-karaoke
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _audio_h:
-
-*********************
-DVB Audio Header File
-*********************
-
-.. kernel-include:: $BUILDDIR/audio.h.rst
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _ca_fclose:
-
-==============
-DVB CA close()
-==============
-
-Name
-----
-
-DVB CA close()
-
-
-Synopsis
---------
-
-.. cpp:function:: int close(int fd)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
-
-Description
------------
-
-This system call closes a previously opened audio device.
-
-
-Return Value
-------------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``EBADF``
-
- - fd is not a valid open file descriptor.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _ca_fopen:
-
-=============
-DVB CA open()
-=============
-
-Name
-----
-
-DVB CA open()
-
-
-Synopsis
---------
-
-.. cpp:function:: int open(const char *deviceName, int flags)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - const char \*deviceName
-
- - Name of specific video device.
-
- - .. row 2
-
- - int flags
-
- - A bit-wise OR of the following flags:
-
- - .. row 3
-
- -
- - O_RDONLY read-only access
-
- - .. row 4
-
- -
- - O_RDWR read/write access
-
- - .. row 5
-
- -
- - O_NONBLOCK open in non-blocking mode
-
- - .. row 6
-
- -
- - (blocking mode is the default)
-
-
-Description
------------
-
-This system call opens a named ca device (e.g. /dev/ost/ca) for
-subsequent use.
-
-When an open() call has succeeded, the device will be ready for use. The
-significance of blocking or non-blocking mode is described in the
-documentation for functions where there is a difference. It does not
-affect the semantics of the open() call itself. A device opened in
-blocking mode can later be put into non-blocking mode (and vice versa)
-using the F_SETFL command of the fcntl system call. This is a standard
-system call, documented in the Linux manual page for fcntl. Only one
-user can open the CA Device in O_RDWR mode. All other attempts to open
-the device in this mode will fail, and an error code will be returned.
-
-
-Return Value
-------------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``ENODEV``
-
- - Device driver not loaded/available.
-
- - .. row 2
-
- - ``EINTERNAL``
-
- - Internal error.
-
- - .. row 3
-
- - ``EBUSY``
-
- - Device or resource busy.
-
- - .. row 4
-
- - ``EINVAL``
-
- - Invalid argument.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _CA_GET_CAP:
-
-==========
-CA_GET_CAP
-==========
-
-Name
-----
-
-CA_GET_CAP
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(fd, int request = CA_GET_CAP, ca_caps_t *)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals CA_GET_CAP for this command.
-
- - .. row 3
-
- - ca_caps_t *
-
- - Undocumented.
-
-
-Description
------------
-
-This ioctl is undocumented. Documentation is welcome.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _CA_GET_DESCR_INFO:
-
-=================
-CA_GET_DESCR_INFO
-=================
-
-Name
-----
-
-CA_GET_DESCR_INFO
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(fd, int request = CA_GET_DESCR_INFO, ca_descr_info_t *)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals CA_GET_DESCR_INFO for this command.
-
- - .. row 3
-
- - ca_descr_info_t \*
-
- - Undocumented.
-
-
-Description
------------
-
-This ioctl is undocumented. Documentation is welcome.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _CA_GET_MSG:
-
-==========
-CA_GET_MSG
-==========
-
-Name
-----
-
-CA_GET_MSG
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(fd, int request = CA_GET_MSG, ca_msg_t *)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals CA_GET_MSG for this command.
-
- - .. row 3
-
- - ca_msg_t \*
-
- - Undocumented.
-
-
-Description
------------
-
-This ioctl is undocumented. Documentation is welcome.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _CA_GET_SLOT_INFO:
-
-================
-CA_GET_SLOT_INFO
-================
-
-Name
-----
-
-CA_GET_SLOT_INFO
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(fd, int request = CA_GET_SLOT_INFO, ca_slot_info_t *)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals CA_GET_SLOT_INFO for this command.
-
- - .. row 3
-
- - ca_slot_info_t \*
-
- - Undocumented.
-
-
-Description
------------
-
-This ioctl is undocumented. Documentation is welcome.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _CA_RESET:
-
-========
-CA_RESET
-========
-
-Name
-----
-
-CA_RESET
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(fd, int request = CA_RESET)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals CA_RESET for this command.
-
-
-Description
------------
-
-This ioctl is undocumented. Documentation is welcome.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _CA_SEND_MSG:
-
-===========
-CA_SEND_MSG
-===========
-
-Name
-----
-
-CA_SEND_MSG
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(fd, int request = CA_SEND_MSG, ca_msg_t *)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals CA_SEND_MSG for this command.
-
- - .. row 3
-
- - ca_msg_t \*
-
- - Undocumented.
-
-
-Description
------------
-
-This ioctl is undocumented. Documentation is welcome.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _CA_SET_DESCR:
-
-============
-CA_SET_DESCR
-============
-
-Name
-----
-
-CA_SET_DESCR
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(fd, int request = CA_SET_DESCR, ca_descr_t *)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals CA_SET_DESCR for this command.
-
- - .. row 3
-
- - ca_descr_t \*
-
- - Undocumented.
-
-
-Description
------------
-
-This ioctl is undocumented. Documentation is welcome.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _CA_SET_PID:
-
-==========
-CA_SET_PID
-==========
-
-Name
-----
-
-CA_SET_PID
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(fd, int request = CA_SET_PID, ca_pid_t *)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals CA_SET_PID for this command.
-
- - .. row 3
-
- - ca_pid_t \*
-
- - Undocumented.
-
-
-Description
------------
-
-This ioctl is undocumented. Documentation is welcome.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _dvb_ca:
-
-#############
-DVB CA Device
-#############
-The DVB CA device controls the conditional access hardware. It can be
-accessed through ``/dev/dvb/adapter?/ca?``. Data types and and ioctl
-definitions can be accessed by including ``linux/dvb/ca.h`` in your
-application.
-
-
-.. toctree::
- :maxdepth: 1
-
- ca_data_types
- ca_function_calls
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _ca_data_types:
-
-*************
-CA Data Types
-*************
-
-
-.. _ca-slot-info:
-
-ca_slot_info_t
-==============
-
-
-.. code-block:: c
-
- typedef struct ca_slot_info {
- int num; /* slot number */
-
- int type; /* CA interface this slot supports */
- #define CA_CI 1 /* CI high level interface */
- #define CA_CI_LINK 2 /* CI link layer level interface */
- #define CA_CI_PHYS 4 /* CI physical layer level interface */
- #define CA_DESCR 8 /* built-in descrambler */
- #define CA_SC 128 /* simple smart card interface */
-
- unsigned int flags;
- #define CA_CI_MODULE_PRESENT 1 /* module (or card) inserted */
- #define CA_CI_MODULE_READY 2
- } ca_slot_info_t;
-
-
-.. _ca-descr-info:
-
-ca_descr_info_t
-===============
-
-
-.. code-block:: c
-
- typedef struct ca_descr_info {
- unsigned int num; /* number of available descramblers (keys) */
- unsigned int type; /* type of supported scrambling system */
- #define CA_ECD 1
- #define CA_NDS 2
- #define CA_DSS 4
- } ca_descr_info_t;
-
-
-.. _ca-caps:
-
-ca_caps_t
-=========
-
-
-.. code-block:: c
-
- typedef struct ca_caps {
- unsigned int slot_num; /* total number of CA card and module slots */
- unsigned int slot_type; /* OR of all supported types */
- unsigned int descr_num; /* total number of descrambler slots (keys) */
- unsigned int descr_type;/* OR of all supported types */
- } ca_cap_t;
-
-
-.. _ca-msg:
-
-ca_msg_t
-========
-
-
-.. code-block:: c
-
- /* a message to/from a CI-CAM */
- typedef struct ca_msg {
- unsigned int index;
- unsigned int type;
- unsigned int length;
- unsigned char msg[256];
- } ca_msg_t;
-
-
-.. _ca-descr:
-
-ca_descr_t
-==========
-
-
-.. code-block:: c
-
- typedef struct ca_descr {
- unsigned int index;
- unsigned int parity;
- unsigned char cw[8];
- } ca_descr_t;
-
-
-.. _ca-pid:
-
-ca-pid
-======
-
-
-.. code-block:: c
-
- typedef struct ca_pid {
- unsigned int pid;
- int index; /* -1 == disable*/
- } ca_pid_t;
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _ca_function_calls:
-
-*****************
-CA Function Calls
-*****************
-
-.. toctree::
- :maxdepth: 1
-
- ca-fopen
- ca-fclose
- ca-reset
- ca-get-cap
- ca-get-slot-info
- ca-get-descr-info
- ca-get-msg
- ca-send-msg
- ca-set-descr
- ca-set-pid
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _ca_h:
-
-**********************************
-DVB Conditional Access Header File
-**********************************
-
-.. kernel-include:: $BUILDDIR/ca.h.rst
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _dvb_demux:
-
-################
-DVB Demux Device
-################
-The DVB demux device controls the filters of the DVB hardware/software.
-It can be accessed through ``/dev/adapter?/demux?``. Data types and and
-ioctl definitions can be accessed by including ``linux/dvb/dmx.h`` in
-your application.
-
-
-.. toctree::
- :maxdepth: 1
-
- dmx_types
- dmx_fcalls
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _DMX_ADD_PID:
-
-===========
-DMX_ADD_PID
-===========
-
-Name
-----
-
-DMX_ADD_PID
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(fd, int request = DMX_ADD_PID, __u16 *)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals DMX_ADD_PID for this command.
-
- - .. row 3
-
- - __u16 *
-
- - PID number to be filtered.
-
-
-Description
------------
-
-This ioctl call allows to add multiple PIDs to a transport stream filter
-previously set up with DMX_SET_PES_FILTER and output equal to
-DMX_OUT_TSDEMUX_TAP.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _dmx_fclose:
-
-=================
-DVB demux close()
-=================
-
-Name
-----
-
-DVB demux close()
-
-
-Synopsis
---------
-
-.. cpp:function:: int close(int fd)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
-
-Description
------------
-
-This system call deactivates and deallocates a filter that was
-previously allocated via the open() call.
-
-
-Return Value
-------------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``EBADF``
-
- - fd is not a valid open file descriptor.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _dmx_fopen:
-
-================
-DVB demux open()
-================
-
-Name
-----
-
-DVB demux open()
-
-
-Synopsis
---------
-
-.. cpp:function:: int open(const char *deviceName, int flags)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - const char \*deviceName
-
- - Name of demux device.
-
- - .. row 2
-
- - int flags
-
- - A bit-wise OR of the following flags:
-
- - .. row 3
-
- -
- - O_RDWR read/write access
-
- - .. row 4
-
- -
- - O_NONBLOCK open in non-blocking mode
-
- - .. row 5
-
- -
- - (blocking mode is the default)
-
-
-Description
------------
-
-This system call, used with a device name of /dev/dvb/adapter0/demux0,
-allocates a new filter and returns a handle which can be used for
-subsequent control of that filter. This call has to be made for each
-filter to be used, i.e. every returned file descriptor is a reference to
-a single filter. /dev/dvb/adapter0/dvr0 is a logical device to be used
-for retrieving Transport Streams for digital video recording. When
-reading from this device a transport stream containing the packets from
-all PES filters set in the corresponding demux device
-(/dev/dvb/adapter0/demux0) having the output set to DMX_OUT_TS_TAP. A
-recorded Transport Stream is replayed by writing to this device.
-
-The significance of blocking or non-blocking mode is described in the
-documentation for functions where there is a difference. It does not
-affect the semantics of the open() call itself. A device opened in
-blocking mode can later be put into non-blocking mode (and vice versa)
-using the F_SETFL command of the fcntl system call.
-
-
-Return Value
-------------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``ENODEV``
-
- - Device driver not loaded/available.
-
- - .. row 2
-
- - ``EINVAL``
-
- - Invalid argument.
-
- - .. row 3
-
- - ``EMFILE``
-
- - “Too many open files”, i.e. no more filters available.
-
- - .. row 4
-
- - ``ENOMEM``
-
- - The driver failed to allocate enough memory.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _dmx_fread:
-
-================
-DVB demux read()
-================
-
-Name
-----
-
-DVB demux read()
-
-
-Synopsis
---------
-
-.. cpp:function:: size_t read(int fd, void *buf, size_t count)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - void \*buf
-
- - Pointer to the buffer to be used for returned filtered data.
-
- - .. row 3
-
- - size_t count
-
- - Size of buf.
-
-
-Description
------------
-
-This system call returns filtered data, which might be section or PES
-data. The filtered data is transferred from the driver’s internal
-circular buffer to buf. The maximum amount of data to be transferred is
-implied by count.
-
-
-Return Value
-------------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``EWOULDBLOCK``
-
- - No data to return and O_NONBLOCK was specified.
-
- - .. row 2
-
- - ``EBADF``
-
- - fd is not a valid open file descriptor.
-
- - .. row 3
-
- - ``ECRC``
-
- - Last section had a CRC error - no data returned. The buffer is
- flushed.
-
- - .. row 4
-
- - ``EOVERFLOW``
-
- -
-
- - .. row 5
-
- -
- - The filtered data was not read from the buffer in due time,
- resulting in non-read data being lost. The buffer is flushed.
-
- - .. row 6
-
- - ``ETIMEDOUT``
-
- - The section was not loaded within the stated timeout period. See
- ioctl DMX_SET_FILTER for how to set a timeout.
-
- - .. row 7
-
- - ``EFAULT``
-
- - The driver failed to write to the callers buffer due to an invalid
- \*buf pointer.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _dmx_fwrite:
-
-=================
-DVB demux write()
-=================
-
-Name
-----
-
-DVB demux write()
-
-
-Synopsis
---------
-
-.. cpp:function:: ssize_t write(int fd, const void *buf, size_t count)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - void \*buf
-
- - Pointer to the buffer containing the Transport Stream.
-
- - .. row 3
-
- - size_t count
-
- - Size of buf.
-
-
-Description
------------
-
-This system call is only provided by the logical device
-/dev/dvb/adapter0/dvr0, associated with the physical demux device that
-provides the actual DVR functionality. It is used for replay of a
-digitally recorded Transport Stream. Matching filters have to be defined
-in the corresponding physical demux device, /dev/dvb/adapter0/demux0.
-The amount of data to be transferred is implied by count.
-
-
-Return Value
-------------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``EWOULDBLOCK``
-
- - No data was written. This might happen if O_NONBLOCK was
- specified and there is no more buffer space available (if
- O_NONBLOCK is not specified the function will block until buffer
- space is available).
-
- - .. row 2
-
- - ``EBUSY``
-
- - This error code indicates that there are conflicting requests. The
- corresponding demux device is setup to receive data from the
- front- end. Make sure that these filters are stopped and that the
- filters with input set to DMX_IN_DVR are started.
-
- - .. row 3
-
- - ``EBADF``
-
- - fd is not a valid open file descriptor.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _DMX_GET_CAPS:
-
-============
-DMX_GET_CAPS
-============
-
-Name
-----
-
-DMX_GET_CAPS
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(fd, int request = DMX_GET_CAPS, dmx_caps_t *)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals DMX_GET_CAPS for this command.
-
- - .. row 3
-
- - dmx_caps_t *
-
- - Undocumented.
-
-
-Description
------------
-
-This ioctl is undocumented. Documentation is welcome.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _DMX_GET_EVENT:
-
-=============
-DMX_GET_EVENT
-=============
-
-Name
-----
-
-DMX_GET_EVENT
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl( int fd, int request = DMX_GET_EVENT, struct dmx_event *ev)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals DMX_GET_EVENT for this command.
-
- - .. row 3
-
- - struct dmx_event \*ev
-
- - Pointer to the location where the event is to be stored.
-
-
-Description
------------
-
-This ioctl call returns an event if available. If an event is not
-available, the behavior depends on whether the device is in blocking or
-non-blocking mode. In the latter case, the call fails immediately with
-errno set to ``EWOULDBLOCK``. In the former case, the call blocks until an
-event becomes available.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``EWOULDBLOCK``
-
- - There is no event pending, and the device is in non-blocking mode.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _DMX_GET_PES_PIDS:
-
-================
-DMX_GET_PES_PIDS
-================
-
-Name
-----
-
-DMX_GET_PES_PIDS
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(fd, int request = DMX_GET_PES_PIDS, __u16[5])
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals DMX_GET_PES_PIDS for this command.
-
- - .. row 3
-
- - __u16[5]
-
- - Undocumented.
-
-
-Description
------------
-
-This ioctl is undocumented. Documentation is welcome.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _DMX_GET_STC:
-
-===========
-DMX_GET_STC
-===========
-
-Name
-----
-
-DMX_GET_STC
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl( int fd, int request = DMX_GET_STC, struct dmx_stc *stc)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals DMX_GET_STC for this command.
-
- - .. row 3
-
- - struct dmx_stc \*stc
-
- - Pointer to the location where the stc is to be stored.
-
-
-Description
------------
-
-This ioctl call returns the current value of the system time counter
-(which is driven by a PES filter of type DMX_PES_PCR). Some hardware
-supports more than one STC, so you must specify which one by setting the
-num field of stc before the ioctl (range 0...n). The result is returned
-in form of a ratio with a 64 bit numerator and a 32 bit denominator, so
-the real 90kHz STC value is stc->stc / stc->base .
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``EINVAL``
-
- - Invalid stc number.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _DMX_REMOVE_PID:
-
-==============
-DMX_REMOVE_PID
-==============
-
-Name
-----
-
-DMX_REMOVE_PID
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(fd, int request = DMX_REMOVE_PID, __u16 *)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals DMX_REMOVE_PID for this command.
-
- - .. row 3
-
- - __u16 *
-
- - PID of the PES filter to be removed.
-
-
-Description
------------
-
-This ioctl call allows to remove a PID when multiple PIDs are set on a
-transport stream filter, e. g. a filter previously set up with output
-equal to DMX_OUT_TSDEMUX_TAP, created via either
-DMX_SET_PES_FILTER or DMX_ADD_PID.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _DMX_SET_BUFFER_SIZE:
-
-===================
-DMX_SET_BUFFER_SIZE
-===================
-
-Name
-----
-
-DMX_SET_BUFFER_SIZE
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl( int fd, int request = DMX_SET_BUFFER_SIZE, unsigned long size)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals DMX_SET_BUFFER_SIZE for this command.
-
- - .. row 3
-
- - unsigned long size
-
- - Size of circular buffer.
-
-
-Description
------------
-
-This ioctl call is used to set the size of the circular buffer used for
-filtered data. The default size is two maximum sized sections, i.e. if
-this function is not called a buffer size of 2 \* 4096 bytes will be
-used.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _DMX_SET_FILTER:
-
-==============
-DMX_SET_FILTER
-==============
-
-Name
-----
-
-DMX_SET_FILTER
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl( int fd, int request = DMX_SET_FILTER, struct dmx_sct_filter_params *params)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals DMX_SET_FILTER for this command.
-
- - .. row 3
-
- - struct dmx_sct_filter_params \*params
-
- - Pointer to structure containing filter parameters.
-
-
-Description
------------
-
-This ioctl call sets up a filter according to the filter and mask
-parameters provided. A timeout may be defined stating number of seconds
-to wait for a section to be loaded. A value of 0 means that no timeout
-should be applied. Finally there is a flag field where it is possible to
-state whether a section should be CRC-checked, whether the filter should
-be a ”one-shot” filter, i.e. if the filtering operation should be
-stopped after the first section is received, and whether the filtering
-operation should be started immediately (without waiting for a
-DMX_START ioctl call). If a filter was previously set-up, this filter
-will be canceled, and the receive buffer will be flushed.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _DMX_SET_PES_FILTER:
-
-==================
-DMX_SET_PES_FILTER
-==================
-
-Name
-----
-
-DMX_SET_PES_FILTER
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl( int fd, int request = DMX_SET_PES_FILTER, struct dmx_pes_filter_params *params)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals DMX_SET_PES_FILTER for this command.
-
- - .. row 3
-
- - struct dmx_pes_filter_params \*params
-
- - Pointer to structure containing filter parameters.
-
-
-Description
------------
-
-This ioctl call sets up a PES filter according to the parameters
-provided. By a PES filter is meant a filter that is based just on the
-packet identifier (PID), i.e. no PES header or payload filtering
-capability is supported.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``EBUSY``
-
- - This error code indicates that there are conflicting requests.
- There are active filters filtering data from another input source.
- Make sure that these filters are stopped before starting this
- filter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _DMX_SET_SOURCE:
-
-==============
-DMX_SET_SOURCE
-==============
-
-Name
-----
-
-DMX_SET_SOURCE
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(fd, int request = DMX_SET_SOURCE, dmx_source_t *)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals DMX_SET_SOURCE for this command.
-
- - .. row 3
-
- - dmx_source_t *
-
- - Undocumented.
-
-
-Description
------------
-
-This ioctl is undocumented. Documentation is welcome.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _DMX_START:
-
-=========
-DMX_START
-=========
-
-Name
-----
-
-DMX_START
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl( int fd, int request = DMX_START)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals DMX_START for this command.
-
-
-Description
------------
-
-This ioctl call is used to start the actual filtering operation defined
-via the ioctl calls DMX_SET_FILTER or DMX_SET_PES_FILTER.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``EINVAL``
-
- - Invalid argument, i.e. no filtering parameters provided via the
- DMX_SET_FILTER or DMX_SET_PES_FILTER functions.
-
- - .. row 2
-
- - ``EBUSY``
-
- - This error code indicates that there are conflicting requests.
- There are active filters filtering data from another input source.
- Make sure that these filters are stopped before starting this
- filter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _DMX_STOP:
-
-========
-DMX_STOP
-========
-
-Name
-----
-
-DMX_STOP
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl( int fd, int request = DMX_STOP)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals DMX_STOP for this command.
-
-
-Description
------------
-
-This ioctl call is used to stop the actual filtering operation defined
-via the ioctl calls DMX_SET_FILTER or DMX_SET_PES_FILTER and
-started via the DMX_START command.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _dmx_fcalls:
-
-********************
-Demux Function Calls
-********************
-
-.. toctree::
- :maxdepth: 1
-
- dmx-fopen
- dmx-fclose
- dmx-fread
- dmx-fwrite
- dmx-start
- dmx-stop
- dmx-set-filter
- dmx-set-pes-filter
- dmx-set-buffer-size
- dmx-get-event
- dmx-get-stc
- dmx-get-pes-pids
- dmx-get-caps
- dmx-set-source
- dmx-add-pid
- dmx-remove-pid
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _dmx_h:
-
-*********************
-DVB Demux Header File
-*********************
-
-.. kernel-include:: $BUILDDIR/dmx.h.rst
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _dmx_types:
-
-****************
-Demux Data Types
-****************
-
-
-.. _dmx-output-t:
-
-Output for the demux
-====================
-
-
-.. _dmx-output:
-
-.. flat-table:: enum dmx_output
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - ID
-
- - Description
-
- - .. row 2
-
- - .. _DMX-OUT-DECODER:
-
- DMX_OUT_DECODER
-
- - Streaming directly to decoder.
-
- - .. row 3
-
- - .. _DMX-OUT-TAP:
-
- DMX_OUT_TAP
-
- - Output going to a memory buffer (to be retrieved via the read
- command). Delivers the stream output to the demux device on which
- the ioctl is called.
-
- - .. row 4
-
- - .. _DMX-OUT-TS-TAP:
-
- DMX_OUT_TS_TAP
-
- - Output multiplexed into a new TS (to be retrieved by reading from
- the logical DVR device). Routes output to the logical DVR device
- ``/dev/dvb/adapter?/dvr?``, which delivers a TS multiplexed from
- all filters for which ``DMX_OUT_TS_TAP`` was specified.
-
- - .. row 5
-
- - .. _DMX-OUT-TSDEMUX-TAP:
-
- DMX_OUT_TSDEMUX_TAP
-
- - Like :ref:`DMX_OUT_TS_TAP <DMX-OUT-TS-TAP>` but retrieved
- from the DMX device.
-
-
-
-.. _dmx-input-t:
-
-dmx_input_t
-===========
-
-
-.. code-block:: c
-
- typedef enum
- {
- DMX_IN_FRONTEND, /* Input from a front-end device. */
- DMX_IN_DVR /* Input from the logical DVR device. */
- } dmx_input_t;
-
-
-.. _dmx-pes-type-t:
-
-dmx_pes_type_t
-==============
-
-
-.. code-block:: c
-
- typedef enum
- {
- DMX_PES_AUDIO0,
- DMX_PES_VIDEO0,
- DMX_PES_TELETEXT0,
- DMX_PES_SUBTITLE0,
- DMX_PES_PCR0,
-
- DMX_PES_AUDIO1,
- DMX_PES_VIDEO1,
- DMX_PES_TELETEXT1,
- DMX_PES_SUBTITLE1,
- DMX_PES_PCR1,
-
- DMX_PES_AUDIO2,
- DMX_PES_VIDEO2,
- DMX_PES_TELETEXT2,
- DMX_PES_SUBTITLE2,
- DMX_PES_PCR2,
-
- DMX_PES_AUDIO3,
- DMX_PES_VIDEO3,
- DMX_PES_TELETEXT3,
- DMX_PES_SUBTITLE3,
- DMX_PES_PCR3,
-
- DMX_PES_OTHER
- } dmx_pes_type_t;
-
-
-.. _dmx-filter:
-
-struct dmx_filter
-=================
-
-
-.. code-block:: c
-
- typedef struct dmx_filter
- {
- __u8 filter[DMX_FILTER_SIZE];
- __u8 mask[DMX_FILTER_SIZE];
- __u8 mode[DMX_FILTER_SIZE];
- } dmx_filter_t;
-
-
-.. _dmx-sct-filter-params:
-
-struct dmx_sct_filter_params
-============================
-
-
-.. code-block:: c
-
- struct dmx_sct_filter_params
- {
- __u16 pid;
- dmx_filter_t filter;
- __u32 timeout;
- __u32 flags;
- #define DMX_CHECK_CRC 1
- #define DMX_ONESHOT 2
- #define DMX_IMMEDIATE_START 4
- #define DMX_KERNEL_CLIENT 0x8000
- };
-
-
-.. _dmx-pes-filter-params:
-
-struct dmx_pes_filter_params
-============================
-
-
-.. code-block:: c
-
- struct dmx_pes_filter_params
- {
- __u16 pid;
- dmx_input_t input;
- dmx_output_t output;
- dmx_pes_type_t pes_type;
- __u32 flags;
- };
-
-
-.. _dmx-event:
-
-struct dmx_event
-================
-
-
-.. code-block:: c
-
- struct dmx_event
- {
- dmx_event_t event;
- time_t timeStamp;
- union
- {
- dmx_scrambling_status_t scrambling;
- } u;
- };
-
-
-.. _dmx-stc:
-
-struct dmx_stc
-==============
-
-
-.. code-block:: c
-
- struct dmx_stc {
- unsigned int num; /* input : which STC? 0..N */
- unsigned int base; /* output: divisor for stc to get 90 kHz clock */
- __u64 stc; /* output: stc in 'base'*90 kHz units */
- };
-
-
-.. _dmx-caps:
-
-struct dmx_caps
-===============
-
-
-.. code-block:: c
-
- typedef struct dmx_caps {
- __u32 caps;
- int num_decoders;
- } dmx_caps_t;
-
-
-.. _dmx-source-t:
-
-enum dmx_source_t
-=================
-
-
-.. code-block:: c
-
- typedef enum {
- DMX_SOURCE_FRONT0 = 0,
- DMX_SOURCE_FRONT1,
- DMX_SOURCE_FRONT2,
- DMX_SOURCE_FRONT3,
- DMX_SOURCE_DVR0 = 16,
- DMX_SOURCE_DVR1,
- DMX_SOURCE_DVR2,
- DMX_SOURCE_DVR3
- } dmx_source_t;
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _dtv-fe-stats:
-
-*******************
-struct dtv_fe_stats
-*******************
-
-
-.. code-block:: c
-
- #define MAX_DTV_STATS 4
-
- struct dtv_fe_stats {
- __u8 len;
- struct dtv_stats stat[MAX_DTV_STATS];
- } __packed;
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _dtv-properties:
-
-*********************
-struct dtv_properties
-*********************
-
-
-.. code-block:: c
-
- struct dtv_properties {
- __u32 num;
- struct dtv_property *props;
- };
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _dtv-property:
-
-*******************
-struct dtv_property
-*******************
-
-
-.. code-block:: c
-
- /* Reserved fields should be set to 0 */
-
- struct dtv_property {
- __u32 cmd;
- __u32 reserved[3];
- union {
- __u32 data;
- struct dtv_fe_stats st;
- struct {
- __u8 data[32];
- __u32 len;
- __u32 reserved1[3];
- void *reserved2;
- } buffer;
- } u;
- int result;
- } __attribute__ ((packed));
-
- /* num of properties cannot exceed DTV_IOCTL_MAX_MSGS per ioctl */
- #define DTV_IOCTL_MAX_MSGS 64
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _dtv-stats:
-
-****************
-struct dtv_stats
-****************
-
-
-.. code-block:: c
-
- struct dtv_stats {
- __u8 scale; /* enum fecap_scale_params type */
- union {
- __u64 uvalue; /* for counters and relative scales */
- __s64 svalue; /* for 1/1000 dB measures */
- };
- } __packed;
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _dvb-fe-read-status:
-
-***************************************
-Querying frontend status and statistics
-***************************************
-
-Once :ref:`FE_SET_PROPERTY <FE_GET_PROPERTY>` is called, the
-frontend will run a kernel thread that will periodically check for the
-tuner lock status and provide statistics about the quality of the
-signal.
-
-The information about the frontend tuner locking status can be queried
-using :ref:`FE_READ_STATUS`.
-
-Signal statistics are provided via
-:ref:`FE_GET_PROPERTY`. Please note that several
-statistics require the demodulator to be fully locked (e. g. with
-FE_HAS_LOCK bit set). See
-:ref:`Frontend statistics indicators <frontend-stat-properties>` for
-more details.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _dvb-frontend-event:
-
-***************
-frontend events
-***************
-
-
-.. code-block:: c
-
- struct dvb_frontend_event {
- fe_status_t status;
- struct dvb_frontend_parameters parameters;
- };
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _dvb-frontend-parameters:
-
-*******************
-frontend parameters
-*******************
-
-The kind of parameters passed to the frontend device for tuning depend
-on the kind of hardware you are using.
-
-The struct ``dvb_frontend_parameters`` uses an union with specific
-per-system parameters. However, as newer delivery systems required more
-data, the structure size weren't enough to fit, and just extending its
-size would break the existing applications. So, those parameters were
-replaced by the usage of
-:ref:`FE_GET_PROPERTY/FE_SET_PROPERTY <FE_GET_PROPERTY>`
-ioctl's. The new API is flexible enough to add new parameters to
-existing delivery systems, and to add newer delivery systems.
-
-So, newer applications should use
-:ref:`FE_GET_PROPERTY/FE_SET_PROPERTY <FE_GET_PROPERTY>`
-instead, in order to be able to support the newer System Delivery like
-DVB-S2, DVB-T2, DVB-C2, ISDB, etc.
-
-All kinds of parameters are combined as an union in the
-FrontendParameters structure:
-
-
-.. code-block:: c
-
- struct dvb_frontend_parameters {
- uint32_t frequency; /* (absolute) frequency in Hz for QAM/OFDM */
- /* intermediate frequency in kHz for QPSK */
- fe_spectral_inversion_t inversion;
- union {
- struct dvb_qpsk_parameters qpsk;
- struct dvb_qam_parameters qam;
- struct dvb_ofdm_parameters ofdm;
- struct dvb_vsb_parameters vsb;
- } u;
- };
-
-In the case of QPSK frontends the ``frequency`` field specifies the
-intermediate frequency, i.e. the offset which is effectively added to
-the local oscillator frequency (LOF) of the LNB. The intermediate
-frequency has to be specified in units of kHz. For QAM and OFDM
-frontends the ``frequency`` specifies the absolute frequency and is
-given in Hz.
-
-
-.. _dvb-qpsk-parameters:
-
-QPSK parameters
-===============
-
-For satellite QPSK frontends you have to use the ``dvb_qpsk_parameters``
-structure:
-
-
-.. code-block:: c
-
- struct dvb_qpsk_parameters {
- uint32_t symbol_rate; /* symbol rate in Symbols per second */
- fe_code_rate_t fec_inner; /* forward error correction (see above) */
- };
-
-
-.. _dvb-qam-parameters:
-
-QAM parameters
-==============
-
-for cable QAM frontend you use the ``dvb_qam_parameters`` structure:
-
-
-.. code-block:: c
-
- struct dvb_qam_parameters {
- uint32_t symbol_rate; /* symbol rate in Symbols per second */
- fe_code_rate_t fec_inner; /* forward error correction (see above) */
- fe_modulation_t modulation; /* modulation type (see above) */
- };
-
-
-.. _dvb-vsb-parameters:
-
-VSB parameters
-==============
-
-ATSC frontends are supported by the ``dvb_vsb_parameters`` structure:
-
-
-.. code-block:: c
-
- struct dvb_vsb_parameters {
- fe_modulation_t modulation; /* modulation type (see above) */
- };
-
-
-.. _dvb-ofdm-parameters:
-
-OFDM parameters
-===============
-
-DVB-T frontends are supported by the ``dvb_ofdm_parameters`` structure:
-
-
-.. code-block:: c
-
- struct dvb_ofdm_parameters {
- fe_bandwidth_t bandwidth;
- fe_code_rate_t code_rate_HP; /* high priority stream code rate */
- fe_code_rate_t code_rate_LP; /* low priority stream code rate */
- fe_modulation_t constellation; /* modulation type (see above) */
- fe_transmit_mode_t transmission_mode;
- fe_guard_interval_t guard_interval;
- fe_hierarchy_t hierarchy_information;
- };
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. include:: <isonum.txt>
-
-.. _dvbapi:
-
-##############
-Digital TV API
-##############
-
-**NOTE:** This API is also known as **DVB API**, although it is generic
-enough to support all digital TV standards.
-
-**Version 5.10**
-
-.. toctree::
- :maxdepth: 1
- :numbered:
-
- intro
- frontend
- demux
- ca
- net
- legacy_dvb_apis
- examples
- audio_h
- ca_h
- dmx_h
- frontend_h
- net_h
- video_h
-
-
-**********************
-Revision and Copyright
-**********************
-
-Authors:
-
-- J. K. Metzler, Ralph <rjkm@metzlerbros.de>
-
- - Original author of the DVB API documentation.
-
-- O. C. Metzler, Marcus <rjkm@metzlerbros.de>
-
- - Original author of the DVB API documentation.
-
-- Carvalho Chehab, Mauro <m.chehab@kernel.org>
-
- - Ported document to Docbook XML, addition of DVBv5 API, documentation gaps fix.
-
-**Copyright** |copy| 2002-2003 : Convergence GmbH
-
-**Copyright** |copy| 2009-2016 : Mauro Carvalho Chehab
-
-****************
-Revision History
-****************
-
-:revision: 2.1.0 / 2015-05-29 (*mcc*)
-
-DocBook improvements and cleanups, in order to document the system calls
-on a more standard way and provide more description about the current
-DVB API.
-
-:revision: 2.0.4 / 2011-05-06 (*mcc*)
-
-Add more information about DVB APIv5, better describing the frontend
-GET/SET props ioctl's.
-
-
-:revision: 2.0.3 / 2010-07-03 (*mcc*)
-
-Add some frontend capabilities flags, present on kernel, but missing at
-the specs.
-
-
-:revision: 2.0.2 / 2009-10-25 (*mcc*)
-
-documents FE_SET_FRONTEND_TUNE_MODE and
-FE_DISHETWORK_SEND_LEGACY_CMD ioctls.
-
-
-:revision: 2.0.1 / 2009-09-16 (*mcc*)
-
-Added ISDB-T test originally written by Patrick Boettcher
-
-
-:revision: 2.0.0 / 2009-09-06 (*mcc*)
-
-Conversion from LaTex to DocBook XML. The contents is the same as the
-original LaTex version.
-
-
-:revision: 1.0.0 / 2003-07-24 (*rjkm*)
-
-Initial revision on LaTEX.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-**************
-Property types
-**************
-
-On :ref:`FE_GET_PROPERTY and FE_SET_PROPERTY <FE_GET_PROPERTY>`,
-the actual action is determined by the dtv_property cmd/data pairs.
-With one single ioctl, is possible to get/set up to 64 properties. The
-actual meaning of each property is described on the next sections.
-
-The available frontend property types are shown on the next section.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _frontend-properties:
-
-DVB Frontend properties
-=======================
-
-Tuning into a Digital TV physical channel and starting decoding it
-requires changing a set of parameters, in order to control the tuner,
-the demodulator, the Linear Low-noise Amplifier (LNA) and to set the
-antenna subsystem via Satellite Equipment Control (SEC), on satellite
-systems. The actual parameters are specific to each particular digital
-TV standards, and may change as the digital TV specs evolves.
-
-In the past, the strategy used was to have a union with the parameters
-needed to tune for DVB-S, DVB-C, DVB-T and ATSC delivery systems grouped
-there. The problem is that, as the second generation standards appeared,
-those structs were not big enough to contain the additional parameters.
-Also, the union didn't have any space left to be expanded without
-breaking userspace. So, the decision was to deprecate the legacy
-union/struct based approach, in favor of a properties set approach.
-
-NOTE: on Linux DVB API version 3, setting a frontend were done via
-:ref:`struct dvb_frontend_parameters <dvb-frontend-parameters>`.
-This got replaced on version 5 (also called "S2API", as this API were
-added originally_enabled to provide support for DVB-S2), because the
-old API has a very limited support to new standards and new hardware.
-This section describes the new and recommended way to set the frontend,
-with suppports all digital TV delivery systems.
-
-Example: with the properties based approach, in order to set the tuner
-to a DVB-C channel at 651 kHz, modulated with 256-QAM, FEC 3/4 and
-symbol rate of 5.217 Mbauds, those properties should be sent to
-:ref:`FE_SET_PROPERTY <FE_GET_PROPERTY>` ioctl:
-
-- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>` =
- SYS_DVBC_ANNEX_A
-
-- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>` = 651000000
-
-- :ref:`DTV_MODULATION <DTV-MODULATION>` = QAM_256
-
-- :ref:`DTV_INVERSION <DTV-INVERSION>` = INVERSION_AUTO
-
-- :ref:`DTV_SYMBOL_RATE <DTV-SYMBOL-RATE>` = 5217000
-
-- :ref:`DTV_INNER_FEC <DTV-INNER-FEC>` = FEC_3_4
-
-- :ref:`DTV_TUNE <DTV-TUNE>`
-
-The code that would do the above is:
-
-
-.. code-block:: c
-
- #include <stdio.h>
- #include <fcntl.h>
- #include <sys/ioctl.h>
- #include <linux/dvb/frontend.h>
-
- static struct dtv_property props[] = {
- { .cmd = DTV_DELIVERY_SYSTEM, .u.data = SYS_DVBC_ANNEX_A },
- { .cmd = DTV_FREQUENCY, .u.data = 651000000 },
- { .cmd = DTV_MODULATION, .u.data = QAM_256 },
- { .cmd = DTV_INVERSION, .u.data = INVERSION_AUTO },
- { .cmd = DTV_SYMBOL_RATE, .u.data = 5217000 },
- { .cmd = DTV_INNER_FEC, .u.data = FEC_3_4 },
- { .cmd = DTV_TUNE }
- };
-
- static struct dtv_properties dtv_prop = {
- .num = 6, .props = props
- };
-
- int main(void)
- {
- int fd = open("/dev/dvb/adapter0/frontend0", O_RDWR);
-
- if (!fd) {
- perror ("open");
- return -1;
- }
- if (ioctl(fd, FE_SET_PROPERTY, &dtv_prop) == -1) {
- perror("ioctl");
- return -1;
- }
- printf("Frontend set\\n");
- return 0;
- }
-
-NOTE: While it is possible to directly call the Kernel code like the
-above example, it is strongly recommended to use
-`libdvbv5 <https://linuxtv.org/docs/libdvbv5/index.html>`__, as it
-provides abstraction to work with the supported digital TV standards and
-provides methods for usual operations like program scanning and to
-read/write channel descriptor files.
-
-
-.. toctree::
- :maxdepth: 1
-
- dtv-stats
- dtv-fe-stats
- dtv-property
- dtv-properties
- dvbproperty-006
- fe_property_parameters
- frontend-stat-properties
- frontend-property-terrestrial-systems
- frontend-property-cable-systems
- frontend-property-satellite-systems
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _dvb_examples:
-
-********
-Examples
-********
-
-In this section we would like to present some examples for using the DVB
-API.
-
-NOTE: This section is out of date, and the code below won't even
-compile. Please refer to the
-`libdvbv5 <https://linuxtv.org/docs/libdvbv5/index.html>`__ for
-updated/recommended examples.
-
-
-.. _tuning:
-
-Tuning
-======
-
-We will start with a generic tuning subroutine that uses the frontend
-and SEC, as well as the demux devices. The example is given for QPSK
-tuners, but can easily be adjusted for QAM.
-
-
-.. code-block:: c
-
- #include <sys/ioctl.h>
- #include <stdio.h>
- #include <stdint.h>
- #include <sys/types.h>
- #include <sys/stat.h>
- #include <fcntl.h>
- #include <time.h>
- #include <unistd.h>
-
- #include <linux/dvb/dmx.h>
- #include <linux/dvb/frontend.h>
- #include <linux/dvb/sec.h>
- #include <sys/poll.h>
-
- #define DMX "/dev/dvb/adapter0/demux1"
- #define FRONT "/dev/dvb/adapter0/frontend1"
- #define SEC "/dev/dvb/adapter0/sec1"
-
- /* routine for checking if we have a signal and other status information*/
- int FEReadStatus(int fd, fe_status_t *stat)
- {
- int ans;
-
- if ( (ans = ioctl(fd,FE_READ_STATUS,stat) < 0)){
- perror("FE READ STATUS: ");
- return -1;
- }
-
- if (*stat & FE_HAS_POWER)
- printf("FE HAS POWER\\n");
-
- if (*stat & FE_HAS_SIGNAL)
- printf("FE HAS SIGNAL\\n");
-
- if (*stat & FE_SPECTRUM_INV)
- printf("SPEKTRUM INV\\n");
-
- return 0;
- }
-
-
- /* tune qpsk */
- /* freq: frequency of transponder */
- /* vpid, apid, tpid: PIDs of video, audio and teletext TS packets */
- /* diseqc: DiSEqC address of the used LNB */
- /* pol: Polarisation */
- /* srate: Symbol Rate */
- /* fec. FEC */
- /* lnb_lof1: local frequency of lower LNB band */
- /* lnb_lof2: local frequency of upper LNB band */
- /* lnb_slof: switch frequency of LNB */
-
- int set_qpsk_channel(int freq, int vpid, int apid, int tpid,
- int diseqc, int pol, int srate, int fec, int lnb_lof1,
- int lnb_lof2, int lnb_slof)
- {
- struct secCommand scmd;
- struct secCmdSequence scmds;
- struct dmx_pes_filter_params pesFilterParams;
- FrontendParameters frp;
- struct pollfd pfd[1];
- FrontendEvent event;
- int demux1, demux2, demux3, front;
-
- frequency = (uint32_t) freq;
- symbolrate = (uint32_t) srate;
-
- if((front = open(FRONT,O_RDWR)) < 0){
- perror("FRONTEND DEVICE: ");
- return -1;
- }
-
- if((sec = open(SEC,O_RDWR)) < 0){
- perror("SEC DEVICE: ");
- return -1;
- }
-
- if (demux1 < 0){
- if ((demux1=open(DMX, O_RDWR|O_NONBLOCK))
- < 0){
- perror("DEMUX DEVICE: ");
- return -1;
- }
- }
-
- if (demux2 < 0){
- if ((demux2=open(DMX, O_RDWR|O_NONBLOCK))
- < 0){
- perror("DEMUX DEVICE: ");
- return -1;
- }
- }
-
- if (demux3 < 0){
- if ((demux3=open(DMX, O_RDWR|O_NONBLOCK))
- < 0){
- perror("DEMUX DEVICE: ");
- return -1;
- }
- }
-
- if (freq < lnb_slof) {
- frp.Frequency = (freq - lnb_lof1);
- scmds.continuousTone = SEC_TONE_OFF;
- } else {
- frp.Frequency = (freq - lnb_lof2);
- scmds.continuousTone = SEC_TONE_ON;
- }
- frp.Inversion = INVERSION_AUTO;
- if (pol) scmds.voltage = SEC_VOLTAGE_18;
- else scmds.voltage = SEC_VOLTAGE_13;
-
- scmd.type=0;
- scmd.u.diseqc.addr=0x10;
- scmd.u.diseqc.cmd=0x38;
- scmd.u.diseqc.numParams=1;
- scmd.u.diseqc.params[0] = 0xF0 | ((diseqc * 4) & 0x0F) |
- (scmds.continuousTone == SEC_TONE_ON ? 1 : 0) |
- (scmds.voltage==SEC_VOLTAGE_18 ? 2 : 0);
-
- scmds.miniCommand=SEC_MINI_NONE;
- scmds.numCommands=1;
- scmds.commands=&scmd;
- if (ioctl(sec, SEC_SEND_SEQUENCE, &scmds) < 0){
- perror("SEC SEND: ");
- return -1;
- }
-
- if (ioctl(sec, SEC_SEND_SEQUENCE, &scmds) < 0){
- perror("SEC SEND: ");
- return -1;
- }
-
- frp.u.qpsk.SymbolRate = srate;
- frp.u.qpsk.FEC_inner = fec;
-
- if (ioctl(front, FE_SET_FRONTEND, &frp) < 0){
- perror("QPSK TUNE: ");
- return -1;
- }
-
- pfd[0].fd = front;
- pfd[0].events = POLLIN;
-
- if (poll(pfd,1,3000)){
- if (pfd[0].revents & POLLIN){
- printf("Getting QPSK event\\n");
- if ( ioctl(front, FE_GET_EVENT, &event)
-
- == -EOVERFLOW){
- perror("qpsk get event");
- return -1;
- }
- printf("Received ");
- switch(event.type){
- case FE_UNEXPECTED_EV:
- printf("unexpected event\\n");
- return -1;
- case FE_FAILURE_EV:
- printf("failure event\\n");
- return -1;
-
- case FE_COMPLETION_EV:
- printf("completion event\\n");
- }
- }
- }
-
-
- pesFilterParams.pid = vpid;
- pesFilterParams.input = DMX_IN_FRONTEND;
- pesFilterParams.output = DMX_OUT_DECODER;
- pesFilterParams.pes_type = DMX_PES_VIDEO;
- pesFilterParams.flags = DMX_IMMEDIATE_START;
- if (ioctl(demux1, DMX_SET_PES_FILTER, &pesFilterParams) < 0){
- perror("set_vpid");
- return -1;
- }
-
- pesFilterParams.pid = apid;
- pesFilterParams.input = DMX_IN_FRONTEND;
- pesFilterParams.output = DMX_OUT_DECODER;
- pesFilterParams.pes_type = DMX_PES_AUDIO;
- pesFilterParams.flags = DMX_IMMEDIATE_START;
- if (ioctl(demux2, DMX_SET_PES_FILTER, &pesFilterParams) < 0){
- perror("set_apid");
- return -1;
- }
-
- pesFilterParams.pid = tpid;
- pesFilterParams.input = DMX_IN_FRONTEND;
- pesFilterParams.output = DMX_OUT_DECODER;
- pesFilterParams.pes_type = DMX_PES_TELETEXT;
- pesFilterParams.flags = DMX_IMMEDIATE_START;
- if (ioctl(demux3, DMX_SET_PES_FILTER, &pesFilterParams) < 0){
- perror("set_tpid");
- return -1;
- }
-
- return has_signal(fds);
- }
-
-The program assumes that you are using a universal LNB and a standard
-DiSEqC switch with up to 4 addresses. Of course, you could build in some
-more checking if tuning was successful and maybe try to repeat the
-tuning process. Depending on the external hardware, i.e. LNB and DiSEqC
-switch, and weather conditions this may be necessary.
-
-
-.. _the_dvr_device:
-
-The DVR device
-==============
-
-The following program code shows how to use the DVR device for
-recording.
-
-
-.. code-block:: c
-
- #include <sys/ioctl.h>
- #include <stdio.h>
- #include <stdint.h>
- #include <sys/types.h>
- #include <sys/stat.h>
- #include <fcntl.h>
- #include <time.h>
- #include <unistd.h>
-
- #include <linux/dvb/dmx.h>
- #include <linux/dvb/video.h>
- #include <sys/poll.h>
- #define DVR "/dev/dvb/adapter0/dvr1"
- #define AUDIO "/dev/dvb/adapter0/audio1"
- #define VIDEO "/dev/dvb/adapter0/video1"
-
- #define BUFFY (188*20)
- #define MAX_LENGTH (1024*1024*5) /* record 5MB */
-
-
- /* switch the demuxes to recording, assuming the transponder is tuned */
-
- /* demux1, demux2: file descriptor of video and audio filters */
- /* vpid, apid: PIDs of video and audio channels */
-
- int switch_to_record(int demux1, int demux2, uint16_t vpid, uint16_t apid)
- {
- struct dmx_pes_filter_params pesFilterParams;
-
- if (demux1 < 0){
- if ((demux1=open(DMX, O_RDWR|O_NONBLOCK))
- < 0){
- perror("DEMUX DEVICE: ");
- return -1;
- }
- }
-
- if (demux2 < 0){
- if ((demux2=open(DMX, O_RDWR|O_NONBLOCK))
- < 0){
- perror("DEMUX DEVICE: ");
- return -1;
- }
- }
-
- pesFilterParams.pid = vpid;
- pesFilterParams.input = DMX_IN_FRONTEND;
- pesFilterParams.output = DMX_OUT_TS_TAP;
- pesFilterParams.pes_type = DMX_PES_VIDEO;
- pesFilterParams.flags = DMX_IMMEDIATE_START;
- if (ioctl(demux1, DMX_SET_PES_FILTER, &pesFilterParams) < 0){
- perror("DEMUX DEVICE");
- return -1;
- }
- pesFilterParams.pid = apid;
- pesFilterParams.input = DMX_IN_FRONTEND;
- pesFilterParams.output = DMX_OUT_TS_TAP;
- pesFilterParams.pes_type = DMX_PES_AUDIO;
- pesFilterParams.flags = DMX_IMMEDIATE_START;
- if (ioctl(demux2, DMX_SET_PES_FILTER, &pesFilterParams) < 0){
- perror("DEMUX DEVICE");
- return -1;
- }
- return 0;
- }
-
- /* start recording MAX_LENGTH , assuming the transponder is tuned */
-
- /* demux1, demux2: file descriptor of video and audio filters */
- /* vpid, apid: PIDs of video and audio channels */
- int record_dvr(int demux1, int demux2, uint16_t vpid, uint16_t apid)
- {
- int i;
- int len;
- int written;
- uint8_t buf[BUFFY];
- uint64_t length;
- struct pollfd pfd[1];
- int dvr, dvr_out;
-
- /* open dvr device */
- if ((dvr = open(DVR, O_RDONLY|O_NONBLOCK)) < 0){
- perror("DVR DEVICE");
- return -1;
- }
-
- /* switch video and audio demuxes to dvr */
- printf ("Switching dvr on\\n");
- i = switch_to_record(demux1, demux2, vpid, apid);
- printf("finished: ");
-
- printf("Recording %2.0f MB of test file in TS format\\n",
- MAX_LENGTH/(1024.0*1024.0));
- length = 0;
-
- /* open output file */
- if ((dvr_out = open(DVR_FILE,O_WRONLY|O_CREAT
- |O_TRUNC, S_IRUSR|S_IWUSR
- |S_IRGRP|S_IWGRP|S_IROTH|
- S_IWOTH)) < 0){
- perror("Can't open file for dvr test");
- return -1;
- }
-
- pfd[0].fd = dvr;
- pfd[0].events = POLLIN;
-
- /* poll for dvr data and write to file */
- while (length < MAX_LENGTH ) {
- if (poll(pfd,1,1)){
- if (pfd[0].revents & POLLIN){
- len = read(dvr, buf, BUFFY);
- if (len < 0){
- perror("recording");
- return -1;
- }
- if (len > 0){
- written = 0;
- while (written < len)
- written +=
- write (dvr_out,
- buf, len);
- length += len;
- printf("written %2.0f MB\\r",
- length/1024./1024.);
- }
- }
- }
- }
- return 0;
- }
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _fe-bandwidth-t:
-
-******************
-Frontend bandwidth
-******************
-
-
-.. _fe-bandwidth:
-
-.. flat-table:: enum fe_bandwidth
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - ID
-
- - Description
-
- - .. row 2
-
- - .. _BANDWIDTH-AUTO:
-
- ``BANDWIDTH_AUTO``
-
- - Autodetect bandwidth (if supported)
-
- - .. row 3
-
- - .. _BANDWIDTH-1-712-MHZ:
-
- ``BANDWIDTH_1_712_MHZ``
-
- - 1.712 MHz
-
- - .. row 4
-
- - .. _BANDWIDTH-5-MHZ:
-
- ``BANDWIDTH_5_MHZ``
-
- - 5 MHz
-
- - .. row 5
-
- - .. _BANDWIDTH-6-MHZ:
-
- ``BANDWIDTH_6_MHZ``
-
- - 6 MHz
-
- - .. row 6
-
- - .. _BANDWIDTH-7-MHZ:
-
- ``BANDWIDTH_7_MHZ``
-
- - 7 MHz
-
- - .. row 7
-
- - .. _BANDWIDTH-8-MHZ:
-
- ``BANDWIDTH_8_MHZ``
-
- - 8 MHz
-
- - .. row 8
-
- - .. _BANDWIDTH-10-MHZ:
-
- ``BANDWIDTH_10_MHZ``
-
- - 10 MHz
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _FE_DISEQC_RECV_SLAVE_REPLY:
-
-********************************
-ioctl FE_DISEQC_RECV_SLAVE_REPLY
-********************************
-
-Name
-====
-
-FE_DISEQC_RECV_SLAVE_REPLY - Receives reply from a DiSEqC 2.0 command
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct dvb_diseqc_slave_reply *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <frontend_f_open>`.
-
-``request``
- FE_DISEQC_RECV_SLAVE_REPLY
-
-``argp``
- pointer to struct
- :ref:`dvb_diseqc_slave_reply <dvb-diseqc-slave-reply>`
-
-
-Description
-===========
-
-Receives reply from a DiSEqC 2.0 command.
-
-.. _dvb-diseqc-slave-reply:
-
-struct dvb_diseqc_slave_reply
------------------------------
-
-.. flat-table:: struct dvb_diseqc_slave_reply
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - uint8_t
-
- - msg[4]
-
- - DiSEqC message (framing, data[3])
-
- - .. row 2
-
- - uint8_t
-
- - msg_len
-
- - Length of the DiSEqC message. Valid values are 0 to 4, where 0
- means no msg
-
- - .. row 3
-
- - int
-
- - timeout
-
- - Return from ioctl after timeout ms with errorcode when no message
- was received
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _FE_DISEQC_RESET_OVERLOAD:
-
-******************************
-ioctl FE_DISEQC_RESET_OVERLOAD
-******************************
-
-Name
-====
-
-FE_DISEQC_RESET_OVERLOAD - Restores the power to the antenna subsystem, if it was powered off due - to power overload.
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, NULL )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <frontend_f_open>`.
-
-``request``
- FE_DISEQC_RESET_OVERLOAD
-
-
-Description
-===========
-
-If the bus has been automatically powered off due to power overload,
-this ioctl call restores the power to the bus. The call requires
-read/write access to the device. This call has no effect if the device
-is manually powered off. Not all DVB adapters support this ioctl.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _FE_DISEQC_SEND_BURST:
-
-**************************
-ioctl FE_DISEQC_SEND_BURST
-**************************
-
-Name
-====
-
-FE_DISEQC_SEND_BURST - Sends a 22KHz tone burst for 2x1 mini DiSEqC satellite selection.
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, enum fe_sec_mini_cmd *tone )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <frontend_f_open>`.
-
-``request``
- FE_DISEQC_SEND_BURST
-
-``tone``
- pointer to enum :ref:`fe_sec_mini_cmd <fe-sec-mini-cmd>`
-
-
-Description
-===========
-
-This ioctl is used to set the generation of a 22kHz tone burst for mini
-DiSEqC satellite selection for 2x1 switches. This call requires
-read/write permissions.
-
-It provides support for what's specified at
-`Digital Satellite Equipment Control (DiSEqC) - Simple "ToneBurst" Detection Circuit specification. <http://www.eutelsat.com/files/contributed/satellites/pdf/Diseqc/associated%20docs/simple_tone_burst_detec.pdf>`__
-
-.. _fe-sec-mini-cmd-t:
-
-enum fe_sec_mini_cmd
-====================
-
-.. _fe-sec-mini-cmd:
-
-.. flat-table:: enum fe_sec_mini_cmd
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - ID
-
- - Description
-
- - .. row 2
-
- - .. _SEC-MINI-A:
-
- ``SEC_MINI_A``
-
- - Sends a mini-DiSEqC 22kHz '0' Tone Burst to select satellite-A
-
- - .. row 3
-
- - .. _SEC-MINI-B:
-
- ``SEC_MINI_B``
-
- - Sends a mini-DiSEqC 22kHz '1' Data Burst to select satellite-B
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _FE_DISEQC_SEND_MASTER_CMD:
-
-*******************************
-ioctl FE_DISEQC_SEND_MASTER_CMD
-*******************************
-
-Name
-====
-
-FE_DISEQC_SEND_MASTER_CMD - Sends a DiSEqC command
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct dvb_diseqc_master_cmd *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <frontend_f_open>`.
-
-``request``
- FE_DISEQC_SEND_MASTER_CMD
-
-``argp``
- pointer to struct
- :ref:`dvb_diseqc_master_cmd <dvb-diseqc-master-cmd>`
-
-
-Description
-===========
-
-Sends a DiSEqC command to the antenna subsystem.
-
-.. _dvb-diseqc-master-cmd:
-
-struct dvb_diseqc_master_cmd
-============================
-
-.. flat-table:: struct dvb_diseqc_master_cmd
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - uint8_t
-
- - msg[6]
-
- - DiSEqC message (framing, address, command, data[3])
-
- - .. row 2
-
- - uint8_t
-
- - msg_len
-
- - Length of the DiSEqC message. Valid values are 3 to 6
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _FE_DISHNETWORK_SEND_LEGACY_CMD:
-
-******************************
-FE_DISHNETWORK_SEND_LEGACY_CMD
-******************************
-
-Name
-====
-
-FE_DISHNETWORK_SEND_LEGACY_CMD
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl(int fd, int request = FE_DISHNETWORK_SEND_LEGACY_CMD, unsigned long cmd)
-
-
-Arguments
-=========
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - unsigned long cmd
-
- - sends the specified raw cmd to the dish via DISEqC.
-
-
-Description
-===========
-
-WARNING: This is a very obscure legacy command, used only at stv0299
-driver. Should not be used on newer drivers.
-
-It provides a non-standard method for selecting Diseqc voltage on the
-frontend, for Dish Network legacy switches.
-
-As support for this ioctl were added in 2004, this means that such
-dishes were already legacy in 2004.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _FE_ENABLE_HIGH_LNB_VOLTAGE:
-
-********************************
-ioctl FE_ENABLE_HIGH_LNB_VOLTAGE
-********************************
-
-Name
-====
-
-FE_ENABLE_HIGH_LNB_VOLTAGE - Select output DC level between normal LNBf voltages or higher LNBf - voltages.
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, unsigned int high )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <frontend_f_open>`.
-
-``request``
- FE_ENABLE_HIGH_LNB_VOLTAGE
-
-``high``
- Valid flags:
-
- - 0 - normal 13V and 18V.
-
- - >0 - enables slightly higher voltages instead of 13/18V, in order
- to compensate for long antenna cables.
-
-
-Description
-===========
-
-Select output DC level between normal LNBf voltages or higher LNBf
-voltages between 0 (normal) or a value grater than 0 for higher
-voltages.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _FE_GET_EVENT:
-
-************
-FE_GET_EVENT
-************
-
-Name
-====
-
-FE_GET_EVENT
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl(int fd, int request = QPSK_GET_EVENT, struct dvb_frontend_event *ev)
-
-
-Arguments
-=========
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals :ref:`FE_GET_EVENT` for this command.
-
- - .. row 3
-
- - struct dvb_frontend_event \*ev
-
- - Points to the location where the event,
-
- - .. row 4
-
- -
- - if any, is to be stored.
-
-
-Description
-===========
-
-This ioctl call returns a frontend event if available. If an event is
-not available, the behavior depends on whether the device is in blocking
-or non-blocking mode. In the latter case, the call fails immediately
-with errno set to ``EWOULDBLOCK``. In the former case, the call blocks until
-an event becomes available.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``EWOULDBLOCK``
-
- - There is no event pending, and the device is in non-blocking mode.
-
- - .. row 2
-
- - ``EOVERFLOW``
-
- - Overflow in event queue - one or more events were lost.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _FE_GET_FRONTEND:
-
-***************
-FE_GET_FRONTEND
-***************
-
-Name
-====
-
-FE_GET_FRONTEND
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl(int fd, int request = FE_GET_FRONTEND, struct dvb_frontend_parameters *p)
-
-
-Arguments
-=========
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals :ref:`FE_SET_FRONTEND` for this
- command.
-
- - .. row 3
-
- - struct dvb_frontend_parameters \*p
-
- - Points to parameters for tuning operation.
-
-
-Description
-===========
-
-This ioctl call queries the currently effective frontend parameters. For
-this command, read-only access to the device is sufficient.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``EINVAL``
-
- - Maximum supported symbol rate reached.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _FE_GET_INFO:
-
-*****************
-ioctl FE_GET_INFO
-*****************
-
-Name
-====
-
-FE_GET_INFO - Query DVB frontend capabilities and returns information about the - front-end. This call only requires read-only access to the device
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct dvb_frontend_info *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <frontend_f_open>`.
-
-``request``
- FE_GET_INFO
-
-``argp``
- pointer to struct struct
- :ref:`dvb_frontend_info <dvb-frontend-info>`
-
-
-Description
-===========
-
-All DVB frontend devices support the ``FE_GET_INFO`` ioctl. It is used
-to identify kernel devices compatible with this specification and to
-obtain information about driver and hardware capabilities. The ioctl
-takes a pointer to dvb_frontend_info which is filled by the driver.
-When the driver is not compatible with this specification the ioctl
-returns an error.
-
-.. _dvb-frontend-info:
-
-struct dvb_frontend_info
-========================
-
-.. flat-table:: struct dvb_frontend_info
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - char
-
- - name[128]
-
- - Name of the frontend
-
- - .. row 2
-
- - fe_type_t
-
- - type
-
- - **DEPRECATED**. DVBv3 type. Should not be used on modern programs,
- as a frontend may have more than one type. So, the DVBv5 API
- should be used instead to enumerate and select the frontend type.
-
- - .. row 3
-
- - uint32_t
-
- - frequency_min
-
- - Minimal frequency supported by the frontend
-
- - .. row 4
-
- - uint32_t
-
- - frequency_max
-
- - Maximal frequency supported by the frontend
-
- - .. row 5
-
- - uint32_t
-
- - frequency_stepsize
-
- - Frequency step - all frequencies are multiple of this value
-
- - .. row 6
-
- - uint32_t
-
- - frequency_tolerance
-
- - Tolerance of the frequency
-
- - .. row 7
-
- - uint32_t
-
- - symbol_rate_min
-
- - Minimal symbol rate (for Cable/Satellite systems), in bauds
-
- - .. row 8
-
- - uint32_t
-
- - symbol_rate_max
-
- - Maximal symbol rate (for Cable/Satellite systems), in bauds
-
- - .. row 9
-
- - uint32_t
-
- - symbol_rate_tolerance
-
- - Maximal symbol rate tolerance, in ppm
-
- - .. row 10
-
- - uint32_t
-
- - notifier_delay
-
- - **DEPRECATED**. Not used by any driver.
-
- - .. row 11
-
- - enum :ref:`fe_caps <fe-caps>`
-
- - caps
-
- - Capabilities supported by the frontend
-
-
-NOTE: The frequencies are specified in Hz for Terrestrial and Cable
-systems. They're specified in kHz for Satellite systems
-
-
-.. _fe-caps-t:
-
-frontend capabilities
-=====================
-
-Capabilities describe what a frontend can do. Some capabilities are
-supported only on some specific frontend types.
-
-
-.. _fe-caps:
-
-.. flat-table:: enum fe_caps
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - ID
-
- - Description
-
- - .. row 2
-
- - .. _FE-IS-STUPID:
-
- ``FE_IS_STUPID``
-
- - There's something wrong at the frontend, and it can't report its
- capabilities
-
- - .. row 3
-
- - .. _FE-CAN-INVERSION-AUTO:
-
- ``FE_CAN_INVERSION_AUTO``
-
- - The frontend is capable of auto-detecting inversion
-
- - .. row 4
-
- - .. _FE-CAN-FEC-1-2:
-
- ``FE_CAN_FEC_1_2``
-
- - The frontend supports FEC 1/2
-
- - .. row 5
-
- - .. _FE-CAN-FEC-2-3:
-
- ``FE_CAN_FEC_2_3``
-
- - The frontend supports FEC 2/3
-
- - .. row 6
-
- - .. _FE-CAN-FEC-3-4:
-
- ``FE_CAN_FEC_3_4``
-
- - The frontend supports FEC 3/4
-
- - .. row 7
-
- - .. _FE-CAN-FEC-4-5:
-
- ``FE_CAN_FEC_4_5``
-
- - The frontend supports FEC 4/5
-
- - .. row 8
-
- - .. _FE-CAN-FEC-5-6:
-
- ``FE_CAN_FEC_5_6``
-
- - The frontend supports FEC 5/6
-
- - .. row 9
-
- - .. _FE-CAN-FEC-6-7:
-
- ``FE_CAN_FEC_6_7``
-
- - The frontend supports FEC 6/7
-
- - .. row 10
-
- - .. _FE-CAN-FEC-7-8:
-
- ``FE_CAN_FEC_7_8``
-
- - The frontend supports FEC 7/8
-
- - .. row 11
-
- - .. _FE-CAN-FEC-8-9:
-
- ``FE_CAN_FEC_8_9``
-
- - The frontend supports FEC 8/9
-
- - .. row 12
-
- - .. _FE-CAN-FEC-AUTO:
-
- ``FE_CAN_FEC_AUTO``
-
- - The frontend can autodetect FEC.
-
- - .. row 13
-
- - .. _FE-CAN-QPSK:
-
- ``FE_CAN_QPSK``
-
- - The frontend supports QPSK modulation
-
- - .. row 14
-
- - .. _FE-CAN-QAM-16:
-
- ``FE_CAN_QAM_16``
-
- - The frontend supports 16-QAM modulation
-
- - .. row 15
-
- - .. _FE-CAN-QAM-32:
-
- ``FE_CAN_QAM_32``
-
- - The frontend supports 32-QAM modulation
-
- - .. row 16
-
- - .. _FE-CAN-QAM-64:
-
- ``FE_CAN_QAM_64``
-
- - The frontend supports 64-QAM modulation
-
- - .. row 17
-
- - .. _FE-CAN-QAM-128:
-
- ``FE_CAN_QAM_128``
-
- - The frontend supports 128-QAM modulation
-
- - .. row 18
-
- - .. _FE-CAN-QAM-256:
-
- ``FE_CAN_QAM_256``
-
- - The frontend supports 256-QAM modulation
-
- - .. row 19
-
- - .. _FE-CAN-QAM-AUTO:
-
- ``FE_CAN_QAM_AUTO``
-
- - The frontend can autodetect modulation
-
- - .. row 20
-
- - .. _FE-CAN-TRANSMISSION-MODE-AUTO:
-
- ``FE_CAN_TRANSMISSION_MODE_AUTO``
-
- - The frontend can autodetect the transmission mode
-
- - .. row 21
-
- - .. _FE-CAN-BANDWIDTH-AUTO:
-
- ``FE_CAN_BANDWIDTH_AUTO``
-
- - The frontend can autodetect the bandwidth
-
- - .. row 22
-
- - .. _FE-CAN-GUARD-INTERVAL-AUTO:
-
- ``FE_CAN_GUARD_INTERVAL_AUTO``
-
- - The frontend can autodetect the guard interval
-
- - .. row 23
-
- - .. _FE-CAN-HIERARCHY-AUTO:
-
- ``FE_CAN_HIERARCHY_AUTO``
-
- - The frontend can autodetect hierarch
-
- - .. row 24
-
- - .. _FE-CAN-8VSB:
-
- ``FE_CAN_8VSB``
-
- - The frontend supports 8-VSB modulation
-
- - .. row 25
-
- - .. _FE-CAN-16VSB:
-
- ``FE_CAN_16VSB``
-
- - The frontend supports 16-VSB modulation
-
- - .. row 26
-
- - .. _FE-HAS-EXTENDED-CAPS:
-
- ``FE_HAS_EXTENDED_CAPS``
-
- - Currently, unused
-
- - .. row 27
-
- - .. _FE-CAN-MULTISTREAM:
-
- ``FE_CAN_MULTISTREAM``
-
- - The frontend supports multistream filtering
-
- - .. row 28
-
- - .. _FE-CAN-TURBO-FEC:
-
- ``FE_CAN_TURBO_FEC``
-
- - The frontend supports turbo FEC modulation
-
- - .. row 29
-
- - .. _FE-CAN-2G-MODULATION:
-
- ``FE_CAN_2G_MODULATION``
-
- - The frontend supports "2nd generation modulation" (DVB-S2/T2)>
-
- - .. row 30
-
- - .. _FE-NEEDS-BENDING:
-
- ``FE_NEEDS_BENDING``
-
- - Not supported anymore, don't use it
-
- - .. row 31
-
- - .. _FE-CAN-RECOVER:
-
- ``FE_CAN_RECOVER``
-
- - The frontend can recover from a cable unplug automatically
-
- - .. row 32
-
- - .. _FE-CAN-MUTE-TS:
-
- ``FE_CAN_MUTE_TS``
-
- - The frontend can stop spurious TS data output
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _FE_GET_PROPERTY:
-
-**************************************
-ioctl FE_SET_PROPERTY, FE_GET_PROPERTY
-**************************************
-
-Name
-====
-
-FE_SET_PROPERTY - FE_GET_PROPERTY - FE_SET_PROPERTY sets one or more frontend properties. - FE_GET_PROPERTY returns one or more frontend properties.
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct dtv_properties *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <frontend_f_open>`.
-
-``request``
- FE_SET_PROPERTY, FE_GET_PROPERTY
-
-``argp``
- pointer to struct :ref:`dtv_properties <dtv-properties>`
-
-
-Description
-===========
-
-All DVB frontend devices support the ``FE_SET_PROPERTY`` and
-``FE_GET_PROPERTY`` ioctls. The supported properties and statistics
-depends on the delivery system and on the device:
-
-- ``FE_SET_PROPERTY:``
-
- - This ioctl is used to set one or more frontend properties.
-
- - This is the basic command to request the frontend to tune into
- some frequency and to start decoding the digital TV signal.
-
- - This call requires read/write access to the device.
-
- - At return, the values are updated to reflect the actual parameters
- used.
-
-- ``FE_GET_PROPERTY:``
-
- - This ioctl is used to get properties and statistics from the
- frontend.
-
- - No properties are changed, and statistics aren't reset.
-
- - This call only requires read-only access to the device.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _FE_READ_BER:
-
-***********
-FE_READ_BER
-***********
-
-Name
-====
-
-FE_READ_BER
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl(int fd, int request = FE_READ_BER, uint32_t *ber)
-
-
-Arguments
-=========
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals :ref:`FE_READ_BER` for this command.
-
- - .. row 3
-
- - uint32_t \*ber
-
- - The bit error rate is stored into \*ber.
-
-
-Description
-===========
-
-This ioctl call returns the bit error rate for the signal currently
-received/demodulated by the front-end. For this command, read-only
-access to the device is sufficient.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _FE_READ_SIGNAL_STRENGTH:
-
-***********************
-FE_READ_SIGNAL_STRENGTH
-***********************
-
-Name
-====
-
-FE_READ_SIGNAL_STRENGTH
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request = FE_READ_SIGNAL_STRENGTH, uint16_t *strength)
-
-
-Arguments
-=========
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals
- :ref:`FE_READ_SIGNAL_STRENGTH`
- for this command.
-
- - .. row 3
-
- - uint16_t \*strength
-
- - The signal strength value is stored into \*strength.
-
-
-Description
-===========
-
-This ioctl call returns the signal strength value for the signal
-currently received by the front-end. For this command, read-only access
-to the device is sufficient.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _FE_READ_SNR:
-
-***********
-FE_READ_SNR
-***********
-
-Name
-====
-
-FE_READ_SNR
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl(int fd, int request = FE_READ_SNR, int16_t *snr)
-
-
-Arguments
-=========
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals :ref:`FE_READ_SNR` for this command.
-
- - .. row 3
-
- - uint16_t \*snr
-
- - The signal-to-noise ratio is stored into \*snr.
-
-
-Description
-===========
-
-This ioctl call returns the signal-to-noise ratio for the signal
-currently received by the front-end. For this command, read-only access
-to the device is sufficient.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _FE_READ_STATUS:
-
-********************
-ioctl FE_READ_STATUS
-********************
-
-Name
-====
-
-FE_READ_STATUS - Returns status information about the front-end. This call only requires - read-only access to the device
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, unsigned int *status )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <frontend_f_open>`.
-
-``request``
- FE_READ_STATUS
-
-``status``
- pointer to a bitmask integer filled with the values defined by enum
- :ref:`fe_status <fe-status>`.
-
-
-Description
-===========
-
-All DVB frontend devices support the ``FE_READ_STATUS`` ioctl. It is
-used to check about the locking status of the frontend after being
-tuned. The ioctl takes a pointer to an integer where the status will be
-written.
-
-NOTE: the size of status is actually sizeof(enum fe_status), with
-varies according with the architecture. This needs to be fixed in the
-future.
-
-
-.. _fe-status-t:
-
-int fe_status
-=============
-
-The fe_status parameter is used to indicate the current state and/or
-state changes of the frontend hardware. It is produced using the enum
-:ref:`fe_status <fe-status>` values on a bitmask
-
-
-.. _fe-status:
-
-.. flat-table:: enum fe_status
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - ID
-
- - Description
-
- - .. row 2
-
- - .. _FE-HAS-SIGNAL:
-
- ``FE_HAS_SIGNAL``
-
- - The frontend has found something above the noise level
-
- - .. row 3
-
- - .. _FE-HAS-CARRIER:
-
- ``FE_HAS_CARRIER``
-
- - The frontend has found a DVB signal
-
- - .. row 4
-
- - .. _FE-HAS-VITERBI:
-
- ``FE_HAS_VITERBI``
-
- - The frontend FEC inner coding (Viterbi, LDPC or other inner code)
- is stable
-
- - .. row 5
-
- - .. _FE-HAS-SYNC:
-
- ``FE_HAS_SYNC``
-
- - Synchronization bytes was found
-
- - .. row 6
-
- - .. _FE-HAS-LOCK:
-
- ``FE_HAS_LOCK``
-
- - The DVB were locked and everything is working
-
- - .. row 7
-
- - .. _FE-TIMEDOUT:
-
- ``FE_TIMEDOUT``
-
- - no lock within the last about 2 seconds
-
- - .. row 8
-
- - .. _FE-REINIT:
-
- ``FE_REINIT``
-
- - The frontend was reinitialized, application is recommended to
- reset DiSEqC, tone and parameters
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _FE_READ_UNCORRECTED_BLOCKS:
-
-**************************
-FE_READ_UNCORRECTED_BLOCKS
-**************************
-
-Name
-====
-
-FE_READ_UNCORRECTED_BLOCKS
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request =FE_READ_UNCORRECTED_BLOCKS, uint32_t *ublocks)
-
-
-Arguments
-=========
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals
- :ref:`FE_READ_UNCORRECTED_BLOCKS`
- for this command.
-
- - .. row 3
-
- - uint32_t \*ublocks
-
- - The total number of uncorrected blocks seen by the driver so far.
-
-
-Description
-===========
-
-This ioctl call returns the number of uncorrected blocks detected by the
-device driver during its lifetime. For meaningful measurements, the
-increment in block count during a specific time interval should be
-calculated. For this command, read-only access to the device is
-sufficient.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _FE_SET_FRONTEND_TUNE_MODE:
-
-*******************************
-ioctl FE_SET_FRONTEND_TUNE_MODE
-*******************************
-
-Name
-====
-
-FE_SET_FRONTEND_TUNE_MODE - Allow setting tuner mode flags to the frontend.
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, unsigned int flags )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <frontend_f_open>`.
-
-``request``
- FE_SET_FRONTEND_TUNE_MODE
-
-``flags``
- Valid flags:
-
- - 0 - normal tune mode
-
- - FE_TUNE_MODE_ONESHOT - When set, this flag will disable any
- zigzagging or other "normal" tuning behaviour. Additionally,
- there will be no automatic monitoring of the lock status, and
- hence no frontend events will be generated. If a frontend device
- is closed, this flag will be automatically turned off when the
- device is reopened read-write.
-
-
-Description
-===========
-
-Allow setting tuner mode flags to the frontend, between 0 (normal) or
-FE_TUNE_MODE_ONESHOT mode
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _FE_SET_FRONTEND:
-
-***************
-FE_SET_FRONTEND
-***************
-
-Name
-====
-
-FE_SET_FRONTEND
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl(int fd, int request = FE_SET_FRONTEND, struct dvb_frontend_parameters *p)
-
-
-Arguments
-=========
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals :ref:`FE_SET_FRONTEND` for this
- command.
-
- - .. row 3
-
- - struct dvb_frontend_parameters \*p
-
- - Points to parameters for tuning operation.
-
-
-Description
-===========
-
-This ioctl call starts a tuning operation using specified parameters.
-The result of this call will be successful if the parameters were valid
-and the tuning could be initiated. The result of the tuning operation in
-itself, however, will arrive asynchronously as an event (see
-documentation for :ref:`FE_GET_EVENT` and
-FrontendEvent.) If a new :ref:`FE_SET_FRONTEND`
-operation is initiated before the previous one was completed, the
-previous operation will be aborted in favor of the new one. This command
-requires read/write access to the device.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``EINVAL``
-
- - Maximum supported symbol rate reached.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _FE_SET_TONE:
-
-*****************
-ioctl FE_SET_TONE
-*****************
-
-Name
-====
-
-FE_SET_TONE - Sets/resets the generation of the continuous 22kHz tone.
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, enum fe_sec_tone_mode *tone )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <frontend_f_open>`.
-
-``request``
- FE_SET_TONE
-
-``tone``
- pointer to enum :ref:`fe_sec_tone_mode <fe-sec-tone-mode>`
-
-
-Description
-===========
-
-This ioctl is used to set the generation of the continuous 22kHz tone.
-This call requires read/write permissions.
-
-Usually, satellite antenna subsystems require that the digital TV device
-to send a 22kHz tone in order to select between high/low band on some
-dual-band LNBf. It is also used to send signals to DiSEqC equipment, but
-this is done using the DiSEqC ioctls.
-
-NOTE: if more than one device is connected to the same antenna, setting
-a tone may interfere on other devices, as they may lose the capability
-of selecting the band. So, it is recommended that applications would
-change to SEC_TONE_OFF when the device is not used.
-
-.. _fe-sec-tone-mode-t:
-
-enum fe_sec_tone_mode
-=====================
-
-.. _fe-sec-tone-mode:
-
-.. flat-table:: enum fe_sec_tone_mode
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - ID
-
- - Description
-
- - .. row 2
-
- - .. _SEC-TONE-ON:
-
- ``SEC_TONE_ON``
-
- - Sends a 22kHz tone burst to the antenna
-
- - .. row 3
-
- - .. _SEC-TONE-OFF:
-
- ``SEC_TONE_OFF``
-
- - Don't send a 22kHz tone to the antenna (except if the
- FE_DISEQC_* ioctls are called)
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _FE_SET_VOLTAGE:
-
-********************
-ioctl FE_SET_VOLTAGE
-********************
-
-Name
-====
-
-FE_SET_VOLTAGE - Allow setting the DC level sent to the antenna subsystem.
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, enum fe_sec_voltage *voltage )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <frontend_f_open>`.
-
-``request``
- FE_SET_VOLTAGE
-
-``voltage``
- pointer to enum :ref:`fe_sec_voltage <fe-sec-voltage>`
-
- Valid values are described at enum
- :ref:`fe_sec_voltage <fe-sec-voltage>`.
-
-
-Description
-===========
-
-This ioctl allows to set the DC voltage level sent through the antenna
-cable to 13V, 18V or off.
-
-Usually, a satellite antenna subsystems require that the digital TV
-device to send a DC voltage to feed power to the LNBf. Depending on the
-LNBf type, the polarization or the intermediate frequency (IF) of the
-LNBf can controlled by the voltage level. Other devices (for example,
-the ones that implement DISEqC and multipoint LNBf's don't need to
-control the voltage level, provided that either 13V or 18V is sent to
-power up the LNBf.
-
-NOTE: if more than one device is connected to the same antenna, setting
-a voltage level may interfere on other devices, as they may lose the
-capability of setting polarization or IF. So, on those cases, setting
-the voltage to SEC_VOLTAGE_OFF while the device is not is used is
-recommended.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _fe-type-t:
-
-*************
-Frontend type
-*************
-
-For historical reasons, frontend types are named by the type of
-modulation used in transmission. The fontend types are given by
-fe_type_t type, defined as:
-
-
-.. _fe-type:
-
-.. flat-table:: Frontend types
- :header-rows: 1
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - fe_type
-
- - Description
-
- - :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>` equivalent
- type
-
- - .. row 2
-
- - .. _FE-QPSK:
-
- ``FE_QPSK``
-
- - For DVB-S standard
-
- - ``SYS_DVBS``
-
- - .. row 3
-
- - .. _FE-QAM:
-
- ``FE_QAM``
-
- - For DVB-C annex A standard
-
- - ``SYS_DVBC_ANNEX_A``
-
- - .. row 4
-
- - .. _FE-OFDM:
-
- ``FE_OFDM``
-
- - For DVB-T standard
-
- - ``SYS_DVBT``
-
- - .. row 5
-
- - .. _FE-ATSC:
-
- ``FE_ATSC``
-
- - For ATSC standard (terrestrial) or for DVB-C Annex B (cable) used
- in US.
-
- - ``SYS_ATSC`` (terrestrial) or ``SYS_DVBC_ANNEX_B`` (cable)
-
-
-Newer formats like DVB-S2, ISDB-T, ISDB-S and DVB-T2 are not described
-at the above, as they're supported via the new
-:ref:`FE_GET_PROPERTY/FE_GET_SET_PROPERTY <FE_GET_PROPERTY>`
-ioctl's, using the :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`
-parameter.
-
-In the old days, struct :ref:`dvb_frontend_info <dvb-frontend-info>`
-used to contain ``fe_type_t`` field to indicate the delivery systems,
-filled with either FE_QPSK, FE_QAM, FE_OFDM or FE_ATSC. While this
-is still filled to keep backward compatibility, the usage of this field
-is deprecated, as it can report just one delivery system, but some
-devices support multiple delivery systems. Please use
-:ref:`DTV_ENUM_DELSYS <DTV-ENUM-DELSYS>` instead.
-
-On devices that support multiple delivery systems, struct
-:ref:`dvb_frontend_info <dvb-frontend-info>`::``fe_type_t`` is
-filled with the currently standard, as selected by the last call to
-:ref:`FE_SET_PROPERTY <FE_GET_PROPERTY>` using the
-:ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>` property.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _fe_property_parameters:
-
-******************************
-Digital TV property parameters
-******************************
-
-
-.. _DTV-UNDEFINED:
-
-DTV_UNDEFINED
-=============
-
-Used internally. A GET/SET operation for it won't change or return
-anything.
-
-
-.. _DTV-TUNE:
-
-DTV_TUNE
-========
-
-Interpret the cache of data, build either a traditional frontend
-tunerequest so we can pass validation in the ``FE_SET_FRONTEND`` ioctl.
-
-
-.. _DTV-CLEAR:
-
-DTV_CLEAR
-=========
-
-Reset a cache of data specific to the frontend here. This does not
-effect hardware.
-
-
-.. _DTV-FREQUENCY:
-
-DTV_FREQUENCY
-=============
-
-Central frequency of the channel.
-
-Notes:
-
-1)For satellite delivery systems, it is measured in kHz. For the other
-ones, it is measured in Hz.
-
-2)For ISDB-T, the channels are usually transmitted with an offset of
-143kHz. E.g. a valid frequency could be 474143 kHz. The stepping is
-bound to the bandwidth of the channel which is 6MHz.
-
-3)As in ISDB-Tsb the channel consists of only one or three segments the
-frequency step is 429kHz, 3*429 respectively. As for ISDB-T the central
-frequency of the channel is expected.
-
-
-.. _DTV-MODULATION:
-
-DTV_MODULATION
-==============
-
-Specifies the frontend modulation type for delivery systems that
-supports more than one modulation type. The modulation can be one of the
-types defined by enum :ref:`fe_modulation <fe-modulation>`.
-
-
-.. _fe-modulation-t:
-
-Modulation property
--------------------
-
-Most of the digital TV standards currently offers more than one possible
-modulation (sometimes called as "constellation" on some standards). This
-enum contains the values used by the Kernel. Please note that not all
-modulations are supported by a given standard.
-
-
-.. _fe-modulation:
-
-.. flat-table:: enum fe_modulation
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - ID
-
- - Description
-
- - .. row 2
-
- - .. _QPSK:
-
- ``QPSK``
-
- - QPSK modulation
-
- - .. row 3
-
- - .. _QAM-16:
-
- ``QAM_16``
-
- - 16-QAM modulation
-
- - .. row 4
-
- - .. _QAM-32:
-
- ``QAM_32``
-
- - 32-QAM modulation
-
- - .. row 5
-
- - .. _QAM-64:
-
- ``QAM_64``
-
- - 64-QAM modulation
-
- - .. row 6
-
- - .. _QAM-128:
-
- ``QAM_128``
-
- - 128-QAM modulation
-
- - .. row 7
-
- - .. _QAM-256:
-
- ``QAM_256``
-
- - 256-QAM modulation
-
- - .. row 8
-
- - .. _QAM-AUTO:
-
- ``QAM_AUTO``
-
- - Autodetect QAM modulation
-
- - .. row 9
-
- - .. _VSB-8:
-
- ``VSB_8``
-
- - 8-VSB modulation
-
- - .. row 10
-
- - .. _VSB-16:
-
- ``VSB_16``
-
- - 16-VSB modulation
-
- - .. row 11
-
- - .. _PSK-8:
-
- ``PSK_8``
-
- - 8-PSK modulation
-
- - .. row 12
-
- - .. _APSK-16:
-
- ``APSK_16``
-
- - 16-APSK modulation
-
- - .. row 13
-
- - .. _APSK-32:
-
- ``APSK_32``
-
- - 32-APSK modulation
-
- - .. row 14
-
- - .. _DQPSK:
-
- ``DQPSK``
-
- - DQPSK modulation
-
- - .. row 15
-
- - .. _QAM-4-NR:
-
- ``QAM_4_NR``
-
- - 4-QAM-NR modulation
-
-
-
-.. _DTV-BANDWIDTH-HZ:
-
-DTV_BANDWIDTH_HZ
-================
-
-Bandwidth for the channel, in HZ.
-
-Possible values: ``1712000``, ``5000000``, ``6000000``, ``7000000``,
-``8000000``, ``10000000``.
-
-Notes:
-
-1) For ISDB-T it should be always 6000000Hz (6MHz)
-
-2) For ISDB-Tsb it can vary depending on the number of connected
-segments
-
-3) Bandwidth doesn't apply for DVB-C transmissions, as the bandwidth for
-DVB-C depends on the symbol rate
-
-4) Bandwidth in ISDB-T is fixed (6MHz) or can be easily derived from
-other parameters (DTV_ISDBT_SB_SEGMENT_IDX,
-DTV_ISDBT_SB_SEGMENT_COUNT).
-
-5) DVB-T supports 6, 7 and 8MHz.
-
-6) In addition, DVB-T2 supports 1.172, 5 and 10MHz.
-
-
-.. _DTV-INVERSION:
-
-DTV_INVERSION
-=============
-
-Specifies if the frontend should do spectral inversion or not.
-
-
-.. _fe-spectral-inversion-t:
-
-enum fe_modulation: Frontend spectral inversion
------------------------------------------------
-
-This parameter indicates if spectral inversion should be presumed or
-not. In the automatic setting (``INVERSION_AUTO``) the hardware will try
-to figure out the correct setting by itself. If the hardware doesn't
-support, the DVB core will try to lock at the carrier first with
-inversion off. If it fails, it will try to enable inversion.
-
-
-.. _fe-spectral-inversion:
-
-.. flat-table:: enum fe_modulation
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - ID
-
- - Description
-
- - .. row 2
-
- - .. _INVERSION-OFF:
-
- ``INVERSION_OFF``
-
- - Don't do spectral band inversion.
-
- - .. row 3
-
- - .. _INVERSION-ON:
-
- ``INVERSION_ON``
-
- - Do spectral band inversion.
-
- - .. row 4
-
- - .. _INVERSION-AUTO:
-
- ``INVERSION_AUTO``
-
- - Autodetect spectral band inversion.
-
-
-
-.. _DTV-DISEQC-MASTER:
-
-DTV_DISEQC_MASTER
-=================
-
-Currently not implemented.
-
-
-.. _DTV-SYMBOL-RATE:
-
-DTV_SYMBOL_RATE
-===============
-
-Digital TV symbol rate, in bauds (symbols/second). Used on cable
-standards.
-
-
-.. _DTV-INNER-FEC:
-
-DTV_INNER_FEC
-=============
-
-Used cable/satellite transmissions. The acceptable values are:
-
-
-.. _fe-code-rate-t:
-
-enum fe_code_rate: type of the Forward Error Correction.
---------------------------------------------------------
-
-
-.. _fe-code-rate:
-
-.. flat-table:: enum fe_code_rate
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - ID
-
- - Description
-
- - .. row 2
-
- - .. _FEC-NONE:
-
- ``FEC_NONE``
-
- - No Forward Error Correction Code
-
- - .. row 3
-
- - .. _FEC-AUTO:
-
- ``FEC_AUTO``
-
- - Autodetect Error Correction Code
-
- - .. row 4
-
- - .. _FEC-1-2:
-
- ``FEC_1_2``
-
- - Forward Error Correction Code 1/2
-
- - .. row 5
-
- - .. _FEC-2-3:
-
- ``FEC_2_3``
-
- - Forward Error Correction Code 2/3
-
- - .. row 6
-
- - .. _FEC-3-4:
-
- ``FEC_3_4``
-
- - Forward Error Correction Code 3/4
-
- - .. row 7
-
- - .. _FEC-4-5:
-
- ``FEC_4_5``
-
- - Forward Error Correction Code 4/5
-
- - .. row 8
-
- - .. _FEC-5-6:
-
- ``FEC_5_6``
-
- - Forward Error Correction Code 5/6
-
- - .. row 9
-
- - .. _FEC-6-7:
-
- ``FEC_6_7``
-
- - Forward Error Correction Code 6/7
-
- - .. row 10
-
- - .. _FEC-7-8:
-
- ``FEC_7_8``
-
- - Forward Error Correction Code 7/8
-
- - .. row 11
-
- - .. _FEC-8-9:
-
- ``FEC_8_9``
-
- - Forward Error Correction Code 8/9
-
- - .. row 12
-
- - .. _FEC-9-10:
-
- ``FEC_9_10``
-
- - Forward Error Correction Code 9/10
-
- - .. row 13
-
- - .. _FEC-2-5:
-
- ``FEC_2_5``
-
- - Forward Error Correction Code 2/5
-
- - .. row 14
-
- - .. _FEC-3-5:
-
- ``FEC_3_5``
-
- - Forward Error Correction Code 3/5
-
-
-
-.. _DTV-VOLTAGE:
-
-DTV_VOLTAGE
-===========
-
-The voltage is usually used with non-DiSEqC capable LNBs to switch the
-polarzation (horizontal/vertical). When using DiSEqC epuipment this
-voltage has to be switched consistently to the DiSEqC commands as
-described in the DiSEqC spec.
-
-
-.. _fe-sec-voltage:
-
-.. flat-table:: enum fe_sec_voltage
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - ID
-
- - Description
-
- - .. row 2
-
- - .. _SEC-VOLTAGE-13:
-
- ``SEC_VOLTAGE_13``
-
- - Set DC voltage level to 13V
-
- - .. row 3
-
- - .. _SEC-VOLTAGE-18:
-
- ``SEC_VOLTAGE_18``
-
- - Set DC voltage level to 18V
-
- - .. row 4
-
- - .. _SEC-VOLTAGE-OFF:
-
- ``SEC_VOLTAGE_OFF``
-
- - Don't send any voltage to the antenna
-
-
-
-.. _DTV-TONE:
-
-DTV_TONE
-========
-
-Currently not used.
-
-
-.. _DTV-PILOT:
-
-DTV_PILOT
-=========
-
-Sets DVB-S2 pilot
-
-
-.. _fe-pilot-t:
-
-fe_pilot type
--------------
-
-
-.. _fe-pilot:
-
-.. flat-table:: enum fe_pilot
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - ID
-
- - Description
-
- - .. row 2
-
- - .. _PILOT-ON:
-
- ``PILOT_ON``
-
- - Pilot tones enabled
-
- - .. row 3
-
- - .. _PILOT-OFF:
-
- ``PILOT_OFF``
-
- - Pilot tones disabled
-
- - .. row 4
-
- - .. _PILOT-AUTO:
-
- ``PILOT_AUTO``
-
- - Autodetect pilot tones
-
-
-
-.. _DTV-ROLLOFF:
-
-DTV_ROLLOFF
-===========
-
-Sets DVB-S2 rolloff
-
-
-.. _fe-rolloff-t:
-
-fe_rolloff type
----------------
-
-
-.. _fe-rolloff:
-
-.. flat-table:: enum fe_rolloff
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - ID
-
- - Description
-
- - .. row 2
-
- - .. _ROLLOFF-35:
-
- ``ROLLOFF_35``
-
- - Roloff factor: α=35%
-
- - .. row 3
-
- - .. _ROLLOFF-20:
-
- ``ROLLOFF_20``
-
- - Roloff factor: α=20%
-
- - .. row 4
-
- - .. _ROLLOFF-25:
-
- ``ROLLOFF_25``
-
- - Roloff factor: α=25%
-
- - .. row 5
-
- - .. _ROLLOFF-AUTO:
-
- ``ROLLOFF_AUTO``
-
- - Auto-detect the roloff factor.
-
-
-
-.. _DTV-DISEQC-SLAVE-REPLY:
-
-DTV_DISEQC_SLAVE_REPLY
-======================
-
-Currently not implemented.
-
-
-.. _DTV-FE-CAPABILITY-COUNT:
-
-DTV_FE_CAPABILITY_COUNT
-=======================
-
-Currently not implemented.
-
-
-.. _DTV-FE-CAPABILITY:
-
-DTV_FE_CAPABILITY
-=================
-
-Currently not implemented.
-
-
-.. _DTV-DELIVERY-SYSTEM:
-
-DTV_DELIVERY_SYSTEM
-===================
-
-Specifies the type of Delivery system
-
-
-.. _fe-delivery-system-t:
-
-fe_delivery_system type
------------------------
-
-Possible values:
-
-
-.. _fe-delivery-system:
-
-.. flat-table:: enum fe_delivery_system
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - ID
-
- - Description
-
- - .. row 2
-
- - .. _SYS-UNDEFINED:
-
- ``SYS_UNDEFINED``
-
- - Undefined standard. Generally, indicates an error
-
- - .. row 3
-
- - .. _SYS-DVBC-ANNEX-A:
-
- ``SYS_DVBC_ANNEX_A``
-
- - Cable TV: DVB-C following ITU-T J.83 Annex A spec
-
- - .. row 4
-
- - .. _SYS-DVBC-ANNEX-B:
-
- ``SYS_DVBC_ANNEX_B``
-
- - Cable TV: DVB-C following ITU-T J.83 Annex B spec (ClearQAM)
-
- - .. row 5
-
- - .. _SYS-DVBC-ANNEX-C:
-
- ``SYS_DVBC_ANNEX_C``
-
- - Cable TV: DVB-C following ITU-T J.83 Annex C spec
-
- - .. row 6
-
- - .. _SYS-ISDBC:
-
- ``SYS_ISDBC``
-
- - Cable TV: ISDB-C (no drivers yet)
-
- - .. row 7
-
- - .. _SYS-DVBT:
-
- ``SYS_DVBT``
-
- - Terrestral TV: DVB-T
-
- - .. row 8
-
- - .. _SYS-DVBT2:
-
- ``SYS_DVBT2``
-
- - Terrestral TV: DVB-T2
-
- - .. row 9
-
- - .. _SYS-ISDBT:
-
- ``SYS_ISDBT``
-
- - Terrestral TV: ISDB-T
-
- - .. row 10
-
- - .. _SYS-ATSC:
-
- ``SYS_ATSC``
-
- - Terrestral TV: ATSC
-
- - .. row 11
-
- - .. _SYS-ATSCMH:
-
- ``SYS_ATSCMH``
-
- - Terrestral TV (mobile): ATSC-M/H
-
- - .. row 12
-
- - .. _SYS-DTMB:
-
- ``SYS_DTMB``
-
- - Terrestrial TV: DTMB
-
- - .. row 13
-
- - .. _SYS-DVBS:
-
- ``SYS_DVBS``
-
- - Satellite TV: DVB-S
-
- - .. row 14
-
- - .. _SYS-DVBS2:
-
- ``SYS_DVBS2``
-
- - Satellite TV: DVB-S2
-
- - .. row 15
-
- - .. _SYS-TURBO:
-
- ``SYS_TURBO``
-
- - Satellite TV: DVB-S Turbo
-
- - .. row 16
-
- - .. _SYS-ISDBS:
-
- ``SYS_ISDBS``
-
- - Satellite TV: ISDB-S
-
- - .. row 17
-
- - .. _SYS-DAB:
-
- ``SYS_DAB``
-
- - Digital audio: DAB (not fully supported)
-
- - .. row 18
-
- - .. _SYS-DSS:
-
- ``SYS_DSS``
-
- - Satellite TV:"DSS (not fully supported)
-
- - .. row 19
-
- - .. _SYS-CMMB:
-
- ``SYS_CMMB``
-
- - Terrestral TV (mobile):CMMB (not fully supported)
-
- - .. row 20
-
- - .. _SYS-DVBH:
-
- ``SYS_DVBH``
-
- - Terrestral TV (mobile): DVB-H (standard deprecated)
-
-
-
-.. _DTV-ISDBT-PARTIAL-RECEPTION:
-
-DTV_ISDBT_PARTIAL_RECEPTION
-===========================
-
-If ``DTV_ISDBT_SOUND_BROADCASTING`` is '0' this bit-field represents
-whether the channel is in partial reception mode or not.
-
-If '1' ``DTV_ISDBT_LAYERA_*`` values are assigned to the center segment
-and ``DTV_ISDBT_LAYERA_SEGMENT_COUNT`` has to be '1'.
-
-If in addition ``DTV_ISDBT_SOUND_BROADCASTING`` is '1'
-``DTV_ISDBT_PARTIAL_RECEPTION`` represents whether this ISDB-Tsb channel
-is consisting of one segment and layer or three segments and two layers.
-
-Possible values: 0, 1, -1 (AUTO)
-
-
-.. _DTV-ISDBT-SOUND-BROADCASTING:
-
-DTV_ISDBT_SOUND_BROADCASTING
-============================
-
-This field represents whether the other DTV_ISDBT_*-parameters are
-referring to an ISDB-T and an ISDB-Tsb channel. (See also
-``DTV_ISDBT_PARTIAL_RECEPTION``).
-
-Possible values: 0, 1, -1 (AUTO)
-
-
-.. _DTV-ISDBT-SB-SUBCHANNEL-ID:
-
-DTV_ISDBT_SB_SUBCHANNEL_ID
-==========================
-
-This field only applies if ``DTV_ISDBT_SOUND_BROADCASTING`` is '1'.
-
-(Note of the author: This might not be the correct description of the
-``SUBCHANNEL-ID`` in all details, but it is my understanding of the
-technical background needed to program a device)
-
-An ISDB-Tsb channel (1 or 3 segments) can be broadcasted alone or in a
-set of connected ISDB-Tsb channels. In this set of channels every
-channel can be received independently. The number of connected ISDB-Tsb
-segment can vary, e.g. depending on the frequency spectrum bandwidth
-available.
-
-Example: Assume 8 ISDB-Tsb connected segments are broadcasted. The
-broadcaster has several possibilities to put those channels in the air:
-Assuming a normal 13-segment ISDB-T spectrum he can align the 8 segments
-from position 1-8 to 5-13 or anything in between.
-
-The underlying layer of segments are subchannels: each segment is
-consisting of several subchannels with a predefined IDs. A sub-channel
-is used to help the demodulator to synchronize on the channel.
-
-An ISDB-T channel is always centered over all sub-channels. As for the
-example above, in ISDB-Tsb it is no longer as simple as that.
-
-``The DTV_ISDBT_SB_SUBCHANNEL_ID`` parameter is used to give the
-sub-channel ID of the segment to be demodulated.
-
-Possible values: 0 .. 41, -1 (AUTO)
-
-
-.. _DTV-ISDBT-SB-SEGMENT-IDX:
-
-DTV_ISDBT_SB_SEGMENT_IDX
-========================
-
-This field only applies if ``DTV_ISDBT_SOUND_BROADCASTING`` is '1'.
-
-``DTV_ISDBT_SB_SEGMENT_IDX`` gives the index of the segment to be
-demodulated for an ISDB-Tsb channel where several of them are
-transmitted in the connected manner.
-
-Possible values: 0 .. ``DTV_ISDBT_SB_SEGMENT_COUNT`` - 1
-
-Note: This value cannot be determined by an automatic channel search.
-
-
-.. _DTV-ISDBT-SB-SEGMENT-COUNT:
-
-DTV_ISDBT_SB_SEGMENT_COUNT
-==========================
-
-This field only applies if ``DTV_ISDBT_SOUND_BROADCASTING`` is '1'.
-
-``DTV_ISDBT_SB_SEGMENT_COUNT`` gives the total count of connected
-ISDB-Tsb channels.
-
-Possible values: 1 .. 13
-
-Note: This value cannot be determined by an automatic channel search.
-
-
-.. _isdb-hierq-layers:
-
-DTV-ISDBT-LAYER[A-C] parameters
-===============================
-
-ISDB-T channels can be coded hierarchically. As opposed to DVB-T in
-ISDB-T hierarchical layers can be decoded simultaneously. For that
-reason a ISDB-T demodulator has 3 Viterbi and 3 Reed-Solomon decoders.
-
-ISDB-T has 3 hierarchical layers which each can use a part of the
-available segments. The total number of segments over all layers has to
-13 in ISDB-T.
-
-There are 3 parameter sets, for Layers A, B and C.
-
-
-.. _DTV-ISDBT-LAYER-ENABLED:
-
-DTV_ISDBT_LAYER_ENABLED
------------------------
-
-Hierarchical reception in ISDB-T is achieved by enabling or disabling
-layers in the decoding process. Setting all bits of
-``DTV_ISDBT_LAYER_ENABLED`` to '1' forces all layers (if applicable) to
-be demodulated. This is the default.
-
-If the channel is in the partial reception mode
-(``DTV_ISDBT_PARTIAL_RECEPTION`` = 1) the central segment can be decoded
-independently of the other 12 segments. In that mode layer A has to have
-a ``SEGMENT_COUNT`` of 1.
-
-In ISDB-Tsb only layer A is used, it can be 1 or 3 in ISDB-Tsb according
-to ``DTV_ISDBT_PARTIAL_RECEPTION``. ``SEGMENT_COUNT`` must be filled
-accordingly.
-
-Only the values of the first 3 bits are used. Other bits will be silently ignored:
-
-``DTV_ISDBT_LAYER_ENABLED`` bit 0: layer A enabled
-
-``DTV_ISDBT_LAYER_ENABLED`` bit 1: layer B enabled
-
-``DTV_ISDBT_LAYER_ENABLED`` bit 2: layer C enabled
-
-``DTV_ISDBT_LAYER_ENABLED`` bits 3-31: unused
-
-
-.. _DTV-ISDBT-LAYER-FEC:
-
-DTV_ISDBT_LAYER[A-C]_FEC
-------------------------
-
-Possible values: ``FEC_AUTO``, ``FEC_1_2``, ``FEC_2_3``, ``FEC_3_4``,
-``FEC_5_6``, ``FEC_7_8``
-
-
-.. _DTV-ISDBT-LAYER-MODULATION:
-
-DTV_ISDBT_LAYER[A-C]_MODULATION
--------------------------------
-
-Possible values: ``QAM_AUTO``, QP\ ``SK, QAM_16``, ``QAM_64``, ``DQPSK``
-
-Note: If layer C is ``DQPSK`` layer B has to be ``DQPSK``. If layer B is
-``DQPSK`` and ``DTV_ISDBT_PARTIAL_RECEPTION``\ =0 layer has to be
-``DQPSK``.
-
-
-.. _DTV-ISDBT-LAYER-SEGMENT-COUNT:
-
-DTV_ISDBT_LAYER[A-C]_SEGMENT_COUNT
-----------------------------------
-
-Possible values: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, -1 (AUTO)
-
-Note: Truth table for ``DTV_ISDBT_SOUND_BROADCASTING`` and
-``DTV_ISDBT_PARTIAL_RECEPTION`` and ``LAYER[A-C]_SEGMENT_COUNT``
-
-
-.. _isdbt-layer_seg-cnt-table:
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - PR
-
- - SB
-
- - Layer A width
-
- - Layer B width
-
- - Layer C width
-
- - total width
-
- - .. row 2
-
- - 0
-
- - 0
-
- - 1 .. 13
-
- - 1 .. 13
-
- - 1 .. 13
-
- - 13
-
- - .. row 3
-
- - 1
-
- - 0
-
- - 1
-
- - 1 .. 13
-
- - 1 .. 13
-
- - 13
-
- - .. row 4
-
- - 0
-
- - 1
-
- - 1
-
- - 0
-
- - 0
-
- - 1
-
- - .. row 5
-
- - 1
-
- - 1
-
- - 1
-
- - 2
-
- - 0
-
- - 13
-
-
-
-.. _DTV-ISDBT-LAYER-TIME-INTERLEAVING:
-
-DTV_ISDBT_LAYER[A-C]_TIME_INTERLEAVING
---------------------------------------
-
-Valid values: 0, 1, 2, 4, -1 (AUTO)
-
-when DTV_ISDBT_SOUND_BROADCASTING is active, value 8 is also valid.
-
-Note: The real time interleaving length depends on the mode (fft-size).
-The values here are referring to what can be found in the
-TMCC-structure, as shown in the table below.
-
-
-.. _isdbt-layer-interleaving-table:
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``DTV_ISDBT_LAYER[A-C]_TIME_INTERLEAVING``
-
- - Mode 1 (2K FFT)
-
- - Mode 2 (4K FFT)
-
- - Mode 3 (8K FFT)
-
- - .. row 2
-
- - 0
-
- - 0
-
- - 0
-
- - 0
-
- - .. row 3
-
- - 1
-
- - 4
-
- - 2
-
- - 1
-
- - .. row 4
-
- - 2
-
- - 8
-
- - 4
-
- - 2
-
- - .. row 5
-
- - 4
-
- - 16
-
- - 8
-
- - 4
-
-
-
-.. _DTV-ATSCMH-FIC-VER:
-
-DTV_ATSCMH_FIC_VER
-------------------
-
-Version number of the FIC (Fast Information Channel) signaling data.
-
-FIC is used for relaying information to allow rapid service acquisition
-by the receiver.
-
-Possible values: 0, 1, 2, 3, ..., 30, 31
-
-
-.. _DTV-ATSCMH-PARADE-ID:
-
-DTV_ATSCMH_PARADE_ID
---------------------
-
-Parade identification number
-
-A parade is a collection of up to eight MH groups, conveying one or two
-ensembles.
-
-Possible values: 0, 1, 2, 3, ..., 126, 127
-
-
-.. _DTV-ATSCMH-NOG:
-
-DTV_ATSCMH_NOG
---------------
-
-Number of MH groups per MH subframe for a designated parade.
-
-Possible values: 1, 2, 3, 4, 5, 6, 7, 8
-
-
-.. _DTV-ATSCMH-TNOG:
-
-DTV_ATSCMH_TNOG
----------------
-
-Total number of MH groups including all MH groups belonging to all MH
-parades in one MH subframe.
-
-Possible values: 0, 1, 2, 3, ..., 30, 31
-
-
-.. _DTV-ATSCMH-SGN:
-
-DTV_ATSCMH_SGN
---------------
-
-Start group number.
-
-Possible values: 0, 1, 2, 3, ..., 14, 15
-
-
-.. _DTV-ATSCMH-PRC:
-
-DTV_ATSCMH_PRC
---------------
-
-Parade repetition cycle.
-
-Possible values: 1, 2, 3, 4, 5, 6, 7, 8
-
-
-.. _DTV-ATSCMH-RS-FRAME-MODE:
-
-DTV_ATSCMH_RS_FRAME_MODE
-------------------------
-
-Reed Solomon (RS) frame mode.
-
-Possible values are:
-
-
-.. _atscmh-rs-frame-mode:
-
-.. flat-table:: enum atscmh_rs_frame_mode
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - ID
-
- - Description
-
- - .. row 2
-
- - .. _ATSCMH-RSFRAME-PRI-ONLY:
-
- ``ATSCMH_RSFRAME_PRI_ONLY``
-
- - Single Frame: There is only a primary RS Frame for all Group
- Regions.
-
- - .. row 3
-
- - .. _ATSCMH-RSFRAME-PRI-SEC:
-
- ``ATSCMH_RSFRAME_PRI_SEC``
-
- - Dual Frame: There are two separate RS Frames: Primary RS Frame for
- Group Region A and B and Secondary RS Frame for Group Region C and
- D.
-
-
-
-.. _DTV-ATSCMH-RS-FRAME-ENSEMBLE:
-
-DTV_ATSCMH_RS_FRAME_ENSEMBLE
-----------------------------
-
-Reed Solomon(RS) frame ensemble.
-
-Possible values are:
-
-
-.. _atscmh-rs-frame-ensemble:
-
-.. flat-table:: enum atscmh_rs_frame_ensemble
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - ID
-
- - Description
-
- - .. row 2
-
- - .. _ATSCMH-RSFRAME-ENS-PRI:
-
- ``ATSCMH_RSFRAME_ENS_PRI``
-
- - Primary Ensemble.
-
- - .. row 3
-
- - .. _ATSCMH-RSFRAME-ENS-SEC:
-
- ``AATSCMH_RSFRAME_PRI_SEC``
-
- - Secondary Ensemble.
-
- - .. row 4
-
- - .. _ATSCMH-RSFRAME-RES:
-
- ``AATSCMH_RSFRAME_RES``
-
- - Reserved. Shouldn't be used.
-
-
-
-.. _DTV-ATSCMH-RS-CODE-MODE-PRI:
-
-DTV_ATSCMH_RS_CODE_MODE_PRI
----------------------------
-
-Reed Solomon (RS) code mode (primary).
-
-Possible values are:
-
-
-.. _atscmh-rs-code-mode:
-
-.. flat-table:: enum atscmh_rs_code_mode
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - ID
-
- - Description
-
- - .. row 2
-
- - .. _ATSCMH-RSCODE-211-187:
-
- ``ATSCMH_RSCODE_211_187``
-
- - Reed Solomon code (211,187).
-
- - .. row 3
-
- - .. _ATSCMH-RSCODE-223-187:
-
- ``ATSCMH_RSCODE_223_187``
-
- - Reed Solomon code (223,187).
-
- - .. row 4
-
- - .. _ATSCMH-RSCODE-235-187:
-
- ``ATSCMH_RSCODE_235_187``
-
- - Reed Solomon code (235,187).
-
- - .. row 5
-
- - .. _ATSCMH-RSCODE-RES:
-
- ``ATSCMH_RSCODE_RES``
-
- - Reserved. Shouldn't be used.
-
-
-
-.. _DTV-ATSCMH-RS-CODE-MODE-SEC:
-
-DTV_ATSCMH_RS_CODE_MODE_SEC
----------------------------
-
-Reed Solomon (RS) code mode (secondary).
-
-Possible values are the same as documented on enum
-:ref:`atscmh_rs_code_mode <atscmh-rs-code-mode>`:
-
-
-.. _DTV-ATSCMH-SCCC-BLOCK-MODE:
-
-DTV_ATSCMH_SCCC_BLOCK_MODE
---------------------------
-
-Series Concatenated Convolutional Code Block Mode.
-
-Possible values are:
-
-
-.. _atscmh-sccc-block-mode:
-
-.. flat-table:: enum atscmh_scc_block_mode
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - ID
-
- - Description
-
- - .. row 2
-
- - .. _ATSCMH-SCCC-BLK-SEP:
-
- ``ATSCMH_SCCC_BLK_SEP``
-
- - Separate SCCC: the SCCC outer code mode shall be set independently
- for each Group Region (A, B, C, D)
-
- - .. row 3
-
- - .. _ATSCMH-SCCC-BLK-COMB:
-
- ``ATSCMH_SCCC_BLK_COMB``
-
- - Combined SCCC: all four Regions shall have the same SCCC outer
- code mode.
-
- - .. row 4
-
- - .. _ATSCMH-SCCC-BLK-RES:
-
- ``ATSCMH_SCCC_BLK_RES``
-
- - Reserved. Shouldn't be used.
-
-
-
-.. _DTV-ATSCMH-SCCC-CODE-MODE-A:
-
-DTV_ATSCMH_SCCC_CODE_MODE_A
----------------------------
-
-Series Concatenated Convolutional Code Rate.
-
-Possible values are:
-
-
-.. _atscmh-sccc-code-mode:
-
-.. flat-table:: enum atscmh_sccc_code_mode
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - ID
-
- - Description
-
- - .. row 2
-
- - .. _ATSCMH-SCCC-CODE-HLF:
-
- ``ATSCMH_SCCC_CODE_HLF``
-
- - The outer code rate of a SCCC Block is 1/2 rate.
-
- - .. row 3
-
- - .. _ATSCMH-SCCC-CODE-QTR:
-
- ``ATSCMH_SCCC_CODE_QTR``
-
- - The outer code rate of a SCCC Block is 1/4 rate.
-
- - .. row 4
-
- - .. _ATSCMH-SCCC-CODE-RES:
-
- ``ATSCMH_SCCC_CODE_RES``
-
- - to be documented.
-
-
-
-.. _DTV-ATSCMH-SCCC-CODE-MODE-B:
-
-DTV_ATSCMH_SCCC_CODE_MODE_B
----------------------------
-
-Series Concatenated Convolutional Code Rate.
-
-Possible values are the same as documented on enum
-:ref:`atscmh_sccc_code_mode <atscmh-sccc-code-mode>`.
-
-
-.. _DTV-ATSCMH-SCCC-CODE-MODE-C:
-
-DTV_ATSCMH_SCCC_CODE_MODE_C
----------------------------
-
-Series Concatenated Convolutional Code Rate.
-
-Possible values are the same as documented on enum
-:ref:`atscmh_sccc_code_mode <atscmh-sccc-code-mode>`.
-
-
-.. _DTV-ATSCMH-SCCC-CODE-MODE-D:
-
-DTV_ATSCMH_SCCC_CODE_MODE_D
----------------------------
-
-Series Concatenated Convolutional Code Rate.
-
-Possible values are the same as documented on enum
-:ref:`atscmh_sccc_code_mode <atscmh-sccc-code-mode>`.
-
-
-.. _DTV-API-VERSION:
-
-DTV_API_VERSION
-===============
-
-Returns the major/minor version of the DVB API
-
-
-.. _DTV-CODE-RATE-HP:
-
-DTV_CODE_RATE_HP
-================
-
-Used on terrestrial transmissions. The acceptable values are the ones
-described at :ref:`fe_transmit_mode_t <fe-transmit-mode-t>`.
-
-
-.. _DTV-CODE-RATE-LP:
-
-DTV_CODE_RATE_LP
-================
-
-Used on terrestrial transmissions. The acceptable values are the ones
-described at :ref:`fe_transmit_mode_t <fe-transmit-mode-t>`.
-
-
-.. _DTV-GUARD-INTERVAL:
-
-DTV_GUARD_INTERVAL
-==================
-
-Possible values are:
-
-
-.. _fe-guard-interval-t:
-
-Modulation guard interval
--------------------------
-
-
-.. _fe-guard-interval:
-
-.. flat-table:: enum fe_guard_interval
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - ID
-
- - Description
-
- - .. row 2
-
- - .. _GUARD-INTERVAL-AUTO:
-
- ``GUARD_INTERVAL_AUTO``
-
- - Autodetect the guard interval
-
- - .. row 3
-
- - .. _GUARD-INTERVAL-1-128:
-
- ``GUARD_INTERVAL_1_128``
-
- - Guard interval 1/128
-
- - .. row 4
-
- - .. _GUARD-INTERVAL-1-32:
-
- ``GUARD_INTERVAL_1_32``
-
- - Guard interval 1/32
-
- - .. row 5
-
- - .. _GUARD-INTERVAL-1-16:
-
- ``GUARD_INTERVAL_1_16``
-
- - Guard interval 1/16
-
- - .. row 6
-
- - .. _GUARD-INTERVAL-1-8:
-
- ``GUARD_INTERVAL_1_8``
-
- - Guard interval 1/8
-
- - .. row 7
-
- - .. _GUARD-INTERVAL-1-4:
-
- ``GUARD_INTERVAL_1_4``
-
- - Guard interval 1/4
-
- - .. row 8
-
- - .. _GUARD-INTERVAL-19-128:
-
- ``GUARD_INTERVAL_19_128``
-
- - Guard interval 19/128
-
- - .. row 9
-
- - .. _GUARD-INTERVAL-19-256:
-
- ``GUARD_INTERVAL_19_256``
-
- - Guard interval 19/256
-
- - .. row 10
-
- - .. _GUARD-INTERVAL-PN420:
-
- ``GUARD_INTERVAL_PN420``
-
- - PN length 420 (1/4)
-
- - .. row 11
-
- - .. _GUARD-INTERVAL-PN595:
-
- ``GUARD_INTERVAL_PN595``
-
- - PN length 595 (1/6)
-
- - .. row 12
-
- - .. _GUARD-INTERVAL-PN945:
-
- ``GUARD_INTERVAL_PN945``
-
- - PN length 945 (1/9)
-
-
-Notes:
-
-1) If ``DTV_GUARD_INTERVAL`` is set the ``GUARD_INTERVAL_AUTO`` the
-hardware will try to find the correct guard interval (if capable) and
-will use TMCC to fill in the missing parameters.
-
-2) Intervals 1/128, 19/128 and 19/256 are used only for DVB-T2 at
-present
-
-3) DTMB specifies PN420, PN595 and PN945.
-
-
-.. _DTV-TRANSMISSION-MODE:
-
-DTV_TRANSMISSION_MODE
-=====================
-
-Specifies the number of carriers used by the standard. This is used only
-on OFTM-based standards, e. g. DVB-T/T2, ISDB-T, DTMB
-
-
-.. _fe-transmit-mode-t:
-
-enum fe_transmit_mode: Number of carriers per channel
------------------------------------------------------
-
-
-.. _fe-transmit-mode:
-
-.. flat-table:: enum fe_transmit_mode
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - ID
-
- - Description
-
- - .. row 2
-
- - .. _TRANSMISSION-MODE-AUTO:
-
- ``TRANSMISSION_MODE_AUTO``
-
- - Autodetect transmission mode. The hardware will try to find the
- correct FFT-size (if capable) to fill in the missing parameters.
-
- - .. row 3
-
- - .. _TRANSMISSION-MODE-1K:
-
- ``TRANSMISSION_MODE_1K``
-
- - Transmission mode 1K
-
- - .. row 4
-
- - .. _TRANSMISSION-MODE-2K:
-
- ``TRANSMISSION_MODE_2K``
-
- - Transmission mode 2K
-
- - .. row 5
-
- - .. _TRANSMISSION-MODE-8K:
-
- ``TRANSMISSION_MODE_8K``
-
- - Transmission mode 8K
-
- - .. row 6
-
- - .. _TRANSMISSION-MODE-4K:
-
- ``TRANSMISSION_MODE_4K``
-
- - Transmission mode 4K
-
- - .. row 7
-
- - .. _TRANSMISSION-MODE-16K:
-
- ``TRANSMISSION_MODE_16K``
-
- - Transmission mode 16K
-
- - .. row 8
-
- - .. _TRANSMISSION-MODE-32K:
-
- ``TRANSMISSION_MODE_32K``
-
- - Transmission mode 32K
-
- - .. row 9
-
- - .. _TRANSMISSION-MODE-C1:
-
- ``TRANSMISSION_MODE_C1``
-
- - Single Carrier (C=1) transmission mode (DTMB)
-
- - .. row 10
-
- - .. _TRANSMISSION-MODE-C3780:
-
- ``TRANSMISSION_MODE_C3780``
-
- - Multi Carrier (C=3780) transmission mode (DTMB)
-
-
-Notes:
-
-1) ISDB-T supports three carrier/symbol-size: 8K, 4K, 2K. It is called
-'mode' in the standard: Mode 1 is 2K, mode 2 is 4K, mode 3 is 8K
-
-2) If ``DTV_TRANSMISSION_MODE`` is set the ``TRANSMISSION_MODE_AUTO``
-the hardware will try to find the correct FFT-size (if capable) and will
-use TMCC to fill in the missing parameters.
-
-3) DVB-T specifies 2K and 8K as valid sizes.
-
-4) DVB-T2 specifies 1K, 2K, 4K, 8K, 16K and 32K.
-
-5) DTMB specifies C1 and C3780.
-
-
-.. _DTV-HIERARCHY:
-
-DTV_HIERARCHY
-=============
-
-Frontend hierarchy
-
-
-.. _fe-hierarchy-t:
-
-Frontend hierarchy
-------------------
-
-
-.. _fe-hierarchy:
-
-.. flat-table:: enum fe_hierarchy
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - ID
-
- - Description
-
- - .. row 2
-
- - .. _HIERARCHY-NONE:
-
- ``HIERARCHY_NONE``
-
- - No hierarchy
-
- - .. row 3
-
- - .. _HIERARCHY-AUTO:
-
- ``HIERARCHY_AUTO``
-
- - Autodetect hierarchy (if supported)
-
- - .. row 4
-
- - .. _HIERARCHY-1:
-
- ``HIERARCHY_1``
-
- - Hierarchy 1
-
- - .. row 5
-
- - .. _HIERARCHY-2:
-
- ``HIERARCHY_2``
-
- - Hierarchy 2
-
- - .. row 6
-
- - .. _HIERARCHY-4:
-
- ``HIERARCHY_4``
-
- - Hierarchy 4
-
-
-
-.. _DTV-STREAM-ID:
-
-DTV_STREAM_ID
-=============
-
-DVB-S2, DVB-T2 and ISDB-S support the transmission of several streams on
-a single transport stream. This property enables the DVB driver to
-handle substream filtering, when supported by the hardware. By default,
-substream filtering is disabled.
-
-For DVB-S2 and DVB-T2, the valid substream id range is from 0 to 255.
-
-For ISDB, the valid substream id range is from 1 to 65535.
-
-To disable it, you should use the special macro NO_STREAM_ID_FILTER.
-
-Note: any value outside the id range also disables filtering.
-
-
-.. _DTV-DVBT2-PLP-ID-LEGACY:
-
-DTV_DVBT2_PLP_ID_LEGACY
-=======================
-
-Obsolete, replaced with DTV_STREAM_ID.
-
-
-.. _DTV-ENUM-DELSYS:
-
-DTV_ENUM_DELSYS
-===============
-
-A Multi standard frontend needs to advertise the delivery systems
-provided. Applications need to enumerate the provided delivery systems,
-before using any other operation with the frontend. Prior to it's
-introduction, FE_GET_INFO was used to determine a frontend type. A
-frontend which provides more than a single delivery system,
-FE_GET_INFO doesn't help much. Applications which intends to use a
-multistandard frontend must enumerate the delivery systems associated
-with it, rather than trying to use FE_GET_INFO. In the case of a
-legacy frontend, the result is just the same as with FE_GET_INFO, but
-in a more structured format
-
-
-.. _DTV-INTERLEAVING:
-
-DTV_INTERLEAVING
-================
-
-Time interleaving to be used. Currently, used only on DTMB.
-
-
-.. _fe-interleaving:
-
-.. flat-table:: enum fe_interleaving
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - ID
-
- - Description
-
- - .. row 2
-
- - .. _INTERLEAVING-NONE:
-
- ``INTERLEAVING_NONE``
-
- - No interleaving.
-
- - .. row 3
-
- - .. _INTERLEAVING-AUTO:
-
- ``INTERLEAVING_AUTO``
-
- - Auto-detect interleaving.
-
- - .. row 4
-
- - .. _INTERLEAVING-240:
-
- ``INTERLEAVING_240``
-
- - Interleaving of 240 symbols.
-
- - .. row 5
-
- - .. _INTERLEAVING-720:
-
- ``INTERLEAVING_720``
-
- - Interleaving of 720 symbols.
-
-
-
-.. _DTV-LNA:
-
-DTV_LNA
-=======
-
-Low-noise amplifier.
-
-Hardware might offer controllable LNA which can be set manually using
-that parameter. Usually LNA could be found only from terrestrial devices
-if at all.
-
-Possible values: 0, 1, LNA_AUTO
-
-0, LNA off
-
-1, LNA on
-
-use the special macro LNA_AUTO to set LNA auto
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _frontend-property-cable-systems:
-
-*****************************************
-Properties used on cable delivery systems
-*****************************************
-
-
-.. _dvbc-params:
-
-DVB-C delivery system
-=====================
-
-The DVB-C Annex-A is the widely used cable standard. Transmission uses
-QAM modulation.
-
-The DVB-C Annex-C is optimized for 6MHz, and is used in Japan. It
-supports a subset of the Annex A modulation types, and a roll-off of
-0.13, instead of 0.15
-
-The following parameters are valid for DVB-C Annex A/C:
-
-- :ref:`DTV_API_VERSION <DTV-API-VERSION>`
-
-- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`
-
-- :ref:`DTV_TUNE <DTV-TUNE>`
-
-- :ref:`DTV_CLEAR <DTV-CLEAR>`
-
-- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`
-
-- :ref:`DTV_MODULATION <DTV-MODULATION>`
-
-- :ref:`DTV_INVERSION <DTV-INVERSION>`
-
-- :ref:`DTV_SYMBOL_RATE <DTV-SYMBOL-RATE>`
-
-- :ref:`DTV_INNER_FEC <DTV-INNER-FEC>`
-
-- :ref:`DTV_LNA <DTV-LNA>`
-
-In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
-are also valid.
-
-
-.. _dvbc-annex-b-params:
-
-DVB-C Annex B delivery system
-=============================
-
-The DVB-C Annex-B is only used on a few Countries like the United
-States.
-
-The following parameters are valid for DVB-C Annex B:
-
-- :ref:`DTV_API_VERSION <DTV-API-VERSION>`
-
-- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`
-
-- :ref:`DTV_TUNE <DTV-TUNE>`
-
-- :ref:`DTV_CLEAR <DTV-CLEAR>`
-
-- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`
-
-- :ref:`DTV_MODULATION <DTV-MODULATION>`
-
-- :ref:`DTV_INVERSION <DTV-INVERSION>`
-
-- :ref:`DTV_LNA <DTV-LNA>`
-
-In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
-are also valid.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _frontend-property-satellite-systems:
-
-*********************************************
-Properties used on satellite delivery systems
-*********************************************
-
-
-.. _dvbs-params:
-
-DVB-S delivery system
-=====================
-
-The following parameters are valid for DVB-S:
-
-- :ref:`DTV_API_VERSION <DTV-API-VERSION>`
-
-- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`
-
-- :ref:`DTV_TUNE <DTV-TUNE>`
-
-- :ref:`DTV_CLEAR <DTV-CLEAR>`
-
-- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`
-
-- :ref:`DTV_INVERSION <DTV-INVERSION>`
-
-- :ref:`DTV_SYMBOL_RATE <DTV-SYMBOL-RATE>`
-
-- :ref:`DTV_INNER_FEC <DTV-INNER-FEC>`
-
-- :ref:`DTV_VOLTAGE <DTV-VOLTAGE>`
-
-- :ref:`DTV_TONE <DTV-TONE>`
-
-In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
-are also valid.
-
-Future implementations might add those two missing parameters:
-
-- :ref:`DTV_DISEQC_MASTER <DTV-DISEQC-MASTER>`
-
-- :ref:`DTV_DISEQC_SLAVE_REPLY <DTV-DISEQC-SLAVE-REPLY>`
-
-
-.. _dvbs2-params:
-
-DVB-S2 delivery system
-======================
-
-In addition to all parameters valid for DVB-S, DVB-S2 supports the
-following parameters:
-
-- :ref:`DTV_MODULATION <DTV-MODULATION>`
-
-- :ref:`DTV_PILOT <DTV-PILOT>`
-
-- :ref:`DTV_ROLLOFF <DTV-ROLLOFF>`
-
-- :ref:`DTV_STREAM_ID <DTV-STREAM-ID>`
-
-In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
-are also valid.
-
-
-.. _turbo-params:
-
-Turbo code delivery system
-==========================
-
-In addition to all parameters valid for DVB-S, turbo code supports the
-following parameters:
-
-- :ref:`DTV_MODULATION <DTV-MODULATION>`
-
-
-.. _isdbs-params:
-
-ISDB-S delivery system
-======================
-
-The following parameters are valid for ISDB-S:
-
-- :ref:`DTV_API_VERSION <DTV-API-VERSION>`
-
-- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`
-
-- :ref:`DTV_TUNE <DTV-TUNE>`
-
-- :ref:`DTV_CLEAR <DTV-CLEAR>`
-
-- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`
-
-- :ref:`DTV_INVERSION <DTV-INVERSION>`
-
-- :ref:`DTV_SYMBOL_RATE <DTV-SYMBOL-RATE>`
-
-- :ref:`DTV_INNER_FEC <DTV-INNER-FEC>`
-
-- :ref:`DTV_VOLTAGE <DTV-VOLTAGE>`
-
-- :ref:`DTV_STREAM_ID <DTV-STREAM-ID>`
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _frontend-property-terrestrial-systems:
-
-***********************************************
-Properties used on terrestrial delivery systems
-***********************************************
-
-
-.. _dvbt-params:
-
-DVB-T delivery system
-=====================
-
-The following parameters are valid for DVB-T:
-
-- :ref:`DTV_API_VERSION <DTV-API-VERSION>`
-
-- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`
-
-- :ref:`DTV_TUNE <DTV-TUNE>`
-
-- :ref:`DTV_CLEAR <DTV-CLEAR>`
-
-- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`
-
-- :ref:`DTV_MODULATION <DTV-MODULATION>`
-
-- :ref:`DTV_BANDWIDTH_HZ <DTV-BANDWIDTH-HZ>`
-
-- :ref:`DTV_INVERSION <DTV-INVERSION>`
-
-- :ref:`DTV_CODE_RATE_HP <DTV-CODE-RATE-HP>`
-
-- :ref:`DTV_CODE_RATE_LP <DTV-CODE-RATE-LP>`
-
-- :ref:`DTV_GUARD_INTERVAL <DTV-GUARD-INTERVAL>`
-
-- :ref:`DTV_TRANSMISSION_MODE <DTV-TRANSMISSION-MODE>`
-
-- :ref:`DTV_HIERARCHY <DTV-HIERARCHY>`
-
-- :ref:`DTV_LNA <DTV-LNA>`
-
-In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
-are also valid.
-
-
-.. _dvbt2-params:
-
-DVB-T2 delivery system
-======================
-
-DVB-T2 support is currently in the early stages of development, so
-expect that this section maygrow and become more detailed with time.
-
-The following parameters are valid for DVB-T2:
-
-- :ref:`DTV_API_VERSION <DTV-API-VERSION>`
-
-- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`
-
-- :ref:`DTV_TUNE <DTV-TUNE>`
-
-- :ref:`DTV_CLEAR <DTV-CLEAR>`
-
-- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`
-
-- :ref:`DTV_MODULATION <DTV-MODULATION>`
-
-- :ref:`DTV_BANDWIDTH_HZ <DTV-BANDWIDTH-HZ>`
-
-- :ref:`DTV_INVERSION <DTV-INVERSION>`
-
-- :ref:`DTV_CODE_RATE_HP <DTV-CODE-RATE-HP>`
-
-- :ref:`DTV_CODE_RATE_LP <DTV-CODE-RATE-LP>`
-
-- :ref:`DTV_GUARD_INTERVAL <DTV-GUARD-INTERVAL>`
-
-- :ref:`DTV_TRANSMISSION_MODE <DTV-TRANSMISSION-MODE>`
-
-- :ref:`DTV_HIERARCHY <DTV-HIERARCHY>`
-
-- :ref:`DTV_STREAM_ID <DTV-STREAM-ID>`
-
-- :ref:`DTV_LNA <DTV-LNA>`
-
-In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
-are also valid.
-
-
-.. _isdbt:
-
-ISDB-T delivery system
-======================
-
-This ISDB-T/ISDB-Tsb API extension should reflect all information needed
-to tune any ISDB-T/ISDB-Tsb hardware. Of course it is possible that some
-very sophisticated devices won't need certain parameters to tune.
-
-The information given here should help application writers to know how
-to handle ISDB-T and ISDB-Tsb hardware using the Linux DVB-API.
-
-The details given here about ISDB-T and ISDB-Tsb are just enough to
-basically show the dependencies between the needed parameter values, but
-surely some information is left out. For more detailed information see
-the following documents:
-
-ARIB STD-B31 - "Transmission System for Digital Terrestrial Television
-Broadcasting" and
-
-ARIB TR-B14 - "Operational Guidelines for Digital Terrestrial Television
-Broadcasting".
-
-In order to understand the ISDB specific parameters, one has to have
-some knowledge the channel structure in ISDB-T and ISDB-Tsb. I.e. it has
-to be known to the reader that an ISDB-T channel consists of 13
-segments, that it can have up to 3 layer sharing those segments, and
-things like that.
-
-The following parameters are valid for ISDB-T:
-
-- :ref:`DTV_API_VERSION <DTV-API-VERSION>`
-
-- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`
-
-- :ref:`DTV_TUNE <DTV-TUNE>`
-
-- :ref:`DTV_CLEAR <DTV-CLEAR>`
-
-- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`
-
-- :ref:`DTV_BANDWIDTH_HZ <DTV-BANDWIDTH-HZ>`
-
-- :ref:`DTV_INVERSION <DTV-INVERSION>`
-
-- :ref:`DTV_GUARD_INTERVAL <DTV-GUARD-INTERVAL>`
-
-- :ref:`DTV_TRANSMISSION_MODE <DTV-TRANSMISSION-MODE>`
-
-- :ref:`DTV_ISDBT_LAYER_ENABLED <DTV-ISDBT-LAYER-ENABLED>`
-
-- :ref:`DTV_ISDBT_PARTIAL_RECEPTION <DTV-ISDBT-PARTIAL-RECEPTION>`
-
-- :ref:`DTV_ISDBT_SOUND_BROADCASTING <DTV-ISDBT-SOUND-BROADCASTING>`
-
-- :ref:`DTV_ISDBT_SB_SUBCHANNEL_ID <DTV-ISDBT-SB-SUBCHANNEL-ID>`
-
-- :ref:`DTV_ISDBT_SB_SEGMENT_IDX <DTV-ISDBT-SB-SEGMENT-IDX>`
-
-- :ref:`DTV_ISDBT_SB_SEGMENT_COUNT <DTV-ISDBT-SB-SEGMENT-COUNT>`
-
-- :ref:`DTV_ISDBT_LAYERA_FEC <DTV-ISDBT-LAYER-FEC>`
-
-- :ref:`DTV_ISDBT_LAYERA_MODULATION <DTV-ISDBT-LAYER-MODULATION>`
-
-- :ref:`DTV_ISDBT_LAYERA_SEGMENT_COUNT <DTV-ISDBT-LAYER-SEGMENT-COUNT>`
-
-- :ref:`DTV_ISDBT_LAYERA_TIME_INTERLEAVING <DTV-ISDBT-LAYER-TIME-INTERLEAVING>`
-
-- :ref:`DTV_ISDBT_LAYERB_FEC <DTV-ISDBT-LAYER-FEC>`
-
-- :ref:`DTV_ISDBT_LAYERB_MODULATION <DTV-ISDBT-LAYER-MODULATION>`
-
-- :ref:`DTV_ISDBT_LAYERB_SEGMENT_COUNT <DTV-ISDBT-LAYER-SEGMENT-COUNT>`
-
-- :ref:`DTV_ISDBT_LAYERB_TIME_INTERLEAVING <DTV-ISDBT-LAYER-TIME-INTERLEAVING>`
-
-- :ref:`DTV_ISDBT_LAYERC_FEC <DTV-ISDBT-LAYER-FEC>`
-
-- :ref:`DTV_ISDBT_LAYERC_MODULATION <DTV-ISDBT-LAYER-MODULATION>`
-
-- :ref:`DTV_ISDBT_LAYERC_SEGMENT_COUNT <DTV-ISDBT-LAYER-SEGMENT-COUNT>`
-
-- :ref:`DTV_ISDBT_LAYERC_TIME_INTERLEAVING <DTV-ISDBT-LAYER-TIME-INTERLEAVING>`
-
-In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
-are also valid.
-
-
-.. _atsc-params:
-
-ATSC delivery system
-====================
-
-The following parameters are valid for ATSC:
-
-- :ref:`DTV_API_VERSION <DTV-API-VERSION>`
-
-- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`
-
-- :ref:`DTV_TUNE <DTV-TUNE>`
-
-- :ref:`DTV_CLEAR <DTV-CLEAR>`
-
-- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`
-
-- :ref:`DTV_MODULATION <DTV-MODULATION>`
-
-- :ref:`DTV_BANDWIDTH_HZ <DTV-BANDWIDTH-HZ>`
-
-In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
-are also valid.
-
-
-.. _atscmh-params:
-
-ATSC-MH delivery system
-=======================
-
-The following parameters are valid for ATSC-MH:
-
-- :ref:`DTV_API_VERSION <DTV-API-VERSION>`
-
-- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`
-
-- :ref:`DTV_TUNE <DTV-TUNE>`
-
-- :ref:`DTV_CLEAR <DTV-CLEAR>`
-
-- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`
-
-- :ref:`DTV_BANDWIDTH_HZ <DTV-BANDWIDTH-HZ>`
-
-- :ref:`DTV_ATSCMH_FIC_VER <DTV-ATSCMH-FIC-VER>`
-
-- :ref:`DTV_ATSCMH_PARADE_ID <DTV-ATSCMH-PARADE-ID>`
-
-- :ref:`DTV_ATSCMH_NOG <DTV-ATSCMH-NOG>`
-
-- :ref:`DTV_ATSCMH_TNOG <DTV-ATSCMH-TNOG>`
-
-- :ref:`DTV_ATSCMH_SGN <DTV-ATSCMH-SGN>`
-
-- :ref:`DTV_ATSCMH_PRC <DTV-ATSCMH-PRC>`
-
-- :ref:`DTV_ATSCMH_RS_FRAME_MODE <DTV-ATSCMH-RS-FRAME-MODE>`
-
-- :ref:`DTV_ATSCMH_RS_FRAME_ENSEMBLE <DTV-ATSCMH-RS-FRAME-ENSEMBLE>`
-
-- :ref:`DTV_ATSCMH_RS_CODE_MODE_PRI <DTV-ATSCMH-RS-CODE-MODE-PRI>`
-
-- :ref:`DTV_ATSCMH_RS_CODE_MODE_SEC <DTV-ATSCMH-RS-CODE-MODE-SEC>`
-
-- :ref:`DTV_ATSCMH_SCCC_BLOCK_MODE <DTV-ATSCMH-SCCC-BLOCK-MODE>`
-
-- :ref:`DTV_ATSCMH_SCCC_CODE_MODE_A <DTV-ATSCMH-SCCC-CODE-MODE-A>`
-
-- :ref:`DTV_ATSCMH_SCCC_CODE_MODE_B <DTV-ATSCMH-SCCC-CODE-MODE-B>`
-
-- :ref:`DTV_ATSCMH_SCCC_CODE_MODE_C <DTV-ATSCMH-SCCC-CODE-MODE-C>`
-
-- :ref:`DTV_ATSCMH_SCCC_CODE_MODE_D <DTV-ATSCMH-SCCC-CODE-MODE-D>`
-
-In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
-are also valid.
-
-
-.. _dtmb-params:
-
-DTMB delivery system
-====================
-
-The following parameters are valid for DTMB:
-
-- :ref:`DTV_API_VERSION <DTV-API-VERSION>`
-
-- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`
-
-- :ref:`DTV_TUNE <DTV-TUNE>`
-
-- :ref:`DTV_CLEAR <DTV-CLEAR>`
-
-- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`
-
-- :ref:`DTV_MODULATION <DTV-MODULATION>`
-
-- :ref:`DTV_BANDWIDTH_HZ <DTV-BANDWIDTH-HZ>`
-
-- :ref:`DTV_INVERSION <DTV-INVERSION>`
-
-- :ref:`DTV_INNER_FEC <DTV-INNER-FEC>`
-
-- :ref:`DTV_GUARD_INTERVAL <DTV-GUARD-INTERVAL>`
-
-- :ref:`DTV_TRANSMISSION_MODE <DTV-TRANSMISSION-MODE>`
-
-- :ref:`DTV_INTERLEAVING <DTV-INTERLEAVING>`
-
-- :ref:`DTV_LNA <DTV-LNA>`
-
-In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
-are also valid.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _frontend-stat-properties:
-
-******************************
-Frontend statistics indicators
-******************************
-
-The values are returned via ``dtv_property.stat``. If the property is
-supported, ``dtv_property.stat.len`` is bigger than zero.
-
-For most delivery systems, ``dtv_property.stat.len`` will be 1 if the
-stats is supported, and the properties will return a single value for
-each parameter.
-
-It should be noted, however, that new OFDM delivery systems like ISDB
-can use different modulation types for each group of carriers. On such
-standards, up to 3 groups of statistics can be provided, and
-``dtv_property.stat.len`` is updated to reflect the "global" metrics,
-plus one metric per each carrier group (called "layer" on ISDB).
-
-So, in order to be consistent with other delivery systems, the first
-value at :ref:`dtv_property.stat.dtv_stats <dtv-stats>` array refers
-to the global metric. The other elements of the array represent each
-layer, starting from layer A(index 1), layer B (index 2) and so on.
-
-The number of filled elements are stored at ``dtv_property.stat.len``.
-
-Each element of the ``dtv_property.stat.dtv_stats`` array consists on
-two elements:
-
-- ``svalue`` or ``uvalue``, where ``svalue`` is for signed values of
- the measure (dB measures) and ``uvalue`` is for unsigned values
- (counters, relative scale)
-
-- ``scale`` - Scale for the value. It can be:
-
- - ``FE_SCALE_NOT_AVAILABLE`` - The parameter is supported by the
- frontend, but it was not possible to collect it (could be a
- transitory or permanent condition)
-
- - ``FE_SCALE_DECIBEL`` - parameter is a signed value, measured in
- 1/1000 dB
-
- - ``FE_SCALE_RELATIVE`` - parameter is a unsigned value, where 0
- means 0% and 65535 means 100%.
-
- - ``FE_SCALE_COUNTER`` - parameter is a unsigned value that counts
- the occurrence of an event, like bit error, block error, or lapsed
- time.
-
-
-.. _DTV-STAT-SIGNAL-STRENGTH:
-
-DTV_STAT_SIGNAL_STRENGTH
-========================
-
-Indicates the signal strength level at the analog part of the tuner or
-of the demod.
-
-Possible scales for this metric are:
-
-- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
- measurement was not complete yet.
-
-- ``FE_SCALE_DECIBEL`` - signal strength is in 0.001 dBm units, power
- measured in miliwatts. This value is generally negative.
-
-- ``FE_SCALE_RELATIVE`` - The frontend provides a 0% to 100%
- measurement for power (actually, 0 to 65535).
-
-
-.. _DTV-STAT-CNR:
-
-DTV_STAT_CNR
-============
-
-Indicates the Signal to Noise ratio for the main carrier.
-
-Possible scales for this metric are:
-
-- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
- measurement was not complete yet.
-
-- ``FE_SCALE_DECIBEL`` - Signal/Noise ratio is in 0.001 dB units.
-
-- ``FE_SCALE_RELATIVE`` - The frontend provides a 0% to 100%
- measurement for Signal/Noise (actually, 0 to 65535).
-
-
-.. _DTV-STAT-PRE-ERROR-BIT-COUNT:
-
-DTV_STAT_PRE_ERROR_BIT_COUNT
-============================
-
-Measures the number of bit errors before the forward error correction
-(FEC) on the inner coding block (before Viterbi, LDPC or other inner
-code).
-
-This measure is taken during the same interval as
-``DTV_STAT_PRE_TOTAL_BIT_COUNT``.
-
-In order to get the BER (Bit Error Rate) measurement, it should be
-divided by
-:ref:`DTV_STAT_PRE_TOTAL_BIT_COUNT <DTV-STAT-PRE-TOTAL-BIT-COUNT>`.
-
-This measurement is monotonically increased, as the frontend gets more
-bit count measurements. The frontend may reset it when a
-channel/transponder is tuned.
-
-Possible scales for this metric are:
-
-- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
- measurement was not complete yet.
-
-- ``FE_SCALE_COUNTER`` - Number of error bits counted before the inner
- coding.
-
-
-.. _DTV-STAT-PRE-TOTAL-BIT-COUNT:
-
-DTV_STAT_PRE_TOTAL_BIT_COUNT
-============================
-
-Measures the amount of bits received before the inner code block, during
-the same period as
-:ref:`DTV_STAT_PRE_ERROR_BIT_COUNT <DTV-STAT-PRE-ERROR-BIT-COUNT>`
-measurement was taken.
-
-It should be noted that this measurement can be smaller than the total
-amount of bits on the transport stream, as the frontend may need to
-manually restart the measurement, losing some data between each
-measurement interval.
-
-This measurement is monotonically increased, as the frontend gets more
-bit count measurements. The frontend may reset it when a
-channel/transponder is tuned.
-
-Possible scales for this metric are:
-
-- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
- measurement was not complete yet.
-
-- ``FE_SCALE_COUNTER`` - Number of bits counted while measuring
- :ref:`DTV_STAT_PRE_ERROR_BIT_COUNT <DTV-STAT-PRE-ERROR-BIT-COUNT>`.
-
-
-.. _DTV-STAT-POST-ERROR-BIT-COUNT:
-
-DTV_STAT_POST_ERROR_BIT_COUNT
-=============================
-
-Measures the number of bit errors after the forward error correction
-(FEC) done by inner code block (after Viterbi, LDPC or other inner
-code).
-
-This measure is taken during the same interval as
-``DTV_STAT_POST_TOTAL_BIT_COUNT``.
-
-In order to get the BER (Bit Error Rate) measurement, it should be
-divided by
-:ref:`DTV_STAT_POST_TOTAL_BIT_COUNT <DTV-STAT-POST-TOTAL-BIT-COUNT>`.
-
-This measurement is monotonically increased, as the frontend gets more
-bit count measurements. The frontend may reset it when a
-channel/transponder is tuned.
-
-Possible scales for this metric are:
-
-- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
- measurement was not complete yet.
-
-- ``FE_SCALE_COUNTER`` - Number of error bits counted after the inner
- coding.
-
-
-.. _DTV-STAT-POST-TOTAL-BIT-COUNT:
-
-DTV_STAT_POST_TOTAL_BIT_COUNT
-=============================
-
-Measures the amount of bits received after the inner coding, during the
-same period as
-:ref:`DTV_STAT_POST_ERROR_BIT_COUNT <DTV-STAT-POST-ERROR-BIT-COUNT>`
-measurement was taken.
-
-It should be noted that this measurement can be smaller than the total
-amount of bits on the transport stream, as the frontend may need to
-manually restart the measurement, losing some data between each
-measurement interval.
-
-This measurement is monotonically increased, as the frontend gets more
-bit count measurements. The frontend may reset it when a
-channel/transponder is tuned.
-
-Possible scales for this metric are:
-
-- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
- measurement was not complete yet.
-
-- ``FE_SCALE_COUNTER`` - Number of bits counted while measuring
- :ref:`DTV_STAT_POST_ERROR_BIT_COUNT <DTV-STAT-POST-ERROR-BIT-COUNT>`.
-
-
-.. _DTV-STAT-ERROR-BLOCK-COUNT:
-
-DTV_STAT_ERROR_BLOCK_COUNT
-==========================
-
-Measures the number of block errors after the outer forward error
-correction coding (after Reed-Solomon or other outer code).
-
-This measurement is monotonically increased, as the frontend gets more
-bit count measurements. The frontend may reset it when a
-channel/transponder is tuned.
-
-Possible scales for this metric are:
-
-- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
- measurement was not complete yet.
-
-- ``FE_SCALE_COUNTER`` - Number of error blocks counted after the outer
- coding.
-
-
-.. _DTV-STAT-TOTAL-BLOCK-COUNT:
-
-DTV-STAT_TOTAL_BLOCK_COUNT
-==========================
-
-Measures the total number of blocks received during the same period as
-:ref:`DTV_STAT_ERROR_BLOCK_COUNT <DTV-STAT-ERROR-BLOCK-COUNT>`
-measurement was taken.
-
-It can be used to calculate the PER indicator, by dividing
-:ref:`DTV_STAT_ERROR_BLOCK_COUNT <DTV-STAT-ERROR-BLOCK-COUNT>` by
-:ref:`DTV-STAT-TOTAL-BLOCK-COUNT`.
-
-Possible scales for this metric are:
-
-- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
- measurement was not complete yet.
-
-- ``FE_SCALE_COUNTER`` - Number of blocks counted while measuring
- :ref:`DTV_STAT_ERROR_BLOCK_COUNT <DTV-STAT-ERROR-BLOCK-COUNT>`.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _dvb_frontend:
-
-################
-DVB Frontend API
-################
-The DVB frontend API was designed to support three types of delivery
-systems:
-
-- Terrestrial systems: DVB-T, DVB-T2, ATSC, ATSC M/H, ISDB-T, DVB-H,
- DTMB, CMMB
-
-- Cable systems: DVB-C Annex A/C, ClearQAM (DVB-C Annex B), ISDB-C
-
-- Satellite systems: DVB-S, DVB-S2, DVB Turbo, ISDB-S, DSS
-
-The DVB frontend controls several sub-devices including:
-
-- Tuner
-
-- Digital TV demodulator
-
-- Low noise amplifier (LNA)
-
-- Satellite Equipment Control (SEC) hardware (only for Satellite).
-
-The frontend can be accessed through ``/dev/dvb/adapter?/frontend?``.
-Data types and ioctl definitions can be accessed by including
-``linux/dvb/frontend.h`` in your application.
-
-NOTE: Transmission via the internet (DVB-IP) is not yet handled by this
-API but a future extension is possible.
-
-On Satellite systems, the API support for the Satellite Equipment
-Control (SEC) allows to power control and to send/receive signals to
-control the antenna subsystem, selecting the polarization and choosing
-the Intermediate Frequency IF) of the Low Noise Block Converter Feed
-Horn (LNBf). It supports the DiSEqC and V-SEC protocols. The DiSEqC
-(digital SEC) specification is available at
-`Eutelsat <http://www.eutelsat.com/satellites/4_5_5.html>`__.
-
-
-.. toctree::
- :maxdepth: 1
-
- query-dvb-frontend-info
- dvb-fe-read-status
- dvbproperty
- frontend_fcalls
- frontend_legacy_dvbv3_api
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _frontend_f_close:
-
-********************
-DVB frontend close()
-********************
-
-Name
-====
-
-fe-close - Close a frontend device
-
-
-Synopsis
-========
-
-.. code-block:: c
-
- #include <unistd.h>
-
-
-.. cpp:function:: int close( int fd )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-
-Description
-===========
-
-This system call closes a previously opened front-end device. After
-closing a front-end device, its corresponding hardware might be powered
-down automatically.
-
-
-Return Value
-============
-
-The function returns 0 on success, -1 on failure and the ``errno`` is
-set appropriately. Possible error codes:
-
-EBADF
- ``fd`` is not a valid open file descriptor.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _frontend_f_open:
-
-*******************
-DVB frontend open()
-*******************
-
-Name
-====
-
-fe-open - Open a frontend device
-
-
-Synopsis
-========
-
-.. code-block:: c
-
- #include <fcntl.h>
-
-
-.. cpp:function:: int open( const char *device_name, int flags )
-
-
-Arguments
-=========
-
-``device_name``
- Device to be opened.
-
-``flags``
- Open flags. Access can either be ``O_RDWR`` or ``O_RDONLY``.
-
- Multiple opens are allowed with ``O_RDONLY``. In this mode, only
- query and read ioctls are allowed.
-
- Only one open is allowed in ``O_RDWR``. In this mode, all ioctls are
- allowed.
-
- When the ``O_NONBLOCK`` flag is given, the system calls may return
- ``EAGAIN`` error code when no data is available or when the device
- driver is temporarily busy.
-
- Other flags have no effect.
-
-
-Description
-===========
-
-This system call opens a named frontend device
-(``/dev/dvb/adapter?/frontend?``) for subsequent use. Usually the first
-thing to do after a successful open is to find out the frontend type
-with :ref:`FE_GET_INFO`.
-
-The device can be opened in read-only mode, which only allows monitoring
-of device status and statistics, or read/write mode, which allows any
-kind of use (e.g. performing tuning operations.)
-
-In a system with multiple front-ends, it is usually the case that
-multiple devices cannot be open in read/write mode simultaneously. As
-long as a front-end device is opened in read/write mode, other open()
-calls in read/write mode will either fail or block, depending on whether
-non-blocking or blocking mode was specified. A front-end device opened
-in blocking mode can later be put into non-blocking mode (and vice
-versa) using the F_SETFL command of the fcntl system call. This is a
-standard system call, documented in the Linux manual page for fcntl.
-When an open() call has succeeded, the device will be ready for use in
-the specified mode. This implies that the corresponding hardware is
-powered up, and that other front-ends may have been powered down to make
-that possible.
-
-
-Return Value
-============
-
-On success :ref:`open() <frontend_f_open>` returns the new file descriptor.
-On error, -1 is returned, and the ``errno`` variable is set appropriately.
-
-Possible error codes are:
-
-EACCES
- The caller has no permission to access the device.
-
-EBUSY
- The the device driver is already in use.
-
-ENXIO
- No device corresponding to this device special file exists.
-
-ENOMEM
- Not enough kernel memory was available to complete the request.
-
-EMFILE
- The process already has the maximum number of files open.
-
-ENFILE
- The limit on the total number of files open on the system has been
- reached.
-
-ENODEV
- The device got removed.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _frontend_fcalls:
-
-#######################
-Frontend Function Calls
-#######################
-
-.. toctree::
- :maxdepth: 1
-
- frontend_f_open
- frontend_f_close
- fe-get-info
- fe-read-status
- fe-get-property
- fe-diseqc-reset-overload
- fe-diseqc-send-master-cmd
- fe-diseqc-recv-slave-reply
- fe-diseqc-send-burst
- fe-set-tone
- fe-set-voltage
- fe-enable-high-lnb-voltage
- fe-set-frontend-tune-mode
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _frontend_h:
-
-************************
-DVB Frontend Header File
-************************
-
-.. kernel-include:: $BUILDDIR/frontend.h.rst
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _frontend_legacy_types:
-
-Frontend Legacy Data Types
-==========================
-
-
-.. toctree::
- :maxdepth: 1
-
- fe-type-t
- fe-bandwidth-t
- dvb-frontend-parameters
- dvb-frontend-event
-
-
-.. _frontend_legacy_fcalls:
-
-Frontend Legacy Function Calls
-==============================
-
-Those functions are defined at DVB version 3. The support is kept in the
-kernel due to compatibility issues only. Their usage is strongly not
-recommended
-
-
-.. toctree::
- :maxdepth: 1
-
- fe-read-ber
- fe-read-snr
- fe-read-signal-strength
- fe-read-uncorrected-blocks
- fe-set-frontend
- fe-get-frontend
- fe-get-event
- fe-dishnetwork-send-legacy-cmd
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _frontend_legacy_dvbv3_api:
-
-****************************************
-DVB Frontend legacy API (a. k. a. DVBv3)
-****************************************
-
-The usage of this API is deprecated, as it doesn't support all digital
-TV standards, doesn't provide good statistics measurements and provides
-incomplete information. This is kept only to support legacy
-applications.
-
-
-.. toctree::
- :maxdepth: 1
-
- frontend_legacy_api
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _dvb_introdution:
-
-************
-Introduction
-************
-
-
-.. _requisites:
-
-What you need to know
-=====================
-
-The reader of this document is required to have some knowledge in the
-area of digital video broadcasting (DVB) and should be familiar with
-part I of the MPEG2 specification ISO/IEC 13818 (aka ITU-T H.222), i.e
-you should know what a program/transport stream (PS/TS) is and what is
-meant by a packetized elementary stream (PES) or an I-frame.
-
-Various DVB standards documents are available from http://www.dvb.org
-and/or http://www.etsi.org.
-
-It is also necessary to know how to access unix/linux devices and how to
-use ioctl calls. This also includes the knowledge of C or C++.
-
-
-.. _history:
-
-History
-=======
-
-The first API for DVB cards we used at Convergence in late 1999 was an
-extension of the Video4Linux API which was primarily developed for frame
-grabber cards. As such it was not really well suited to be used for DVB
-cards and their new features like recording MPEG streams and filtering
-several section and PES data streams at the same time.
-
-In early 2000, we were approached by Nokia with a proposal for a new
-standard Linux DVB API. As a commitment to the development of terminals
-based on open standards, Nokia and Convergence made it available to all
-Linux developers and published it on https://linuxtv.org in September
-2000. Convergence is the maintainer of the Linux DVB API. Together with
-the LinuxTV community (i.e. you, the reader of this document), the Linux
-DVB API will be constantly reviewed and improved. With the Linux driver
-for the Siemens/Hauppauge DVB PCI card Convergence provides a first
-implementation of the Linux DVB API.
-
-
-.. _overview:
-
-Overview
-========
-
-
-.. _stb_components:
-
-.. figure:: intro_files/dvbstb.*
- :alt: dvbstb.pdf / dvbstb.png
- :align: center
-
- Components of a DVB card/STB
-
-A DVB PCI card or DVB set-top-box (STB) usually consists of the
-following main hardware components:
-
-- Frontend consisting of tuner and DVB demodulator
-
- Here the raw signal reaches the DVB hardware from a satellite dish or
- antenna or directly from cable. The frontend down-converts and
- demodulates this signal into an MPEG transport stream (TS). In case
- of a satellite frontend, this includes a facility for satellite
- equipment control (SEC), which allows control of LNB polarization,
- multi feed switches or dish rotors.
-
-- Conditional Access (CA) hardware like CI adapters and smartcard slots
-
- The complete TS is passed through the CA hardware. Programs to which
- the user has access (controlled by the smart card) are decoded in
- real time and re-inserted into the TS.
-
-- Demultiplexer which filters the incoming DVB stream
-
- The demultiplexer splits the TS into its components like audio and
- video streams. Besides usually several of such audio and video
- streams it also contains data streams with information about the
- programs offered in this or other streams of the same provider.
-
-- MPEG2 audio and video decoder
-
- The main targets of the demultiplexer are the MPEG2 audio and video
- decoders. After decoding they pass on the uncompressed audio and
- video to the computer screen or (through a PAL/NTSC encoder) to a TV
- set.
-
-:ref:`stb_components` shows a crude schematic of the control and data
-flow between those components.
-
-On a DVB PCI card not all of these have to be present since some
-functionality can be provided by the main CPU of the PC (e.g. MPEG
-picture and sound decoding) or is not needed (e.g. for data-only uses
-like “internet over satellite”). Also not every card or STB provides
-conditional access hardware.
-
-
-.. _dvb_devices:
-
-Linux DVB Devices
-=================
-
-The Linux DVB API lets you control these hardware components through
-currently six Unix-style character devices for video, audio, frontend,
-demux, CA and IP-over-DVB networking. The video and audio devices
-control the MPEG2 decoder hardware, the frontend device the tuner and
-the DVB demodulator. The demux device gives you control over the PES and
-section filters of the hardware. If the hardware does not support
-filtering these filters can be implemented in software. Finally, the CA
-device controls all the conditional access capabilities of the hardware.
-It can depend on the individual security requirements of the platform,
-if and how many of the CA functions are made available to the
-application through this device.
-
-All devices can be found in the ``/dev`` tree under ``/dev/dvb``. The
-individual devices are called:
-
-- ``/dev/dvb/adapterN/audioM``,
-
-- ``/dev/dvb/adapterN/videoM``,
-
-- ``/dev/dvb/adapterN/frontendM``,
-
-- ``/dev/dvb/adapterN/netM``,
-
-- ``/dev/dvb/adapterN/demuxM``,
-
-- ``/dev/dvb/adapterN/dvrM``,
-
-- ``/dev/dvb/adapterN/caM``,
-
-where N enumerates the DVB PCI cards in a system starting from 0, and M
-enumerates the devices of each type within each adapter, starting
-from 0, too. We will omit the “ ``/dev/dvb/adapterN/``\ ” in the further
-discussion of these devices.
-
-More details about the data structures and function calls of all the
-devices are described in the following chapters.
-
-
-.. _include_files:
-
-API include files
-=================
-
-For each of the DVB devices a corresponding include file exists. The DVB
-API include files should be included in application sources with a
-partial path like:
-
-
-.. code-block:: c
-
- #include <linux/dvb/ca.h>
-
- #include <linux/dvb/dmx.h>
-
- #include <linux/dvb/frontend.h>
-
- #include <linux/dvb/net.h>
-
-
-To enable applications to support different API version, an additional
-include file ``linux/dvb/version.h`` exists, which defines the constant
-``DVB_API_VERSION``. This document describes ``DVB_API_VERSION 5.10``.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _legacy_dvb_apis:
-
-*******************
-DVB Deprecated APIs
-*******************
-
-The APIs described here are kept only for historical reasons. There's
-just one driver for a very legacy hardware that uses this API. No modern
-drivers should use it. Instead, audio and video should be using the V4L2
-and ALSA APIs, and the pipelines should be set using the Media
-Controller API
-
-
-.. toctree::
- :maxdepth: 1
-
- video
- audio
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _NET_ADD_IF:
-
-****************
-ioctl NET_ADD_IF
-****************
-
-Name
-====
-
-NET_ADD_IF - Creates a new network interface for a given Packet ID.
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct dvb_net_if *net_if )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <frontend_f_open>`.
-
-``request``
- FE_SET_TONE
-
-``net_if``
- pointer to struct :ref:`dvb_net_if <dvb-net-if>`
-
-
-Description
-===========
-
-The NET_ADD_IF ioctl system call selects the Packet ID (PID) that
-contains a TCP/IP traffic, the type of encapsulation to be used (MPE or
-ULE) and the interface number for the new interface to be created. When
-the system call successfully returns, a new virtual network interface is
-created.
-
-The struct :ref:`dvb_net_if <dvb-net-if>`::ifnum field will be
-filled with the number of the created interface.
-
-
-.. _dvb-net-if-t:
-
-struct dvb_net_if description
-=============================
-
-.. _dvb-net-if:
-
-.. flat-table:: struct dvb_net_if
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - ID
-
- - Description
-
- - .. row 2
-
- - pid
-
- - Packet ID (PID) of the MPEG-TS that contains data
-
- - .. row 3
-
- - ifnum
-
- - number of the DVB interface.
-
- - .. row 4
-
- - feedtype
-
- - Encapsulation type of the feed. It can be:
- ``DVB_NET_FEEDTYPE_MPE`` for MPE encoding or
- ``DVB_NET_FEEDTYPE_ULE`` for ULE encoding.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _NET_GET_IF:
-
-****************
-ioctl NET_GET_IF
-****************
-
-Name
-====
-
-NET_GET_IF - Read the configuration data of an interface created via - :ref:`NET_ADD_IF <net>`.
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct dvb_net_if *net_if )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <frontend_f_open>`.
-
-``request``
- FE_SET_TONE
-
-``net_if``
- pointer to struct :ref:`dvb_net_if <dvb-net-if>`
-
-
-Description
-===========
-
-The NET_GET_IF ioctl uses the interface number given by the struct
-:ref:`dvb_net_if <dvb-net-if>`::ifnum field and fills the content of
-struct :ref:`dvb_net_if <dvb-net-if>` with the packet ID and
-encapsulation type used on such interface. If the interface was not
-created yet with :ref:`NET_ADD_IF <net>`, it will return -1 and fill
-the ``errno`` with ``EINVAL`` error code.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _NET_REMOVE_IF:
-
-*******************
-ioctl NET_REMOVE_IF
-*******************
-
-Name
-====
-
-NET_REMOVE_IF - Removes a network interface.
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, int ifnum )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <frontend_f_open>`.
-
-``request``
- FE_SET_TONE
-
-``net_if``
- number of the interface to be removed
-
-
-Description
-===========
-
-The NET_REMOVE_IF ioctl deletes an interface previously created via
-:ref:`NET_ADD_IF <net>`.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _net:
-
-###############
-DVB Network API
-###############
-The DVB net device controls the mapping of data packages that are part
-of a transport stream to be mapped into a virtual network interface,
-visible through the standard Linux network protocol stack.
-
-Currently, two encapsulations are supported:
-
-- `Multi Protocol Encapsulation (MPE) <http://en.wikipedia.org/wiki/Multiprotocol_Encapsulation>`__
-
-- `Ultra Lightweight Encapsulation (ULE) <http://en.wikipedia.org/wiki/Unidirectional_Lightweight_Encapsulation>`__
-
-In order to create the Linux virtual network interfaces, an application
-needs to tell to the Kernel what are the PIDs and the encapsulation
-types that are present on the transport stream. This is done through
-``/dev/dvb/adapter?/net?`` device node. The data will be available via
-virtual ``dvb?_?`` network interfaces, and will be controlled/routed via
-the standard ip tools (like ip, route, netstat, ifconfig, etc).
-
-Data types and and ioctl definitions are defined via ``linux/dvb/net.h``
-header.
-
-
-.. _net_fcalls:
-
-######################
-DVB net Function Calls
-######################
-
-.. toctree::
- :maxdepth: 1
-
- net-add-if
- net-remove-if
- net-get-if
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _net_h:
-
-***********************
-DVB Network Header File
-***********************
-
-.. kernel-include:: $BUILDDIR/net.h.rst
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _query-dvb-frontend-info:
-
-*****************************
-Querying frontend information
-*****************************
-
-Usually, the first thing to do when the frontend is opened is to check
-the frontend capabilities. This is done using
-:ref:`FE_GET_INFO`. This ioctl will enumerate the
-DVB API version and other characteristics about the frontend, and can be
-opened either in read only or read/write mode.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDEO_CLEAR_BUFFER:
-
-==================
-VIDEO_CLEAR_BUFFER
-==================
-
-Name
-----
-
-VIDEO_CLEAR_BUFFER
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(fd, int request = VIDEO_CLEAR_BUFFER)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals VIDEO_CLEAR_BUFFER for this command.
-
-
-Description
------------
-
-This ioctl call clears all video buffers in the driver and in the
-decoder hardware.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDEO_COMMAND:
-
-=============
-VIDEO_COMMAND
-=============
-
-Name
-----
-
-VIDEO_COMMAND
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(int fd, int request = VIDEO_COMMAND, struct video_command *cmd)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals VIDEO_COMMAND for this command.
-
- - .. row 3
-
- - struct video_command \*cmd
-
- - Commands the decoder.
-
-
-Description
------------
-
-This ioctl is obsolete. Do not use in new drivers. For V4L2 decoders
-this ioctl has been replaced by the
-:ref:`VIDIOC_DECODER_CMD` ioctl.
-
-This ioctl commands the decoder. The ``video_command`` struct is a
-subset of the ``v4l2_decoder_cmd`` struct, so refer to the
-:ref:`VIDIOC_DECODER_CMD` documentation for
-more information.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDEO_CONTINUE:
-
-==============
-VIDEO_CONTINUE
-==============
-
-Name
-----
-
-VIDEO_CONTINUE
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(fd, int request = VIDEO_CONTINUE)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals VIDEO_CONTINUE for this command.
-
-
-Description
------------
-
-This ioctl is for DVB devices only. To control a V4L2 decoder use the
-V4L2 :ref:`VIDIOC_DECODER_CMD` instead.
-
-This ioctl call restarts decoding and playing processes of the video
-stream which was played before a call to VIDEO_FREEZE was made.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDEO_FAST_FORWARD:
-
-==================
-VIDEO_FAST_FORWARD
-==================
-
-Name
-----
-
-VIDEO_FAST_FORWARD
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(fd, int request = VIDEO_FAST_FORWARD, int nFrames)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals VIDEO_FAST_FORWARD for this command.
-
- - .. row 3
-
- - int nFrames
-
- - The number of frames to skip.
-
-
-Description
------------
-
-This ioctl call asks the Video Device to skip decoding of N number of
-I-frames. This call can only be used if VIDEO_SOURCE_MEMORY is
-selected.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``EPERM``
-
- - Mode VIDEO_SOURCE_MEMORY not selected.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _video_fclose:
-
-=================
-dvb video close()
-=================
-
-Name
-----
-
-dvb video close()
-
-
-Synopsis
---------
-
-.. cpp:function:: int close(int fd)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
-
-Description
------------
-
-This system call closes a previously opened video device.
-
-
-Return Value
-------------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``EBADF``
-
- - fd is not a valid open file descriptor.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _video_fopen:
-
-================
-dvb video open()
-================
-
-Name
-----
-
-dvb video open()
-
-
-Synopsis
---------
-
-.. cpp:function:: int open(const char *deviceName, int flags)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - const char \*deviceName
-
- - Name of specific video device.
-
- - .. row 2
-
- - int flags
-
- - A bit-wise OR of the following flags:
-
- - .. row 3
-
- -
- - O_RDONLY read-only access
-
- - .. row 4
-
- -
- - O_RDWR read/write access
-
- - .. row 5
-
- -
- - O_NONBLOCK open in non-blocking mode
-
- - .. row 6
-
- -
- - (blocking mode is the default)
-
-
-Description
------------
-
-This system call opens a named video device (e.g.
-/dev/dvb/adapter0/video0) for subsequent use.
-
-When an open() call has succeeded, the device will be ready for use. The
-significance of blocking or non-blocking mode is described in the
-documentation for functions where there is a difference. It does not
-affect the semantics of the open() call itself. A device opened in
-blocking mode can later be put into non-blocking mode (and vice versa)
-using the F_SETFL command of the fcntl system call. This is a standard
-system call, documented in the Linux manual page for fcntl. Only one
-user can open the Video Device in O_RDWR mode. All other attempts to
-open the device in this mode will fail, and an error-code will be
-returned. If the Video Device is opened in O_RDONLY mode, the only
-ioctl call that can be used is VIDEO_GET_STATUS. All other call will
-return an error code.
-
-
-Return Value
-------------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``ENODEV``
-
- - Device driver not loaded/available.
-
- - .. row 2
-
- - ``EINTERNAL``
-
- - Internal error.
-
- - .. row 3
-
- - ``EBUSY``
-
- - Device or resource busy.
-
- - .. row 4
-
- - ``EINVAL``
-
- - Invalid argument.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDEO_FREEZE:
-
-============
-VIDEO_FREEZE
-============
-
-Name
-----
-
-VIDEO_FREEZE
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(fd, int request = VIDEO_FREEZE)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals VIDEO_FREEZE for this command.
-
-
-Description
------------
-
-This ioctl is for DVB devices only. To control a V4L2 decoder use the
-V4L2 :ref:`VIDIOC_DECODER_CMD` instead.
-
-This ioctl call suspends the live video stream being played. Decoding
-and playing are frozen. It is then possible to restart the decoding and
-playing process of the video stream using the VIDEO_CONTINUE command.
-If VIDEO_SOURCE_MEMORY is selected in the ioctl call
-VIDEO_SELECT_SOURCE, the DVB subsystem will not decode any more data
-until the ioctl call VIDEO_CONTINUE or VIDEO_PLAY is performed.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _video_fwrite:
-
-=================
-dvb video write()
-=================
-
-Name
-----
-
-dvb video write()
-
-
-Synopsis
---------
-
-.. cpp:function:: size_t write(int fd, const void *buf, size_t count)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - void \*buf
-
- - Pointer to the buffer containing the PES data.
-
- - .. row 3
-
- - size_t count
-
- - Size of buf.
-
-
-Description
------------
-
-This system call can only be used if VIDEO_SOURCE_MEMORY is selected
-in the ioctl call VIDEO_SELECT_SOURCE. The data provided shall be in
-PES format, unless the capability allows other formats. If O_NONBLOCK
-is not specified the function will block until buffer space is
-available. The amount of data to be transferred is implied by count.
-
-
-Return Value
-------------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``EPERM``
-
- - Mode VIDEO_SOURCE_MEMORY not selected.
-
- - .. row 2
-
- - ``ENOMEM``
-
- - Attempted to write more data than the internal buffer can hold.
-
- - .. row 3
-
- - ``EBADF``
-
- - fd is not a valid open file descriptor.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDEO_GET_CAPABILITIES:
-
-======================
-VIDEO_GET_CAPABILITIES
-======================
-
-Name
-----
-
-VIDEO_GET_CAPABILITIES
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(fd, int request = VIDEO_GET_CAPABILITIES, unsigned int *cap)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals VIDEO_GET_CAPABILITIES for this command.
-
- - .. row 3
-
- - unsigned int \*cap
-
- - Pointer to a location where to store the capability information.
-
-
-Description
------------
-
-This ioctl call asks the video device about its decoding capabilities.
-On success it returns and integer which has bits set according to the
-defines in section ??.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDEO_GET_EVENT:
-
-===============
-VIDEO_GET_EVENT
-===============
-
-Name
-----
-
-VIDEO_GET_EVENT
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(fd, int request = VIDEO_GET_EVENT, struct video_event *ev)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals VIDEO_GET_EVENT for this command.
-
- - .. row 3
-
- - struct video_event \*ev
-
- - Points to the location where the event, if any, is to be stored.
-
-
-Description
------------
-
-This ioctl is for DVB devices only. To get events from a V4L2 decoder
-use the V4L2 :ref:`VIDIOC_DQEVENT` ioctl instead.
-
-This ioctl call returns an event of type video_event if available. If
-an event is not available, the behavior depends on whether the device is
-in blocking or non-blocking mode. In the latter case, the call fails
-immediately with errno set to ``EWOULDBLOCK``. In the former case, the call
-blocks until an event becomes available. The standard Linux poll()
-and/or select() system calls can be used with the device file descriptor
-to watch for new events. For select(), the file descriptor should be
-included in the exceptfds argument, and for poll(), POLLPRI should be
-specified as the wake-up condition. Read-only permissions are sufficient
-for this ioctl call.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``EWOULDBLOCK``
-
- - There is no event pending, and the device is in non-blocking mode.
-
- - .. row 2
-
- - ``EOVERFLOW``
-
- - Overflow in event queue - one or more events were lost.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDEO_GET_FRAME_COUNT:
-
-=====================
-VIDEO_GET_FRAME_COUNT
-=====================
-
-Name
-----
-
-VIDEO_GET_FRAME_COUNT
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(int fd, int request = VIDEO_GET_FRAME_COUNT, __u64 *pts)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals VIDEO_GET_FRAME_COUNT for this command.
-
- - .. row 3
-
- - __u64 \*pts
-
- - Returns the number of frames displayed since the decoder was
- started.
-
-
-Description
------------
-
-This ioctl is obsolete. Do not use in new drivers. For V4L2 decoders
-this ioctl has been replaced by the ``V4L2_CID_MPEG_VIDEO_DEC_FRAME``
-control.
-
-This ioctl call asks the Video Device to return the number of displayed
-frames since the decoder was started.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDEO_GET_FRAME_RATE:
-
-====================
-VIDEO_GET_FRAME_RATE
-====================
-
-Name
-----
-
-VIDEO_GET_FRAME_RATE
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(int fd, int request = VIDEO_GET_FRAME_RATE, unsigned int *rate)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals VIDEO_GET_FRAME_RATE for this command.
-
- - .. row 3
-
- - unsigned int \*rate
-
- - Returns the framerate in number of frames per 1000 seconds.
-
-
-Description
------------
-
-This ioctl call asks the Video Device to return the current framerate.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDEO_GET_NAVI:
-
-==============
-VIDEO_GET_NAVI
-==============
-
-Name
-----
-
-VIDEO_GET_NAVI
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(fd, int request = VIDEO_GET_NAVI , video_navi_pack_t *navipack)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals VIDEO_GET_NAVI for this command.
-
- - .. row 3
-
- - video_navi_pack_t \*navipack
-
- - PCI or DSI pack (private stream 2) according to section ??.
-
-
-Description
------------
-
-This ioctl returns navigational information from the DVD stream. This is
-especially needed if an encoded stream has to be decoded by the
-hardware.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``EFAULT``
-
- - driver is not able to return navigational information
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDEO_GET_PTS:
-
-=============
-VIDEO_GET_PTS
-=============
-
-Name
-----
-
-VIDEO_GET_PTS
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(int fd, int request = VIDEO_GET_PTS, __u64 *pts)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals VIDEO_GET_PTS for this command.
-
- - .. row 3
-
- - __u64 \*pts
-
- - Returns the 33-bit timestamp as defined in ITU T-REC-H.222.0 /
- ISO/IEC 13818-1.
-
- The PTS should belong to the currently played frame if possible,
- but may also be a value close to it like the PTS of the last
- decoded frame or the last PTS extracted by the PES parser.
-
-
-Description
------------
-
-This ioctl is obsolete. Do not use in new drivers. For V4L2 decoders
-this ioctl has been replaced by the ``V4L2_CID_MPEG_VIDEO_DEC_PTS``
-control.
-
-This ioctl call asks the Video Device to return the current PTS
-timestamp.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDEO_GET_SIZE:
-
-==============
-VIDEO_GET_SIZE
-==============
-
-Name
-----
-
-VIDEO_GET_SIZE
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(int fd, int request = VIDEO_GET_SIZE, video_size_t *size)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals VIDEO_GET_SIZE for this command.
-
- - .. row 3
-
- - video_size_t \*size
-
- - Returns the size and aspect ratio.
-
-
-Description
------------
-
-This ioctl returns the size and aspect ratio.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDEO_GET_STATUS:
-
-================
-VIDEO_GET_STATUS
-================
-
-Name
-----
-
-VIDEO_GET_STATUS
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(fd, int request = VIDEO_GET_STATUS, struct video_status *status)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals VIDEO_GET_STATUS for this command.
-
- - .. row 3
-
- - struct video_status \*status
-
- - Returns the current status of the Video Device.
-
-
-Description
------------
-
-This ioctl call asks the Video Device to return the current status of
-the device.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDEO_PLAY:
-
-==========
-VIDEO_PLAY
-==========
-
-Name
-----
-
-VIDEO_PLAY
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(fd, int request = VIDEO_PLAY)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals VIDEO_PLAY for this command.
-
-
-Description
------------
-
-This ioctl is for DVB devices only. To control a V4L2 decoder use the
-V4L2 :ref:`VIDIOC_DECODER_CMD` instead.
-
-This ioctl call asks the Video Device to start playing a video stream
-from the selected source.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDEO_SELECT_SOURCE:
-
-===================
-VIDEO_SELECT_SOURCE
-===================
-
-Name
-----
-
-VIDEO_SELECT_SOURCE
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(fd, int request = VIDEO_SELECT_SOURCE, video_stream_source_t source)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals VIDEO_SELECT_SOURCE for this command.
-
- - .. row 3
-
- - video_stream_source_t source
-
- - Indicates which source shall be used for the Video stream.
-
-
-Description
------------
-
-This ioctl is for DVB devices only. This ioctl was also supported by the
-V4L2 ivtv driver, but that has been replaced by the ivtv-specific
-``IVTV_IOC_PASSTHROUGH_MODE`` ioctl.
-
-This ioctl call informs the video device which source shall be used for
-the input data. The possible sources are demux or memory. If memory is
-selected, the data is fed to the video device through the write command.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDEO_SET_ATTRIBUTES:
-
-====================
-VIDEO_SET_ATTRIBUTES
-====================
-
-Name
-----
-
-VIDEO_SET_ATTRIBUTES
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(fd, int request = VIDEO_SET_ATTRIBUTE ,video_attributes_t vattr)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals VIDEO_SET_ATTRIBUTE for this command.
-
- - .. row 3
-
- - video_attributes_t vattr
-
- - video attributes according to section ??.
-
-
-Description
------------
-
-This ioctl is intended for DVD playback and allows you to set certain
-information about the stream. Some hardware may not need this
-information, but the call also tells the hardware to prepare for DVD
-playback.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``EINVAL``
-
- - input is not a valid attribute setting.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDEO_SET_BLANK:
-
-===============
-VIDEO_SET_BLANK
-===============
-
-Name
-----
-
-VIDEO_SET_BLANK
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(fd, int request = VIDEO_SET_BLANK, boolean mode)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals VIDEO_SET_BLANK for this command.
-
- - .. row 3
-
- - boolean mode
-
- - TRUE: Blank screen when stop.
-
- - .. row 4
-
- -
- - FALSE: Show last decoded frame.
-
-
-Description
------------
-
-This ioctl call asks the Video Device to blank out the picture.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDEO_SET_DISPLAY_FORMAT:
-
-========================
-VIDEO_SET_DISPLAY_FORMAT
-========================
-
-Name
-----
-
-VIDEO_SET_DISPLAY_FORMAT
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(fd, int request = VIDEO_SET_DISPLAY_FORMAT, video_display_format_t format)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals VIDEO_SET_DISPLAY_FORMAT for this command.
-
- - .. row 3
-
- - video_display_format_t format
-
- - Selects the video format to be used.
-
-
-Description
------------
-
-This ioctl call asks the Video Device to select the video format to be
-applied by the MPEG chip on the video.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDEO_SET_FORMAT:
-
-================
-VIDEO_SET_FORMAT
-================
-
-Name
-----
-
-VIDEO_SET_FORMAT
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(fd, int request = VIDEO_SET_FORMAT, video_format_t format)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals VIDEO_SET_FORMAT for this command.
-
- - .. row 3
-
- - video_format_t format
-
- - video format of TV as defined in section ??.
-
-
-Description
------------
-
-This ioctl sets the screen format (aspect ratio) of the connected output
-device (TV) so that the output of the decoder can be adjusted
-accordingly.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``EINVAL``
-
- - format is not a valid video format.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDEO_SET_HIGHLIGHT:
-
-===================
-VIDEO_SET_HIGHLIGHT
-===================
-
-Name
-----
-
-VIDEO_SET_HIGHLIGHT
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(fd, int request = VIDEO_SET_HIGHLIGHT ,video_highlight_t *vhilite)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals VIDEO_SET_HIGHLIGHT for this command.
-
- - .. row 3
-
- - video_highlight_t \*vhilite
-
- - SPU Highlight information according to section ??.
-
-
-Description
------------
-
-This ioctl sets the SPU highlight information for the menu access of a
-DVD.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDEO_SET_ID:
-
-============
-VIDEO_SET_ID
-============
-
-Name
-----
-
-VIDEO_SET_ID
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(int fd, int request = VIDEO_SET_ID, int id)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals VIDEO_SET_ID for this command.
-
- - .. row 3
-
- - int id
-
- - video sub-stream id
-
-
-Description
------------
-
-This ioctl selects which sub-stream is to be decoded if a program or
-system stream is sent to the video device.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``EINVAL``
-
- - Invalid sub-stream id.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDEO_SET_SPU_PALETTE:
-
-=====================
-VIDEO_SET_SPU_PALETTE
-=====================
-
-Name
-----
-
-VIDEO_SET_SPU_PALETTE
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(fd, int request = VIDEO_SET_SPU_PALETTE, video_spu_palette_t *palette )
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals VIDEO_SET_SPU_PALETTE for this command.
-
- - .. row 3
-
- - video_spu_palette_t \*palette
-
- - SPU palette according to section ??.
-
-
-Description
------------
-
-This ioctl sets the SPU color palette.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``EINVAL``
-
- - input is not a valid palette or driver doesn’t handle SPU.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDEO_SET_SPU:
-
-=============
-VIDEO_SET_SPU
-=============
-
-Name
-----
-
-VIDEO_SET_SPU
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(fd, int request = VIDEO_SET_SPU , video_spu_t *spu)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals VIDEO_SET_SPU for this command.
-
- - .. row 3
-
- - video_spu_t \*spu
-
- - SPU decoding (de)activation and subid setting according to section
- ??.
-
-
-Description
------------
-
-This ioctl activates or deactivates SPU decoding in a DVD input stream.
-It can only be used, if the driver is able to handle a DVD stream.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``EINVAL``
-
- - input is not a valid spu setting or driver cannot handle SPU.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDEO_SET_STREAMTYPE:
-
-====================
-VIDEO_SET_STREAMTYPE
-====================
-
-Name
-----
-
-VIDEO_SET_STREAMTYPE
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(fd, int request = VIDEO_SET_STREAMTYPE, int type)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals VIDEO_SET_STREAMTYPE for this command.
-
- - .. row 3
-
- - int type
-
- - stream type
-
-
-Description
------------
-
-This ioctl tells the driver which kind of stream to expect being written
-to it. If this call is not used the default of video PES is used. Some
-drivers might not support this call and always expect PES.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDEO_SET_SYSTEM:
-
-================
-VIDEO_SET_SYSTEM
-================
-
-Name
-----
-
-VIDEO_SET_SYSTEM
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(fd, int request = VIDEO_SET_SYSTEM , video_system_t system)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals VIDEO_SET_FORMAT for this command.
-
- - .. row 3
-
- - video_system_t system
-
- - video system of TV output.
-
-
-Description
------------
-
-This ioctl sets the television output format. The format (see section
-??) may vary from the color format of the displayed MPEG stream. If the
-hardware is not able to display the requested format the call will
-return an error.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``EINVAL``
-
- - system is not a valid or supported video system.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDEO_SLOWMOTION:
-
-================
-VIDEO_SLOWMOTION
-================
-
-Name
-----
-
-VIDEO_SLOWMOTION
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(fd, int request = VIDEO_SLOWMOTION, int nFrames)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals VIDEO_SLOWMOTION for this command.
-
- - .. row 3
-
- - int nFrames
-
- - The number of times to repeat each frame.
-
-
-Description
------------
-
-This ioctl call asks the video device to repeat decoding frames N number
-of times. This call can only be used if VIDEO_SOURCE_MEMORY is
-selected.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``EPERM``
-
- - Mode VIDEO_SOURCE_MEMORY not selected.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDEO_STILLPICTURE:
-
-==================
-VIDEO_STILLPICTURE
-==================
-
-Name
-----
-
-VIDEO_STILLPICTURE
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(fd, int request = VIDEO_STILLPICTURE, struct video_still_picture *sp)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals VIDEO_STILLPICTURE for this command.
-
- - .. row 3
-
- - struct video_still_picture \*sp
-
- - Pointer to a location where an I-frame and size is stored.
-
-
-Description
------------
-
-This ioctl call asks the Video Device to display a still picture
-(I-frame). The input data shall contain an I-frame. If the pointer is
-NULL, then the current displayed still picture is blanked.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDEO_STOP:
-
-==========
-VIDEO_STOP
-==========
-
-Name
-----
-
-VIDEO_STOP
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(fd, int request = VIDEO_STOP, boolean mode)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals VIDEO_STOP for this command.
-
- - .. row 3
-
- - Boolean mode
-
- - Indicates how the screen shall be handled.
-
- - .. row 4
-
- -
- - TRUE: Blank screen when stop.
-
- - .. row 5
-
- -
- - FALSE: Show last decoded frame.
-
-
-Description
------------
-
-This ioctl is for DVB devices only. To control a V4L2 decoder use the
-V4L2 :ref:`VIDIOC_DECODER_CMD` instead.
-
-This ioctl call asks the Video Device to stop playing the current
-stream. Depending on the input parameter, the screen can be blanked out
-or displaying the last decoded frame.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDEO_TRY_COMMAND:
-
-=================
-VIDEO_TRY_COMMAND
-=================
-
-Name
-----
-
-VIDEO_TRY_COMMAND
-
-
-Synopsis
---------
-
-.. cpp:function:: int ioctl(int fd, int request = VIDEO_TRY_COMMAND, struct video_command *cmd)
-
-
-Arguments
----------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - int fd
-
- - File descriptor returned by a previous call to open().
-
- - .. row 2
-
- - int request
-
- - Equals VIDEO_TRY_COMMAND for this command.
-
- - .. row 3
-
- - struct video_command \*cmd
-
- - Try a decoder command.
-
-
-Description
------------
-
-This ioctl is obsolete. Do not use in new drivers. For V4L2 decoders
-this ioctl has been replaced by the
-:ref:`VIDIOC_TRY_DECODER_CMD <VIDIOC_DECODER_CMD>` ioctl.
-
-This ioctl tries a decoder command. The ``video_command`` struct is a
-subset of the ``v4l2_decoder_cmd`` struct, so refer to the
-:ref:`VIDIOC_TRY_DECODER_CMD <VIDIOC_DECODER_CMD>` documentation
-for more information.
-
-
-Return Value
-------------
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _dvb_video:
-
-################
-DVB Video Device
-################
-The DVB video device controls the MPEG2 video decoder of the DVB
-hardware. It can be accessed through **/dev/dvb/adapter0/video0**. Data
-types and and ioctl definitions can be accessed by including
-**linux/dvb/video.h** in your application.
-
-Note that the DVB video device only controls decoding of the MPEG video
-stream, not its presentation on the TV or computer screen. On PCs this
-is typically handled by an associated video4linux device, e.g.
-**/dev/video**, which allows scaling and defining output windows.
-
-Some DVB cards don’t have their own MPEG decoder, which results in the
-omission of the audio and video device as well as the video4linux
-device.
-
-The ioctls that deal with SPUs (sub picture units) and navigation
-packets are only supported on some MPEG decoders made for DVD playback.
-
-These ioctls were also used by V4L2 to control MPEG decoders implemented
-in V4L2. The use of these ioctls for that purpose has been made obsolete
-and proper V4L2 ioctls or controls have been created to replace that
-functionality.
-
-
-.. toctree::
- :maxdepth: 1
-
- video_types
- video_function_calls
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _video_function_calls:
-
-********************
-Video Function Calls
-********************
-
-.. toctree::
- :maxdepth: 1
-
- video-fopen
- video-fclose
- video-fwrite
- video-stop
- video-play
- video-freeze
- video-continue
- video-select-source
- video-set-blank
- video-get-status
- video-get-frame-count
- video-get-pts
- video-get-frame-rate
- video-get-event
- video-command
- video-try-command
- video-get-size
- video-set-display-format
- video-stillpicture
- video-fast-forward
- video-slowmotion
- video-get-capabilities
- video-set-id
- video-clear-buffer
- video-set-streamtype
- video-set-format
- video-set-system
- video-set-highlight
- video-set-spu
- video-set-spu-palette
- video-get-navi
- video-set-attributes
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _video_h:
-
-*********************
-DVB Video Header File
-*********************
-
-.. kernel-include:: $BUILDDIR/video.h.rst
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _video_types:
-
-****************
-Video Data Types
-****************
-
-
-.. _video-format-t:
-
-video_format_t
-==============
-
-The ``video_format_t`` data type defined by
-
-
-.. code-block:: c
-
- typedef enum {
- VIDEO_FORMAT_4_3, /* Select 4:3 format */
- VIDEO_FORMAT_16_9, /* Select 16:9 format. */
- VIDEO_FORMAT_221_1 /* 2.21:1 */
- } video_format_t;
-
-is used in the VIDEO_SET_FORMAT function (??) to tell the driver which
-aspect ratio the output hardware (e.g. TV) has. It is also used in the
-data structures video_status (??) returned by VIDEO_GET_STATUS (??)
-and video_event (??) returned by VIDEO_GET_EVENT (??) which report
-about the display format of the current video stream.
-
-
-.. _video-displayformat-t:
-
-video_displayformat_t
-=====================
-
-In case the display format of the video stream and of the display
-hardware differ the application has to specify how to handle the
-cropping of the picture. This can be done using the
-VIDEO_SET_DISPLAY_FORMAT call (??) which accepts
-
-
-.. code-block:: c
-
- typedef enum {
- VIDEO_PAN_SCAN, /* use pan and scan format */
- VIDEO_LETTER_BOX, /* use letterbox format */
- VIDEO_CENTER_CUT_OUT /* use center cut out format */
- } video_displayformat_t;
-
-as argument.
-
-
-.. _video-stream-source-t:
-
-video_stream_source_t
-=====================
-
-The video stream source is set through the VIDEO_SELECT_SOURCE call
-and can take the following values, depending on whether we are replaying
-from an internal (demuxer) or external (user write) source.
-
-
-.. code-block:: c
-
- typedef enum {
- VIDEO_SOURCE_DEMUX, /* Select the demux as the main source */
- VIDEO_SOURCE_MEMORY /* If this source is selected, the stream
- comes from the user through the write
- system call */
- } video_stream_source_t;
-
-VIDEO_SOURCE_DEMUX selects the demultiplexer (fed either by the
-frontend or the DVR device) as the source of the video stream. If
-VIDEO_SOURCE_MEMORY is selected the stream comes from the application
-through the **write()** system call.
-
-
-.. _video-play-state-t:
-
-video_play_state_t
-==================
-
-The following values can be returned by the VIDEO_GET_STATUS call
-representing the state of video playback.
-
-
-.. code-block:: c
-
- typedef enum {
- VIDEO_STOPPED, /* Video is stopped */
- VIDEO_PLAYING, /* Video is currently playing */
- VIDEO_FREEZED /* Video is freezed */
- } video_play_state_t;
-
-
-.. _video-command:
-
-struct video_command
-====================
-
-The structure must be zeroed before use by the application This ensures
-it can be extended safely in the future.
-
-
-.. code-block:: c
-
- struct video_command {
- __u32 cmd;
- __u32 flags;
- union {
- struct {
- __u64 pts;
- } stop;
-
- struct {
- /* 0 or 1000 specifies normal speed,
- 1 specifies forward single stepping,
- -1 specifies backward single stepping,
- >>1: playback at speed/1000 of the normal speed,
- <-1: reverse playback at (-speed/1000) of the normal speed. */
- __s32 speed;
- __u32 format;
- } play;
-
- struct {
- __u32 data[16];
- } raw;
- };
- };
-
-
-.. _video-size-t:
-
-video_size_t
-============
-
-
-.. code-block:: c
-
- typedef struct {
- int w;
- int h;
- video_format_t aspect_ratio;
- } video_size_t;
-
-
-.. _video-event:
-
-struct video_event
-==================
-
-The following is the structure of a video event as it is returned by the
-VIDEO_GET_EVENT call.
-
-
-.. code-block:: c
-
- struct video_event {
- __s32 type;
- #define VIDEO_EVENT_SIZE_CHANGED 1
- #define VIDEO_EVENT_FRAME_RATE_CHANGED 2
- #define VIDEO_EVENT_DECODER_STOPPED 3
- #define VIDEO_EVENT_VSYNC 4
- __kernel_time_t timestamp;
- union {
- video_size_t size;
- unsigned int frame_rate; /* in frames per 1000sec */
- unsigned char vsync_field; /* unknown/odd/even/progressive */
- } u;
- };
-
-
-.. _video-status:
-
-struct video_status
-===================
-
-The VIDEO_GET_STATUS call returns the following structure informing
-about various states of the playback operation.
-
-
-.. code-block:: c
-
- struct video_status {
- int video_blank; /* blank video on freeze? */
- video_play_state_t play_state; /* current state of playback */
- video_stream_source_t stream_source; /* current source (demux/memory) */
- video_format_t video_format; /* current aspect ratio of stream */
- video_displayformat_t display_format;/* selected cropping mode */
- };
-
-If video_blank is set video will be blanked out if the channel is
-changed or if playback is stopped. Otherwise, the last picture will be
-displayed. play_state indicates if the video is currently frozen,
-stopped, or being played back. The stream_source corresponds to the
-seleted source for the video stream. It can come either from the
-demultiplexer or from memory. The video_format indicates the aspect
-ratio (one of 4:3 or 16:9) of the currently played video stream.
-Finally, display_format corresponds to the selected cropping mode in
-case the source video format is not the same as the format of the output
-device.
-
-
-.. _video-still-picture:
-
-struct video_still_picture
-==========================
-
-An I-frame displayed via the VIDEO_STILLPICTURE call is passed on
-within the following structure.
-
-
-.. code-block:: c
-
- /* pointer to and size of a single iframe in memory */
- struct video_still_picture {
- char *iFrame; /* pointer to a single iframe in memory */
- int32_t size;
- };
-
-
-.. _video_caps:
-
-video capabilities
-==================
-
-A call to VIDEO_GET_CAPABILITIES returns an unsigned integer with the
-following bits set according to the hardwares capabilities.
-
-
-.. code-block:: c
-
- /* bit definitions for capabilities: */
- /* can the hardware decode MPEG1 and/or MPEG2? */
- #define VIDEO_CAP_MPEG1 1
- #define VIDEO_CAP_MPEG2 2
- /* can you send a system and/or program stream to video device?
- (you still have to open the video and the audio device but only
- send the stream to the video device) */
- #define VIDEO_CAP_SYS 4
- #define VIDEO_CAP_PROG 8
- /* can the driver also handle SPU, NAVI and CSS encoded data?
- (CSS API is not present yet) */
- #define VIDEO_CAP_SPU 16
- #define VIDEO_CAP_NAVI 32
- #define VIDEO_CAP_CSS 64
-
-
-.. _video-system:
-
-video_system_t
-==============
-
-A call to VIDEO_SET_SYSTEM sets the desired video system for TV
-output. The following system types can be set:
-
-
-.. code-block:: c
-
- typedef enum {
- VIDEO_SYSTEM_PAL,
- VIDEO_SYSTEM_NTSC,
- VIDEO_SYSTEM_PALN,
- VIDEO_SYSTEM_PALNc,
- VIDEO_SYSTEM_PALM,
- VIDEO_SYSTEM_NTSC60,
- VIDEO_SYSTEM_PAL60,
- VIDEO_SYSTEM_PALM60
- } video_system_t;
-
-
-.. _video-highlight:
-
-struct video_highlight
-======================
-
-Calling the ioctl VIDEO_SET_HIGHLIGHTS posts the SPU highlight
-information. The call expects the following format for that information:
-
-
-.. code-block:: c
-
- typedef
- struct video_highlight {
- boolean active; /* 1=show highlight, 0=hide highlight */
- uint8_t contrast1; /* 7- 4 Pattern pixel contrast */
- /* 3- 0 Background pixel contrast */
- uint8_t contrast2; /* 7- 4 Emphasis pixel-2 contrast */
- /* 3- 0 Emphasis pixel-1 contrast */
- uint8_t color1; /* 7- 4 Pattern pixel color */
- /* 3- 0 Background pixel color */
- uint8_t color2; /* 7- 4 Emphasis pixel-2 color */
- /* 3- 0 Emphasis pixel-1 color */
- uint32_t ypos; /* 23-22 auto action mode */
- /* 21-12 start y */
- /* 9- 0 end y */
- uint32_t xpos; /* 23-22 button color number */
- /* 21-12 start x */
- /* 9- 0 end x */
- } video_highlight_t;
-
-
-.. _video-spu:
-
-struct video_spu
-================
-
-Calling VIDEO_SET_SPU deactivates or activates SPU decoding, according
-to the following format:
-
-
-.. code-block:: c
-
- typedef
- struct video_spu {
- boolean active;
- int stream_id;
- } video_spu_t;
-
-
-.. _video-spu-palette:
-
-struct video_spu_palette
-========================
-
-The following structure is used to set the SPU palette by calling
-VIDEO_SPU_PALETTE:
-
-
-.. code-block:: c
-
- typedef
- struct video_spu_palette {
- int length;
- uint8_t *palette;
- } video_spu_palette_t;
-
-
-.. _video-navi-pack:
-
-struct video_navi_pack
-======================
-
-In order to get the navigational data the following structure has to be
-passed to the ioctl VIDEO_GET_NAVI:
-
-
-.. code-block:: c
-
- typedef
- struct video_navi_pack {
- int length; /* 0 ... 1024 */
- uint8_t data[1024];
- } video_navi_pack_t;
-
-
-.. _video-attributes-t:
-
-video_attributes_t
-==================
-
-The following attributes can be set by a call to VIDEO_SET_ATTRIBUTES:
-
-
-.. code-block:: c
-
- typedef uint16_t video_attributes_t;
- /* bits: descr. */
- /* 15-14 Video compression mode (0=MPEG-1, 1=MPEG-2) */
- /* 13-12 TV system (0=525/60, 1=625/50) */
- /* 11-10 Aspect ratio (0=4:3, 3=16:9) */
- /* 9- 8 permitted display mode on 4:3 monitor (0=both, 1=only pan-sca */
- /* 7 line 21-1 data present in GOP (1=yes, 0=no) */
- /* 6 line 21-2 data present in GOP (1=yes, 0=no) */
- /* 5- 3 source resolution (0=720x480/576, 1=704x480/576, 2=352x480/57 */
- /* 2 source letterboxed (1=yes, 0=no) */
- /* 0 film/camera mode (0=camera, 1=film (625/50 only)) */
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _fdl:
-
-******************************
-GNU Free Documentation License
-******************************
-
-
-.. _fdl-preamble:
-
-0. PREAMBLE
-===========
-
-The purpose of this License is to make a manual, textbook, or other
-written document “free” in the sense of freedom: to assure everyone the
-effective freedom to copy and redistribute it, with or without modifying
-it, either commercially or noncommercially. Secondarily, this License
-preserves for the author and publisher a way to get credit for their
-work, while not being considered responsible for modifications made by
-others.
-
-This License is a kind of “copyleft”, which means that derivative works
-of the document must themselves be free in the same sense. It
-complements the GNU General Public License, which is a copyleft license
-designed for free software.
-
-We have designed this License in order to use it for manuals for free
-software, because free software needs free documentation: a free program
-should come with manuals providing the same freedoms that the software
-does. But this License is not limited to software manuals; it can be
-used for any textual work, regardless of subject matter or whether it is
-published as a printed book. We recommend this License principally for
-works whose purpose is instruction or reference.
-
-
-.. _fdl-section1:
-
-1. APPLICABILITY AND DEFINITIONS
-================================
-
-
-.. _fdl-document:
-
-This License applies to any manual or other work that contains a notice
-placed by the copyright holder saying it can be distributed under the
-terms of this License. The “Document”, below, refers to any such manual
-or work. Any member of the public is a licensee, and is addressed as
-“you”.
-
-
-.. _fdl-modified:
-
-A “Modified Version” of the Document means any work containing the
-Document or a portion of it, either copied verbatim, or with
-modifications and/or translated into another language.
-
-
-.. _fdl-secondary:
-
-A “Secondary Section” is a named appendix or a front-matter section of
-the :ref:`Document <fdl-document>` that deals exclusively with the
-relationship of the publishers or authors of the Document to the
-Document's overall subject (or to related matters) and contains nothing
-that could fall directly within that overall subject. (For example, if
-the Document is in part a textbook of mathematics, a Secondary Section
-may not explain any mathematics.) The relationship could be a matter of
-historical connection with the subject or with related matters, or of
-legal, commercial, philosophical, ethical or political position
-regarding them.
-
-
-.. _fdl-invariant:
-
-The “Invariant Sections” are certain
-:ref:`Secondary Sections <fdl-secondary>` whose titles are designated,
-as being those of Invariant Sections, in the notice that says that the
-:ref:`Document <fdl-document>` is released under this License.
-
-
-.. _fdl-cover-texts:
-
-The “Cover Texts” are certain short passages of text that are listed, as
-Front-Cover Texts or Back-Cover Texts, in the notice that says that the
-:ref:`Document <fdl-document>` is released under this License.
-
-
-.. _fdl-transparent:
-
-A “Transparent” copy of the :ref:`Document <fdl-document>` means a
-machine-readable copy, represented in a format whose specification is
-available to the general public, whose contents can be viewed and edited
-directly and straightforwardly with generic text editors or (for images
-composed of pixels) generic paint programs or (for drawings) some widely
-available drawing editor, and that is suitable for input to text
-formatters or for automatic translation to a variety of formats suitable
-for input to text formatters. A copy made in an otherwise Transparent
-file format whose markup has been designed to thwart or discourage
-subsequent modification by readers is not Transparent. A copy that is
-not “Transparent” is called “Opaque”.
-
-Examples of suitable formats for Transparent copies include plain ASCII
-without markup, Texinfo input format, LaTeX input format, SGML or XML
-using a publicly available DTD, and standard-conforming simple HTML
-designed for human modification. Opaque formats include PostScript, PDF,
-proprietary formats that can be read and edited only by proprietary word
-processors, SGML or XML for which the DTD and/or processing tools are
-not generally available, and the machine-generated HTML produced by some
-word processors for output purposes only.
-
-
-.. _fdl-title-page:
-
-The “Title Page” means, for a printed book, the title page itself, plus
-such following pages as are needed to hold, legibly, the material this
-License requires to appear in the title page. For works in formats which
-do not have any title page as such, “Title Page” means the text near the
-most prominent appearance of the work's title, preceding the beginning
-of the body of the text.
-
-
-.. _fdl-section2:
-
-2. VERBATIM COPYING
-===================
-
-You may copy and distribute the :ref:`Document <fdl-document>` in any
-medium, either commercially or noncommercially, provided that this
-License, the copyright notices, and the license notice saying this
-License applies to the Document are reproduced in all copies, and that
-you add no other conditions whatsoever to those of this License. You may
-not use technical measures to obstruct or control the reading or further
-copying of the copies you make or distribute. However, you may accept
-compensation in exchange for copies. If you distribute a large enough
-number of copies you must also follow the conditions in
-:ref:`section 3 <fdl-section3>`.
-
-You may also lend copies, under the same conditions stated above, and
-you may publicly display copies.
-
-
-.. _fdl-section3:
-
-3. COPYING IN QUANTITY
-======================
-
-If you publish printed copies of the :ref:`Document <fdl-document>`
-numbering more than 100, and the Document's license notice requires
-:ref:`Cover Texts <fdl-cover-texts>`, you must enclose the copies in
-covers that carry, clearly and legibly, all these Cover Texts:
-Front-Cover Texts on the front cover, and Back-Cover Texts on the back
-cover. Both covers must also clearly and legibly identify you as the
-publisher of these copies. The front cover must present the full title
-with all words of the title equally prominent and visible. You may add
-other material on the covers in addition. Copying with changes limited
-to the covers, as long as they preserve the title of the
-:ref:`Document <fdl-document>` and satisfy these conditions, can be
-treated as verbatim copying in other respects.
-
-If the required texts for either cover are too voluminous to fit
-legibly, you should put the first ones listed (as many as fit
-reasonably) on the actual cover, and continue the rest onto adjacent
-pages.
-
-If you publish or distribute :ref:`Opaque <fdl-transparent>` copies of
-the :ref:`Document <fdl-document>` numbering more than 100, you must
-either include a machine-readable :ref:`Transparent <fdl-transparent>`
-copy along with each Opaque copy, or state in or with each Opaque copy a
-publicly-accessible computer-network location containing a complete
-Transparent copy of the Document, free of added material, which the
-general network-using public has access to download anonymously at no
-charge using public-standard network protocols. If you use the latter
-option, you must take reasonably prudent steps, when you begin
-distribution of Opaque copies in quantity, to ensure that this
-Transparent copy will remain thus accessible at the stated location
-until at least one year after the last time you distribute an Opaque
-copy (directly or through your agents or retailers) of that edition to
-the public.
-
-It is requested, but not required, that you contact the authors of the
-:ref:`Document <fdl-document>` well before redistributing any large
-number of copies, to give them a chance to provide you with an updated
-version of the Document.
-
-
-.. _fdl-section4:
-
-4. MODIFICATIONS
-================
-
-You may copy and distribute a :ref:`Modified Version <fdl-modified>`
-of the :ref:`Document <fdl-document>` under the conditions of sections
-:ref:`2 <fdl-section2>` and :ref:`3 <fdl-section3>` above, provided
-that you release the Modified Version under precisely this License, with
-the Modified Version filling the role of the Document, thus licensing
-distribution and modification of the Modified Version to whoever
-possesses a copy of it. In addition, you must do these things in the
-Modified Version:
-
-- **A.**
- Use in the :ref:`Title Page <fdl-title-page>` (and on the covers,
- if any) a title distinct from that of the
- :ref:`Document <fdl-document>`, and from those of previous versions
- (which should, if there were any, be listed in the History section of
- the Document). You may use the same title as a previous version if
- the original publisher of that version gives permission.
-
-- **B.**
- List on the :ref:`Title Page <fdl-title-page>`, as authors, one or
- more persons or entities responsible for authorship of the
- modifications in the :ref:`Modified Version <fdl-modified>`,
- together with at least five of the principal authors of the
- :ref:`Document <fdl-document>` (all of its principal authors, if it
- has less than five).
-
-- **C.**
- State on the :ref:`Title Page <fdl-title-page>` the name of the
- publisher of the :ref:`Modified Version <fdl-modified>`, as the
- publisher.
-
-- **D.**
- Preserve all the copyright notices of the
- :ref:`Document <fdl-document>`.
-
-- **E.**
- Add an appropriate copyright notice for your modifications adjacent
- to the other copyright notices.
-
-- **F.**
- Include, immediately after the copyright notices, a license notice
- giving the public permission to use the
- :ref:`Modified Version <fdl-modified>` under the terms of this
- License, in the form shown in the Addendum below.
-
-- **G.**
- Preserve in that license notice the full lists of
- :ref:`Invariant Sections <fdl-invariant>` and required
- :ref:`Cover Texts <fdl-cover-texts>` given in the
- :ref:`Document's <fdl-document>` license notice.
-
-- **H.**
- Include an unaltered copy of this License.
-
-- **I.**
- Preserve the section entitled “History”, and its title, and add to it
- an item stating at least the title, year, new authors, and publisher
- of the :ref:`Modified Version <fdl-modified>` as given on the
- :ref:`Title Page <fdl-title-page>`. If there is no section entitled
- “History” in the :ref:`Document <fdl-document>`, create one stating
- the title, year, authors, and publisher of the Document as given on
- its Title Page, then add an item describing the Modified Version as
- stated in the previous sentence.
-
-- **J.**
- Preserve the network location, if any, given in the
- :ref:`Document <fdl-document>` for public access to a
- :ref:`Transparent <fdl-transparent>` copy of the Document, and
- likewise the network locations given in the Document for previous
- versions it was based on. These may be placed in the “History”
- section. You may omit a network location for a work that was
- published at least four years before the Document itself, or if the
- original publisher of the version it refers to gives permission.
-
-- **K.**
- In any section entitled “Acknowledgements” or “Dedications”, preserve
- the section's title, and preserve in the section all the substance
- and tone of each of the contributor acknowledgements and/or
- dedications given therein.
-
-- **L.**
- Preserve all the :ref:`Invariant Sections <fdl-invariant>` of the
- :ref:`Document <fdl-document>`, unaltered in their text and in
- their titles. Section numbers or the equivalent are not considered
- part of the section titles.
-
-- **M.**
- Delete any section entitled “Endorsements”. Such a section may not be
- included in the :ref:`Modified Version <fdl-modified>`.
-
-- **N.**
- Do not retitle any existing section as “Endorsements” or to conflict
- in title with any :ref:`Invariant Section <fdl-invariant>`.
-
-If the :ref:`Modified Version <fdl-modified>` includes new
-front-matter sections or appendices that qualify as
-:ref:`Secondary Sections <fdl-secondary>` and contain no material
-copied from the Document, you may at your option designate some or all
-of these sections as invariant. To do this, add their titles to the list
-of :ref:`Invariant Sections <fdl-invariant>` in the Modified Version's
-license notice. These titles must be distinct from any other section
-titles.
-
-You may add a section entitled “Endorsements”, provided it contains
-nothing but endorsements of your
-:ref:`Modified Version <fdl-modified>` by various parties--for
-example, statements of peer review or that the text has been approved by
-an organization as the authoritative definition of a standard.
-
-You may add a passage of up to five words as a
-:ref:`Front-Cover Text <fdl-cover-texts>`, and a passage of up to 25
-words as a :ref:`Back-Cover Text <fdl-cover-texts>`, to the end of the
-list of :ref:`Cover Texts <fdl-cover-texts>` in the
-:ref:`Modified Version <fdl-modified>`. Only one passage of
-Front-Cover Text and one of Back-Cover Text may be added by (or through
-arrangements made by) any one entity. If the
-:ref:`Document <fdl-document>` already includes a cover text for the
-same cover, previously added by you or by arrangement made by the same
-entity you are acting on behalf of, you may not add another; but you may
-replace the old one, on explicit permission from the previous publisher
-that added the old one.
-
-The author(s) and publisher(s) of the :ref:`Document <fdl-document>`
-do not by this License give permission to use their names for publicity
-for or to assert or imply endorsement of any
-:ref:`Modified Version <fdl-modified>`.
-
-
-.. _fdl-section5:
-
-5. COMBINING DOCUMENTS
-======================
-
-You may combine the :ref:`Document <fdl-document>` with other
-documents released under this License, under the terms defined in
-:ref:`section 4 <fdl-section4>` above for modified versions, provided
-that you include in the combination all of the
-:ref:`Invariant Sections <fdl-invariant>` of all of the original
-documents, unmodified, and list them all as Invariant Sections of your
-combined work in its license notice.
-
-The combined work need only contain one copy of this License, and
-multiple identical :ref:`Invariant Sections <fdl-invariant>` may be
-replaced with a single copy. If there are multiple Invariant Sections
-with the same name but different contents, make the title of each such
-section unique by adding at the end of it, in parentheses, the name of
-the original author or publisher of that section if known, or else a
-unique number. Make the same adjustment to the section titles in the
-list of Invariant Sections in the license notice of the combined work.
-
-In the combination, you must combine any sections entitled “History” in
-the various original documents, forming one section entitled “History”;
-likewise combine any sections entitled “Acknowledgements”, and any
-sections entitled “Dedications”. You must delete all sections entitled
-“Endorsements.”
-
-
-.. _fdl-section6:
-
-6. COLLECTIONS OF DOCUMENTS
-===========================
-
-You may make a collection consisting of the
-:ref:`Document <fdl-document>` and other documents released under this
-License, and replace the individual copies of this License in the
-various documents with a single copy that is included in the collection,
-provided that you follow the rules of this License for verbatim copying
-of each of the documents in all other respects.
-
-You may extract a single document from such a collection, and dispbibute
-it individually under this License, provided you insert a copy of this
-License into the extracted document, and follow this License in all
-other respects regarding verbatim copying of that document.
-
-
-.. _fdl-section7:
-
-7. AGGREGATION WITH INDEPENDENT WORKS
-=====================================
-
-A compilation of the :ref:`Document <fdl-document>` or its derivatives
-with other separate and independent documents or works, in or on a
-volume of a storage or distribution medium, does not as a whole count as
-a :ref:`Modified Version <fdl-modified>` of the Document, provided no
-compilation copyright is claimed for the compilation. Such a compilation
-is called an “aggregate”, and this License does not apply to the other
-self-contained works thus compiled with the Document , on account of
-their being thus compiled, if they are not themselves derivative works
-of the Document. If the :ref:`Cover Text <fdl-cover-texts>`
-requirement of :ref:`section 3 <fdl-section3>` is applicable to these
-copies of the Document, then if the Document is less than one quarter of
-the entire aggregate, the Document's Cover Texts may be placed on covers
-that surround only the Document within the aggregate. Otherwise they
-must appear on covers around the whole aggregate.
-
-
-.. _fdl-section8:
-
-8. TRANSLATION
-==============
-
-Translation is considered a kind of modification, so you may distribute
-translations of the :ref:`Document <fdl-document>` under the terms of
-:ref:`section 4 <fdl-section4>`. Replacing
-:ref:`Invariant Sections <fdl-invariant>` with translations requires
-special permission from their copyright holders, but you may include
-translations of some or all Invariant Sections in addition to the
-original versions of these Invariant Sections. You may include a
-translation of this License provided that you also include the original
-English version of this License. In case of a disagreement between the
-translation and the original English version of this License, the
-original English version will prevail.
-
-
-.. _fdl-section9:
-
-9. TERMINATION
-==============
-
-You may not copy, modify, sublicense, or distribute the
-:ref:`Document <fdl-document>` except as expressly provided for under
-this License. Any other attempt to copy, modify, sublicense or
-distribute the Document is void, and will automatically terminate your
-rights under this License. However, parties who have received copies, or
-rights, from you under this License will not have their licenses
-terminated so long as such parties remain in full compliance.
-
-
-.. _fdl-section10:
-
-10. FUTURE REVISIONS OF THIS LICENSE
-====================================
-
-The `Free Software Foundation <http://www.gnu.org/fsf/fsf.html>`__
-may publish new, revised versions of the GNU Free Documentation License
-from time to time. Such new versions will be similar in spirit to the
-present version, but may differ in detail to address new problems or
-concerns. See
-`http://www.gnu.org/copyleft/ <http://www.gnu.org/copyleft>`__.
-
-Each version of the License is given a distinguishing version number. If
-the :ref:`Document <fdl-document>` specifies that a particular
-numbered version of this License “or any later version” applies to it,
-you have the option of following the terms and conditions either of that
-specified version or of any later version that has been published (not
-as a draft) by the Free Software Foundation. If the Document does not
-specify a version number of this License, you may choose any version
-ever published (not as a draft) by the Free Software Foundation.
-
-
-.. _fdl-using:
-
-Addendum
-========
-
-To use this License in a document you have written, include a copy of
-the License in the document and put the following copyright and license
-notices just after the title page:
-
- Copyright © YEAR YOUR NAME.
-
- 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 the :ref:`Invariant Sections <fdl-invariant>`
- being LIST THEIR TITLES, with the
- :ref:`Front-Cover Texts <fdl-cover-texts>` being LIST, and with
- the :ref:`Back-Cover Texts <fdl-cover-texts>` being LIST. A copy
- of the license is included in the section entitled “GNU Free
- Documentation License”.
-
-If you have no :ref:`Invariant Sections <fdl-invariant>`, write “with
-no Invariant Sections” instead of saying which ones are invariant. If
-you have no :ref:`Front-Cover Texts <fdl-cover-texts>`, write “no
-Front-Cover Texts” instead of “Front-Cover Texts being LIST”; likewise
-for :ref:`Back-Cover Texts <fdl-cover-texts>`.
-
-If your document contains nontrivial examples of program code, we
-recommend releasing these examples in parallel under your choice of free
-software license, such as the
-`GNU General Public License <http://www.gnu.org/copyleft/gpl.html>`__,
-to permit their use in free software.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _gen_errors:
-
-*******************
-Generic Error Codes
-*******************
-
-
-.. _gen-errors:
-
-.. flat-table:: Generic error codes
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 16
-
-
- - .. row 1
-
- - ``EAGAIN`` (aka ``EWOULDBLOCK``)
-
- - The ioctl can't be handled because the device is in state where it
- can't perform it. This could happen for example in case where
- device is sleeping and ioctl is performed to query statistics. It
- is also returned when the ioctl would need to wait for an event,
- but the device was opened in non-blocking mode.
-
- - .. row 2
-
- - ``EBADF``
-
- - The file descriptor is not a valid.
-
- - .. row 3
-
- - ``EBUSY``
-
- - The ioctl can't be handled because the device is busy. This is
- typically return while device is streaming, and an ioctl tried to
- change something that would affect the stream, or would require
- the usage of a hardware resource that was already allocated. The
- ioctl must not be retried without performing another action to fix
- the problem first (typically: stop the stream before retrying).
-
- - .. row 4
-
- - ``EFAULT``
-
- - There was a failure while copying data from/to userspace, probably
- caused by an invalid pointer reference.
-
- - .. row 5
-
- - ``EINVAL``
-
- - One or more of the ioctl parameters are invalid or out of the
- allowed range. This is a widely used error code. See the
- individual ioctl requests for specific causes.
-
- - .. row 6
-
- - ``ENODEV``
-
- - Device not found or was removed.
-
- - .. row 7
-
- - ``ENOMEM``
-
- - There's not enough memory to handle the desired operation.
-
- - .. row 8
-
- - ``ENOTTY``
-
- - The ioctl is not supported by the driver, actually meaning that
- the required functionality is not available, or the file
- descriptor is not for a media device.
-
- - .. row 9
-
- - ``ENOSPC``
-
- - On USB devices, the stream ioctl's can return this error, meaning
- that this request would overcommit the usb bandwidth reserved for
- periodic transfers (up to 80% of the USB bandwidth).
-
- - .. row 10
-
- - ``EPERM``
-
- - Permission denied. Can be returned if the device needs write
- permission, or some special capabilities is needed (e. g. root)
-
-
-Note 1: ioctls may return other error codes. Since errors may have side
-effects such as a driver reset, applications should abort on unexpected
-errors.
-
-Note 2: Request-specific error codes are listed in the individual
-requests descriptions.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _media-controller-intro:
-
-Introduction
-============
-
-Media devices increasingly handle multiple related functions. Many USB
-cameras include microphones, video capture hardware can also output
-video, or SoC camera interfaces also perform memory-to-memory operations
-similar to video codecs.
-
-Independent functions, even when implemented in the same hardware, can
-be modelled as separate devices. A USB camera with a microphone will be
-presented to userspace applications as V4L2 and ALSA capture devices.
-The devices' relationships (when using a webcam, end-users shouldn't
-have to manually select the associated USB microphone), while not made
-available directly to applications by the drivers, can usually be
-retrieved from sysfs.
-
-With more and more advanced SoC devices being introduced, the current
-approach will not scale. Device topologies are getting increasingly
-complex and can't always be represented by a tree structure. Hardware
-blocks are shared between different functions, creating dependencies
-between seemingly unrelated devices.
-
-Kernel abstraction APIs such as V4L2 and ALSA provide means for
-applications to access hardware parameters. As newer hardware expose an
-increasingly high number of those parameters, drivers need to guess what
-applications really require based on limited information, thereby
-implementing policies that belong to userspace.
-
-The media controller API aims at solving those problems.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _media-controller-model:
-
-Media device model
-==================
-
-Discovering a device internal topology, and configuring it at runtime,
-is one of the goals of the media controller API. To achieve this,
-hardware devices and Linux Kernel interfaces are modelled as graph
-objects on an oriented graph. The object types that constitute the graph
-are:
-
-- An **entity** is a basic media hardware or software building block.
- It can correspond to a large variety of logical blocks such as
- physical hardware devices (CMOS sensor for instance), logical
- hardware devices (a building block in a System-on-Chip image
- processing pipeline), DMA channels or physical connectors.
-
-- An **interface** is a graph representation of a Linux Kernel
- userspace API interface, like a device node or a sysfs file that
- controls one or more entities in the graph.
-
-- A **pad** is a data connection endpoint through which an entity can
- interact with other entities. Data (not restricted to video) produced
- by an entity flows from the entity's output to one or more entity
- inputs. Pads should not be confused with physical pins at chip
- boundaries.
-
-- A **data link** is a point-to-point oriented connection between two
- pads, either on the same entity or on different entities. Data flows
- from a source pad to a sink pad.
-
-- An **interface link** is a point-to-point bidirectional control
- connection between a Linux Kernel interface and an entity.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. include:: <isonum.txt>
-
-.. _media_common:
-
-####################
-Media Controller API
-####################
-
-.. _media_controller:
-
-****************
-Media Controller
-****************
-
-
-.. toctree::
- :maxdepth: 1
- :numbered:
-
- media-controller-intro
- media-controller-model
- media-types
-
-
-.. _media-user-func:
-
-******************
-Function Reference
-******************
-
-
-.. toctree::
- :maxdepth: 1
-
- media-func-open
- media-func-close
- media-func-ioctl
- media-ioc-device-info
- media-ioc-g-topology
- media-ioc-enum-entities
- media-ioc-enum-links
- media-ioc-setup-link
-
-
-**********************
-Revision and Copyright
-**********************
-
-Authors:
-
-- Pinchart, Laurent <laurent.pinchart@ideasonboard.com>
-
- - Initial version.
-
-- Carvalho Chehab, Mauro <mchehab@kernel.org>
-
- - MEDIA_IOC_G_TOPOLOGY documentation and documentation improvements.
-
-**Copyright** |copy| 2010 : Laurent Pinchart
-
-**Copyright** |copy| 2015-2016 : Mauro Carvalho Chehab
-
-****************
-Revision History
-****************
-
-:revision: 1.1.0 / 2015-12-12 (*mcc*)
-
-:revision: 1.0.0 / 2010-11-10 (*lp*)
-
-Initial revision
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _media-func-close:
-
-*************
-media close()
-*************
-
-Name
-====
-
-media-close - Close a media device
-
-
-Synopsis
-========
-
-.. code-block:: c
-
- #include <unistd.h>
-
-
-.. cpp:function:: int close( int fd )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-
-Description
-===========
-
-Closes the media device. Resources associated with the file descriptor
-are freed. The device configuration remain unchanged.
-
-
-Return Value
-============
-
-:ref:`close() <media-func-close>` returns 0 on success. On error, -1 is returned, and
-``errno`` is set appropriately. Possible error codes are:
-
-EBADF
- ``fd`` is not a valid open file descriptor.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _media-func-ioctl:
-
-*************
-media ioctl()
-*************
-
-Name
-====
-
-media-ioctl - Control a media device
-
-
-Synopsis
-========
-
-.. code-block:: c
-
- #include <sys/ioctl.h>
-
-
-.. cpp:function:: int ioctl( int fd, int request, void *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- Media ioctl request code as defined in the media.h header file, for
- example MEDIA_IOC_SETUP_LINK.
-
-``argp``
- Pointer to a request-specific structure.
-
-
-Description
-===========
-
-The :ref:`ioctl() <media-func-ioctl>` function manipulates media device
-parameters. The argument ``fd`` must be an open file descriptor.
-
-The ioctl ``request`` code specifies the media function to be called. It
-has encoded in it whether the argument is an input, output or read/write
-parameter, and the size of the argument ``argp`` in bytes.
-
-Macros and structures definitions specifying media ioctl requests and
-their parameters are located in the media.h header file. All media ioctl
-requests, their respective function and parameters are specified in
-:ref:`media-user-func`.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-Request-specific error codes are listed in the individual requests
-descriptions.
-
-When an ioctl that takes an output or read/write parameter fails, the
-parameter remains unmodified.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _media-func-open:
-
-************
-media open()
-************
-
-Name
-====
-
-media-open - Open a media device
-
-
-Synopsis
-========
-
-.. code-block:: c
-
- #include <fcntl.h>
-
-
-.. cpp:function:: int open( const char *device_name, int flags )
-
-
-Arguments
-=========
-
-``device_name``
- Device to be opened.
-
-``flags``
- Open flags. Access mode must be either ``O_RDONLY`` or ``O_RDWR``.
- Other flags have no effect.
-
-
-Description
-===========
-
-To open a media device applications call :ref:`open() <media-func-open>` with the
-desired device name. The function has no side effects; the device
-configuration remain unchanged.
-
-When the device is opened in read-only mode, attempts to modify its
-configuration will result in an error, and ``errno`` will be set to
-EBADF.
-
-
-Return Value
-============
-
-:ref:`open() <func-open>` returns the new file descriptor on success. On error,
--1 is returned, and ``errno`` is set appropriately. Possible error codes
-are:
-
-EACCES
- The requested access to the file is not allowed.
-
-EMFILE
- The process already has the maximum number of files open.
-
-ENFILE
- The system limit on the total number of open files has been reached.
-
-ENOMEM
- Insufficient kernel memory was available.
-
-ENXIO
- No device corresponding to this device special file exists.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _media-ioc-device-info:
-
-***************************
-ioctl MEDIA_IOC_DEVICE_INFO
-***************************
-
-Name
-====
-
-MEDIA_IOC_DEVICE_INFO - Query device information
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct media_device_info *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <media-func-open>`.
-
-``request``
- MEDIA_IOC_DEVICE_INFO
-
-``argp``
-
-
-Description
-===========
-
-All media devices must support the ``MEDIA_IOC_DEVICE_INFO`` ioctl. To
-query device information, applications call the ioctl with a pointer to
-a struct :ref:`media_device_info <media-device-info>`. The driver
-fills the structure and returns the information to the application. The
-ioctl never fails.
-
-
-.. _media-device-info:
-
-.. flat-table:: struct media_device_info
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - char
-
- - ``driver``\ [16]
-
- - Name of the driver implementing the media API as a NUL-terminated
- ASCII string. The driver version is stored in the
- ``driver_version`` field.
-
- Driver specific applications can use this information to verify
- the driver identity. It is also useful to work around known bugs,
- or to identify drivers in error reports.
-
- - .. row 2
-
- - char
-
- - ``model``\ [32]
-
- - Device model name as a NUL-terminated UTF-8 string. The device
- version is stored in the ``device_version`` field and is not be
- appended to the model name.
-
- - .. row 3
-
- - char
-
- - ``serial``\ [40]
-
- - Serial number as a NUL-terminated ASCII string.
-
- - .. row 4
-
- - char
-
- - ``bus_info``\ [32]
-
- - Location of the device in the system as a NUL-terminated ASCII
- string. This includes the bus type name (PCI, USB, ...) and a
- bus-specific identifier.
-
- - .. row 5
-
- - __u32
-
- - ``media_version``
-
- - Media API version, formatted with the ``KERNEL_VERSION()`` macro.
-
- - .. row 6
-
- - __u32
-
- - ``hw_revision``
-
- - Hardware device revision in a driver-specific format.
-
- - .. row 7
-
- - __u32
-
- - ``driver_version``
-
- - Media device driver version, formatted with the
- ``KERNEL_VERSION()`` macro. Together with the ``driver`` field
- this identifies a particular driver.
-
- - .. row 8
-
- - __u32
-
- - ``reserved``\ [31]
-
- - Reserved for future extensions. Drivers and applications must set
- this array to zero.
-
-
-The ``serial`` and ``bus_info`` fields can be used to distinguish
-between multiple instances of otherwise identical hardware. The serial
-number takes precedence when provided and can be assumed to be unique.
-If the serial number is an empty string, the ``bus_info`` field can be
-used instead. The ``bus_info`` field is guaranteed to be unique, but can
-vary across reboots or device unplug/replug.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _media-ioc-enum-entities:
-
-*****************************
-ioctl MEDIA_IOC_ENUM_ENTITIES
-*****************************
-
-Name
-====
-
-MEDIA_IOC_ENUM_ENTITIES - Enumerate entities and their properties
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct media_entity_desc *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <media-func-open>`.
-
-``request``
- MEDIA_IOC_ENUM_ENTITIES
-
-``argp``
-
-
-Description
-===========
-
-To query the attributes of an entity, applications set the id field of a
-struct :ref:`media_entity_desc <media-entity-desc>` structure and
-call the MEDIA_IOC_ENUM_ENTITIES ioctl with a pointer to this
-structure. The driver fills the rest of the structure or returns an
-EINVAL error code when the id is invalid.
-
-Entities can be enumerated by or'ing the id with the
-``MEDIA_ENT_ID_FLAG_NEXT`` flag. The driver will return information
-about the entity with the smallest id strictly larger than the requested
-one ('next entity'), or the ``EINVAL`` error code if there is none.
-
-Entity IDs can be non-contiguous. Applications must *not* try to
-enumerate entities by calling MEDIA_IOC_ENUM_ENTITIES with increasing
-id's until they get an error.
-
-
-.. _media-entity-desc:
-
-.. flat-table:: struct media_entity_desc
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 1 1 8
-
-
- - .. row 1
-
- - __u32
-
- - ``id``
-
- -
- -
- - Entity id, set by the application. When the id is or'ed with
- ``MEDIA_ENT_ID_FLAG_NEXT``, the driver clears the flag and returns
- the first entity with a larger id.
-
- - .. row 2
-
- - char
-
- - ``name``\ [32]
-
- -
- -
- - Entity name as an UTF-8 NULL-terminated string.
-
- - .. row 3
-
- - __u32
-
- - ``type``
-
- -
- -
- - Entity type, see :ref:`media-entity-type` for details.
-
- - .. row 4
-
- - __u32
-
- - ``revision``
-
- -
- -
- - Entity revision. Always zero (obsolete)
-
- - .. row 5
-
- - __u32
-
- - ``flags``
-
- -
- -
- - Entity flags, see :ref:`media-entity-flag` for details.
-
- - .. row 6
-
- - __u32
-
- - ``group_id``
-
- -
- -
- - Entity group ID. Always zero (obsolete)
-
- - .. row 7
-
- - __u16
-
- - ``pads``
-
- -
- -
- - Number of pads
-
- - .. row 8
-
- - __u16
-
- - ``links``
-
- -
- -
- - Total number of outbound links. Inbound links are not counted in
- this field.
-
- - .. row 9
-
- - union
-
- - .. row 10
-
- -
- - struct
-
- - ``dev``
-
- -
- - Valid for (sub-)devices that create a single device node.
-
- - .. row 11
-
- -
- -
- - __u32
-
- - ``major``
-
- - Device node major number.
-
- - .. row 12
-
- -
- -
- - __u32
-
- - ``minor``
-
- - Device node minor number.
-
- - .. row 13
-
- -
- - __u8
-
- - ``raw``\ [184]
-
- -
- -
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EINVAL
- The struct :ref:`media_entity_desc <media-entity-desc>` ``id``
- references a non-existing entity.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _media-ioc-enum-links:
-
-**************************
-ioctl MEDIA_IOC_ENUM_LINKS
-**************************
-
-Name
-====
-
-MEDIA_IOC_ENUM_LINKS - Enumerate all pads and links for a given entity
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct media_links_enum *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <media-func-open>`.
-
-``request``
- MEDIA_IOC_ENUM_LINKS
-
-``argp``
-
-
-Description
-===========
-
-To enumerate pads and/or links for a given entity, applications set the
-entity field of a struct :ref:`media_links_enum <media-links-enum>`
-structure and initialize the struct
-:ref:`media_pad_desc <media-pad-desc>` and struct
-:ref:`media_link_desc <media-link-desc>` structure arrays pointed by
-the ``pads`` and ``links`` fields. They then call the
-MEDIA_IOC_ENUM_LINKS ioctl with a pointer to this structure.
-
-If the ``pads`` field is not NULL, the driver fills the ``pads`` array
-with information about the entity's pads. The array must have enough
-room to store all the entity's pads. The number of pads can be retrieved
-with the :ref:`MEDIA_IOC_ENUM_ENTITIES <media-ioc-enum-entities>`
-ioctl.
-
-If the ``links`` field is not NULL, the driver fills the ``links`` array
-with information about the entity's outbound links. The array must have
-enough room to store all the entity's outbound links. The number of
-outbound links can be retrieved with the
-:ref:`MEDIA_IOC_ENUM_ENTITIES <media-ioc-enum-entities>` ioctl.
-
-Only forward links that originate at one of the entity's source pads are
-returned during the enumeration process.
-
-
-.. _media-links-enum:
-
-.. flat-table:: struct media_links_enum
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``entity``
-
- - Entity id, set by the application.
-
- - .. row 2
-
- - struct :ref:`media_pad_desc <media-pad-desc>`
-
- - \*\ ``pads``
-
- - Pointer to a pads array allocated by the application. Ignored if
- NULL.
-
- - .. row 3
-
- - struct :ref:`media_link_desc <media-link-desc>`
-
- - \*\ ``links``
-
- - Pointer to a links array allocated by the application. Ignored if
- NULL.
-
-
-
-.. _media-pad-desc:
-
-.. flat-table:: struct media_pad_desc
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``entity``
-
- - ID of the entity this pad belongs to.
-
- - .. row 2
-
- - __u16
-
- - ``index``
-
- - 0-based pad index.
-
- - .. row 3
-
- - __u32
-
- - ``flags``
-
- - Pad flags, see :ref:`media-pad-flag` for more details.
-
-
-
-.. _media-link-desc:
-
-.. flat-table:: struct media_link_desc
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - struct :ref:`media_pad_desc <media-pad-desc>`
-
- - ``source``
-
- - Pad at the origin of this link.
-
- - .. row 2
-
- - struct :ref:`media_pad_desc <media-pad-desc>`
-
- - ``sink``
-
- - Pad at the target of this link.
-
- - .. row 3
-
- - __u32
-
- - ``flags``
-
- - Link flags, see :ref:`media-link-flag` for more details.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EINVAL
- The struct :ref:`media_links_enum <media-links-enum>` ``id``
- references a non-existing entity.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _media-g-topology:
-
-**************************
-ioctl MEDIA_IOC_G_TOPOLOGY
-**************************
-
-Name
-====
-
-MEDIA_IOC_G_TOPOLOGY - Enumerate the graph topology and graph element properties
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct media_v2_topology *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <media-func-open>`.
-
-``request``
- MEDIA_IOC_G_TOPOLOGY
-
-``argp``
-
-
-Description
-===========
-
-The typical usage of this ioctl is to call it twice. On the first call,
-the structure defined at struct
-:ref:`media_v2_topology <media-v2-topology>` should be zeroed. At
-return, if no errors happen, this ioctl will return the
-``topology_version`` and the total number of entities, interfaces, pads
-and links.
-
-Before the second call, the userspace should allocate arrays to store
-the graph elements that are desired, putting the pointers to them at the
-ptr_entities, ptr_interfaces, ptr_links and/or ptr_pads, keeping the
-other values untouched.
-
-If the ``topology_version`` remains the same, the ioctl should fill the
-desired arrays with the media graph elements.
-
-
-.. _media-v2-topology:
-
-.. flat-table:: struct media_v2_topology
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 2 8
-
-
- - .. row 1
-
- - __u64
-
- - ``topology_version``
-
- - Version of the media graph topology. When the graph is created,
- this field starts with zero. Every time a graph element is added
- or removed, this field is incremented.
-
- - .. row 2
-
- - __u64
-
- - ``num_entities``
-
- - Number of entities in the graph
-
- - .. row 3
-
- - __u64
-
- - ``ptr_entities``
-
- - A pointer to a memory area where the entities array will be
- stored, converted to a 64-bits integer. It can be zero. if zero,
- the ioctl won't store the entities. It will just update
- ``num_entities``
-
- - .. row 4
-
- - __u64
-
- - ``num_interfaces``
-
- - Number of interfaces in the graph
-
- - .. row 5
-
- - __u64
-
- - ``ptr_interfaces``
-
- - A pointer to a memory area where the interfaces array will be
- stored, converted to a 64-bits integer. It can be zero. if zero,
- the ioctl won't store the interfaces. It will just update
- ``num_interfaces``
-
- - .. row 6
-
- - __u64
-
- - ``num_pads``
-
- - Total number of pads in the graph
-
- - .. row 7
-
- - __u64
-
- - ``ptr_pads``
-
- - A pointer to a memory area where the pads array will be stored,
- converted to a 64-bits integer. It can be zero. if zero, the ioctl
- won't store the pads. It will just update ``num_pads``
-
- - .. row 8
-
- - __u64
-
- - ``num_links``
-
- - Total number of data and interface links in the graph
-
- - .. row 9
-
- - __u64
-
- - ``ptr_links``
-
- - A pointer to a memory area where the links array will be stored,
- converted to a 64-bits integer. It can be zero. if zero, the ioctl
- won't store the links. It will just update ``num_links``
-
-
-
-.. _media-v2-entity:
-
-.. flat-table:: struct media_v2_entity
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 2 8
-
-
- - .. row 1
-
- - __u32
-
- - ``id``
-
- - Unique ID for the entity.
-
- - .. row 2
-
- - char
-
- - ``name``\ [64]
-
- - Entity name as an UTF-8 NULL-terminated string.
-
- - .. row 3
-
- - __u32
-
- - ``function``
-
- - Entity main function, see :ref:`media-entity-type` for details.
-
- - .. row 4
-
- - __u32
-
- - ``reserved``\ [12]
-
- - Reserved for future extensions. Drivers and applications must set
- this array to zero.
-
-
-
-.. _media-v2-interface:
-
-.. flat-table:: struct media_v2_interface
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 2 8
-
- - .. row 1
-
- - __u32
-
- - ``id``
-
- - Unique ID for the interface.
-
- - .. row 2
-
- - __u32
-
- - ``intf_type``
-
- - Interface type, see :ref:`media-intf-type` for details.
-
- - .. row 3
-
- - __u32
-
- - ``flags``
-
- - Interface flags. Currently unused.
-
- - .. row 4
-
- - __u32
-
- - ``reserved``\ [9]
-
- - Reserved for future extensions. Drivers and applications must set
- this array to zero.
-
- - .. row 5
-
- - struct media_v2_intf_devnode
-
- - ``devnode``
-
- - Used only for device node interfaces. See
- :ref:`media-v2-intf-devnode` for details..
-
-
-
-.. _media-v2-intf-devnode:
-
-.. flat-table:: struct media_v2_interface
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 2 8
-
-
- - .. row 1
-
- - __u32
-
- - ``major``
-
- - Device node major number.
-
- - .. row 2
-
- - __u32
-
- - ``minor``
-
- - Device node minor number.
-
-
-
-.. _media-v2-pad:
-
-.. flat-table:: struct media_v2_pad
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 2 8
-
-
- - .. row 1
-
- - __u32
-
- - ``id``
-
- - Unique ID for the pad.
-
- - .. row 2
-
- - __u32
-
- - ``entity_id``
-
- - Unique ID for the entity where this pad belongs.
-
- - .. row 3
-
- - __u32
-
- - ``flags``
-
- - Pad flags, see :ref:`media-pad-flag` for more details.
-
- - .. row 4
-
- - __u32
-
- - ``reserved``\ [9]
-
- - Reserved for future extensions. Drivers and applications must set
- this array to zero.
-
-
-
-.. _media-v2-link:
-
-.. flat-table:: struct media_v2_pad
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 2 8
-
-
- - .. row 1
-
- - __u32
-
- - ``id``
-
- - Unique ID for the pad.
-
- - .. row 2
-
- - __u32
-
- - ``source_id``
-
- - On pad to pad links: unique ID for the source pad.
-
- On interface to entity links: unique ID for the interface.
-
- - .. row 3
-
- - __u32
-
- - ``sink_id``
-
- - On pad to pad links: unique ID for the sink pad.
-
- On interface to entity links: unique ID for the entity.
-
- - .. row 4
-
- - __u32
-
- - ``flags``
-
- - Link flags, see :ref:`media-link-flag` for more details.
-
- - .. row 5
-
- - __u32
-
- - ``reserved``\ [5]
-
- - Reserved for future extensions. Drivers and applications must set
- this array to zero.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-ENOSPC
- This is returned when either one or more of the num_entities,
- num_interfaces, num_links or num_pads are non-zero and are
- smaller than the actual number of elements inside the graph. This
- may happen if the ``topology_version`` changed when compared to the
- last time this ioctl was called. Userspace should usually free the
- area for the pointers, zero the struct elements and call this ioctl
- again.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _media-ioc-setup-link:
-
-**************************
-ioctl MEDIA_IOC_SETUP_LINK
-**************************
-
-Name
-====
-
-MEDIA_IOC_SETUP_LINK - Modify the properties of a link
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct media_link_desc *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <media-func-open>`.
-
-``request``
- MEDIA_IOC_SETUP_LINK
-
-``argp``
-
-
-Description
-===========
-
-To change link properties applications fill a struct
-:ref:`media_link_desc <media-link-desc>` with link identification
-information (source and sink pad) and the new requested link flags. They
-then call the MEDIA_IOC_SETUP_LINK ioctl with a pointer to that
-structure.
-
-The only configurable property is the ``ENABLED`` link flag to
-enable/disable a link. Links marked with the ``IMMUTABLE`` link flag can
-not be enabled or disabled.
-
-Link configuration has no side effect on other links. If an enabled link
-at the sink pad prevents the link from being enabled, the driver returns
-with an ``EBUSY`` error code.
-
-Only links marked with the ``DYNAMIC`` link flag can be enabled/disabled
-while streaming media data. Attempting to enable or disable a streaming
-non-dynamic link will return an ``EBUSY`` error code.
-
-If the specified link can't be found the driver returns with an ``EINVAL``
-error code.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EINVAL
- The struct :ref:`media_link_desc <media-link-desc>` references a
- non-existing link, or the link is immutable and an attempt to modify
- its configuration was made.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _media-controller-types:
-
-Types and flags used to represent the media graph elements
-==========================================================
-
-
-.. _media-entity-type:
-
-.. flat-table:: Media entity types
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``MEDIA_ENT_F_UNKNOWN`` and ``MEDIA_ENT_F_V4L2_SUBDEV_UNKNOWN``
-
- - Unknown entity. That generally indicates that a driver didn't
- initialize properly the entity, with is a Kernel bug
-
- - .. row 2
-
- - ``MEDIA_ENT_F_IO_V4L``
-
- - Data streaming input and/or output entity.
-
- - .. row 3
-
- - ``MEDIA_ENT_F_IO_VBI``
-
- - V4L VBI streaming input or output entity
-
- - .. row 4
-
- - ``MEDIA_ENT_F_IO_SWRADIO``
-
- - V4L Software Digital Radio (SDR) streaming input or output entity
-
- - .. row 5
-
- - ``MEDIA_ENT_F_IO_DTV``
-
- - DVB Digital TV streaming input or output entity
-
- - .. row 6
-
- - ``MEDIA_ENT_F_DTV_DEMOD``
-
- - Digital TV demodulator entity.
-
- - .. row 7
-
- - ``MEDIA_ENT_F_TS_DEMUX``
-
- - MPEG Transport stream demux entity. Could be implemented on
- hardware or in Kernelspace by the Linux DVB subsystem.
-
- - .. row 8
-
- - ``MEDIA_ENT_F_DTV_CA``
-
- - Digital TV Conditional Access module (CAM) entity
-
- - .. row 9
-
- - ``MEDIA_ENT_F_DTV_NET_DECAP``
-
- - Digital TV network ULE/MLE desencapsulation entity. Could be
- implemented on hardware or in Kernelspace
-
- - .. row 10
-
- - ``MEDIA_ENT_F_CONN_RF``
-
- - Connector for a Radio Frequency (RF) signal.
-
- - .. row 11
-
- - ``MEDIA_ENT_F_CONN_SVIDEO``
-
- - Connector for a S-Video signal.
-
- - .. row 12
-
- - ``MEDIA_ENT_F_CONN_COMPOSITE``
-
- - Connector for a RGB composite signal.
-
- - .. row 13
-
- - ``MEDIA_ENT_F_CAM_SENSOR``
-
- - Camera video sensor entity.
-
- - .. row 14
-
- - ``MEDIA_ENT_F_FLASH``
-
- - Flash controller entity.
-
- - .. row 15
-
- - ``MEDIA_ENT_F_LENS``
-
- - Lens controller entity.
-
- - .. row 16
-
- - ``MEDIA_ENT_F_ATV_DECODER``
-
- - Analog video decoder, the basic function of the video decoder is
- to accept analogue video from a wide variety of sources such as
- broadcast, DVD players, cameras and video cassette recorders, in
- either NTSC, PAL, SECAM or HD format, separating the stream into
- its component parts, luminance and chrominance, and output it in
- some digital video standard, with appropriate timing signals.
-
- - .. row 17
-
- - ``MEDIA_ENT_F_TUNER``
-
- - Digital TV, analog TV, radio and/or software radio tuner, with
- consists on a PLL tuning stage that converts radio frequency (RF)
- signal into an Intermediate Frequency (IF). Modern tuners have
- internally IF-PLL decoders for audio and video, but older models
- have those stages implemented on separate entities.
-
- - .. row 18
-
- - ``MEDIA_ENT_F_IF_VID_DECODER``
-
- - IF-PLL video decoder. It receives the IF from a PLL and decodes
- the analog TV video signal. This is commonly found on some very
- old analog tuners, like Philips MK3 designs. They all contain a
- tda9887 (or some software compatible similar chip, like tda9885).
- Those devices use a different I2C address than the tuner PLL.
-
- - .. row 19
-
- - ``MEDIA_ENT_F_IF_AUD_DECODER``
-
- - IF-PLL sound decoder. It receives the IF from a PLL and decodes
- the analog TV audio signal. This is commonly found on some very
- old analog hardware, like Micronas msp3400, Philips tda9840,
- tda985x, etc. Those devices use a different I2C address than the
- tuner PLL and should be controlled together with the IF-PLL video
- decoder.
-
- - .. row 20
-
- - ``MEDIA_ENT_F_AUDIO_CAPTURE``
-
- - Audio Capture Function Entity.
-
- - .. row 21
-
- - ``MEDIA_ENT_F_AUDIO_PLAYBACK``
-
- - Audio Playback Function Entity.
-
- - .. row 22
-
- - ``MEDIA_ENT_F_AUDIO_MIXER``
-
- - Audio Mixer Function Entity.
-
-
-
-.. _media-entity-flag:
-
-.. flat-table:: Media entity flags
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``MEDIA_ENT_FL_DEFAULT``
-
- - Default entity for its type. Used to discover the default audio,
- VBI and video devices, the default camera sensor, ...
-
- - .. row 2
-
- - ``MEDIA_ENT_FL_CONNECTOR``
-
- - The entity represents a data conector
-
-
-
-.. _media-intf-type:
-
-.. flat-table:: Media interface types
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``MEDIA_INTF_T_DVB_FE``
-
- - Device node interface for the Digital TV frontend
-
- - typically, /dev/dvb/adapter?/frontend?
-
- - .. row 2
-
- - ``MEDIA_INTF_T_DVB_DEMUX``
-
- - Device node interface for the Digital TV demux
-
- - typically, /dev/dvb/adapter?/demux?
-
- - .. row 3
-
- - ``MEDIA_INTF_T_DVB_DVR``
-
- - Device node interface for the Digital TV DVR
-
- - typically, /dev/dvb/adapter?/dvr?
-
- - .. row 4
-
- - ``MEDIA_INTF_T_DVB_CA``
-
- - Device node interface for the Digital TV Conditional Access
-
- - typically, /dev/dvb/adapter?/ca?
-
- - .. row 5
-
- - ``MEDIA_INTF_T_DVB_FE``
-
- - Device node interface for the Digital TV network control
-
- - typically, /dev/dvb/adapter?/net?
-
- - .. row 6
-
- - ``MEDIA_INTF_T_V4L_VIDEO``
-
- - Device node interface for video (V4L)
-
- - typically, /dev/video?
-
- - .. row 7
-
- - ``MEDIA_INTF_T_V4L_VBI``
-
- - Device node interface for VBI (V4L)
-
- - typically, /dev/vbi?
-
- - .. row 8
-
- - ``MEDIA_INTF_T_V4L_RADIO``
-
- - Device node interface for radio (V4L)
-
- - typically, /dev/vbi?
-
- - .. row 9
-
- - ``MEDIA_INTF_T_V4L_SUBDEV``
-
- - Device node interface for a V4L subdevice
-
- - typically, /dev/v4l-subdev?
-
- - .. row 10
-
- - ``MEDIA_INTF_T_V4L_SWRADIO``
-
- - Device node interface for Software Defined Radio (V4L)
-
- - typically, /dev/swradio?
-
- - .. row 11
-
- - ``MEDIA_INTF_T_ALSA_PCM_CAPTURE``
-
- - Device node interface for ALSA PCM Capture
-
- - typically, /dev/snd/pcmC?D?c
-
- - .. row 12
-
- - ``MEDIA_INTF_T_ALSA_PCM_PLAYBACK``
-
- - Device node interface for ALSA PCM Playback
-
- - typically, /dev/snd/pcmC?D?p
-
- - .. row 13
-
- - ``MEDIA_INTF_T_ALSA_CONTROL``
-
- - Device node interface for ALSA Control
-
- - typically, /dev/snd/controlC?
-
- - .. row 14
-
- - ``MEDIA_INTF_T_ALSA_COMPRESS``
-
- - Device node interface for ALSA Compress
-
- - typically, /dev/snd/compr?
-
- - .. row 15
-
- - ``MEDIA_INTF_T_ALSA_RAWMIDI``
-
- - Device node interface for ALSA Raw MIDI
-
- - typically, /dev/snd/midi?
-
- - .. row 16
-
- - ``MEDIA_INTF_T_ALSA_HWDEP``
-
- - Device node interface for ALSA Hardware Dependent
-
- - typically, /dev/snd/hwC?D?
-
- - .. row 17
-
- - ``MEDIA_INTF_T_ALSA_SEQUENCER``
-
- - Device node interface for ALSA Sequencer
-
- - typically, /dev/snd/seq
-
- - .. row 18
-
- - ``MEDIA_INTF_T_ALSA_TIMER``
-
- - Device node interface for ALSA Timer
-
- - typically, /dev/snd/timer
-
-
-
-.. _media-pad-flag:
-
-.. flat-table:: Media pad flags
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``MEDIA_PAD_FL_SINK``
-
- - Input pad, relative to the entity. Input pads sink data and are
- targets of links.
-
- - .. row 2
-
- - ``MEDIA_PAD_FL_SOURCE``
-
- - Output pad, relative to the entity. Output pads source data and
- are origins of links.
-
- - .. row 3
-
- - ``MEDIA_PAD_FL_MUST_CONNECT``
-
- - If this flag is set and the pad is linked to any other pad, then
- at least one of those links must be enabled for the entity to be
- able to stream. There could be temporary reasons (e.g. device
- configuration dependent) for the pad to need enabled links even
- when this flag isn't set; the absence of the flag doesn't imply
- there is none.
-
-
-One and only one of ``MEDIA_PAD_FL_SINK`` and ``MEDIA_PAD_FL_SOURCE``
-must be set for every pad.
-
-
-.. _media-link-flag:
-
-.. flat-table:: Media link flags
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``MEDIA_LNK_FL_ENABLED``
-
- - The link is enabled and can be used to transfer media data. When
- two or more links target a sink pad, only one of them can be
- enabled at a time.
-
- - .. row 2
-
- - ``MEDIA_LNK_FL_IMMUTABLE``
-
- - The link enabled state can't be modified at runtime. An immutable
- link is always enabled.
-
- - .. row 3
-
- - ``MEDIA_LNK_FL_DYNAMIC``
-
- - The link enabled state can be modified during streaming. This flag
- is set by drivers and is read-only for applications.
-
- - .. row 4
-
- - ``MEDIA_LNK_FL_LINK_TYPE``
-
- - This is a bitmask that defines the type of the link. Currently,
- two types of links are supported:
-
- ``MEDIA_LNK_FL_DATA_LINK`` if the link is between two pads
-
- ``MEDIA_LNK_FL_INTERFACE_LINK`` if the link is between an
- interface and an entity
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _Remote_controllers_Intro:
-
-************
-Introduction
-************
-
-Currently, most analog and digital devices have a Infrared input for
-remote controllers. Each manufacturer has their own type of control. It
-is not rare for the same manufacturer to ship different types of
-controls, depending on the device.
-
-A Remote Controller interface is mapped as a normal evdev/input
-interface, just like a keyboard or a mouse. So, it uses all ioctls
-already defined for any other input devices.
-
-However, remove controllers are more flexible than a normal input
-device, as the IR receiver (and/or transmitter) can be used in
-conjunction with a wide variety of different IR remotes.
-
-In order to allow flexibility, the Remote Controller subsystem allows
-controlling the RC-specific attributes via
-:ref:`the sysfs class nodes <remote_controllers_sysfs_nodes>`.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _Remote_controllers_table_change:
-
-*******************************************
-Changing default Remote Controller mappings
-*******************************************
-
-The event interface provides two ioctls to be used against the
-/dev/input/event device, to allow changing the default keymapping.
-
-This program demonstrates how to replace the keymap tables.
-
-
-.. toctree::
- :maxdepth: 1
-
- keytable.c
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _Remote_controllers_tables:
-
-************************
-Remote controller tables
-************************
-
-Unfortunately, for several years, there was no effort to create uniform
-IR keycodes for different devices. This caused the same IR keyname to be
-mapped completely differently on different IR devices. This resulted
-that the same IR keyname to be mapped completely different on different
-IR's. Due to that, V4L2 API now specifies a standard for mapping Media
-keys on IR.
-
-This standard should be used by both V4L/DVB drivers and userspace
-applications
-
-The modules register the remote as keyboard within the linux input
-layer. This means that the IR key strokes will look like normal keyboard
-key strokes (if CONFIG_INPUT_KEYBOARD is enabled). Using the event
-devices (CONFIG_INPUT_EVDEV) it is possible for applications to access
-the remote via /dev/input/event devices.
-
-
-.. _rc_standard_keymap:
-
-.. flat-table:: IR default keymapping
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - Key code
-
- - Meaning
-
- - Key examples on IR
-
- - .. row 2
-
- - **Numeric keys**
-
- - .. row 3
-
- - ``KEY_0``
-
- - Keyboard digit 0
-
- - 0
-
- - .. row 4
-
- - ``KEY_1``
-
- - Keyboard digit 1
-
- - 1
-
- - .. row 5
-
- - ``KEY_2``
-
- - Keyboard digit 2
-
- - 2
-
- - .. row 6
-
- - ``KEY_3``
-
- - Keyboard digit 3
-
- - 3
-
- - .. row 7
-
- - ``KEY_4``
-
- - Keyboard digit 4
-
- - 4
-
- - .. row 8
-
- - ``KEY_5``
-
- - Keyboard digit 5
-
- - 5
-
- - .. row 9
-
- - ``KEY_6``
-
- - Keyboard digit 6
-
- - 6
-
- - .. row 10
-
- - ``KEY_7``
-
- - Keyboard digit 7
-
- - 7
-
- - .. row 11
-
- - ``KEY_8``
-
- - Keyboard digit 8
-
- - 8
-
- - .. row 12
-
- - ``KEY_9``
-
- - Keyboard digit 9
-
- - 9
-
- - .. row 13
-
- - **Movie play control**
-
- - .. row 14
-
- - ``KEY_FORWARD``
-
- - Instantly advance in time
-
- - >> / FORWARD
-
- - .. row 15
-
- - ``KEY_BACK``
-
- - Instantly go back in time
-
- - <<< / BACK
-
- - .. row 16
-
- - ``KEY_FASTFORWARD``
-
- - Play movie faster
-
- - >>> / FORWARD
-
- - .. row 17
-
- - ``KEY_REWIND``
-
- - Play movie back
-
- - REWIND / BACKWARD
-
- - .. row 18
-
- - ``KEY_NEXT``
-
- - Select next chapter / sub-chapter / interval
-
- - NEXT / SKIP
-
- - .. row 19
-
- - ``KEY_PREVIOUS``
-
- - Select previous chapter / sub-chapter / interval
-
- - << / PREV / PREVIOUS
-
- - .. row 20
-
- - ``KEY_AGAIN``
-
- - Repeat the video or a video interval
-
- - REPEAT / LOOP / RECALL
-
- - .. row 21
-
- - ``KEY_PAUSE``
-
- - Pause sroweam
-
- - PAUSE / FREEZE
-
- - .. row 22
-
- - ``KEY_PLAY``
-
- - Play movie at the normal timeshift
-
- - NORMAL TIMESHIFT / LIVE / >
-
- - .. row 23
-
- - ``KEY_PLAYPAUSE``
-
- - Alternate between play and pause
-
- - PLAY / PAUSE
-
- - .. row 24
-
- - ``KEY_STOP``
-
- - Stop sroweam
-
- - STOP
-
- - .. row 25
-
- - ``KEY_RECORD``
-
- - Start/stop recording sroweam
-
- - CAPTURE / REC / RECORD/PAUSE
-
- - .. row 26
-
- - ``KEY_CAMERA``
-
- - Take a picture of the image
-
- - CAMERA ICON / CAPTURE / SNAPSHOT
-
- - .. row 27
-
- - ``KEY_SHUFFLE``
-
- - Enable shuffle mode
-
- - SHUFFLE
-
- - .. row 28
-
- - ``KEY_TIME``
-
- - Activate time shift mode
-
- - TIME SHIFT
-
- - .. row 29
-
- - ``KEY_TITLE``
-
- - Allow changing the chapter
-
- - CHAPTER
-
- - .. row 30
-
- - ``KEY_SUBTITLE``
-
- - Allow changing the subtitle
-
- - SUBTITLE
-
- - .. row 31
-
- - **Image control**
-
- - .. row 32
-
- - ``KEY_BRIGHTNESSDOWN``
-
- - Decrease Brightness
-
- - BRIGHTNESS DECREASE
-
- - .. row 33
-
- - ``KEY_BRIGHTNESSUP``
-
- - Increase Brightness
-
- - BRIGHTNESS INCREASE
-
- - .. row 34
-
- - ``KEY_ANGLE``
-
- - Switch video camera angle (on videos with more than one angle
- stored)
-
- - ANGLE / SWAP
-
- - .. row 35
-
- - ``KEY_EPG``
-
- - Open the Elecrowonic Play Guide (EPG)
-
- - EPG / GUIDE
-
- - .. row 36
-
- - ``KEY_TEXT``
-
- - Activate/change closed caption mode
-
- - CLOSED CAPTION/TELETEXT / DVD TEXT / TELETEXT / TTX
-
- - .. row 37
-
- - **Audio control**
-
- - .. row 38
-
- - ``KEY_AUDIO``
-
- - Change audio source
-
- - AUDIO SOURCE / AUDIO / MUSIC
-
- - .. row 39
-
- - ``KEY_MUTE``
-
- - Mute/unmute audio
-
- - MUTE / DEMUTE / UNMUTE
-
- - .. row 40
-
- - ``KEY_VOLUMEDOWN``
-
- - Decrease volume
-
- - VOLUME- / VOLUME DOWN
-
- - .. row 41
-
- - ``KEY_VOLUMEUP``
-
- - Increase volume
-
- - VOLUME+ / VOLUME UP
-
- - .. row 42
-
- - ``KEY_MODE``
-
- - Change sound mode
-
- - MONO/STEREO
-
- - .. row 43
-
- - ``KEY_LANGUAGE``
-
- - Select Language
-
- - 1ST / 2ND LANGUAGE / DVD LANG / MTS/SAP / MTS SEL
-
- - .. row 44
-
- - **Channel control**
-
- - .. row 45
-
- - ``KEY_CHANNEL``
-
- - Go to the next favorite channel
-
- - ALT / CHANNEL / CH SURFING / SURF / FAV
-
- - .. row 46
-
- - ``KEY_CHANNELDOWN``
-
- - Decrease channel sequencially
-
- - CHANNEL - / CHANNEL DOWN / DOWN
-
- - .. row 47
-
- - ``KEY_CHANNELUP``
-
- - Increase channel sequencially
-
- - CHANNEL + / CHANNEL UP / UP
-
- - .. row 48
-
- - ``KEY_DIGITS``
-
- - Use more than one digit for channel
-
- - PLUS / 100/ 1xx / xxx / -/-- / Single Double Triple Digit
-
- - .. row 49
-
- - ``KEY_SEARCH``
-
- - Start channel autoscan
-
- - SCAN / AUTOSCAN
-
- - .. row 50
-
- - **Colored keys**
-
- - .. row 51
-
- - ``KEY_BLUE``
-
- - IR Blue key
-
- - BLUE
-
- - .. row 52
-
- - ``KEY_GREEN``
-
- - IR Green Key
-
- - GREEN
-
- - .. row 53
-
- - ``KEY_RED``
-
- - IR Red key
-
- - RED
-
- - .. row 54
-
- - ``KEY_YELLOW``
-
- - IR Yellow key
-
- - YELLOW
-
- - .. row 55
-
- - **Media selection**
-
- - .. row 56
-
- - ``KEY_CD``
-
- - Change input source to Compact Disc
-
- - CD
-
- - .. row 57
-
- - ``KEY_DVD``
-
- - Change input to DVD
-
- - DVD / DVD MENU
-
- - .. row 58
-
- - ``KEY_EJECTCLOSECD``
-
- - Open/close the CD/DVD player
-
- - -> ) / CLOSE / OPEN
-
- - .. row 59
-
- - ``KEY_MEDIA``
-
- - Turn on/off Media application
-
- - PC/TV / TURN ON/OFF APP
-
- - .. row 60
-
- - ``KEY_PC``
-
- - Selects from TV to PC
-
- - PC
-
- - .. row 61
-
- - ``KEY_RADIO``
-
- - Put into AM/FM radio mode
-
- - RADIO / TV/FM / TV/RADIO / FM / FM/RADIO
-
- - .. row 62
-
- - ``KEY_TV``
-
- - Select tv mode
-
- - TV / LIVE TV
-
- - .. row 63
-
- - ``KEY_TV2``
-
- - Select Cable mode
-
- - AIR/CBL
-
- - .. row 64
-
- - ``KEY_VCR``
-
- - Select VCR mode
-
- - VCR MODE / DTR
-
- - .. row 65
-
- - ``KEY_VIDEO``
-
- - Alternate between input modes
-
- - SOURCE / SELECT / DISPLAY / SWITCH INPUTS / VIDEO
-
- - .. row 66
-
- - **Power control**
-
- - .. row 67
-
- - ``KEY_POWER``
-
- - Turn on/off computer
-
- - SYSTEM POWER / COMPUTER POWER
-
- - .. row 68
-
- - ``KEY_POWER2``
-
- - Turn on/off application
-
- - TV ON/OFF / POWER
-
- - .. row 69
-
- - ``KEY_SLEEP``
-
- - Activate sleep timer
-
- - SLEEP / SLEEP TIMER
-
- - .. row 70
-
- - ``KEY_SUSPEND``
-
- - Put computer into suspend mode
-
- - STANDBY / SUSPEND
-
- - .. row 71
-
- - **Window control**
-
- - .. row 72
-
- - ``KEY_CLEAR``
-
- - Stop sroweam and return to default input video/audio
-
- - CLEAR / RESET / BOSS KEY
-
- - .. row 73
-
- - ``KEY_CYCLEWINDOWS``
-
- - Minimize windows and move to the next one
-
- - ALT-TAB / MINIMIZE / DESKTOP
-
- - .. row 74
-
- - ``KEY_FAVORITES``
-
- - Open the favorites sroweam window
-
- - TV WALL / Favorites
-
- - .. row 75
-
- - ``KEY_MENU``
-
- - Call application menu
-
- - 2ND CONTROLS (USA: MENU) / DVD/MENU / SHOW/HIDE CTRL
-
- - .. row 76
-
- - ``KEY_NEW``
-
- - Open/Close Picture in Picture
-
- - PIP
-
- - .. row 77
-
- - ``KEY_OK``
-
- - Send a confirmation code to application
-
- - OK / ENTER / RETURN
-
- - .. row 78
-
- - ``KEY_SCREEN``
-
- - Select screen aspect ratio
-
- - 4:3 16:9 SELECT
-
- - .. row 79
-
- - ``KEY_ZOOM``
-
- - Put device into zoom/full screen mode
-
- - ZOOM / FULL SCREEN / ZOOM+ / HIDE PANNEL / SWITCH
-
- - .. row 80
-
- - **Navigation keys**
-
- - .. row 81
-
- - ``KEY_ESC``
-
- - Cancel current operation
-
- - CANCEL / BACK
-
- - .. row 82
-
- - ``KEY_HELP``
-
- - Open a Help window
-
- - HELP
-
- - .. row 83
-
- - ``KEY_HOMEPAGE``
-
- - Navigate to Homepage
-
- - HOME
-
- - .. row 84
-
- - ``KEY_INFO``
-
- - Open On Screen Display
-
- - DISPLAY INFORMATION / OSD
-
- - .. row 85
-
- - ``KEY_WWW``
-
- - Open the default browser
-
- - WEB
-
- - .. row 86
-
- - ``KEY_UP``
-
- - Up key
-
- - UP
-
- - .. row 87
-
- - ``KEY_DOWN``
-
- - Down key
-
- - DOWN
-
- - .. row 88
-
- - ``KEY_LEFT``
-
- - Left key
-
- - LEFT
-
- - .. row 89
-
- - ``KEY_RIGHT``
-
- - Right key
-
- - RIGHT
-
- - .. row 90
-
- - **Miscellaneous keys**
-
- - .. row 91
-
- - ``KEY_DOT``
-
- - Return a dot
-
- - .
-
- - .. row 92
-
- - ``KEY_FN``
-
- - Select a function
-
- - FUNCTION
-
-
-It should be noted that, sometimes, there some fundamental missing keys
-at some cheaper IR's. Due to that, it is recommended to:
-
-
-.. _rc_keymap_notes:
-
-.. flat-table:: Notes
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - On simpler IR's, without separate channel keys, you need to map UP
- as ``KEY_CHANNELUP``
-
- - .. row 2
-
- - On simpler IR's, without separate channel keys, you need to map
- DOWN as ``KEY_CHANNELDOWN``
-
- - .. row 3
-
- - On simpler IR's, without separate volume keys, you need to map
- LEFT as ``KEY_VOLUMEDOWN``
-
- - .. row 4
-
- - On simpler IR's, without separate volume keys, you need to map
- RIGHT as ``KEY_VOLUMEUP``
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-file: media/v4l/keytable.c
-==========================
-
-.. code-block:: c
-
- /* keytable.c - This program allows checking/replacing keys at IR
-
- Copyright (C) 2006-2009 Mauro Carvalho Chehab <mchehab@infradead.org>
-
- This program is free software; you can redistribute it and/or modify
- it under the terms of the GNU General Public License as published by
- the Free Software Foundation, version 2 of the License.
-
- This program is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- GNU General Public License for more details.
- */
-
- #include <ctype.h>
- #include <errno.h>
- #include <fcntl.h>
- #include <stdio.h>
- #include <stdlib.h>
- #include <string.h>
- #include <linux/input.h>
- #include <sys/ioctl.h>
-
- #include "parse.h"
-
- void prtcode (int *codes)
- {
- struct parse_key *p;
-
- for (p=keynames;p->name!=NULL;p++) {
- if (p->value == (unsigned)codes[1]) {
- printf("scancode 0x%04x = %s (0x%02x)\\n", codes[0], p->name, codes[1]);
- return;
- }
- }
-
- if (isprint (codes[1]))
- printf("scancode %d = '%c' (0x%02x)\\n", codes[0], codes[1], codes[1]);
- else
- printf("scancode %d = 0x%02x\\n", codes[0], codes[1]);
- }
-
- int parse_code(char *string)
- {
- struct parse_key *p;
-
- for (p=keynames;p->name!=NULL;p++) {
- if (!strcasecmp(p->name, string)) {
- return p->value;
- }
- }
- return -1;
- }
-
- int main (int argc, char *argv[])
- {
- int fd;
- unsigned int i, j;
- int codes[2];
-
- if (argc<2 || argc>4) {
- printf ("usage: %s <device> to get table; or\\n"
- " %s <device> <scancode> <keycode>\\n"
- " %s <device> <keycode_file>n",*argv,*argv,*argv);
- return -1;
- }
-
- if ((fd = open(argv[1], O_RDONLY)) < 0) {
- perror("Couldn't open input device");
- return(-1);
- }
-
- if (argc==4) {
- int value;
-
- value=parse_code(argv[3]);
-
- if (value==-1) {
- value = strtol(argv[3], NULL, 0);
- if (errno)
- perror("value");
- }
-
- codes [0] = (unsigned) strtol(argv[2], NULL, 0);
- codes [1] = (unsigned) value;
-
- if(ioctl(fd, EVIOCSKEYCODE, codes))
- perror ("EVIOCSKEYCODE");
-
- if(ioctl(fd, EVIOCGKEYCODE, codes)==0)
- prtcode(codes);
- return 0;
- }
-
- if (argc==3) {
- FILE *fin;
- int value;
- char *scancode, *keycode, s[2048];
-
- fin=fopen(argv[2],"r");
- if (fin==NULL) {
- perror ("opening keycode file");
- return -1;
- }
-
- /* Clears old table */
- for (j = 0; j < 256; j++) {
- for (i = 0; i < 256; i++) {
- codes[0] = (j << 8) | i;
- codes[1] = KEY_RESERVED;
- ioctl(fd, EVIOCSKEYCODE, codes);
- }
- }
-
- while (fgets(s,sizeof(s),fin)) {
- scancode=strtok(s,"\\n\\t =:");
- if (!scancode) {
- perror ("parsing input file scancode");
- return -1;
- }
- if (!strcasecmp(scancode, "scancode")) {
- scancode = strtok(NULL,"\\n\\t =:");
- if (!scancode) {
- perror ("parsing input file scancode");
- return -1;
- }
- }
-
- keycode=strtok(NULL,"\\n\\t =:(");
- if (!keycode) {
- perror ("parsing input file keycode");
- return -1;
- }
-
- // printf ("parsing %s=%s:", scancode, keycode);
- value=parse_code(keycode);
- // printf ("\\tvalue=%d\\n",value);
-
- if (value==-1) {
- value = strtol(keycode, NULL, 0);
- if (errno)
- perror("value");
- }
-
- codes [0] = (unsigned) strtol(scancode, NULL, 0);
- codes [1] = (unsigned) value;
-
- // printf("\\t%04x=%04x\\n",codes[0], codes[1]);
- if(ioctl(fd, EVIOCSKEYCODE, codes)) {
- fprintf(stderr, "Setting scancode 0x%04x with 0x%04x via ",codes[0], codes[1]);
- perror ("EVIOCSKEYCODE");
- }
-
- if(ioctl(fd, EVIOCGKEYCODE, codes)==0)
- prtcode(codes);
- }
- return 0;
- }
-
- /* Get scancode table */
- for (j = 0; j < 256; j++) {
- for (i = 0; i < 256; i++) {
- codes[0] = (j << 8) | i;
- if (!ioctl(fd, EVIOCGKEYCODE, codes) && codes[1] != KEY_RESERVED)
- prtcode(codes);
- }
- }
- return 0;
- }
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _lirc_dev_intro:
-
-************
-Introduction
-************
-
-The LIRC device interface is a bi-directional interface for transporting
-raw IR data between userspace and kernelspace. Fundamentally, it is just
-a chardev (/dev/lircX, for X = 0, 1, 2, ...), with a number of standard
-struct file_operations defined on it. With respect to transporting raw
-IR data to and fro, the essential fops are read, write and ioctl.
-
-Example dmesg output upon a driver registering w/LIRC:
-
-.. code-block:: none
-
- $ dmesg |grep lirc_dev
- lirc_dev: IR Remote Control driver registered, major 248
- rc rc0: lirc_dev: driver ir-lirc-codec (mceusb) registered at minor = 0
-
-What you should see for a chardev:
-
-.. code-block:: none
-
- $ ls -l /dev/lirc*
- crw-rw---- 1 root root 248, 0 Jul 2 22:20 /dev/lirc0
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _lirc_dev:
-
-LIRC Device Interface
-=====================
-
-
-.. toctree::
- :maxdepth: 1
-
- lirc_dev_intro
- lirc_read
- lirc_write
- lirc_ioctl
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _lirc_ioctl:
-
-**************
-LIRC ioctl fop
-**************
-
-The LIRC device's ioctl definition is bound by the ioctl function
-definition of struct file_operations, leaving us with an unsigned int
-for the ioctl command and an unsigned long for the arg. For the purposes
-of ioctl portability across 32-bit and 64-bit, these values are capped
-to their 32-bit sizes.
-
-The following ioctls can be used to change specific hardware settings.
-In general each driver should have a default set of settings. The driver
-implementation is expected to re-apply the default settings when the
-device is closed by user-space, so that every application opening the
-device can rely on working with the default settings initially.
-
-LIRC_GET_FEATURES
- Obviously, get the underlying hardware device's features. If a
- driver does not announce support of certain features, calling of the
- corresponding ioctls is undefined.
-
-LIRC_GET_SEND_MODE
- Get supported transmit mode. Only LIRC_MODE_PULSE is supported by
- lircd.
-
-LIRC_GET_REC_MODE
- Get supported receive modes. Only LIRC_MODE_MODE2 and
- LIRC_MODE_LIRCCODE are supported by lircd.
-
-LIRC_GET_SEND_CARRIER
- Get carrier frequency (in Hz) currently used for transmit.
-
-LIRC_GET_REC_CARRIER
- Get carrier frequency (in Hz) currently used for IR reception.
-
-LIRC_{G,S}ET_{SEND,REC}_DUTY_CYCLE
- Get/set the duty cycle (from 0 to 100) of the carrier signal.
- Currently, no special meaning is defined for 0 or 100, but this
- could be used to switch off carrier generation in the future, so
- these values should be reserved.
-
-LIRC_GET_REC_RESOLUTION
- Some receiver have maximum resolution which is defined by internal
- sample rate or data format limitations. E.g. it's common that
- signals can only be reported in 50 microsecond steps. This integer
- value is used by lircd to automatically adjust the aeps tolerance
- value in the lircd config file.
-
-LIRC_GET_M{IN,AX}_TIMEOUT
- Some devices have internal timers that can be used to detect when
- there's no IR activity for a long time. This can help lircd in
- detecting that a IR signal is finished and can speed up the decoding
- process. Returns an integer value with the minimum/maximum timeout
- that can be set. Some devices have a fixed timeout, in that case
- both ioctls will return the same value even though the timeout
- cannot be changed.
-
-LIRC_GET_M{IN,AX}_FILTER_{PULSE,SPACE}
- Some devices are able to filter out spikes in the incoming signal
- using given filter rules. These ioctls return the hardware
- capabilities that describe the bounds of the possible filters.
- Filter settings depend on the IR protocols that are expected. lircd
- derives the settings from all protocols definitions found in its
- config file.
-
-LIRC_GET_LENGTH
- Retrieves the code length in bits (only for LIRC_MODE_LIRCCODE).
- Reads on the device must be done in blocks matching the bit count.
- The bit could should be rounded up so that it matches full bytes.
-
-LIRC_SET_{SEND,REC}_MODE
- Set send/receive mode. Largely obsolete for send, as only
- LIRC_MODE_PULSE is supported.
-
-LIRC_SET_{SEND,REC}_CARRIER
- Set send/receive carrier (in Hz).
-
-LIRC_SET_TRANSMITTER_MASK
- This enables the given set of transmitters. The first transmitter is
- encoded by the least significant bit, etc. When an invalid bit mask
- is given, i.e. a bit is set, even though the device does not have so
- many transitters, then this ioctl returns the number of available
- transitters and does nothing otherwise.
-
-LIRC_SET_REC_TIMEOUT
- Sets the integer value for IR inactivity timeout (cf.
- LIRC_GET_MIN_TIMEOUT and LIRC_GET_MAX_TIMEOUT). A value of 0
- (if supported by the hardware) disables all hardware timeouts and
- data should be reported as soon as possible. If the exact value
- cannot be set, then the next possible value _greater_ than the
- given value should be set.
-
-LIRC_SET_REC_TIMEOUT_REPORTS
- Enable (1) or disable (0) timeout reports in LIRC_MODE_MODE2. By
- default, timeout reports should be turned off.
-
-LIRC_SET_REC_FILTER_{,PULSE,SPACE}
- Pulses/spaces shorter than this are filtered out by hardware. If
- filters cannot be set independently for pulse/space, the
- corresponding ioctls must return an error and LIRC_SET_REC_FILTER
- shall be used instead.
-
-LIRC_SET_MEASURE_CARRIER_MODE
- Enable (1)/disable (0) measure mode. If enabled, from the next key
- press on, the driver will send LIRC_MODE2_FREQUENCY packets. By
- default this should be turned off.
-
-LIRC_SET_REC_{DUTY_CYCLE,CARRIER}_RANGE
- To set a range use
- LIRC_SET_REC_DUTY_CYCLE_RANGE/LIRC_SET_REC_CARRIER_RANGE
- with the lower bound first and later
- LIRC_SET_REC_DUTY_CYCLE/LIRC_SET_REC_CARRIER with the upper
- bound.
-
-LIRC_NOTIFY_DECODE
- This ioctl is called by lircd whenever a successful decoding of an
- incoming IR signal could be done. This can be used by supporting
- hardware to give visual feedback to the user e.g. by flashing a LED.
-
-LIRC_SETUP_{START,END}
- Setting of several driver parameters can be optimized by
- encapsulating the according ioctl calls with
- LIRC_SETUP_START/LIRC_SETUP_END. When a driver receives a
- LIRC_SETUP_START ioctl it can choose to not commit further setting
- changes to the hardware until a LIRC_SETUP_END is received. But
- this is open to the driver implementation and every driver must also
- handle parameter changes which are not encapsulated by
- LIRC_SETUP_START and LIRC_SETUP_END. Drivers can also choose to
- ignore these ioctls.
-
-LIRC_SET_WIDEBAND_RECEIVER
- Some receivers are equipped with special wide band receiver which is
- intended to be used to learn output of existing remote. Calling that
- ioctl with (1) will enable it, and with (0) disable it. This might
- be useful of receivers that have otherwise narrow band receiver that
- prevents them to be used with some remotes. Wide band receiver might
- also be more precise On the other hand its disadvantage it usually
- reduced range of reception. Note: wide band receiver might be
- implictly enabled if you enable carrier reports. In that case it
- will be disabled as soon as you disable carrier reports. Trying to
- disable wide band receiver while carrier reports are active will do
- nothing.
-
-
-.. _lirc_dev_errors:
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _lirc_read:
-
-*************
-LIRC read fop
-*************
-
-The lircd userspace daemon reads raw IR data from the LIRC chardev. The
-exact format of the data depends on what modes a driver supports, and
-what mode has been selected. lircd obtains supported modes and sets the
-active mode via the ioctl interface, detailed at :ref:`lirc_ioctl`.
-The generally preferred mode is LIRC_MODE_MODE2, in which packets
-containing an int value describing an IR signal are read from the
-chardev.
-
-See also
-`http://www.lirc.org/html/technical.html <http://www.lirc.org/html/technical.html>`__
-for more info.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _lirc_write:
-
-**************
-LIRC write fop
-**************
-
-The data written to the chardev is a pulse/space sequence of integer
-values. Pulses and spaces are only marked implicitly by their position.
-The data must start and end with a pulse, therefore, the data must
-always include an uneven number of samples. The write function must
-block until the data has been transmitted by the hardware. If more data
-is provided than the hardware can send, the driver returns ``EINVAL``.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. include:: <isonum.txt>
-
-.. _remotes:
-
-#####################
-Remote Controller API
-#####################
-
-.. _remote_controllers:
-
-******************
-Remote Controllers
-******************
-
-
-.. toctree::
- :maxdepth: 1
- :numbered:
-
- Remote_controllers_Intro
- remote_controllers_sysfs_nodes
- Remote_controllers_tables
- Remote_controllers_table_change
- lirc_device_interface
-
-
-**********************
-Revision and Copyright
-**********************
-
-Authors:
-
-- Carvalho Chehab, Mauro <mchehab@kernel.org>
-
- - Initial version.
-
-**Copyright** |copy| 2009-2016 : Mauro Carvalho Chehab
-
-****************
-Revision History
-****************
-
-:revision: 3.15 / 2014-02-06 (*mcc*)
-
-Added the interface description and the RC sysfs class description.
-
-
-:revision: 1.0 / 2009-09-06 (*mcc*)
-
-Initial revision
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _remote_controllers_sysfs_nodes:
-
-*******************************
-Remote Controller's sysfs nodes
-*******************************
-
-As defined at ``Documentation/ABI/testing/sysfs-class-rc``, those are
-the sysfs nodes that control the Remote Controllers:
-
-
-.. _sys_class_rc:
-
-/sys/class/rc/
-==============
-
-The ``/sys/class/rc/`` class sub-directory belongs to the Remote
-Controller core and provides a sysfs interface for configuring infrared
-remote controller receivers.
-
-
-.. _sys_class_rc_rcN:
-
-/sys/class/rc/rcN/
-==================
-
-A ``/sys/class/rc/rcN`` directory is created for each remote control
-receiver device where N is the number of the receiver.
-
-
-.. _sys_class_rc_rcN_protocols:
-
-/sys/class/rc/rcN/protocols
-===========================
-
-Reading this file returns a list of available protocols, something like:
-
-``rc5 [rc6] nec jvc [sony]``
-
-Enabled protocols are shown in [] brackets.
-
-Writing "+proto" will add a protocol to the list of enabled protocols.
-
-Writing "-proto" will remove a protocol from the list of enabled
-protocols.
-
-Writing "proto" will enable only "proto".
-
-Writing "none" will disable all protocols.
-
-Write fails with ``EINVAL`` if an invalid protocol combination or unknown
-protocol name is used.
-
-
-.. _sys_class_rc_rcN_filter:
-
-/sys/class/rc/rcN/filter
-========================
-
-Sets the scancode filter expected value.
-
-Use in combination with ``/sys/class/rc/rcN/filter_mask`` to set the
-expected value of the bits set in the filter mask. If the hardware
-supports it then scancodes which do not match the filter will be
-ignored. Otherwise the write will fail with an error.
-
-This value may be reset to 0 if the current protocol is altered.
-
-
-.. _sys_class_rc_rcN_filter_mask:
-
-/sys/class/rc/rcN/filter_mask
-=============================
-
-Sets the scancode filter mask of bits to compare. Use in combination
-with ``/sys/class/rc/rcN/filter`` to set the bits of the scancode which
-should be compared against the expected value. A value of 0 disables the
-filter to allow all valid scancodes to be processed.
-
-If the hardware supports it then scancodes which do not match the filter
-will be ignored. Otherwise the write will fail with an error.
-
-This value may be reset to 0 if the current protocol is altered.
-
-
-.. _sys_class_rc_rcN_wakeup_protocols:
-
-/sys/class/rc/rcN/wakeup_protocols
-==================================
-
-Reading this file returns a list of available protocols to use for the
-wakeup filter, something like:
-
-``rc5 rc6 nec jvc [sony]``
-
-The enabled wakeup protocol is shown in [] brackets.
-
-Writing "+proto" will add a protocol to the list of enabled wakeup
-protocols.
-
-Writing "-proto" will remove a protocol from the list of enabled wakeup
-protocols.
-
-Writing "proto" will use "proto" for wakeup events.
-
-Writing "none" will disable wakeup.
-
-Write fails with ``EINVAL`` if an invalid protocol combination or unknown
-protocol name is used, or if wakeup is not supported by the hardware.
-
-
-.. _sys_class_rc_rcN_wakeup_filter:
-
-/sys/class/rc/rcN/wakeup_filter
-===============================
-
-Sets the scancode wakeup filter expected value. Use in combination with
-``/sys/class/rc/rcN/wakeup_filter_mask`` to set the expected value of
-the bits set in the wakeup filter mask to trigger a system wake event.
-
-If the hardware supports it and wakeup_filter_mask is not 0 then
-scancodes which match the filter will wake the system from e.g. suspend
-to RAM or power off. Otherwise the write will fail with an error.
-
-This value may be reset to 0 if the wakeup protocol is altered.
-
-
-.. _sys_class_rc_rcN_wakeup_filter_mask:
-
-/sys/class/rc/rcN/wakeup_filter_mask
-====================================
-
-Sets the scancode wakeup filter mask of bits to compare. Use in
-combination with ``/sys/class/rc/rcN/wakeup_filter`` to set the bits of
-the scancode which should be compared against the expected value to
-trigger a system wake event.
-
-If the hardware supports it and wakeup_filter_mask is not 0 then
-scancodes which match the filter will wake the system from e.g. suspend
-to RAM or power off. Otherwise the write will fail with an error.
-
-This value may be reset to 0 if the wakeup protocol is altered.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _app-pri:
-
-********************
-Application Priority
-********************
-
-When multiple applications share a device it may be desirable to assign
-them different priorities. Contrary to the traditional "rm -rf /" school
-of thought a video recording application could for example block other
-applications from changing video controls or switching the current TV
-channel. Another objective is to permit low priority applications
-working in background, which can be preempted by user controlled
-applications and automatically regain control of the device at a later
-time.
-
-Since these features cannot be implemented entirely in user space V4L2
-defines the :ref:`VIDIOC_G_PRIORITY <VIDIOC_G_PRIORITY>` and
-:ref:`VIDIOC_S_PRIORITY <VIDIOC_G_PRIORITY>` ioctls to request and
-query the access priority associate with a file descriptor. Opening a
-device assigns a medium priority, compatible with earlier versions of
-V4L2 and drivers not supporting these ioctls. Applications requiring a
-different priority will usually call :ref:`VIDIOC_S_PRIORITY
-<VIDIOC_G_PRIORITY>` after verifying the device with the
-:ref:`VIDIOC_QUERYCAP` ioctl.
-
-Ioctls changing driver properties, such as
-:ref:`VIDIOC_S_INPUT <VIDIOC_G_INPUT>`, return an ``EBUSY`` error code
-after another application obtained higher priority.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _async:
-
-****************
-Asynchronous I/O
-****************
-
-This method is not defined yet.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _audio:
-
-************************
-Audio Inputs and Outputs
-************************
-
-Audio inputs and outputs are physical connectors of a device. Video
-capture devices have inputs, output devices have outputs, zero or more
-each. Radio devices have no audio inputs or outputs. They have exactly
-one tuner which in fact *is* an audio source, but this API associates
-tuners with video inputs or outputs only, and radio devices have none of
-these. [1]_ A connector on a TV card to loop back the received audio
-signal to a sound card is not considered an audio output.
-
-Audio and video inputs and outputs are associated. Selecting a video
-source also selects an audio source. This is most evident when the video
-and audio source is a tuner. Further audio connectors can combine with
-more than one video input or output. Assumed two composite video inputs
-and two audio inputs exist, there may be up to four valid combinations.
-The relation of video and audio connectors is defined in the
-``audioset`` field of the respective struct
-:ref:`v4l2_input <v4l2-input>` or struct
-:ref:`v4l2_output <v4l2-output>`, where each bit represents the index
-number, starting at zero, of one audio input or output.
-
-To learn about the number and attributes of the available inputs and
-outputs applications can enumerate them with the
-:ref:`VIDIOC_ENUMAUDIO` and
-:ref:`VIDIOC_ENUMAUDOUT <VIDIOC_ENUMAUDOUT>` ioctl, respectively.
-The struct :ref:`v4l2_audio <v4l2-audio>` returned by the
-:ref:`VIDIOC_ENUMAUDIO` ioctl also contains signal
-:status information applicable when the current audio input is queried.
-
-The :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` and
-:ref:`VIDIOC_G_AUDOUT <VIDIOC_G_AUDOUT>` ioctls report the current
-audio input and output, respectively. Note that, unlike
-:ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` and
-:ref:`VIDIOC_G_OUTPUT <VIDIOC_G_OUTPUT>` these ioctls return a
-structure as :ref:`VIDIOC_ENUMAUDIO` and
-:ref:`VIDIOC_ENUMAUDOUT <VIDIOC_ENUMAUDOUT>` do, not just an index.
-
-To select an audio input and change its properties applications call the
-:ref:`VIDIOC_S_AUDIO <VIDIOC_G_AUDIO>` ioctl. To select an audio
-output (which presently has no changeable properties) applications call
-the :ref:`VIDIOC_S_AUDOUT <VIDIOC_G_AUDOUT>` ioctl.
-
-Drivers must implement all audio input ioctls when the device has
-multiple selectable audio inputs, all audio output ioctls when the
-device has multiple selectable audio outputs. When the device has any
-audio inputs or outputs the driver must set the ``V4L2_CAP_AUDIO`` flag
-in the struct :ref:`v4l2_capability <v4l2-capability>` returned by
-the :ref:`VIDIOC_QUERYCAP` ioctl.
-
-
-.. code-block:: c
- :caption: Example 1.3. Information about the current audio input
-
- struct v4l2_audio audio;
-
- memset(&audio, 0, sizeof(audio));
-
- if (-1 == ioctl(fd, VIDIOC_G_AUDIO, &audio)) {
- perror("VIDIOC_G_AUDIO");
- exit(EXIT_FAILURE);
- }
-
- printf("Current input: %s\\n", audio.name);
-
-
-.. code-block:: c
- :caption: Example 1.4. Switching to the first audio input
-
- struct v4l2_audio audio;
-
- memset(&audio, 0, sizeof(audio)); /* clear audio.mode, audio.reserved */
-
- audio.index = 0;
-
- if (-1 == ioctl(fd, VIDIOC_S_AUDIO, &audio)) {
- perror("VIDIOC_S_AUDIO");
- exit(EXIT_FAILURE);
- }
-
-.. [1]
- Actually struct :ref:`v4l2_audio <v4l2-audio>` ought to have a
- ``tuner`` field like struct :ref:`v4l2_input <v4l2-input>`, not
- only making the API more consistent but also permitting radio devices
- with multiple tuners.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-**********
-References
-**********
-
-
-.. _cea608:
-
-CEA 608-E
-=========
-
-
-:title: CEA-608-E R-2014 "Line 21 Data Services"
-
-:author: Consumer Electronics Association (http://www.ce.org)
-
-.. _en300294:
-
-EN 300 294
-==========
-
-
-:title: EN 300 294 "625-line television Wide Screen Signalling (WSS)"
-
-:author: European Telecommunication Standards Institute (http://www.etsi.org)
-
-.. _ets300231:
-
-ETS 300 231
-===========
-
-
-:title: ETS 300 231 "Specification of the domestic video Programme Delivery Control system (PDC)"
-
-:author: European Telecommunication Standards Institute (http://www.etsi.org)
-
-.. _ets300706:
-
-ETS 300 706
-===========
-
-
-:title: ETS 300 706 "Enhanced Teletext specification"
-
-:author: European Telecommunication Standards Institute (http://www.etsi.org)
-
-.. _mpeg2part1:
-
-ISO 13818-1
-===========
-
-
-:title: ITU-T Rec. H.222.0 | ISO/IEC 13818-1 "Information technology — Generic coding of moving pictures and associated audio information: Systems"
-
-:author: International Telecommunication Union (http://www.itu.ch), International Organisation for Standardisation (http://www.iso.ch)
-
-.. _mpeg2part2:
-
-ISO 13818-2
-===========
-
-
-:title: ITU-T Rec. H.262 | ISO/IEC 13818-2 "Information technology — Generic coding of moving pictures and associated audio information: Video"
-
-:author: International Telecommunication Union (http://www.itu.ch), International Organisation for Standardisation (http://www.iso.ch)
-
-.. _itu470:
-
-ITU BT.470
-==========
-
-
-:title: ITU-R Recommendation BT.470-6 "Conventional Television Systems"
-
-:author: International Telecommunication Union (http://www.itu.ch)
-
-.. _itu601:
-
-ITU BT.601
-==========
-
-
-:title: ITU-R Recommendation BT.601-5 "Studio Encoding Parameters of Digital Television for Standard 4:3 and Wide-Screen 16:9 Aspect Ratios"
-
-:author: International Telecommunication Union (http://www.itu.ch)
-
-.. _itu653:
-
-ITU BT.653
-==========
-
-
-:title: ITU-R Recommendation BT.653-3 "Teletext systems"
-
-:author: International Telecommunication Union (http://www.itu.ch)
-
-.. _itu709:
-
-ITU BT.709
-==========
-
-
-:title: ITU-R Recommendation BT.709-5 "Parameter values for the HDTV standards for production and international programme exchange"
-
-:author: International Telecommunication Union (http://www.itu.ch)
-
-.. _itu1119:
-
-ITU BT.1119
-===========
-
-
-:title: ITU-R Recommendation BT.1119 "625-line television Wide Screen Signalling (WSS)"
-
-:author: International Telecommunication Union (http://www.itu.ch)
-
-.. _jfif:
-
-JFIF
-====
-
-
-:title: JPEG File Interchange Format
-:subtitle: Version 1.02
-
-:author: Independent JPEG Group (http://www.ijg.org)
-
-.. _itu-t81:
-
-ITU-T.81
-========
-
-
-:title: ITU-T Recommendation T.81 "Information Technology — Digital Compression and Coding of Continous-Tone Still Images — Requirements and Guidelines"
-
-:author: International Telecommunication Union (http://www.itu.int)
-
-.. _w3c-jpeg-jfif:
-
-W3C JPEG JFIF
-=============
-
-
-:title: JPEG JFIF
-
-:author: The World Wide Web Consortium (http://www.w3.org)
-
-.. _smpte12m:
-
-SMPTE 12M
-=========
-
-
-:title: SMPTE 12M-1999 "Television, Audio and Film - Time and Control Code"
-
-:author: Society of Motion Picture and Television Engineers (http://www.smpte.org)
-
-.. _smpte170m:
-
-SMPTE 170M
-==========
-
-
-:title: SMPTE 170M-1999 "Television - Composite Analog Video Signal - NTSC for Studio Applications"
-
-:author: Society of Motion Picture and Television Engineers (http://www.smpte.org)
-
-.. _smpte240m:
-
-SMPTE 240M
-==========
-
-
-:title: SMPTE 240M-1999 "Television - Signal Parameters - 1125-Line High-Definition Production"
-
-:author: Society of Motion Picture and Television Engineers (http://www.smpte.org)
-
-.. _smpte431:
-
-SMPTE RP 431-2
-==============
-
-
-:title: SMPTE RP 431-2:2011 "D-Cinema Quality - Reference Projector and Environment"
-
-:author: Society of Motion Picture and Television Engineers (http://www.smpte.org)
-
-.. _smpte2084:
-
-SMPTE ST 2084
-=============
-
-
-:title: SMPTE ST 2084:2014 "High Dynamic Range Electro-Optical Transfer Function of Master Reference Displays"
-
-:author: Society of Motion Picture and Television Engineers (http://www.smpte.org)
-
-.. _srgb:
-
-sRGB
-====
-
-
-:title: IEC 61966-2-1 ed1.0 "Multimedia systems and equipment - Colour measurement and management - Part 2-1: Colour management - Default RGB colour space - sRGB"
-
-:author: International Electrotechnical Commission (http://www.iec.ch)
-
-.. _sycc:
-
-sYCC
-====
-
-
-:title: IEC 61966-2-1-am1 ed1.0 "Amendment 1 - Multimedia systems and equipment - Colour measurement and management - Part 2-1: Colour management - Default RGB colour space - sRGB"
-
-:author: International Electrotechnical Commission (http://www.iec.ch)
-
-.. _xvycc:
-
-xvYCC
-=====
-
-
-:title: IEC 61966-2-4 ed1.0 "Multimedia systems and equipment - Colour measurement and management - Part 2-4: Colour management - Extended-gamut YCC colour space for video applications - xvYCC"
-
-:author: International Electrotechnical Commission (http://www.iec.ch)
-
-.. _adobergb:
-
-AdobeRGB
-========
-
-
-:title: Adobe© RGB (1998) Color Image Encoding Version 2005-05
-
-:author: Adobe Systems Incorporated (http://www.adobe.com)
-
-.. _oprgb:
-
-opRGB
-=====
-
-
-:title: IEC 61966-2-5 "Multimedia systems and equipment - Colour measurement and management - Part 2-5: Colour management - Optional RGB colour space - opRGB"
-
-:author: International Electrotechnical Commission (http://www.iec.ch)
-
-.. _itu2020:
-
-ITU BT.2020
-===========
-
-
-:title: ITU-R Recommendation BT.2020 (08/2012) "Parameter values for ultra-high definition television systems for production and international programme exchange"
-
-:author: International Telecommunication Union (http://www.itu.ch)
-
-.. _tech3213:
-
-EBU Tech 3213
-=============
-
-
-:title: E.B.U. Standard for Chromaticity Tolerances for Studio Monitors"
-
-:author: European Broadcast Union (http://www.ebu.ch)
-
-.. _iec62106:
-
-IEC 62106
-=========
-
-
-:title: Specification of the radio data system (RDS) for VHF/FM sound broadcasting in the frequency range from 87,5 to 108,0 MHz
-
-:author: International Electrotechnical Commission (http://www.iec.ch)
-
-.. _nrsc4:
-
-NRSC-4-B
-========
-
-
-:title: NRSC-4-B: United States RBDS Standard
-
-:author: National Radio Systems Committee (http://www.nrscstandards.org)
-
-.. _iso12232:
-
-ISO 12232:2006
-==============
-
-
-:title: Photography — Digital still cameras — Determination of exposure index, ISO speed ratings, standard output sensitivity, and recommended exposure index
-
-:author: International Organization for Standardization (http://www.iso.org)
-
-.. _cea861:
-
-CEA-861-E
-=========
-
-
-:title: A DTV Profile for Uncompressed High Speed Digital Interfaces
-
-:author: Consumer Electronics Association (http://www.ce.org)
-
-.. _vesadmt:
-
-VESA DMT
-========
-
-
-:title: VESA and Industry Standards and Guidelines for Computer Display Monitor Timing (DMT)
-
-:author: Video Electronics Standards Association (http://www.vesa.org)
-
-.. _vesaedid:
-
-EDID
-====
-
-
-:title: VESA Enhanced Extended Display Identification Data Standard
-:subtitle: Release A, Revision 2
-
-:author: Video Electronics Standards Association (http://www.vesa.org)
-
-.. _hdcp:
-
-HDCP
-====
-
-
-:title: High-bandwidth Digital Content Protection System
-:subtitle: Revision 1.3
-
-:author: Digital Content Protection LLC (http://www.digital-cp.com)
-
-.. _hdmi:
-
-HDMI
-====
-
-
-:title: High-Definition Multimedia Interface
-:subtitle: Specification Version 1.4a
-
-:author: HDMI Licensing LLC (http://www.hdmi.org)
-
-.. _dp:
-
-DP
-==
-
-
-:title: VESA DisplayPort Standard
-:subtitle: Version 1, Revision 2
-
-:author: Video Electronics Standards Association (http://www.vesa.org)
-
-.. _poynton:
-
-poynton
-=======
-
-
-:title: Digital Video and HDTV, Algorithms and Interfaces
-
-:author: Charles Poynton
-
-.. _colimg:
-
-colimg
-======
-
-
-:title: Color Imaging: Fundamentals and Applications
-
-:author: Erik Reinhard et al.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _buffer:
-
-*******
-Buffers
-*******
-
-A buffer contains data exchanged by application and driver using one of
-the Streaming I/O methods. In the multi-planar API, the data is held in
-planes, while the buffer structure acts as a container for the planes.
-Only pointers to buffers (planes) are exchanged, the data itself is not
-copied. These pointers, together with meta-information like timestamps
-or field parity, are stored in a struct :ref:`struct v4l2_buffer <v4l2-buffer>`,
-argument to the :ref:`VIDIOC_QUERYBUF`,
-:ref:`VIDIOC_QBUF` and
-:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. In the multi-planar API,
-some plane-specific members of struct :ref:`struct v4l2_buffer <v4l2-buffer>`,
-such as pointers and sizes for each plane, are stored in struct
-:ref:`struct v4l2_plane <v4l2-plane>` instead. In that case, struct
-:ref:`struct v4l2_buffer <v4l2-buffer>` contains an array of plane structures.
-
-Dequeued video buffers come with timestamps. The driver decides at which
-part of the frame and with which clock the timestamp is taken. Please
-see flags in the masks ``V4L2_BUF_FLAG_TIMESTAMP_MASK`` and
-``V4L2_BUF_FLAG_TSTAMP_SRC_MASK`` in :ref:`buffer-flags`. These flags
-are always valid and constant across all buffers during the whole video
-stream. Changes in these flags may take place as a side effect of
-:ref:`VIDIOC_S_INPUT <VIDIOC_G_INPUT>` or
-:ref:`VIDIOC_S_OUTPUT <VIDIOC_G_OUTPUT>` however. The
-``V4L2_BUF_FLAG_TIMESTAMP_COPY`` timestamp type which is used by e.g. on
-mem-to-mem devices is an exception to the rule: the timestamp source
-flags are copied from the OUTPUT video buffer to the CAPTURE video
-buffer.
-
-
-.. _v4l2-buffer:
-
-struct v4l2_buffer
-==================
-
-.. flat-table:: struct v4l2_buffer
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``index``
-
- -
- - Number of the buffer, set by the application except when calling
- :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, then it is set by the
- driver. This field can range from zero to the number of buffers
- allocated with the :ref:`VIDIOC_REQBUFS` ioctl
- (struct :ref:`v4l2_requestbuffers <v4l2-requestbuffers>`
- ``count``), plus any buffers allocated with
- :ref:`VIDIOC_CREATE_BUFS` minus one.
-
- - .. row 2
-
- - __u32
-
- - ``type``
-
- -
- - Type of the buffer, same as struct
- :ref:`v4l2_format <v4l2-format>` ``type`` or struct
- :ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``type``, set
- by the application. See :ref:`v4l2-buf-type`
-
- - .. row 3
-
- - __u32
-
- - ``bytesused``
-
- -
- - The number of bytes occupied by the data in the buffer. It depends
- on the negotiated data format and may change with each buffer for
- compressed variable size data like JPEG images. Drivers must set
- this field when ``type`` refers to a capture stream, applications
- when it refers to an output stream. If the application sets this
- to 0 for an output stream, then ``bytesused`` will be set to the
- size of the buffer (see the ``length`` field of this struct) by
- the driver. For multiplanar formats this field is ignored and the
- ``planes`` pointer is used instead.
-
- - .. row 4
-
- - __u32
-
- - ``flags``
-
- -
- - Flags set by the application or driver, see :ref:`buffer-flags`.
-
- - .. row 5
-
- - __u32
-
- - ``field``
-
- -
- - Indicates the field order of the image in the buffer, see
- :ref:`v4l2-field`. This field is not used when the buffer
- contains VBI data. Drivers must set it when ``type`` refers to a
- capture stream, applications when it refers to an output stream.
-
- - .. row 6
-
- - struct timeval
-
- - ``timestamp``
-
- -
- - For capture streams this is time when the first data byte was
- captured, as returned by the :c:func:`clock_gettime()` function
- for the relevant clock id; see ``V4L2_BUF_FLAG_TIMESTAMP_*`` in
- :ref:`buffer-flags`. For output streams the driver stores the
- time at which the last data byte was actually sent out in the
- ``timestamp`` field. This permits applications to monitor the
- drift between the video and system clock. For output streams that
- use ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` the application has to fill
- in the timestamp which will be copied by the driver to the capture
- stream.
-
- - .. row 7
-
- - struct :ref:`v4l2_timecode <v4l2-timecode>`
-
- - ``timecode``
-
- -
- - When ``type`` is ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` and the
- ``V4L2_BUF_FLAG_TIMECODE`` flag is set in ``flags``, this
- structure contains a frame timecode. In
- :ref:`V4L2_FIELD_ALTERNATE <v4l2-field>` mode the top and
- bottom field contain the same timecode. Timecodes are intended to
- help video editing and are typically recorded on video tapes, but
- also embedded in compressed formats like MPEG. This field is
- independent of the ``timestamp`` and ``sequence`` fields.
-
- - .. row 8
-
- - __u32
-
- - ``sequence``
-
- -
- - Set by the driver, counting the frames (not fields!) in sequence.
- This field is set for both input and output devices.
-
- - .. row 9
-
- - :cspan:`3`
-
- In :ref:`V4L2_FIELD_ALTERNATE <v4l2-field>` mode the top and
- bottom field have the same sequence number. The count starts at
- zero and includes dropped or repeated frames. A dropped frame was
- received by an input device but could not be stored due to lack of
- free buffer space. A repeated frame was displayed again by an
- output device because the application did not pass new data in
- time.
-
- Note this may count the frames received e.g. over USB, without
- taking into account the frames dropped by the remote hardware due
- to limited compression throughput or bus bandwidth. These devices
- identify by not enumerating any video standards, see
- :ref:`standard`.
-
- - .. row 10
-
- - __u32
-
- - ``memory``
-
- -
- - This field must be set by applications and/or drivers in
- accordance with the selected I/O method. See :ref:`v4l2-memory`
-
- - .. row 11
-
- - union
-
- - ``m``
-
- - .. row 12
-
- -
- - __u32
-
- - ``offset``
-
- - For the single-planar API and when ``memory`` is
- ``V4L2_MEMORY_MMAP`` this is the offset of the buffer from the
- start of the device memory. The value is returned by the driver
- and apart of serving as parameter to the
- :ref:`mmap() <func-mmap>` function not useful for applications.
- See :ref:`mmap` for details
-
- - .. row 13
-
- -
- - unsigned long
-
- - ``userptr``
-
- - For the single-planar API and when ``memory`` is
- ``V4L2_MEMORY_USERPTR`` this is a pointer to the buffer (casted to
- unsigned long type) in virtual memory, set by the application. See
- :ref:`userp` for details.
-
- - .. row 14
-
- -
- - struct v4l2_plane
-
- - ``*planes``
-
- - When using the multi-planar API, contains a userspace pointer to
- an array of struct :ref:`v4l2_plane <v4l2-plane>`. The size of
- the array should be put in the ``length`` field of this
- :ref:`struct v4l2_buffer <v4l2-buffer>` structure.
-
- - .. row 15
-
- -
- - int
-
- - ``fd``
-
- - For the single-plane API and when ``memory`` is
- ``V4L2_MEMORY_DMABUF`` this is the file descriptor associated with
- a DMABUF buffer.
-
- - .. row 16
-
- - __u32
-
- - ``length``
-
- -
- - Size of the buffer (not the payload) in bytes for the
- single-planar API. This is set by the driver based on the calls to
- :ref:`VIDIOC_REQBUFS` and/or
- :ref:`VIDIOC_CREATE_BUFS`. For the
- multi-planar API the application sets this to the number of
- elements in the ``planes`` array. The driver will fill in the
- actual number of valid elements in that array.
-
- - .. row 17
-
- - __u32
-
- - ``reserved2``
-
- -
- - A place holder for future extensions. Drivers and applications
- must set this to 0.
-
- - .. row 18
-
- - __u32
-
- - ``reserved``
-
- -
- - A place holder for future extensions. Drivers and applications
- must set this to 0.
-
-
-
-.. _v4l2-plane:
-
-struct v4l2_plane
-=================
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``bytesused``
-
- -
- - The number of bytes occupied by data in the plane (its payload).
- Drivers must set this field when ``type`` refers to a capture
- stream, applications when it refers to an output stream. If the
- application sets this to 0 for an output stream, then
- ``bytesused`` will be set to the size of the plane (see the
- ``length`` field of this struct) by the driver. Note that the
- actual image data starts at ``data_offset`` which may not be 0.
-
- - .. row 2
-
- - __u32
-
- - ``length``
-
- -
- - Size in bytes of the plane (not its payload). This is set by the
- driver based on the calls to
- :ref:`VIDIOC_REQBUFS` and/or
- :ref:`VIDIOC_CREATE_BUFS`.
-
- - .. row 3
-
- - union
-
- - ``m``
-
- -
- -
-
- - .. row 4
-
- -
- - __u32
-
- - ``mem_offset``
-
- - When the memory type in the containing struct
- :ref:`v4l2_buffer <v4l2-buffer>` is ``V4L2_MEMORY_MMAP``, this
- is the value that should be passed to :ref:`mmap() <func-mmap>`,
- similar to the ``offset`` field in struct
- :ref:`v4l2_buffer <v4l2-buffer>`.
-
- - .. row 5
-
- -
- - unsigned long
-
- - ``userptr``
-
- - When the memory type in the containing struct
- :ref:`v4l2_buffer <v4l2-buffer>` is ``V4L2_MEMORY_USERPTR``,
- this is a userspace pointer to the memory allocated for this plane
- by an application.
-
- - .. row 6
-
- -
- - int
-
- - ``fd``
-
- - When the memory type in the containing struct
- :ref:`v4l2_buffer <v4l2-buffer>` is ``V4L2_MEMORY_DMABUF``,
- this is a file descriptor associated with a DMABUF buffer, similar
- to the ``fd`` field in struct :ref:`v4l2_buffer <v4l2-buffer>`.
-
- - .. row 7
-
- - __u32
-
- - ``data_offset``
-
- -
- - Offset in bytes to video data in the plane. Drivers must set this
- field when ``type`` refers to a capture stream, applications when
- it refers to an output stream. Note that data_offset is included
- in ``bytesused``. So the size of the image in the plane is
- ``bytesused``-``data_offset`` at offset ``data_offset`` from the
- start of the plane.
-
- - .. row 8
-
- - __u32
-
- - ``reserved[11]``
-
- -
- - Reserved for future use. Should be zeroed by drivers and
- applications.
-
-
-
-.. _v4l2-buf-type:
-
-enum v4l2_buf_type
-==================
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - ``V4L2_BUF_TYPE_VIDEO_CAPTURE``
-
- - 1
-
- - Buffer of a single-planar video capture stream, see
- :ref:`capture`.
-
- - .. row 2
-
- - ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``
-
- - 9
-
- - Buffer of a multi-planar video capture stream, see
- :ref:`capture`.
-
- - .. row 3
-
- - ``V4L2_BUF_TYPE_VIDEO_OUTPUT``
-
- - 2
-
- - Buffer of a single-planar video output stream, see
- :ref:`output`.
-
- - .. row 4
-
- - ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``
-
- - 10
-
- - Buffer of a multi-planar video output stream, see :ref:`output`.
-
- - .. row 5
-
- - ``V4L2_BUF_TYPE_VIDEO_OVERLAY``
-
- - 3
-
- - Buffer for video overlay, see :ref:`overlay`.
-
- - .. row 6
-
- - ``V4L2_BUF_TYPE_VBI_CAPTURE``
-
- - 4
-
- - Buffer of a raw VBI capture stream, see :ref:`raw-vbi`.
-
- - .. row 7
-
- - ``V4L2_BUF_TYPE_VBI_OUTPUT``
-
- - 5
-
- - Buffer of a raw VBI output stream, see :ref:`raw-vbi`.
-
- - .. row 8
-
- - ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE``
-
- - 6
-
- - Buffer of a sliced VBI capture stream, see :ref:`sliced`.
-
- - .. row 9
-
- - ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT``
-
- - 7
-
- - Buffer of a sliced VBI output stream, see :ref:`sliced`.
-
- - .. row 10
-
- - ``V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY``
-
- - 8
-
- - Buffer for video output overlay (OSD), see :ref:`osd`.
-
- - .. row 11
-
- - ``V4L2_BUF_TYPE_SDR_CAPTURE``
-
- - 11
-
- - Buffer for Software Defined Radio (SDR) capture stream, see
- :ref:`sdr`.
-
- - .. row 12
-
- - ``V4L2_BUF_TYPE_SDR_OUTPUT``
-
- - 12
-
- - Buffer for Software Defined Radio (SDR) output stream, see
- :ref:`sdr`.
-
-
-
-.. _buffer-flags:
-
-Buffer Flags
-============
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - ``V4L2_BUF_FLAG_MAPPED``
-
- - 0x00000001
-
- - The buffer resides in device memory and has been mapped into the
- application's address space, see :ref:`mmap` for details.
- Drivers set or clear this flag when the
- :ref:`VIDIOC_QUERYBUF`,
- :ref:`VIDIOC_QBUF` or
- :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called. Set by the
- driver.
-
- - .. row 2
-
- - ``V4L2_BUF_FLAG_QUEUED``
-
- - 0x00000002
-
- - Internally drivers maintain two buffer queues, an incoming and
- outgoing queue. When this flag is set, the buffer is currently on
- the incoming queue. It automatically moves to the outgoing queue
- after the buffer has been filled (capture devices) or displayed
- (output devices). Drivers set or clear this flag when the
- ``VIDIOC_QUERYBUF`` ioctl is called. After (successful) calling
- the ``VIDIOC_QBUF``\ ioctl it is always set and after
- ``VIDIOC_DQBUF`` always cleared.
-
- - .. row 3
-
- - ``V4L2_BUF_FLAG_DONE``
-
- - 0x00000004
-
- - When this flag is set, the buffer is currently on the outgoing
- queue, ready to be dequeued from the driver. Drivers set or clear
- this flag when the ``VIDIOC_QUERYBUF`` ioctl is called. After
- calling the ``VIDIOC_QBUF`` or ``VIDIOC_DQBUF`` it is always
- cleared. Of course a buffer cannot be on both queues at the same
- time, the ``V4L2_BUF_FLAG_QUEUED`` and ``V4L2_BUF_FLAG_DONE`` flag
- are mutually exclusive. They can be both cleared however, then the
- buffer is in "dequeued" state, in the application domain so to
- say.
-
- - .. row 4
-
- - ``V4L2_BUF_FLAG_ERROR``
-
- - 0x00000040
-
- - When this flag is set, the buffer has been dequeued successfully,
- although the data might have been corrupted. This is recoverable,
- streaming may continue as normal and the buffer may be reused
- normally. Drivers set this flag when the ``VIDIOC_DQBUF`` ioctl is
- called.
-
- - .. row 5
-
- - ``V4L2_BUF_FLAG_KEYFRAME``
-
- - 0x00000008
-
- - Drivers set or clear this flag when calling the ``VIDIOC_DQBUF``
- ioctl. It may be set by video capture devices when the buffer
- contains a compressed image which is a key frame (or field), i. e.
- can be decompressed on its own. Also known as an I-frame.
- Applications can set this bit when ``type`` refers to an output
- stream.
-
- - .. row 6
-
- - ``V4L2_BUF_FLAG_PFRAME``
-
- - 0x00000010
-
- - Similar to ``V4L2_BUF_FLAG_KEYFRAME`` this flags predicted frames
- or fields which contain only differences to a previous key frame.
- Applications can set this bit when ``type`` refers to an output
- stream.
-
- - .. row 7
-
- - ``V4L2_BUF_FLAG_BFRAME``
-
- - 0x00000020
-
- - Similar to ``V4L2_BUF_FLAG_KEYFRAME`` this flags a bi-directional
- predicted frame or field which contains only the differences
- between the current frame and both the preceding and following key
- frames to specify its content. Applications can set this bit when
- ``type`` refers to an output stream.
-
- - .. row 8
-
- - ``V4L2_BUF_FLAG_TIMECODE``
-
- - 0x00000100
-
- - The ``timecode`` field is valid. Drivers set or clear this flag
- when the ``VIDIOC_DQBUF`` ioctl is called. Applications can set
- this bit and the corresponding ``timecode`` structure when
- ``type`` refers to an output stream.
-
- - .. row 9
-
- - ``V4L2_BUF_FLAG_PREPARED``
-
- - 0x00000400
-
- - The buffer has been prepared for I/O and can be queued by the
- application. Drivers set or clear this flag when the
- :ref:`VIDIOC_QUERYBUF`,
- :ref:`VIDIOC_PREPARE_BUF <VIDIOC_QBUF>`,
- :ref:`VIDIOC_QBUF` or
- :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called.
-
- - .. row 10
-
- - ``V4L2_BUF_FLAG_NO_CACHE_INVALIDATE``
-
- - 0x00000800
-
- - Caches do not have to be invalidated for this buffer. Typically
- applications shall use this flag if the data captured in the
- buffer is not going to be touched by the CPU, instead the buffer
- will, probably, be passed on to a DMA-capable hardware unit for
- further processing or output.
-
- - .. row 11
-
- - ``V4L2_BUF_FLAG_NO_CACHE_CLEAN``
-
- - 0x00001000
-
- - Caches do not have to be cleaned for this buffer. Typically
- applications shall use this flag for output buffers if the data in
- this buffer has not been created by the CPU but by some
- DMA-capable unit, in which case caches have not been used.
-
- - .. row 12
-
- - ``V4L2_BUF_FLAG_LAST``
-
- - 0x00100000
-
- - Last buffer produced by the hardware. mem2mem codec drivers set
- this flag on the capture queue for the last buffer when the
- :ref:`VIDIOC_QUERYBUF` or
- :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called. Due to
- hardware limitations, the last buffer may be empty. In this case
- the driver will set the ``bytesused`` field to 0, regardless of
- the format. Any Any subsequent call to the
- :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will not block anymore,
- but return an ``EPIPE`` error code.
-
- - .. row 13
-
- - ``V4L2_BUF_FLAG_TIMESTAMP_MASK``
-
- - 0x0000e000
-
- - Mask for timestamp types below. To test the timestamp type, mask
- out bits not belonging to timestamp type by performing a logical
- and operation with buffer flags and timestamp mask.
-
- - .. row 14
-
- - ``V4L2_BUF_FLAG_TIMESTAMP_UNKNOWN``
-
- - 0x00000000
-
- - Unknown timestamp type. This type is used by drivers before Linux
- 3.9 and may be either monotonic (see below) or realtime (wall
- clock). Monotonic clock has been favoured in embedded systems
- whereas most of the drivers use the realtime clock. Either kinds
- of timestamps are available in user space via
- :c:func:`clock_gettime(2)` using clock IDs ``CLOCK_MONOTONIC``
- and ``CLOCK_REALTIME``, respectively.
-
- - .. row 15
-
- - ``V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC``
-
- - 0x00002000
-
- - The buffer timestamp has been taken from the ``CLOCK_MONOTONIC``
- clock. To access the same clock outside V4L2, use
- :c:func:`clock_gettime(2)`.
-
- - .. row 16
-
- - ``V4L2_BUF_FLAG_TIMESTAMP_COPY``
-
- - 0x00004000
-
- - The CAPTURE buffer timestamp has been taken from the corresponding
- OUTPUT buffer. This flag applies only to mem2mem devices.
-
- - .. row 17
-
- - ``V4L2_BUF_FLAG_TSTAMP_SRC_MASK``
-
- - 0x00070000
-
- - Mask for timestamp sources below. The timestamp source defines the
- point of time the timestamp is taken in relation to the frame.
- Logical 'and' operation between the ``flags`` field and
- ``V4L2_BUF_FLAG_TSTAMP_SRC_MASK`` produces the value of the
- timestamp source. Applications must set the timestamp source when
- ``type`` refers to an output stream and
- ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` is set.
-
- - .. row 18
-
- - ``V4L2_BUF_FLAG_TSTAMP_SRC_EOF``
-
- - 0x00000000
-
- - End Of Frame. The buffer timestamp has been taken when the last
- pixel of the frame has been received or the last pixel of the
- frame has been transmitted. In practice, software generated
- timestamps will typically be read from the clock a small amount of
- time after the last pixel has been received or transmitten,
- depending on the system and other activity in it.
-
- - .. row 19
-
- - ``V4L2_BUF_FLAG_TSTAMP_SRC_SOE``
-
- - 0x00010000
-
- - Start Of Exposure. The buffer timestamp has been taken when the
- exposure of the frame has begun. This is only valid for the
- ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` buffer type.
-
-
-
-.. _v4l2-memory:
-
-enum v4l2_memory
-================
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - ``V4L2_MEMORY_MMAP``
-
- - 1
-
- - The buffer is used for :ref:`memory mapping <mmap>` I/O.
-
- - .. row 2
-
- - ``V4L2_MEMORY_USERPTR``
-
- - 2
-
- - The buffer is used for :ref:`user pointer <userp>` I/O.
-
- - .. row 3
-
- - ``V4L2_MEMORY_OVERLAY``
-
- - 3
-
- - [to do]
-
- - .. row 4
-
- - ``V4L2_MEMORY_DMABUF``
-
- - 4
-
- - The buffer is used for :ref:`DMA shared buffer <dmabuf>` I/O.
-
-
-
-Timecodes
-=========
-
-The :ref:`struct v4l2_timecode <v4l2-timecode>` structure is designed to hold a
-:ref:`smpte12m` or similar timecode. (struct
-:c:type:`struct timeval` timestamps are stored in struct
-:ref:`v4l2_buffer <v4l2-buffer>` field ``timestamp``.)
-
-
-.. _v4l2-timecode:
-
-struct v4l2_timecode
---------------------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``type``
-
- - Frame rate the timecodes are based on, see :ref:`timecode-type`.
-
- - .. row 2
-
- - __u32
-
- - ``flags``
-
- - Timecode flags, see :ref:`timecode-flags`.
-
- - .. row 3
-
- - __u8
-
- - ``frames``
-
- - Frame count, 0 ... 23/24/29/49/59, depending on the type of
- timecode.
-
- - .. row 4
-
- - __u8
-
- - ``seconds``
-
- - Seconds count, 0 ... 59. This is a binary, not BCD number.
-
- - .. row 5
-
- - __u8
-
- - ``minutes``
-
- - Minutes count, 0 ... 59. This is a binary, not BCD number.
-
- - .. row 6
-
- - __u8
-
- - ``hours``
-
- - Hours count, 0 ... 29. This is a binary, not BCD number.
-
- - .. row 7
-
- - __u8
-
- - ``userbits``\ [4]
-
- - The "user group" bits from the timecode.
-
-
-
-.. _timecode-type:
-
-Timecode Types
---------------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - ``V4L2_TC_TYPE_24FPS``
-
- - 1
-
- - 24 frames per second, i. e. film.
-
- - .. row 2
-
- - ``V4L2_TC_TYPE_25FPS``
-
- - 2
-
- - 25 frames per second, i. e. PAL or SECAM video.
-
- - .. row 3
-
- - ``V4L2_TC_TYPE_30FPS``
-
- - 3
-
- - 30 frames per second, i. e. NTSC video.
-
- - .. row 4
-
- - ``V4L2_TC_TYPE_50FPS``
-
- - 4
-
- -
-
- - .. row 5
-
- - ``V4L2_TC_TYPE_60FPS``
-
- - 5
-
- -
-
-
-
-.. _timecode-flags:
-
-Timecode Flags
---------------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - ``V4L2_TC_FLAG_DROPFRAME``
-
- - 0x0001
-
- - Indicates "drop frame" semantics for counting frames in 29.97 fps
- material. When set, frame numbers 0 and 1 at the start of each
- minute, except minutes 0, 10, 20, 30, 40, 50 are omitted from the
- count.
-
- - .. row 2
-
- - ``V4L2_TC_FLAG_COLORFRAME``
-
- - 0x0002
-
- - The "color frame" flag.
-
- - .. row 3
-
- - ``V4L2_TC_USERBITS_field``
-
- - 0x000C
-
- - Field mask for the "binary group flags".
-
- - .. row 4
-
- - ``V4L2_TC_USERBITS_USERDEFINED``
-
- - 0x0000
-
- - Unspecified format.
-
- - .. row 5
-
- - ``V4L2_TC_USERBITS_8BITCHARS``
-
- - 0x0008
-
- - 8-bit ISO characters.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _capture-example:
-
-*********************
-Video Capture Example
-*********************
-
-
-.. toctree::
- :maxdepth: 1
-
- capture.c
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-file: media/v4l/capture.c
-=========================
-
-.. code-block:: c
-
- /*
- * V4L2 video capture example
- *
- * This program can be used and distributed without restrictions.
- *
- * This program is provided with the V4L2 API
- * see https://linuxtv.org/docs.php for more information
- */
-
- #include <stdio.h>
- #include <stdlib.h>
- #include <string.h>
- #include <assert.h>
-
- #include <getopt.h> /* getopt_long() */
-
- #include <fcntl.h> /* low-level i/o */
- #include <unistd.h>
- #include <errno.h>
- #include <sys/stat.h>
- #include <sys/types.h>
- #include <sys/time.h>
- #include <sys/mman.h>
- #include <sys/ioctl.h>
-
- #include <linux/videodev2.h>
-
- #define CLEAR(x) memset(&(x), 0, sizeof(x))
-
- enum io_method {
- IO_METHOD_READ,
- IO_METHOD_MMAP,
- IO_METHOD_USERPTR,
- };
-
- struct buffer {
- void *start;
- size_t length;
- };
-
- static char *dev_name;
- static enum io_method io = IO_METHOD_MMAP;
- static int fd = -1;
- struct buffer *buffers;
- static unsigned int n_buffers;
- static int out_buf;
- static int force_format;
- static int frame_count = 70;
-
- static void errno_exit(const char *s)
- {
- fprintf(stderr, "%s error %d, %s\\n", s, errno, strerror(errno));
- exit(EXIT_FAILURE);
- }
-
- static int xioctl(int fh, int request, void *arg)
- {
- int r;
-
- do {
- r = ioctl(fh, request, arg);
- } while (-1 == r && EINTR == errno);
-
- return r;
- }
-
- static void process_image(const void *p, int size)
- {
- if (out_buf)
- fwrite(p, size, 1, stdout);
-
- fflush(stderr);
- fprintf(stderr, ".");
- fflush(stdout);
- }
-
- static int read_frame(void)
- {
- struct v4l2_buffer buf;
- unsigned int i;
-
- switch (io) {
- case IO_METHOD_READ:
- if (-1 == read(fd, buffers[0].start, buffers[0].length)) {
- switch (errno) {
- case EAGAIN:
- return 0;
-
- case EIO:
- /* Could ignore EIO, see spec. */
-
- /* fall through */
-
- default:
- errno_exit("read");
- }
- }
-
- process_image(buffers[0].start, buffers[0].length);
- break;
-
- case IO_METHOD_MMAP:
- CLEAR(buf);
-
- buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- buf.memory = V4L2_MEMORY_MMAP;
-
- if (-1 == xioctl(fd, VIDIOC_DQBUF, &buf)) {
- switch (errno) {
- case EAGAIN:
- return 0;
-
- case EIO:
- /* Could ignore EIO, see spec. */
-
- /* fall through */
-
- default:
- errno_exit("VIDIOC_DQBUF");
- }
- }
-
- assert(buf.index < n_buffers);
-
- process_image(buffers[buf.index].start, buf.bytesused);
-
- if (-1 == xioctl(fd, VIDIOC_QBUF, &buf))
- errno_exit("VIDIOC_QBUF");
- break;
-
- case IO_METHOD_USERPTR:
- CLEAR(buf);
-
- buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- buf.memory = V4L2_MEMORY_USERPTR;
-
- if (-1 == xioctl(fd, VIDIOC_DQBUF, &buf)) {
- switch (errno) {
- case EAGAIN:
- return 0;
-
- case EIO:
- /* Could ignore EIO, see spec. */
-
- /* fall through */
-
- default:
- errno_exit("VIDIOC_DQBUF");
- }
- }
-
- for (i = 0; i < n_buffers; ++i)
- if (buf.m.userptr == (unsigned long)buffers[i].start
- && buf.length == buffers[i].length)
- break;
-
- assert(i < n_buffers);
-
- process_image((void *)buf.m.userptr, buf.bytesused);
-
- if (-1 == xioctl(fd, VIDIOC_QBUF, &buf))
- errno_exit("VIDIOC_QBUF");
- break;
- }
-
- return 1;
- }
-
- static void mainloop(void)
- {
- unsigned int count;
-
- count = frame_count;
-
- while (count-- > 0) {
- for (;;) {
- fd_set fds;
- struct timeval tv;
- int r;
-
- FD_ZERO(&fds);
- FD_SET(fd, &fds);
-
- /* Timeout. */
- tv.tv_sec = 2;
- tv.tv_usec = 0;
-
- r = select(fd + 1, &fds, NULL, NULL, &tv);
-
- if (-1 == r) {
- if (EINTR == errno)
- continue;
- errno_exit("select");
- }
-
- if (0 == r) {
- fprintf(stderr, "select timeout\\n");
- exit(EXIT_FAILURE);
- }
-
- if (read_frame())
- break;
- /* EAGAIN - continue select loop. */
- }
- }
- }
-
- static void stop_capturing(void)
- {
- enum v4l2_buf_type type;
-
- switch (io) {
- case IO_METHOD_READ:
- /* Nothing to do. */
- break;
-
- case IO_METHOD_MMAP:
- case IO_METHOD_USERPTR:
- type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- if (-1 == xioctl(fd, VIDIOC_STREAMOFF, &type))
- errno_exit("VIDIOC_STREAMOFF");
- break;
- }
- }
-
- static void start_capturing(void)
- {
- unsigned int i;
- enum v4l2_buf_type type;
-
- switch (io) {
- case IO_METHOD_READ:
- /* Nothing to do. */
- break;
-
- case IO_METHOD_MMAP:
- for (i = 0; i < n_buffers; ++i) {
- struct v4l2_buffer buf;
-
- CLEAR(buf);
- buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- buf.memory = V4L2_MEMORY_MMAP;
- buf.index = i;
-
- if (-1 == xioctl(fd, VIDIOC_QBUF, &buf))
- errno_exit("VIDIOC_QBUF");
- }
- type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- if (-1 == xioctl(fd, VIDIOC_STREAMON, &type))
- errno_exit("VIDIOC_STREAMON");
- break;
-
- case IO_METHOD_USERPTR:
- for (i = 0; i < n_buffers; ++i) {
- struct v4l2_buffer buf;
-
- CLEAR(buf);
- buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- buf.memory = V4L2_MEMORY_USERPTR;
- buf.index = i;
- buf.m.userptr = (unsigned long)buffers[i].start;
- buf.length = buffers[i].length;
-
- if (-1 == xioctl(fd, VIDIOC_QBUF, &buf))
- errno_exit("VIDIOC_QBUF");
- }
- type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- if (-1 == xioctl(fd, VIDIOC_STREAMON, &type))
- errno_exit("VIDIOC_STREAMON");
- break;
- }
- }
-
- static void uninit_device(void)
- {
- unsigned int i;
-
- switch (io) {
- case IO_METHOD_READ:
- free(buffers[0].start);
- break;
-
- case IO_METHOD_MMAP:
- for (i = 0; i < n_buffers; ++i)
- if (-1 == munmap(buffers[i].start, buffers[i].length))
- errno_exit("munmap");
- break;
-
- case IO_METHOD_USERPTR:
- for (i = 0; i < n_buffers; ++i)
- free(buffers[i].start);
- break;
- }
-
- free(buffers);
- }
-
- static void init_read(unsigned int buffer_size)
- {
- buffers = calloc(1, sizeof(*buffers));
-
- if (!buffers) {
- fprintf(stderr, "Out of memory\\n");
- exit(EXIT_FAILURE);
- }
-
- buffers[0].length = buffer_size;
- buffers[0].start = malloc(buffer_size);
-
- if (!buffers[0].start) {
- fprintf(stderr, "Out of memory\\n");
- exit(EXIT_FAILURE);
- }
- }
-
- static void init_mmap(void)
- {
- struct v4l2_requestbuffers req;
-
- CLEAR(req);
-
- req.count = 4;
- req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- req.memory = V4L2_MEMORY_MMAP;
-
- if (-1 == xioctl(fd, VIDIOC_REQBUFS, &req)) {
- if (EINVAL == errno) {
- fprintf(stderr, "%s does not support "
- "memory mappingn", dev_name);
- exit(EXIT_FAILURE);
- } else {
- errno_exit("VIDIOC_REQBUFS");
- }
- }
-
- if (req.count < 2) {
- fprintf(stderr, "Insufficient buffer memory on %s\\n",
- dev_name);
- exit(EXIT_FAILURE);
- }
-
- buffers = calloc(req.count, sizeof(*buffers));
-
- if (!buffers) {
- fprintf(stderr, "Out of memory\\n");
- exit(EXIT_FAILURE);
- }
-
- for (n_buffers = 0; n_buffers < req.count; ++n_buffers) {
- struct v4l2_buffer buf;
-
- CLEAR(buf);
-
- buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- buf.memory = V4L2_MEMORY_MMAP;
- buf.index = n_buffers;
-
- if (-1 == xioctl(fd, VIDIOC_QUERYBUF, &buf))
- errno_exit("VIDIOC_QUERYBUF");
-
- buffers[n_buffers].length = buf.length;
- buffers[n_buffers].start =
- mmap(NULL /* start anywhere */,
- buf.length,
- PROT_READ | PROT_WRITE /* required */,
- MAP_SHARED /* recommended */,
- fd, buf.m.offset);
-
- if (MAP_FAILED == buffers[n_buffers].start)
- errno_exit("mmap");
- }
- }
-
- static void init_userp(unsigned int buffer_size)
- {
- struct v4l2_requestbuffers req;
-
- CLEAR(req);
-
- req.count = 4;
- req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- req.memory = V4L2_MEMORY_USERPTR;
-
- if (-1 == xioctl(fd, VIDIOC_REQBUFS, &req)) {
- if (EINVAL == errno) {
- fprintf(stderr, "%s does not support "
- "user pointer i/on", dev_name);
- exit(EXIT_FAILURE);
- } else {
- errno_exit("VIDIOC_REQBUFS");
- }
- }
-
- buffers = calloc(4, sizeof(*buffers));
-
- if (!buffers) {
- fprintf(stderr, "Out of memory\\n");
- exit(EXIT_FAILURE);
- }
-
- for (n_buffers = 0; n_buffers < 4; ++n_buffers) {
- buffers[n_buffers].length = buffer_size;
- buffers[n_buffers].start = malloc(buffer_size);
-
- if (!buffers[n_buffers].start) {
- fprintf(stderr, "Out of memory\\n");
- exit(EXIT_FAILURE);
- }
- }
- }
-
- static void init_device(void)
- {
- struct v4l2_capability cap;
- struct v4l2_cropcap cropcap;
- struct v4l2_crop crop;
- struct v4l2_format fmt;
- unsigned int min;
-
- if (-1 == xioctl(fd, VIDIOC_QUERYCAP, &cap)) {
- if (EINVAL == errno) {
- fprintf(stderr, "%s is no V4L2 device\\n",
- dev_name);
- exit(EXIT_FAILURE);
- } else {
- errno_exit("VIDIOC_QUERYCAP");
- }
- }
-
- if (!(cap.capabilities & V4L2_CAP_VIDEO_CAPTURE)) {
- fprintf(stderr, "%s is no video capture device\\n",
- dev_name);
- exit(EXIT_FAILURE);
- }
-
- switch (io) {
- case IO_METHOD_READ:
- if (!(cap.capabilities & V4L2_CAP_READWRITE)) {
- fprintf(stderr, "%s does not support read i/o\\n",
- dev_name);
- exit(EXIT_FAILURE);
- }
- break;
-
- case IO_METHOD_MMAP:
- case IO_METHOD_USERPTR:
- if (!(cap.capabilities & V4L2_CAP_STREAMING)) {
- fprintf(stderr, "%s does not support streaming i/o\\n",
- dev_name);
- exit(EXIT_FAILURE);
- }
- break;
- }
-
-
- /* Select video input, video standard and tune here. */
-
-
- CLEAR(cropcap);
-
- cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
-
- if (0 == xioctl(fd, VIDIOC_CROPCAP, &cropcap)) {
- crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- crop.c = cropcap.defrect; /* reset to default */
-
- if (-1 == xioctl(fd, VIDIOC_S_CROP, &crop)) {
- switch (errno) {
- case EINVAL:
- /* Cropping not supported. */
- break;
- default:
- /* Errors ignored. */
- break;
- }
- }
- } else {
- /* Errors ignored. */
- }
-
-
- CLEAR(fmt);
-
- fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- if (force_format) {
- fmt.fmt.pix.width = 640;
- fmt.fmt.pix.height = 480;
- fmt.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV;
- fmt.fmt.pix.field = V4L2_FIELD_INTERLACED;
-
- if (-1 == xioctl(fd, VIDIOC_S_FMT, &fmt))
- errno_exit("VIDIOC_S_FMT");
-
- /* Note VIDIOC_S_FMT may change width and height. */
- } else {
- /* Preserve original settings as set by v4l2-ctl for example */
- if (-1 == xioctl(fd, VIDIOC_G_FMT, &fmt))
- errno_exit("VIDIOC_G_FMT");
- }
-
- /* Buggy driver paranoia. */
- min = fmt.fmt.pix.width * 2;
- if (fmt.fmt.pix.bytesperline < min)
- fmt.fmt.pix.bytesperline = min;
- min = fmt.fmt.pix.bytesperline * fmt.fmt.pix.height;
- if (fmt.fmt.pix.sizeimage < min)
- fmt.fmt.pix.sizeimage = min;
-
- switch (io) {
- case IO_METHOD_READ:
- init_read(fmt.fmt.pix.sizeimage);
- break;
-
- case IO_METHOD_MMAP:
- init_mmap();
- break;
-
- case IO_METHOD_USERPTR:
- init_userp(fmt.fmt.pix.sizeimage);
- break;
- }
- }
-
- static void close_device(void)
- {
- if (-1 == close(fd))
- errno_exit("close");
-
- fd = -1;
- }
-
- static void open_device(void)
- {
- struct stat st;
-
- if (-1 == stat(dev_name, &st)) {
- fprintf(stderr, "Cannot identify '%s': %d, %s\\n",
- dev_name, errno, strerror(errno));
- exit(EXIT_FAILURE);
- }
-
- if (!S_ISCHR(st.st_mode)) {
- fprintf(stderr, "%s is no devicen", dev_name);
- exit(EXIT_FAILURE);
- }
-
- fd = open(dev_name, O_RDWR /* required */ | O_NONBLOCK, 0);
-
- if (-1 == fd) {
- fprintf(stderr, "Cannot open '%s': %d, %s\\n",
- dev_name, errno, strerror(errno));
- exit(EXIT_FAILURE);
- }
- }
-
- static void usage(FILE *fp, int argc, char **argv)
- {
- fprintf(fp,
- "Usage: %s [options]\\n\\n"
- "Version 1.3\\n"
- "Options:\\n"
- "-d | --device name Video device name [%s]n"
- "-h | --help Print this messagen"
- "-m | --mmap Use memory mapped buffers [default]n"
- "-r | --read Use read() callsn"
- "-u | --userp Use application allocated buffersn"
- "-o | --output Outputs stream to stdoutn"
- "-f | --format Force format to 640x480 YUYVn"
- "-c | --count Number of frames to grab [%i]n"
- "",
- argv[0], dev_name, frame_count);
- }
-
- static const char short_options[] = "d:hmruofc:";
-
- static const struct option
- long_options[] = {
- { "device", required_argument, NULL, 'd' },
- { "help", no_argument, NULL, 'h' },
- { "mmap", no_argument, NULL, 'm' },
- { "read", no_argument, NULL, 'r' },
- { "userp", no_argument, NULL, 'u' },
- { "output", no_argument, NULL, 'o' },
- { "format", no_argument, NULL, 'f' },
- { "count", required_argument, NULL, 'c' },
- { 0, 0, 0, 0 }
- };
-
- int main(int argc, char **argv)
- {
- dev_name = "/dev/video0";
-
- for (;;) {
- int idx;
- int c;
-
- c = getopt_long(argc, argv,
- short_options, long_options, &idx);
-
- if (-1 == c)
- break;
-
- switch (c) {
- case 0: /* getopt_long() flag */
- break;
-
- case 'd':
- dev_name = optarg;
- break;
-
- case 'h':
- usage(stdout, argc, argv);
- exit(EXIT_SUCCESS);
-
- case 'm':
- io = IO_METHOD_MMAP;
- break;
-
- case 'r':
- io = IO_METHOD_READ;
- break;
-
- case 'u':
- io = IO_METHOD_USERPTR;
- break;
-
- case 'o':
- out_buf++;
- break;
-
- case 'f':
- force_format++;
- break;
-
- case 'c':
- errno = 0;
- frame_count = strtol(optarg, NULL, 0);
- if (errno)
- errno_exit(optarg);
- break;
-
- default:
- usage(stderr, argc, argv);
- exit(EXIT_FAILURE);
- }
- }
-
- open_device();
- init_device();
- start_capturing();
- mainloop();
- stop_capturing();
- uninit_device();
- close_device();
- fprintf(stderr, "\\n");
- return 0;
- }
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _colorspaces:
-
-***********
-Colorspaces
-***********
-
-'Color' is a very complex concept and depends on physics, chemistry and
-biology. Just because you have three numbers that describe the 'red',
-'green' and 'blue' components of the color of a pixel does not mean that
-you can accurately display that color. A colorspace defines what it
-actually *means* to have an RGB value of e.g. (255, 0, 0). That is,
-which color should be reproduced on the screen in a perfectly calibrated
-environment.
-
-In order to do that we first need to have a good definition of color,
-i.e. some way to uniquely and unambiguously define a color so that
-someone else can reproduce it. Human color vision is trichromatic since
-the human eye has color receptors that are sensitive to three different
-wavelengths of light. Hence the need to use three numbers to describe
-color. Be glad you are not a mantis shrimp as those are sensitive to 12
-different wavelengths, so instead of RGB we would be using the
-ABCDEFGHIJKL colorspace...
-
-Color exists only in the eye and brain and is the result of how strongly
-color receptors are stimulated. This is based on the Spectral Power
-Distribution (SPD) which is a graph showing the intensity (radiant
-power) of the light at wavelengths covering the visible spectrum as it
-enters the eye. The science of colorimetry is about the relationship
-between the SPD and color as perceived by the human brain.
-
-Since the human eye has only three color receptors it is perfectly
-possible that different SPDs will result in the same stimulation of
-those receptors and are perceived as the same color, even though the SPD
-of the light is different.
-
-In the 1920s experiments were devised to determine the relationship
-between SPDs and the perceived color and that resulted in the CIE 1931
-standard that defines spectral weighting functions that model the
-perception of color. Specifically that standard defines functions that
-can take an SPD and calculate the stimulus for each color receptor.
-After some further mathematical transforms these stimuli are known as
-the *CIE XYZ tristimulus* values and these X, Y and Z values describe a
-color as perceived by a human unambiguously. These X, Y and Z values are
-all in the range [0…1].
-
-The Y value in the CIE XYZ colorspace corresponds to luminance. Often
-the CIE XYZ colorspace is transformed to the normalized CIE xyY
-colorspace:
-
-x = X / (X + Y + Z)
-
-y = Y / (X + Y + Z)
-
-The x and y values are the chromaticity coordinates and can be used to
-define a color without the luminance component Y. It is very confusing
-to have such similar names for these colorspaces. Just be aware that if
-colors are specified with lower case 'x' and 'y', then the CIE xyY
-colorspace is used. Upper case 'X' and 'Y' refer to the CIE XYZ
-colorspace. Also, y has nothing to do with luminance. Together x and y
-specify a color, and Y the luminance. That is really all you need to
-remember from a practical point of view. At the end of this section you
-will find reading resources that go into much more detail if you are
-interested.
-
-A monitor or TV will reproduce colors by emitting light at three
-different wavelengths, the combination of which will stimulate the color
-receptors in the eye and thus cause the perception of color.
-Historically these wavelengths were defined by the red, green and blue
-phosphors used in the displays. These *color primaries* are part of what
-defines a colorspace.
-
-Different display devices will have different primaries and some
-primaries are more suitable for some display technologies than others.
-This has resulted in a variety of colorspaces that are used for
-different display technologies or uses. To define a colorspace you need
-to define the three color primaries (these are typically defined as x, y
-chromaticity coordinates from the CIE xyY colorspace) but also the white
-reference: that is the color obtained when all three primaries are at
-maximum power. This determines the relative power or energy of the
-primaries. This is usually chosen to be close to daylight which has been
-defined as the CIE D65 Illuminant.
-
-To recapitulate: the CIE XYZ colorspace uniquely identifies colors.
-Other colorspaces are defined by three chromaticity coordinates defined
-in the CIE xyY colorspace. Based on those a 3x3 matrix can be
-constructed that transforms CIE XYZ colors to colors in the new
-colorspace.
-
-Both the CIE XYZ and the RGB colorspace that are derived from the
-specific chromaticity primaries are linear colorspaces. But neither the
-eye, nor display technology is linear. Doubling the values of all
-components in the linear colorspace will not be perceived as twice the
-intensity of the color. So each colorspace also defines a transfer
-function that takes a linear color component value and transforms it to
-the non-linear component value, which is a closer match to the
-non-linear performance of both the eye and displays. Linear component
-values are denoted RGB, non-linear are denoted as R'G'B'. In general
-colors used in graphics are all R'G'B', except in openGL which uses
-linear RGB. Special care should be taken when dealing with openGL to
-provide linear RGB colors or to use the built-in openGL support to apply
-the inverse transfer function.
-
-The final piece that defines a colorspace is a function that transforms
-non-linear R'G'B' to non-linear Y'CbCr. This function is determined by
-the so-called luma coefficients. There may be multiple possible Y'CbCr
-encodings allowed for the same colorspace. Many encodings of color
-prefer to use luma (Y') and chroma (CbCr) instead of R'G'B'. Since the
-human eye is more sensitive to differences in luminance than in color
-this encoding allows one to reduce the amount of color information
-compared to the luma data. Note that the luma (Y') is unrelated to the Y
-in the CIE XYZ colorspace. Also note that Y'CbCr is often called YCbCr
-or YUV even though these are strictly speaking wrong.
-
-Sometimes people confuse Y'CbCr as being a colorspace. This is not
-correct, it is just an encoding of an R'G'B' color into luma and chroma
-values. The underlying colorspace that is associated with the R'G'B'
-color is also associated with the Y'CbCr color.
-
-The final step is how the RGB, R'G'B' or Y'CbCr values are quantized.
-The CIE XYZ colorspace where X, Y and Z are in the range [0…1] describes
-all colors that humans can perceive, but the transform to another
-colorspace will produce colors that are outside the [0…1] range. Once
-clamped to the [0…1] range those colors can no longer be reproduced in
-that colorspace. This clamping is what reduces the extent or gamut of
-the colorspace. How the range of [0…1] is translated to integer values
-in the range of [0…255] (or higher, depending on the color depth) is
-called the quantization. This is *not* part of the colorspace
-definition. In practice RGB or R'G'B' values are full range, i.e. they
-use the full [0…255] range. Y'CbCr values on the other hand are limited
-range with Y' using [16…235] and Cb and Cr using [16…240].
-
-Unfortunately, in some cases limited range RGB is also used where the
-components use the range [16…235]. And full range Y'CbCr also exists
-using the [0…255] range.
-
-In order to correctly interpret a color you need to know the
-quantization range, whether it is R'G'B' or Y'CbCr, the used Y'CbCr
-encoding and the colorspace. From that information you can calculate the
-corresponding CIE XYZ color and map that again to whatever colorspace
-your display device uses.
-
-The colorspace definition itself consists of the three chromaticity
-primaries, the white reference chromaticity, a transfer function and the
-luma coefficients needed to transform R'G'B' to Y'CbCr. While some
-colorspace standards correctly define all four, quite often the
-colorspace standard only defines some, and you have to rely on other
-standards for the missing pieces. The fact that colorspaces are often a
-mix of different standards also led to very confusing naming conventions
-where the name of a standard was used to name a colorspace when in fact
-that standard was part of various other colorspaces as well.
-
-If you want to read more about colors and colorspaces, then the
-following resources are useful: :ref:`poynton` is a good practical
-book for video engineers, :ref:`colimg` has a much broader scope and
-describes many more aspects of color (physics, chemistry, biology,
-etc.). The
-`http://www.brucelindbloom.com <http://www.brucelindbloom.com>`__
-website is an excellent resource, especially with respect to the
-mathematics behind colorspace conversions. The wikipedia
-`CIE 1931 colorspace <http://en.wikipedia.org/wiki/CIE_1931_color_space#CIE_xy_chromaticity_diagram_and_the_CIE_xyY_color_space>`__
-article is also very useful.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _common-defs:
-
-******************************************************
-Common definitions for V4L2 and V4L2 subdev interfaces
-******************************************************
-
-
-.. toctree::
- :maxdepth: 1
-
- selections-common
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _common:
-
-###################
-Common API Elements
-###################
-Programming a V4L2 device consists of these steps:
-
-- Opening the device
-
-- Changing device properties, selecting a video and audio input, video
- standard, picture brightness a. o.
-
-- Negotiating a data format
-
-- Negotiating an input/output method
-
-- The actual input/output loop
-
-- Closing the device
-
-In practice most steps are optional and can be executed out of order. It
-depends on the V4L2 device type, you can read about the details in
-:ref:`devices`. In this chapter we will discuss the basic concepts
-applicable to all devices.
-
-
-.. toctree::
- :maxdepth: 1
-
- open
- querycap
- app-pri
- video
- audio
- tuner
- standard
- dv-timings
- control
- extended-controls
- format
- planar-apis
- crop
- selection-api
- streaming-par
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _compat:
-
-*******
-Changes
-*******
-
-The following chapters document the evolution of the V4L2 API, errata or
-extensions. They are also intended to help application and driver
-writers to port or update their code.
-
-
-.. toctree::
- :maxdepth: 1
-
- diff-v4l
- hist-v4l2
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _control:
-
-*************
-User Controls
-*************
-
-Devices typically have a number of user-settable controls such as
-brightness, saturation and so on, which would be presented to the user
-on a graphical user interface. But, different devices will have
-different controls available, and furthermore, the range of possible
-values, and the default value will vary from device to device. The
-control ioctls provide the information and a mechanism to create a nice
-user interface for these controls that will work correctly with any
-device.
-
-All controls are accessed using an ID value. V4L2 defines several IDs
-for specific purposes. Drivers can also implement their own custom
-controls using ``V4L2_CID_PRIVATE_BASE`` [1]_ and higher values. The
-pre-defined control IDs have the prefix ``V4L2_CID_``, and are listed in
-:ref:`control-id`. The ID is used when querying the attributes of a
-control, and when getting or setting the current value.
-
-Generally applications should present controls to the user without
-assumptions about their purpose. Each control comes with a name string
-the user is supposed to understand. When the purpose is non-intuitive
-the driver writer should provide a user manual, a user interface plug-in
-or a driver specific panel application. Predefined IDs were introduced
-to change a few controls programmatically, for example to mute a device
-during a channel switch.
-
-Drivers may enumerate different controls after switching the current
-video input or output, tuner or modulator, or audio input or output.
-Different in the sense of other bounds, another default and current
-value, step size or other menu items. A control with a certain *custom*
-ID can also change name and type.
-
-If a control is not applicable to the current configuration of the
-device (for example, it doesn't apply to the current video input)
-drivers set the ``V4L2_CTRL_FLAG_INACTIVE`` flag.
-
-Control values are stored globally, they do not change when switching
-except to stay within the reported bounds. They also do not change e. g.
-when the device is opened or closed, when the tuner radio frequency is
-changed or generally never without application request.
-
-V4L2 specifies an event mechanism to notify applications when controls
-change value (see
-:ref:`VIDIOC_SUBSCRIBE_EVENT`, event
-``V4L2_EVENT_CTRL``), panel applications might want to make use of that
-in order to always reflect the correct control value.
-
-All controls use machine endianness.
-
-
-.. _control-id:
-
-Control IDs
-===========
-
-``V4L2_CID_BASE``
- First predefined ID, equal to ``V4L2_CID_BRIGHTNESS``.
-
-``V4L2_CID_USER_BASE``
- Synonym of ``V4L2_CID_BASE``.
-
-``V4L2_CID_BRIGHTNESS`` ``(integer)``
- Picture brightness, or more precisely, the black level.
-
-``V4L2_CID_CONTRAST`` ``(integer)``
- Picture contrast or luma gain.
-
-``V4L2_CID_SATURATION`` ``(integer)``
- Picture color saturation or chroma gain.
-
-``V4L2_CID_HUE`` ``(integer)``
- Hue or color balance.
-
-``V4L2_CID_AUDIO_VOLUME`` ``(integer)``
- Overall audio volume. Note some drivers also provide an OSS or ALSA
- mixer interface.
-
-``V4L2_CID_AUDIO_BALANCE`` ``(integer)``
- Audio stereo balance. Minimum corresponds to all the way left,
- maximum to right.
-
-``V4L2_CID_AUDIO_BASS`` ``(integer)``
- Audio bass adjustment.
-
-``V4L2_CID_AUDIO_TREBLE`` ``(integer)``
- Audio treble adjustment.
-
-``V4L2_CID_AUDIO_MUTE`` ``(boolean)``
- Mute audio, i. e. set the volume to zero, however without affecting
- ``V4L2_CID_AUDIO_VOLUME``. Like ALSA drivers, V4L2 drivers must mute
- at load time to avoid excessive noise. Actually the entire device
- should be reset to a low power consumption state.
-
-``V4L2_CID_AUDIO_LOUDNESS`` ``(boolean)``
- Loudness mode (bass boost).
-
-``V4L2_CID_BLACK_LEVEL`` ``(integer)``
- Another name for brightness (not a synonym of
- ``V4L2_CID_BRIGHTNESS``). This control is deprecated and should not
- be used in new drivers and applications.
-
-``V4L2_CID_AUTO_WHITE_BALANCE`` ``(boolean)``
- Automatic white balance (cameras).
-
-``V4L2_CID_DO_WHITE_BALANCE`` ``(button)``
- This is an action control. When set (the value is ignored), the
- device will do a white balance and then hold the current setting.
- Contrast this with the boolean ``V4L2_CID_AUTO_WHITE_BALANCE``,
- which, when activated, keeps adjusting the white balance.
-
-``V4L2_CID_RED_BALANCE`` ``(integer)``
- Red chroma balance.
-
-``V4L2_CID_BLUE_BALANCE`` ``(integer)``
- Blue chroma balance.
-
-``V4L2_CID_GAMMA`` ``(integer)``
- Gamma adjust.
-
-``V4L2_CID_WHITENESS`` ``(integer)``
- Whiteness for grey-scale devices. This is a synonym for
- ``V4L2_CID_GAMMA``. This control is deprecated and should not be
- used in new drivers and applications.
-
-``V4L2_CID_EXPOSURE`` ``(integer)``
- Exposure (cameras). [Unit?]
-
-``V4L2_CID_AUTOGAIN`` ``(boolean)``
- Automatic gain/exposure control.
-
-``V4L2_CID_GAIN`` ``(integer)``
- Gain control.
-
-``V4L2_CID_HFLIP`` ``(boolean)``
- Mirror the picture horizontally.
-
-``V4L2_CID_VFLIP`` ``(boolean)``
- Mirror the picture vertically.
-
-.. _v4l2-power-line-frequency:
-
-``V4L2_CID_POWER_LINE_FREQUENCY`` ``(enum)``
- Enables a power line frequency filter to avoid flicker. Possible
- values for ``enum v4l2_power_line_frequency`` are:
- ``V4L2_CID_POWER_LINE_FREQUENCY_DISABLED`` (0),
- ``V4L2_CID_POWER_LINE_FREQUENCY_50HZ`` (1),
- ``V4L2_CID_POWER_LINE_FREQUENCY_60HZ`` (2) and
- ``V4L2_CID_POWER_LINE_FREQUENCY_AUTO`` (3).
-
-``V4L2_CID_HUE_AUTO`` ``(boolean)``
- Enables automatic hue control by the device. The effect of setting
- ``V4L2_CID_HUE`` while automatic hue control is enabled is
- undefined, drivers should ignore such request.
-
-``V4L2_CID_WHITE_BALANCE_TEMPERATURE`` ``(integer)``
- This control specifies the white balance settings as a color
- temperature in Kelvin. A driver should have a minimum of 2800
- (incandescent) to 6500 (daylight). For more information about color
- temperature see
- `Wikipedia <http://en.wikipedia.org/wiki/Color_temperature>`__.
-
-``V4L2_CID_SHARPNESS`` ``(integer)``
- Adjusts the sharpness filters in a camera. The minimum value
- disables the filters, higher values give a sharper picture.
-
-``V4L2_CID_BACKLIGHT_COMPENSATION`` ``(integer)``
- Adjusts the backlight compensation in a camera. The minimum value
- disables backlight compensation.
-
-``V4L2_CID_CHROMA_AGC`` ``(boolean)``
- Chroma automatic gain control.
-
-``V4L2_CID_CHROMA_GAIN`` ``(integer)``
- Adjusts the Chroma gain control (for use when chroma AGC is
- disabled).
-
-``V4L2_CID_COLOR_KILLER`` ``(boolean)``
- Enable the color killer (i. e. force a black & white image in case
- of a weak video signal).
-
-.. _v4l2-colorfx:
-
-``V4L2_CID_COLORFX`` ``(enum)``
- Selects a color effect. The following values are defined:
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_COLORFX_NONE``
-
- - Color effect is disabled.
-
- - .. row 2
-
- - ``V4L2_COLORFX_ANTIQUE``
-
- - An aging (old photo) effect.
-
- - .. row 3
-
- - ``V4L2_COLORFX_ART_FREEZE``
-
- - Frost color effect.
-
- - .. row 4
-
- - ``V4L2_COLORFX_AQUA``
-
- - Water color, cool tone.
-
- - .. row 5
-
- - ``V4L2_COLORFX_BW``
-
- - Black and white.
-
- - .. row 6
-
- - ``V4L2_COLORFX_EMBOSS``
-
- - Emboss, the highlights and shadows replace light/dark boundaries
- and low contrast areas are set to a gray background.
-
- - .. row 7
-
- - ``V4L2_COLORFX_GRASS_GREEN``
-
- - Grass green.
-
- - .. row 8
-
- - ``V4L2_COLORFX_NEGATIVE``
-
- - Negative.
-
- - .. row 9
-
- - ``V4L2_COLORFX_SEPIA``
-
- - Sepia tone.
-
- - .. row 10
-
- - ``V4L2_COLORFX_SKETCH``
-
- - Sketch.
-
- - .. row 11
-
- - ``V4L2_COLORFX_SKIN_WHITEN``
-
- - Skin whiten.
-
- - .. row 12
-
- - ``V4L2_COLORFX_SKY_BLUE``
-
- - Sky blue.
-
- - .. row 13
-
- - ``V4L2_COLORFX_SOLARIZATION``
-
- - Solarization, the image is partially reversed in tone, only color
- values above or below a certain threshold are inverted.
-
- - .. row 14
-
- - ``V4L2_COLORFX_SILHOUETTE``
-
- - Silhouette (outline).
-
- - .. row 15
-
- - ``V4L2_COLORFX_VIVID``
-
- - Vivid colors.
-
- - .. row 16
-
- - ``V4L2_COLORFX_SET_CBCR``
-
- - The Cb and Cr chroma components are replaced by fixed coefficients
- determined by ``V4L2_CID_COLORFX_CBCR`` control.
-
-
-
-``V4L2_CID_COLORFX_CBCR`` ``(integer)``
- Determines the Cb and Cr coefficients for ``V4L2_COLORFX_SET_CBCR``
- color effect. Bits [7:0] of the supplied 32 bit value are
- interpreted as Cr component, bits [15:8] as Cb component and bits
- [31:16] must be zero.
-
-``V4L2_CID_AUTOBRIGHTNESS`` ``(boolean)``
- Enable Automatic Brightness.
-
-``V4L2_CID_ROTATE`` ``(integer)``
- Rotates the image by specified angle. Common angles are 90, 270 and
- 180. Rotating the image to 90 and 270 will reverse the height and
- width of the display window. It is necessary to set the new height
- and width of the picture using the
- :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl according to the
- rotation angle selected.
-
-``V4L2_CID_BG_COLOR`` ``(integer)``
- Sets the background color on the current output device. Background
- color needs to be specified in the RGB24 format. The supplied 32 bit
- value is interpreted as bits 0-7 Red color information, bits 8-15
- Green color information, bits 16-23 Blue color information and bits
- 24-31 must be zero.
-
-``V4L2_CID_ILLUMINATORS_1 V4L2_CID_ILLUMINATORS_2`` ``(boolean)``
- Switch on or off the illuminator 1 or 2 of the device (usually a
- microscope).
-
-``V4L2_CID_MIN_BUFFERS_FOR_CAPTURE`` ``(integer)``
- This is a read-only control that can be read by the application and
- used as a hint to determine the number of CAPTURE buffers to pass to
- REQBUFS. The value is the minimum number of CAPTURE buffers that is
- necessary for hardware to work.
-
-``V4L2_CID_MIN_BUFFERS_FOR_OUTPUT`` ``(integer)``
- This is a read-only control that can be read by the application and
- used as a hint to determine the number of OUTPUT buffers to pass to
- REQBUFS. The value is the minimum number of OUTPUT buffers that is
- necessary for hardware to work.
-
-.. _v4l2-alpha-component:
-
-``V4L2_CID_ALPHA_COMPONENT`` ``(integer)``
- Sets the alpha color component. When a capture device (or capture
- queue of a mem-to-mem device) produces a frame format that includes
- an alpha component (e.g.
- :ref:`packed RGB image formats <rgb-formats>`) and the alpha value
- is not defined by the device or the mem-to-mem input data this
- control lets you select the alpha component value of all pixels.
- When an output device (or output queue of a mem-to-mem device)
- consumes a frame format that doesn't include an alpha component and
- the device supports alpha channel processing this control lets you
- set the alpha component value of all pixels for further processing
- in the device.
-
-``V4L2_CID_LASTP1``
- End of the predefined control IDs (currently
- ``V4L2_CID_ALPHA_COMPONENT`` + 1).
-
-``V4L2_CID_PRIVATE_BASE``
- ID of the first custom (driver specific) control. Applications
- depending on particular custom controls should check the driver name
- and version, see :ref:`querycap`.
-
-Applications can enumerate the available controls with the
-:ref:`VIDIOC_QUERYCTRL` and
-:ref:`VIDIOC_QUERYMENU <VIDIOC_QUERYCTRL>` ioctls, get and set a
-control value with the :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and
-:ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls. Drivers must implement
-``VIDIOC_QUERYCTRL``, ``VIDIOC_G_CTRL`` and ``VIDIOC_S_CTRL`` when the
-device has one or more controls, ``VIDIOC_QUERYMENU`` when it has one or
-more menu type controls.
-
-
-.. _enum_all_controls:
-
-.. code-block:: c
- :caption: Example 1.8. Enumerating all user controls
-
-
- struct v4l2_queryctrl queryctrl;
- struct v4l2_querymenu querymenu;
-
- static void enumerate_menu(void)
- {
- printf(" Menu items:\\n");
-
- memset(&querymenu, 0, sizeof(querymenu));
- querymenu.id = queryctrl.id;
-
- for (querymenu.index = queryctrl.minimum;
- querymenu.index <= queryctrl.maximum;
- querymenu.index++) {
- if (0 == ioctl(fd, VIDIOC_QUERYMENU, &querymenu)) {
- printf(" %s\\n", querymenu.name);
- }
- }
- }
-
- memset(&queryctrl, 0, sizeof(queryctrl));
-
- for (queryctrl.id = V4L2_CID_BASE;
- queryctrl.id < V4L2_CID_LASTP1;
- queryctrl.id++) {
- if (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
- if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)
- continue;
-
- printf("Control %s\\n", queryctrl.name);
-
- if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
- enumerate_menu();
- } else {
- if (errno == EINVAL)
- continue;
-
- perror("VIDIOC_QUERYCTRL");
- exit(EXIT_FAILURE);
- }
- }
-
- for (queryctrl.id = V4L2_CID_PRIVATE_BASE;;
- queryctrl.id++) {
- if (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
- if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)
- continue;
-
- printf("Control %s\\n", queryctrl.name);
-
- if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
- enumerate_menu();
- } else {
- if (errno == EINVAL)
- break;
-
- perror("VIDIOC_QUERYCTRL");
- exit(EXIT_FAILURE);
- }
- }
-
-
-.. code-block:: c
- :caption: Example 1.9. Enumerating all user controls (alternative)
-
- memset(&queryctrl, 0, sizeof(queryctrl));
-
- queryctrl.id = V4L2_CTRL_CLASS_USER | V4L2_CTRL_FLAG_NEXT_CTRL;
- while (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
- if (V4L2_CTRL_ID2CLASS(queryctrl.id) != V4L2_CTRL_CLASS_USER)
- break;
- if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)
- continue;
-
- printf("Control %s\\n", queryctrl.name);
-
- if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
- enumerate_menu();
-
- queryctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
- }
- if (errno != EINVAL) {
- perror("VIDIOC_QUERYCTRL");
- exit(EXIT_FAILURE);
- }
-
-
-.. code-block:: c
- :caption: Example 1.10. Changing controls
-
- struct v4l2_queryctrl queryctrl;
- struct v4l2_control control;
-
- memset(&queryctrl, 0, sizeof(queryctrl));
- queryctrl.id = V4L2_CID_BRIGHTNESS;
-
- if (-1 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
- if (errno != EINVAL) {
- perror("VIDIOC_QUERYCTRL");
- exit(EXIT_FAILURE);
- } else {
- printf("V4L2_CID_BRIGHTNESS is not supportedn");
- }
- } else if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) {
- printf("V4L2_CID_BRIGHTNESS is not supportedn");
- } else {
- memset(&control, 0, sizeof (control));
- control.id = V4L2_CID_BRIGHTNESS;
- control.value = queryctrl.default_value;
-
- if (-1 == ioctl(fd, VIDIOC_S_CTRL, &control)) {
- perror("VIDIOC_S_CTRL");
- exit(EXIT_FAILURE);
- }
- }
-
- memset(&control, 0, sizeof(control));
- control.id = V4L2_CID_CONTRAST;
-
- if (0 == ioctl(fd, VIDIOC_G_CTRL, &control)) {
- control.value += 1;
-
- /* The driver may clamp the value or return ERANGE, ignored here */
-
- if (-1 == ioctl(fd, VIDIOC_S_CTRL, &control)
- && errno != ERANGE) {
- perror("VIDIOC_S_CTRL");
- exit(EXIT_FAILURE);
- }
- /* Ignore if V4L2_CID_CONTRAST is unsupported */
- } else if (errno != EINVAL) {
- perror("VIDIOC_G_CTRL");
- exit(EXIT_FAILURE);
- }
-
- control.id = V4L2_CID_AUDIO_MUTE;
- control.value = 1; /* silence */
-
- /* Errors ignored */
- ioctl(fd, VIDIOC_S_CTRL, &control);
-
-.. [1]
- The use of ``V4L2_CID_PRIVATE_BASE`` is problematic because different
- drivers may use the same ``V4L2_CID_PRIVATE_BASE`` ID for different
- controls. This makes it hard to programatically set such controls
- since the meaning of the control with that ID is driver dependent. In
- order to resolve this drivers use unique IDs and the
- ``V4L2_CID_PRIVATE_BASE`` IDs are mapped to those unique IDs by the
- kernel. Consider these ``V4L2_CID_PRIVATE_BASE`` IDs as aliases to
- the real IDs.
-
- Many applications today still use the ``V4L2_CID_PRIVATE_BASE`` IDs
- instead of using :ref:`VIDIOC_QUERYCTRL` with
- the ``V4L2_CTRL_FLAG_NEXT_CTRL`` flag to enumerate all IDs, so
- support for ``V4L2_CID_PRIVATE_BASE`` is still around.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _crop:
-
-*************************************
-Image Cropping, Insertion and Scaling
-*************************************
-
-Some video capture devices can sample a subsection of the picture and
-shrink or enlarge it to an image of arbitrary size. We call these
-abilities cropping and scaling. Some video output devices can scale an
-image up or down and insert it at an arbitrary scan line and horizontal
-offset into a video signal.
-
-Applications can use the following API to select an area in the video
-signal, query the default area and the hardware limits.
-
-**NOTE**: Despite their name, the :ref:`VIDIOC_CROPCAP <VIDIOC_CROPCAP>`,
-:ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and :ref:`VIDIOC_S_CROP
-<VIDIOC_G_CROP>` ioctls apply to input as well as output devices.
-
-Scaling requires a source and a target. On a video capture or overlay
-device the source is the video signal, and the cropping ioctls determine
-the area actually sampled. The target are images read by the application
-or overlaid onto the graphics screen. Their size (and position for an
-overlay) is negotiated with the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`
-and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls.
-
-On a video output device the source are the images passed in by the
-application, and their size is again negotiated with the
-:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
-ioctls, or may be encoded in a compressed video stream. The target is
-the video signal, and the cropping ioctls determine the area where the
-images are inserted.
-
-Source and target rectangles are defined even if the device does not
-support scaling or the :ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and
-:ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` ioctls. Their size (and position
-where applicable) will be fixed in this case.
-
-**NOTE:** All capture and output devices must support the
-:ref:`VIDIOC_CROPCAP <VIDIOC_CROPCAP>` ioctl such that applications can
-determine if scaling takes place.
-
-
-Cropping Structures
-===================
-
-
-.. _crop-scale:
-
-.. figure:: crop_files/crop.*
- :alt: crop.pdf / crop.gif
- :align: center
-
- Image Cropping, Insertion and Scaling
-
- The cropping, insertion and scaling process
-
-
-
-For capture devices the coordinates of the top left corner, width and
-height of the area which can be sampled is given by the ``bounds``
-substructure of the struct :ref:`v4l2_cropcap <v4l2-cropcap>` returned
-by the :ref:`VIDIOC_CROPCAP <VIDIOC_CROPCAP>` ioctl. To support a wide
-range of hardware this specification does not define an origin or units.
-However by convention drivers should horizontally count unscaled samples
-relative to 0H (the leading edge of the horizontal sync pulse, see
-:ref:`vbi-hsync`). Vertically ITU-R line numbers of the first field
-(see ITU R-525 line numbering for :ref:`525 lines <vbi-525>` and for
-:ref:`625 lines <vbi-625>`), multiplied by two if the driver
-can capture both fields.
-
-The top left corner, width and height of the source rectangle, that is
-the area actually sampled, is given by struct
-:ref:`v4l2_crop <v4l2-crop>` using the same coordinate system as
-struct :ref:`v4l2_cropcap <v4l2-cropcap>`. Applications can use the
-:ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>`
-ioctls to get and set this rectangle. It must lie completely within the
-capture boundaries and the driver may further adjust the requested size
-and/or position according to hardware limitations.
-
-Each capture device has a default source rectangle, given by the
-``defrect`` substructure of struct
-:ref:`v4l2_cropcap <v4l2-cropcap>`. The center of this rectangle
-shall align with the center of the active picture area of the video
-signal, and cover what the driver writer considers the complete picture.
-Drivers shall reset the source rectangle to the default when the driver
-is first loaded, but not later.
-
-For output devices these structures and ioctls are used accordingly,
-defining the *target* rectangle where the images will be inserted into
-the video signal.
-
-
-Scaling Adjustments
-===================
-
-Video hardware can have various cropping, insertion and scaling
-limitations. It may only scale up or down, support only discrete scaling
-factors, or have different scaling abilities in horizontal and vertical
-direction. Also it may not support scaling at all. At the same time the
-struct :ref:`v4l2_crop <v4l2-crop>` rectangle may have to be aligned,
-and both the source and target rectangles may have arbitrary upper and
-lower size limits. In particular the maximum ``width`` and ``height`` in
-struct :ref:`v4l2_crop <v4l2-crop>` may be smaller than the struct
-:ref:`v4l2_cropcap <v4l2-cropcap>`. ``bounds`` area. Therefore, as
-usual, drivers are expected to adjust the requested parameters and
-return the actual values selected.
-
-Applications can change the source or the target rectangle first, as
-they may prefer a particular image size or a certain area in the video
-signal. If the driver has to adjust both to satisfy hardware
-limitations, the last requested rectangle shall take priority, and the
-driver should preferably adjust the opposite one. The
-:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl however shall not change
-the driver state and therefore only adjust the requested rectangle.
-
-Suppose scaling on a video capture device is restricted to a factor 1:1
-or 2:1 in either direction and the target image size must be a multiple
-of 16 × 16 pixels. The source cropping rectangle is set to defaults,
-which are also the upper limit in this example, of 640 × 400 pixels at
-offset 0, 0. An application requests an image size of 300 × 225 pixels,
-assuming video will be scaled down from the "full picture" accordingly.
-The driver sets the image size to the closest possible values 304 × 224,
-then chooses the cropping rectangle closest to the requested size, that
-is 608 × 224 (224 × 2:1 would exceed the limit 400). The offset 0, 0 is
-still valid, thus unmodified. Given the default cropping rectangle
-reported by :ref:`VIDIOC_CROPCAP <VIDIOC_CROPCAP>` the application can
-easily propose another offset to center the cropping rectangle.
-
-Now the application may insist on covering an area using a picture
-aspect ratio closer to the original request, so it asks for a cropping
-rectangle of 608 × 456 pixels. The present scaling factors limit
-cropping to 640 × 384, so the driver returns the cropping size 608 × 384
-and adjusts the image size to closest possible 304 × 192.
-
-
-Examples
-========
-
-Source and target rectangles shall remain unchanged across closing and
-reopening a device, such that piping data into or out of a device will
-work without special preparations. More advanced applications should
-ensure the parameters are suitable before starting I/O.
-
-**NOTE:** on the next two examples, a video capture device is assumed;
-change ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` for other types of device.
-
-.. code-block:: c
- :caption: Example 1.11. Resetting the cropping parameters
-
- struct v4l2_cropcap cropcap;
- struct v4l2_crop crop;
-
- memset (&cropcap, 0, sizeof (cropcap));
- cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
-
- if (-1 == ioctl (fd, VIDIOC_CROPCAP, &cropcap)) {
- perror ("VIDIOC_CROPCAP");
- exit (EXIT_FAILURE);
- }
-
- memset (&crop, 0, sizeof (crop));
- crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- crop.c = cropcap.defrect;
-
- /* Ignore if cropping is not supported (EINVAL). */
-
- if (-1 == ioctl (fd, VIDIOC_S_CROP, &crop)
- && errno != EINVAL) {
- perror ("VIDIOC_S_CROP");
- exit (EXIT_FAILURE);
- }
-
-.. code-block:: c
- :caption: Example 1.12. Simple downscaling
-
- struct v4l2_cropcap cropcap;
- struct v4l2_format format;
-
- reset_cropping_parameters ();
-
- /* Scale down to 1/4 size of full picture. */
-
- memset (&format, 0, sizeof (format)); /* defaults */
-
- format.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
-
- format.fmt.pix.width = cropcap.defrect.width >> 1;
- format.fmt.pix.height = cropcap.defrect.height >> 1;
- format.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV;
-
- if (-1 == ioctl (fd, VIDIOC_S_FMT, &format)) {
- perror ("VIDIOC_S_FORMAT");
- exit (EXIT_FAILURE);
- }
-
- /* We could check the actual image size now, the actual scaling factor
- or if the driver can scale at all. */
-
-**NOTE:** This example assumes an output device.
-
-.. code-block:: c
- :caption: Example 1.13. Selecting an output area
-
- struct v4l2_cropcap cropcap;
- struct v4l2_crop crop;
-
- memset (&cropcap, 0, sizeof (cropcap));
- cropcap.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;
-
- if (-1 == ioctl (fd, VIDIOC_CROPCAP;, &cropcap)) {
- perror ("VIDIOC_CROPCAP");
- exit (EXIT_FAILURE);
- }
-
- memset (&crop, 0, sizeof (crop));
-
- crop.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;
- crop.c = cropcap.defrect;
-
- /* Scale the width and height to 50 % of their original size
- and center the output. */
-
- crop.c.width /= 2;
- crop.c.height /= 2;
- crop.c.left += crop.c.width / 2;
- crop.c.top += crop.c.height / 2;
-
- /* Ignore if cropping is not supported (EINVAL). */
-
- if (-1 == ioctl (fd, VIDIOC_S_CROP, &crop)
- && errno != EINVAL) {
- perror ("VIDIOC_S_CROP");
- exit (EXIT_FAILURE);
- }
-
-**NOTE:** This example assumes a video capture device.
-
-.. code-block:: c
- :caption: Example 1.14. Current scaling factor and pixel aspect
-
- struct v4l2_cropcap cropcap;
- struct v4l2_crop crop;
- struct v4l2_format format;
- double hscale, vscale;
- double aspect;
- int dwidth, dheight;
-
- memset (&cropcap, 0, sizeof (cropcap));
- cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
-
- if (-1 == ioctl (fd, VIDIOC_CROPCAP, &cropcap)) {
- perror ("VIDIOC_CROPCAP");
- exit (EXIT_FAILURE);
- }
-
- memset (&crop, 0, sizeof (crop));
- crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
-
- if (-1 == ioctl (fd, VIDIOC_G_CROP, &crop)) {
- if (errno != EINVAL) {
- perror ("VIDIOC_G_CROP");
- exit (EXIT_FAILURE);
- }
-
- /* Cropping not supported. */
- crop.c = cropcap.defrect;
- }
-
- memset (&format, 0, sizeof (format));
- format.fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
-
- if (-1 == ioctl (fd, VIDIOC_G_FMT, &format)) {
- perror ("VIDIOC_G_FMT");
- exit (EXIT_FAILURE);
- }
-
- /* The scaling applied by the driver. */
-
- hscale = format.fmt.pix.width / (double) crop.c.width;
- vscale = format.fmt.pix.height / (double) crop.c.height;
-
- aspect = cropcap.pixelaspect.numerator /
- (double) cropcap.pixelaspect.denominator;
- aspect = aspect * hscale / vscale;
-
- /* Devices following ITU-R BT.601 do not capture
- square pixels. For playback on a computer monitor
- we should scale the images to this size. */
-
- dwidth = format.fmt.pix.width / aspect;
- dheight = format.fmt.pix.height;
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _depth-formats:
-
-*************
-Depth Formats
-*************
-
-Depth data provides distance to points, mapped onto the image plane
-
-
-.. toctree::
- :maxdepth: 1
-
- pixfmt-z16
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _capture:
-
-***********************
-Video Capture Interface
-***********************
-
-Video capture devices sample an analog video signal and store the
-digitized images in memory. Today nearly all devices can capture at full
-25 or 30 frames/second. With this interface applications can control the
-capture process and move images from the driver into user space.
-
-Conventionally V4L2 video capture devices are accessed through character
-device special files named ``/dev/video`` and ``/dev/video0`` to
-``/dev/video63`` with major number 81 and minor numbers 0 to 63.
-``/dev/video`` is typically a symbolic link to the preferred video
-device. Note the same device files are used for video output devices.
-
-
-Querying Capabilities
-=====================
-
-Devices supporting the video capture interface set the
-``V4L2_CAP_VIDEO_CAPTURE`` or ``V4L2_CAP_VIDEO_CAPTURE_MPLANE`` flag in
-the ``capabilities`` field of struct
-:ref:`v4l2_capability <v4l2-capability>` returned by the
-:ref:`VIDIOC_QUERYCAP` ioctl. As secondary device
-functions they may also support the :ref:`video overlay <overlay>`
-(``V4L2_CAP_VIDEO_OVERLAY``) and the :ref:`raw VBI capture <raw-vbi>`
-(``V4L2_CAP_VBI_CAPTURE``) interface. At least one of the read/write or
-streaming I/O methods must be supported. Tuners and audio inputs are
-optional.
-
-
-Supplemental Functions
-======================
-
-Video capture devices shall support :ref:`audio input <audio>`,
-:ref:`tuner`, :ref:`controls <control>`,
-:ref:`cropping and scaling <crop>` and
-:ref:`streaming parameter <streaming-par>` ioctls as needed. The
-:ref:`video input <video>` and :ref:`video standard <standard>`
-ioctls must be supported by all video capture devices.
-
-
-Image Format Negotiation
-========================
-
-The result of a capture operation is determined by cropping and image
-format parameters. The former select an area of the video picture to
-capture, the latter how images are stored in memory, i. e. in RGB or YUV
-format, the number of bits per pixel or width and height. Together they
-also define how images are scaled in the process.
-
-As usual these parameters are *not* reset at :ref:`open() <func-open>`
-time to permit Unix tool chains, programming a device and then reading
-from it as if it was a plain file. Well written V4L2 applications ensure
-they really get what they want, including cropping and scaling.
-
-Cropping initialization at minimum requires to reset the parameters to
-defaults. An example is given in :ref:`crop`.
-
-To query the current image format applications set the ``type`` field of
-a struct :ref:`v4l2_format <v4l2-format>` to
-``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or
-``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and call the
-:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl with a pointer to this
-structure. Drivers fill the struct
-:ref:`v4l2_pix_format <v4l2-pix-format>` ``pix`` or the struct
-:ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` ``pix_mp``
-member of the ``fmt`` union.
-
-To request different parameters applications set the ``type`` field of a
-struct :ref:`v4l2_format <v4l2-format>` as above and initialize all
-fields of the struct :ref:`v4l2_pix_format <v4l2-pix-format>`
-``vbi`` member of the ``fmt`` union, or better just modify the results
-of :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, and call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
-ioctl with a pointer to this structure. Drivers may adjust the
-parameters and finally return the actual parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`
-does.
-
-Like :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` the :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl
-can be used to learn about hardware limitations without disabling I/O or
-possibly time consuming hardware preparations.
-
-The contents of struct :ref:`v4l2_pix_format <v4l2-pix-format>` and
-struct :ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` are
-discussed in :ref:`pixfmt`. See also the specification of the
-:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctls for
-details. Video capture devices must implement both the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`
-and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ignores all
-requests and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does.
-:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional.
-
-
-Reading Images
-==============
-
-A video capture device may support the ::ref:`read() function <func-read>`
-and/or streaming (:ref:`memory mapping <func-mmap>` or
-:ref:`user pointer <userp>`) I/O. See :ref:`io` for details.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _codec:
-
-***************
-Codec Interface
-***************
-
-A V4L2 codec can compress, decompress, transform, or otherwise convert
-video data from one format into another format, in memory. Typically
-such devices are memory-to-memory devices (i.e. devices with the
-``V4L2_CAP_VIDEO_M2M`` or ``V4L2_CAP_VIDEO_M2M_MPLANE`` capability set).
-
-A memory-to-memory video node acts just like a normal video node, but it
-supports both output (sending frames from memory to the codec hardware)
-and capture (receiving the processed frames from the codec hardware into
-memory) stream I/O. An application will have to setup the stream I/O for
-both sides and finally call :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`
-for both capture and output to start the codec.
-
-Video compression codecs use the MPEG controls to setup their codec
-parameters (note that the MPEG controls actually support many more
-codecs than just MPEG). See :ref:`mpeg-controls`.
-
-Memory-to-memory devices can often be used as a shared resource: you can
-open the video node multiple times, each application setting up their
-own codec properties that are local to the file handle, and each can use
-it independently from the others. The driver will arbitrate access to
-the codec and reprogram it whenever another file handler gets access.
-This is different from the usual video node behavior where the video
-properties are global to the device (i.e. changing something through one
-file handle is visible through another file handle).
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _effect:
-
-************************
-Effect Devices Interface
-************************
-
- **Note**
-
- This interface has been be suspended from the V4L2 API implemented
- in Linux 2.6 until we have more experience with effect device
- interfaces.
-
-A V4L2 video effect device can do image effects, filtering, or combine
-two or more images or image streams. For example video transitions or
-wipes. Applications send data to be processed and receive the result
-data either with :ref:`read() <func-read>` and
-:ref:`write() <func-write>` functions, or through the streaming I/O
-mechanism.
-
-[to do]
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _event:
-
-***************
-Event Interface
-***************
-
-The V4L2 event interface provides a means for a user to get immediately
-notified on certain conditions taking place on a device. This might
-include start of frame or loss of signal events, for example. Changes in
-the value or state of a V4L2 control can also be reported through
-events.
-
-To receive events, the events the user is interested in first must be
-subscribed using the
-:ref:`VIDIOC_SUBSCRIBE_EVENT` ioctl. Once
-an event is subscribed, the events of subscribed types are dequeueable
-using the :ref:`VIDIOC_DQEVENT` ioctl. Events may be
-unsubscribed using VIDIOC_UNSUBSCRIBE_EVENT ioctl. The special event
-type V4L2_EVENT_ALL may be used to unsubscribe all the events the
-driver supports.
-
-The event subscriptions and event queues are specific to file handles.
-Subscribing an event on one file handle does not affect other file
-handles.
-
-The information on dequeueable events is obtained by using select or
-poll system calls on video devices. The V4L2 events use POLLPRI events
-on poll system call and exceptions on select system call.
-
-Starting with kernel 3.1 certain guarantees can be given with regards to
-events:
-
-1. Each subscribed event has its own internal dedicated event queue.
- This means that flooding of one event type will not interfere with
- other event types.
-
-2. If the internal event queue for a particular subscribed event becomes
- full, then the oldest event in that queue will be dropped.
-
-3. Where applicable, certain event types can ensure that the payload of
- the oldest event that is about to be dropped will be merged with the
- payload of the next oldest event. Thus ensuring that no information
- is lost, but only an intermediate step leading up to that
- information. See the documentation for the event you want to
- subscribe to whether this is applicable for that event or not.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _osd:
-
-******************************
-Video Output Overlay Interface
-******************************
-
-**Also known as On-Screen Display (OSD)**
-
-Some video output devices can overlay a framebuffer image onto the
-outgoing video signal. Applications can set up such an overlay using
-this interface, which borrows structures and ioctls of the
-:ref:`Video Overlay <overlay>` interface.
-
-The OSD function is accessible through the same character special file
-as the :ref:`Video Output <capture>` function. Note the default
-function of such a ``/dev/video`` device is video capturing or output.
-The OSD function is only available after calling the
-:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
-
-
-Querying Capabilities
-=====================
-
-Devices supporting the *Video Output Overlay* interface set the
-``V4L2_CAP_VIDEO_OUTPUT_OVERLAY`` flag in the ``capabilities`` field of
-struct :ref:`v4l2_capability <v4l2-capability>` returned by the
-:ref:`VIDIOC_QUERYCAP` ioctl.
-
-
-Framebuffer
-===========
-
-Contrary to the *Video Overlay* interface the framebuffer is normally
-implemented on the TV card and not the graphics card. On Linux it is
-accessible as a framebuffer device (``/dev/fbN``). Given a V4L2 device,
-applications can find the corresponding framebuffer device by calling
-the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` ioctl. It returns, amongst
-other information, the physical address of the framebuffer in the
-``base`` field of struct :ref:`v4l2_framebuffer <v4l2-framebuffer>`.
-The framebuffer device ioctl ``FBIOGET_FSCREENINFO`` returns the same
-address in the ``smem_start`` field of struct
-:c:type:`struct fb_fix_screeninfo`. The ``FBIOGET_FSCREENINFO``
-ioctl and struct :c:type:`struct fb_fix_screeninfo` are defined in
-the ``linux/fb.h`` header file.
-
-The width and height of the framebuffer depends on the current video
-standard. A V4L2 driver may reject attempts to change the video standard
-(or any other ioctl which would imply a framebuffer size change) with an
-``EBUSY`` error code until all applications closed the framebuffer device.
-
-
-.. code-block:: c
- :caption: Example 4.1. Finding a framebuffer device for OSD
-
- #include <linux/fb.h>
-
- struct v4l2_framebuffer fbuf;
- unsigned int i;
- int fb_fd;
-
- if (-1 == ioctl(fd, VIDIOC_G_FBUF, &fbuf)) {
- perror("VIDIOC_G_FBUF");
- exit(EXIT_FAILURE);
- }
-
- for (i = 0; i < 30; i++) {
- char dev_name[16];
- struct fb_fix_screeninfo si;
-
- snprintf(dev_name, sizeof(dev_name), "/dev/fb%u", i);
-
- fb_fd = open(dev_name, O_RDWR);
- if (-1 == fb_fd) {
- switch (errno) {
- case ENOENT: /* no such file */
- case ENXIO: /* no driver */
- continue;
-
- default:
- perror("open");
- exit(EXIT_FAILURE);
- }
- }
-
- if (0 == ioctl(fb_fd, FBIOGET_FSCREENINFO, &si)) {
- if (si.smem_start == (unsigned long)fbuf.base)
- break;
- } else {
- /* Apparently not a framebuffer device. */
- }
-
- close(fb_fd);
- fb_fd = -1;
- }
-
- /* fb_fd is the file descriptor of the framebuffer device
- for the video output overlay, or -1 if no device was found. */
-
-
-Overlay Window and Scaling
-==========================
-
-The overlay is controlled by source and target rectangles. The source
-rectangle selects a subsection of the framebuffer image to be overlaid,
-the target rectangle an area in the outgoing video signal where the
-image will appear. Drivers may or may not support scaling, and arbitrary
-sizes and positions of these rectangles. Further drivers may support any
-(or none) of the clipping/blending methods defined for the
-:ref:`Video Overlay <overlay>` interface.
-
-A struct :ref:`v4l2_window <v4l2-window>` defines the size of the
-source rectangle, its position in the framebuffer and the
-clipping/blending method to be used for the overlay. To get the current
-parameters applications set the ``type`` field of a struct
-:ref:`v4l2_format <v4l2-format>` to
-``V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY`` and call the
-:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl. The driver fills the
-:ref:`struct v4l2_window <v4l2-window>` substructure named ``win``. It is not
-possible to retrieve a previously programmed clipping list or bitmap.
-
-To program the source rectangle applications set the ``type`` field of a
-struct :ref:`v4l2_format <v4l2-format>` to
-``V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY``, initialize the ``win``
-substructure and call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
-The driver adjusts the parameters against hardware limits and returns
-the actual parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. Like :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`,
-the :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl can be used to learn
-about driver capabilities without actually changing driver state. Unlike
-:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` this also works after the overlay has been enabled.
-
-A struct :ref:`v4l2_crop <v4l2-crop>` defines the size and position
-of the target rectangle. The scaling factor of the overlay is implied by
-the width and height given in struct :ref:`v4l2_window <v4l2-window>`
-and struct :ref:`v4l2_crop <v4l2-crop>`. The cropping API applies to
-*Video Output* and *Video Output Overlay* devices in the same way as to
-*Video Capture* and *Video Overlay* devices, merely reversing the
-direction of the data flow. For more information see :ref:`crop`.
-
-
-Enabling Overlay
-================
-
-There is no V4L2 ioctl to enable or disable the overlay, however the
-framebuffer interface of the driver may support the ``FBIOBLANK`` ioctl.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _output:
-
-**********************
-Video Output Interface
-**********************
-
-Video output devices encode stills or image sequences as analog video
-signal. With this interface applications can control the encoding
-process and move images from user space to the driver.
-
-Conventionally V4L2 video output devices are accessed through character
-device special files named ``/dev/video`` and ``/dev/video0`` to
-``/dev/video63`` with major number 81 and minor numbers 0 to 63.
-``/dev/video`` is typically a symbolic link to the preferred video
-device. Note the same device files are used for video capture devices.
-
-
-Querying Capabilities
-=====================
-
-Devices supporting the video output interface set the
-``V4L2_CAP_VIDEO_OUTPUT`` or ``V4L2_CAP_VIDEO_OUTPUT_MPLANE`` flag in
-the ``capabilities`` field of struct
-:ref:`v4l2_capability <v4l2-capability>` returned by the
-:ref:`VIDIOC_QUERYCAP` ioctl. As secondary device
-functions they may also support the :ref:`raw VBI output <raw-vbi>`
-(``V4L2_CAP_VBI_OUTPUT``) interface. At least one of the read/write or
-streaming I/O methods must be supported. Modulators and audio outputs
-are optional.
-
-
-Supplemental Functions
-======================
-
-Video output devices shall support :ref:`audio output <audio>`,
-:ref:`modulator <tuner>`, :ref:`controls <control>`,
-:ref:`cropping and scaling <crop>` and
-:ref:`streaming parameter <streaming-par>` ioctls as needed. The
-:ref:`video output <video>` and :ref:`video standard <standard>`
-ioctls must be supported by all video output devices.
-
-
-Image Format Negotiation
-========================
-
-The output is determined by cropping and image format parameters. The
-former select an area of the video picture where the image will appear,
-the latter how images are stored in memory, i. e. in RGB or YUV format,
-the number of bits per pixel or width and height. Together they also
-define how images are scaled in the process.
-
-As usual these parameters are *not* reset at :ref:`open() <func-open>`
-time to permit Unix tool chains, programming a device and then writing
-to it as if it was a plain file. Well written V4L2 applications ensure
-they really get what they want, including cropping and scaling.
-
-Cropping initialization at minimum requires to reset the parameters to
-defaults. An example is given in :ref:`crop`.
-
-To query the current image format applications set the ``type`` field of
-a struct :ref:`v4l2_format <v4l2-format>` to
-``V4L2_BUF_TYPE_VIDEO_OUTPUT`` or ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``
-and call the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl with a pointer
-to this structure. Drivers fill the struct
-:ref:`v4l2_pix_format <v4l2-pix-format>` ``pix`` or the struct
-:ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` ``pix_mp``
-member of the ``fmt`` union.
-
-To request different parameters applications set the ``type`` field of a
-struct :ref:`v4l2_format <v4l2-format>` as above and initialize all
-fields of the struct :ref:`v4l2_pix_format <v4l2-pix-format>`
-``vbi`` member of the ``fmt`` union, or better just modify the results
-of :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, and call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
-ioctl with a pointer to this structure. Drivers may adjust the
-parameters and finally return the actual parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`
-does.
-
-Like :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` the :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl
-can be used to learn about hardware limitations without disabling I/O or
-possibly time consuming hardware preparations.
-
-The contents of struct :ref:`v4l2_pix_format <v4l2-pix-format>` and
-struct :ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` are
-discussed in :ref:`pixfmt`. See also the specification of the
-:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctls for
-details. Video output devices must implement both the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`
-and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ignores all
-requests and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does.
-:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional.
-
-
-Writing Images
-==============
-
-A video output device may support the :ref:`write() function <rw>`
-and/or streaming (:ref:`memory mapping <mmap>` or
-:ref:`user pointer <userp>`) I/O. See :ref:`io` for details.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _overlay:
-
-***********************
-Video Overlay Interface
-***********************
-
-**Also known as Framebuffer Overlay or Previewing.**
-
-Video overlay devices have the ability to genlock (TV-)video into the
-(VGA-)video signal of a graphics card, or to store captured images
-directly in video memory of a graphics card, typically with clipping.
-This can be considerable more efficient than capturing images and
-displaying them by other means. In the old days when only nuclear power
-plants needed cooling towers this used to be the only way to put live
-video into a window.
-
-Video overlay devices are accessed through the same character special
-files as :ref:`video capture <capture>` devices. Note the default
-function of a ``/dev/video`` device is video capturing. The overlay
-function is only available after calling the
-:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
-
-The driver may support simultaneous overlay and capturing using the
-read/write and streaming I/O methods. If so, operation at the nominal
-frame rate of the video standard is not guaranteed. Frames may be
-directed away from overlay to capture, or one field may be used for
-overlay and the other for capture if the capture parameters permit this.
-
-Applications should use different file descriptors for capturing and
-overlay. This must be supported by all drivers capable of simultaneous
-capturing and overlay. Optionally these drivers may also permit
-capturing and overlay with a single file descriptor for compatibility
-with V4L and earlier versions of V4L2. [1]_
-
-
-Querying Capabilities
-=====================
-
-Devices supporting the video overlay interface set the
-``V4L2_CAP_VIDEO_OVERLAY`` flag in the ``capabilities`` field of struct
-:ref:`v4l2_capability <v4l2-capability>` returned by the
-:ref:`VIDIOC_QUERYCAP` ioctl. The overlay I/O
-method specified below must be supported. Tuners and audio inputs are
-optional.
-
-
-Supplemental Functions
-======================
-
-Video overlay devices shall support :ref:`audio input <audio>`,
-:ref:`tuner`, :ref:`controls <control>`,
-:ref:`cropping and scaling <crop>` and
-:ref:`streaming parameter <streaming-par>` ioctls as needed. The
-:ref:`video input <video>` and :ref:`video standard <standard>`
-ioctls must be supported by all video overlay devices.
-
-
-Setup
-=====
-
-Before overlay can commence applications must program the driver with
-frame buffer parameters, namely the address and size of the frame buffer
-and the image format, for example RGB 5:6:5. The
-:ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` and
-:ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctls are available to get and
-set these parameters, respectively. The :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctl is
-privileged because it allows to set up DMA into physical memory,
-bypassing the memory protection mechanisms of the kernel. Only the
-superuser can change the frame buffer address and size. Users are not
-supposed to run TV applications as root or with SUID bit set. A small
-helper application with suitable privileges should query the graphics
-system and program the V4L2 driver at the appropriate time.
-
-Some devices add the video overlay to the output signal of the graphics
-card. In this case the frame buffer is not modified by the video device,
-and the frame buffer address and pixel format are not needed by the
-driver. The :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctl is not privileged. An application
-can check for this type of device by calling the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`
-ioctl.
-
-A driver may support any (or none) of five clipping/blending methods:
-
-1. Chroma-keying displays the overlaid image only where pixels in the
- primary graphics surface assume a certain color.
-
-2. A bitmap can be specified where each bit corresponds to a pixel in
- the overlaid image. When the bit is set, the corresponding video
- pixel is displayed, otherwise a pixel of the graphics surface.
-
-3. A list of clipping rectangles can be specified. In these regions *no*
- video is displayed, so the graphics surface can be seen here.
-
-4. The framebuffer has an alpha channel that can be used to clip or
- blend the framebuffer with the video.
-
-5. A global alpha value can be specified to blend the framebuffer
- contents with video images.
-
-When simultaneous capturing and overlay is supported and the hardware
-prohibits different image and frame buffer formats, the format requested
-first takes precedence. The attempt to capture
-(:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`) or overlay
-(:ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`) may fail with an ``EBUSY`` error
-code or return accordingly modified parameters..
-
-
-Overlay Window
-==============
-
-The overlaid image is determined by cropping and overlay window
-parameters. The former select an area of the video picture to capture,
-the latter how images are overlaid and clipped. Cropping initialization
-at minimum requires to reset the parameters to defaults. An example is
-given in :ref:`crop`.
-
-The overlay window is described by a struct
-:ref:`v4l2_window <v4l2-window>`. It defines the size of the image,
-its position over the graphics surface and the clipping to be applied.
-To get the current parameters applications set the ``type`` field of a
-struct :ref:`v4l2_format <v4l2-format>` to
-``V4L2_BUF_TYPE_VIDEO_OVERLAY`` and call the
-:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl. The driver fills the
-:ref:`struct v4l2_window <v4l2-window>` substructure named ``win``. It is not
-possible to retrieve a previously programmed clipping list or bitmap.
-
-To program the overlay window applications set the ``type`` field of a
-struct :ref:`v4l2_format <v4l2-format>` to
-``V4L2_BUF_TYPE_VIDEO_OVERLAY``, initialize the ``win`` substructure and
-call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. The driver
-adjusts the parameters against hardware limits and returns the actual
-parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. Like :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`, the
-:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl can be used to learn
-about driver capabilities without actually changing driver state. Unlike
-:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` this also works after the overlay has been enabled.
-
-The scaling factor of the overlaid image is implied by the width and
-height given in struct :ref:`v4l2_window <v4l2-window>` and the size
-of the cropping rectangle. For more information see :ref:`crop`.
-
-When simultaneous capturing and overlay is supported and the hardware
-prohibits different image and window sizes, the size requested first
-takes precedence. The attempt to capture or overlay as well
-(:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`) may fail with an ``EBUSY`` error
-code or return accordingly modified parameters.
-
-
-.. _v4l2-window:
-
-struct v4l2_window
-------------------
-
-``struct v4l2_rect w``
- Size and position of the window relative to the top, left corner of
- the frame buffer defined with
- :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`. The window can extend the
- frame buffer width and height, the ``x`` and ``y`` coordinates can
- be negative, and it can lie completely outside the frame buffer. The
- driver clips the window accordingly, or if that is not possible,
- modifies its size and/or position.
-
-``enum v4l2_field field``
- Applications set this field to determine which video field shall be
- overlaid, typically one of ``V4L2_FIELD_ANY`` (0),
- ``V4L2_FIELD_TOP``, ``V4L2_FIELD_BOTTOM`` or
- ``V4L2_FIELD_INTERLACED``. Drivers may have to choose a different
- field order and return the actual setting here.
-
-``__u32 chromakey``
- When chroma-keying has been negotiated with
- :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` applications set this field
- to the desired pixel value for the chroma key. The format is the
- same as the pixel format of the framebuffer (struct
- :ref:`v4l2_framebuffer <v4l2-framebuffer>` ``fmt.pixelformat``
- field), with bytes in host order. E. g. for
- :ref:`V4L2_PIX_FMT_BGR24 <V4L2-PIX-FMT-BGR32>` the value should
- be 0xRRGGBB on a little endian, 0xBBGGRR on a big endian host.
-
-``struct v4l2_clip * clips``
- When chroma-keying has *not* been negotiated and
- :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` indicated this capability,
- applications can set this field to point to an array of clipping
- rectangles.
-
- Like the window coordinates w, clipping rectangles are defined
- relative to the top, left corner of the frame buffer. However
- clipping rectangles must not extend the frame buffer width and
- height, and they must not overlap. If possible applications
- should merge adjacent rectangles. Whether this must create
- x-y or y-x bands, or the order of rectangles, is not defined. When
- clip lists are not supported the driver ignores this field. Its
- contents after calling :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
- are undefined.
-
-``__u32 clipcount``
- When the application set the ``clips`` field, this field must
- contain the number of clipping rectangles in the list. When clip
- lists are not supported the driver ignores this field, its contents
- after calling :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` are undefined. When clip lists are
- supported but no clipping is desired this field must be set to zero.
-
-``void * bitmap``
- When chroma-keying has *not* been negotiated and
- :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` indicated this capability,
- applications can set this field to point to a clipping bit mask.
-
-It must be of the same size as the window, ``w.width`` and ``w.height``.
-Each bit corresponds to a pixel in the overlaid image, which is
-displayed only when the bit is *set*. Pixel coordinates translate to
-bits like:
-
-
-.. code-block:: c
-
- ((__u8 *) bitmap)[w.width * y + x / 8] & (1 << (x & 7))
-
-where ``0`` ≤ x < ``w.width`` and ``0`` ≤ y <``w.height``. [2]_
-
-When a clipping bit mask is not supported the driver ignores this field,
-its contents after calling :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` are
-undefined. When a bit mask is supported but no clipping is desired this
-field must be set to ``NULL``.
-
-Applications need not create a clip list or bit mask. When they pass
-both, or despite negotiating chroma-keying, the results are undefined.
-Regardless of the chosen method, the clipping abilities of the hardware
-may be limited in quantity or quality. The results when these limits are
-exceeded are undefined. [3]_
-
-``__u8 global_alpha``
- The global alpha value used to blend the framebuffer with video
- images, if global alpha blending has been negotiated
- (``V4L2_FBUF_FLAG_GLOBAL_ALPHA``, see
- :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`,
- :ref:`framebuffer-flags`).
-
- **Note**: this field was added in Linux 2.6.23, extending the structure.
- However the :ref:`VIDIOC_[G|S|TRY]_FMT <VIDIOC_G_FMT>`
- ioctls, which take a pointer to a :ref:`v4l2_format <v4l2-format>`
- parent structure with padding bytes at the end, are not affected.
-
-
-.. _v4l2-clip:
-
-struct v4l2_clip [4]_
----------------------
-
-``struct v4l2_rect c``
- Coordinates of the clipping rectangle, relative to the top, left
- corner of the frame buffer. Only window pixels *outside* all
- clipping rectangles are displayed.
-
-``struct v4l2_clip * next``
- Pointer to the next clipping rectangle, ``NULL`` when this is the last
- rectangle. Drivers ignore this field, it cannot be used to pass a
- linked list of clipping rectangles.
-
-
-.. _v4l2-rect:
-
-struct v4l2_rect
-----------------
-
-``__s32 left``
- Horizontal offset of the top, left corner of the rectangle, in
- pixels.
-
-``__s32 top``
- Vertical offset of the top, left corner of the rectangle, in pixels.
- Offsets increase to the right and down.
-
-``__u32 width``
- Width of the rectangle, in pixels.
-
-``__u32 height``
- Height of the rectangle, in pixels.
-
-
-Enabling Overlay
-================
-
-To start or stop the frame buffer overlay applications call the
-:ref:`VIDIOC_OVERLAY` ioctl.
-
-.. [1]
- A common application of two file descriptors is the XFree86
- :ref:`Xv/V4L <xvideo>` interface driver and a V4L2 application.
- While the X server controls video overlay, the application can take
- advantage of memory mapping and DMA.
-
- In the opinion of the designers of this API, no driver writer taking
- the efforts to support simultaneous capturing and overlay will
- restrict this ability by requiring a single file descriptor, as in
- V4L and earlier versions of V4L2. Making this optional means
- applications depending on two file descriptors need backup routines
- to be compatible with all drivers, which is considerable more work
- than using two fds in applications which do not. Also two fd's fit
- the general concept of one file descriptor for each logical stream.
- Hence as a complexity trade-off drivers *must* support two file
- descriptors and *may* support single fd operation.
-
-.. [2]
- Should we require ``w.width`` to be a multiple of eight?
-
-.. [3]
- When the image is written into frame buffer memory it will be
- undesirable if the driver clips out less pixels than expected,
- because the application and graphics system are not aware these
- regions need to be refreshed. The driver should clip out more pixels
- or not write the image at all.
-
-.. [4]
- The X Window system defines "regions" which are vectors of ``struct
- BoxRec { short x1, y1, x2, y2; }`` with ``width = x2 - x1`` and
- ``height = y2 - y1``, so one cannot pass X11 clip lists directly.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _radio:
-
-***************
-Radio Interface
-***************
-
-This interface is intended for AM and FM (analog) radio receivers and
-transmitters.
-
-Conventionally V4L2 radio devices are accessed through character device
-special files named ``/dev/radio`` and ``/dev/radio0`` to
-``/dev/radio63`` with major number 81 and minor numbers 64 to 127.
-
-
-Querying Capabilities
-=====================
-
-Devices supporting the radio interface set the ``V4L2_CAP_RADIO`` and
-``V4L2_CAP_TUNER`` or ``V4L2_CAP_MODULATOR`` flag in the
-``capabilities`` field of struct
-:ref:`v4l2_capability <v4l2-capability>` returned by the
-:ref:`VIDIOC_QUERYCAP` ioctl. Other combinations of
-capability flags are reserved for future extensions.
-
-
-Supplemental Functions
-======================
-
-Radio devices can support :ref:`controls <control>`, and must support
-the :ref:`tuner or modulator <tuner>` ioctls.
-
-They do not support the video input or output, audio input or output,
-video standard, cropping and scaling, compression and streaming
-parameter, or overlay ioctls. All other ioctls and I/O methods are
-reserved for future extensions.
-
-
-Programming
-===========
-
-Radio devices may have a couple audio controls (as discussed in
-:ref:`control`) such as a volume control, possibly custom controls.
-Further all radio devices have one tuner or modulator (these are
-discussed in :ref:`tuner`) with index number zero to select the radio
-frequency and to determine if a monaural or FM stereo program is
-received/emitted. Drivers switch automatically between AM and FM
-depending on the selected frequency. The
-:ref:`VIDIOC_G_TUNER <VIDIOC_G_TUNER>` or
-:ref:`VIDIOC_G_MODULATOR <VIDIOC_G_MODULATOR>` ioctl reports the
-supported frequency range.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _raw-vbi:
-
-**********************
-Raw VBI Data Interface
-**********************
-
-VBI is an abbreviation of Vertical Blanking Interval, a gap in the
-sequence of lines of an analog video signal. During VBI no picture
-information is transmitted, allowing some time while the electron beam
-of a cathode ray tube TV returns to the top of the screen. Using an
-oscilloscope you will find here the vertical synchronization pulses and
-short data packages ASK modulated [1]_ onto the video signal. These are
-transmissions of services such as Teletext or Closed Caption.
-
-Subject of this interface type is raw VBI data, as sampled off a video
-signal, or to be added to a signal for output. The data format is
-similar to uncompressed video images, a number of lines times a number
-of samples per line, we call this a VBI image.
-
-Conventionally V4L2 VBI devices are accessed through character device
-special files named ``/dev/vbi`` and ``/dev/vbi0`` to ``/dev/vbi31``
-with major number 81 and minor numbers 224 to 255. ``/dev/vbi`` is
-typically a symbolic link to the preferred VBI device. This convention
-applies to both input and output devices.
-
-To address the problems of finding related video and VBI devices VBI
-capturing and output is also available as device function under
-``/dev/video``. To capture or output raw VBI data with these devices
-applications must call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
-Accessed as ``/dev/vbi``, raw VBI capturing or output is the default
-device function.
-
-
-Querying Capabilities
-=====================
-
-Devices supporting the raw VBI capturing or output API set the
-``V4L2_CAP_VBI_CAPTURE`` or ``V4L2_CAP_VBI_OUTPUT`` flags, respectively,
-in the ``capabilities`` field of struct
-:ref:`v4l2_capability <v4l2-capability>` returned by the
-:ref:`VIDIOC_QUERYCAP` ioctl. At least one of the
-read/write, streaming or asynchronous I/O methods must be supported. VBI
-devices may or may not have a tuner or modulator.
-
-
-Supplemental Functions
-======================
-
-VBI devices shall support :ref:`video input or output <video>`,
-:ref:`tuner or modulator <tuner>`, and :ref:`controls <control>`
-ioctls as needed. The :ref:`video standard <standard>` ioctls provide
-information vital to program a VBI device, therefore must be supported.
-
-
-Raw VBI Format Negotiation
-==========================
-
-Raw VBI sampling abilities can vary, in particular the sampling
-frequency. To properly interpret the data V4L2 specifies an ioctl to
-query the sampling parameters. Moreover, to allow for some flexibility
-applications can also suggest different parameters.
-
-As usual these parameters are *not* reset at :ref:`open() <func-open>`
-time to permit Unix tool chains, programming a device and then reading
-from it as if it was a plain file. Well written V4L2 applications should
-always ensure they really get what they want, requesting reasonable
-parameters and then checking if the actual parameters are suitable.
-
-To query the current raw VBI capture parameters applications set the
-``type`` field of a struct :ref:`v4l2_format <v4l2-format>` to
-``V4L2_BUF_TYPE_VBI_CAPTURE`` or ``V4L2_BUF_TYPE_VBI_OUTPUT``, and call
-the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl with a pointer to this
-structure. Drivers fill the struct
-:ref:`v4l2_vbi_format <v4l2-vbi-format>` ``vbi`` member of the
-``fmt`` union.
-
-To request different parameters applications set the ``type`` field of a
-struct :ref:`v4l2_format <v4l2-format>` as above and initialize all
-fields of the struct :ref:`v4l2_vbi_format <v4l2-vbi-format>`
-``vbi`` member of the ``fmt`` union, or better just modify the results
-of :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, and call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
-ioctl with a pointer to this structure. Drivers return an ``EINVAL`` error
-code only when the given parameters are ambiguous, otherwise they modify
-the parameters according to the hardware capabilities and return the
-actual parameters. When the driver allocates resources at this point, it
-may return an ``EBUSY`` error code to indicate the returned parameters are
-valid but the required resources are currently not available. That may
-happen for instance when the video and VBI areas to capture would
-overlap, or when the driver supports multiple opens and another process
-already requested VBI capturing or output. Anyway, applications must
-expect other resource allocation points which may return ``EBUSY``, at the
-:ref:`VIDIOC_STREAMON` ioctl and the first :ref:`read() <func-read>`
-, :ref:`write() <func-write>` and :ref:`select() <func-select>` calls.
-
-VBI devices must implement both the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
-:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ignores all requests
-and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does.
-:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional.
-
-
-.. _v4l2-vbi-format:
-
-.. flat-table:: struct v4l2_vbi_format
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``sampling_rate``
-
- - Samples per second, i. e. unit 1 Hz.
-
- - .. row 2
-
- - __u32
-
- - ``offset``
-
- - Horizontal offset of the VBI image, relative to the leading edge
- of the line synchronization pulse and counted in samples: The
- first sample in the VBI image will be located ``offset`` /
- ``sampling_rate`` seconds following the leading edge. See also
- :ref:`vbi-hsync`.
-
- - .. row 3
-
- - __u32
-
- - ``samples_per_line``
-
- -
-
- - .. row 4
-
- - __u32
-
- - ``sample_format``
-
- - Defines the sample format as in :ref:`pixfmt`, a
- four-character-code. [2]_ Usually this is ``V4L2_PIX_FMT_GREY``,
- i. e. each sample consists of 8 bits with lower values oriented
- towards the black level. Do not assume any other correlation of
- values with the signal level. For example, the MSB does not
- necessarily indicate if the signal is 'high' or 'low' because 128
- may not be the mean value of the signal. Drivers shall not convert
- the sample format by software.
-
- - .. row 5
-
- - __u32
-
- - ``start``\ [2]_
-
- - This is the scanning system line number associated with the first
- line of the VBI image, of the first and the second field
- respectively. See :ref:`vbi-525` and :ref:`vbi-625` for valid
- values. The ``V4L2_VBI_ITU_525_F1_START``,
- ``V4L2_VBI_ITU_525_F2_START``, ``V4L2_VBI_ITU_625_F1_START`` and
- ``V4L2_VBI_ITU_625_F2_START`` defines give the start line numbers
- for each field for each 525 or 625 line format as a convenience.
- Don't forget that ITU line numbering starts at 1, not 0. VBI input
- drivers can return start values 0 if the hardware cannot reliable
- identify scanning lines, VBI acquisition may not require this
- information.
-
- - .. row 6
-
- - __u32
-
- - ``count``\ [2]_
-
- - The number of lines in the first and second field image,
- respectively.
-
- - .. row 7
-
- - :cspan:`2`
-
- Drivers should be as flexibility as possible. For example, it may
- be possible to extend or move the VBI capture window down to the
- picture area, implementing a 'full field mode' to capture data
- service transmissions embedded in the picture.
-
- An application can set the first or second ``count`` value to zero
- if no data is required from the respective field; ``count``\ [1]
- if the scanning system is progressive, i. e. not interlaced. The
- corresponding start value shall be ignored by the application and
- driver. Anyway, drivers may not support single field capturing and
- return both count values non-zero.
-
- Both ``count`` values set to zero, or line numbers outside the
- bounds depicted in :ref:`vbi-525` and :ref:`vbi-625`, or a
- field image covering lines of two fields, are invalid and shall
- not be returned by the driver.
-
- To initialize the ``start`` and ``count`` fields, applications
- must first determine the current video standard selection. The
- :ref:`v4l2_std_id <v4l2-std-id>` or the ``framelines`` field
- of struct :ref:`v4l2_standard <v4l2-standard>` can be evaluated
- for this purpose.
-
- - .. row 8
-
- - __u32
-
- - ``flags``
-
- - See :ref:`vbifmt-flags` below. Currently only drivers set flags,
- applications must set this field to zero.
-
- - .. row 9
-
- - __u32
-
- - ``reserved``\ [2]_
-
- - This array is reserved for future extensions. Drivers and
- applications must set it to zero.
-
-
-
-.. _vbifmt-flags:
-
-.. flat-table:: Raw VBI Format Flags
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - ``V4L2_VBI_UNSYNC``
-
- - 0x0001
-
- - This flag indicates hardware which does not properly distinguish
- between fields. Normally the VBI image stores the first field
- (lower scanning line numbers) first in memory. This may be a top
- or bottom field depending on the video standard. When this flag is
- set the first or second field may be stored first, however the
- fields are still in correct temporal order with the older field
- first in memory. [3]_
-
- - .. row 2
-
- - ``V4L2_VBI_INTERLACED``
-
- - 0x0002
-
- - By default the two field images will be passed sequentially; all
- lines of the first field followed by all lines of the second field
- (compare :ref:`field-order` ``V4L2_FIELD_SEQ_TB`` and
- ``V4L2_FIELD_SEQ_BT``, whether the top or bottom field is first in
- memory depends on the video standard). When this flag is set, the
- two fields are interlaced (cf. ``V4L2_FIELD_INTERLACED``). The
- first line of the first field followed by the first line of the
- second field, then the two second lines, and so on. Such a layout
- may be necessary when the hardware has been programmed to capture
- or output interlaced video images and is unable to separate the
- fields for VBI capturing at the same time. For simplicity setting
- this flag implies that both ``count`` values are equal and
- non-zero.
-
-
-
-.. _vbi-hsync:
-
-.. figure:: dev-raw-vbi_files/vbi_hsync.*
- :alt: vbi_hsync.pdf / vbi_hsync.gif
- :align: center
-
- **Figure 4.1. Line synchronization**
-
-
-.. _vbi-525:
-
-.. figure:: dev-raw-vbi_files/vbi_525.*
- :alt: vbi_525.pdf / vbi_525.gif
- :align: center
-
- **Figure 4.2. ITU-R 525 line numbering (M/NTSC and M/PAL)**
-
-
-
-.. _vbi-625:
-
-.. figure:: dev-raw-vbi_files/vbi_625.*
- :alt: vbi_625.pdf / vbi_625.gif
- :align: center
-
- **Figure 4.3. ITU-R 625 line numbering**
-
-
-
-Remember the VBI image format depends on the selected video standard,
-therefore the application must choose a new standard or query the
-current standard first. Attempts to read or write data ahead of format
-negotiation, or after switching the video standard which may invalidate
-the negotiated VBI parameters, should be refused by the driver. A format
-change during active I/O is not permitted.
-
-
-Reading and writing VBI images
-==============================
-
-To assure synchronization with the field number and easier
-implementation, the smallest unit of data passed at a time is one frame,
-consisting of two fields of VBI images immediately following in memory.
-
-The total size of a frame computes as follows:
-
-
-.. code-block:: c
-
- (count[0] + count[1]) * samples_per_line * sample size in bytes
-
-The sample size is most likely always one byte, applications must check
-the ``sample_format`` field though, to function properly with other
-drivers.
-
-A VBI device may support :ref:`read/write <rw>` and/or streaming
-(:ref:`memory mapping <mmap>` or :ref:`user pointer <userp>`) I/O.
-The latter bears the possibility of synchronizing video and VBI data by
-using buffer timestamps.
-
-Remember the :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` ioctl and the
-first :ref:`read() <func-read>`, :ref:`write() <func-write>` and
-:ref:`select() <func-select>` call can be resource allocation
-points returning an ``EBUSY`` error code if the required hardware resources
-are temporarily unavailable, for example the device is already in use by
-another process.
-
-.. [1]
- ASK: Amplitude-Shift Keying. A high signal level represents a '1'
- bit, a low level a '0' bit.
-
-.. [2]
- A few devices may be unable to sample VBI data at all but can extend
- the video capture window to the VBI region.
-
-.. [3]
- Most VBI services transmit on both fields, but some have different
- semantics depending on the field number. These cannot be reliable
- decoded or encoded when ``V4L2_VBI_UNSYNC`` is set.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _rds:
-
-*************
-RDS Interface
-*************
-
-The Radio Data System transmits supplementary information in binary
-format, for example the station name or travel information, on an
-inaudible audio subcarrier of a radio program. This interface is aimed
-at devices capable of receiving and/or transmitting RDS information.
-
-For more information see the core RDS standard :ref:`iec62106` and the
-RBDS standard :ref:`nrsc4`.
-
-Note that the RBDS standard as is used in the USA is almost identical to
-the RDS standard. Any RDS decoder/encoder can also handle RBDS. Only
-some of the fields have slightly different meanings. See the RBDS
-standard for more information.
-
-The RBDS standard also specifies support for MMBS (Modified Mobile
-Search). This is a proprietary format which seems to be discontinued.
-The RDS interface does not support this format. Should support for MMBS
-(or the so-called 'E blocks' in general) be needed, then please contact
-the linux-media mailing list:
-`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__.
-
-
-Querying Capabilities
-=====================
-
-Devices supporting the RDS capturing API set the
-``V4L2_CAP_RDS_CAPTURE`` flag in the ``capabilities`` field of struct
-:ref:`v4l2_capability <v4l2-capability>` returned by the
-:ref:`VIDIOC_QUERYCAP` ioctl. Any tuner that
-supports RDS will set the ``V4L2_TUNER_CAP_RDS`` flag in the
-``capability`` field of struct :ref:`v4l2_tuner <v4l2-tuner>`. If the
-driver only passes RDS blocks without interpreting the data the
-``V4L2_TUNER_CAP_RDS_BLOCK_IO`` flag has to be set, see
-:ref:`Reading RDS data <reading-rds-data>`. For future use the flag
-``V4L2_TUNER_CAP_RDS_CONTROLS`` has also been defined. However, a driver
-for a radio tuner with this capability does not yet exist, so if you are
-planning to write such a driver you should discuss this on the
-linux-media mailing list:
-`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__.
-
-Whether an RDS signal is present can be detected by looking at the
-``rxsubchans`` field of struct :ref:`v4l2_tuner <v4l2-tuner>`: the
-``V4L2_TUNER_SUB_RDS`` will be set if RDS data was detected.
-
-Devices supporting the RDS output API set the ``V4L2_CAP_RDS_OUTPUT``
-flag in the ``capabilities`` field of struct
-:ref:`v4l2_capability <v4l2-capability>` returned by the
-:ref:`VIDIOC_QUERYCAP` ioctl. Any modulator that
-supports RDS will set the ``V4L2_TUNER_CAP_RDS`` flag in the
-``capability`` field of struct
-:ref:`v4l2_modulator <v4l2-modulator>`. In order to enable the RDS
-transmission one must set the ``V4L2_TUNER_SUB_RDS`` bit in the
-``txsubchans`` field of struct
-:ref:`v4l2_modulator <v4l2-modulator>`. If the driver only passes RDS
-blocks without interpreting the data the ``V4L2_TUNER_CAP_RDS_BLOCK_IO``
-flag has to be set. If the tuner is capable of handling RDS entities
-like program identification codes and radio text, the flag
-``V4L2_TUNER_CAP_RDS_CONTROLS`` should be set, see
-:ref:`Writing RDS data <writing-rds-data>` and
-:ref:`FM Transmitter Control Reference <fm-tx-controls>`.
-
-
-.. _reading-rds-data:
-
-Reading RDS data
-================
-
-RDS data can be read from the radio device with the
-:ref:`read() <func-read>` function. The data is packed in groups of
-three bytes.
-
-
-.. _writing-rds-data:
-
-Writing RDS data
-================
-
-RDS data can be written to the radio device with the
-:ref:`write() <func-write>` function. The data is packed in groups of
-three bytes, as follows:
-
-
-RDS datastructures
-==================
-
-
-.. _v4l2-rds-data:
-
-.. flat-table:: struct v4l2_rds_data
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 5
-
-
- - .. row 1
-
- - __u8
-
- - ``lsb``
-
- - Least Significant Byte of RDS Block
-
- - .. row 2
-
- - __u8
-
- - ``msb``
-
- - Most Significant Byte of RDS Block
-
- - .. row 3
-
- - __u8
-
- - ``block``
-
- - Block description
-
-
-
-.. _v4l2-rds-block:
-
-.. flat-table:: Block description
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 5
-
-
- - .. row 1
-
- - Bits 0-2
-
- - Block (aka offset) of the received data.
-
- - .. row 2
-
- - Bits 3-5
-
- - Deprecated. Currently identical to bits 0-2. Do not use these
- bits.
-
- - .. row 3
-
- - Bit 6
-
- - Corrected bit. Indicates that an error was corrected for this data
- block.
-
- - .. row 4
-
- - Bit 7
-
- - Error bit. Indicates that an uncorrectable error occurred during
- reception of this block.
-
-
-
-.. _v4l2-rds-block-codes:
-
-.. flat-table:: Block defines
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 1 5
-
-
- - .. row 1
-
- - V4L2_RDS_BLOCK_MSK
-
- -
- - 7
-
- - Mask for bits 0-2 to get the block ID.
-
- - .. row 2
-
- - V4L2_RDS_BLOCK_A
-
- -
- - 0
-
- - Block A.
-
- - .. row 3
-
- - V4L2_RDS_BLOCK_B
-
- -
- - 1
-
- - Block B.
-
- - .. row 4
-
- - V4L2_RDS_BLOCK_C
-
- -
- - 2
-
- - Block C.
-
- - .. row 5
-
- - V4L2_RDS_BLOCK_D
-
- -
- - 3
-
- - Block D.
-
- - .. row 6
-
- - V4L2_RDS_BLOCK_C_ALT
-
- -
- - 4
-
- - Block C'.
-
- - .. row 7
-
- - V4L2_RDS_BLOCK_INVALID
-
- - read-only
-
- - 7
-
- - An invalid block.
-
- - .. row 8
-
- - V4L2_RDS_BLOCK_CORRECTED
-
- - read-only
-
- - 0x40
-
- - A bit error was detected but corrected.
-
- - .. row 9
-
- - V4L2_RDS_BLOCK_ERROR
-
- - read-only
-
- - 0x80
-
- - An uncorrectable error occurred.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _sdr:
-
-**************************************
-Software Defined Radio Interface (SDR)
-**************************************
-
-SDR is an abbreviation of Software Defined Radio, the radio device which
-uses application software for modulation or demodulation. This interface
-is intended for controlling and data streaming of such devices.
-
-SDR devices are accessed through character device special files named
-``/dev/swradio0`` to ``/dev/swradio255`` with major number 81 and
-dynamically allocated minor numbers 0 to 255.
-
-
-Querying Capabilities
-=====================
-
-Devices supporting the SDR receiver interface set the
-``V4L2_CAP_SDR_CAPTURE`` and ``V4L2_CAP_TUNER`` flag in the
-``capabilities`` field of struct
-:ref:`v4l2_capability <v4l2-capability>` returned by the
-:ref:`VIDIOC_QUERYCAP` ioctl. That flag means the
-device has an Analog to Digital Converter (ADC), which is a mandatory
-element for the SDR receiver.
-
-Devices supporting the SDR transmitter interface set the
-``V4L2_CAP_SDR_OUTPUT`` and ``V4L2_CAP_MODULATOR`` flag in the
-``capabilities`` field of struct
-:ref:`v4l2_capability <v4l2-capability>` returned by the
-:ref:`VIDIOC_QUERYCAP` ioctl. That flag means the
-device has an Digital to Analog Converter (DAC), which is a mandatory
-element for the SDR transmitter.
-
-At least one of the read/write, streaming or asynchronous I/O methods
-must be supported.
-
-
-Supplemental Functions
-======================
-
-SDR devices can support :ref:`controls <control>`, and must support
-the :ref:`tuner` ioctls. Tuner ioctls are used for setting the
-ADC/DAC sampling rate (sampling frequency) and the possible radio
-frequency (RF).
-
-The ``V4L2_TUNER_SDR`` tuner type is used for setting SDR device ADC/DAC
-frequency, and the ``V4L2_TUNER_RF`` tuner type is used for setting
-radio frequency. The tuner index of the RF tuner (if any) must always
-follow the SDR tuner index. Normally the SDR tuner is #0 and the RF
-tuner is #1.
-
-The :ref:`VIDIOC_S_HW_FREQ_SEEK` ioctl is
-not supported.
-
-
-Data Format Negotiation
-=======================
-
-The SDR device uses the :ref:`format` ioctls to select the
-capture and output format. Both the sampling resolution and the data
-streaming format are bound to that selectable format. In addition to the
-basic :ref:`format` ioctls, the
-:ref:`VIDIOC_ENUM_FMT` ioctl must be supported as
-well.
-
-To use the :ref:`format` ioctls applications set the ``type``
-field of a struct :ref:`v4l2_format <v4l2-format>` to
-``V4L2_BUF_TYPE_SDR_CAPTURE`` or ``V4L2_BUF_TYPE_SDR_OUTPUT`` and use
-the struct :ref:`v4l2_sdr_format <v4l2-sdr-format>` ``sdr`` member
-of the ``fmt`` union as needed per the desired operation. Currently
-there is two fields, ``pixelformat`` and ``buffersize``, of struct
-struct :ref:`v4l2_sdr_format <v4l2-sdr-format>` which are used.
-Content of the ``pixelformat`` is V4L2 FourCC code of the data format.
-The ``buffersize`` field is maximum buffer size in bytes required for
-data transfer, set by the driver in order to inform application.
-
-
-.. _v4l2-sdr-format:
-
-.. flat-table:: struct v4l2_sdr_format
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``pixelformat``
-
- - The data format or type of compression, set by the application.
- This is a little endian
- :ref:`four character code <v4l2-fourcc>`. V4L2 defines SDR
- formats in :ref:`sdr-formats`.
-
- - .. row 2
-
- - __u32
-
- - ``buffersize``
-
- - Maximum size in bytes required for data. Value is set by the
- driver.
-
- - .. row 3
-
- - __u8
-
- - ``reserved[24]``
-
- - This array is reserved for future extensions. Drivers and
- applications must set it to zero.
-
-
-An SDR device may support :ref:`read/write <rw>` and/or streaming
-(:ref:`memory mapping <mmap>` or :ref:`user pointer <userp>`) I/O.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _sliced:
-
-*************************
-Sliced VBI Data Interface
-*************************
-
-VBI stands for Vertical Blanking Interval, a gap in the sequence of
-lines of an analog video signal. During VBI no picture information is
-transmitted, allowing some time while the electron beam of a cathode ray
-tube TV returns to the top of the screen.
-
-Sliced VBI devices use hardware to demodulate data transmitted in the
-VBI. V4L2 drivers shall *not* do this by software, see also the
-:ref:`raw VBI interface <raw-vbi>`. The data is passed as short
-packets of fixed size, covering one scan line each. The number of
-packets per video frame is variable.
-
-Sliced VBI capture and output devices are accessed through the same
-character special files as raw VBI devices. When a driver supports both
-interfaces, the default function of a ``/dev/vbi`` device is *raw* VBI
-capturing or output, and the sliced VBI function is only available after
-calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl as defined
-below. Likewise a ``/dev/video`` device may support the sliced VBI API,
-however the default function here is video capturing or output.
-Different file descriptors must be used to pass raw and sliced VBI data
-simultaneously, if this is supported by the driver.
-
-
-Querying Capabilities
-=====================
-
-Devices supporting the sliced VBI capturing or output API set the
-``V4L2_CAP_SLICED_VBI_CAPTURE`` or ``V4L2_CAP_SLICED_VBI_OUTPUT`` flag
-respectively, in the ``capabilities`` field of struct
-:ref:`v4l2_capability <v4l2-capability>` returned by the
-:ref:`VIDIOC_QUERYCAP` ioctl. At least one of the
-read/write, streaming or asynchronous :ref:`I/O methods <io>` must be
-supported. Sliced VBI devices may have a tuner or modulator.
-
-
-Supplemental Functions
-======================
-
-Sliced VBI devices shall support :ref:`video input or output <video>`
-and :ref:`tuner or modulator <tuner>` ioctls if they have these
-capabilities, and they may support :ref:`control` ioctls.
-The :ref:`video standard <standard>` ioctls provide information vital
-to program a sliced VBI device, therefore must be supported.
-
-
-.. _sliced-vbi-format-negotitation:
-
-Sliced VBI Format Negotiation
-=============================
-
-To find out which data services are supported by the hardware
-applications can call the
-:ref:`VIDIOC_G_SLICED_VBI_CAP <VIDIOC_G_SLICED_VBI_CAP>` ioctl.
-All drivers implementing the sliced VBI interface must support this
-ioctl. The results may differ from those of the
-:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl when the number of VBI
-lines the hardware can capture or output per frame, or the number of
-services it can identify on a given line are limited. For example on PAL
-line 16 the hardware may be able to look for a VPS or Teletext signal,
-but not both at the same time.
-
-To determine the currently selected services applications set the
-``type`` field of struct :ref:`v4l2_format <v4l2-format>` to
-``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE`` or
-``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT``, and the
-:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl fills the ``fmt.sliced``
-member, a struct
-:ref:`v4l2_sliced_vbi_format <v4l2-sliced-vbi-format>`.
-
-Applications can request different parameters by initializing or
-modifying the ``fmt.sliced`` member and calling the
-:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with a pointer to the
-:ref:`struct v4l2_format <v4l2-format>` structure.
-
-The sliced VBI API is more complicated than the raw VBI API because the
-hardware must be told which VBI service to expect on each scan line. Not
-all services may be supported by the hardware on all lines (this is
-especially true for VBI output where Teletext is often unsupported and
-other services can only be inserted in one specific line). In many
-cases, however, it is sufficient to just set the ``service_set`` field
-to the required services and let the driver fill the ``service_lines``
-array according to hardware capabilities. Only if more precise control
-is needed should the programmer set the ``service_lines`` array
-explicitly.
-
-The :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl modifies the parameters
-according to hardware capabilities. When the driver allocates resources
-at this point, it may return an ``EBUSY`` error code if the required
-resources are temporarily unavailable. Other resource allocation points
-which may return ``EBUSY`` can be the
-:ref:`VIDIOC_STREAMON` ioctl and the first
-:ref:`read() <func-read>`, :ref:`write() <func-write>` and
-:ref:`select() <func-select>` call.
-
-
-.. _v4l2-sliced-vbi-format:
-
-struct v4l2_sliced_vbi_format
------------------------------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 3 2 2 2
-
-
- - .. row 1
-
- - __u32
-
- - ``service_set``
-
- - :cspan:`2`
-
- If ``service_set`` is non-zero when passed with
- :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` or
- :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>`, the ``service_lines``
- array will be filled by the driver according to the services
- specified in this field. For example, if ``service_set`` is
- initialized with ``V4L2_SLICED_TELETEXT_B | V4L2_SLICED_WSS_625``,
- a driver for the cx25840 video decoder sets lines 7-22 of both
- fields [1]_ to ``V4L2_SLICED_TELETEXT_B`` and line 23 of the first
- field to ``V4L2_SLICED_WSS_625``. If ``service_set`` is set to
- zero, then the values of ``service_lines`` will be used instead.
-
- On return the driver sets this field to the union of all elements
- of the returned ``service_lines`` array. It may contain less
- services than requested, perhaps just one, if the hardware cannot
- handle more services simultaneously. It may be empty (zero) if
- none of the requested services are supported by the hardware.
-
- - .. row 2
-
- - __u16
-
- - ``service_lines``\ [2][24]
-
- - :cspan:`2`
-
- Applications initialize this array with sets of data services the
- driver shall look for or insert on the respective scan line.
- Subject to hardware capabilities drivers return the requested set,
- a subset, which may be just a single service, or an empty set.
- When the hardware cannot handle multiple services on the same line
- the driver shall choose one. No assumptions can be made on which
- service the driver chooses.
-
- Data services are defined in :ref:`vbi-services2`. Array indices
- map to ITU-R line numbers (see also :ref:`vbi-525` and
- :ref:`vbi-625`) as follows:
-
- - .. row 3
-
- -
- -
- - Element
-
- - 525 line systems
-
- - 625 line systems
-
- - .. row 4
-
- -
- -
- - ``service_lines``\ [0][1]
-
- - 1
-
- - 1
-
- - .. row 5
-
- -
- -
- - ``service_lines``\ [0][23]
-
- - 23
-
- - 23
-
- - .. row 6
-
- -
- -
- - ``service_lines``\ [1][1]
-
- - 264
-
- - 314
-
- - .. row 7
-
- -
- -
- - ``service_lines``\ [1][23]
-
- - 286
-
- - 336
-
- - .. row 8
-
- -
- -
- - :cspan:`2` Drivers must set ``service_lines`` [0][0] and
- ``service_lines``\ [1][0] to zero. The
- ``V4L2_VBI_ITU_525_F1_START``, ``V4L2_VBI_ITU_525_F2_START``,
- ``V4L2_VBI_ITU_625_F1_START`` and ``V4L2_VBI_ITU_625_F2_START``
- defines give the start line numbers for each field for each 525 or
- 625 line format as a convenience. Don't forget that ITU line
- numbering starts at 1, not 0.
-
- - .. row 9
-
- - __u32
-
- - ``io_size``
-
- - :cspan:`2` Maximum number of bytes passed by one
- :ref:`read() <func-read>` or :ref:`write() <func-write>` call,
- and the buffer size in bytes for the
- :ref:`VIDIOC_QBUF` and
- :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. Drivers set this field
- to the size of struct
- :ref:`v4l2_sliced_vbi_data <v4l2-sliced-vbi-data>` times the
- number of non-zero elements in the returned ``service_lines``
- array (that is the number of lines potentially carrying data).
-
- - .. row 10
-
- - __u32
-
- - ``reserved``\ [2]
-
- - :cspan:`2` This array is reserved for future extensions.
- Applications and drivers must set it to zero.
-
-
-
-.. _vbi-services2:
-
-Sliced VBI services
--------------------
-
-.. flat-table::
- :header-rows: 1
- :stub-columns: 0
- :widths: 2 1 1 2 2
-
-
- - .. row 1
-
- - Symbol
-
- - Value
-
- - Reference
-
- - Lines, usually
-
- - Payload
-
- - .. row 2
-
- - ``V4L2_SLICED_TELETEXT_B`` (Teletext System B)
-
- - 0x0001
-
- - :ref:`ets300706`, :ref:`itu653`
-
- - PAL/SECAM line 7-22, 320-335 (second field 7-22)
-
- - Last 42 of the 45 byte Teletext packet, that is without clock
- run-in and framing code, lsb first transmitted.
-
- - .. row 3
-
- - ``V4L2_SLICED_VPS``
-
- - 0x0400
-
- - :ref:`ets300231`
-
- - PAL line 16
-
- - Byte number 3 to 15 according to Figure 9 of ETS 300 231, lsb
- first transmitted.
-
- - .. row 4
-
- - ``V4L2_SLICED_CAPTION_525``
-
- - 0x1000
-
- - :ref:`cea608`
-
- - NTSC line 21, 284 (second field 21)
-
- - Two bytes in transmission order, including parity bit, lsb first
- transmitted.
-
- - .. row 5
-
- - ``V4L2_SLICED_WSS_625``
-
- - 0x4000
-
- - :ref:`itu1119`, :ref:`en300294`
-
- - PAL/SECAM line 23
-
- -
-
- ::
-
- Byte 0 1
- msb lsb msb lsb
- Bit 7 6 5 4 3 2 1 0 x x 13 12 11 10 9
-
- - .. row 6
-
- - ``V4L2_SLICED_VBI_525``
-
- - 0x1000
-
- - :cspan:`2` Set of services applicable to 525 line systems.
-
- - .. row 7
-
- - ``V4L2_SLICED_VBI_625``
-
- - 0x4401
-
- - :cspan:`2` Set of services applicable to 625 line systems.
-
-
-Drivers may return an ``EINVAL`` error code when applications attempt to
-read or write data without prior format negotiation, after switching the
-video standard (which may invalidate the negotiated VBI parameters) and
-after switching the video input (which may change the video standard as
-a side effect). The :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl may
-return an ``EBUSY`` error code when applications attempt to change the
-format while i/o is in progress (between a
-:ref:`VIDIOC_STREAMON` and
-:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` call, and after the first
-:ref:`read() <func-read>` or :ref:`write() <func-write>` call).
-
-
-Reading and writing sliced VBI data
-===================================
-
-A single :ref:`read() <func-read>` or :ref:`write() <func-write>`
-call must pass all data belonging to one video frame. That is an array
-of :ref:`struct v4l2_sliced_vbi_data <v4l2-sliced-vbi-data>` structures with one or
-more elements and a total size not exceeding ``io_size`` bytes. Likewise
-in streaming I/O mode one buffer of ``io_size`` bytes must contain data
-of one video frame. The ``id`` of unused
-:ref:`struct v4l2_sliced_vbi_data <v4l2-sliced-vbi-data>` elements must be zero.
-
-
-.. _v4l2-sliced-vbi-data:
-
-struct v4l2_sliced_vbi_data
----------------------------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - __u32
-
- - ``id``
-
- - A flag from :ref:`vbi-services` identifying the type of data in
- this packet. Only a single bit must be set. When the ``id`` of a
- captured packet is zero, the packet is empty and the contents of
- other fields are undefined. Applications shall ignore empty
- packets. When the ``id`` of a packet for output is zero the
- contents of the ``data`` field are undefined and the driver must
- no longer insert data on the requested ``field`` and ``line``.
-
- - .. row 2
-
- - __u32
-
- - ``field``
-
- - The video field number this data has been captured from, or shall
- be inserted at. ``0`` for the first field, ``1`` for the second
- field.
-
- - .. row 3
-
- - __u32
-
- - ``line``
-
- - The field (as opposed to frame) line number this data has been
- captured from, or shall be inserted at. See :ref:`vbi-525` and
- :ref:`vbi-625` for valid values. Sliced VBI capture devices can
- set the line number of all packets to ``0`` if the hardware cannot
- reliably identify scan lines. The field number must always be
- valid.
-
- - .. row 4
-
- - __u32
-
- - ``reserved``
-
- - This field is reserved for future extensions. Applications and
- drivers must set it to zero.
-
- - .. row 5
-
- - __u8
-
- - ``data``\ [48]
-
- - The packet payload. See :ref:`vbi-services` for the contents and
- number of bytes passed for each data type. The contents of padding
- bytes at the end of this array are undefined, drivers and
- applications shall ignore them.
-
-
-Packets are always passed in ascending line number order, without
-duplicate line numbers. The :ref:`write() <func-write>` function and
-the :ref:`VIDIOC_QBUF` ioctl must return an ``EINVAL``
-error code when applications violate this rule. They must also return an
-EINVAL error code when applications pass an incorrect field or line
-number, or a combination of ``field``, ``line`` and ``id`` which has not
-been negotiated with the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` or
-:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. When the line numbers are
-unknown the driver must pass the packets in transmitted order. The
-driver can insert empty packets with ``id`` set to zero anywhere in the
-packet array.
-
-To assure synchronization and to distinguish from frame dropping, when a
-captured frame does not carry any of the requested data services drivers
-must pass one or more empty packets. When an application fails to pass
-VBI data in time for output, the driver must output the last VPS and WSS
-packet again, and disable the output of Closed Caption and Teletext
-data, or output data which is ignored by Closed Caption and Teletext
-decoders.
-
-A sliced VBI device may support :ref:`read/write <rw>` and/or
-streaming (:ref:`memory mapping <mmap>` and/or
-:ref:`user pointer <userp>`) I/O. The latter bears the possibility of
-synchronizing video and VBI data by using buffer timestamps.
-
-
-Sliced VBI Data in MPEG Streams
-===============================
-
-If a device can produce an MPEG output stream, it may be capable of
-providing
-:ref:`negotiated sliced VBI services <sliced-vbi-format-negotitation>`
-as data embedded in the MPEG stream. Users or applications control this
-sliced VBI data insertion with the
-:ref:`V4L2_CID_MPEG_STREAM_VBI_FMT <v4l2-mpeg-stream-vbi-fmt>`
-control.
-
-If the driver does not provide the
-:ref:`V4L2_CID_MPEG_STREAM_VBI_FMT <v4l2-mpeg-stream-vbi-fmt>`
-control, or only allows that control to be set to
-:ref:`V4L2_MPEG_STREAM_VBI_FMT_NONE <v4l2-mpeg-stream-vbi-fmt>`,
-then the device cannot embed sliced VBI data in the MPEG stream.
-
-The
-:ref:`V4L2_CID_MPEG_STREAM_VBI_FMT <v4l2-mpeg-stream-vbi-fmt>`
-control does not implicitly set the device driver to capture nor cease
-capturing sliced VBI data. The control only indicates to embed sliced
-VBI data in the MPEG stream, if an application has negotiated sliced VBI
-service be captured.
-
-It may also be the case that a device can embed sliced VBI data in only
-certain types of MPEG streams: for example in an MPEG-2 PS but not an
-MPEG-2 TS. In this situation, if sliced VBI data insertion is requested,
-the sliced VBI data will be embedded in MPEG stream types when
-supported, and silently omitted from MPEG stream types where sliced VBI
-data insertion is not supported by the device.
-
-The following subsections specify the format of the embedded sliced VBI
-data.
-
-
-MPEG Stream Embedded, Sliced VBI Data Format: NONE
---------------------------------------------------
-
-The
-:ref:`V4L2_MPEG_STREAM_VBI_FMT_NONE <v4l2-mpeg-stream-vbi-fmt>`
-embedded sliced VBI format shall be interpreted by drivers as a control
-to cease embedding sliced VBI data in MPEG streams. Neither the device
-nor driver shall insert "empty" embedded sliced VBI data packets in the
-MPEG stream when this format is set. No MPEG stream data structures are
-specified for this format.
-
-
-MPEG Stream Embedded, Sliced VBI Data Format: IVTV
---------------------------------------------------
-
-The
-:ref:`V4L2_MPEG_STREAM_VBI_FMT_IVTV <v4l2-mpeg-stream-vbi-fmt>`
-embedded sliced VBI format, when supported, indicates to the driver to
-embed up to 36 lines of sliced VBI data per frame in an MPEG-2 *Private
-Stream 1 PES* packet encapsulated in an MPEG-2 *Program Pack* in the
-MPEG stream.
-
-*Historical context*: This format specification originates from a
-custom, embedded, sliced VBI data format used by the ``ivtv`` driver.
-This format has already been informally specified in the kernel sources
-in the file ``Documentation/video4linux/cx2341x/README.vbi`` . The
-maximum size of the payload and other aspects of this format are driven
-by the CX23415 MPEG decoder's capabilities and limitations with respect
-to extracting, decoding, and displaying sliced VBI data embedded within
-an MPEG stream.
-
-This format's use is *not* exclusive to the ``ivtv`` driver *nor*
-exclusive to CX2341x devices, as the sliced VBI data packet insertion
-into the MPEG stream is implemented in driver software. At least the
-``cx18`` driver provides sliced VBI data insertion into an MPEG-2 PS in
-this format as well.
-
-The following definitions specify the payload of the MPEG-2 *Private
-Stream 1 PES* packets that contain sliced VBI data when
-:ref:`V4L2_MPEG_STREAM_VBI_FMT_IVTV <v4l2-mpeg-stream-vbi-fmt>`
-is set. (The MPEG-2 *Private Stream 1 PES* packet header and
-encapsulating MPEG-2 *Program Pack* header are not detailed here. Please
-refer to the MPEG-2 specifications for details on those packet headers.)
-
-The payload of the MPEG-2 *Private Stream 1 PES* packets that contain
-sliced VBI data is specified by struct
-:ref:`v4l2_mpeg_vbi_fmt_ivtv <v4l2-mpeg-vbi-fmt-ivtv>`. The
-payload is variable length, depending on the actual number of lines of
-sliced VBI data present in a video frame. The payload may be padded at
-the end with unspecified fill bytes to align the end of the payload to a
-4-byte boundary. The payload shall never exceed 1552 bytes (2 fields
-with 18 lines/field with 43 bytes of data/line and a 4 byte magic
-number).
-
-
-.. _v4l2-mpeg-vbi-fmt-ivtv:
-
-struct v4l2_mpeg_vbi_fmt_ivtv
------------------------------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 1 2
-
-
- - .. row 1
-
- - __u8
-
- - ``magic``\ [4]
-
- -
- - A "magic" constant from :ref:`v4l2-mpeg-vbi-fmt-ivtv-magic` that
- indicates this is a valid sliced VBI data payload and also
- indicates which member of the anonymous union, ``itv0`` or
- ``ITV0``, to use for the payload data.
-
- - .. row 2
-
- - union
-
- - (anonymous)
-
- - .. row 3
-
- -
- - struct :ref:`v4l2_mpeg_vbi_itv0 <v4l2-mpeg-vbi-itv0>`
-
- - ``itv0``
-
- - The primary form of the sliced VBI data payload that contains
- anywhere from 1 to 35 lines of sliced VBI data. Line masks are
- provided in this form of the payload indicating which VBI lines
- are provided.
-
- - .. row 4
-
- -
- - struct :ref:`v4l2_mpeg_vbi_ITV0 <v4l2-mpeg-vbi-itv0-1>`
-
- - ``ITV0``
-
- - An alternate form of the sliced VBI data payload used when 36
- lines of sliced VBI data are present. No line masks are provided
- in this form of the payload; all valid line mask bits are
- implcitly set.
-
-
-
-.. _v4l2-mpeg-vbi-fmt-ivtv-magic:
-
-Magic Constants for struct v4l2_mpeg_vbi_fmt_ivtv magic field
--------------------------------------------------------------
-
-.. flat-table::
- :header-rows: 1
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - Defined Symbol
-
- - Value
-
- - Description
-
- - .. row 2
-
- - ``V4L2_MPEG_VBI_IVTV_MAGIC0``
-
- - "itv0"
-
- - Indicates the ``itv0`` member of the union in struct
- :ref:`v4l2_mpeg_vbi_fmt_ivtv <v4l2-mpeg-vbi-fmt-ivtv>` is
- valid.
-
- - .. row 3
-
- - ``V4L2_MPEG_VBI_IVTV_MAGIC1``
-
- - "ITV0"
-
- - Indicates the ``ITV0`` member of the union in struct
- :ref:`v4l2_mpeg_vbi_fmt_ivtv <v4l2-mpeg-vbi-fmt-ivtv>` is
- valid and that 36 lines of sliced VBI data are present.
-
-
-
-.. _v4l2-mpeg-vbi-itv0:
-
-struct v4l2_mpeg_vbi_itv0
--------------------------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __le32
-
- - ``linemask``\ [2]
-
- - Bitmasks indicating the VBI service lines present. These
- ``linemask`` values are stored in little endian byte order in the
- MPEG stream. Some reference ``linemask`` bit positions with their
- corresponding VBI line number and video field are given below.
- b\ :sub:`0` indicates the least significant bit of a ``linemask``
- value:
-
-
-
- ::
-
- linemask[0] b0: line 6 first field
- linemask[0] b17: line 23 first field
- linemask[0] b18: line 6 second field
- linemask[0] b31: line 19 second field
- linemask[1] b0: line 20 second field
- linemask[1] b3: line 23 second field
- linemask[1] b4-b31: unused and set to 0
-
- - .. row 2
-
- - struct
- :ref:`v4l2_mpeg_vbi_itv0_line <v4l2-mpeg-vbi-itv0-line>`
-
- - ``line``\ [35]
-
- - This is a variable length array that holds from 1 to 35 lines of
- sliced VBI data. The sliced VBI data lines present correspond to
- the bits set in the ``linemask`` array, starting from b\ :sub:`0`
- of ``linemask``\ [0] up through b\ :sub:`31` of ``linemask``\ [0],
- and from b\ :sub:`0` of ``linemask``\ [1] up through b\ :sub:`3` of
- ``linemask``\ [1]. ``line``\ [0] corresponds to the first bit
- found set in the ``linemask`` array, ``line``\ [1] corresponds to
- the second bit found set in the ``linemask`` array, etc. If no
- ``linemask`` array bits are set, then ``line``\ [0] may contain
- one line of unspecified data that should be ignored by
- applications.
-
-
-
-.. _v4l2-mpeg-vbi-itv0-1:
-
-struct v4l2_mpeg_vbi_ITV0
--------------------------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - struct
- :ref:`v4l2_mpeg_vbi_itv0_line <v4l2-mpeg-vbi-itv0-line>`
-
- - ``line``\ [36]
-
- - A fixed length array of 36 lines of sliced VBI data. ``line``\ [0]
- through ``line``\ [17] correspond to lines 6 through 23 of the
- first field. ``line``\ [18] through ``line``\ [35] corresponds to
- lines 6 through 23 of the second field.
-
-
-
-.. _v4l2-mpeg-vbi-itv0-line:
-
-struct v4l2_mpeg_vbi_itv0_line
-------------------------------
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u8
-
- - ``id``
-
- - A line identifier value from
- :ref:`ITV0-Line-Identifier-Constants` that indicates the type of
- sliced VBI data stored on this line.
-
- - .. row 2
-
- - __u8
-
- - ``data``\ [42]
-
- - The sliced VBI data for the line.
-
-
-
-.. _ITV0-Line-Identifier-Constants:
-
-Line Identifiers for struct v4l2_mpeg_vbi_itv0_line id field
-------------------------------------------------------------
-
-.. flat-table::
- :header-rows: 1
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - Defined Symbol
-
- - Value
-
- - Description
-
- - .. row 2
-
- - ``V4L2_MPEG_VBI_IVTV_TELETEXT_B``
-
- - 1
-
- - Refer to :ref:`Sliced VBI services <vbi-services2>` for a
- description of the line payload.
-
- - .. row 3
-
- - ``V4L2_MPEG_VBI_IVTV_CAPTION_525``
-
- - 4
-
- - Refer to :ref:`Sliced VBI services <vbi-services2>` for a
- description of the line payload.
-
- - .. row 4
-
- - ``V4L2_MPEG_VBI_IVTV_WSS_625``
-
- - 5
-
- - Refer to :ref:`Sliced VBI services <vbi-services2>` for a
- description of the line payload.
-
- - .. row 5
-
- - ``V4L2_MPEG_VBI_IVTV_VPS``
-
- - 7
-
- - Refer to :ref:`Sliced VBI services <vbi-services2>` for a
- description of the line payload.
-
-
-
-.. [1]
- According to :ref:`ETS 300 706 <ets300706>` lines 6-22 of the first
- field and lines 5-22 of the second field may carry Teletext data.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _subdev:
-
-********************
-Sub-device Interface
-********************
-
-The complex nature of V4L2 devices, where hardware is often made of
-several integrated circuits that need to interact with each other in a
-controlled way, leads to complex V4L2 drivers. The drivers usually
-reflect the hardware model in software, and model the different hardware
-components as software blocks called sub-devices.
-
-V4L2 sub-devices are usually kernel-only objects. If the V4L2 driver
-implements the media device API, they will automatically inherit from
-media entities. Applications will be able to enumerate the sub-devices
-and discover the hardware topology using the media entities, pads and
-links enumeration API.
-
-In addition to make sub-devices discoverable, drivers can also choose to
-make them directly configurable by applications. When both the
-sub-device driver and the V4L2 device driver support this, sub-devices
-will feature a character device node on which ioctls can be called to
-
-- query, read and write sub-devices controls
-
-- subscribe and unsubscribe to events and retrieve them
-
-- negotiate image formats on individual pads
-
-Sub-device character device nodes, conventionally named
-``/dev/v4l-subdev*``, use major number 81.
-
-
-Controls
-========
-
-Most V4L2 controls are implemented by sub-device hardware. Drivers
-usually merge all controls and expose them through video device nodes.
-Applications can control all sub-devices through a single interface.
-
-Complex devices sometimes implement the same control in different pieces
-of hardware. This situation is common in embedded platforms, where both
-sensors and image processing hardware implement identical functions,
-such as contrast adjustment, white balance or faulty pixels correction.
-As the V4L2 controls API doesn't support several identical controls in a
-single device, all but one of the identical controls are hidden.
-
-Applications can access those hidden controls through the sub-device
-node with the V4L2 control API described in :ref:`control`. The ioctls
-behave identically as when issued on V4L2 device nodes, with the
-exception that they deal only with controls implemented in the
-sub-device.
-
-Depending on the driver, those controls might also be exposed through
-one (or several) V4L2 device nodes.
-
-
-Events
-======
-
-V4L2 sub-devices can notify applications of events as described in
-:ref:`event`. The API behaves identically as when used on V4L2 device
-nodes, with the exception that it only deals with events generated by
-the sub-device. Depending on the driver, those events might also be
-reported on one (or several) V4L2 device nodes.
-
-
-.. _pad-level-formats:
-
-Pad-level Formats
-=================
-
- **Warning**
-
- Pad-level formats are only applicable to very complex device that
- need to expose low-level format configuration to user space. Generic
- V4L2 applications do *not* need to use the API described in this
- section.
-
- **Note**
-
- For the purpose of this section, the term *format* means the
- combination of media bus data format, frame width and frame height.
-
-Image formats are typically negotiated on video capture and output
-devices using the format and
-:ref:`selection <VIDIOC_SUBDEV_G_SELECTION>` ioctls. The driver is
-responsible for configuring every block in the video pipeline according
-to the requested format at the pipeline input and/or output.
-
-For complex devices, such as often found in embedded systems, identical
-image sizes at the output of a pipeline can be achieved using different
-hardware configurations. One such example is shown on
-:ref:`pipeline-scaling`, where image scaling can be performed on both
-the video sensor and the host image processing hardware.
-
-
-.. _pipeline-scaling:
-
-.. figure:: dev-subdev_files/pipeline.*
- :alt: pipeline.pdf / pipeline.png
- :align: center
-
- Image Format Negotiation on Pipelines
-
- High quality and high speed pipeline configuration
-
-
-
-The sensor scaler is usually of less quality than the host scaler, but
-scaling on the sensor is required to achieve higher frame rates.
-Depending on the use case (quality vs. speed), the pipeline must be
-configured differently. Applications need to configure the formats at
-every point in the pipeline explicitly.
-
-Drivers that implement the :ref:`media API <media-controller-intro>`
-can expose pad-level image format configuration to applications. When
-they do, applications can use the
-:ref:`VIDIOC_SUBDEV_G_FMT <VIDIOC_SUBDEV_G_FMT>` and
-:ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` ioctls. to
-negotiate formats on a per-pad basis.
-
-Applications are responsible for configuring coherent parameters on the
-whole pipeline and making sure that connected pads have compatible
-formats. The pipeline is checked for formats mismatch at
-:ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` time, and an ``EPIPE`` error
-code is then returned if the configuration is invalid.
-
-Pad-level image format configuration support can be tested by calling
-the :ref:`VIDIOC_SUBDEV_G_FMT` ioctl on pad
-0. If the driver returns an ``EINVAL`` error code pad-level format
-configuration is not supported by the sub-device.
-
-
-Format Negotiation
-------------------
-
-Acceptable formats on pads can (and usually do) depend on a number of
-external parameters, such as formats on other pads, active links, or
-even controls. Finding a combination of formats on all pads in a video
-pipeline, acceptable to both application and driver, can't rely on
-formats enumeration only. A format negotiation mechanism is required.
-
-Central to the format negotiation mechanism are the get/set format
-operations. When called with the ``which`` argument set to
-:ref:`V4L2_SUBDEV_FORMAT_TRY <VIDIOC_SUBDEV_G_FMT>`, the
-:ref:`VIDIOC_SUBDEV_G_FMT <VIDIOC_SUBDEV_G_FMT>` and
-:ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` ioctls operate on
-a set of formats parameters that are not connected to the hardware
-configuration. Modifying those 'try' formats leaves the device state
-untouched (this applies to both the software state stored in the driver
-and the hardware state stored in the device itself).
-
-While not kept as part of the device state, try formats are stored in
-the sub-device file handles. A
-:ref:`VIDIOC_SUBDEV_G_FMT <VIDIOC_SUBDEV_G_FMT>` call will return
-the last try format set *on the same sub-device file handle*. Several
-applications querying the same sub-device at the same time will thus not
-interact with each other.
-
-To find out whether a particular format is supported by the device,
-applications use the
-:ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` ioctl. Drivers
-verify and, if needed, change the requested ``format`` based on device
-requirements and return the possibly modified value. Applications can
-then choose to try a different format or accept the returned value and
-continue.
-
-Formats returned by the driver during a negotiation iteration are
-guaranteed to be supported by the device. In particular, drivers
-guarantee that a returned format will not be further changed if passed
-to an :ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` call as-is
-(as long as external parameters, such as formats on other pads or links'
-configuration are not changed).
-
-Drivers automatically propagate formats inside sub-devices. When a try
-or active format is set on a pad, corresponding formats on other pads of
-the same sub-device can be modified by the driver. Drivers are free to
-modify formats as required by the device. However, they should comply
-with the following rules when possible:
-
-- Formats should be propagated from sink pads to source pads. Modifying
- a format on a source pad should not modify the format on any sink
- pad.
-
-- Sub-devices that scale frames using variable scaling factors should
- reset the scale factors to default values when sink pads formats are
- modified. If the 1:1 scaling ratio is supported, this means that
- source pads formats should be reset to the sink pads formats.
-
-Formats are not propagated across links, as that would involve
-propagating them from one sub-device file handle to another.
-Applications must then take care to configure both ends of every link
-explicitly with compatible formats. Identical formats on the two ends of
-a link are guaranteed to be compatible. Drivers are free to accept
-different formats matching device requirements as being compatible.
-
-:ref:`sample-pipeline-config` shows a sample configuration sequence
-for the pipeline described in :ref:`pipeline-scaling` (table columns
-list entity names and pad numbers).
-
-
-.. _sample-pipeline-config:
-
-.. flat-table:: Sample Pipeline Configuration
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- -
- - Sensor/0 format
-
- - Frontend/0 format
-
- - Frontend/1 format
-
- - Scaler/0 format
-
- - Scaler/0 compose selection rectangle
-
- - Scaler/1 format
-
- - .. row 2
-
- - Initial state
-
- - 2048x1536/SGRBG8_1X8
-
- - (default)
-
- - (default)
-
- - (default)
-
- - (default)
-
- - (default)
-
- - .. row 3
-
- - Configure frontend sink format
-
- - 2048x1536/SGRBG8_1X8
-
- - *2048x1536/SGRBG8_1X8*
-
- - *2046x1534/SGRBG8_1X8*
-
- - (default)
-
- - (default)
-
- - (default)
-
- - .. row 4
-
- - Configure scaler sink format
-
- - 2048x1536/SGRBG8_1X8
-
- - 2048x1536/SGRBG8_1X8
-
- - 2046x1534/SGRBG8_1X8
-
- - *2046x1534/SGRBG8_1X8*
-
- - *0,0/2046x1534*
-
- - *2046x1534/SGRBG8_1X8*
-
- - .. row 5
-
- - Configure scaler sink compose selection
-
- - 2048x1536/SGRBG8_1X8
-
- - 2048x1536/SGRBG8_1X8
-
- - 2046x1534/SGRBG8_1X8
-
- - 2046x1534/SGRBG8_1X8
-
- - *0,0/1280x960*
-
- - *1280x960/SGRBG8_1X8*
-
-
-
-1. Initial state. The sensor source pad format is set to its native 3MP
- size and V4L2_MBUS_FMT_SGRBG8_1X8 media bus code. Formats on the
- host frontend and scaler sink and source pads have the default
- values, as well as the compose rectangle on the scaler's sink pad.
-
-2. The application configures the frontend sink pad format's size to
- 2048x1536 and its media bus code to V4L2_MBUS_FMT_SGRBG_1X8. The
- driver propagates the format to the frontend source pad.
-
-3. The application configures the scaler sink pad format's size to
- 2046x1534 and the media bus code to V4L2_MBUS_FMT_SGRBG_1X8 to
- match the frontend source size and media bus code. The media bus code
- on the sink pad is set to V4L2_MBUS_FMT_SGRBG_1X8. The driver
- propagates the size to the compose selection rectangle on the
- scaler's sink pad, and the format to the scaler source pad.
-
-4. The application configures the size of the compose selection
- rectangle of the scaler's sink pad 1280x960. The driver propagates
- the size to the scaler's source pad format.
-
-When satisfied with the try results, applications can set the active
-formats by setting the ``which`` argument to
-``V4L2_SUBDEV_FORMAT_ACTIVE``. Active formats are changed exactly as try
-formats by drivers. To avoid modifying the hardware state during format
-negotiation, applications should negotiate try formats first and then
-modify the active settings using the try formats returned during the
-last negotiation iteration. This guarantees that the active format will
-be applied as-is by the driver without being modified.
-
-
-.. _v4l2-subdev-selections:
-
-Selections: cropping, scaling and composition
----------------------------------------------
-
-Many sub-devices support cropping frames on their input or output pads
-(or possible even on both). Cropping is used to select the area of
-interest in an image, typically on an image sensor or a video decoder.
-It can also be used as part of digital zoom implementations to select
-the area of the image that will be scaled up.
-
-Crop settings are defined by a crop rectangle and represented in a
-struct :ref:`v4l2_rect <v4l2-rect>` by the coordinates of the top
-left corner and the rectangle size. Both the coordinates and sizes are
-expressed in pixels.
-
-As for pad formats, drivers store try and active rectangles for the
-selection targets :ref:`v4l2-selections-common`.
-
-On sink pads, cropping is applied relative to the current pad format.
-The pad format represents the image size as received by the sub-device
-from the previous block in the pipeline, and the crop rectangle
-represents the sub-image that will be transmitted further inside the
-sub-device for processing.
-
-The scaling operation changes the size of the image by scaling it to new
-dimensions. The scaling ratio isn't specified explicitly, but is implied
-from the original and scaled image sizes. Both sizes are represented by
-struct :ref:`v4l2_rect <v4l2-rect>`.
-
-Scaling support is optional. When supported by a subdev, the crop
-rectangle on the subdev's sink pad is scaled to the size configured
-using the
-:ref:`VIDIOC_SUBDEV_S_SELECTION <VIDIOC_SUBDEV_G_SELECTION>` IOCTL
-using ``V4L2_SEL_TGT_COMPOSE`` selection target on the same pad. If the
-subdev supports scaling but not composing, the top and left values are
-not used and must always be set to zero.
-
-On source pads, cropping is similar to sink pads, with the exception
-that the source size from which the cropping is performed, is the
-COMPOSE rectangle on the sink pad. In both sink and source pads, the
-crop rectangle must be entirely contained inside the source image size
-for the crop operation.
-
-The drivers should always use the closest possible rectangle the user
-requests on all selection targets, unless specifically told otherwise.
-``V4L2_SEL_FLAG_GE`` and ``V4L2_SEL_FLAG_LE`` flags may be used to round
-the image size either up or down. :ref:`v4l2-selection-flags`
-
-
-Types of selection targets
---------------------------
-
-
-Actual targets
-^^^^^^^^^^^^^^
-
-Actual targets (without a postfix) reflect the actual hardware
-configuration at any point of time. There is a BOUNDS target
-corresponding to every actual target.
-
-
-BOUNDS targets
-^^^^^^^^^^^^^^
-
-BOUNDS targets is the smallest rectangle that contains all valid actual
-rectangles. It may not be possible to set the actual rectangle as large
-as the BOUNDS rectangle, however. This may be because e.g. a sensor's
-pixel array is not rectangular but cross-shaped or round. The maximum
-size may also be smaller than the BOUNDS rectangle.
-
-
-Order of configuration and format propagation
----------------------------------------------
-
-Inside subdevs, the order of image processing steps will always be from
-the sink pad towards the source pad. This is also reflected in the order
-in which the configuration must be performed by the user: the changes
-made will be propagated to any subsequent stages. If this behaviour is
-not desired, the user must set ``V4L2_SEL_FLAG_KEEP_CONFIG`` flag. This
-flag causes no propagation of the changes are allowed in any
-circumstances. This may also cause the accessed rectangle to be adjusted
-by the driver, depending on the properties of the underlying hardware.
-
-The coordinates to a step always refer to the actual size of the
-previous step. The exception to this rule is the source compose
-rectangle, which refers to the sink compose bounds rectangle --- if it
-is supported by the hardware.
-
-1. Sink pad format. The user configures the sink pad format. This format
- defines the parameters of the image the entity receives through the
- pad for further processing.
-
-2. Sink pad actual crop selection. The sink pad crop defines the crop
- performed to the sink pad format.
-
-3. Sink pad actual compose selection. The size of the sink pad compose
- rectangle defines the scaling ratio compared to the size of the sink
- pad crop rectangle. The location of the compose rectangle specifies
- the location of the actual sink compose rectangle in the sink compose
- bounds rectangle.
-
-4. Source pad actual crop selection. Crop on the source pad defines crop
- performed to the image in the sink compose bounds rectangle.
-
-5. Source pad format. The source pad format defines the output pixel
- format of the subdev, as well as the other parameters with the
- exception of the image width and height. Width and height are defined
- by the size of the source pad actual crop selection.
-
-Accessing any of the above rectangles not supported by the subdev will
-return ``EINVAL``. Any rectangle referring to a previous unsupported
-rectangle coordinates will instead refer to the previous supported
-rectangle. For example, if sink crop is not supported, the compose
-selection will refer to the sink pad format dimensions instead.
-
-
-.. _subdev-image-processing-crop:
-
-.. figure:: dev-subdev_files/subdev-image-processing-crop.*
- :alt: subdev-image-processing-crop.svg
- :align: center
-
- **Figure 4.5. Image processing in subdevs: simple crop example**
-
-In the above example, the subdev supports cropping on its sink pad. To
-configure it, the user sets the media bus format on the subdev's sink
-pad. Now the actual crop rectangle can be set on the sink pad --- the
-location and size of this rectangle reflect the location and size of a
-rectangle to be cropped from the sink format. The size of the sink crop
-rectangle will also be the size of the format of the subdev's source
-pad.
-
-
-.. _subdev-image-processing-scaling-multi-source:
-
-.. figure:: dev-subdev_files/subdev-image-processing-scaling-multi-source.*
- :alt: subdev-image-processing-scaling-multi-source.svg
- :align: center
-
- **Figure 4.6. Image processing in subdevs: scaling with multiple sources**
-
-In this example, the subdev is capable of first cropping, then scaling
-and finally cropping for two source pads individually from the resulting
-scaled image. The location of the scaled image in the cropped image is
-ignored in sink compose target. Both of the locations of the source crop
-rectangles refer to the sink scaling rectangle, independently cropping
-an area at location specified by the source crop rectangle from it.
-
-
-.. _subdev-image-processing-full:
-
-.. figure:: dev-subdev_files/subdev-image-processing-full.*
- :alt: subdev-image-processing-full.svg
- :align: center
-
- **Figure 4.7. Image processing in subdevs: scaling and composition with multiple sinks and sources**
-
-The subdev driver supports two sink pads and two source pads. The images
-from both of the sink pads are individually cropped, then scaled and
-further composed on the composition bounds rectangle. From that, two
-independent streams are cropped and sent out of the subdev from the
-source pads.
-
-
-.. toctree::
- :maxdepth: 1
-
- subdev-formats
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/PR-SVG-20010719/DTD/svg10.dtd">
-<svg width="43cm" height="10cm" viewBox="-194 128 844 196" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x="-8" y="130" width="469.774" height="193"/>
- <g>
- <rect style="fill: #ffffff" x="4.5" y="189" width="159" height="104"/>
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a52a2a" x="4.5" y="189" width="159" height="104"/>
- </g>
- <g>
- <rect style="fill: #ffffff" x="63.5" y="211" width="94" height="77"/>
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" x="63.5" y="211" width="94" height="77"/>
- </g>
- <text style="fill: #0000ff;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="74.5" y="227.75">
- <tspan x="74.5" y="227.75">sink</tspan>
- <tspan x="74.5" y="243.75">crop</tspan>
- <tspan x="74.5" y="259.75">selection</tspan>
- </text>
- <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="29.5" y="158">
- <tspan x="29.5" y="158"></tspan>
- </text>
- <text style="fill: #a52a2a;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="8.53836" y="157.914">
- <tspan x="8.53836" y="157.914">sink media</tspan>
- <tspan x="8.53836" y="173.914">bus format</tspan>
- </text>
- <text style="fill: #8b6914;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="349.774" y="155">
- <tspan x="349.774" y="155">source media</tspan>
- <tspan x="349.774" y="171">bus format</tspan>
- </text>
- <g>
- <rect style="fill: #ffffff" x="350.488" y="190.834" width="93.2863" height="75.166"/>
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #8b6914" x="350.488" y="190.834" width="93.2863" height="75.166"/>
- </g>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="350.488" y1="266" x2="63.5" y2="288"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="350.488" y1="190.834" x2="63.5" y2="211"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="443.774" y1="266" x2="157.5" y2="288"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="443.774" y1="190.834" x2="157.5" y2="211"/>
- <g>
- <ellipse style="fill: #ffffff" cx="473.1" cy="219.984" rx="8.5" ry="8.5"/>
- <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="473.1" cy="219.984" rx="8.5" ry="8.5"/>
- <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="473.1" cy="219.984" rx="8.5" ry="8.5"/>
- </g>
- <g>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="481.6" y1="219.984" x2="637.934" y2="220.012"/>
- <polygon style="fill: #000000" points="645.434,220.014 635.433,225.012 637.934,220.012 635.435,215.012 "/>
- <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="645.434,220.014 635.433,225.012 637.934,220.012 635.435,215.012 "/>
- </g>
- <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="506.908" y="209.8">
- <tspan x="506.908" y="209.8">pad 1 (source)</tspan>
- </text>
- <g>
- <ellipse style="fill: #ffffff" cx="-20.3982" cy="241.512" rx="8.5" ry="8.5"/>
- <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-20.3982" cy="241.512" rx="8.5" ry="8.5"/>
- <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-20.3982" cy="241.512" rx="8.5" ry="8.5"/>
- </g>
- <g>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="-192.398" y1="241.8" x2="-38.6343" y2="241.529"/>
- <polygon style="fill: #000000" points="-31.1343,241.516 -41.1254,246.534 -38.6343,241.529 -41.1431,236.534 "/>
- <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="-31.1343,241.516 -41.1254,246.534 -38.6343,241.529 -41.1431,236.534 "/>
- </g>
- <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="-147.858" y="229.8">
- <tspan x="-147.858" y="229.8">pad 0 (sink)</tspan>
- </text>
-</svg>
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/PR-SVG-20010719/DTD/svg10.dtd">
-<svg width="59cm" height="18cm" viewBox="-186 71 1178 346" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
- <g>
- <rect style="fill: #ffffff" x="318.9" y="129" width="208.1" height="249"/>
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #ff765a" x="318.9" y="129" width="208.1" height="249"/>
- </g>
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x="-2" y="73" width="806" height="343"/>
- <g>
- <ellipse style="fill: #ffffff" cx="-12.5" cy="166.712" rx="8.5" ry="8.5"/>
- <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-12.5" cy="166.712" rx="8.5" ry="8.5"/>
- <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-12.5" cy="166.712" rx="8.5" ry="8.5"/>
- </g>
- <g>
- <ellipse style="fill: #ffffff" cx="815.232" cy="205.184" rx="8.5" ry="8.5"/>
- <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="815.232" cy="205.184" rx="8.5" ry="8.5"/>
- <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="815.232" cy="205.184" rx="8.5" ry="8.5"/>
- </g>
- <g>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="-184.5" y1="167" x2="-30.7361" y2="166.729"/>
- <polygon style="fill: #000000" points="-23.2361,166.716 -33.2272,171.734 -30.7361,166.729 -33.2449,161.734 "/>
- <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="-23.2361,166.716 -33.2272,171.734 -30.7361,166.729 -33.2449,161.734 "/>
- </g>
- <g>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="823.732" y1="205.184" x2="980.066" y2="205.212"/>
- <polygon style="fill: #000000" points="987.566,205.214 977.565,210.212 980.066,205.212 977.567,200.212 "/>
- <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="987.566,205.214 977.565,210.212 980.066,205.212 977.567,200.212 "/>
- </g>
- <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="-139.96" y="155">
- <tspan x="-139.96" y="155">pad 0 (sink)</tspan>
- </text>
- <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="849.04" y="195">
- <tspan x="849.04" y="195">pad 2 (source)</tspan>
- </text>
- <g>
- <rect style="fill: #ffffff" x="5.5" y="120" width="159" height="104"/>
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a52a2a" x="5.5" y="120" width="159" height="104"/>
- </g>
- <g>
- <rect style="fill: #ffffff" x="62.5" y="136" width="94" height="77"/>
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" x="62.5" y="136" width="94" height="77"/>
- </g>
- <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="30.5" y="89">
- <tspan x="30.5" y="89"></tspan>
- </text>
- <text style="fill: #a52a2a;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="9.53836" y="88.9138">
- <tspan x="9.53836" y="88.9138">sink media</tspan>
- <tspan x="9.53836" y="104.914">bus format</tspan>
- </text>
- <g>
- <rect style="fill: #ffffff" x="333.644" y="185.65" width="165.2" height="172.478"/>
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #00ff00" x="333.644" y="185.65" width="165.2" height="172.478"/>
- </g>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="333.644" y1="358.128" x2="62.5" y2="213"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="333.644" y1="185.65" x2="62.5" y2="136"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="498.844" y1="358.128" x2="156.5" y2="213"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="498.844" y1="185.65" x2="156.5" y2="136"/>
- <text style="fill: #00ff00;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="334.704" y="149.442">
- <tspan x="334.704" y="149.442">sink compose</tspan>
- <tspan x="334.704" y="165.442">selection (scaling)</tspan>
- </text>
- <g>
- <rect style="fill: #ffffff" x="409.322" y="194.565" width="100.186" height="71.4523"/>
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x="409.322" y="194.565" width="100.186" height="71.4523"/>
- </g>
- <text style="fill: #8b6914;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="689.5" y="105.128">
- <tspan x="689.5" y="105.128">source media</tspan>
- <tspan x="689.5" y="121.128">bus format</tspan>
- </text>
- <g>
- <rect style="fill: #ffffff" x="688.488" y="173.834" width="100.186" height="71.4523"/>
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #8b6914" x="688.488" y="173.834" width="100.186" height="71.4523"/>
- </g>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="688.488" y1="245.286" x2="409.322" y2="266.018"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="688.488" y1="173.834" x2="409.322" y2="194.565"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="788.674" y1="245.286" x2="509.508" y2="266.018"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="788.674" y1="173.834" x2="509.508" y2="194.565"/>
- <text style="fill: #ff765a;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="325" y="103">
- <tspan x="325" y="103">sink compose</tspan>
- <tspan x="325" y="119">bounds selection</tspan>
- </text>
- <g>
- <ellipse style="fill: #ffffff" cx="-12.0982" cy="341.512" rx="8.5" ry="8.5"/>
- <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-12.0982" cy="341.512" rx="8.5" ry="8.5"/>
- <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-12.0982" cy="341.512" rx="8.5" ry="8.5"/>
- </g>
- <g>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="-184.098" y1="341.8" x2="-30.3343" y2="341.529"/>
- <polygon style="fill: #000000" points="-22.8343,341.516 -32.8254,346.534 -30.3343,341.529 -32.8431,336.534 "/>
- <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="-22.8343,341.516 -32.8254,346.534 -30.3343,341.529 -32.8431,336.534 "/>
- </g>
- <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="-139" y="329">
- <tspan x="-139" y="329">pad 1 (sink)</tspan>
- </text>
- <g>
- <rect style="fill: #ffffff" x="7.80824" y="292.8" width="112.092" height="82.2"/>
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a52a2a" x="7.80824" y="292.8" width="112.092" height="82.2"/>
- </g>
- <g>
- <rect style="fill: #ffffff" x="52.9" y="314.8" width="58.1" height="50.2"/>
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" x="52.9" y="314.8" width="58.1" height="50.2"/>
- </g>
- <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="31.9" y="259.8">
- <tspan x="31.9" y="259.8"></tspan>
- </text>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="358.9" y1="251.9" x2="52.9" y2="314.8"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="358.9" y1="316" x2="52.9" y2="365"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="434" y1="316" x2="111" y2="365"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="434" y1="251.9" x2="111" y2="314.8"/>
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #00ff00" x="358.9" y="251.9" width="75.1" height="64.1"/>
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x="443.262" y="284.466" width="64.738" height="48.534"/>
- <g>
- <rect style="fill: #ffffff" x="693.428" y="324.734" width="63.572" height="49.266"/>
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #8b6914" x="693.428" y="324.734" width="63.572" height="49.266"/>
- </g>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="693.428" y1="374" x2="443.262" y2="333"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="693.428" y1="324.734" x2="443.262" y2="284.466"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="757" y1="374" x2="508" y2="333"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="757" y1="324.734" x2="508" y2="284.466"/>
- <g>
- <ellipse style="fill: #ffffff" cx="815.44" cy="343.984" rx="8.5" ry="8.5"/>
- <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="815.44" cy="343.984" rx="8.5" ry="8.5"/>
- <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="815.44" cy="343.984" rx="8.5" ry="8.5"/>
- </g>
- <g>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="823.94" y1="343.984" x2="980.274" y2="344.012"/>
- <polygon style="fill: #000000" points="987.774,344.014 977.773,349.012 980.274,344.012 977.775,339.012 "/>
- <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="987.774,344.014 977.773,349.012 980.274,344.012 977.775,339.012 "/>
- </g>
- <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="849.248" y="333.8">
- <tspan x="849.248" y="333.8">pad 3 (source)</tspan>
- </text>
- <text style="fill: #0000ff;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="197" y="91">
- <tspan x="197" y="91">sink</tspan>
- <tspan x="197" y="107">crop</tspan>
- <tspan x="197" y="123">selection</tspan>
- </text>
- <text style="fill: #a020f0;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="553" y="95">
- <tspan x="553" y="95">source</tspan>
- <tspan x="553" y="111">crop</tspan>
- <tspan x="553" y="127">selection</tspan>
- </text>
- <g>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" x1="211" y1="132" x2="166.21" y2="135.287"/>
- <polygon style="fill: #0000ff" points="158.73,135.836 168.337,130.118 166.21,135.287 169.069,140.091 "/>
- <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" points="158.73,135.836 168.337,130.118 166.21,135.287 169.069,140.091 "/>
- </g>
- <g>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" x1="209" y1="131" x2="115.581" y2="306.209"/>
- <polygon style="fill: #0000ff" points="112.052,312.827 112.345,301.65 115.581,306.209 121.169,306.355 "/>
- <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" points="112.052,312.827 112.345,301.65 115.581,306.209 121.169,306.355 "/>
- </g>
- <g>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x1="550.492" y1="133.214" x2="514.916" y2="186.469"/>
- <polygon style="fill: #a020f0" points="510.75,192.706 512.147,181.613 514.916,186.469 520.463,187.168 "/>
- <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" points="510.75,192.706 512.147,181.613 514.916,186.469 520.463,187.168 "/>
- </g>
- <g>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x1="550.072" y1="133.787" x2="510.618" y2="275.089"/>
- <polygon style="fill: #a020f0" points="508.601,282.312 506.475,271.336 510.618,275.089 516.106,274.025 "/>
- <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" points="508.601,282.312 506.475,271.336 510.618,275.089 516.106,274.025 "/>
- </g>
-</svg>
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/PR-SVG-20010719/DTD/svg10.dtd">
-<svg width="59cm" height="17cm" viewBox="-194 128 1179 330" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x="-8" y="130" width="806" height="327"/>
- <g>
- <rect style="fill: #ffffff" x="4.5" y="189" width="159" height="104"/>
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a52a2a" x="4.5" y="189" width="159" height="104"/>
- </g>
- <g>
- <rect style="fill: #ffffff" x="49.5" y="204" width="94" height="77"/>
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" x="49.5" y="204" width="94" height="77"/>
- </g>
- <text style="fill: #0000ff;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="60" y="224">
- <tspan x="60" y="224">sink</tspan>
- <tspan x="60" y="240">crop</tspan>
- <tspan x="60" y="256">selection</tspan>
- </text>
- <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="29.5" y="158">
- <tspan x="29.5" y="158"></tspan>
- </text>
- <text style="fill: #a52a2a;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="8.53836" y="157.914">
- <tspan x="8.53836" y="157.914">sink media</tspan>
- <tspan x="8.53836" y="173.914">bus format</tspan>
- </text>
- <g>
- <rect style="fill: #ffffff" x="333.644" y="185.65" width="165.2" height="172.478"/>
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #00ff00" x="333.644" y="185.65" width="165.2" height="172.478"/>
- </g>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="333.644" y1="358.128" x2="49.5" y2="281"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="333.644" y1="185.65" x2="49.5" y2="204"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="498.844" y1="358.128" x2="143.5" y2="281"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="498.844" y1="185.65" x2="143.5" y2="204"/>
- <text style="fill: #00ff00;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="334.704" y="149.442">
- <tspan x="334.704" y="149.442">sink compose</tspan>
- <tspan x="334.704" y="165.442">selection (scaling)</tspan>
- </text>
- <g>
- <rect style="fill: #ffffff" x="382.322" y="199.565" width="100.186" height="71.4523"/>
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x="382.322" y="199.565" width="100.186" height="71.4523"/>
- </g>
- <text style="fill: #a020f0;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="543.322" y="149.442">
- <tspan x="543.322" y="149.442">source</tspan>
- <tspan x="543.322" y="165.442">crop</tspan>
- <tspan x="543.322" y="181.442">selection</tspan>
- </text>
- <text style="fill: #8b6914;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="691.5" y="157.128">
- <tspan x="691.5" y="157.128">source media</tspan>
- <tspan x="691.5" y="173.128">bus format</tspan>
- </text>
- <g>
- <rect style="fill: #ffffff" x="690.488" y="225.834" width="100.186" height="71.4523"/>
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #8b6914" x="690.488" y="225.834" width="100.186" height="71.4523"/>
- </g>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="690.488" y1="297.286" x2="382.322" y2="271.018"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="690.488" y1="225.834" x2="382.322" y2="199.565"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="790.674" y1="297.286" x2="482.508" y2="271.018"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="790.674" y1="225.834" x2="482.508" y2="199.565"/>
- <g>
- <ellipse style="fill: #ffffff" cx="808.1" cy="249.984" rx="8.5" ry="8.5"/>
- <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="808.1" cy="249.984" rx="8.5" ry="8.5"/>
- <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="808.1" cy="249.984" rx="8.5" ry="8.5"/>
- </g>
- <g>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="816.6" y1="249.984" x2="972.934" y2="250.012"/>
- <polygon style="fill: #000000" points="980.434,250.014 970.433,255.012 972.934,250.012 970.435,245.012 "/>
- <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="980.434,250.014 970.433,255.012 972.934,250.012 970.435,245.012 "/>
- </g>
- <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="841.908" y="239.8">
- <tspan x="841.908" y="239.8">pad 1 (source)</tspan>
- </text>
- <g>
- <ellipse style="fill: #ffffff" cx="-20.3982" cy="241.512" rx="8.5" ry="8.5"/>
- <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-20.3982" cy="241.512" rx="8.5" ry="8.5"/>
- <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-20.3982" cy="241.512" rx="8.5" ry="8.5"/>
- </g>
- <g>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="-192.398" y1="241.8" x2="-38.6343" y2="241.529"/>
- <polygon style="fill: #000000" points="-31.1343,241.516 -41.1254,246.534 -38.6343,241.529 -41.1431,236.534 "/>
- <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="-31.1343,241.516 -41.1254,246.534 -38.6343,241.529 -41.1431,236.534 "/>
- </g>
- <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="-147.858" y="229.8">
- <tspan x="-147.858" y="229.8">pad 0 (sink)</tspan>
- </text>
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x="389.822" y="276.666" width="100.186" height="71.4523"/>
- <g>
- <rect style="fill: #ffffff" x="689.988" y="345.934" width="100.186" height="71.4523"/>
- <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #8b6914" x="689.988" y="345.934" width="100.186" height="71.4523"/>
- </g>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="689.988" y1="417.386" x2="389.822" y2="348.118"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="689.988" y1="345.934" x2="389.822" y2="276.666"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="790.174" y1="417.386" x2="490.008" y2="348.118"/>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="790.174" y1="345.934" x2="490.008" y2="276.666"/>
- <g>
- <ellipse style="fill: #ffffff" cx="805.6" cy="384.084" rx="8.5" ry="8.5"/>
- <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="805.6" cy="384.084" rx="8.5" ry="8.5"/>
- <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="805.6" cy="384.084" rx="8.5" ry="8.5"/>
- </g>
- <g>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="814.1" y1="384.084" x2="970.434" y2="384.112"/>
- <polygon style="fill: #000000" points="977.934,384.114 967.933,389.112 970.434,384.112 967.935,379.112 "/>
- <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="977.934,384.114 967.933,389.112 970.434,384.112 967.935,379.112 "/>
- </g>
- <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="839.408" y="373.9">
- <tspan x="839.408" y="373.9">pad 2 (source)</tspan>
- </text>
- <g>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x1="546" y1="191" x2="492.157" y2="198.263"/>
- <polygon style="fill: #a020f0" points="484.724,199.266 493.966,192.974 492.157,198.263 495.303,202.884 "/>
- <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" points="484.724,199.266 493.966,192.974 492.157,198.263 495.303,202.884 "/>
- </g>
- <g>
- <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x1="546.908" y1="190.725" x2="495.383" y2="268.548"/>
- <polygon style="fill: #a020f0" points="491.242,274.802 492.594,263.703 495.383,268.548 500.932,269.224 "/>
- <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" points="491.242,274.802 492.594,263.703 495.383,268.548 500.932,269.224 "/>
- </g>
-</svg>
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _ttx:
-
-******************
-Teletext Interface
-******************
-
-This interface was aimed at devices receiving and demodulating Teletext
-data [:ref:`ets300706`, :ref:`itu653`], evaluating the Teletext
-packages and storing formatted pages in cache memory. Such devices are
-usually implemented as microcontrollers with serial interface
-(I:sup:`2`\ C) and could be found on old TV cards, dedicated Teletext
-decoding cards and home-brew devices connected to the PC parallel port.
-
-The Teletext API was designed by Martin Buck. It was defined in the
-kernel header file ``linux/videotext.h``, the specification is available
-from
-`ftp://ftp.gwdg.de/pub/linux/misc/videotext/ <ftp://ftp.gwdg.de/pub/linux/misc/videotext/>`__.
-(Videotext is the name of the German public television Teletext
-service.)
-
-Eventually the Teletext API was integrated into the V4L API with
-character device file names ``/dev/vtx0`` to ``/dev/vtx31``, device
-major number 81, minor numbers 192 to 223.
-
-However, teletext decoders were quickly replaced by more generic VBI
-demodulators and those dedicated teletext decoders no longer exist. For
-many years the vtx devices were still around, even though nobody used
-them. So the decision was made to finally remove support for the
-Teletext API in kernel 2.6.37.
-
-Modern devices all use the :ref:`raw <raw-vbi>` or
-:ref:`sliced` VBI API.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _devices:
-
-**********
-Interfaces
-**********
-
-
-.. toctree::
- :maxdepth: 1
-
- dev-capture
- dev-overlay
- dev-output
- dev-osd
- dev-codec
- dev-effect
- dev-raw-vbi
- dev-sliced-vbi
- dev-teletext
- dev-radio
- dev-rds
- dev-sdr
- dev-event
- dev-subdev
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _diff-v4l:
-
-********************************
-Differences between V4L and V4L2
-********************************
-
-The Video For Linux API was first introduced in Linux 2.1 to unify and
-replace various TV and radio device related interfaces, developed
-independently by driver writers in prior years. Starting with Linux 2.5
-the much improved V4L2 API replaces the V4L API. The support for the old
-V4L calls were removed from Kernel, but the library :ref:`libv4l`
-supports the conversion of a V4L API system call into a V4L2 one.
-
-
-Opening and Closing Devices
-===========================
-
-For compatibility reasons the character device file names recommended
-for V4L2 video capture, overlay, radio and raw vbi capture devices did
-not change from those used by V4L. They are listed in :ref:`devices`
-and below in :ref:`v4l-dev`.
-
-The teletext devices (minor range 192-223) have been removed in V4L2 and
-no longer exist. There is no hardware available anymore for handling
-pure teletext. Instead raw or sliced VBI is used.
-
-The V4L ``videodev`` module automatically assigns minor numbers to
-drivers in load order, depending on the registered device type. We
-recommend that V4L2 drivers by default register devices with the same
-numbers, but the system administrator can assign arbitrary minor numbers
-using driver module options. The major device number remains 81.
-
-
-.. _v4l-dev:
-
-.. flat-table:: V4L Device Types, Names and Numbers
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - Device Type
-
- - File Name
-
- - Minor Numbers
-
- - .. row 2
-
- - Video capture and overlay
-
- - ``/dev/video`` and ``/dev/bttv0``\ [1]_, ``/dev/video0`` to
- ``/dev/video63``
-
- - 0-63
-
- - .. row 3
-
- - Radio receiver
-
- - ``/dev/radio``\ [2]_, ``/dev/radio0`` to ``/dev/radio63``
-
- - 64-127
-
- - .. row 4
-
- - Raw VBI capture
-
- - ``/dev/vbi``, ``/dev/vbi0`` to ``/dev/vbi31``
-
- - 224-255
-
-
-V4L prohibits (or used to prohibit) multiple opens of a device file.
-V4L2 drivers *may* support multiple opens, see :ref:`open` for details
-and consequences.
-
-V4L drivers respond to V4L2 ioctls with an ``EINVAL`` error code.
-
-
-Querying Capabilities
-=====================
-
-The V4L ``VIDIOCGCAP`` ioctl is equivalent to V4L2's
-:ref:`VIDIOC_QUERYCAP`.
-
-The ``name`` field in struct :c:type:`struct video_capability` became
-``card`` in struct :ref:`v4l2_capability <v4l2-capability>`, ``type``
-was replaced by ``capabilities``. Note V4L2 does not distinguish between
-device types like this, better think of basic video input, video output
-and radio devices supporting a set of related functions like video
-capturing, video overlay and VBI capturing. See :ref:`open` for an
-introduction.
-
-
-
-.. flat-table::
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - struct :c:type:`struct video_capability` ``type``
-
- - struct :ref:`v4l2_capability <v4l2-capability>`
- ``capabilities`` flags
-
- - Purpose
-
- - .. row 2
-
- - ``VID_TYPE_CAPTURE``
-
- - ``V4L2_CAP_VIDEO_CAPTURE``
-
- - The :ref:`video capture <capture>` interface is supported.
-
- - .. row 3
-
- - ``VID_TYPE_TUNER``
-
- - ``V4L2_CAP_TUNER``
-
- - The device has a :ref:`tuner or modulator <tuner>`.
-
- - .. row 4
-
- - ``VID_TYPE_TELETEXT``
-
- - ``V4L2_CAP_VBI_CAPTURE``
-
- - The :ref:`raw VBI capture <raw-vbi>` interface is supported.
-
- - .. row 5
-
- - ``VID_TYPE_OVERLAY``
-
- - ``V4L2_CAP_VIDEO_OVERLAY``
-
- - The :ref:`video overlay <overlay>` interface is supported.
-
- - .. row 6
-
- - ``VID_TYPE_CHROMAKEY``
-
- - ``V4L2_FBUF_CAP_CHROMAKEY`` in field ``capability`` of struct
- :ref:`v4l2_framebuffer <v4l2-framebuffer>`
-
- - Whether chromakey overlay is supported. For more information on
- overlay see :ref:`overlay`.
-
- - .. row 7
-
- - ``VID_TYPE_CLIPPING``
-
- - ``V4L2_FBUF_CAP_LIST_CLIPPING`` and
- ``V4L2_FBUF_CAP_BITMAP_CLIPPING`` in field ``capability`` of
- struct :ref:`v4l2_framebuffer <v4l2-framebuffer>`
-
- - Whether clipping the overlaid image is supported, see
- :ref:`overlay`.
-
- - .. row 8
-
- - ``VID_TYPE_FRAMERAM``
-
- - ``V4L2_FBUF_CAP_EXTERNOVERLAY`` *not set* in field ``capability``
- of struct :ref:`v4l2_framebuffer <v4l2-framebuffer>`
-
- - Whether overlay overwrites frame buffer memory, see
- :ref:`overlay`.
-
- - .. row 9
-
- - ``VID_TYPE_SCALES``
-
- - ``-``
-
- - This flag indicates if the hardware can scale images. The V4L2 API
- implies the scale factor by setting the cropping dimensions and
- image size with the :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` and
- :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, respectively. The
- driver returns the closest sizes possible. For more information on
- cropping and scaling see :ref:`crop`.
-
- - .. row 10
-
- - ``VID_TYPE_MONOCHROME``
-
- - ``-``
-
- - Applications can enumerate the supported image formats with the
- :ref:`VIDIOC_ENUM_FMT` ioctl to determine if
- the device supports grey scale capturing only. For more
- information on image formats see :ref:`pixfmt`.
-
- - .. row 11
-
- - ``VID_TYPE_SUBCAPTURE``
-
- - ``-``
-
- - Applications can call the :ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>`
- ioctl to determine if the device supports capturing a subsection
- of the full picture ("cropping" in V4L2). If not, the ioctl
- returns the ``EINVAL`` error code. For more information on cropping
- and scaling see :ref:`crop`.
-
- - .. row 12
-
- - ``VID_TYPE_MPEG_DECODER``
-
- - ``-``
-
- - Applications can enumerate the supported image formats with the
- :ref:`VIDIOC_ENUM_FMT` ioctl to determine if
- the device supports MPEG streams.
-
- - .. row 13
-
- - ``VID_TYPE_MPEG_ENCODER``
-
- - ``-``
-
- - See above.
-
- - .. row 14
-
- - ``VID_TYPE_MJPEG_DECODER``
-
- - ``-``
-
- - See above.
-
- - .. row 15
-
- - ``VID_TYPE_MJPEG_ENCODER``
-
- - ``-``
-
- - See above.
-
-
-The ``audios`` field was replaced by ``capabilities`` flag
-``V4L2_CAP_AUDIO``, indicating *if* the device has any audio inputs or
-outputs. To determine their number applications can enumerate audio
-inputs with the :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` ioctl. The
-audio ioctls are described in :ref:`audio`.
-
-The ``maxwidth``, ``maxheight``, ``minwidth`` and ``minheight`` fields
-were removed. Calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` or
-:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl with the desired
-dimensions returns the closest size possible, taking into account the
-current video standard, cropping and scaling limitations.
-
-
-Video Sources
-=============
-
-V4L provides the ``VIDIOCGCHAN`` and ``VIDIOCSCHAN`` ioctl using struct
-:c:type:`struct video_channel` to enumerate the video inputs of a V4L
-device. The equivalent V4L2 ioctls are
-:ref:`VIDIOC_ENUMINPUT`,
-:ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` and
-:ref:`VIDIOC_S_INPUT <VIDIOC_G_INPUT>` using struct
-:ref:`v4l2_input <v4l2-input>` as discussed in :ref:`video`.
-
-The ``channel`` field counting inputs was renamed to ``index``, the
-video input types were renamed as follows:
-
-
-
-.. flat-table::
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - struct :c:type:`struct video_channel` ``type``
-
- - struct :ref:`v4l2_input <v4l2-input>` ``type``
-
- - .. row 2
-
- - ``VIDEO_TYPE_TV``
-
- - ``V4L2_INPUT_TYPE_TUNER``
-
- - .. row 3
-
- - ``VIDEO_TYPE_CAMERA``
-
- - ``V4L2_INPUT_TYPE_CAMERA``
-
-
-Unlike the ``tuners`` field expressing the number of tuners of this
-input, V4L2 assumes each video input is connected to at most one tuner.
-However a tuner can have more than one input, i. e. RF connectors, and a
-device can have multiple tuners. The index number of the tuner
-associated with the input, if any, is stored in field ``tuner`` of
-struct :ref:`v4l2_input <v4l2-input>`. Enumeration of tuners is
-discussed in :ref:`tuner`.
-
-The redundant ``VIDEO_VC_TUNER`` flag was dropped. Video inputs
-associated with a tuner are of type ``V4L2_INPUT_TYPE_TUNER``. The
-``VIDEO_VC_AUDIO`` flag was replaced by the ``audioset`` field. V4L2
-considers devices with up to 32 audio inputs. Each set bit in the
-``audioset`` field represents one audio input this video input combines
-with. For information about audio inputs and how to switch between them
-see :ref:`audio`.
-
-The ``norm`` field describing the supported video standards was replaced
-by ``std``. The V4L specification mentions a flag ``VIDEO_VC_NORM``
-indicating whether the standard can be changed. This flag was a later
-addition together with the ``norm`` field and has been removed in the
-meantime. V4L2 has a similar, albeit more comprehensive approach to
-video standards, see :ref:`standard` for more information.
-
-
-Tuning
-======
-
-The V4L ``VIDIOCGTUNER`` and ``VIDIOCSTUNER`` ioctl and struct
-:c:type:`struct video_tuner` can be used to enumerate the tuners of a
-V4L TV or radio device. The equivalent V4L2 ioctls are
-:ref:`VIDIOC_G_TUNER <VIDIOC_G_TUNER>` and
-:ref:`VIDIOC_S_TUNER <VIDIOC_G_TUNER>` using struct
-:ref:`v4l2_tuner <v4l2-tuner>`. Tuners are covered in :ref:`tuner`.
-
-The ``tuner`` field counting tuners was renamed to ``index``. The fields
-``name``, ``rangelow`` and ``rangehigh`` remained unchanged.
-
-The ``VIDEO_TUNER_PAL``, ``VIDEO_TUNER_NTSC`` and ``VIDEO_TUNER_SECAM``
-flags indicating the supported video standards were dropped. This
-information is now contained in the associated struct
-:ref:`v4l2_input <v4l2-input>`. No replacement exists for the
-``VIDEO_TUNER_NORM`` flag indicating whether the video standard can be
-switched. The ``mode`` field to select a different video standard was
-replaced by a whole new set of ioctls and structures described in
-:ref:`standard`. Due to its ubiquity it should be mentioned the BTTV
-driver supports several standards in addition to the regular
-``VIDEO_MODE_PAL`` (0), ``VIDEO_MODE_NTSC``, ``VIDEO_MODE_SECAM`` and
-``VIDEO_MODE_AUTO`` (3). Namely N/PAL Argentina, M/PAL, N/PAL, and NTSC
-Japan with numbers 3-6 (sic).
-
-The ``VIDEO_TUNER_STEREO_ON`` flag indicating stereo reception became
-``V4L2_TUNER_SUB_STEREO`` in field ``rxsubchans``. This field also
-permits the detection of monaural and bilingual audio, see the
-definition of struct :ref:`v4l2_tuner <v4l2-tuner>` for details.
-Presently no replacement exists for the ``VIDEO_TUNER_RDS_ON`` and
-``VIDEO_TUNER_MBS_ON`` flags.
-
-The ``VIDEO_TUNER_LOW`` flag was renamed to ``V4L2_TUNER_CAP_LOW`` in
-the struct :ref:`v4l2_tuner <v4l2-tuner>` ``capability`` field.
-
-The ``VIDIOCGFREQ`` and ``VIDIOCSFREQ`` ioctl to change the tuner
-frequency where renamed to
-:ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` and
-:ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>`. They take a pointer
-to a struct :ref:`v4l2_frequency <v4l2-frequency>` instead of an
-unsigned long integer.
-
-
-.. _v4l-image-properties:
-
-Image Properties
-================
-
-V4L2 has no equivalent of the ``VIDIOCGPICT`` and ``VIDIOCSPICT`` ioctl
-and struct :c:type:`struct video_picture`. The following fields where
-replaced by V4L2 controls accessible with the
-:ref:`VIDIOC_QUERYCTRL`,
-:ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and
-:ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls:
-
-
-
-.. flat-table::
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - struct :c:type:`struct video_picture`
-
- - V4L2 Control ID
-
- - .. row 2
-
- - ``brightness``
-
- - ``V4L2_CID_BRIGHTNESS``
-
- - .. row 3
-
- - ``hue``
-
- - ``V4L2_CID_HUE``
-
- - .. row 4
-
- - ``colour``
-
- - ``V4L2_CID_SATURATION``
-
- - .. row 5
-
- - ``contrast``
-
- - ``V4L2_CID_CONTRAST``
-
- - .. row 6
-
- - ``whiteness``
-
- - ``V4L2_CID_WHITENESS``
-
-
-The V4L picture controls are assumed to range from 0 to 65535 with no
-particular reset value. The V4L2 API permits arbitrary limits and
-defaults which can be queried with the
-:ref:`VIDIOC_QUERYCTRL` ioctl. For general
-information about controls see :ref:`control`.
-
-The ``depth`` (average number of bits per pixel) of a video image is
-implied by the selected image format. V4L2 does not explicitly provide
-such information assuming applications recognizing the format are aware
-of the image depth and others need not know. The ``palette`` field moved
-into the struct :ref:`v4l2_pix_format <v4l2-pix-format>`:
-
-
-
-.. flat-table::
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - struct :c:type:`struct video_picture` ``palette``
-
- - struct :ref:`v4l2_pix_format <v4l2-pix-format>` ``pixfmt``
-
- - .. row 2
-
- - ``VIDEO_PALETTE_GREY``
-
- - :ref:`V4L2_PIX_FMT_GREY <V4L2-PIX-FMT-GREY>`
-
- - .. row 3
-
- - ``VIDEO_PALETTE_HI240``
-
- - :ref:`V4L2_PIX_FMT_HI240 <pixfmt-reserved>` [3]_
-
- - .. row 4
-
- - ``VIDEO_PALETTE_RGB565``
-
- - :ref:`V4L2_PIX_FMT_RGB565 <pixfmt-rgb>`
-
- - .. row 5
-
- - ``VIDEO_PALETTE_RGB555``
-
- - :ref:`V4L2_PIX_FMT_RGB555 <pixfmt-rgb>`
-
- - .. row 6
-
- - ``VIDEO_PALETTE_RGB24``
-
- - :ref:`V4L2_PIX_FMT_BGR24 <pixfmt-rgb>`
-
- - .. row 7
-
- - ``VIDEO_PALETTE_RGB32``
-
- - :ref:`V4L2_PIX_FMT_BGR32 <pixfmt-rgb>` [4]_
-
- - .. row 8
-
- - ``VIDEO_PALETTE_YUV422``
-
- - :ref:`V4L2_PIX_FMT_YUYV <V4L2-PIX-FMT-YUYV>`
-
- - .. row 9
-
- - ``VIDEO_PALETTE_YUYV``\ [5]_
-
- - :ref:`V4L2_PIX_FMT_YUYV <V4L2-PIX-FMT-YUYV>`
-
- - .. row 10
-
- - ``VIDEO_PALETTE_UYVY``
-
- - :ref:`V4L2_PIX_FMT_UYVY <V4L2-PIX-FMT-UYVY>`
-
- - .. row 11
-
- - ``VIDEO_PALETTE_YUV420``
-
- - None
-
- - .. row 12
-
- - ``VIDEO_PALETTE_YUV411``
-
- - :ref:`V4L2_PIX_FMT_Y41P <V4L2-PIX-FMT-Y41P>` [6]_
-
- - .. row 13
-
- - ``VIDEO_PALETTE_RAW``
-
- - None [7]_
-
- - .. row 14
-
- - ``VIDEO_PALETTE_YUV422P``
-
- - :ref:`V4L2_PIX_FMT_YUV422P <V4L2-PIX-FMT-YUV422P>`
-
- - .. row 15
-
- - ``VIDEO_PALETTE_YUV411P``
-
- - :ref:`V4L2_PIX_FMT_YUV411P <V4L2-PIX-FMT-YUV411P>` [8]_
-
- - .. row 16
-
- - ``VIDEO_PALETTE_YUV420P``
-
- - :ref:`V4L2_PIX_FMT_YVU420 <V4L2-PIX-FMT-YVU420>`
-
- - .. row 17
-
- - ``VIDEO_PALETTE_YUV410P``
-
- - :ref:`V4L2_PIX_FMT_YVU410 <V4L2-PIX-FMT-YVU410>`
-
-
-V4L2 image formats are defined in :ref:`pixfmt`. The image format can
-be selected with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
-
-
-Audio
-=====
-
-The ``VIDIOCGAUDIO`` and ``VIDIOCSAUDIO`` ioctl and struct
-:c:type:`struct video_audio` are used to enumerate the audio inputs
-of a V4L device. The equivalent V4L2 ioctls are
-:ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` and
-:ref:`VIDIOC_S_AUDIO <VIDIOC_G_AUDIO>` using struct
-:ref:`v4l2_audio <v4l2-audio>` as discussed in :ref:`audio`.
-
-The ``audio`` "channel number" field counting audio inputs was renamed
-to ``index``.
-
-On ``VIDIOCSAUDIO`` the ``mode`` field selects *one* of the
-``VIDEO_SOUND_MONO``, ``VIDEO_SOUND_STEREO``, ``VIDEO_SOUND_LANG1`` or
-``VIDEO_SOUND_LANG2`` audio demodulation modes. When the current audio
-standard is BTSC ``VIDEO_SOUND_LANG2`` refers to SAP and
-``VIDEO_SOUND_LANG1`` is meaningless. Also undocumented in the V4L
-specification, there is no way to query the selected mode. On
-``VIDIOCGAUDIO`` the driver returns the *actually received* audio
-programmes in this field. In the V4L2 API this information is stored in
-the struct :ref:`v4l2_tuner <v4l2-tuner>` ``rxsubchans`` and
-``audmode`` fields, respectively. See :ref:`tuner` for more
-information on tuners. Related to audio modes struct
-:ref:`v4l2_audio <v4l2-audio>` also reports if this is a mono or
-stereo input, regardless if the source is a tuner.
-
-The following fields where replaced by V4L2 controls accessible with the
-:ref:`VIDIOC_QUERYCTRL`,
-:ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and
-:ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls:
-
-
-
-.. flat-table::
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - struct :c:type:`struct video_audio`
-
- - V4L2 Control ID
-
- - .. row 2
-
- - ``volume``
-
- - ``V4L2_CID_AUDIO_VOLUME``
-
- - .. row 3
-
- - ``bass``
-
- - ``V4L2_CID_AUDIO_BASS``
-
- - .. row 4
-
- - ``treble``
-
- - ``V4L2_CID_AUDIO_TREBLE``
-
- - .. row 5
-
- - ``balance``
-
- - ``V4L2_CID_AUDIO_BALANCE``
-
-
-To determine which of these controls are supported by a driver V4L
-provides the ``flags`` ``VIDEO_AUDIO_VOLUME``, ``VIDEO_AUDIO_BASS``,
-``VIDEO_AUDIO_TREBLE`` and ``VIDEO_AUDIO_BALANCE``. In the V4L2 API the
-:ref:`VIDIOC_QUERYCTRL` ioctl reports if the
-respective control is supported. Accordingly the ``VIDEO_AUDIO_MUTABLE``
-and ``VIDEO_AUDIO_MUTE`` flags where replaced by the boolean
-``V4L2_CID_AUDIO_MUTE`` control.
-
-All V4L2 controls have a ``step`` attribute replacing the struct
-:c:type:`struct video_audio` ``step`` field. The V4L audio controls
-are assumed to range from 0 to 65535 with no particular reset value. The
-V4L2 API permits arbitrary limits and defaults which can be queried with
-the :ref:`VIDIOC_QUERYCTRL` ioctl. For general
-information about controls see :ref:`control`.
-
-
-Frame Buffer Overlay
-====================
-
-The V4L2 ioctls equivalent to ``VIDIOCGFBUF`` and ``VIDIOCSFBUF`` are
-:ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` and
-:ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`. The ``base`` field of struct
-:c:type:`struct video_buffer` remained unchanged, except V4L2 defines
-a flag to indicate non-destructive overlays instead of a ``NULL``
-pointer. All other fields moved into the struct
-:ref:`v4l2_pix_format <v4l2-pix-format>` ``fmt`` substructure of
-struct :ref:`v4l2_framebuffer <v4l2-framebuffer>`. The ``depth``
-field was replaced by ``pixelformat``. See :ref:`pixfmt-rgb` for a
-list of RGB formats and their respective color depths.
-
-Instead of the special ioctls ``VIDIOCGWIN`` and ``VIDIOCSWIN`` V4L2
-uses the general-purpose data format negotiation ioctls
-:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
-:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. They take a pointer to a struct
-:ref:`v4l2_format <v4l2-format>` as argument. Here the ``win`` member
-of the ``fmt`` union is used, a struct
-:ref:`v4l2_window <v4l2-window>`.
-
-The ``x``, ``y``, ``width`` and ``height`` fields of struct
-:c:type:`struct video_window` moved into struct
-:ref:`v4l2_rect <v4l2-rect>` substructure ``w`` of struct
-:c:type:`struct v4l2_window`. The ``chromakey``, ``clips``, and
-``clipcount`` fields remained unchanged. Struct
-:c:type:`struct video_clip` was renamed to struct
-:ref:`v4l2_clip <v4l2-clip>`, also containing a struct
-:c:type:`struct v4l2_rect`, but the semantics are still the same.
-
-The ``VIDEO_WINDOW_INTERLACE`` flag was dropped. Instead applications
-must set the ``field`` field to ``V4L2_FIELD_ANY`` or
-``V4L2_FIELD_INTERLACED``. The ``VIDEO_WINDOW_CHROMAKEY`` flag moved
-into struct :ref:`v4l2_framebuffer <v4l2-framebuffer>`, under the new
-name ``V4L2_FBUF_FLAG_CHROMAKEY``.
-
-In V4L, storing a bitmap pointer in ``clips`` and setting ``clipcount``
-to ``VIDEO_CLIP_BITMAP`` (-1) requests bitmap clipping, using a fixed
-size bitmap of 1024 × 625 bits. Struct :c:type:`struct v4l2_window`
-has a separate ``bitmap`` pointer field for this purpose and the bitmap
-size is determined by ``w.width`` and ``w.height``.
-
-The ``VIDIOCCAPTURE`` ioctl to enable or disable overlay was renamed to
-:ref:`VIDIOC_OVERLAY`.
-
-
-Cropping
-========
-
-To capture only a subsection of the full picture V4L defines the
-``VIDIOCGCAPTURE`` and ``VIDIOCSCAPTURE`` ioctls using struct
-:c:type:`struct video_capture`. The equivalent V4L2 ioctls are
-:ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and
-:ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` using struct
-:ref:`v4l2_crop <v4l2-crop>`, and the related
-:ref:`VIDIOC_CROPCAP` ioctl. This is a rather
-complex matter, see :ref:`crop` for details.
-
-The ``x``, ``y``, ``width`` and ``height`` fields moved into struct
-:ref:`v4l2_rect <v4l2-rect>` substructure ``c`` of struct
-:c:type:`struct v4l2_crop`. The ``decimation`` field was dropped. In
-the V4L2 API the scaling factor is implied by the size of the cropping
-rectangle and the size of the captured or overlaid image.
-
-The ``VIDEO_CAPTURE_ODD`` and ``VIDEO_CAPTURE_EVEN`` flags to capture
-only the odd or even field, respectively, were replaced by
-``V4L2_FIELD_TOP`` and ``V4L2_FIELD_BOTTOM`` in the field named
-``field`` of struct :ref:`v4l2_pix_format <v4l2-pix-format>` and
-struct :ref:`v4l2_window <v4l2-window>`. These structures are used to
-select a capture or overlay format with the
-:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
-
-
-Reading Images, Memory Mapping
-==============================
-
-
-Capturing using the read method
--------------------------------
-
-There is no essential difference between reading images from a V4L or
-V4L2 device using the :ref:`read() <func-read>` function, however V4L2
-drivers are not required to support this I/O method. Applications can
-determine if the function is available with the
-:ref:`VIDIOC_QUERYCAP` ioctl. All V4L2 devices
-exchanging data with applications must support the
-:ref:`select() <func-select>` and :ref:`poll() <func-poll>`
-functions.
-
-To select an image format and size, V4L provides the ``VIDIOCSPICT`` and
-``VIDIOCSWIN`` ioctls. V4L2 uses the general-purpose data format
-negotiation ioctls :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
-:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. They take a pointer to a struct
-:ref:`v4l2_format <v4l2-format>` as argument, here the struct
-:ref:`v4l2_pix_format <v4l2-pix-format>` named ``pix`` of its
-``fmt`` union is used.
-
-For more information about the V4L2 read interface see :ref:`rw`.
-
-
-Capturing using memory mapping
-------------------------------
-
-Applications can read from V4L devices by mapping buffers in device
-memory, or more often just buffers allocated in DMA-able system memory,
-into their address space. This avoids the data copying overhead of the
-read method. V4L2 supports memory mapping as well, with a few
-differences.
-
-
-
-.. flat-table::
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - V4L
-
- - V4L2
-
- - .. row 2
-
- -
- - The image format must be selected before buffers are allocated,
- with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. When no
- format is selected the driver may use the last, possibly by
- another application requested format.
-
- - .. row 3
-
- - Applications cannot change the number of buffers. The it is built
- into the driver, unless it has a module option to change the
- number when the driver module is loaded.
-
- - The :ref:`VIDIOC_REQBUFS` ioctl allocates the
- desired number of buffers, this is a required step in the
- initialization sequence.
-
- - .. row 4
-
- - Drivers map all buffers as one contiguous range of memory. The
- ``VIDIOCGMBUF`` ioctl is available to query the number of buffers,
- the offset of each buffer from the start of the virtual file, and
- the overall amount of memory used, which can be used as arguments
- for the :ref:`mmap() <func-mmap>` function.
-
- - Buffers are individually mapped. The offset and size of each
- buffer can be determined with the
- :ref:`VIDIOC_QUERYBUF` ioctl.
-
- - .. row 5
-
- - The ``VIDIOCMCAPTURE`` ioctl prepares a buffer for capturing. It
- also determines the image format for this buffer. The ioctl
- returns immediately, eventually with an ``EAGAIN`` error code if no
- video signal had been detected. When the driver supports more than
- one buffer applications can call the ioctl multiple times and thus
- have multiple outstanding capture requests.
-
- The ``VIDIOCSYNC`` ioctl suspends execution until a particular
- buffer has been filled.
-
- - Drivers maintain an incoming and outgoing queue.
- :ref:`VIDIOC_QBUF` enqueues any empty buffer into
- the incoming queue. Filled buffers are dequeued from the outgoing
- queue with the :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. To wait
- until filled buffers become available this function,
- :ref:`select() <func-select>` or :ref:`poll() <func-poll>` can
- be used. The :ref:`VIDIOC_STREAMON` ioctl
- must be called once after enqueuing one or more buffers to start
- capturing. Its counterpart
- :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` stops capturing and
- dequeues all buffers from both queues. Applications can query the
- signal status, if known, with the
- :ref:`VIDIOC_ENUMINPUT` ioctl.
-
-
-For a more in-depth discussion of memory mapping and examples, see
-:ref:`mmap`.
-
-
-Reading Raw VBI Data
-====================
-
-Originally the V4L API did not specify a raw VBI capture interface, only
-the device file ``/dev/vbi`` was reserved for this purpose. The only
-driver supporting this interface was the BTTV driver, de-facto defining
-the V4L VBI interface. Reading from the device yields a raw VBI image
-with the following parameters:
-
-
-
-.. flat-table::
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - struct :ref:`v4l2_vbi_format <v4l2-vbi-format>`
-
- - V4L, BTTV driver
-
- - .. row 2
-
- - sampling_rate
-
- - 28636363 Hz NTSC (or any other 525-line standard); 35468950 Hz PAL
- and SECAM (625-line standards)
-
- - .. row 3
-
- - offset
-
- - ?
-
- - .. row 4
-
- - samples_per_line
-
- - 2048
-
- - .. row 5
-
- - sample_format
-
- - V4L2_PIX_FMT_GREY. The last four bytes (a machine endianness
- integer) contain a frame counter.
-
- - .. row 6
-
- - start[]
-
- - 10, 273 NTSC; 22, 335 PAL and SECAM
-
- - .. row 7
-
- - count[]
-
- - 16, 16 [9]_
-
- - .. row 8
-
- - flags
-
- - 0
-
-
-Undocumented in the V4L specification, in Linux 2.3 the
-``VIDIOCGVBIFMT`` and ``VIDIOCSVBIFMT`` ioctls using struct
-:c:type:`struct vbi_format` were added to determine the VBI image
-parameters. These ioctls are only partially compatible with the V4L2 VBI
-interface specified in :ref:`raw-vbi`.
-
-An ``offset`` field does not exist, ``sample_format`` is supposed to be
-``VIDEO_PALETTE_RAW``, equivalent to ``V4L2_PIX_FMT_GREY``. The
-remaining fields are probably equivalent to struct
-:ref:`v4l2_vbi_format <v4l2-vbi-format>`.
-
-Apparently only the Zoran (ZR 36120) driver implements these ioctls. The
-semantics differ from those specified for V4L2 in two ways. The
-parameters are reset on :ref:`open() <func-open>` and
-``VIDIOCSVBIFMT`` always returns an ``EINVAL`` error code if the parameters
-are invalid.
-
-
-Miscellaneous
-=============
-
-V4L2 has no equivalent of the ``VIDIOCGUNIT`` ioctl. Applications can
-find the VBI device associated with a video capture device (or vice
-versa) by reopening the device and requesting VBI data. For details see
-:ref:`open`.
-
-No replacement exists for ``VIDIOCKEY``, and the V4L functions for
-microcode programming. A new interface for MPEG compression and playback
-devices is documented in :ref:`extended-controls`.
-
-.. [1]
- According to Documentation/devices.txt these should be symbolic links
- to ``/dev/video0``. Note the original bttv interface is not
- compatible with V4L or V4L2.
-
-.. [2]
- According to ``Documentation/devices.txt`` a symbolic link to
- ``/dev/radio0``.
-
-.. [3]
- This is a custom format used by the BTTV driver, not one of the V4L2
- standard formats.
-
-.. [4]
- Presumably all V4L RGB formats are little-endian, although some
- drivers might interpret them according to machine endianness. V4L2
- defines little-endian, big-endian and red/blue swapped variants. For
- details see :ref:`pixfmt-rgb`.
-
-.. [5]
- ``VIDEO_PALETTE_YUV422`` and ``VIDEO_PALETTE_YUYV`` are the same
- formats. Some V4L drivers respond to one, some to the other.
-
-.. [6]
- Not to be confused with ``V4L2_PIX_FMT_YUV411P``, which is a planar
- format.
-
-.. [7]
- V4L explains this as: "RAW capture (BT848)"
-
-.. [8]
- Not to be confused with ``V4L2_PIX_FMT_Y41P``, which is a packed
- format.
-
-.. [9]
- Old driver versions used different values, eventually the custom
- ``BTTV_VBISIZE`` ioctl was added to query the correct values.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _dmabuf:
-
-************************************
-Streaming I/O (DMA buffer importing)
-************************************
-
-The DMABUF framework provides a generic method for sharing buffers
-between multiple devices. Device drivers that support DMABUF can export
-a DMA buffer to userspace as a file descriptor (known as the exporter
-role), import a DMA buffer from userspace using a file descriptor
-previously exported for a different or the same device (known as the
-importer role), or both. This section describes the DMABUF importer role
-API in V4L2.
-
-Refer to :ref:`DMABUF exporting <VIDIOC_EXPBUF>` for details about
-exporting V4L2 buffers as DMABUF file descriptors.
-
-Input and output devices support the streaming I/O method when the
-``V4L2_CAP_STREAMING`` flag in the ``capabilities`` field of struct
-:ref:`v4l2_capability <v4l2-capability>` returned by the
-:ref:`VIDIOC_QUERYCAP <VIDIOC_QUERYCAP>` ioctl is set. Whether
-importing DMA buffers through DMABUF file descriptors is supported is
-determined by calling the :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`
-ioctl with the memory type set to ``V4L2_MEMORY_DMABUF``.
-
-This I/O method is dedicated to sharing DMA buffers between different
-devices, which may be V4L devices or other video-related devices (e.g.
-DRM). Buffers (planes) are allocated by a driver on behalf of an
-application. Next, these buffers are exported to the application as file
-descriptors using an API which is specific for an allocator driver. Only
-such file descriptor are exchanged. The descriptors and meta-information
-are passed in struct :ref:`v4l2_buffer <v4l2-buffer>` (or in struct
-:ref:`v4l2_plane <v4l2-plane>` in the multi-planar API case). The
-driver must be switched into DMABUF I/O mode by calling the
-:ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>` with the desired buffer type.
-
-
-.. code-block:: c
- :caption: Example 3.4. Initiating streaming I/O with DMABUF file descriptors
-
- struct v4l2_requestbuffers reqbuf;
-
- memset(&reqbuf, 0, sizeof (reqbuf));
- reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- reqbuf.memory = V4L2_MEMORY_DMABUF;
- reqbuf.count = 1;
-
- if (ioctl(fd, VIDIOC_REQBUFS, &reqbuf) == -1) {
- if (errno == EINVAL)
- printf("Video capturing or DMABUF streaming is not supported\\n");
- else
- perror("VIDIOC_REQBUFS");
-
- exit(EXIT_FAILURE);
- }
-
-The buffer (plane) file descriptor is passed on the fly with the
-:ref:`VIDIOC_QBUF <VIDIOC_QBUF>` ioctl. In case of multiplanar
-buffers, every plane can be associated with a different DMABUF
-descriptor. Although buffers are commonly cycled, applications can pass
-a different DMABUF descriptor at each :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` call.
-
-
-.. code-block:: c
- :caption: Example 3.5. Queueing DMABUF using single plane API
-
- int buffer_queue(int v4lfd, int index, int dmafd)
- {
- struct v4l2_buffer buf;
-
- memset(&buf, 0, sizeof buf);
- buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- buf.memory = V4L2_MEMORY_DMABUF;
- buf.index = index;
- buf.m.fd = dmafd;
-
- if (ioctl(v4lfd, VIDIOC_QBUF, &buf) == -1) {
- perror("VIDIOC_QBUF");
- return -1;
- }
-
- return 0;
- }
-
-
-.. code-block:: c
- :caption: Example 3.6. Queueing DMABUF using multi plane API
-
- int buffer_queue_mp(int v4lfd, int index, int dmafd[], int n_planes)
- {
- struct v4l2_buffer buf;
- struct v4l2_plane planes[VIDEO_MAX_PLANES];
- int i;
-
- memset(&buf, 0, sizeof buf);
- buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE;
- buf.memory = V4L2_MEMORY_DMABUF;
- buf.index = index;
- buf.m.planes = planes;
- buf.length = n_planes;
-
- memset(&planes, 0, sizeof planes);
-
- for (i = 0; i < n_planes; ++i)
- buf.m.planes[i].m.fd = dmafd[i];
-
- if (ioctl(v4lfd, VIDIOC_QBUF, &buf) == -1) {
- perror("VIDIOC_QBUF");
- return -1;
- }
-
- return 0;
- }
-
-Captured or displayed buffers are dequeued with the
-:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. The driver can unlock the
-buffer at any time between the completion of the DMA and this ioctl. The
-memory is also unlocked when
-:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` is called,
-:ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, or when the device is closed.
-
-For capturing applications it is customary to enqueue a number of empty
-buffers, to start capturing and enter the read loop. Here the
-application waits until a filled buffer can be dequeued, and re-enqueues
-the buffer when the data is no longer needed. Output applications fill
-and enqueue buffers, when enough buffers are stacked up output is
-started. In the write loop, when the application runs out of free
-buffers it must wait until an empty buffer can be dequeued and reused.
-Two methods exist to suspend execution of the application until one or
-more buffers can be dequeued. By default :ref:`VIDIOC_DQBUF
-<VIDIOC_QBUF>` blocks when no buffer is in the outgoing queue. When the
-``O_NONBLOCK`` flag was given to the :ref:`open() <func-open>` function,
-:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` returns immediately with an ``EAGAIN``
-error code when no buffer is available. The
-:ref:`select() <func-select>` and :ref:`poll() <func-poll>`
-functions are always available.
-
-To start and stop capturing or displaying applications call the
-:ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and
-:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls. Note that
-:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` removes all buffers from
-both queues and unlocks all buffers as a side effect. Since there is no
-notion of doing anything "now" on a multitasking system, if an
-application needs to synchronize with another event it should examine
-the struct :ref:`v4l2_buffer <v4l2-buffer>` ``timestamp`` of captured or
-outputted buffers.
-
-Drivers implementing DMABUF importing I/O must support the
-:ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`,
-:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_STREAMON
-<VIDIOC_STREAMON>` and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls,
-and the :ref:`select() <func-select>` and :ref:`poll() <func-poll>`
-functions.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _driver:
-
-***********************
-V4L2 Driver Programming
-***********************
-
-to do
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _dv-timings:
-
-**************************
-Digital Video (DV) Timings
-**************************
-
-The video standards discussed so far have been dealing with Analog TV
-and the corresponding video timings. Today there are many more different
-hardware interfaces such as High Definition TV interfaces (HDMI), VGA,
-DVI connectors etc., that carry video signals and there is a need to
-extend the API to select the video timings for these interfaces. Since
-it is not possible to extend the :ref:`v4l2_std_id <v4l2-std-id>`
-due to the limited bits available, a new set of ioctls was added to
-set/get video timings at the input and output.
-
-These ioctls deal with the detailed digital video timings that define
-each video format. This includes parameters such as the active video
-width and height, signal polarities, frontporches, backporches, sync
-widths etc. The ``linux/v4l2-dv-timings.h`` header can be used to get
-the timings of the formats in the :ref:`cea861` and :ref:`vesadmt`
-standards.
-
-To enumerate and query the attributes of the DV timings supported by a
-device applications use the
-:ref:`VIDIOC_ENUM_DV_TIMINGS` and
-:ref:`VIDIOC_DV_TIMINGS_CAP` ioctls. To set
-DV timings for the device applications use the
-:ref:`VIDIOC_S_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>` ioctl and to get
-current DV timings they use the
-:ref:`VIDIOC_G_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>` ioctl. To detect
-the DV timings as seen by the video receiver applications use the
-:ref:`VIDIOC_QUERY_DV_TIMINGS` ioctl.
-
-Applications can make use of the :ref:`input-capabilities` and
-:ref:`output-capabilities` flags to determine whether the digital
-video ioctls can be used with the given input or output.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _extended-controls:
-
-*****************
-Extended Controls
-*****************
-
-
-Introduction
-============
-
-The control mechanism as originally designed was meant to be used for
-user settings (brightness, saturation, etc). However, it turned out to
-be a very useful model for implementing more complicated driver APIs
-where each driver implements only a subset of a larger API.
-
-The MPEG encoding API was the driving force behind designing and
-implementing this extended control mechanism: the MPEG standard is quite
-large and the currently supported hardware MPEG encoders each only
-implement a subset of this standard. Further more, many parameters
-relating to how the video is encoded into an MPEG stream are specific to
-the MPEG encoding chip since the MPEG standard only defines the format
-of the resulting MPEG stream, not how the video is actually encoded into
-that format.
-
-Unfortunately, the original control API lacked some features needed for
-these new uses and so it was extended into the (not terribly originally
-named) extended control API.
-
-Even though the MPEG encoding API was the first effort to use the
-Extended Control API, nowadays there are also other classes of Extended
-Controls, such as Camera Controls and FM Transmitter Controls. The
-Extended Controls API as well as all Extended Controls classes are
-described in the following text.
-
-
-The Extended Control API
-========================
-
-Three new ioctls are available:
-:ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`,
-:ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` and
-:ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`. These ioctls act
-on arrays of controls (as opposed to the
-:ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and
-:ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls that act on a single
-control). This is needed since it is often required to atomically change
-several controls at once.
-
-Each of the new ioctls expects a pointer to a struct
-:ref:`v4l2_ext_controls <v4l2-ext-controls>`. This structure
-contains a pointer to the control array, a count of the number of
-controls in that array and a control class. Control classes are used to
-group similar controls into a single class. For example, control class
-``V4L2_CTRL_CLASS_USER`` contains all user controls (i. e. all controls
-that can also be set using the old :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>`
-ioctl). Control class ``V4L2_CTRL_CLASS_MPEG`` contains all controls
-relating to MPEG encoding, etc.
-
-All controls in the control array must belong to the specified control
-class. An error is returned if this is not the case.
-
-It is also possible to use an empty control array (``count`` == 0) to check
-whether the specified control class is supported.
-
-The control array is a struct
-:ref:`v4l2_ext_control <v4l2-ext-control>` array. The
-:ref:`struct v4l2_ext_control <v4l2-ext-control>` structure is very similar to
-struct :ref:`v4l2_control <v4l2-control>`, except for the fact that
-it also allows for 64-bit values and pointers to be passed.
-
-Since the struct :ref:`v4l2_ext_control <v4l2-ext-control>` supports
-pointers it is now also possible to have controls with compound types
-such as N-dimensional arrays and/or structures. You need to specify the
-``V4L2_CTRL_FLAG_NEXT_COMPOUND`` when enumerating controls to actually
-be able to see such compound controls. In other words, these controls
-with compound types should only be used programmatically.
-
-Since such compound controls need to expose more information about
-themselves than is possible with
-:ref:`VIDIOC_QUERYCTRL` the
-:ref:`VIDIOC_QUERY_EXT_CTRL <VIDIOC_QUERYCTRL>` ioctl was added. In
-particular, this ioctl gives the dimensions of the N-dimensional array
-if this control consists of more than one element.
-
-It is important to realize that due to the flexibility of controls it is
-necessary to check whether the control you want to set actually is
-supported in the driver and what the valid range of values is. So use
-the :ref:`VIDIOC_QUERYCTRL` (or
-:ref:`VIDIOC_QUERY_EXT_CTRL <VIDIOC_QUERYCTRL>`) and
-:ref:`VIDIOC_QUERYMENU <VIDIOC_QUERYCTRL>` ioctls to check this. Also
-note that it is possible that some of the menu indices in a control of
-type ``V4L2_CTRL_TYPE_MENU`` may not be supported (``VIDIOC_QUERYMENU``
-will return an error). A good example is the list of supported MPEG
-audio bitrates. Some drivers only support one or two bitrates, others
-support a wider range.
-
-All controls use machine endianness.
-
-
-Enumerating Extended Controls
-=============================
-
-The recommended way to enumerate over the extended controls is by using
-:ref:`VIDIOC_QUERYCTRL` in combination with the
-``V4L2_CTRL_FLAG_NEXT_CTRL`` flag:
-
-
-.. code-block:: c
-
- struct v4l2_queryctrl qctrl;
-
- qctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL;
- while (0 == ioctl (fd, VIDIOC_QUERYCTRL, &qctrl)) {
- /* ... */
- qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
- }
-
-The initial control ID is set to 0 ORed with the
-``V4L2_CTRL_FLAG_NEXT_CTRL`` flag. The ``VIDIOC_QUERYCTRL`` ioctl will
-return the first control with a higher ID than the specified one. When
-no such controls are found an error is returned.
-
-If you want to get all controls within a specific control class, then
-you can set the initial ``qctrl.id`` value to the control class and add
-an extra check to break out of the loop when a control of another
-control class is found:
-
-
-.. code-block:: c
-
- qctrl.id = V4L2_CTRL_CLASS_MPEG | V4L2_CTRL_FLAG_NEXT_CTRL;
- while (0 == ioctl(fd, VIDIOC_QUERYCTRL, &qctrl)) {
- if (V4L2_CTRL_ID2CLASS(qctrl.id) != V4L2_CTRL_CLASS_MPEG)
- break;
- /* ... */
- qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
- }
-
-The 32-bit ``qctrl.id`` value is subdivided into three bit ranges: the
-top 4 bits are reserved for flags (e. g. ``V4L2_CTRL_FLAG_NEXT_CTRL``)
-and are not actually part of the ID. The remaining 28 bits form the
-control ID, of which the most significant 12 bits define the control
-class and the least significant 16 bits identify the control within the
-control class. It is guaranteed that these last 16 bits are always
-non-zero for controls. The range of 0x1000 and up are reserved for
-driver-specific controls. The macro ``V4L2_CTRL_ID2CLASS(id)`` returns
-the control class ID based on a control ID.
-
-If the driver does not support extended controls, then
-``VIDIOC_QUERYCTRL`` will fail when used in combination with
-``V4L2_CTRL_FLAG_NEXT_CTRL``. In that case the old method of enumerating
-control should be used (see :ref:`enum_all_controls`). But if it is
-supported, then it is guaranteed to enumerate over all controls,
-including driver-private controls.
-
-
-Creating Control Panels
-=======================
-
-It is possible to create control panels for a graphical user interface
-where the user can select the various controls. Basically you will have
-to iterate over all controls using the method described above. Each
-control class starts with a control of type
-``V4L2_CTRL_TYPE_CTRL_CLASS``. ``VIDIOC_QUERYCTRL`` will return the name
-of this control class which can be used as the title of a tab page
-within a control panel.
-
-The flags field of struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` also
-contains hints on the behavior of the control. See the
-:ref:`VIDIOC_QUERYCTRL` documentation for more
-details.
-
-
-.. _mpeg-controls:
-
-Codec Control Reference
-=======================
-
-Below all controls within the Codec control class are described. First
-the generic controls, then controls specific for certain hardware.
-
-Note: These controls are applicable to all codecs and not just MPEG. The
-defines are prefixed with V4L2_CID_MPEG/V4L2_MPEG as the controls
-were originally made for MPEG codecs and later extended to cover all
-encoding formats.
-
-
-Generic Codec Controls
-----------------------
-
-
-.. _mpeg-control-id:
-
-Codec Control IDs
-^^^^^^^^^^^^^^^^^
-
-``V4L2_CID_MPEG_CLASS (class)``
- The Codec class descriptor. Calling
- :ref:`VIDIOC_QUERYCTRL` for this control will
- return a description of this control class. This description can be
- used as the caption of a Tab page in a GUI, for example.
-
-.. _v4l2-mpeg-stream-type:
-
-``V4L2_CID_MPEG_STREAM_TYPE (enum v4l2_mpeg_stream_type)``
- The MPEG-1, -2 or -4 output stream type. One cannot assume anything
- here. Each hardware MPEG encoder tends to support different subsets
- of the available MPEG stream types. This control is specific to
- multiplexed MPEG streams. The currently defined stream types are:
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_MPEG_STREAM_TYPE_MPEG2_PS``
-
- - MPEG-2 program stream
-
- - .. row 2
-
- - ``V4L2_MPEG_STREAM_TYPE_MPEG2_TS``
-
- - MPEG-2 transport stream
-
- - .. row 3
-
- - ``V4L2_MPEG_STREAM_TYPE_MPEG1_SS``
-
- - MPEG-1 system stream
-
- - .. row 4
-
- - ``V4L2_MPEG_STREAM_TYPE_MPEG2_DVD``
-
- - MPEG-2 DVD-compatible stream
-
- - .. row 5
-
- - ``V4L2_MPEG_STREAM_TYPE_MPEG1_VCD``
-
- - MPEG-1 VCD-compatible stream
-
- - .. row 6
-
- - ``V4L2_MPEG_STREAM_TYPE_MPEG2_SVCD``
-
- - MPEG-2 SVCD-compatible stream
-
-
-
-``V4L2_CID_MPEG_STREAM_PID_PMT (integer)``
- Program Map Table Packet ID for the MPEG transport stream (default
- 16)
-
-``V4L2_CID_MPEG_STREAM_PID_AUDIO (integer)``
- Audio Packet ID for the MPEG transport stream (default 256)
-
-``V4L2_CID_MPEG_STREAM_PID_VIDEO (integer)``
- Video Packet ID for the MPEG transport stream (default 260)
-
-``V4L2_CID_MPEG_STREAM_PID_PCR (integer)``
- Packet ID for the MPEG transport stream carrying PCR fields (default
- 259)
-
-``V4L2_CID_MPEG_STREAM_PES_ID_AUDIO (integer)``
- Audio ID for MPEG PES
-
-``V4L2_CID_MPEG_STREAM_PES_ID_VIDEO (integer)``
- Video ID for MPEG PES
-
-.. _v4l2-mpeg-stream-vbi-fmt:
-
-``V4L2_CID_MPEG_STREAM_VBI_FMT (enum v4l2_mpeg_stream_vbi_fmt)``
- Some cards can embed VBI data (e. g. Closed Caption, Teletext) into
- the MPEG stream. This control selects whether VBI data should be
- embedded, and if so, what embedding method should be used. The list
- of possible VBI formats depends on the driver. The currently defined
- VBI format types are:
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_MPEG_STREAM_VBI_FMT_NONE``
-
- - No VBI in the MPEG stream
-
- - .. row 2
-
- - ``V4L2_MPEG_STREAM_VBI_FMT_IVTV``
-
- - VBI in private packets, IVTV format (documented in the kernel
- sources in the file
- ``Documentation/video4linux/cx2341x/README.vbi``)
-
-
-
-.. _v4l2-mpeg-audio-sampling-freq:
-
-``V4L2_CID_MPEG_AUDIO_SAMPLING_FREQ (enum v4l2_mpeg_audio_sampling_freq)``
- MPEG Audio sampling frequency. Possible values are:
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_MPEG_AUDIO_SAMPLING_FREQ_44100``
-
- - 44.1 kHz
-
- - .. row 2
-
- - ``V4L2_MPEG_AUDIO_SAMPLING_FREQ_48000``
-
- - 48 kHz
-
- - .. row 3
-
- - ``V4L2_MPEG_AUDIO_SAMPLING_FREQ_32000``
-
- - 32 kHz
-
-
-
-.. _v4l2-mpeg-audio-encoding:
-
-``V4L2_CID_MPEG_AUDIO_ENCODING (enum v4l2_mpeg_audio_encoding)``
- MPEG Audio encoding. This control is specific to multiplexed MPEG
- streams. Possible values are:
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_MPEG_AUDIO_ENCODING_LAYER_1``
-
- - MPEG-1/2 Layer I encoding
-
- - .. row 2
-
- - ``V4L2_MPEG_AUDIO_ENCODING_LAYER_2``
-
- - MPEG-1/2 Layer II encoding
-
- - .. row 3
-
- - ``V4L2_MPEG_AUDIO_ENCODING_LAYER_3``
-
- - MPEG-1/2 Layer III encoding
-
- - .. row 4
-
- - ``V4L2_MPEG_AUDIO_ENCODING_AAC``
-
- - MPEG-2/4 AAC (Advanced Audio Coding)
-
- - .. row 5
-
- - ``V4L2_MPEG_AUDIO_ENCODING_AC3``
-
- - AC-3 aka ATSC A/52 encoding
-
-
-
-.. _v4l2-mpeg-audio-l1-bitrate:
-
-``V4L2_CID_MPEG_AUDIO_L1_BITRATE (enum v4l2_mpeg_audio_l1_bitrate)``
- MPEG-1/2 Layer I bitrate. Possible values are:
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_MPEG_AUDIO_L1_BITRATE_32K``
-
- - 32 kbit/s
-
- - .. row 2
-
- - ``V4L2_MPEG_AUDIO_L1_BITRATE_64K``
-
- - 64 kbit/s
-
- - .. row 3
-
- - ``V4L2_MPEG_AUDIO_L1_BITRATE_96K``
-
- - 96 kbit/s
-
- - .. row 4
-
- - ``V4L2_MPEG_AUDIO_L1_BITRATE_128K``
-
- - 128 kbit/s
-
- - .. row 5
-
- - ``V4L2_MPEG_AUDIO_L1_BITRATE_160K``
-
- - 160 kbit/s
-
- - .. row 6
-
- - ``V4L2_MPEG_AUDIO_L1_BITRATE_192K``
-
- - 192 kbit/s
-
- - .. row 7
-
- - ``V4L2_MPEG_AUDIO_L1_BITRATE_224K``
-
- - 224 kbit/s
-
- - .. row 8
-
- - ``V4L2_MPEG_AUDIO_L1_BITRATE_256K``
-
- - 256 kbit/s
-
- - .. row 9
-
- - ``V4L2_MPEG_AUDIO_L1_BITRATE_288K``
-
- - 288 kbit/s
-
- - .. row 10
-
- - ``V4L2_MPEG_AUDIO_L1_BITRATE_320K``
-
- - 320 kbit/s
-
- - .. row 11
-
- - ``V4L2_MPEG_AUDIO_L1_BITRATE_352K``
-
- - 352 kbit/s
-
- - .. row 12
-
- - ``V4L2_MPEG_AUDIO_L1_BITRATE_384K``
-
- - 384 kbit/s
-
- - .. row 13
-
- - ``V4L2_MPEG_AUDIO_L1_BITRATE_416K``
-
- - 416 kbit/s
-
- - .. row 14
-
- - ``V4L2_MPEG_AUDIO_L1_BITRATE_448K``
-
- - 448 kbit/s
-
-
-
-.. _v4l2-mpeg-audio-l2-bitrate:
-
-``V4L2_CID_MPEG_AUDIO_L2_BITRATE (enum v4l2_mpeg_audio_l2_bitrate)``
- MPEG-1/2 Layer II bitrate. Possible values are:
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_MPEG_AUDIO_L2_BITRATE_32K``
-
- - 32 kbit/s
-
- - .. row 2
-
- - ``V4L2_MPEG_AUDIO_L2_BITRATE_48K``
-
- - 48 kbit/s
-
- - .. row 3
-
- - ``V4L2_MPEG_AUDIO_L2_BITRATE_56K``
-
- - 56 kbit/s
-
- - .. row 4
-
- - ``V4L2_MPEG_AUDIO_L2_BITRATE_64K``
-
- - 64 kbit/s
-
- - .. row 5
-
- - ``V4L2_MPEG_AUDIO_L2_BITRATE_80K``
-
- - 80 kbit/s
-
- - .. row 6
-
- - ``V4L2_MPEG_AUDIO_L2_BITRATE_96K``
-
- - 96 kbit/s
-
- - .. row 7
-
- - ``V4L2_MPEG_AUDIO_L2_BITRATE_112K``
-
- - 112 kbit/s
-
- - .. row 8
-
- - ``V4L2_MPEG_AUDIO_L2_BITRATE_128K``
-
- - 128 kbit/s
-
- - .. row 9
-
- - ``V4L2_MPEG_AUDIO_L2_BITRATE_160K``
-
- - 160 kbit/s
-
- - .. row 10
-
- - ``V4L2_MPEG_AUDIO_L2_BITRATE_192K``
-
- - 192 kbit/s
-
- - .. row 11
-
- - ``V4L2_MPEG_AUDIO_L2_BITRATE_224K``
-
- - 224 kbit/s
-
- - .. row 12
-
- - ``V4L2_MPEG_AUDIO_L2_BITRATE_256K``
-
- - 256 kbit/s
-
- - .. row 13
-
- - ``V4L2_MPEG_AUDIO_L2_BITRATE_320K``
-
- - 320 kbit/s
-
- - .. row 14
-
- - ``V4L2_MPEG_AUDIO_L2_BITRATE_384K``
-
- - 384 kbit/s
-
-
-
-.. _v4l2-mpeg-audio-l3-bitrate:
-
-``V4L2_CID_MPEG_AUDIO_L3_BITRATE (enum v4l2_mpeg_audio_l3_bitrate)``
- MPEG-1/2 Layer III bitrate. Possible values are:
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_MPEG_AUDIO_L3_BITRATE_32K``
-
- - 32 kbit/s
-
- - .. row 2
-
- - ``V4L2_MPEG_AUDIO_L3_BITRATE_40K``
-
- - 40 kbit/s
-
- - .. row 3
-
- - ``V4L2_MPEG_AUDIO_L3_BITRATE_48K``
-
- - 48 kbit/s
-
- - .. row 4
-
- - ``V4L2_MPEG_AUDIO_L3_BITRATE_56K``
-
- - 56 kbit/s
-
- - .. row 5
-
- - ``V4L2_MPEG_AUDIO_L3_BITRATE_64K``
-
- - 64 kbit/s
-
- - .. row 6
-
- - ``V4L2_MPEG_AUDIO_L3_BITRATE_80K``
-
- - 80 kbit/s
-
- - .. row 7
-
- - ``V4L2_MPEG_AUDIO_L3_BITRATE_96K``
-
- - 96 kbit/s
-
- - .. row 8
-
- - ``V4L2_MPEG_AUDIO_L3_BITRATE_112K``
-
- - 112 kbit/s
-
- - .. row 9
-
- - ``V4L2_MPEG_AUDIO_L3_BITRATE_128K``
-
- - 128 kbit/s
-
- - .. row 10
-
- - ``V4L2_MPEG_AUDIO_L3_BITRATE_160K``
-
- - 160 kbit/s
-
- - .. row 11
-
- - ``V4L2_MPEG_AUDIO_L3_BITRATE_192K``
-
- - 192 kbit/s
-
- - .. row 12
-
- - ``V4L2_MPEG_AUDIO_L3_BITRATE_224K``
-
- - 224 kbit/s
-
- - .. row 13
-
- - ``V4L2_MPEG_AUDIO_L3_BITRATE_256K``
-
- - 256 kbit/s
-
- - .. row 14
-
- - ``V4L2_MPEG_AUDIO_L3_BITRATE_320K``
-
- - 320 kbit/s
-
-
-
-``V4L2_CID_MPEG_AUDIO_AAC_BITRATE (integer)``
- AAC bitrate in bits per second.
-
-.. _v4l2-mpeg-audio-ac3-bitrate:
-
-``V4L2_CID_MPEG_AUDIO_AC3_BITRATE (enum v4l2_mpeg_audio_ac3_bitrate)``
- AC-3 bitrate. Possible values are:
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_MPEG_AUDIO_AC3_BITRATE_32K``
-
- - 32 kbit/s
-
- - .. row 2
-
- - ``V4L2_MPEG_AUDIO_AC3_BITRATE_40K``
-
- - 40 kbit/s
-
- - .. row 3
-
- - ``V4L2_MPEG_AUDIO_AC3_BITRATE_48K``
-
- - 48 kbit/s
-
- - .. row 4
-
- - ``V4L2_MPEG_AUDIO_AC3_BITRATE_56K``
-
- - 56 kbit/s
-
- - .. row 5
-
- - ``V4L2_MPEG_AUDIO_AC3_BITRATE_64K``
-
- - 64 kbit/s
-
- - .. row 6
-
- - ``V4L2_MPEG_AUDIO_AC3_BITRATE_80K``
-
- - 80 kbit/s
-
- - .. row 7
-
- - ``V4L2_MPEG_AUDIO_AC3_BITRATE_96K``
-
- - 96 kbit/s
-
- - .. row 8
-
- - ``V4L2_MPEG_AUDIO_AC3_BITRATE_112K``
-
- - 112 kbit/s
-
- - .. row 9
-
- - ``V4L2_MPEG_AUDIO_AC3_BITRATE_128K``
-
- - 128 kbit/s
-
- - .. row 10
-
- - ``V4L2_MPEG_AUDIO_AC3_BITRATE_160K``
-
- - 160 kbit/s
-
- - .. row 11
-
- - ``V4L2_MPEG_AUDIO_AC3_BITRATE_192K``
-
- - 192 kbit/s
-
- - .. row 12
-
- - ``V4L2_MPEG_AUDIO_AC3_BITRATE_224K``
-
- - 224 kbit/s
-
- - .. row 13
-
- - ``V4L2_MPEG_AUDIO_AC3_BITRATE_256K``
-
- - 256 kbit/s
-
- - .. row 14
-
- - ``V4L2_MPEG_AUDIO_AC3_BITRATE_320K``
-
- - 320 kbit/s
-
- - .. row 15
-
- - ``V4L2_MPEG_AUDIO_AC3_BITRATE_384K``
-
- - 384 kbit/s
-
- - .. row 16
-
- - ``V4L2_MPEG_AUDIO_AC3_BITRATE_448K``
-
- - 448 kbit/s
-
- - .. row 17
-
- - ``V4L2_MPEG_AUDIO_AC3_BITRATE_512K``
-
- - 512 kbit/s
-
- - .. row 18
-
- - ``V4L2_MPEG_AUDIO_AC3_BITRATE_576K``
-
- - 576 kbit/s
-
- - .. row 19
-
- - ``V4L2_MPEG_AUDIO_AC3_BITRATE_640K``
-
- - 640 kbit/s
-
-
-
-.. _v4l2-mpeg-audio-mode:
-
-``V4L2_CID_MPEG_AUDIO_MODE (enum v4l2_mpeg_audio_mode)``
- MPEG Audio mode. Possible values are:
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_MPEG_AUDIO_MODE_STEREO``
-
- - Stereo
-
- - .. row 2
-
- - ``V4L2_MPEG_AUDIO_MODE_JOINT_STEREO``
-
- - Joint Stereo
-
- - .. row 3
-
- - ``V4L2_MPEG_AUDIO_MODE_DUAL``
-
- - Bilingual
-
- - .. row 4
-
- - ``V4L2_MPEG_AUDIO_MODE_MONO``
-
- - Mono
-
-
-
-.. _v4l2-mpeg-audio-mode-extension:
-
-``V4L2_CID_MPEG_AUDIO_MODE_EXTENSION (enum v4l2_mpeg_audio_mode_extension)``
- Joint Stereo audio mode extension. In Layer I and II they indicate
- which subbands are in intensity stereo. All other subbands are coded
- in stereo. Layer III is not (yet) supported. Possible values are:
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_4``
-
- - Subbands 4-31 in intensity stereo
-
- - .. row 2
-
- - ``V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_8``
-
- - Subbands 8-31 in intensity stereo
-
- - .. row 3
-
- - ``V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_12``
-
- - Subbands 12-31 in intensity stereo
-
- - .. row 4
-
- - ``V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_16``
-
- - Subbands 16-31 in intensity stereo
-
-
-
-.. _v4l2-mpeg-audio-emphasis:
-
-``V4L2_CID_MPEG_AUDIO_EMPHASIS (enum v4l2_mpeg_audio_emphasis)``
- Audio Emphasis. Possible values are:
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_MPEG_AUDIO_EMPHASIS_NONE``
-
- - None
-
- - .. row 2
-
- - ``V4L2_MPEG_AUDIO_EMPHASIS_50_DIV_15_uS``
-
- - 50/15 microsecond emphasis
-
- - .. row 3
-
- - ``V4L2_MPEG_AUDIO_EMPHASIS_CCITT_J17``
-
- - CCITT J.17
-
-
-
-.. _v4l2-mpeg-audio-crc:
-
-``V4L2_CID_MPEG_AUDIO_CRC (enum v4l2_mpeg_audio_crc)``
- CRC method. Possible values are:
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_MPEG_AUDIO_CRC_NONE``
-
- - None
-
- - .. row 2
-
- - ``V4L2_MPEG_AUDIO_CRC_CRC16``
-
- - 16 bit parity check
-
-
-
-``V4L2_CID_MPEG_AUDIO_MUTE (boolean)``
- Mutes the audio when capturing. This is not done by muting audio
- hardware, which can still produce a slight hiss, but in the encoder
- itself, guaranteeing a fixed and reproducible audio bitstream. 0 =
- unmuted, 1 = muted.
-
-.. _v4l2-mpeg-audio-dec-playback:
-
-``V4L2_CID_MPEG_AUDIO_DEC_PLAYBACK (enum v4l2_mpeg_audio_dec_playback)``
- Determines how monolingual audio should be played back. Possible
- values are:
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_AUTO``
-
- - Automatically determines the best playback mode.
-
- - .. row 2
-
- - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_STEREO``
-
- - Stereo playback.
-
- - .. row 3
-
- - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_LEFT``
-
- - Left channel playback.
-
- - .. row 4
-
- - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_RIGHT``
-
- - Right channel playback.
-
- - .. row 5
-
- - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_MONO``
-
- - Mono playback.
-
- - .. row 6
-
- - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_SWAPPED_STEREO``
-
- - Stereo playback with swapped left and right channels.
-
-
-
-.. _v4l2-mpeg-audio-dec-multilingual-playback:
-
-``V4L2_CID_MPEG_AUDIO_DEC_MULTILINGUAL_PLAYBACK (enum v4l2_mpeg_audio_dec_playback)``
- Determines how multilingual audio should be played back.
-
-.. _v4l2-mpeg-video-encoding:
-
-``V4L2_CID_MPEG_VIDEO_ENCODING (enum v4l2_mpeg_video_encoding)``
- MPEG Video encoding method. This control is specific to multiplexed
- MPEG streams. Possible values are:
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_MPEG_VIDEO_ENCODING_MPEG_1``
-
- - MPEG-1 Video encoding
-
- - .. row 2
-
- - ``V4L2_MPEG_VIDEO_ENCODING_MPEG_2``
-
- - MPEG-2 Video encoding
-
- - .. row 3
-
- - ``V4L2_MPEG_VIDEO_ENCODING_MPEG_4_AVC``
-
- - MPEG-4 AVC (H.264) Video encoding
-
-
-
-.. _v4l2-mpeg-video-aspect:
-
-``V4L2_CID_MPEG_VIDEO_ASPECT (enum v4l2_mpeg_video_aspect)``
- Video aspect. Possible values are:
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_MPEG_VIDEO_ASPECT_1x1``
-
- - .. row 2
-
- - ``V4L2_MPEG_VIDEO_ASPECT_4x3``
-
- - .. row 3
-
- - ``V4L2_MPEG_VIDEO_ASPECT_16x9``
-
- - .. row 4
-
- - ``V4L2_MPEG_VIDEO_ASPECT_221x100``
-
-
-
-``V4L2_CID_MPEG_VIDEO_B_FRAMES (integer)``
- Number of B-Frames (default 2)
-
-``V4L2_CID_MPEG_VIDEO_GOP_SIZE (integer)``
- GOP size (default 12)
-
-``V4L2_CID_MPEG_VIDEO_GOP_CLOSURE (boolean)``
- GOP closure (default 1)
-
-``V4L2_CID_MPEG_VIDEO_PULLDOWN (boolean)``
- Enable 3:2 pulldown (default 0)
-
-.. _v4l2-mpeg-video-bitrate-mode:
-
-``V4L2_CID_MPEG_VIDEO_BITRATE_MODE (enum v4l2_mpeg_video_bitrate_mode)``
- Video bitrate mode. Possible values are:
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_MPEG_VIDEO_BITRATE_MODE_VBR``
-
- - Variable bitrate
-
- - .. row 2
-
- - ``V4L2_MPEG_VIDEO_BITRATE_MODE_CBR``
-
- - Constant bitrate
-
-
-
-``V4L2_CID_MPEG_VIDEO_BITRATE (integer)``
- Video bitrate in bits per second.
-
-``V4L2_CID_MPEG_VIDEO_BITRATE_PEAK (integer)``
- Peak video bitrate in bits per second. Must be larger or equal to
- the average video bitrate. It is ignored if the video bitrate mode
- is set to constant bitrate.
-
-``V4L2_CID_MPEG_VIDEO_TEMPORAL_DECIMATION (integer)``
- For every captured frame, skip this many subsequent frames (default
- 0).
-
-``V4L2_CID_MPEG_VIDEO_MUTE (boolean)``
- "Mutes" the video to a fixed color when capturing. This is useful
- for testing, to produce a fixed video bitstream. 0 = unmuted, 1 =
- muted.
-
-``V4L2_CID_MPEG_VIDEO_MUTE_YUV (integer)``
- Sets the "mute" color of the video. The supplied 32-bit integer is
- interpreted as follows (bit 0 = least significant bit):
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - Bit 0:7
-
- - V chrominance information
-
- - .. row 2
-
- - Bit 8:15
-
- - U chrominance information
-
- - .. row 3
-
- - Bit 16:23
-
- - Y luminance information
-
- - .. row 4
-
- - Bit 24:31
-
- - Must be zero.
-
-
-
-.. _v4l2-mpeg-video-dec-pts:
-
-``V4L2_CID_MPEG_VIDEO_DEC_PTS (integer64)``
- This read-only control returns the 33-bit video Presentation Time
- Stamp as defined in ITU T-REC-H.222.0 and ISO/IEC 13818-1 of the
- currently displayed frame. This is the same PTS as is used in
- :ref:`VIDIOC_DECODER_CMD`.
-
-.. _v4l2-mpeg-video-dec-frame:
-
-``V4L2_CID_MPEG_VIDEO_DEC_FRAME (integer64)``
- This read-only control returns the frame counter of the frame that
- is currently displayed (decoded). This value is reset to 0 whenever
- the decoder is started.
-
-``V4L2_CID_MPEG_VIDEO_DECODER_SLICE_INTERFACE (boolean)``
- If enabled the decoder expects to receive a single slice per buffer,
- otherwise the decoder expects a single frame in per buffer.
- Applicable to the decoder, all codecs.
-
-``V4L2_CID_MPEG_VIDEO_H264_VUI_SAR_ENABLE (boolean)``
- Enable writing sample aspect ratio in the Video Usability
- Information. Applicable to the H264 encoder.
-
-.. _v4l2-mpeg-video-h264-vui-sar-idc:
-
-``V4L2_CID_MPEG_VIDEO_H264_VUI_SAR_IDC (enum v4l2_mpeg_video_h264_vui_sar_idc)``
- VUI sample aspect ratio indicator for H.264 encoding. The value is
- defined in the table E-1 in the standard. Applicable to the H264
- encoder.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_UNSPECIFIED``
-
- - Unspecified
-
- - .. row 2
-
- - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_1x1``
-
- - 1x1
-
- - .. row 3
-
- - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_12x11``
-
- - 12x11
-
- - .. row 4
-
- - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_10x11``
-
- - 10x11
-
- - .. row 5
-
- - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_16x11``
-
- - 16x11
-
- - .. row 6
-
- - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_40x33``
-
- - 40x33
-
- - .. row 7
-
- - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_24x11``
-
- - 24x11
-
- - .. row 8
-
- - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_20x11``
-
- - 20x11
-
- - .. row 9
-
- - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_32x11``
-
- - 32x11
-
- - .. row 10
-
- - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_80x33``
-
- - 80x33
-
- - .. row 11
-
- - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_18x11``
-
- - 18x11
-
- - .. row 12
-
- - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_15x11``
-
- - 15x11
-
- - .. row 13
-
- - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_64x33``
-
- - 64x33
-
- - .. row 14
-
- - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_160x99``
-
- - 160x99
-
- - .. row 15
-
- - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_4x3``
-
- - 4x3
-
- - .. row 16
-
- - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_3x2``
-
- - 3x2
-
- - .. row 17
-
- - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_2x1``
-
- - 2x1
-
- - .. row 18
-
- - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_EXTENDED``
-
- - Extended SAR
-
-
-
-``V4L2_CID_MPEG_VIDEO_H264_VUI_EXT_SAR_WIDTH (integer)``
- Extended sample aspect ratio width for H.264 VUI encoding.
- Applicable to the H264 encoder.
-
-``V4L2_CID_MPEG_VIDEO_H264_VUI_EXT_SAR_HEIGHT (integer)``
- Extended sample aspect ratio height for H.264 VUI encoding.
- Applicable to the H264 encoder.
-
-.. _v4l2-mpeg-video-h264-level:
-
-``V4L2_CID_MPEG_VIDEO_H264_LEVEL (enum v4l2_mpeg_video_h264_level)``
- The level information for the H264 video elementary stream.
- Applicable to the H264 encoder. Possible values are:
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_MPEG_VIDEO_H264_LEVEL_1_0``
-
- - Level 1.0
-
- - .. row 2
-
- - ``V4L2_MPEG_VIDEO_H264_LEVEL_1B``
-
- - Level 1B
-
- - .. row 3
-
- - ``V4L2_MPEG_VIDEO_H264_LEVEL_1_1``
-
- - Level 1.1
-
- - .. row 4
-
- - ``V4L2_MPEG_VIDEO_H264_LEVEL_1_2``
-
- - Level 1.2
-
- - .. row 5
-
- - ``V4L2_MPEG_VIDEO_H264_LEVEL_1_3``
-
- - Level 1.3
-
- - .. row 6
-
- - ``V4L2_MPEG_VIDEO_H264_LEVEL_2_0``
-
- - Level 2.0
-
- - .. row 7
-
- - ``V4L2_MPEG_VIDEO_H264_LEVEL_2_1``
-
- - Level 2.1
-
- - .. row 8
-
- - ``V4L2_MPEG_VIDEO_H264_LEVEL_2_2``
-
- - Level 2.2
-
- - .. row 9
-
- - ``V4L2_MPEG_VIDEO_H264_LEVEL_3_0``
-
- - Level 3.0
-
- - .. row 10
-
- - ``V4L2_MPEG_VIDEO_H264_LEVEL_3_1``
-
- - Level 3.1
-
- - .. row 11
-
- - ``V4L2_MPEG_VIDEO_H264_LEVEL_3_2``
-
- - Level 3.2
-
- - .. row 12
-
- - ``V4L2_MPEG_VIDEO_H264_LEVEL_4_0``
-
- - Level 4.0
-
- - .. row 13
-
- - ``V4L2_MPEG_VIDEO_H264_LEVEL_4_1``
-
- - Level 4.1
-
- - .. row 14
-
- - ``V4L2_MPEG_VIDEO_H264_LEVEL_4_2``
-
- - Level 4.2
-
- - .. row 15
-
- - ``V4L2_MPEG_VIDEO_H264_LEVEL_5_0``
-
- - Level 5.0
-
- - .. row 16
-
- - ``V4L2_MPEG_VIDEO_H264_LEVEL_5_1``
-
- - Level 5.1
-
-
-
-.. _v4l2-mpeg-video-mpeg4-level:
-
-``V4L2_CID_MPEG_VIDEO_MPEG4_LEVEL (enum v4l2_mpeg_video_mpeg4_level)``
- The level information for the MPEG4 elementary stream. Applicable to
- the MPEG4 encoder. Possible values are:
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_MPEG_VIDEO_LEVEL_0``
-
- - Level 0
-
- - .. row 2
-
- - ``V4L2_MPEG_VIDEO_LEVEL_0B``
-
- - Level 0b
-
- - .. row 3
-
- - ``V4L2_MPEG_VIDEO_LEVEL_1``
-
- - Level 1
-
- - .. row 4
-
- - ``V4L2_MPEG_VIDEO_LEVEL_2``
-
- - Level 2
-
- - .. row 5
-
- - ``V4L2_MPEG_VIDEO_LEVEL_3``
-
- - Level 3
-
- - .. row 6
-
- - ``V4L2_MPEG_VIDEO_LEVEL_3B``
-
- - Level 3b
-
- - .. row 7
-
- - ``V4L2_MPEG_VIDEO_LEVEL_4``
-
- - Level 4
-
- - .. row 8
-
- - ``V4L2_MPEG_VIDEO_LEVEL_5``
-
- - Level 5
-
-
-
-.. _v4l2-mpeg-video-h264-profile:
-
-``V4L2_CID_MPEG_VIDEO_H264_PROFILE (enum v4l2_mpeg_video_h264_profile)``
- The profile information for H264. Applicable to the H264 encoder.
- Possible values are:
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_MPEG_VIDEO_H264_PROFILE_BASELINE``
-
- - Baseline profile
-
- - .. row 2
-
- - ``V4L2_MPEG_VIDEO_H264_PROFILE_CONSTRAINED_BASELINE``
-
- - Constrained Baseline profile
-
- - .. row 3
-
- - ``V4L2_MPEG_VIDEO_H264_PROFILE_MAIN``
-
- - Main profile
-
- - .. row 4
-
- - ``V4L2_MPEG_VIDEO_H264_PROFILE_EXTENDED``
-
- - Extended profile
-
- - .. row 5
-
- - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH``
-
- - High profile
-
- - .. row 6
-
- - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_10``
-
- - High 10 profile
-
- - .. row 7
-
- - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_422``
-
- - High 422 profile
-
- - .. row 8
-
- - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_444_PREDICTIVE``
-
- - High 444 Predictive profile
-
- - .. row 9
-
- - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_10_INTRA``
-
- - High 10 Intra profile
-
- - .. row 10
-
- - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_422_INTRA``
-
- - High 422 Intra profile
-
- - .. row 11
-
- - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_444_INTRA``
-
- - High 444 Intra profile
-
- - .. row 12
-
- - ``V4L2_MPEG_VIDEO_H264_PROFILE_CAVLC_444_INTRA``
-
- - CAVLC 444 Intra profile
-
- - .. row 13
-
- - ``V4L2_MPEG_VIDEO_H264_PROFILE_SCALABLE_BASELINE``
-
- - Scalable Baseline profile
-
- - .. row 14
-
- - ``V4L2_MPEG_VIDEO_H264_PROFILE_SCALABLE_HIGH``
-
- - Scalable High profile
-
- - .. row 15
-
- - ``V4L2_MPEG_VIDEO_H264_PROFILE_SCALABLE_HIGH_INTRA``
-
- - Scalable High Intra profile
-
- - .. row 16
-
- - ``V4L2_MPEG_VIDEO_H264_PROFILE_STEREO_HIGH``
-
- - Stereo High profile
-
- - .. row 17
-
- - ``V4L2_MPEG_VIDEO_H264_PROFILE_MULTIVIEW_HIGH``
-
- - Multiview High profile
-
-
-
-.. _v4l2-mpeg-video-mpeg4-profile:
-
-``V4L2_CID_MPEG_VIDEO_MPEG4_PROFILE (enum v4l2_mpeg_video_mpeg4_profile)``
- The profile information for MPEG4. Applicable to the MPEG4 encoder.
- Possible values are:
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_MPEG_VIDEO_PROFILE_SIMPLE``
-
- - Simple profile
-
- - .. row 2
-
- - ``V4L2_MPEG_VIDEO_PROFILE_ADVANCED_SIMPLE``
-
- - Advanced Simple profile
-
- - .. row 3
-
- - ``V4L2_MPEG_VIDEO_PROFILE_CORE``
-
- - Core profile
-
- - .. row 4
-
- - ``V4L2_MPEG_VIDEO_PROFILE_SIMPLE_SCALABLE``
-
- - Simple Scalable profile
-
- - .. row 5
-
- - ``V4L2_MPEG_VIDEO_PROFILE_ADVANCED_CODING_EFFICIENCY``
-
- -
-
-
-
-``V4L2_CID_MPEG_VIDEO_MAX_REF_PIC (integer)``
- The maximum number of reference pictures used for encoding.
- Applicable to the encoder.
-
-.. _v4l2-mpeg-video-multi-slice-mode:
-
-``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE (enum v4l2_mpeg_video_multi_slice_mode)``
- Determines how the encoder should handle division of frame into
- slices. Applicable to the encoder. Possible values are:
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_SINGLE``
-
- - Single slice per frame.
-
- - .. row 2
-
- - ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_MB``
-
- - Multiple slices with set maximum number of macroblocks per slice.
-
- - .. row 3
-
- - ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_BYTES``
-
- - Multiple slice with set maximum size in bytes per slice.
-
-
-
-``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MAX_MB (integer)``
- The maximum number of macroblocks in a slice. Used when
- ``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE`` is set to
- ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_MB``. Applicable to the
- encoder.
-
-``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MAX_BYTES (integer)``
- The maximum size of a slice in bytes. Used when
- ``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE`` is set to
- ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_BYTES``. Applicable to the
- encoder.
-
-.. _v4l2-mpeg-video-h264-loop-filter-mode:
-
-``V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_MODE (enum v4l2_mpeg_video_h264_loop_filter_mode)``
- Loop filter mode for H264 encoder. Possible values are:
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_MPEG_VIDEO_H264_LOOP_FILTER_MODE_ENABLED``
-
- - Loop filter is enabled.
-
- - .. row 2
-
- - ``V4L2_MPEG_VIDEO_H264_LOOP_FILTER_MODE_DISABLED``
-
- - Loop filter is disabled.
-
- - .. row 3
-
- - ``V4L2_MPEG_VIDEO_H264_LOOP_FILTER_MODE_DISABLED_AT_SLICE_BOUNDARY``
-
- - Loop filter is disabled at the slice boundary.
-
-
-
-``V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_ALPHA (integer)``
- Loop filter alpha coefficient, defined in the H264 standard.
- Applicable to the H264 encoder.
-
-``V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_BETA (integer)``
- Loop filter beta coefficient, defined in the H264 standard.
- Applicable to the H264 encoder.
-
-.. _v4l2-mpeg-video-h264-entropy-mode:
-
-``V4L2_CID_MPEG_VIDEO_H264_ENTROPY_MODE (enum v4l2_mpeg_video_h264_entropy_mode)``
- Entropy coding mode for H264 - CABAC/CAVALC. Applicable to the H264
- encoder. Possible values are:
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_MPEG_VIDEO_H264_ENTROPY_MODE_CAVLC``
-
- - Use CAVLC entropy coding.
-
- - .. row 2
-
- - ``V4L2_MPEG_VIDEO_H264_ENTROPY_MODE_CABAC``
-
- - Use CABAC entropy coding.
-
-
-
-``V4L2_CID_MPEG_VIDEO_H264_8X8_TRANSFORM (boolean)``
- Enable 8X8 transform for H264. Applicable to the H264 encoder.
-
-``V4L2_CID_MPEG_VIDEO_CYCLIC_INTRA_REFRESH_MB (integer)``
- Cyclic intra macroblock refresh. This is the number of continuous
- macroblocks refreshed every frame. Each frame a successive set of
- macroblocks is refreshed until the cycle completes and starts from
- the top of the frame. Applicable to H264, H263 and MPEG4 encoder.
-
-``V4L2_CID_MPEG_VIDEO_FRAME_RC_ENABLE (boolean)``
- Frame level rate control enable. If this control is disabled then
- the quantization parameter for each frame type is constant and set
- with appropriate controls (e.g.
- ``V4L2_CID_MPEG_VIDEO_H263_I_FRAME_QP``). If frame rate control is
- enabled then quantization parameter is adjusted to meet the chosen
- bitrate. Minimum and maximum value for the quantization parameter
- can be set with appropriate controls (e.g.
- ``V4L2_CID_MPEG_VIDEO_H263_MIN_QP``). Applicable to encoders.
-
-``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE (boolean)``
- Macroblock level rate control enable. Applicable to the MPEG4 and
- H264 encoders.
-
-``V4L2_CID_MPEG_VIDEO_MPEG4_QPEL (boolean)``
- Quarter pixel motion estimation for MPEG4. Applicable to the MPEG4
- encoder.
-
-``V4L2_CID_MPEG_VIDEO_H263_I_FRAME_QP (integer)``
- Quantization parameter for an I frame for H263. Valid range: from 1
- to 31.
-
-``V4L2_CID_MPEG_VIDEO_H263_MIN_QP (integer)``
- Minimum quantization parameter for H263. Valid range: from 1 to 31.
-
-``V4L2_CID_MPEG_VIDEO_H263_MAX_QP (integer)``
- Maximum quantization parameter for H263. Valid range: from 1 to 31.
-
-``V4L2_CID_MPEG_VIDEO_H263_P_FRAME_QP (integer)``
- Quantization parameter for an P frame for H263. Valid range: from 1
- to 31.
-
-``V4L2_CID_MPEG_VIDEO_H263_B_FRAME_QP (integer)``
- Quantization parameter for an B frame for H263. Valid range: from 1
- to 31.
-
-``V4L2_CID_MPEG_VIDEO_H264_I_FRAME_QP (integer)``
- Quantization parameter for an I frame for H264. Valid range: from 0
- to 51.
-
-``V4L2_CID_MPEG_VIDEO_H264_MIN_QP (integer)``
- Minimum quantization parameter for H264. Valid range: from 0 to 51.
-
-``V4L2_CID_MPEG_VIDEO_H264_MAX_QP (integer)``
- Maximum quantization parameter for H264. Valid range: from 0 to 51.
-
-``V4L2_CID_MPEG_VIDEO_H264_P_FRAME_QP (integer)``
- Quantization parameter for an P frame for H264. Valid range: from 0
- to 51.
-
-``V4L2_CID_MPEG_VIDEO_H264_B_FRAME_QP (integer)``
- Quantization parameter for an B frame for H264. Valid range: from 0
- to 51.
-
-``V4L2_CID_MPEG_VIDEO_MPEG4_I_FRAME_QP (integer)``
- Quantization parameter for an I frame for MPEG4. Valid range: from 1
- to 31.
-
-``V4L2_CID_MPEG_VIDEO_MPEG4_MIN_QP (integer)``
- Minimum quantization parameter for MPEG4. Valid range: from 1 to 31.
-
-``V4L2_CID_MPEG_VIDEO_MPEG4_MAX_QP (integer)``
- Maximum quantization parameter for MPEG4. Valid range: from 1 to 31.
-
-``V4L2_CID_MPEG_VIDEO_MPEG4_P_FRAME_QP (integer)``
- Quantization parameter for an P frame for MPEG4. Valid range: from 1
- to 31.
-
-``V4L2_CID_MPEG_VIDEO_MPEG4_B_FRAME_QP (integer)``
- Quantization parameter for an B frame for MPEG4. Valid range: from 1
- to 31.
-
-``V4L2_CID_MPEG_VIDEO_VBV_SIZE (integer)``
- The Video Buffer Verifier size in kilobytes, it is used as a
- limitation of frame skip. The VBV is defined in the standard as a
- mean to verify that the produced stream will be successfully
- decoded. The standard describes it as "Part of a hypothetical
- decoder that is conceptually connected to the output of the encoder.
- Its purpose is to provide a constraint on the variability of the
- data rate that an encoder or editing process may produce.".
- Applicable to the MPEG1, MPEG2, MPEG4 encoders.
-
-.. _v4l2-mpeg-video-vbv-delay:
-
-``V4L2_CID_MPEG_VIDEO_VBV_DELAY (integer)``
- Sets the initial delay in milliseconds for VBV buffer control.
-
-.. _v4l2-mpeg-video-hor-search-range:
-
-``V4L2_CID_MPEG_VIDEO_MV_H_SEARCH_RANGE (integer)``
- Horizontal search range defines maximum horizontal search area in
- pixels to search and match for the present Macroblock (MB) in the
- reference picture. This V4L2 control macro is used to set horizontal
- search range for motion estimation module in video encoder.
-
-.. _v4l2-mpeg-video-vert-search-range:
-
-``V4L2_CID_MPEG_VIDEO_MV_V_SEARCH_RANGE (integer)``
- Vertical search range defines maximum vertical search area in pixels
- to search and match for the present Macroblock (MB) in the reference
- picture. This V4L2 control macro is used to set vertical search
- range for motion estimation module in video encoder.
-
-.. _v4l2-mpeg-video-force-key-frame:
-
-``V4L2_CID_MPEG_VIDEO_FORCE_KEY_FRAME (button)``
- Force a key frame for the next queued buffer. Applicable to
- encoders. This is a general, codec-agnostic keyframe control.
-
-``V4L2_CID_MPEG_VIDEO_H264_CPB_SIZE (integer)``
- The Coded Picture Buffer size in kilobytes, it is used as a
- limitation of frame skip. The CPB is defined in the H264 standard as
- a mean to verify that the produced stream will be successfully
- decoded. Applicable to the H264 encoder.
-
-``V4L2_CID_MPEG_VIDEO_H264_I_PERIOD (integer)``
- Period between I-frames in the open GOP for H264. In case of an open
- GOP this is the period between two I-frames. The period between IDR
- (Instantaneous Decoding Refresh) frames is taken from the GOP_SIZE
- control. An IDR frame, which stands for Instantaneous Decoding
- Refresh is an I-frame after which no prior frames are referenced.
- This means that a stream can be restarted from an IDR frame without
- the need to store or decode any previous frames. Applicable to the
- H264 encoder.
-
-.. _v4l2-mpeg-video-header-mode:
-
-``V4L2_CID_MPEG_VIDEO_HEADER_MODE (enum v4l2_mpeg_video_header_mode)``
- Determines whether the header is returned as the first buffer or is
- it returned together with the first frame. Applicable to encoders.
- Possible values are:
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_MPEG_VIDEO_HEADER_MODE_SEPARATE``
-
- - The stream header is returned separately in the first buffer.
-
- - .. row 2
-
- - ``V4L2_MPEG_VIDEO_HEADER_MODE_JOINED_WITH_1ST_FRAME``
-
- - The stream header is returned together with the first encoded
- frame.
-
-
-
-``V4L2_CID_MPEG_VIDEO_REPEAT_SEQ_HEADER (boolean)``
- Repeat the video sequence headers. Repeating these headers makes
- random access to the video stream easier. Applicable to the MPEG1, 2
- and 4 encoder.
-
-``V4L2_CID_MPEG_VIDEO_DECODER_MPEG4_DEBLOCK_FILTER (boolean)``
- Enabled the deblocking post processing filter for MPEG4 decoder.
- Applicable to the MPEG4 decoder.
-
-``V4L2_CID_MPEG_VIDEO_MPEG4_VOP_TIME_RES (integer)``
- vop_time_increment_resolution value for MPEG4. Applicable to the
- MPEG4 encoder.
-
-``V4L2_CID_MPEG_VIDEO_MPEG4_VOP_TIME_INC (integer)``
- vop_time_increment value for MPEG4. Applicable to the MPEG4
- encoder.
-
-``V4L2_CID_MPEG_VIDEO_H264_SEI_FRAME_PACKING (boolean)``
- Enable generation of frame packing supplemental enhancement
- information in the encoded bitstream. The frame packing SEI message
- contains the arrangement of L and R planes for 3D viewing.
- Applicable to the H264 encoder.
-
-``V4L2_CID_MPEG_VIDEO_H264_SEI_FP_CURRENT_FRAME_0 (boolean)``
- Sets current frame as frame0 in frame packing SEI. Applicable to the
- H264 encoder.
-
-.. _v4l2-mpeg-video-h264-sei-fp-arrangement-type:
-
-``V4L2_CID_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE (enum v4l2_mpeg_video_h264_sei_fp_arrangement_type)``
- Frame packing arrangement type for H264 SEI. Applicable to the H264
- encoder. Possible values are:
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_CHEKERBOARD``
-
- - Pixels are alternatively from L and R.
-
- - .. row 2
-
- - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_COLUMN``
-
- - L and R are interlaced by column.
-
- - .. row 3
-
- - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_ROW``
-
- - L and R are interlaced by row.
-
- - .. row 4
-
- - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_SIDE_BY_SIDE``
-
- - L is on the left, R on the right.
-
- - .. row 5
-
- - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_TOP_BOTTOM``
-
- - L is on top, R on bottom.
-
- - .. row 6
-
- - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_TEMPORAL``
-
- - One view per frame.
-
-
-
-``V4L2_CID_MPEG_VIDEO_H264_FMO (boolean)``
- Enables flexible macroblock ordering in the encoded bitstream. It is
- a technique used for restructuring the ordering of macroblocks in
- pictures. Applicable to the H264 encoder.
-
-.. _v4l2-mpeg-video-h264-fmo-map-type:
-
-``V4L2_CID_MPEG_VIDEO_H264_FMO_MAP_TYPE (enum v4l2_mpeg_video_h264_fmo_map_type)``
- When using FMO, the map type divides the image in different scan
- patterns of macroblocks. Applicable to the H264 encoder. Possible
- values are:
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_INTERLEAVED_SLICES``
-
- - Slices are interleaved one after other with macroblocks in run
- length order.
-
- - .. row 2
-
- - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_SCATTERED_SLICES``
-
- - Scatters the macroblocks based on a mathematical function known to
- both encoder and decoder.
-
- - .. row 3
-
- - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_FOREGROUND_WITH_LEFT_OVER``
-
- - Macroblocks arranged in rectangular areas or regions of interest.
-
- - .. row 4
-
- - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_BOX_OUT``
-
- - Slice groups grow in a cyclic way from centre to outwards.
-
- - .. row 5
-
- - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_RASTER_SCAN``
-
- - Slice groups grow in raster scan pattern from left to right.
-
- - .. row 6
-
- - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_WIPE_SCAN``
-
- - Slice groups grow in wipe scan pattern from top to bottom.
-
- - .. row 7
-
- - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_EXPLICIT``
-
- - User defined map type.
-
-
-
-``V4L2_CID_MPEG_VIDEO_H264_FMO_SLICE_GROUP (integer)``
- Number of slice groups in FMO. Applicable to the H264 encoder.
-
-.. _v4l2-mpeg-video-h264-fmo-change-direction:
-
-``V4L2_CID_MPEG_VIDEO_H264_FMO_CHANGE_DIRECTION (enum v4l2_mpeg_video_h264_fmo_change_dir)``
- Specifies a direction of the slice group change for raster and wipe
- maps. Applicable to the H264 encoder. Possible values are:
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_MPEG_VIDEO_H264_FMO_CHANGE_DIR_RIGHT``
-
- - Raster scan or wipe right.
-
- - .. row 2
-
- - ``V4L2_MPEG_VIDEO_H264_FMO_CHANGE_DIR_LEFT``
-
- - Reverse raster scan or wipe left.
-
-
-
-``V4L2_CID_MPEG_VIDEO_H264_FMO_CHANGE_RATE (integer)``
- Specifies the size of the first slice group for raster and wipe map.
- Applicable to the H264 encoder.
-
-``V4L2_CID_MPEG_VIDEO_H264_FMO_RUN_LENGTH (integer)``
- Specifies the number of consecutive macroblocks for the interleaved
- map. Applicable to the H264 encoder.
-
-``V4L2_CID_MPEG_VIDEO_H264_ASO (boolean)``
- Enables arbitrary slice ordering in encoded bitstream. Applicable to
- the H264 encoder.
-
-``V4L2_CID_MPEG_VIDEO_H264_ASO_SLICE_ORDER (integer)``
- Specifies the slice order in ASO. Applicable to the H264 encoder.
- The supplied 32-bit integer is interpreted as follows (bit 0 = least
- significant bit):
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - Bit 0:15
-
- - Slice ID
-
- - .. row 2
-
- - Bit 16:32
-
- - Slice position or order
-
-
-
-``V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING (boolean)``
- Enables H264 hierarchical coding. Applicable to the H264 encoder.
-
-.. _v4l2-mpeg-video-h264-hierarchical-coding-type:
-
-``V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING_TYPE (enum v4l2_mpeg_video_h264_hierarchical_coding_type)``
- Specifies the hierarchical coding type. Applicable to the H264
- encoder. Possible values are:
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_MPEG_VIDEO_H264_HIERARCHICAL_CODING_B``
-
- - Hierarchical B coding.
-
- - .. row 2
-
- - ``V4L2_MPEG_VIDEO_H264_HIERARCHICAL_CODING_P``
-
- - Hierarchical P coding.
-
-
-
-``V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING_LAYER (integer)``
- Specifies the number of hierarchical coding layers. Applicable to
- the H264 encoder.
-
-``V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING_LAYER_QP (integer)``
- Specifies a user defined QP for each layer. Applicable to the H264
- encoder. The supplied 32-bit integer is interpreted as follows (bit
- 0 = least significant bit):
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - Bit 0:15
-
- - QP value
-
- - .. row 2
-
- - Bit 16:32
-
- - Layer number
-
-
-
-
-MFC 5.1 MPEG Controls
----------------------
-
-The following MPEG class controls deal with MPEG decoding and encoding
-settings that are specific to the Multi Format Codec 5.1 device present
-in the S5P family of SoCs by Samsung.
-
-
-.. _mfc51-control-id:
-
-MFC 5.1 Control IDs
-^^^^^^^^^^^^^^^^^^^
-
-``V4L2_CID_MPEG_MFC51_VIDEO_DECODER_H264_DISPLAY_DELAY_ENABLE (boolean)``
- If the display delay is enabled then the decoder is forced to return
- a CAPTURE buffer (decoded frame) after processing a certain number
- of OUTPUT buffers. The delay can be set through
- ``V4L2_CID_MPEG_MFC51_VIDEO_DECODER_H264_DISPLAY_DELAY``. This
- feature can be used for example for generating thumbnails of videos.
- Applicable to the H264 decoder.
-
-``V4L2_CID_MPEG_MFC51_VIDEO_DECODER_H264_DISPLAY_DELAY (integer)``
- Display delay value for H264 decoder. The decoder is forced to
- return a decoded frame after the set 'display delay' number of
- frames. If this number is low it may result in frames returned out
- of dispaly order, in addition the hardware may still be using the
- returned buffer as a reference picture for subsequent frames.
-
-``V4L2_CID_MPEG_MFC51_VIDEO_H264_NUM_REF_PIC_FOR_P (integer)``
- The number of reference pictures used for encoding a P picture.
- Applicable to the H264 encoder.
-
-``V4L2_CID_MPEG_MFC51_VIDEO_PADDING (boolean)``
- Padding enable in the encoder - use a color instead of repeating
- border pixels. Applicable to encoders.
-
-``V4L2_CID_MPEG_MFC51_VIDEO_PADDING_YUV (integer)``
- Padding color in the encoder. Applicable to encoders. The supplied
- 32-bit integer is interpreted as follows (bit 0 = least significant
- bit):
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - Bit 0:7
-
- - V chrominance information
-
- - .. row 2
-
- - Bit 8:15
-
- - U chrominance information
-
- - .. row 3
-
- - Bit 16:23
-
- - Y luminance information
-
- - .. row 4
-
- - Bit 24:31
-
- - Must be zero.
-
-
-
-``V4L2_CID_MPEG_MFC51_VIDEO_RC_REACTION_COEFF (integer)``
- Reaction coefficient for MFC rate control. Applicable to encoders.
-
- Note 1: Valid only when the frame level RC is enabled.
-
- Note 2: For tight CBR, this field must be small (ex. 2 ~ 10). For
- VBR, this field must be large (ex. 100 ~ 1000).
-
- Note 3: It is not recommended to use the greater number than
- FRAME_RATE * (10^9 / BIT_RATE).
-
-``V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_DARK (boolean)``
- Adaptive rate control for dark region. Valid only when H.264 and
- macroblock level RC is enabled
- (``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE``). Applicable to the H264
- encoder.
-
-``V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_SMOOTH (boolean)``
- Adaptive rate control for smooth region. Valid only when H.264 and
- macroblock level RC is enabled
- (``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE``). Applicable to the H264
- encoder.
-
-``V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_STATIC (boolean)``
- Adaptive rate control for static region. Valid only when H.264 and
- macroblock level RC is enabled
- (``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE``). Applicable to the H264
- encoder.
-
-``V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_ACTIVITY (boolean)``
- Adaptive rate control for activity region. Valid only when H.264 and
- macroblock level RC is enabled
- (``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE``). Applicable to the H264
- encoder.
-
-.. _v4l2-mpeg-mfc51-video-frame-skip-mode:
-
-``V4L2_CID_MPEG_MFC51_VIDEO_FRAME_SKIP_MODE (enum v4l2_mpeg_mfc51_video_frame_skip_mode)``
- Indicates in what conditions the encoder should skip frames. If
- encoding a frame would cause the encoded stream to be larger then a
- chosen data limit then the frame will be skipped. Possible values
- are:
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_MPEG_MFC51_FRAME_SKIP_MODE_DISABLED``
-
- - Frame skip mode is disabled.
-
- - .. row 2
-
- - ``V4L2_MPEG_MFC51_FRAME_SKIP_MODE_LEVEL_LIMIT``
-
- - Frame skip mode enabled and buffer limit is set by the chosen
- level and is defined by the standard.
-
- - .. row 3
-
- - ``V4L2_MPEG_MFC51_FRAME_SKIP_MODE_BUF_LIMIT``
-
- - Frame skip mode enabled and buffer limit is set by the VBV
- (MPEG1/2/4) or CPB (H264) buffer size control.
-
-
-
-``V4L2_CID_MPEG_MFC51_VIDEO_RC_FIXED_TARGET_BIT (integer)``
- Enable rate-control with fixed target bit. If this setting is
- enabled, then the rate control logic of the encoder will calculate
- the average bitrate for a GOP and keep it below or equal the set
- bitrate target. Otherwise the rate control logic calculates the
- overall average bitrate for the stream and keeps it below or equal
- to the set bitrate. In the first case the average bitrate for the
- whole stream will be smaller then the set bitrate. This is caused
- because the average is calculated for smaller number of frames, on
- the other hand enabling this setting will ensure that the stream
- will meet tight bandwidth constraints. Applicable to encoders.
-
-.. _v4l2-mpeg-mfc51-video-force-frame-type:
-
-``V4L2_CID_MPEG_MFC51_VIDEO_FORCE_FRAME_TYPE (enum v4l2_mpeg_mfc51_video_force_frame_type)``
- Force a frame type for the next queued buffer. Applicable to
- encoders. Possible values are:
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_DISABLED``
-
- - Forcing a specific frame type disabled.
-
- - .. row 2
-
- - ``V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_I_FRAME``
-
- - Force an I-frame.
-
- - .. row 3
-
- - ``V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_NOT_CODED``
-
- - Force a non-coded frame.
-
-
-
-
-CX2341x MPEG Controls
----------------------
-
-The following MPEG class controls deal with MPEG encoding settings that
-are specific to the Conexant CX23415 and CX23416 MPEG encoding chips.
-
-
-.. _cx2341x-control-id:
-
-CX2341x Control IDs
-^^^^^^^^^^^^^^^^^^^
-
-.. _v4l2-mpeg-cx2341x-video-spatial-filter-mode:
-
-``V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE (enum v4l2_mpeg_cx2341x_video_spatial_filter_mode)``
- Sets the Spatial Filter mode (default ``MANUAL``). Possible values
- are:
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_MANUAL``
-
- - Choose the filter manually
-
- - .. row 2
-
- - ``V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_AUTO``
-
- - Choose the filter automatically
-
-
-
-``V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER (integer (0-15))``
- The setting for the Spatial Filter. 0 = off, 15 = maximum. (Default
- is 0.)
-
-.. _luma-spatial-filter-type:
-
-``V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE (enum v4l2_mpeg_cx2341x_video_luma_spatial_filter_type)``
- Select the algorithm to use for the Luma Spatial Filter (default
- ``1D_HOR``). Possible values:
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_OFF``
-
- - No filter
-
- - .. row 2
-
- - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_HOR``
-
- - One-dimensional horizontal
-
- - .. row 3
-
- - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_VERT``
-
- - One-dimensional vertical
-
- - .. row 4
-
- - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_HV_SEPARABLE``
-
- - Two-dimensional separable
-
- - .. row 5
-
- - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_SYM_NON_SEPARABLE``
-
- - Two-dimensional symmetrical non-separable
-
-
-
-.. _chroma-spatial-filter-type:
-
-``V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE (enum v4l2_mpeg_cx2341x_video_chroma_spatial_filter_type)``
- Select the algorithm for the Chroma Spatial Filter (default
- ``1D_HOR``). Possible values are:
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_OFF``
-
- - No filter
-
- - .. row 2
-
- - ``V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_1D_HOR``
-
- - One-dimensional horizontal
-
-
-
-.. _v4l2-mpeg-cx2341x-video-temporal-filter-mode:
-
-``V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE (enum v4l2_mpeg_cx2341x_video_temporal_filter_mode)``
- Sets the Temporal Filter mode (default ``MANUAL``). Possible values
- are:
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_MANUAL``
-
- - Choose the filter manually
-
- - .. row 2
-
- - ``V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_AUTO``
-
- - Choose the filter automatically
-
-
-
-``V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER (integer (0-31))``
- The setting for the Temporal Filter. 0 = off, 31 = maximum. (Default
- is 8 for full-scale capturing and 0 for scaled capturing.)
-
-.. _v4l2-mpeg-cx2341x-video-median-filter-type:
-
-``V4L2_CID_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE (enum v4l2_mpeg_cx2341x_video_median_filter_type)``
- Median Filter Type (default ``OFF``). Possible values are:
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_OFF``
-
- - No filter
-
- - .. row 2
-
- - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR``
-
- - Horizontal filter
-
- - .. row 3
-
- - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_VERT``
-
- - Vertical filter
-
- - .. row 4
-
- - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR_VERT``
-
- - Horizontal and vertical filter
-
- - .. row 5
-
- - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_DIAG``
-
- - Diagonal filter
-
-
-
-``V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_BOTTOM (integer (0-255))``
- Threshold above which the luminance median filter is enabled
- (default 0)
-
-``V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_TOP (integer (0-255))``
- Threshold below which the luminance median filter is enabled
- (default 255)
-
-``V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_BOTTOM (integer (0-255))``
- Threshold above which the chroma median filter is enabled (default
- 0)
-
-``V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_TOP (integer (0-255))``
- Threshold below which the chroma median filter is enabled (default
- 255)
-
-``V4L2_CID_MPEG_CX2341X_STREAM_INSERT_NAV_PACKETS (boolean)``
- The CX2341X MPEG encoder can insert one empty MPEG-2 PES packet into
- the stream between every four video frames. The packet size is 2048
- bytes, including the packet_start_code_prefix and stream_id
- fields. The stream_id is 0xBF (private stream 2). The payload
- consists of 0x00 bytes, to be filled in by the application. 0 = do
- not insert, 1 = insert packets.
-
-
-VPX Control Reference
----------------------
-
-The VPX controls include controls for encoding parameters of VPx video
-codec.
-
-
-.. _vpx-control-id:
-
-VPX Control IDs
-^^^^^^^^^^^^^^^
-
-.. _v4l2-vpx-num-partitions:
-
-``V4L2_CID_MPEG_VIDEO_VPX_NUM_PARTITIONS (enum v4l2_vp8_num_partitions)``
- The number of token partitions to use in VP8 encoder. Possible
- values are:
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_CID_MPEG_VIDEO_VPX_1_PARTITION``
-
- - 1 coefficient partition
-
- - .. row 2
-
- - ``V4L2_CID_MPEG_VIDEO_VPX_2_PARTITIONS``
-
- - 2 coefficient partitions
-
- - .. row 3
-
- - ``V4L2_CID_MPEG_VIDEO_VPX_4_PARTITIONS``
-
- - 4 coefficient partitions
-
- - .. row 4
-
- - ``V4L2_CID_MPEG_VIDEO_VPX_8_PARTITIONS``
-
- - 8 coefficient partitions
-
-
-
-``V4L2_CID_MPEG_VIDEO_VPX_IMD_DISABLE_4X4 (boolean)``
- Setting this prevents intra 4x4 mode in the intra mode decision.
-
-.. _v4l2-vpx-num-ref-frames:
-
-``V4L2_CID_MPEG_VIDEO_VPX_NUM_REF_FRAMES (enum v4l2_vp8_num_ref_frames)``
- The number of reference pictures for encoding P frames. Possible
- values are:
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_CID_MPEG_VIDEO_VPX_1_REF_FRAME``
-
- - Last encoded frame will be searched
-
- - .. row 2
-
- - ``V4L2_CID_MPEG_VIDEO_VPX_2_REF_FRAME``
-
- - Two frames will be searched among the last encoded frame, the
- golden frame and the alternate reference (altref) frame. The
- encoder implementation will decide which two are chosen.
-
- - .. row 3
-
- - ``V4L2_CID_MPEG_VIDEO_VPX_3_REF_FRAME``
-
- - The last encoded frame, the golden frame and the altref frame will
- be searched.
-
-
-
-``V4L2_CID_MPEG_VIDEO_VPX_FILTER_LEVEL (integer)``
- Indicates the loop filter level. The adjustment of the loop filter
- level is done via a delta value against a baseline loop filter
- value.
-
-``V4L2_CID_MPEG_VIDEO_VPX_FILTER_SHARPNESS (integer)``
- This parameter affects the loop filter. Anything above zero weakens
- the deblocking effect on the loop filter.
-
-``V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_REF_PERIOD (integer)``
- Sets the refresh period for the golden frame. The period is defined
- in number of frames. For a value of 'n', every nth frame starting
- from the first key frame will be taken as a golden frame. For eg.
- for encoding sequence of 0, 1, 2, 3, 4, 5, 6, 7 where the golden
- frame refresh period is set as 4, the frames 0, 4, 8 etc will be
- taken as the golden frames as frame 0 is always a key frame.
-
-.. _v4l2-vpx-golden-frame-sel:
-
-``V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_SEL (enum v4l2_vp8_golden_frame_sel)``
- Selects the golden frame for encoding. Possible values are:
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_USE_PREV``
-
- - Use the (n-2)th frame as a golden frame, current frame index being
- 'n'.
-
- - .. row 2
-
- - ``V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_USE_REF_PERIOD``
-
- - Use the previous specific frame indicated by
- V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_REF_PERIOD as a
- golden frame.
-
-
-
-``V4L2_CID_MPEG_VIDEO_VPX_MIN_QP (integer)``
- Minimum quantization parameter for VP8.
-
-``V4L2_CID_MPEG_VIDEO_VPX_MAX_QP (integer)``
- Maximum quantization parameter for VP8.
-
-``V4L2_CID_MPEG_VIDEO_VPX_I_FRAME_QP (integer)``
- Quantization parameter for an I frame for VP8.
-
-``V4L2_CID_MPEG_VIDEO_VPX_P_FRAME_QP (integer)``
- Quantization parameter for a P frame for VP8.
-
-``V4L2_CID_MPEG_VIDEO_VPX_PROFILE (integer)``
- Select the desired profile for VPx encoder. Acceptable values are 0,
- 1, 2 and 3 corresponding to encoder profiles 0, 1, 2 and 3.
-
-
-.. _camera-controls:
-
-Camera Control Reference
-========================
-
-The Camera class includes controls for mechanical (or equivalent
-digital) features of a device such as controllable lenses or sensors.
-
-
-.. _camera-control-id:
-
-Camera Control IDs
-------------------
-
-``V4L2_CID_CAMERA_CLASS (class)``
- The Camera class descriptor. Calling
- :ref:`VIDIOC_QUERYCTRL` for this control will
- return a description of this control class.
-
-.. _v4l2-exposure-auto-type:
-
-``V4L2_CID_EXPOSURE_AUTO (enum v4l2_exposure_auto_type)``
- Enables automatic adjustments of the exposure time and/or iris
- aperture. The effect of manual changes of the exposure time or iris
- aperture while these features are enabled is undefined, drivers
- should ignore such requests. Possible values are:
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_EXPOSURE_AUTO``
-
- - Automatic exposure time, automatic iris aperture.
-
- - .. row 2
-
- - ``V4L2_EXPOSURE_MANUAL``
-
- - Manual exposure time, manual iris.
-
- - .. row 3
-
- - ``V4L2_EXPOSURE_SHUTTER_PRIORITY``
-
- - Manual exposure time, auto iris.
-
- - .. row 4
-
- - ``V4L2_EXPOSURE_APERTURE_PRIORITY``
-
- - Auto exposure time, manual iris.
-
-
-
-``V4L2_CID_EXPOSURE_ABSOLUTE (integer)``
- Determines the exposure time of the camera sensor. The exposure time
- is limited by the frame interval. Drivers should interpret the
- values as 100 µs units, where the value 1 stands for 1/10000th of a
- second, 10000 for 1 second and 100000 for 10 seconds.
-
-``V4L2_CID_EXPOSURE_AUTO_PRIORITY (boolean)``
- When ``V4L2_CID_EXPOSURE_AUTO`` is set to ``AUTO`` or
- ``APERTURE_PRIORITY``, this control determines if the device may
- dynamically vary the frame rate. By default this feature is disabled
- (0) and the frame rate must remain constant.
-
-``V4L2_CID_EXPOSURE_BIAS (integer menu)``
- Determines the automatic exposure compensation, it is effective only
- when ``V4L2_CID_EXPOSURE_AUTO`` control is set to ``AUTO``,
- ``SHUTTER_PRIORITY`` or ``APERTURE_PRIORITY``. It is expressed in
- terms of EV, drivers should interpret the values as 0.001 EV units,
- where the value 1000 stands for +1 EV.
-
- Increasing the exposure compensation value is equivalent to
- decreasing the exposure value (EV) and will increase the amount of
- light at the image sensor. The camera performs the exposure
- compensation by adjusting absolute exposure time and/or aperture.
-
-.. _v4l2-exposure-metering:
-
-``V4L2_CID_EXPOSURE_METERING (enum v4l2_exposure_metering)``
- Determines how the camera measures the amount of light available for
- the frame exposure. Possible values are:
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_EXPOSURE_METERING_AVERAGE``
-
- - Use the light information coming from the entire frame and average
- giving no weighting to any particular portion of the metered area.
-
- - .. row 2
-
- - ``V4L2_EXPOSURE_METERING_CENTER_WEIGHTED``
-
- - Average the light information coming from the entire frame giving
- priority to the center of the metered area.
-
- - .. row 3
-
- - ``V4L2_EXPOSURE_METERING_SPOT``
-
- - Measure only very small area at the center of the frame.
-
- - .. row 4
-
- - ``V4L2_EXPOSURE_METERING_MATRIX``
-
- - A multi-zone metering. The light intensity is measured in several
- points of the frame and the results are combined. The algorithm of
- the zones selection and their significance in calculating the
- final value is device dependent.
-
-
-
-``V4L2_CID_PAN_RELATIVE (integer)``
- This control turns the camera horizontally by the specified amount.
- The unit is undefined. A positive value moves the camera to the
- right (clockwise when viewed from above), a negative value to the
- left. A value of zero does not cause motion. This is a write-only
- control.
-
-``V4L2_CID_TILT_RELATIVE (integer)``
- This control turns the camera vertically by the specified amount.
- The unit is undefined. A positive value moves the camera up, a
- negative value down. A value of zero does not cause motion. This is
- a write-only control.
-
-``V4L2_CID_PAN_RESET (button)``
- When this control is set, the camera moves horizontally to the
- default position.
-
-``V4L2_CID_TILT_RESET (button)``
- When this control is set, the camera moves vertically to the default
- position.
-
-``V4L2_CID_PAN_ABSOLUTE (integer)``
- This control turns the camera horizontally to the specified
- position. Positive values move the camera to the right (clockwise
- when viewed from above), negative values to the left. Drivers should
- interpret the values as arc seconds, with valid values between -180
- * 3600 and +180 * 3600 inclusive.
-
-``V4L2_CID_TILT_ABSOLUTE (integer)``
- This control turns the camera vertically to the specified position.
- Positive values move the camera up, negative values down. Drivers
- should interpret the values as arc seconds, with valid values
- between -180 * 3600 and +180 * 3600 inclusive.
-
-``V4L2_CID_FOCUS_ABSOLUTE (integer)``
- This control sets the focal point of the camera to the specified
- position. The unit is undefined. Positive values set the focus
- closer to the camera, negative values towards infinity.
-
-``V4L2_CID_FOCUS_RELATIVE (integer)``
- This control moves the focal point of the camera by the specified
- amount. The unit is undefined. Positive values move the focus closer
- to the camera, negative values towards infinity. This is a
- write-only control.
-
-``V4L2_CID_FOCUS_AUTO (boolean)``
- Enables continuous automatic focus adjustments. The effect of manual
- focus adjustments while this feature is enabled is undefined,
- drivers should ignore such requests.
-
-``V4L2_CID_AUTO_FOCUS_START (button)``
- Starts single auto focus process. The effect of setting this control
- when ``V4L2_CID_FOCUS_AUTO`` is set to ``TRUE`` (1) is undefined,
- drivers should ignore such requests.
-
-``V4L2_CID_AUTO_FOCUS_STOP (button)``
- Aborts automatic focusing started with ``V4L2_CID_AUTO_FOCUS_START``
- control. It is effective only when the continuous autofocus is
- disabled, that is when ``V4L2_CID_FOCUS_AUTO`` control is set to
- ``FALSE`` (0).
-
-.. _v4l2-auto-focus-status:
-
-``V4L2_CID_AUTO_FOCUS_STATUS (bitmask)``
- The automatic focus status. This is a read-only control.
-
- Setting ``V4L2_LOCK_FOCUS`` lock bit of the ``V4L2_CID_3A_LOCK``
- control may stop updates of the ``V4L2_CID_AUTO_FOCUS_STATUS``
- control value.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_AUTO_FOCUS_STATUS_IDLE``
-
- - Automatic focus is not active.
-
- - .. row 2
-
- - ``V4L2_AUTO_FOCUS_STATUS_BUSY``
-
- - Automatic focusing is in progress.
-
- - .. row 3
-
- - ``V4L2_AUTO_FOCUS_STATUS_REACHED``
-
- - Focus has been reached.
-
- - .. row 4
-
- - ``V4L2_AUTO_FOCUS_STATUS_FAILED``
-
- - Automatic focus has failed, the driver will not transition from
- this state until another action is performed by an application.
-
-
-
-.. _v4l2-auto-focus-range:
-
-``V4L2_CID_AUTO_FOCUS_RANGE (enum v4l2_auto_focus_range)``
- Determines auto focus distance range for which lens may be adjusted.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_AUTO_FOCUS_RANGE_AUTO``
-
- - The camera automatically selects the focus range.
-
- - .. row 2
-
- - ``V4L2_AUTO_FOCUS_RANGE_NORMAL``
-
- - Normal distance range, limited for best automatic focus
- performance.
-
- - .. row 3
-
- - ``V4L2_AUTO_FOCUS_RANGE_MACRO``
-
- - Macro (close-up) auto focus. The camera will use its minimum
- possible distance for auto focus.
-
- - .. row 4
-
- - ``V4L2_AUTO_FOCUS_RANGE_INFINITY``
-
- - The lens is set to focus on an object at infinite distance.
-
-
-
-``V4L2_CID_ZOOM_ABSOLUTE (integer)``
- Specify the objective lens focal length as an absolute value. The
- zoom unit is driver-specific and its value should be a positive
- integer.
-
-``V4L2_CID_ZOOM_RELATIVE (integer)``
- Specify the objective lens focal length relatively to the current
- value. Positive values move the zoom lens group towards the
- telephoto direction, negative values towards the wide-angle
- direction. The zoom unit is driver-specific. This is a write-only
- control.
-
-``V4L2_CID_ZOOM_CONTINUOUS (integer)``
- Move the objective lens group at the specified speed until it
- reaches physical device limits or until an explicit request to stop
- the movement. A positive value moves the zoom lens group towards the
- telephoto direction. A value of zero stops the zoom lens group
- movement. A negative value moves the zoom lens group towards the
- wide-angle direction. The zoom speed unit is driver-specific.
-
-``V4L2_CID_IRIS_ABSOLUTE (integer)``
- This control sets the camera's aperture to the specified value. The
- unit is undefined. Larger values open the iris wider, smaller values
- close it.
-
-``V4L2_CID_IRIS_RELATIVE (integer)``
- This control modifies the camera's aperture by the specified amount.
- The unit is undefined. Positive values open the iris one step
- further, negative values close it one step further. This is a
- write-only control.
-
-``V4L2_CID_PRIVACY (boolean)``
- Prevent video from being acquired by the camera. When this control
- is set to ``TRUE`` (1), no image can be captured by the camera.
- Common means to enforce privacy are mechanical obturation of the
- sensor and firmware image processing, but the device is not
- restricted to these methods. Devices that implement the privacy
- control must support read access and may support write access.
-
-``V4L2_CID_BAND_STOP_FILTER (integer)``
- Switch the band-stop filter of a camera sensor on or off, or specify
- its strength. Such band-stop filters can be used, for example, to
- filter out the fluorescent light component.
-
-.. _v4l2-auto-n-preset-white-balance:
-
-``V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE (enum v4l2_auto_n_preset_white_balance)``
- Sets white balance to automatic, manual or a preset. The presets
- determine color temperature of the light as a hint to the camera for
- white balance adjustments resulting in most accurate color
- representation. The following white balance presets are listed in
- order of increasing color temperature.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_WHITE_BALANCE_MANUAL``
-
- - Manual white balance.
-
- - .. row 2
-
- - ``V4L2_WHITE_BALANCE_AUTO``
-
- - Automatic white balance adjustments.
-
- - .. row 3
-
- - ``V4L2_WHITE_BALANCE_INCANDESCENT``
-
- - White balance setting for incandescent (tungsten) lighting. It
- generally cools down the colors and corresponds approximately to
- 2500...3500 K color temperature range.
-
- - .. row 4
-
- - ``V4L2_WHITE_BALANCE_FLUORESCENT``
-
- - White balance preset for fluorescent lighting. It corresponds
- approximately to 4000...5000 K color temperature.
-
- - .. row 5
-
- - ``V4L2_WHITE_BALANCE_FLUORESCENT_H``
-
- - With this setting the camera will compensate for fluorescent H
- lighting.
-
- - .. row 6
-
- - ``V4L2_WHITE_BALANCE_HORIZON``
-
- - White balance setting for horizon daylight. It corresponds
- approximately to 5000 K color temperature.
-
- - .. row 7
-
- - ``V4L2_WHITE_BALANCE_DAYLIGHT``
-
- - White balance preset for daylight (with clear sky). It corresponds
- approximately to 5000...6500 K color temperature.
-
- - .. row 8
-
- - ``V4L2_WHITE_BALANCE_FLASH``
-
- - With this setting the camera will compensate for the flash light.
- It slightly warms up the colors and corresponds roughly to
- 5000...5500 K color temperature.
-
- - .. row 9
-
- - ``V4L2_WHITE_BALANCE_CLOUDY``
-
- - White balance preset for moderately overcast sky. This option
- corresponds approximately to 6500...8000 K color temperature
- range.
-
- - .. row 10
-
- - ``V4L2_WHITE_BALANCE_SHADE``
-
- - White balance preset for shade or heavily overcast sky. It
- corresponds approximately to 9000...10000 K color temperature.
-
-
-
-.. _v4l2-wide-dynamic-range:
-
-``V4L2_CID_WIDE_DYNAMIC_RANGE (boolean)``
- Enables or disables the camera's wide dynamic range feature. This
- feature allows to obtain clear images in situations where intensity
- of the illumination varies significantly throughout the scene, i.e.
- there are simultaneously very dark and very bright areas. It is most
- commonly realized in cameras by combining two subsequent frames with
- different exposure times. [1]_
-
-.. _v4l2-image-stabilization:
-
-``V4L2_CID_IMAGE_STABILIZATION (boolean)``
- Enables or disables image stabilization.
-
-``V4L2_CID_ISO_SENSITIVITY (integer menu)``
- Determines ISO equivalent of an image sensor indicating the sensor's
- sensitivity to light. The numbers are expressed in arithmetic scale,
- as per :ref:`iso12232` standard, where doubling the sensor
- sensitivity is represented by doubling the numerical ISO value.
- Applications should interpret the values as standard ISO values
- multiplied by 1000, e.g. control value 800 stands for ISO 0.8.
- Drivers will usually support only a subset of standard ISO values.
- The effect of setting this control while the
- ``V4L2_CID_ISO_SENSITIVITY_AUTO`` control is set to a value other
- than ``V4L2_CID_ISO_SENSITIVITY_MANUAL`` is undefined, drivers
- should ignore such requests.
-
-.. _v4l2-iso-sensitivity-auto-type:
-
-``V4L2_CID_ISO_SENSITIVITY_AUTO (enum v4l2_iso_sensitivity_type)``
- Enables or disables automatic ISO sensitivity adjustments.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_CID_ISO_SENSITIVITY_MANUAL``
-
- - Manual ISO sensitivity.
-
- - .. row 2
-
- - ``V4L2_CID_ISO_SENSITIVITY_AUTO``
-
- - Automatic ISO sensitivity adjustments.
-
-
-
-.. _v4l2-scene-mode:
-
-``V4L2_CID_SCENE_MODE (enum v4l2_scene_mode)``
- This control allows to select scene programs as the camera automatic
- modes optimized for common shooting scenes. Within these modes the
- camera determines best exposure, aperture, focusing, light metering,
- white balance and equivalent sensitivity. The controls of those
- parameters are influenced by the scene mode control. An exact
- behavior in each mode is subject to the camera specification.
-
- When the scene mode feature is not used, this control should be set
- to ``V4L2_SCENE_MODE_NONE`` to make sure the other possibly related
- controls are accessible. The following scene programs are defined:
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_SCENE_MODE_NONE``
-
- - The scene mode feature is disabled.
-
- - .. row 2
-
- - ``V4L2_SCENE_MODE_BACKLIGHT``
-
- - Backlight. Compensates for dark shadows when light is coming from
- behind a subject, also by automatically turning on the flash.
-
- - .. row 3
-
- - ``V4L2_SCENE_MODE_BEACH_SNOW``
-
- - Beach and snow. This mode compensates for all-white or bright
- scenes, which tend to look gray and low contrast, when camera's
- automatic exposure is based on an average scene brightness. To
- compensate, this mode automatically slightly overexposes the
- frames. The white balance may also be adjusted to compensate for
- the fact that reflected snow looks bluish rather than white.
-
- - .. row 4
-
- - ``V4L2_SCENE_MODE_CANDLELIGHT``
-
- - Candle light. The camera generally raises the ISO sensitivity and
- lowers the shutter speed. This mode compensates for relatively
- close subject in the scene. The flash is disabled in order to
- preserve the ambiance of the light.
-
- - .. row 5
-
- - ``V4L2_SCENE_MODE_DAWN_DUSK``
-
- - Dawn and dusk. Preserves the colors seen in low natural light
- before dusk and after down. The camera may turn off the flash, and
- automatically focus at infinity. It will usually boost saturation
- and lower the shutter speed.
-
- - .. row 6
-
- - ``V4L2_SCENE_MODE_FALL_COLORS``
-
- - Fall colors. Increases saturation and adjusts white balance for
- color enhancement. Pictures of autumn leaves get saturated reds
- and yellows.
-
- - .. row 7
-
- - ``V4L2_SCENE_MODE_FIREWORKS``
-
- - Fireworks. Long exposure times are used to capture the expanding
- burst of light from a firework. The camera may invoke image
- stabilization.
-
- - .. row 8
-
- - ``V4L2_SCENE_MODE_LANDSCAPE``
-
- - Landscape. The camera may choose a small aperture to provide deep
- depth of field and long exposure duration to help capture detail
- in dim light conditions. The focus is fixed at infinity. Suitable
- for distant and wide scenery.
-
- - .. row 9
-
- - ``V4L2_SCENE_MODE_NIGHT``
-
- - Night, also known as Night Landscape. Designed for low light
- conditions, it preserves detail in the dark areas without blowing
- out bright objects. The camera generally sets itself to a
- medium-to-high ISO sensitivity, with a relatively long exposure
- time, and turns flash off. As such, there will be increased image
- noise and the possibility of blurred image.
-
- - .. row 10
-
- - ``V4L2_SCENE_MODE_PARTY_INDOOR``
-
- - Party and indoor. Designed to capture indoor scenes that are lit
- by indoor background lighting as well as the flash. The camera
- usually increases ISO sensitivity, and adjusts exposure for the
- low light conditions.
-
- - .. row 11
-
- - ``V4L2_SCENE_MODE_PORTRAIT``
-
- - Portrait. The camera adjusts the aperture so that the depth of
- field is reduced, which helps to isolate the subject against a
- smooth background. Most cameras recognize the presence of faces in
- the scene and focus on them. The color hue is adjusted to enhance
- skin tones. The intensity of the flash is often reduced.
-
- - .. row 12
-
- - ``V4L2_SCENE_MODE_SPORTS``
-
- - Sports. Significantly increases ISO and uses a fast shutter speed
- to freeze motion of rapidly-moving subjects. Increased image noise
- may be seen in this mode.
-
- - .. row 13
-
- - ``V4L2_SCENE_MODE_SUNSET``
-
- - Sunset. Preserves deep hues seen in sunsets and sunrises. It bumps
- up the saturation.
-
- - .. row 14
-
- - ``V4L2_SCENE_MODE_TEXT``
-
- - Text. It applies extra contrast and sharpness, it is typically a
- black-and-white mode optimized for readability. Automatic focus
- may be switched to close-up mode and this setting may also involve
- some lens-distortion correction.
-
-
-
-``V4L2_CID_3A_LOCK (bitmask)``
- This control locks or unlocks the automatic focus, exposure and
- white balance. The automatic adjustments can be paused independently
- by setting the corresponding lock bit to 1. The camera then retains
- the settings until the lock bit is cleared. The following lock bits
- are defined:
-
- When a given algorithm is not enabled, drivers should ignore
- requests to lock it and should return no error. An example might be
- an application setting bit ``V4L2_LOCK_WHITE_BALANCE`` when the
- ``V4L2_CID_AUTO_WHITE_BALANCE`` control is set to ``FALSE``. The
- value of this control may be changed by exposure, white balance or
- focus controls.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_LOCK_EXPOSURE``
-
- - Automatic exposure adjustments lock.
-
- - .. row 2
-
- - ``V4L2_LOCK_WHITE_BALANCE``
-
- - Automatic white balance adjustments lock.
-
- - .. row 3
-
- - ``V4L2_LOCK_FOCUS``
-
- - Automatic focus lock.
-
-
-
-``V4L2_CID_PAN_SPEED (integer)``
- This control turns the camera horizontally at the specific speed.
- The unit is undefined. A positive value moves the camera to the
- right (clockwise when viewed from above), a negative value to the
- left. A value of zero stops the motion if one is in progress and has
- no effect otherwise.
-
-``V4L2_CID_TILT_SPEED (integer)``
- This control turns the camera vertically at the specified speed. The
- unit is undefined. A positive value moves the camera up, a negative
- value down. A value of zero stops the motion if one is in progress
- and has no effect otherwise.
-
-
-.. _fm-tx-controls:
-
-FM Transmitter Control Reference
-================================
-
-The FM Transmitter (FM_TX) class includes controls for common features
-of FM transmissions capable devices. Currently this class includes
-parameters for audio compression, pilot tone generation, audio deviation
-limiter, RDS transmission and tuning power features.
-
-
-.. _fm-tx-control-id:
-
-FM_TX Control IDs
------------------
-
-``V4L2_CID_FM_TX_CLASS (class)``
- The FM_TX class descriptor. Calling
- :ref:`VIDIOC_QUERYCTRL` for this control will
- return a description of this control class.
-
-``V4L2_CID_RDS_TX_DEVIATION (integer)``
- Configures RDS signal frequency deviation level in Hz. The range and
- step are driver-specific.
-
-``V4L2_CID_RDS_TX_PI (integer)``
- Sets the RDS Programme Identification field for transmission.
-
-``V4L2_CID_RDS_TX_PTY (integer)``
- Sets the RDS Programme Type field for transmission. This encodes up
- to 31 pre-defined programme types.
-
-``V4L2_CID_RDS_TX_PS_NAME (string)``
- Sets the Programme Service name (PS_NAME) for transmission. It is
- intended for static display on a receiver. It is the primary aid to
- listeners in programme service identification and selection. In
- Annex E of :ref:`iec62106`, the RDS specification, there is a full
- description of the correct character encoding for Programme Service
- name strings. Also from RDS specification, PS is usually a single
- eight character text. However, it is also possible to find receivers
- which can scroll strings sized as 8 x N characters. So, this control
- must be configured with steps of 8 characters. The result is it must
- always contain a string with size multiple of 8.
-
-``V4L2_CID_RDS_TX_RADIO_TEXT (string)``
- Sets the Radio Text info for transmission. It is a textual
- description of what is being broadcasted. RDS Radio Text can be
- applied when broadcaster wishes to transmit longer PS names,
- programme-related information or any other text. In these cases,
- RadioText should be used in addition to ``V4L2_CID_RDS_TX_PS_NAME``.
- The encoding for Radio Text strings is also fully described in Annex
- E of :ref:`iec62106`. The length of Radio Text strings depends on
- which RDS Block is being used to transmit it, either 32 (2A block)
- or 64 (2B block). However, it is also possible to find receivers
- which can scroll strings sized as 32 x N or 64 x N characters. So,
- this control must be configured with steps of 32 or 64 characters.
- The result is it must always contain a string with size multiple of
- 32 or 64.
-
-``V4L2_CID_RDS_TX_MONO_STEREO (boolean)``
- Sets the Mono/Stereo bit of the Decoder Identification code. If set,
- then the audio was recorded as stereo.
-
-``V4L2_CID_RDS_TX_ARTIFICIAL_HEAD (boolean)``
- Sets the
- `Artificial Head <http://en.wikipedia.org/wiki/Artificial_head>`__
- bit of the Decoder Identification code. If set, then the audio was
- recorded using an artificial head.
-
-``V4L2_CID_RDS_TX_COMPRESSED (boolean)``
- Sets the Compressed bit of the Decoder Identification code. If set,
- then the audio is compressed.
-
-``V4L2_CID_RDS_TX_DYNAMIC_PTY (boolean)``
- Sets the Dynamic PTY bit of the Decoder Identification code. If set,
- then the PTY code is dynamically switched.
-
-``V4L2_CID_RDS_TX_TRAFFIC_ANNOUNCEMENT (boolean)``
- If set, then a traffic announcement is in progress.
-
-``V4L2_CID_RDS_TX_TRAFFIC_PROGRAM (boolean)``
- If set, then the tuned programme carries traffic announcements.
-
-``V4L2_CID_RDS_TX_MUSIC_SPEECH (boolean)``
- If set, then this channel broadcasts music. If cleared, then it
- broadcasts speech. If the transmitter doesn't make this distinction,
- then it should be set.
-
-``V4L2_CID_RDS_TX_ALT_FREQS_ENABLE (boolean)``
- If set, then transmit alternate frequencies.
-
-``V4L2_CID_RDS_TX_ALT_FREQS (__u32 array)``
- The alternate frequencies in kHz units. The RDS standard allows for
- up to 25 frequencies to be defined. Drivers may support fewer
- frequencies so check the array size.
-
-``V4L2_CID_AUDIO_LIMITER_ENABLED (boolean)``
- Enables or disables the audio deviation limiter feature. The limiter
- is useful when trying to maximize the audio volume, minimize
- receiver-generated distortion and prevent overmodulation.
-
-``V4L2_CID_AUDIO_LIMITER_RELEASE_TIME (integer)``
- Sets the audio deviation limiter feature release time. Unit is in
- useconds. Step and range are driver-specific.
-
-``V4L2_CID_AUDIO_LIMITER_DEVIATION (integer)``
- Configures audio frequency deviation level in Hz. The range and step
- are driver-specific.
-
-``V4L2_CID_AUDIO_COMPRESSION_ENABLED (boolean)``
- Enables or disables the audio compression feature. This feature
- amplifies signals below the threshold by a fixed gain and compresses
- audio signals above the threshold by the ratio of Threshold/(Gain +
- Threshold).
-
-``V4L2_CID_AUDIO_COMPRESSION_GAIN (integer)``
- Sets the gain for audio compression feature. It is a dB value. The
- range and step are driver-specific.
-
-``V4L2_CID_AUDIO_COMPRESSION_THRESHOLD (integer)``
- Sets the threshold level for audio compression freature. It is a dB
- value. The range and step are driver-specific.
-
-``V4L2_CID_AUDIO_COMPRESSION_ATTACK_TIME (integer)``
- Sets the attack time for audio compression feature. It is a useconds
- value. The range and step are driver-specific.
-
-``V4L2_CID_AUDIO_COMPRESSION_RELEASE_TIME (integer)``
- Sets the release time for audio compression feature. It is a
- useconds value. The range and step are driver-specific.
-
-``V4L2_CID_PILOT_TONE_ENABLED (boolean)``
- Enables or disables the pilot tone generation feature.
-
-``V4L2_CID_PILOT_TONE_DEVIATION (integer)``
- Configures pilot tone frequency deviation level. Unit is in Hz. The
- range and step are driver-specific.
-
-``V4L2_CID_PILOT_TONE_FREQUENCY (integer)``
- Configures pilot tone frequency value. Unit is in Hz. The range and
- step are driver-specific.
-
-``V4L2_CID_TUNE_PREEMPHASIS (enum v4l2_preemphasis)``
- Configures the pre-emphasis value for broadcasting. A pre-emphasis
- filter is applied to the broadcast to accentuate the high audio
- frequencies. Depending on the region, a time constant of either 50
- or 75 useconds is used. The enum v4l2_preemphasis defines possible
- values for pre-emphasis. Here they are:
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_PREEMPHASIS_DISABLED``
-
- - No pre-emphasis is applied.
-
- - .. row 2
-
- - ``V4L2_PREEMPHASIS_50_uS``
-
- - A pre-emphasis of 50 uS is used.
-
- - .. row 3
-
- - ``V4L2_PREEMPHASIS_75_uS``
-
- - A pre-emphasis of 75 uS is used.
-
-
-
-``V4L2_CID_TUNE_POWER_LEVEL (integer)``
- Sets the output power level for signal transmission. Unit is in
- dBuV. Range and step are driver-specific.
-
-``V4L2_CID_TUNE_ANTENNA_CAPACITOR (integer)``
- This selects the value of antenna tuning capacitor manually or
- automatically if set to zero. Unit, range and step are
- driver-specific.
-
-For more details about RDS specification, refer to :ref:`iec62106`
-document, from CENELEC.
-
-
-.. _flash-controls:
-
-Flash Control Reference
-=======================
-
-The V4L2 flash controls are intended to provide generic access to flash
-controller devices. Flash controller devices are typically used in
-digital cameras.
-
-The interface can support both LED and xenon flash devices. As of
-writing this, there is no xenon flash driver using this interface.
-
-
-.. _flash-controls-use-cases:
-
-Supported use cases
--------------------
-
-
-Unsynchronised LED flash (software strobe)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Unsynchronised LED flash is controlled directly by the host as the
-sensor. The flash must be enabled by the host before the exposure of the
-image starts and disabled once it ends. The host is fully responsible
-for the timing of the flash.
-
-Example of such device: Nokia N900.
-
-
-Synchronised LED flash (hardware strobe)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The synchronised LED flash is pre-programmed by the host (power and
-timeout) but controlled by the sensor through a strobe signal from the
-sensor to the flash.
-
-The sensor controls the flash duration and timing. This information
-typically must be made available to the sensor.
-
-
-LED flash as torch
-^^^^^^^^^^^^^^^^^^
-
-LED flash may be used as torch in conjunction with another use case
-involving camera or individually.
-
-
-.. _flash-control-id:
-
-Flash Control IDs
-"""""""""""""""""
-
-``V4L2_CID_FLASH_CLASS (class)``
- The FLASH class descriptor.
-
-``V4L2_CID_FLASH_LED_MODE (menu)``
- Defines the mode of the flash LED, the high-power white LED attached
- to the flash controller. Setting this control may not be possible in
- presence of some faults. See V4L2_CID_FLASH_FAULT.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_FLASH_LED_MODE_NONE``
-
- - Off.
-
- - .. row 2
-
- - ``V4L2_FLASH_LED_MODE_FLASH``
-
- - Flash mode.
-
- - .. row 3
-
- - ``V4L2_FLASH_LED_MODE_TORCH``
-
- - Torch mode. See V4L2_CID_FLASH_TORCH_INTENSITY.
-
-
-
-``V4L2_CID_FLASH_STROBE_SOURCE (menu)``
- Defines the source of the flash LED strobe.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_FLASH_STROBE_SOURCE_SOFTWARE``
-
- - The flash strobe is triggered by using the
- V4L2_CID_FLASH_STROBE control.
-
- - .. row 2
-
- - ``V4L2_FLASH_STROBE_SOURCE_EXTERNAL``
-
- - The flash strobe is triggered by an external source. Typically
- this is a sensor, which makes it possible to synchronises the
- flash strobe start to exposure start.
-
-
-
-``V4L2_CID_FLASH_STROBE (button)``
- Strobe flash. Valid when V4L2_CID_FLASH_LED_MODE is set to
- V4L2_FLASH_LED_MODE_FLASH and V4L2_CID_FLASH_STROBE_SOURCE
- is set to V4L2_FLASH_STROBE_SOURCE_SOFTWARE. Setting this
- control may not be possible in presence of some faults. See
- V4L2_CID_FLASH_FAULT.
-
-``V4L2_CID_FLASH_STROBE_STOP (button)``
- Stop flash strobe immediately.
-
-``V4L2_CID_FLASH_STROBE_STATUS (boolean)``
- Strobe status: whether the flash is strobing at the moment or not.
- This is a read-only control.
-
-``V4L2_CID_FLASH_TIMEOUT (integer)``
- Hardware timeout for flash. The flash strobe is stopped after this
- period of time has passed from the start of the strobe.
-
-``V4L2_CID_FLASH_INTENSITY (integer)``
- Intensity of the flash strobe when the flash LED is in flash mode
- (V4L2_FLASH_LED_MODE_FLASH). The unit should be milliamps (mA)
- if possible.
-
-``V4L2_CID_FLASH_TORCH_INTENSITY (integer)``
- Intensity of the flash LED in torch mode
- (V4L2_FLASH_LED_MODE_TORCH). The unit should be milliamps (mA)
- if possible. Setting this control may not be possible in presence of
- some faults. See V4L2_CID_FLASH_FAULT.
-
-``V4L2_CID_FLASH_INDICATOR_INTENSITY (integer)``
- Intensity of the indicator LED. The indicator LED may be fully
- independent of the flash LED. The unit should be microamps (uA) if
- possible.
-
-``V4L2_CID_FLASH_FAULT (bitmask)``
- Faults related to the flash. The faults tell about specific problems
- in the flash chip itself or the LEDs attached to it. Faults may
- prevent further use of some of the flash controls. In particular,
- V4L2_CID_FLASH_LED_MODE is set to V4L2_FLASH_LED_MODE_NONE
- if the fault affects the flash LED. Exactly which faults have such
- an effect is chip dependent. Reading the faults resets the control
- and returns the chip to a usable state if possible.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_FLASH_FAULT_OVER_VOLTAGE``
-
- - Flash controller voltage to the flash LED has exceeded the limit
- specific to the flash controller.
-
- - .. row 2
-
- - ``V4L2_FLASH_FAULT_TIMEOUT``
-
- - The flash strobe was still on when the timeout set by the user ---
- V4L2_CID_FLASH_TIMEOUT control --- has expired. Not all flash
- controllers may set this in all such conditions.
-
- - .. row 3
-
- - ``V4L2_FLASH_FAULT_OVER_TEMPERATURE``
-
- - The flash controller has overheated.
-
- - .. row 4
-
- - ``V4L2_FLASH_FAULT_SHORT_CIRCUIT``
-
- - The short circuit protection of the flash controller has been
- triggered.
-
- - .. row 5
-
- - ``V4L2_FLASH_FAULT_OVER_CURRENT``
-
- - Current in the LED power supply has exceeded the limit specific to
- the flash controller.
-
- - .. row 6
-
- - ``V4L2_FLASH_FAULT_INDICATOR``
-
- - The flash controller has detected a short or open circuit
- condition on the indicator LED.
-
- - .. row 7
-
- - ``V4L2_FLASH_FAULT_UNDER_VOLTAGE``
-
- - Flash controller voltage to the flash LED has been below the
- minimum limit specific to the flash controller.
-
- - .. row 8
-
- - ``V4L2_FLASH_FAULT_INPUT_VOLTAGE``
-
- - The input voltage of the flash controller is below the limit under
- which strobing the flash at full current will not be possible.The
- condition persists until this flag is no longer set.
-
- - .. row 9
-
- - ``V4L2_FLASH_FAULT_LED_OVER_TEMPERATURE``
-
- - The temperature of the LED has exceeded its allowed upper limit.
-
-
-
-``V4L2_CID_FLASH_CHARGE (boolean)``
- Enable or disable charging of the xenon flash capacitor.
-
-``V4L2_CID_FLASH_READY (boolean)``
- Is the flash ready to strobe? Xenon flashes require their capacitors
- charged before strobing. LED flashes often require a cooldown period
- after strobe during which another strobe will not be possible. This
- is a read-only control.
-
-
-.. _jpeg-controls:
-
-JPEG Control Reference
-======================
-
-The JPEG class includes controls for common features of JPEG encoders
-and decoders. Currently it includes features for codecs implementing
-progressive baseline DCT compression process with Huffman entrophy
-coding.
-
-
-.. _jpeg-control-id:
-
-JPEG Control IDs
-----------------
-
-``V4L2_CID_JPEG_CLASS (class)``
- The JPEG class descriptor. Calling
- :ref:`VIDIOC_QUERYCTRL` for this control will
- return a description of this control class.
-
-``V4L2_CID_JPEG_CHROMA_SUBSAMPLING (menu)``
- The chroma subsampling factors describe how each component of an
- input image is sampled, in respect to maximum sample rate in each
- spatial dimension. See :ref:`itu-t81`, clause A.1.1. for more
- details. The ``V4L2_CID_JPEG_CHROMA_SUBSAMPLING`` control determines
- how Cb and Cr components are downsampled after coverting an input
- image from RGB to Y'CbCr color space.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_JPEG_CHROMA_SUBSAMPLING_444``
-
- - No chroma subsampling, each pixel has Y, Cr and Cb values.
-
- - .. row 2
-
- - ``V4L2_JPEG_CHROMA_SUBSAMPLING_422``
-
- - Horizontally subsample Cr, Cb components by a factor of 2.
-
- - .. row 3
-
- - ``V4L2_JPEG_CHROMA_SUBSAMPLING_420``
-
- - Subsample Cr, Cb components horizontally and vertically by 2.
-
- - .. row 4
-
- - ``V4L2_JPEG_CHROMA_SUBSAMPLING_411``
-
- - Horizontally subsample Cr, Cb components by a factor of 4.
-
- - .. row 5
-
- - ``V4L2_JPEG_CHROMA_SUBSAMPLING_410``
-
- - Subsample Cr, Cb components horizontally by 4 and vertically by 2.
-
- - .. row 6
-
- - ``V4L2_JPEG_CHROMA_SUBSAMPLING_GRAY``
-
- - Use only luminance component.
-
-
-
-``V4L2_CID_JPEG_RESTART_INTERVAL (integer)``
- The restart interval determines an interval of inserting RSTm
- markers (m = 0..7). The purpose of these markers is to additionally
- reinitialize the encoder process, in order to process blocks of an
- image independently. For the lossy compression processes the restart
- interval unit is MCU (Minimum Coded Unit) and its value is contained
- in DRI (Define Restart Interval) marker. If
- ``V4L2_CID_JPEG_RESTART_INTERVAL`` control is set to 0, DRI and RSTm
- markers will not be inserted.
-
-.. _jpeg-quality-control:
-
-``V4L2_CID_JPEG_COMPRESSION_QUALITY (integer)``
- ``V4L2_CID_JPEG_COMPRESSION_QUALITY`` control determines trade-off
- between image quality and size. It provides simpler method for
- applications to control image quality, without a need for direct
- reconfiguration of luminance and chrominance quantization tables. In
- cases where a driver uses quantization tables configured directly by
- an application, using interfaces defined elsewhere,
- ``V4L2_CID_JPEG_COMPRESSION_QUALITY`` control should be set by
- driver to 0.
-
- The value range of this control is driver-specific. Only positive,
- non-zero values are meaningful. The recommended range is 1 - 100,
- where larger values correspond to better image quality.
-
-.. _jpeg-active-marker-control:
-
-``V4L2_CID_JPEG_ACTIVE_MARKER (bitmask)``
- Specify which JPEG markers are included in compressed stream. This
- control is valid only for encoders.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_JPEG_ACTIVE_MARKER_APP0``
-
- - Application data segment APP\ :sub:`0`.
-
- - .. row 2
-
- - ``V4L2_JPEG_ACTIVE_MARKER_APP1``
-
- - Application data segment APP\ :sub:`1`.
-
- - .. row 3
-
- - ``V4L2_JPEG_ACTIVE_MARKER_COM``
-
- - Comment segment.
-
- - .. row 4
-
- - ``V4L2_JPEG_ACTIVE_MARKER_DQT``
-
- - Quantization tables segment.
-
- - .. row 5
-
- - ``V4L2_JPEG_ACTIVE_MARKER_DHT``
-
- - Huffman tables segment.
-
-
-
-For more details about JPEG specification, refer to :ref:`itu-t81`,
-:ref:`jfif`, :ref:`w3c-jpeg-jfif`.
-
-
-.. _image-source-controls:
-
-Image Source Control Reference
-==============================
-
-The Image Source control class is intended for low-level control of
-image source devices such as image sensors. The devices feature an
-analogue to digital converter and a bus transmitter to transmit the
-image data out of the device.
-
-
-.. _image-source-control-id:
-
-Image Source Control IDs
-------------------------
-
-``V4L2_CID_IMAGE_SOURCE_CLASS (class)``
- The IMAGE_SOURCE class descriptor.
-
-``V4L2_CID_VBLANK (integer)``
- Vertical blanking. The idle period after every frame during which no
- image data is produced. The unit of vertical blanking is a line.
- Every line has length of the image width plus horizontal blanking at
- the pixel rate defined by ``V4L2_CID_PIXEL_RATE`` control in the
- same sub-device.
-
-``V4L2_CID_HBLANK (integer)``
- Horizontal blanking. The idle period after every line of image data
- during which no image data is produced. The unit of horizontal
- blanking is pixels.
-
-``V4L2_CID_ANALOGUE_GAIN (integer)``
- Analogue gain is gain affecting all colour components in the pixel
- matrix. The gain operation is performed in the analogue domain
- before A/D conversion.
-
-``V4L2_CID_TEST_PATTERN_RED (integer)``
- Test pattern red colour component.
-
-``V4L2_CID_TEST_PATTERN_GREENR (integer)``
- Test pattern green (next to red) colour component.
-
-``V4L2_CID_TEST_PATTERN_BLUE (integer)``
- Test pattern blue colour component.
-
-``V4L2_CID_TEST_PATTERN_GREENB (integer)``
- Test pattern green (next to blue) colour component.
-
-
-.. _image-process-controls:
-
-Image Process Control Reference
-===============================
-
-The Image Process control class is intended for low-level control of
-image processing functions. Unlike ``V4L2_CID_IMAGE_SOURCE_CLASS``, the
-controls in this class affect processing the image, and do not control
-capturing of it.
-
-
-.. _image-process-control-id:
-
-Image Process Control IDs
--------------------------
-
-``V4L2_CID_IMAGE_PROC_CLASS (class)``
- The IMAGE_PROC class descriptor.
-
-``V4L2_CID_LINK_FREQ (integer menu)``
- Data bus frequency. Together with the media bus pixel code, bus type
- (clock cycles per sample), the data bus frequency defines the pixel
- rate (``V4L2_CID_PIXEL_RATE``) in the pixel array (or possibly
- elsewhere, if the device is not an image sensor). The frame rate can
- be calculated from the pixel clock, image width and height and
- horizontal and vertical blanking. While the pixel rate control may
- be defined elsewhere than in the subdev containing the pixel array,
- the frame rate cannot be obtained from that information. This is
- because only on the pixel array it can be assumed that the vertical
- and horizontal blanking information is exact: no other blanking is
- allowed in the pixel array. The selection of frame rate is performed
- by selecting the desired horizontal and vertical blanking. The unit
- of this control is Hz.
-
-``V4L2_CID_PIXEL_RATE (64-bit integer)``
- Pixel rate in the source pads of the subdev. This control is
- read-only and its unit is pixels / second.
-
-``V4L2_CID_TEST_PATTERN (menu)``
- Some capture/display/sensor devices have the capability to generate
- test pattern images. These hardware specific test patterns can be
- used to test if a device is working properly.
-
-
-.. _dv-controls:
-
-Digital Video Control Reference
-===============================
-
-The Digital Video control class is intended to control receivers and
-transmitters for `VGA <http://en.wikipedia.org/wiki/Vga>`__,
-`DVI <http://en.wikipedia.org/wiki/Digital_Visual_Interface>`__
-(Digital Visual Interface), HDMI (:ref:`hdmi`) and DisplayPort
-(:ref:`dp`). These controls are generally expected to be private to
-the receiver or transmitter subdevice that implements them, so they are
-only exposed on the ``/dev/v4l-subdev*`` device node.
-
-Note that these devices can have multiple input or output pads which are
-hooked up to e.g. HDMI connectors. Even though the subdevice will
-receive or transmit video from/to only one of those pads, the other pads
-can still be active when it comes to EDID (Extended Display
-Identification Data, :ref:`vesaedid`) and HDCP (High-bandwidth Digital
-Content Protection System, :ref:`hdcp`) processing, allowing the
-device to do the fairly slow EDID/HDCP handling in advance. This allows
-for quick switching between connectors.
-
-These pads appear in several of the controls in this section as
-bitmasks, one bit for each pad. Bit 0 corresponds to pad 0, bit 1 to pad
-1, etc. The maximum value of the control is the set of valid pads.
-
-
-.. _dv-control-id:
-
-Digital Video Control IDs
--------------------------
-
-``V4L2_CID_DV_CLASS (class)``
- The Digital Video class descriptor.
-
-``V4L2_CID_DV_TX_HOTPLUG (bitmask)``
- Many connectors have a hotplug pin which is high if EDID information
- is available from the source. This control shows the state of the
- hotplug pin as seen by the transmitter. Each bit corresponds to an
- output pad on the transmitter. If an output pad does not have an
- associated hotplug pin, then the bit for that pad will be 0. This
- read-only control is applicable to DVI-D, HDMI and DisplayPort
- connectors.
-
-``V4L2_CID_DV_TX_RXSENSE (bitmask)``
- Rx Sense is the detection of pull-ups on the TMDS clock lines. This
- normally means that the sink has left/entered standby (i.e. the
- transmitter can sense that the receiver is ready to receive video).
- Each bit corresponds to an output pad on the transmitter. If an
- output pad does not have an associated Rx Sense, then the bit for
- that pad will be 0. This read-only control is applicable to DVI-D
- and HDMI devices.
-
-``V4L2_CID_DV_TX_EDID_PRESENT (bitmask)``
- When the transmitter sees the hotplug signal from the receiver it
- will attempt to read the EDID. If set, then the transmitter has read
- at least the first block (= 128 bytes). Each bit corresponds to an
- output pad on the transmitter. If an output pad does not support
- EDIDs, then the bit for that pad will be 0. This read-only control
- is applicable to VGA, DVI-A/D, HDMI and DisplayPort connectors.
-
-``V4L2_CID_DV_TX_MODE (enum v4l2_dv_tx_mode)``
- HDMI transmitters can transmit in DVI-D mode (just video) or in HDMI
- mode (video + audio + auxiliary data). This control selects which
- mode to use: V4L2_DV_TX_MODE_DVI_D or V4L2_DV_TX_MODE_HDMI.
- This control is applicable to HDMI connectors.
-
-``V4L2_CID_DV_TX_RGB_RANGE (enum v4l2_dv_rgb_range)``
- Select the quantization range for RGB output. V4L2_DV_RANGE_AUTO
- follows the RGB quantization range specified in the standard for the
- video interface (ie. :ref:`cea861` for HDMI).
- V4L2_DV_RANGE_LIMITED and V4L2_DV_RANGE_FULL override the
- standard to be compatible with sinks that have not implemented the
- standard correctly (unfortunately quite common for HDMI and DVI-D).
- Full range allows all possible values to be used whereas limited
- range sets the range to (16 << (N-8)) - (235 << (N-8)) where N is
- the number of bits per component. This control is applicable to VGA,
- DVI-A/D, HDMI and DisplayPort connectors.
-
-``V4L2_CID_DV_TX_IT_CONTENT_TYPE (enum v4l2_dv_it_content_type)``
- Configures the IT Content Type of the transmitted video. This
- information is sent over HDMI and DisplayPort connectors as part of
- the AVI InfoFrame. The term 'IT Content' is used for content that
- originates from a computer as opposed to content from a TV broadcast
- or an analog source. The enum v4l2_dv_it_content_type defines
- the possible content types:
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_DV_IT_CONTENT_TYPE_GRAPHICS``
-
- - Graphics content. Pixel data should be passed unfiltered and
- without analog reconstruction.
-
- - .. row 2
-
- - ``V4L2_DV_IT_CONTENT_TYPE_PHOTO``
-
- - Photo content. The content is derived from digital still pictures.
- The content should be passed through with minimal scaling and
- picture enhancements.
-
- - .. row 3
-
- - ``V4L2_DV_IT_CONTENT_TYPE_CINEMA``
-
- - Cinema content.
-
- - .. row 4
-
- - ``V4L2_DV_IT_CONTENT_TYPE_GAME``
-
- - Game content. Audio and video latency should be minimized.
-
- - .. row 5
-
- - ``V4L2_DV_IT_CONTENT_TYPE_NO_ITC``
-
- - No IT Content information is available and the ITC bit in the AVI
- InfoFrame is set to 0.
-
-
-
-``V4L2_CID_DV_RX_POWER_PRESENT (bitmask)``
- Detects whether the receiver receives power from the source (e.g.
- HDMI carries 5V on one of the pins). This is often used to power an
- eeprom which contains EDID information, such that the source can
- read the EDID even if the sink is in standby/power off. Each bit
- corresponds to an input pad on the transmitter. If an input pad
- cannot detect whether power is present, then the bit for that pad
- will be 0. This read-only control is applicable to DVI-D, HDMI and
- DisplayPort connectors.
-
-``V4L2_CID_DV_RX_RGB_RANGE (enum v4l2_dv_rgb_range)``
- Select the quantization range for RGB input. V4L2_DV_RANGE_AUTO
- follows the RGB quantization range specified in the standard for the
- video interface (ie. :ref:`cea861` for HDMI).
- V4L2_DV_RANGE_LIMITED and V4L2_DV_RANGE_FULL override the
- standard to be compatible with sources that have not implemented the
- standard correctly (unfortunately quite common for HDMI and DVI-D).
- Full range allows all possible values to be used whereas limited
- range sets the range to (16 << (N-8)) - (235 << (N-8)) where N is
- the number of bits per component. This control is applicable to VGA,
- DVI-A/D, HDMI and DisplayPort connectors.
-
-``V4L2_CID_DV_RX_IT_CONTENT_TYPE (enum v4l2_dv_it_content_type)``
- Reads the IT Content Type of the received video. This information is
- sent over HDMI and DisplayPort connectors as part of the AVI
- InfoFrame. The term 'IT Content' is used for content that originates
- from a computer as opposed to content from a TV broadcast or an
- analog source. See ``V4L2_CID_DV_TX_IT_CONTENT_TYPE`` for the
- available content types.
-
-
-.. _fm-rx-controls:
-
-FM Receiver Control Reference
-=============================
-
-The FM Receiver (FM_RX) class includes controls for common features of
-FM Reception capable devices.
-
-
-.. _fm-rx-control-id:
-
-FM_RX Control IDs
------------------
-
-``V4L2_CID_FM_RX_CLASS (class)``
- The FM_RX class descriptor. Calling
- :ref:`VIDIOC_QUERYCTRL` for this control will
- return a description of this control class.
-
-``V4L2_CID_RDS_RECEPTION (boolean)``
- Enables/disables RDS reception by the radio tuner
-
-``V4L2_CID_RDS_RX_PTY (integer)``
- Gets RDS Programme Type field. This encodes up to 31 pre-defined
- programme types.
-
-``V4L2_CID_RDS_RX_PS_NAME (string)``
- Gets the Programme Service name (PS_NAME). It is intended for
- static display on a receiver. It is the primary aid to listeners in
- programme service identification and selection. In Annex E of
- :ref:`iec62106`, the RDS specification, there is a full
- description of the correct character encoding for Programme Service
- name strings. Also from RDS specification, PS is usually a single
- eight character text. However, it is also possible to find receivers
- which can scroll strings sized as 8 x N characters. So, this control
- must be configured with steps of 8 characters. The result is it must
- always contain a string with size multiple of 8.
-
-``V4L2_CID_RDS_RX_RADIO_TEXT (string)``
- Gets the Radio Text info. It is a textual description of what is
- being broadcasted. RDS Radio Text can be applied when broadcaster
- wishes to transmit longer PS names, programme-related information or
- any other text. In these cases, RadioText can be used in addition to
- ``V4L2_CID_RDS_RX_PS_NAME``. The encoding for Radio Text strings is
- also fully described in Annex E of :ref:`iec62106`. The length of
- Radio Text strings depends on which RDS Block is being used to
- transmit it, either 32 (2A block) or 64 (2B block). However, it is
- also possible to find receivers which can scroll strings sized as 32
- x N or 64 x N characters. So, this control must be configured with
- steps of 32 or 64 characters. The result is it must always contain a
- string with size multiple of 32 or 64.
-
-``V4L2_CID_RDS_RX_TRAFFIC_ANNOUNCEMENT (boolean)``
- If set, then a traffic announcement is in progress.
-
-``V4L2_CID_RDS_RX_TRAFFIC_PROGRAM (boolean)``
- If set, then the tuned programme carries traffic announcements.
-
-``V4L2_CID_RDS_RX_MUSIC_SPEECH (boolean)``
- If set, then this channel broadcasts music. If cleared, then it
- broadcasts speech. If the transmitter doesn't make this distinction,
- then it will be set.
-
-``V4L2_CID_TUNE_DEEMPHASIS (enum v4l2_deemphasis)``
- Configures the de-emphasis value for reception. A de-emphasis filter
- is applied to the broadcast to accentuate the high audio
- frequencies. Depending on the region, a time constant of either 50
- or 75 useconds is used. The enum v4l2_deemphasis defines possible
- values for de-emphasis. Here they are:
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_DEEMPHASIS_DISABLED``
-
- - No de-emphasis is applied.
-
- - .. row 2
-
- - ``V4L2_DEEMPHASIS_50_uS``
-
- - A de-emphasis of 50 uS is used.
-
- - .. row 3
-
- - ``V4L2_DEEMPHASIS_75_uS``
-
- - A de-emphasis of 75 uS is used.
-
-
-
-
-.. _detect-controls:
-
-Detect Control Reference
-========================
-
-The Detect class includes controls for common features of various motion
-or object detection capable devices.
-
-
-.. _detect-control-id:
-
-Detect Control IDs
-------------------
-
-``V4L2_CID_DETECT_CLASS (class)``
- The Detect class descriptor. Calling
- :ref:`VIDIOC_QUERYCTRL` for this control will
- return a description of this control class.
-
-``V4L2_CID_DETECT_MD_MODE (menu)``
- Sets the motion detection mode.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - ``V4L2_DETECT_MD_MODE_DISABLED``
-
- - Disable motion detection.
-
- - .. row 2
-
- - ``V4L2_DETECT_MD_MODE_GLOBAL``
-
- - Use a single motion detection threshold.
-
- - .. row 3
-
- - ``V4L2_DETECT_MD_MODE_THRESHOLD_GRID``
-
- - The image is divided into a grid, each cell with its own motion
- detection threshold. These thresholds are set through the
- ``V4L2_CID_DETECT_MD_THRESHOLD_GRID`` matrix control.
-
- - .. row 4
-
- - ``V4L2_DETECT_MD_MODE_REGION_GRID``
-
- - The image is divided into a grid, each cell with its own region
- value that specifies which per-region motion detection thresholds
- should be used. Each region has its own thresholds. How these
- per-region thresholds are set up is driver-specific. The region
- values for the grid are set through the
- ``V4L2_CID_DETECT_MD_REGION_GRID`` matrix control.
-
-
-
-``V4L2_CID_DETECT_MD_GLOBAL_THRESHOLD (integer)``
- Sets the global motion detection threshold to be used with the
- ``V4L2_DETECT_MD_MODE_GLOBAL`` motion detection mode.
-
-``V4L2_CID_DETECT_MD_THRESHOLD_GRID (__u16 matrix)``
- Sets the motion detection thresholds for each cell in the grid. To
- be used with the ``V4L2_DETECT_MD_MODE_THRESHOLD_GRID`` motion
- detection mode. Matrix element (0, 0) represents the cell at the
- top-left of the grid.
-
-``V4L2_CID_DETECT_MD_REGION_GRID (__u8 matrix)``
- Sets the motion detection region value for each cell in the grid. To
- be used with the ``V4L2_DETECT_MD_MODE_REGION_GRID`` motion
- detection mode. Matrix element (0, 0) represents the cell at the
- top-left of the grid.
-
-
-.. _rf-tuner-controls:
-
-RF Tuner Control Reference
-==========================
-
-The RF Tuner (RF_TUNER) class includes controls for common features of
-devices having RF tuner.
-
-In this context, RF tuner is radio receiver circuit between antenna and
-demodulator. It receives radio frequency (RF) from the antenna and
-converts that received signal to lower intermediate frequency (IF) or
-baseband frequency (BB). Tuners that could do baseband output are often
-called Zero-IF tuners. Older tuners were typically simple PLL tuners
-inside a metal box, whilst newer ones are highly integrated chips
-without a metal box "silicon tuners". These controls are mostly
-applicable for new feature rich silicon tuners, just because older
-tuners does not have much adjustable features.
-
-For more information about RF tuners see
-`Tuner (radio) <http://en.wikipedia.org/wiki/Tuner_%28radio%29>`__
-and `RF front end <http://en.wikipedia.org/wiki/RF_front_end>`__
-from Wikipedia.
-
-
-.. _rf-tuner-control-id:
-
-RF_TUNER Control IDs
---------------------
-
-``V4L2_CID_RF_TUNER_CLASS (class)``
- The RF_TUNER class descriptor. Calling
- :ref:`VIDIOC_QUERYCTRL` for this control will
- return a description of this control class.
-
-``V4L2_CID_RF_TUNER_BANDWIDTH_AUTO (boolean)``
- Enables/disables tuner radio channel bandwidth configuration. In
- automatic mode bandwidth configuration is performed by the driver.
-
-``V4L2_CID_RF_TUNER_BANDWIDTH (integer)``
- Filter(s) on tuner signal path are used to filter signal according
- to receiving party needs. Driver configures filters to fulfill
- desired bandwidth requirement. Used when
- V4L2_CID_RF_TUNER_BANDWIDTH_AUTO is not set. Unit is in Hz. The
- range and step are driver-specific.
-
-``V4L2_CID_RF_TUNER_LNA_GAIN_AUTO (boolean)``
- Enables/disables LNA automatic gain control (AGC)
-
-``V4L2_CID_RF_TUNER_MIXER_GAIN_AUTO (boolean)``
- Enables/disables mixer automatic gain control (AGC)
-
-``V4L2_CID_RF_TUNER_IF_GAIN_AUTO (boolean)``
- Enables/disables IF automatic gain control (AGC)
-
-``V4L2_CID_RF_TUNER_RF_GAIN (integer)``
- The RF amplifier is the very first amplifier on the receiver signal
- path, just right after the antenna input. The difference between the
- LNA gain and the RF gain in this document is that the LNA gain is
- integrated in the tuner chip while the RF gain is a separate chip.
- There may be both RF and LNA gain controls in the same device. The
- range and step are driver-specific.
-
-``V4L2_CID_RF_TUNER_LNA_GAIN (integer)``
- LNA (low noise amplifier) gain is first gain stage on the RF tuner
- signal path. It is located very close to tuner antenna input. Used
- when ``V4L2_CID_RF_TUNER_LNA_GAIN_AUTO`` is not set. See
- ``V4L2_CID_RF_TUNER_RF_GAIN`` to understand how RF gain and LNA gain
- differs from the each others. The range and step are
- driver-specific.
-
-``V4L2_CID_RF_TUNER_MIXER_GAIN (integer)``
- Mixer gain is second gain stage on the RF tuner signal path. It is
- located inside mixer block, where RF signal is down-converted by the
- mixer. Used when ``V4L2_CID_RF_TUNER_MIXER_GAIN_AUTO`` is not set.
- The range and step are driver-specific.
-
-``V4L2_CID_RF_TUNER_IF_GAIN (integer)``
- IF gain is last gain stage on the RF tuner signal path. It is
- located on output of RF tuner. It controls signal level of
- intermediate frequency output or baseband output. Used when
- ``V4L2_CID_RF_TUNER_IF_GAIN_AUTO`` is not set. The range and step
- are driver-specific.
-
-``V4L2_CID_RF_TUNER_PLL_LOCK (boolean)``
- Is synthesizer PLL locked? RF tuner is receiving given frequency
- when that control is set. This is a read-only control.
-
-.. [1]
- This control may be changed to a menu control in the future, if more
- options are required.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _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.
-
-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
-:ref:`v4l2_pix_format <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).
-
-
-.. _v4l2-field:
-
-enum v4l2_field
-===============
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - ``V4L2_FIELD_ANY``
-
- - 0
-
- - Applications request this field order when any one of the
- ``V4L2_FIELD_NONE``, ``V4L2_FIELD_TOP``, ``V4L2_FIELD_BOTTOM``, or
- ``V4L2_FIELD_INTERLACED`` formats 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
- :ref:`v4l2_buffer <v4l2-buffer>` ``field`` can never be
- ``V4L2_FIELD_ANY``.
-
- - .. row 2
-
- - ``V4L2_FIELD_NONE``
-
- - 1
-
- - Images are in progressive format, not interlaced. The driver may
- also indicate this order when it cannot distinguish between
- ``V4L2_FIELD_TOP`` and ``V4L2_FIELD_BOTTOM``.
-
- - .. row 3
-
- - ``V4L2_FIELD_TOP``
-
- - 2
-
- - Images consist of the top (aka odd) field only.
-
- - .. row 4
-
- - ``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.
-
- - .. row 5
-
- - ``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 first
- transmitted) depends on the current video standard. M/NTSC
- transmits the bottom field first, all other standards the top
- field first.
-
- - .. row 6
-
- - ``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.
-
- - .. row 7
-
- - ``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.
-
- - .. row 8
-
- - ``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 :ref:`v4l2_buffer <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
- :ref:`v4l2_buffer <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.
-
- - .. row 9
-
- - ``V4L2_FIELD_INTERLACED_TB``
-
- - 8
-
- - Images contain both fields, interleaved line by line, top field
- first. The top field is transmitted first.
-
- - .. row 10
-
- - ``V4L2_FIELD_INTERLACED_BT``
-
- - 9
-
- - Images contain both fields, interleaved line by line, top field
- first. The bottom field is transmitted first.
-
-
-
-.. _fieldseq-tb:
-
-Field Order, Top Field First Transmitted
-========================================
-
-.. figure:: field-order_files/fieldseq_tb.*
- :alt: fieldseq_tb.pdf / fieldseq_tb.gif
- :align: center
-
-
-.. _fieldseq-bt:
-
-Field Order, Bottom Field First Transmitted
-===========================================
-
-.. figure:: field-order_files/fieldseq_bt.*
- :alt: fieldseq_bt.pdf / fieldseq_bt.gif
- :align: center
-
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _format:
-
-************
-Data Formats
-************
-
-
-Data Format Negotiation
-=======================
-
-Different devices exchange different kinds of data with applications,
-for example video images, raw or sliced VBI data, RDS datagrams. Even
-within one kind many different formats are possible, in particular an
-abundance of image formats. Although drivers must provide a default and
-the selection persists across closing and reopening a device,
-applications should always negotiate a data format before engaging in
-data exchange. Negotiation means the application asks for a particular
-format and the driver selects and reports the best the hardware can do
-to satisfy the request. Of course applications can also just query the
-current selection.
-
-A single mechanism exists to negotiate all data formats using the
-aggregate struct :ref:`v4l2_format <v4l2-format>` and the
-:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
-:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls. Additionally the
-:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl can be used to examine
-what the hardware *could* do, without actually selecting a new data
-format. The data formats supported by the V4L2 API are covered in the
-respective device section in :ref:`devices`. For a closer look at
-image formats see :ref:`pixfmt`.
-
-The :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl is a major turning-point in the
-initialization sequence. Prior to this point multiple panel applications
-can access the same device concurrently to select the current input,
-change controls or modify other properties. The first :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
-assigns a logical stream (video data, VBI data etc.) exclusively to one
-file descriptor.
-
-Exclusive means no other application, more precisely no other file
-descriptor, can grab this stream or change device properties
-inconsistent with the negotiated parameters. A video standard change for
-example, when the new standard uses a different number of scan lines,
-can invalidate the selected image format. Therefore only the file
-descriptor owning the stream can make invalidating changes. Accordingly
-multiple file descriptors which grabbed different logical streams
-prevent each other from interfering with their settings. When for
-example video overlay is about to start or already in progress,
-simultaneous video capturing may be restricted to the same cropping and
-image size.
-
-When applications omit the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl its locking side
-effects are implied by the next step, the selection of an I/O method
-with the :ref:`VIDIOC_REQBUFS` ioctl or implicit
-with the first :ref:`read() <func-read>` or
-:ref:`write() <func-write>` call.
-
-Generally only one logical stream can be assigned to a file descriptor,
-the exception being drivers permitting simultaneous video capturing and
-overlay using the same file descriptor for compatibility with V4L and
-earlier versions of V4L2. Switching the logical stream or returning into
-"panel mode" is possible by closing and reopening the device. Drivers
-*may* support a switch using :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`.
-
-All drivers exchanging data with applications must support the
-:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. Implementation of the
-:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is highly recommended but optional.
-
-
-Image Format Enumeration
-========================
-
-Apart of the generic format negotiation functions a special ioctl to
-enumerate all image formats supported by video capture, overlay or
-output devices is available. [1]_
-
-The :ref:`VIDIOC_ENUM_FMT` ioctl must be supported
-by all drivers exchanging image data with applications.
-
- **Important**
-
- Drivers are not supposed to convert image formats in kernel space.
- They must enumerate only formats directly supported by the hardware.
- If necessary driver writers should publish an example conversion
- routine or library for integration into applications.
-
-.. [1]
- Enumerating formats an application has no a-priori knowledge of
- (otherwise it could explicitly ask for them and need not enumerate)
- seems useless, but there are applications serving as proxy between
- drivers and the actual video applications for which this is useful.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _func-close:
-
-************
-V4L2 close()
-************
-
-Name
-====
-
-v4l2-close - Close a V4L2 device
-
-
-Synopsis
-========
-
-.. code-block:: c
-
- #include <unistd.h>
-
-
-.. cpp:function:: int close( int fd )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-
-Description
-===========
-
-Closes the device. Any I/O in progress is terminated and resources
-associated with the file descriptor are freed. However data format
-parameters, current input or output, control values or other properties
-remain unchanged.
-
-
-Return Value
-============
-
-The function returns 0 on success, -1 on failure and the ``errno`` is
-set appropriately. Possible error codes:
-
-EBADF
- ``fd`` is not a valid open file descriptor.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _func-ioctl:
-
-************
-V4L2 ioctl()
-************
-
-Name
-====
-
-v4l2-ioctl - Program a V4L2 device
-
-
-Synopsis
-========
-
-.. code-block:: c
-
- #include <sys/ioctl.h>
-
-
-.. cpp:function:: int ioctl( int fd, int request, void *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- V4L2 ioctl request code as defined in the ``videodev2.h`` header
- file, for example VIDIOC_QUERYCAP.
-
-``argp``
- Pointer to a function parameter, usually a structure.
-
-
-Description
-===========
-
-The :ref:`ioctl() <func-ioctl>` function is used to program V4L2 devices. The
-argument ``fd`` must be an open file descriptor. An ioctl ``request``
-has encoded in it whether the argument is an input, output or read/write
-parameter, and the size of the argument ``argp`` in bytes. Macros and
-defines specifying V4L2 ioctl requests are located in the
-``videodev2.h`` header file. Applications should use their own copy, not
-include the version in the kernel sources on the system they compile on.
-All V4L2 ioctl requests, their respective function and parameters are
-specified in :ref:`user-func`.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-When an ioctl that takes an output or read/write parameter fails, the
-parameter remains unmodified.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _func-mmap:
-
-***********
-V4L2 mmap()
-***********
-
-Name
-====
-
-v4l2-mmap - Map device memory into application address space
-
-
-Synopsis
-========
-
-.. code-block:: c
-
- #include <unistd.h>
- #include <sys/mman.h>
-
-
-.. cpp:function:: void *mmap( void *start, size_t length, int prot, int flags, int fd, off_t offset )
-
-
-Arguments
-=========
-
-``start``
- Map the buffer to this address in the application's address space.
- When the ``MAP_FIXED`` flag is specified, ``start`` must be a
- multiple of the pagesize and mmap will fail when the specified
- address cannot be used. Use of this option is discouraged;
- applications should just specify a ``NULL`` pointer here.
-
-``length``
- Length of the memory area to map. This must be the same value as
- returned by the driver in the struct
- :ref:`v4l2_buffer <v4l2-buffer>` ``length`` field for the
- single-planar API, and the same value as returned by the driver in
- the struct :ref:`v4l2_plane <v4l2-plane>` ``length`` field for
- the multi-planar API.
-
-``prot``
- The ``prot`` argument describes the desired memory protection.
- Regardless of the device type and the direction of data exchange it
- should be set to ``PROT_READ`` | ``PROT_WRITE``, permitting read
- and write access to image buffers. Drivers should support at least
- this combination of flags. Note the Linux ``video-buf`` kernel
- module, which is used by the bttv, saa7134, saa7146, cx88 and vivi
- driver supports only ``PROT_READ`` | ``PROT_WRITE``. When the
- driver does not support the desired protection the
- :ref:`mmap() <func-mmap>` function fails.
-
- Note device memory accesses (e. g. the memory on a graphics card
- with video capturing hardware) may incur a performance penalty
- compared to main memory accesses, or reads may be significantly
- slower than writes or vice versa. Other I/O methods may be more
- efficient in this case.
-
-``flags``
- The ``flags`` parameter specifies the type of the mapped object,
- mapping options and whether modifications made to the mapped copy of
- the page are private to the process or are to be shared with other
- references.
-
- ``MAP_FIXED`` requests that the driver selects no other address than
- the one specified. If the specified address cannot be used,
- :ref:`mmap() <func-mmap>` will fail. If ``MAP_FIXED`` is specified,
- ``start`` must be a multiple of the pagesize. Use of this option is
- discouraged.
-
- One of the ``MAP_SHARED`` or ``MAP_PRIVATE`` flags must be set.
- ``MAP_SHARED`` allows applications to share the mapped memory with
- other (e. g. child-) processes. Note the Linux ``video-buf`` module
- which is used by the bttv, saa7134, saa7146, cx88 and vivi driver
- supports only ``MAP_SHARED``. ``MAP_PRIVATE`` requests copy-on-write
- semantics. V4L2 applications should not set the ``MAP_PRIVATE``,
- ``MAP_DENYWRITE``, ``MAP_EXECUTABLE`` or ``MAP_ANON`` flag.
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``offset``
- Offset of the buffer in device memory. This must be the same value
- as returned by the driver in the struct
- :ref:`v4l2_buffer <v4l2-buffer>` ``m`` union ``offset`` field for
- the single-planar API, and the same value as returned by the driver
- in the struct :ref:`v4l2_plane <v4l2-plane>` ``m`` union
- ``mem_offset`` field for the multi-planar API.
-
-
-Description
-===========
-
-The :ref:`mmap() <func-mmap>` function asks to map ``length`` bytes starting at
-``offset`` in the memory of the device specified by ``fd`` into the
-application address space, preferably at address ``start``. This latter
-address is a hint only, and is usually specified as 0.
-
-Suitable length and offset parameters are queried with the
-:ref:`VIDIOC_QUERYBUF` ioctl. Buffers must be
-allocated with the :ref:`VIDIOC_REQBUFS` ioctl
-before they can be queried.
-
-To unmap buffers the :ref:`munmap() <func-munmap>` function is used.
-
-
-Return Value
-============
-
-On success :ref:`mmap() <func-mmap>` returns a pointer to the mapped buffer. On
-error ``MAP_FAILED`` (-1) is returned, and the ``errno`` variable is set
-appropriately. Possible error codes are:
-
-EBADF
- ``fd`` is not a valid file descriptor.
-
-EACCES
- ``fd`` is not open for reading and writing.
-
-EINVAL
- The ``start`` or ``length`` or ``offset`` are not suitable. (E. g.
- they are too large, or not aligned on a ``PAGESIZE`` boundary.)
-
- The ``flags`` or ``prot`` value is not supported.
-
- No buffers have been allocated with the
- :ref:`VIDIOC_REQBUFS` ioctl.
-
-ENOMEM
- Not enough physical or virtual memory was available to complete the
- request.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _func-munmap:
-
-*************
-V4L2 munmap()
-*************
-
-Name
-====
-
-v4l2-munmap - Unmap device memory
-
-
-Synopsis
-========
-
-.. code-block:: c
-
- #include <unistd.h>
- #include <sys/mman.h>
-
-
-.. cpp:function:: int munmap( void *start, size_t length )
-
-
-Arguments
-=========
-
-``start``
- Address of the mapped buffer as returned by the
- :ref:`mmap() <func-mmap>` function.
-
-``length``
- Length of the mapped buffer. This must be the same value as given to
- :ref:`mmap() <func-mmap>` and returned by the driver in the struct
- :ref:`v4l2_buffer <v4l2-buffer>` ``length`` field for the
- single-planar API and in the struct
- :ref:`v4l2_plane <v4l2-plane>` ``length`` field for the
- multi-planar API.
-
-
-Description
-===========
-
-Unmaps a previously with the :ref:`mmap() <func-mmap>` function mapped
-buffer and frees it, if possible.
-
-
-Return Value
-============
-
-On success :ref:`munmap() <func-munmap>` returns 0, on failure -1 and the
-``errno`` variable is set appropriately:
-
-EINVAL
- The ``start`` or ``length`` is incorrect, or no buffers have been
- mapped yet.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _func-open:
-
-***********
-V4L2 open()
-***********
-
-Name
-====
-
-v4l2-open - Open a V4L2 device
-
-
-Synopsis
-========
-
-.. code-block:: c
-
- #include <fcntl.h>
-
-
-.. cpp:function:: int open( const char *device_name, int flags )
-
-
-Arguments
-=========
-
-``device_name``
- Device to be opened.
-
-``flags``
- Open flags. Access mode must be ``O_RDWR``. This is just a
- technicality, input devices still support only reading and output
- devices only writing.
-
- When the ``O_NONBLOCK`` flag is given, the :ref:`read() <func-read>`
- function and the :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will
- return the ``EAGAIN`` error code when no data is available or no
- buffer is in the driver outgoing queue, otherwise these functions
- block until data becomes available. All V4L2 drivers exchanging data
- with applications must support the ``O_NONBLOCK`` flag.
-
- Other flags have no effect.
-
-
-Description
-===========
-
-To open a V4L2 device applications call :ref:`open() <func-open>` with the
-desired device name. This function has no side effects; all data format
-parameters, current input or output, control values or other properties
-remain unchanged. At the first :ref:`open() <func-open>` call after loading the
-driver they will be reset to default values, drivers are never in an
-undefined state.
-
-
-Return Value
-============
-
-On success :ref:`open() <func-open>` returns the new file descriptor. On error
--1 is returned, and the ``errno`` variable is set appropriately.
-Possible error codes are:
-
-EACCES
- The caller has no permission to access the device.
-
-EBUSY
- The driver does not support multiple opens and the device is already
- in use.
-
-ENXIO
- No device corresponding to this device special file exists.
-
-ENOMEM
- Not enough kernel memory was available to complete the request.
-
-EMFILE
- The process already has the maximum number of files open.
-
-ENFILE
- The limit on the total number of files open on the system has been
- reached.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _func-poll:
-
-***********
-V4L2 poll()
-***********
-
-Name
-====
-
-v4l2-poll - Wait for some event on a file descriptor
-
-
-Synopsis
-========
-
-.. code-block:: c
-
- #include <sys/poll.h>
-
-
-.. cpp:function:: int poll( struct pollfd *ufds, unsigned int nfds, int timeout )
-
-
-Arguments
-=========
-
-
-
-Description
-===========
-
-With the :ref:`poll() <func-poll>` function applications can suspend execution
-until the driver has captured data or is ready to accept data for
-output.
-
-When streaming I/O has been negotiated this function waits until a
-buffer has been filled by the capture device and can be dequeued with
-the :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. For output devices this
-function waits until the device is ready to accept a new buffer to be
-queued up with the :ref:`VIDIOC_QBUF` ioctl for
-display. When buffers are already in the outgoing queue of the driver
-(capture) or the incoming queue isn't full (display) the function
-returns immediately.
-
-On success :ref:`poll() <func-poll>` returns the number of file descriptors
-that have been selected (that is, file descriptors for which the
-``revents`` field of the respective :c:func:`struct pollfd` structure
-is non-zero). Capture devices set the ``POLLIN`` and ``POLLRDNORM``
-flags in the ``revents`` field, output devices the ``POLLOUT`` and
-``POLLWRNORM`` flags. When the function timed out it returns a value of
-zero, on failure it returns -1 and the ``errno`` variable is set
-appropriately. When the application did not call
-:ref:`VIDIOC_STREAMON` the :ref:`poll() <func-poll>`
-function succeeds, but sets the ``POLLERR`` flag in the ``revents``
-field. When the application has called
-:ref:`VIDIOC_STREAMON` for a capture device but
-hasn't yet called :ref:`VIDIOC_QBUF`, the
-:ref:`poll() <func-poll>` function succeeds and sets the ``POLLERR`` flag in
-the ``revents`` field. For output devices this same situation will cause
-:ref:`poll() <func-poll>` to succeed as well, but it sets the ``POLLOUT`` and
-``POLLWRNORM`` flags in the ``revents`` field.
-
-If an event occurred (see :ref:`VIDIOC_DQEVENT`)
-then ``POLLPRI`` will be set in the ``revents`` field and
-:ref:`poll() <func-poll>` will return.
-
-When use of the :ref:`read() <func-read>` function has been negotiated and the
-driver does not capture yet, the :ref:`poll() <func-poll>` function starts
-capturing. When that fails it returns a ``POLLERR`` as above. Otherwise
-it waits until data has been captured and can be read. When the driver
-captures continuously (as opposed to, for example, still images) the
-function may return immediately.
-
-When use of the :ref:`write() <func-write>` function has been negotiated and the
-driver does not stream yet, the :ref:`poll() <func-poll>` function starts
-streaming. When that fails it returns a ``POLLERR`` as above. Otherwise
-it waits until the driver is ready for a non-blocking
-:ref:`write() <func-write>` call.
-
-If the caller is only interested in events (just ``POLLPRI`` is set in
-the ``events`` field), then :ref:`poll() <func-poll>` will *not* start
-streaming if the driver does not stream yet. This makes it possible to
-just poll for events and not for buffers.
-
-All drivers implementing the :ref:`read() <func-read>` or :ref:`write() <func-write>`
-function or streaming I/O must also support the :ref:`poll() <func-poll>`
-function.
-
-For more details see the :ref:`poll() <func-poll>` manual page.
-
-
-Return Value
-============
-
-On success, :ref:`poll() <func-poll>` returns the number structures which have
-non-zero ``revents`` fields, or zero if the call timed out. On error -1
-is returned, and the ``errno`` variable is set appropriately:
-
-EBADF
- One or more of the ``ufds`` members specify an invalid file
- descriptor.
-
-EBUSY
- The driver does not support multiple read or write streams and the
- device is already in use.
-
-EFAULT
- ``ufds`` references an inaccessible memory area.
-
-EINTR
- The call was interrupted by a signal.
-
-EINVAL
- The ``nfds`` argument is greater than ``OPEN_MAX``.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _func-read:
-
-***********
-V4L2 read()
-***********
-
-Name
-====
-
-v4l2-read - Read from a V4L2 device
-
-
-Synopsis
-========
-
-.. code-block:: c
-
- #include <unistd.h>
-
-
-.. cpp:function:: ssize_t read( int fd, void *buf, size_t count )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``buf``
-``count``
-
-
-Description
-===========
-
-:ref:`read() <func-read>` attempts to read up to ``count`` bytes from file
-descriptor ``fd`` into the buffer starting at ``buf``. The layout of the
-data in the buffer is discussed in the respective device interface
-section, see ##. If ``count`` is zero, :ref:`read() <func-read>` returns zero
-and has no other results. If ``count`` is greater than ``SSIZE_MAX``,
-the result is unspecified. Regardless of the ``count`` value each
-:ref:`read() <func-read>` call will provide at most one frame (two fields)
-worth of data.
-
-By default :ref:`read() <func-read>` blocks until data becomes available. When
-the ``O_NONBLOCK`` flag was given to the :ref:`open() <func-open>`
-function it returns immediately with an ``EAGAIN`` error code when no data
-is available. The :ref:`select() <func-select>` or
-:ref:`poll() <func-poll>` functions can always be used to suspend
-execution until data becomes available. All drivers supporting the
-:ref:`read() <func-read>` function must also support :ref:`select() <func-select>` and
-:ref:`poll() <func-poll>`.
-
-Drivers can implement read functionality in different ways, using a
-single or multiple buffers and discarding the oldest or newest frames
-once the internal buffers are filled.
-
-:ref:`read() <func-read>` never returns a "snapshot" of a buffer being filled.
-Using a single buffer the driver will stop capturing when the
-application starts reading the buffer until the read is finished. Thus
-only the period of the vertical blanking interval is available for
-reading, or the capture rate must fall below the nominal frame rate of
-the video standard.
-
-The behavior of :ref:`read() <func-read>` when called during the active picture
-period or the vertical blanking separating the top and bottom field
-depends on the discarding policy. A driver discarding the oldest frames
-keeps capturing into an internal buffer, continuously overwriting the
-previously, not read frame, and returns the frame being received at the
-time of the :ref:`read() <func-read>` call as soon as it is complete.
-
-A driver discarding the newest frames stops capturing until the next
-:ref:`read() <func-read>` call. The frame being received at :ref:`read() <func-read>`
-time is discarded, returning the following frame instead. Again this
-implies a reduction of the capture rate to one half or less of the
-nominal frame rate. An example of this model is the video read mode of
-the bttv driver, initiating a DMA to user memory when :ref:`read() <func-read>`
-is called and returning when the DMA finished.
-
-In the multiple buffer model drivers maintain a ring of internal
-buffers, automatically advancing to the next free buffer. This allows
-continuous capturing when the application can empty the buffers fast
-enough. Again, the behavior when the driver runs out of free buffers
-depends on the discarding policy.
-
-Applications can get and set the number of buffers used internally by
-the driver with the :ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and
-:ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` ioctls. They are optional,
-however. The discarding policy is not reported and cannot be changed.
-For minimum requirements see :ref:`devices`.
-
-
-Return Value
-============
-
-On success, the number of bytes read is returned. It is not an error if
-this number is smaller than the number of bytes requested, or the amount
-of data required for one frame. This may happen for example because
-:ref:`read() <func-read>` was interrupted by a signal. On error, -1 is
-returned, and the ``errno`` variable is set appropriately. In this case
-the next read will start at the beginning of a new frame. Possible error
-codes are:
-
-EAGAIN
- Non-blocking I/O has been selected using O_NONBLOCK and no data was
- immediately available for reading.
-
-EBADF
- ``fd`` is not a valid file descriptor or is not open for reading, or
- the process already has the maximum number of files open.
-
-EBUSY
- The driver does not support multiple read streams and the device is
- already in use.
-
-EFAULT
- ``buf`` references an inaccessible memory area.
-
-EINTR
- The call was interrupted by a signal before any data was read.
-
-EIO
- I/O error. This indicates some hardware problem or a failure to
- communicate with a remote device (USB camera etc.).
-
-EINVAL
- The :ref:`read() <func-read>` function is not supported by this driver, not
- on this device, or generally not on this type of device.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _func-select:
-
-*************
-V4L2 select()
-*************
-
-Name
-====
-
-v4l2-select - Synchronous I/O multiplexing
-
-
-Synopsis
-========
-
-.. code-block:: c
-
- #include <sys/time.h>
- #include <sys/types.h>
- #include <unistd.h>
-
-
-.. cpp:function:: int select( int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout )
-
-
-Arguments
-=========
-
-
-
-Description
-===========
-
-With the :ref:`select() <func-select>` function applications can suspend
-execution until the driver has captured data or is ready to accept data
-for output.
-
-When streaming I/O has been negotiated this function waits until a
-buffer has been filled or displayed and can be dequeued with the
-:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. When buffers are already in
-the outgoing queue of the driver the function returns immediately.
-
-On success :ref:`select() <func-select>` returns the total number of bits set in
-:c:func:`struct fd_set`. When the function timed out it returns
-a value of zero. On failure it returns -1 and the ``errno`` variable is
-set appropriately. When the application did not call
-:ref:`VIDIOC_QBUF` or
-:ref:`VIDIOC_STREAMON` yet the :ref:`select() <func-select>`
-function succeeds, setting the bit of the file descriptor in ``readfds``
-or ``writefds``, but subsequent :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`
-calls will fail. [1]_
-
-When use of the :ref:`read() <func-read>` function has been negotiated and the
-driver does not capture yet, the :ref:`select() <func-select>` function starts
-capturing. When that fails, :ref:`select() <func-select>` returns successful and
-a subsequent :ref:`read() <func-read>` call, which also attempts to start
-capturing, will return an appropriate error code. When the driver
-captures continuously (as opposed to, for example, still images) and
-data is already available the :ref:`select() <func-select>` function returns
-immediately.
-
-When use of the :ref:`write() <func-write>` function has been negotiated the
-:ref:`select() <func-select>` function just waits until the driver is ready for a
-non-blocking :ref:`write() <func-write>` call.
-
-All drivers implementing the :ref:`read() <func-read>` or :ref:`write() <func-write>`
-function or streaming I/O must also support the :ref:`select() <func-select>`
-function.
-
-For more details see the :ref:`select() <func-select>` manual page.
-
-
-Return Value
-============
-
-On success, :ref:`select() <func-select>` returns the number of descriptors
-contained in the three returned descriptor sets, which will be zero if
-the timeout expired. On error -1 is returned, and the ``errno`` variable
-is set appropriately; the sets and ``timeout`` are undefined. Possible
-error codes are:
-
-EBADF
- One or more of the file descriptor sets specified a file descriptor
- that is not open.
-
-EBUSY
- The driver does not support multiple read or write streams and the
- device is already in use.
-
-EFAULT
- The ``readfds``, ``writefds``, ``exceptfds`` or ``timeout`` pointer
- references an inaccessible memory area.
-
-EINTR
- The call was interrupted by a signal.
-
-EINVAL
- The ``nfds`` argument is less than zero or greater than
- ``FD_SETSIZE``.
-
-.. [1]
- The Linux kernel implements :ref:`select() <func-select>` like the
- :ref:`poll() <func-poll>` function, but :ref:`select() <func-select>` cannot
- return a ``POLLERR``.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _func-write:
-
-************
-V4L2 write()
-************
-
-Name
-====
-
-v4l2-write - Write to a V4L2 device
-
-
-Synopsis
-========
-
-.. code-block:: c
-
- #include <unistd.h>
-
-
-.. cpp:function:: ssize_t write( int fd, void *buf, size_t count )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``buf``
-``count``
-
-
-Description
-===========
-
-:ref:`write() <func-write>` writes up to ``count`` bytes to the device
-referenced by the file descriptor ``fd`` from the buffer starting at
-``buf``. When the hardware outputs are not active yet, this function
-enables them. When ``count`` is zero, :ref:`write() <func-write>` returns 0
-without any other effect.
-
-When the application does not provide more data in time, the previous
-video frame, raw VBI image, sliced VPS or WSS data is displayed again.
-Sliced Teletext or Closed Caption data is not repeated, the driver
-inserts a blank line instead.
-
-
-Return Value
-============
-
-On success, the number of bytes written are returned. Zero indicates
-nothing was written. On error, -1 is returned, and the ``errno``
-variable is set appropriately. In this case the next write will start at
-the beginning of a new frame. Possible error codes are:
-
-EAGAIN
- Non-blocking I/O has been selected using the
- :ref:`O_NONBLOCK <func-open>` flag and no buffer space was
- available to write the data immediately.
-
-EBADF
- ``fd`` is not a valid file descriptor or is not open for writing.
-
-EBUSY
- The driver does not support multiple write streams and the device is
- already in use.
-
-EFAULT
- ``buf`` references an inaccessible memory area.
-
-EINTR
- The call was interrupted by a signal before any data was written.
-
-EIO
- I/O error. This indicates some hardware problem.
-
-EINVAL
- The :ref:`write() <func-write>` function is not supported by this driver,
- not on this device, or generally not on this type of device.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _hist-v4l2:
-
-***********************
-Changes of the V4L2 API
-***********************
-
-Soon after the V4L API was added to the kernel it was criticised as too
-inflexible. In August 1998 Bill Dirks proposed a number of improvements
-and began to work on documentation, example drivers and applications.
-With the help of other volunteers this eventually became the V4L2 API,
-not just an extension but a replacement for the V4L API. However it took
-another four years and two stable kernel releases until the new API was
-finally accepted for inclusion into the kernel in its present form.
-
-
-Early Versions
-==============
-
-1998-08-20: First version.
-
-1998-08-27: The :ref:`select() <func-select>` function was introduced.
-
-1998-09-10: New video standard interface.
-
-1998-09-18: The ``VIDIOC_NONCAP`` ioctl was replaced by the otherwise
-meaningless ``O_TRUNC`` :ref:`open() <func-open>` flag, and the
-aliases ``O_NONCAP`` and ``O_NOIO`` were defined. Applications can set
-this flag if they intend to access controls only, as opposed to capture
-applications which need exclusive access. The ``VIDEO_STD_XXX``
-identifiers are now ordinals instead of flags, and the
-:c:func:`video_std_construct()` helper function takes id and
-transmission arguments.
-
-1998-09-28: Revamped video standard. Made video controls individually
-enumerable.
-
-1998-10-02: The ``id`` field was removed from struct
-:c:type:`struct video_standard` and the color subcarrier fields were
-renamed. The :ref:`VIDIOC_QUERYSTD` ioctl was
-renamed to :ref:`VIDIOC_ENUMSTD`,
-:ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` to
-:ref:`VIDIOC_ENUMINPUT`. A first draft of the
-Codec API was released.
-
-1998-11-08: Many minor changes. Most symbols have been renamed. Some
-material changes to struct :ref:`v4l2_capability <v4l2-capability>`.
-
-1998-11-12: The read/write directon of some ioctls was misdefined.
-
-1998-11-14: ``V4L2_PIX_FMT_RGB24`` changed to ``V4L2_PIX_FMT_BGR24``,
-and ``V4L2_PIX_FMT_RGB32`` changed to ``V4L2_PIX_FMT_BGR32``. Audio
-controls are now accessible with the
-:ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and
-:ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls under names starting
-with ``V4L2_CID_AUDIO``. The ``V4L2_MAJOR`` define was removed from
-``videodev.h`` since it was only used once in the ``videodev`` kernel
-module. The ``YUV422`` and ``YUV411`` planar image formats were added.
-
-1998-11-28: A few ioctl symbols changed. Interfaces for codecs and video
-output devices were added.
-
-1999-01-14: A raw VBI capture interface was added.
-
-1999-01-19: The ``VIDIOC_NEXTBUF`` ioctl was removed.
-
-
-V4L2 Version 0.16 1999-01-31
-============================
-
-1999-01-27: There is now one QBUF ioctl, VIDIOC_QWBUF and VIDIOC_QRBUF
-are gone. VIDIOC_QBUF takes a v4l2_buffer as a parameter. Added
-digital zoom (cropping) controls.
-
-
-V4L2 Version 0.18 1999-03-16
-============================
-
-Added a v4l to V4L2 ioctl compatibility layer to videodev.c. Driver
-writers, this changes how you implement your ioctl handler. See the
-Driver Writer's Guide. Added some more control id codes.
-
-
-V4L2 Version 0.19 1999-06-05
-============================
-
-1999-03-18: Fill in the category and catname fields of v4l2_queryctrl
-objects before passing them to the driver. Required a minor change to
-the VIDIOC_QUERYCTRL handlers in the sample drivers.
-
-1999-03-31: Better compatibility for v4l memory capture ioctls. Requires
-changes to drivers to fully support new compatibility features, see
-Driver Writer's Guide and v4l2cap.c. Added new control IDs:
-V4L2_CID_HFLIP, _VFLIP. Changed V4L2_PIX_FMT_YUV422P to _YUV422P,
-and _YUV411P to _YUV411P.
-
-1999-04-04: Added a few more control IDs.
-
-1999-04-07: Added the button control type.
-
-1999-05-02: Fixed a typo in videodev.h, and added the
-V4L2_CTRL_FLAG_GRAYED (later V4L2_CTRL_FLAG_GRABBED) flag.
-
-1999-05-20: Definition of VIDIOC_G_CTRL was wrong causing a
-malfunction of this ioctl.
-
-1999-06-05: Changed the value of V4L2_CID_WHITENESS.
-
-
-V4L2 Version 0.20 (1999-09-10)
-==============================
-
-Version 0.20 introduced a number of changes which were *not backward
-compatible* with 0.19 and earlier versions. Purpose of these changes was
-to simplify the API, while making it more extensible and following
-common Linux driver API conventions.
-
-1. Some typos in ``V4L2_FMT_FLAG`` symbols were fixed. struct
- :ref:`v4l2_clip <v4l2-clip>` was changed for compatibility with
- v4l. (1999-08-30)
-
-2. ``V4L2_TUNER_SUB_LANG1`` was added. (1999-09-05)
-
-3. All ioctl() commands that used an integer argument now take a pointer
- to an integer. Where it makes sense, ioctls will return the actual
- new value in the integer pointed to by the argument, a common
- convention in the V4L2 API. The affected ioctls are: VIDIOC_PREVIEW,
- VIDIOC_STREAMON, VIDIOC_STREAMOFF, VIDIOC_S_FREQ,
- VIDIOC_S_INPUT, VIDIOC_S_OUTPUT, VIDIOC_S_EFFECT. For example
-
-
- .. code-block:: c
-
- err = ioctl (fd, VIDIOC_XXX, V4L2_XXX);
-
- becomes
-
-
- .. code-block:: c
-
- int a = V4L2_XXX; err = ioctl(fd, VIDIOC_XXX, &a);
-
-4. All the different get- and set-format commands were swept into one
- :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
- :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl taking a union and a
- type field selecting the union member as parameter. Purpose is to
- simplify the API by eliminating several ioctls and to allow new and
- driver private data streams without adding new ioctls.
-
- This change obsoletes the following ioctls: ``VIDIOC_S_INFMT``,
- ``VIDIOC_G_INFMT``, ``VIDIOC_S_OUTFMT``, ``VIDIOC_G_OUTFMT``,
- ``VIDIOC_S_VBIFMT`` and ``VIDIOC_G_VBIFMT``. The image format
- structure :c:type:`struct v4l2_format` was renamed to struct
- :ref:`v4l2_pix_format <v4l2-pix-format>`, while struct
- :ref:`v4l2_format <v4l2-format>` is now the envelopping structure
- for all format negotiations.
-
-5. Similar to the changes above, the ``VIDIOC_G_PARM`` and
- ``VIDIOC_S_PARM`` ioctls were merged with ``VIDIOC_G_OUTPARM`` and
- ``VIDIOC_S_OUTPARM``. A ``type`` field in the new struct
- :ref:`v4l2_streamparm <v4l2-streamparm>` selects the respective
- union member.
-
- This change obsoletes the ``VIDIOC_G_OUTPARM`` and
- ``VIDIOC_S_OUTPARM`` ioctls.
-
-6. Control enumeration was simplified, and two new control flags were
- introduced and one dropped. The ``catname`` field was replaced by a
- ``group`` field.
-
- Drivers can now flag unsupported and temporarily unavailable controls
- with ``V4L2_CTRL_FLAG_DISABLED`` and ``V4L2_CTRL_FLAG_GRABBED``
- respectively. The ``group`` name indicates a possibly narrower
- classification than the ``category``. In other words, there may be
- multiple groups within a category. Controls within a group would
- typically be drawn within a group box. Controls in different
- categories might have a greater separation, or may even appear in
- separate windows.
-
-7. The struct :ref:`v4l2_buffer <v4l2-buffer>` ``timestamp`` was
- changed to a 64 bit integer, containing the sampling or output time
- of the frame in nanoseconds. Additionally timestamps will be in
- absolute system time, not starting from zero at the beginning of a
- stream. The data type name for timestamps is stamp_t, defined as a
- signed 64-bit integer. Output devices should not send a buffer out
- until the time in the timestamp field has arrived. I would like to
- follow SGI's lead, and adopt a multimedia timestamping system like
- their UST (Unadjusted System Time). See
- http://web.archive.org/web/\*/http://reality.sgi.com
- /cpirazzi_engr/lg/time/intro.html. UST uses timestamps that are
- 64-bit signed integers (not struct timeval's) and given in nanosecond
- units. The UST clock starts at zero when the system is booted and
- runs continuously and uniformly. It takes a little over 292 years for
- UST to overflow. There is no way to set the UST clock. The regular
- Linux time-of-day clock can be changed periodically, which would
- cause errors if it were being used for timestamping a multimedia
- stream. A real UST style clock will require some support in the
- kernel that is not there yet. But in anticipation, I will change the
- timestamp field to a 64-bit integer, and I will change the
- v4l2_masterclock_gettime() function (used only by drivers) to
- return a 64-bit integer.
-
-8. A ``sequence`` field was added to struct
- :ref:`v4l2_buffer <v4l2-buffer>`. The ``sequence`` field counts
- captured frames, it is ignored by output devices. When a capture
- driver drops a frame, the sequence number of that frame is skipped.
-
-
-V4L2 Version 0.20 incremental changes
-=====================================
-
-1999-12-23: In struct :ref:`v4l2_vbi_format <v4l2-vbi-format>` the
-``reserved1`` field became ``offset``. Previously drivers were required
-to clear the ``reserved1`` field.
-
-2000-01-13: The ``V4L2_FMT_FLAG_NOT_INTERLACED`` flag was added.
-
-2000-07-31: The ``linux/poll.h`` header is now included by
-``videodev.h`` for compatibility with the original ``videodev.h`` file.
-
-2000-11-20: ``V4L2_TYPE_VBI_OUTPUT`` and ``V4L2_PIX_FMT_Y41P`` were
-added.
-
-2000-11-25: ``V4L2_TYPE_VBI_INPUT`` was added.
-
-2000-12-04: A couple typos in symbol names were fixed.
-
-2001-01-18: To avoid namespace conflicts the ``fourcc`` macro defined in
-the ``videodev.h`` header file was renamed to ``v4l2_fourcc``.
-
-2001-01-25: A possible driver-level compatibility problem between the
-``videodev.h`` file in Linux 2.4.0 and the ``videodev.h`` file included
-in the ``videodevX`` patch was fixed. Users of an earlier version of
-``videodevX`` on Linux 2.4.0 should recompile their V4L and V4L2
-drivers.
-
-2001-01-26: A possible kernel-level incompatibility between the
-``videodev.h`` file in the ``videodevX`` patch and the ``videodev.h``
-file in Linux 2.2.x with devfs patches applied was fixed.
-
-2001-03-02: Certain V4L ioctls which pass data in both direction
-although they are defined with read-only parameter, did not work
-correctly through the backward compatibility layer. [Solution?]
-
-2001-04-13: Big endian 16-bit RGB formats were added.
-
-2001-09-17: New YUV formats and the
-:ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` and
-:ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctls were added.
-(The old ``VIDIOC_G_FREQ`` and ``VIDIOC_S_FREQ`` ioctls did not take
-multiple tuners into account.)
-
-2000-09-18: ``V4L2_BUF_TYPE_VBI`` was added. This may *break
-compatibility* as the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
-:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls may fail now if the struct
-:c:type:`struct v4l2_fmt` ``type`` field does not contain
-``V4L2_BUF_TYPE_VBI``. In the documentation of the struct
-:ref:`v4l2_vbi_format <v4l2-vbi-format>` ``offset`` field the
-ambiguous phrase "rising edge" was changed to "leading edge".
-
-
-V4L2 Version 0.20 2000-11-23
-============================
-
-A number of changes were made to the raw VBI interface.
-
-1. Figures clarifying the line numbering scheme were added to the V4L2
- API specification. The ``start``\ [0] and ``start``\ [1] fields no
- longer count line numbers beginning at zero. Rationale: a) The
- previous definition was unclear. b) The ``start``\ [] values are
- ordinal numbers. c) There is no point in inventing a new line
- numbering scheme. We now use line number as defined by ITU-R, period.
- Compatibility: Add one to the start values. Applications depending on
- the previous semantics may not function correctly.
-
-2. The restriction "count[0] > 0 and count[1] > 0" has been relaxed to
- "(count[0] + count[1]) > 0". Rationale: Drivers may allocate
- resources at scan line granularity and some data services are
- transmitted only on the first field. The comment that both ``count``
- values will usually be equal is misleading and pointless and has been
- removed. This change *breaks compatibility* with earlier versions:
- Drivers may return ``EINVAL``, applications may not function correctly.
-
-3. Drivers are again permitted to return negative (unknown) start values
- as proposed earlier. Why this feature was dropped is unclear. This
- change may *break compatibility* with applications depending on the
- start values being positive. The use of ``EBUSY`` and ``EINVAL``
- error codes with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl was
- clarified. The ``EBUSY`` error code was finally documented, and the
- ``reserved2`` field which was previously mentioned only in the
- ``videodev.h`` header file.
-
-4. New buffer types ``V4L2_TYPE_VBI_INPUT`` and ``V4L2_TYPE_VBI_OUTPUT``
- were added. The former is an alias for the old ``V4L2_TYPE_VBI``, the
- latter was missing in the ``videodev.h`` file.
-
-
-V4L2 Version 0.20 2002-07-25
-============================
-
-Added sliced VBI interface proposal.
-
-
-V4L2 in Linux 2.5.46, 2002-10
-=============================
-
-Around October-November 2002, prior to an announced feature freeze of
-Linux 2.5, the API was revised, drawing from experience with V4L2 0.20.
-This unnamed version was finally merged into Linux 2.5.46.
-
-1. As specified in :ref:`related`, drivers must make related device
- functions available under all minor device numbers.
-
-2. The :ref:`open() <func-open>` function requires access mode
- ``O_RDWR`` regardless of the device type. All V4L2 drivers
- exchanging data with applications must support the ``O_NONBLOCK``
- flag. The ``O_NOIO`` flag, a V4L2 symbol which aliased the
- meaningless ``O_TRUNC`` to indicate accesses without data exchange
- (panel applications) was dropped. Drivers must stay in "panel mode"
- until the application attempts to initiate a data exchange, see
- :ref:`open`.
-
-3. The struct :ref:`v4l2_capability <v4l2-capability>` changed
- dramatically. Note that also the size of the structure changed,
- which is encoded in the ioctl request code, thus older V4L2 devices
- will respond with an ``EINVAL`` error code to the new
- :ref:`VIDIOC_QUERYCAP` ioctl.
-
- There are new fields to identify the driver, a new RDS device
- function ``V4L2_CAP_RDS_CAPTURE``, the ``V4L2_CAP_AUDIO`` flag
- indicates if the device has any audio connectors, another I/O
- capability ``V4L2_CAP_ASYNCIO`` can be flagged. In response to these
- changes the ``type`` field became a bit set and was merged into the
- ``flags`` field. ``V4L2_FLAG_TUNER`` was renamed to
- ``V4L2_CAP_TUNER``, ``V4L2_CAP_VIDEO_OVERLAY`` replaced
- ``V4L2_FLAG_PREVIEW`` and ``V4L2_CAP_VBI_CAPTURE`` and
- ``V4L2_CAP_VBI_OUTPUT`` replaced ``V4L2_FLAG_DATA_SERVICE``.
- ``V4L2_FLAG_READ`` and ``V4L2_FLAG_WRITE`` were merged into
- ``V4L2_CAP_READWRITE``.
-
- The redundant fields ``inputs``, ``outputs`` and ``audios`` were
- removed. These properties can be determined as described in
- :ref:`video` and :ref:`audio`.
-
- The somewhat volatile and therefore barely useful fields
- ``maxwidth``, ``maxheight``, ``minwidth``, ``minheight``,
- ``maxframerate`` were removed. This information is available as
- described in :ref:`format` and :ref:`standard`.
-
- ``V4L2_FLAG_SELECT`` was removed. We believe the select() function
- is important enough to require support of it in all V4L2 drivers
- exchanging data with applications. The redundant
- ``V4L2_FLAG_MONOCHROME`` flag was removed, this information is
- available as described in :ref:`format`.
-
-4. In struct :ref:`v4l2_input <v4l2-input>` the ``assoc_audio``
- field and the ``capability`` field and its only flag
- ``V4L2_INPUT_CAP_AUDIO`` was replaced by the new ``audioset`` field.
- Instead of linking one video input to one audio input this field
- reports all audio inputs this video input combines with.
-
- New fields are ``tuner`` (reversing the former link from tuners to
- video inputs), ``std`` and ``status``.
-
- Accordingly struct :ref:`v4l2_output <v4l2-output>` lost its
- ``capability`` and ``assoc_audio`` fields. ``audioset``,
- ``modulator`` and ``std`` where added instead.
-
-5. The struct :ref:`v4l2_audio <v4l2-audio>` field ``audio`` was
- renamed to ``index``, for consistency with other structures. A new
- capability flag ``V4L2_AUDCAP_STEREO`` was added to indicated if the
- audio input in question supports stereo sound.
- ``V4L2_AUDCAP_EFFECTS`` and the corresponding ``V4L2_AUDMODE`` flags
- where removed. This can be easily implemented using controls.
- (However the same applies to AVL which is still there.)
-
- Again for consistency the struct
- :ref:`v4l2_audioout <v4l2-audioout>` field ``audio`` was renamed
- to ``index``.
-
-6. The struct :ref:`v4l2_tuner <v4l2-tuner>` ``input`` field was
- replaced by an ``index`` field, permitting devices with multiple
- tuners. The link between video inputs and tuners is now reversed,
- inputs point to their tuner. The ``std`` substructure became a
- simple set (more about this below) and moved into struct
- :ref:`v4l2_input <v4l2-input>`. A ``type`` field was added.
-
- Accordingly in struct :ref:`v4l2_modulator <v4l2-modulator>` the
- ``output`` was replaced by an ``index`` field.
-
- In struct :ref:`v4l2_frequency <v4l2-frequency>` the ``port``
- field was replaced by a ``tuner`` field containing the respective
- tuner or modulator index number. A tuner ``type`` field was added
- and the ``reserved`` field became larger for future extensions
- (satellite tuners in particular).
-
-7. The idea of completely transparent video standards was dropped.
- Experience showed that applications must be able to work with video
- standards beyond presenting the user a menu. Instead of enumerating
- supported standards with an ioctl applications can now refer to
- standards by :ref:`v4l2_std_id <v4l2-std-id>` and symbols
- defined in the ``videodev2.h`` header file. For details see
- :ref:`standard`. The :ref:`VIDIOC_G_STD <VIDIOC_G_STD>` and
- :ref:`VIDIOC_S_STD <VIDIOC_G_STD>` now take a pointer to this
- type as argument. :ref:`VIDIOC_QUERYSTD` was
- added to autodetect the received standard, if the hardware has this
- capability. In struct :ref:`v4l2_standard <v4l2-standard>` an
- ``index`` field was added for
- :ref:`VIDIOC_ENUMSTD`. A
- :ref:`v4l2_std_id <v4l2-std-id>` field named ``id`` was added as
- machine readable identifier, also replacing the ``transmission``
- field. The misleading ``framerate`` field was renamed to
- ``frameperiod``. The now obsolete ``colorstandard`` information,
- originally needed to distguish between variations of standards, were
- removed.
-
- Struct :c:type:`struct v4l2_enumstd` ceased to be.
- :ref:`VIDIOC_ENUMSTD` now takes a pointer to a
- struct :ref:`v4l2_standard <v4l2-standard>` directly. The
- information which standards are supported by a particular video
- input or output moved into struct :ref:`v4l2_input <v4l2-input>`
- and struct :ref:`v4l2_output <v4l2-output>` fields named ``std``,
- respectively.
-
-8. The struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` fields
- ``category`` and ``group`` did not catch on and/or were not
- implemented as expected and therefore removed.
-
-9. The :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl was added to
- negotiate data formats as with
- :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`, but without the overhead of
- programming the hardware and regardless of I/O in progress.
-
- In struct :ref:`v4l2_format <v4l2-format>` the ``fmt`` union was
- extended to contain struct :ref:`v4l2_window <v4l2-window>`. All
- image format negotiations are now possible with ``VIDIOC_G_FMT``,
- ``VIDIOC_S_FMT`` and ``VIDIOC_TRY_FMT``; ioctl. The ``VIDIOC_G_WIN``
- and ``VIDIOC_S_WIN`` ioctls to prepare for a video overlay were
- removed. The ``type`` field changed to type enum
- :ref:`v4l2_buf_type <v4l2-buf-type>` and the buffer type names
- changed as follows.
-
-
-
- .. flat-table::
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - Old defines
-
- - enum :ref:`v4l2_buf_type <v4l2-buf-type>`
-
- - .. row 2
-
- - ``V4L2_BUF_TYPE_CAPTURE``
-
- - ``V4L2_BUF_TYPE_VIDEO_CAPTURE``
-
- - .. row 3
-
- - ``V4L2_BUF_TYPE_CODECIN``
-
- - Omitted for now
-
- - .. row 4
-
- - ``V4L2_BUF_TYPE_CODECOUT``
-
- - Omitted for now
-
- - .. row 5
-
- - ``V4L2_BUF_TYPE_EFFECTSIN``
-
- - Omitted for now
-
- - .. row 6
-
- - ``V4L2_BUF_TYPE_EFFECTSIN2``
-
- - Omitted for now
-
- - .. row 7
-
- - ``V4L2_BUF_TYPE_EFFECTSOUT``
-
- - Omitted for now
-
- - .. row 8
-
- - ``V4L2_BUF_TYPE_VIDEOOUT``
-
- - ``V4L2_BUF_TYPE_VIDEO_OUTPUT``
-
- - .. row 9
-
- - ``-``
-
- - ``V4L2_BUF_TYPE_VIDEO_OVERLAY``
-
- - .. row 10
-
- - ``-``
-
- - ``V4L2_BUF_TYPE_VBI_CAPTURE``
-
- - .. row 11
-
- - ``-``
-
- - ``V4L2_BUF_TYPE_VBI_OUTPUT``
-
- - .. row 12
-
- - ``-``
-
- - ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE``
-
- - .. row 13
-
- - ``-``
-
- - ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT``
-
- - .. row 14
-
- - ``V4L2_BUF_TYPE_PRIVATE_BASE``
-
- - ``V4L2_BUF_TYPE_PRIVATE`` (but this is deprecated)
-
-
-10. In struct :ref:`v4l2_fmtdesc <v4l2-fmtdesc>` a enum
- :ref:`v4l2_buf_type <v4l2-buf-type>` field named ``type`` was
- added as in struct :ref:`v4l2_format <v4l2-format>`. The
- ``VIDIOC_ENUM_FBUFFMT`` ioctl is no longer needed and was removed.
- These calls can be replaced by
- :ref:`VIDIOC_ENUM_FMT` with type
- ``V4L2_BUF_TYPE_VIDEO_OVERLAY``.
-
-11. In struct :ref:`v4l2_pix_format <v4l2-pix-format>` the ``depth``
- field was removed, assuming applications which recognize the format
- by its four-character-code already know the color depth, and others
- do not care about it. The same rationale lead to the removal of the
- ``V4L2_FMT_FLAG_COMPRESSED`` flag. The
- ``V4L2_FMT_FLAG_SWCONVECOMPRESSED`` flag was removed because drivers
- are not supposed to convert images in kernel space. A user library
- of conversion functions should be provided instead. The
- ``V4L2_FMT_FLAG_BYTESPERLINE`` flag was redundant. Applications can
- set the ``bytesperline`` field to zero to get a reasonable default.
- Since the remaining flags were replaced as well, the ``flags`` field
- itself was removed.
-
- The interlace flags were replaced by a enum
- :ref:`v4l2_field <v4l2-field>` value in a newly added ``field``
- field.
-
-
-
- .. flat-table::
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - Old flag
-
- - enum :ref:`v4l2_field <v4l2-field>`
-
- - .. row 2
-
- - ``V4L2_FMT_FLAG_NOT_INTERLACED``
-
- - ?
-
- - .. row 3
-
- - ``V4L2_FMT_FLAG_INTERLACED`` = ``V4L2_FMT_FLAG_COMBINED``
-
- - ``V4L2_FIELD_INTERLACED``
-
- - .. row 4
-
- - ``V4L2_FMT_FLAG_TOPFIELD`` = ``V4L2_FMT_FLAG_ODDFIELD``
-
- - ``V4L2_FIELD_TOP``
-
- - .. row 5
-
- - ``V4L2_FMT_FLAG_BOTFIELD`` = ``V4L2_FMT_FLAG_EVENFIELD``
-
- - ``V4L2_FIELD_BOTTOM``
-
- - .. row 6
-
- - ``-``
-
- - ``V4L2_FIELD_SEQ_TB``
-
- - .. row 7
-
- - ``-``
-
- - ``V4L2_FIELD_SEQ_BT``
-
- - .. row 8
-
- - ``-``
-
- - ``V4L2_FIELD_ALTERNATE``
-
-
- The color space flags were replaced by a enum
- :ref:`v4l2_colorspace <v4l2-colorspace>` value in a newly added
- ``colorspace`` field, where one of ``V4L2_COLORSPACE_SMPTE170M``,
- ``V4L2_COLORSPACE_BT878``, ``V4L2_COLORSPACE_470_SYSTEM_M`` or
- ``V4L2_COLORSPACE_470_SYSTEM_BG`` replaces ``V4L2_FMT_CS_601YUV``.
-
-12. In struct :ref:`v4l2_requestbuffers <v4l2-requestbuffers>` the
- ``type`` field was properly defined as enum
- :ref:`v4l2_buf_type <v4l2-buf-type>`. Buffer types changed as
- mentioned above. A new ``memory`` field of type enum
- :ref:`v4l2_memory <v4l2-memory>` was added to distinguish between
- I/O methods using buffers allocated by the driver or the
- application. See :ref:`io` for details.
-
-13. In struct :ref:`v4l2_buffer <v4l2-buffer>` the ``type`` field was
- properly defined as enum :ref:`v4l2_buf_type <v4l2-buf-type>`.
- Buffer types changed as mentioned above. A ``field`` field of type
- enum :ref:`v4l2_field <v4l2-field>` was added to indicate if a
- buffer contains a top or bottom field. The old field flags were
- removed. Since no unadjusted system time clock was added to the
- kernel as planned, the ``timestamp`` field changed back from type
- stamp_t, an unsigned 64 bit integer expressing the sample time in
- nanoseconds, to struct :c:type:`struct timeval`. With the addition
- of a second memory mapping method the ``offset`` field moved into
- union ``m``, and a new ``memory`` field of type enum
- :ref:`v4l2_memory <v4l2-memory>` was added to distinguish between
- I/O methods. See :ref:`io` for details.
-
- The ``V4L2_BUF_REQ_CONTIG`` flag was used by the V4L compatibility
- layer, after changes to this code it was no longer needed. The
- ``V4L2_BUF_ATTR_DEVICEMEM`` flag would indicate if the buffer was
- indeed allocated in device memory rather than DMA-able system
- memory. It was barely useful and so was removed.
-
-14. In struct :ref:`v4l2_framebuffer <v4l2-framebuffer>` the
- ``base[3]`` array anticipating double- and triple-buffering in
- off-screen video memory, however without defining a synchronization
- mechanism, was replaced by a single pointer. The
- ``V4L2_FBUF_CAP_SCALEUP`` and ``V4L2_FBUF_CAP_SCALEDOWN`` flags were
- removed. Applications can determine this capability more accurately
- using the new cropping and scaling interface. The
- ``V4L2_FBUF_CAP_CLIPPING`` flag was replaced by
- ``V4L2_FBUF_CAP_LIST_CLIPPING`` and
- ``V4L2_FBUF_CAP_BITMAP_CLIPPING``.
-
-15. In struct :ref:`v4l2_clip <v4l2-clip>` the ``x``, ``y``,
- ``width`` and ``height`` field moved into a ``c`` substructure of
- type struct :ref:`v4l2_rect <v4l2-rect>`. The ``x`` and ``y``
- fields were renamed to ``left`` and ``top``, i. e. offsets to a
- context dependent origin.
-
-16. In struct :ref:`v4l2_window <v4l2-window>` the ``x``, ``y``,
- ``width`` and ``height`` field moved into a ``w`` substructure as
- above. A ``field`` field of type %v4l2-field; was added to
- distinguish between field and frame (interlaced) overlay.
-
-17. The digital zoom interface, including struct
- :c:type:`struct v4l2_zoomcap`, struct
- :c:type:`struct v4l2_zoom`, ``V4L2_ZOOM_NONCAP`` and
- ``V4L2_ZOOM_WHILESTREAMING`` was replaced by a new cropping and
- scaling interface. The previously unused struct
- :c:type:`struct v4l2_cropcap` and :c:type:`struct v4l2_crop`
- where redefined for this purpose. See :ref:`crop` for details.
-
-18. In struct :ref:`v4l2_vbi_format <v4l2-vbi-format>` the
- ``SAMPLE_FORMAT`` field now contains a four-character-code as used
- to identify video image formats and ``V4L2_PIX_FMT_GREY`` replaces
- the ``V4L2_VBI_SF_UBYTE`` define. The ``reserved`` field was
- extended.
-
-19. In struct :ref:`v4l2_captureparm <v4l2-captureparm>` the type of
- the ``timeperframe`` field changed from unsigned long to struct
- :ref:`v4l2_fract <v4l2-fract>`. This allows the accurate
- expression of multiples of the NTSC-M frame rate 30000 / 1001. A new
- field ``readbuffers`` was added to control the driver behaviour in
- read I/O mode.
-
- Similar changes were made to struct
- :ref:`v4l2_outputparm <v4l2-outputparm>`.
-
-20. The struct :c:type:`struct v4l2_performance` and
- ``VIDIOC_G_PERF`` ioctl were dropped. Except when using the
- :ref:`read/write I/O method <rw>`, which is limited anyway, this
- information is already available to applications.
-
-21. The example transformation from RGB to YCbCr color space in the old
- V4L2 documentation was inaccurate, this has been corrected in
- :ref:`pixfmt`.
-
-
-V4L2 2003-06-19
-===============
-
-1. A new capability flag ``V4L2_CAP_RADIO`` was added for radio devices.
- Prior to this change radio devices would identify solely by having
- exactly one tuner whose type field reads ``V4L2_TUNER_RADIO``.
-
-2. An optional driver access priority mechanism was added, see
- :ref:`app-pri` for details.
-
-3. The audio input and output interface was found to be incomplete.
-
- Previously the :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` ioctl would
- enumerate the available audio inputs. An ioctl to determine the
- current audio input, if more than one combines with the current video
- input, did not exist. So ``VIDIOC_G_AUDIO`` was renamed to
- ``VIDIOC_G_AUDIO_OLD``, this ioctl was removed on Kernel 2.6.39. The
- :ref:`VIDIOC_ENUMAUDIO` ioctl was added to
- enumerate audio inputs, while
- :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` now reports the current
- audio input.
-
- The same changes were made to
- :ref:`VIDIOC_G_AUDOUT <VIDIOC_G_AUDOUT>` and
- :ref:`VIDIOC_ENUMAUDOUT <VIDIOC_ENUMAUDOUT>`.
-
- Until further the "videodev" module will automatically translate
- between the old and new ioctls, but drivers and applications must be
- updated to successfully compile again.
-
-4. The :ref:`VIDIOC_OVERLAY` ioctl was incorrectly
- defined with write-read parameter. It was changed to write-only,
- while the write-read version was renamed to ``VIDIOC_OVERLAY_OLD``.
- The old ioctl was removed on Kernel 2.6.39. Until further the
- "videodev" kernel module will automatically translate to the new
- version, so drivers must be recompiled, but not applications.
-
-5. :ref:`overlay` incorrectly stated that clipping rectangles define
- regions where the video can be seen. Correct is that clipping
- rectangles define regions where *no* video shall be displayed and so
- the graphics surface can be seen.
-
-6. The :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` and
- :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls were defined with
- write-only parameter, inconsistent with other ioctls modifying their
- argument. They were changed to write-read, while a ``_OLD`` suffix
- was added to the write-only versions. The old ioctls were removed on
- Kernel 2.6.39. Drivers and applications assuming a constant parameter
- need an update.
-
-
-V4L2 2003-11-05
-===============
-
-1. In :ref:`pixfmt-rgb` the following pixel formats were incorrectly
- transferred from Bill Dirks' V4L2 specification. Descriptions below
- refer to bytes in memory, in ascending address order.
-
-
-
- .. flat-table::
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - Symbol
-
- - In this document prior to revision 0.5
-
- - Corrected
-
- - .. row 2
-
- - ``V4L2_PIX_FMT_RGB24``
-
- - B, G, R
-
- - R, G, B
-
- - .. row 3
-
- - ``V4L2_PIX_FMT_BGR24``
-
- - R, G, B
-
- - B, G, R
-
- - .. row 4
-
- - ``V4L2_PIX_FMT_RGB32``
-
- - B, G, R, X
-
- - R, G, B, X
-
- - .. row 5
-
- - ``V4L2_PIX_FMT_BGR32``
-
- - R, G, B, X
-
- - B, G, R, X
-
-
- The ``V4L2_PIX_FMT_BGR24`` example was always correct.
-
- In :ref:`v4l-image-properties` the mapping of the V4L
- ``VIDEO_PALETTE_RGB24`` and ``VIDEO_PALETTE_RGB32`` formats to V4L2
- pixel formats was accordingly corrected.
-
-2. Unrelated to the fixes above, drivers may still interpret some V4L2
- RGB pixel formats differently. These issues have yet to be addressed,
- for details see :ref:`pixfmt-rgb`.
-
-
-V4L2 in Linux 2.6.6, 2004-05-09
-===============================
-
-1. The :ref:`VIDIOC_CROPCAP` ioctl was incorrectly
- defined with read-only parameter. It is now defined as write-read
- ioctl, while the read-only version was renamed to
- ``VIDIOC_CROPCAP_OLD``. The old ioctl was removed on Kernel 2.6.39.
-
-
-V4L2 in Linux 2.6.8
-===================
-
-1. A new field ``input`` (former ``reserved[0]``) was added to the
- struct :ref:`v4l2_buffer <v4l2-buffer>` structure. Purpose of this
- field is to alternate between video inputs (e. g. cameras) in step
- with the video capturing process. This function must be enabled with
- the new ``V4L2_BUF_FLAG_INPUT`` flag. The ``flags`` field is no
- longer read-only.
-
-
-V4L2 spec erratum 2004-08-01
-============================
-
-1. The return value of the :ref:`func-open` function was incorrectly
- documented.
-
-2. Audio output ioctls end in -AUDOUT, not -AUDIOOUT.
-
-3. In the Current Audio Input example the ``VIDIOC_G_AUDIO`` ioctl took
- the wrong argument.
-
-4. The documentation of the :ref:`VIDIOC_QBUF` and
- :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctls did not mention the
- struct :ref:`v4l2_buffer <v4l2-buffer>` ``memory`` field. It was
- also missing from examples. Also on the ``VIDIOC_DQBUF`` page the ``EIO``
- error code was not documented.
-
-
-V4L2 in Linux 2.6.14
-====================
-
-1. A new sliced VBI interface was added. It is documented in
- :ref:`sliced` and replaces the interface first proposed in V4L2
- specification 0.8.
-
-
-V4L2 in Linux 2.6.15
-====================
-
-1. The :ref:`VIDIOC_LOG_STATUS` ioctl was added.
-
-2. New video standards ``V4L2_STD_NTSC_443``, ``V4L2_STD_SECAM_LC``,
- ``V4L2_STD_SECAM_DK`` (a set of SECAM D, K and K1), and
- ``V4L2_STD_ATSC`` (a set of ``V4L2_STD_ATSC_8_VSB`` and
- ``V4L2_STD_ATSC_16_VSB``) were defined. Note the ``V4L2_STD_525_60``
- set now includes ``V4L2_STD_NTSC_443``. See also
- :ref:`v4l2-std-id`.
-
-3. The ``VIDIOC_G_COMP`` and ``VIDIOC_S_COMP`` ioctl were renamed to
- ``VIDIOC_G_MPEGCOMP`` and ``VIDIOC_S_MPEGCOMP`` respectively. Their
- argument was replaced by a struct
- :c:type:`struct v4l2_mpeg_compression` pointer. (The
- ``VIDIOC_G_MPEGCOMP`` and ``VIDIOC_S_MPEGCOMP`` ioctls where removed
- in Linux 2.6.25.)
-
-
-V4L2 spec erratum 2005-11-27
-============================
-
-The capture example in :ref:`capture-example` called the
-:ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` ioctl without checking if
-cropping is supported. In the video standard selection example in
-:ref:`standard` the :ref:`VIDIOC_S_STD <VIDIOC_G_STD>` call used
-the wrong argument type.
-
-
-V4L2 spec erratum 2006-01-10
-============================
-
-1. The ``V4L2_IN_ST_COLOR_KILL`` flag in struct
- :ref:`v4l2_input <v4l2-input>` not only indicates if the color
- killer is enabled, but also if it is active. (The color killer
- disables color decoding when it detects no color in the video signal
- to improve the image quality.)
-
-2. :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` is a write-read ioctl, not
- write-only as stated on its reference page. The ioctl changed in 2003
- as noted above.
-
-
-V4L2 spec erratum 2006-02-03
-============================
-
-1. In struct :ref:`v4l2_captureparm <v4l2-captureparm>` and struct
- :ref:`v4l2_outputparm <v4l2-outputparm>` the ``timeperframe``
- field gives the time in seconds, not microseconds.
-
-
-V4L2 spec erratum 2006-02-04
-============================
-
-1. The ``clips`` field in struct :ref:`v4l2_window <v4l2-window>`
- must point to an array of struct :ref:`v4l2_clip <v4l2-clip>`, not
- a linked list, because drivers ignore the struct
- :c:type:`struct v4l2_clip`. ``next`` pointer.
-
-
-V4L2 in Linux 2.6.17
-====================
-
-1. New video standard macros were added: ``V4L2_STD_NTSC_M_KR`` (NTSC M
- South Korea), and the sets ``V4L2_STD_MN``, ``V4L2_STD_B``,
- ``V4L2_STD_GH`` and ``V4L2_STD_DK``. The ``V4L2_STD_NTSC`` and
- ``V4L2_STD_SECAM`` sets now include ``V4L2_STD_NTSC_M_KR`` and
- ``V4L2_STD_SECAM_LC`` respectively.
-
-2. A new ``V4L2_TUNER_MODE_LANG1_LANG2`` was defined to record both
- languages of a bilingual program. The use of
- ``V4L2_TUNER_MODE_STEREO`` for this purpose is deprecated now. See
- the :ref:`VIDIOC_G_TUNER <VIDIOC_G_TUNER>` section for details.
-
-
-V4L2 spec erratum 2006-09-23 (Draft 0.15)
-=========================================
-
-1. In various places ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE`` and
- ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT`` of the sliced VBI interface were
- not mentioned along with other buffer types.
-
-2. In :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` it was clarified that the struct
- :ref:`v4l2_audio <v4l2-audio>` ``mode`` field is a flags field.
-
-3. :ref:`VIDIOC_QUERYCAP` did not mention the sliced VBI and radio
- capability flags.
-
-4. In :ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` it was clarified that applications
- must initialize the tuner ``type`` field of struct
- :ref:`v4l2_frequency <v4l2-frequency>` before calling
- :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>`.
-
-5. The ``reserved`` array in struct
- :ref:`v4l2_requestbuffers <v4l2-requestbuffers>` has 2 elements,
- not 32.
-
-6. In :ref:`output` and :ref:`raw-vbi` the device file names
- ``/dev/vout`` which never caught on were replaced by ``/dev/video``.
-
-7. With Linux 2.6.15 the possible range for VBI device minor numbers was
- extended from 224-239 to 224-255. Accordingly device file names
- ``/dev/vbi0`` to ``/dev/vbi31`` are possible now.
-
-
-V4L2 in Linux 2.6.18
-====================
-
-1. New ioctls :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`,
- :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` and
- :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` were added, a
- flag to skip unsupported controls with
- :ref:`VIDIOC_QUERYCTRL`, new control types
- ``V4L2_CTRL_TYPE_INTEGER64`` and ``V4L2_CTRL_TYPE_CTRL_CLASS``
- (:ref:`v4l2-ctrl-type`), and new control flags
- ``V4L2_CTRL_FLAG_READ_ONLY``, ``V4L2_CTRL_FLAG_UPDATE``,
- ``V4L2_CTRL_FLAG_INACTIVE`` and ``V4L2_CTRL_FLAG_SLIDER``
- (:ref:`control-flags`). See :ref:`extended-controls` for details.
-
-
-V4L2 in Linux 2.6.19
-====================
-
-1. In struct :ref:`v4l2_sliced_vbi_cap <v4l2-sliced-vbi-cap>` a
- buffer type field was added replacing a reserved field. Note on
- architectures where the size of enum types differs from int types the
- size of the structure changed. The
- :ref:`VIDIOC_G_SLICED_VBI_CAP <VIDIOC_G_SLICED_VBI_CAP>` ioctl
- was redefined from being read-only to write-read. Applications must
- initialize the type field and clear the reserved fields now. These
- changes may *break the compatibility* with older drivers and
- applications.
-
-2. The ioctls :ref:`VIDIOC_ENUM_FRAMESIZES`
- and
- :ref:`VIDIOC_ENUM_FRAMEINTERVALS`
- were added.
-
-3. A new pixel format ``V4L2_PIX_FMT_RGB444`` (:ref:`rgb-formats`) was
- added.
-
-
-V4L2 spec erratum 2006-10-12 (Draft 0.17)
-=========================================
-
-1. ``V4L2_PIX_FMT_HM12`` (:ref:`reserved-formats`) is a YUV 4:2:0, not
- 4:2:2 format.
-
-
-V4L2 in Linux 2.6.21
-====================
-
-1. The ``videodev2.h`` header file is now dual licensed under GNU
- General Public License version two or later, and under a 3-clause
- BSD-style license.
-
-
-V4L2 in Linux 2.6.22
-====================
-
-1. Two new field orders ``V4L2_FIELD_INTERLACED_TB`` and
- ``V4L2_FIELD_INTERLACED_BT`` were added. See :ref:`v4l2-field` for
- details.
-
-2. Three new clipping/blending methods with a global or straight or
- inverted local alpha value were added to the video overlay interface.
- See the description of the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`
- and :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctls for details.
-
- A new ``global_alpha`` field was added to
- :ref:`v4l2_window <v4l2-window>`, extending the structure. This
- may *break compatibility* with applications using a struct
- :c:type:`struct v4l2_window` directly. However the
- :ref:`VIDIOC_G/S/TRY_FMT <VIDIOC_G_FMT>` ioctls, which take a
- pointer to a :ref:`v4l2_format <v4l2-format>` parent structure
- with padding bytes at the end, are not affected.
-
-3. The format of the ``chromakey`` field in struct
- :ref:`v4l2_window <v4l2-window>` changed from "host order RGB32"
- to a pixel value in the same format as the framebuffer. This may
- *break compatibility* with existing applications. Drivers supporting
- the "host order RGB32" format are not known.
-
-
-V4L2 in Linux 2.6.24
-====================
-
-1. The pixel formats ``V4L2_PIX_FMT_PAL8``, ``V4L2_PIX_FMT_YUV444``,
- ``V4L2_PIX_FMT_YUV555``, ``V4L2_PIX_FMT_YUV565`` and
- ``V4L2_PIX_FMT_YUV32`` were added.
-
-
-V4L2 in Linux 2.6.25
-====================
-
-1. The pixel formats :ref:`V4L2_PIX_FMT_Y16 <V4L2-PIX-FMT-Y16>` and
- :ref:`V4L2_PIX_FMT_SBGGR16 <V4L2-PIX-FMT-SBGGR16>` were added.
-
-2. New :ref:`controls <control>` ``V4L2_CID_POWER_LINE_FREQUENCY``,
- ``V4L2_CID_HUE_AUTO``, ``V4L2_CID_WHITE_BALANCE_TEMPERATURE``,
- ``V4L2_CID_SHARPNESS`` and ``V4L2_CID_BACKLIGHT_COMPENSATION`` were
- added. The controls ``V4L2_CID_BLACK_LEVEL``, ``V4L2_CID_WHITENESS``,
- ``V4L2_CID_HCENTER`` and ``V4L2_CID_VCENTER`` were deprecated.
-
-3. A :ref:`Camera controls class <camera-controls>` was added, with
- the new controls ``V4L2_CID_EXPOSURE_AUTO``,
- ``V4L2_CID_EXPOSURE_ABSOLUTE``, ``V4L2_CID_EXPOSURE_AUTO_PRIORITY``,
- ``V4L2_CID_PAN_RELATIVE``, ``V4L2_CID_TILT_RELATIVE``,
- ``V4L2_CID_PAN_RESET``, ``V4L2_CID_TILT_RESET``,
- ``V4L2_CID_PAN_ABSOLUTE``, ``V4L2_CID_TILT_ABSOLUTE``,
- ``V4L2_CID_FOCUS_ABSOLUTE``, ``V4L2_CID_FOCUS_RELATIVE`` and
- ``V4L2_CID_FOCUS_AUTO``.
-
-4. The ``VIDIOC_G_MPEGCOMP`` and ``VIDIOC_S_MPEGCOMP`` ioctls, which
- were superseded by the :ref:`extended controls <extended-controls>`
- interface in Linux 2.6.18, where finally removed from the
- ``videodev2.h`` header file.
-
-
-V4L2 in Linux 2.6.26
-====================
-
-1. The pixel formats ``V4L2_PIX_FMT_Y16`` and ``V4L2_PIX_FMT_SBGGR16``
- were added.
-
-2. Added user controls ``V4L2_CID_CHROMA_AGC`` and
- ``V4L2_CID_COLOR_KILLER``.
-
-
-V4L2 in Linux 2.6.27
-====================
-
-1. The :ref:`VIDIOC_S_HW_FREQ_SEEK` ioctl
- and the ``V4L2_CAP_HW_FREQ_SEEK`` capability were added.
-
-2. The pixel formats ``V4L2_PIX_FMT_YVYU``, ``V4L2_PIX_FMT_PCA501``,
- ``V4L2_PIX_FMT_PCA505``, ``V4L2_PIX_FMT_PCA508``,
- ``V4L2_PIX_FMT_PCA561``, ``V4L2_PIX_FMT_SGBRG8``,
- ``V4L2_PIX_FMT_PAC207`` and ``V4L2_PIX_FMT_PJPG`` were added.
-
-
-V4L2 in Linux 2.6.28
-====================
-
-1. Added ``V4L2_MPEG_AUDIO_ENCODING_AAC`` and
- ``V4L2_MPEG_AUDIO_ENCODING_AC3`` MPEG audio encodings.
-
-2. Added ``V4L2_MPEG_VIDEO_ENCODING_MPEG_4_AVC`` MPEG video encoding.
-
-3. The pixel formats ``V4L2_PIX_FMT_SGRBG10`` and
- ``V4L2_PIX_FMT_SGRBG10DPCM8`` were added.
-
-
-V4L2 in Linux 2.6.29
-====================
-
-1. The ``VIDIOC_G_CHIP_IDENT`` ioctl was renamed to
- ``VIDIOC_G_CHIP_IDENT_OLD`` and ``VIDIOC_DBG_G_CHIP_IDENT`` was
- introduced in its place. The old struct
- :c:type:`struct v4l2_chip_ident` was renamed to
- :c:type:`struct v4l2_chip_ident_old`.
-
-2. The pixel formats ``V4L2_PIX_FMT_VYUY``, ``V4L2_PIX_FMT_NV16`` and
- ``V4L2_PIX_FMT_NV61`` were added.
-
-3. Added camera controls ``V4L2_CID_ZOOM_ABSOLUTE``,
- ``V4L2_CID_ZOOM_RELATIVE``, ``V4L2_CID_ZOOM_CONTINUOUS`` and
- ``V4L2_CID_PRIVACY``.
-
-
-V4L2 in Linux 2.6.30
-====================
-
-1. New control flag ``V4L2_CTRL_FLAG_WRITE_ONLY`` was added.
-
-2. New control ``V4L2_CID_COLORFX`` was added.
-
-
-V4L2 in Linux 2.6.32
-====================
-
-1. In order to be easier to compare a V4L2 API and a kernel version, now
- V4L2 API is numbered using the Linux Kernel version numeration.
-
-2. Finalized the RDS capture API. See :ref:`rds` for more information.
-
-3. Added new capabilities for modulators and RDS encoders.
-
-4. Add description for libv4l API.
-
-5. Added support for string controls via new type
- ``V4L2_CTRL_TYPE_STRING``.
-
-6. Added ``V4L2_CID_BAND_STOP_FILTER`` documentation.
-
-7. Added FM Modulator (FM TX) Extended Control Class:
- ``V4L2_CTRL_CLASS_FM_TX`` and their Control IDs.
-
-8. Added FM Receiver (FM RX) Extended Control Class:
- ``V4L2_CTRL_CLASS_FM_RX`` and their Control IDs.
-
-9. Added Remote Controller chapter, describing the default Remote
- Controller mapping for media devices.
-
-
-V4L2 in Linux 2.6.33
-====================
-
-1. Added support for Digital Video timings in order to support HDTV
- receivers and transmitters.
-
-
-V4L2 in Linux 2.6.34
-====================
-
-1. Added ``V4L2_CID_IRIS_ABSOLUTE`` and ``V4L2_CID_IRIS_RELATIVE``
- controls to the :ref:`Camera controls class <camera-controls>`.
-
-
-V4L2 in Linux 2.6.37
-====================
-
-1. Remove the vtx (videotext/teletext) API. This API was no longer used
- and no hardware exists to verify the API. Nor were any userspace
- applications found that used it. It was originally scheduled for
- removal in 2.6.35.
-
-
-V4L2 in Linux 2.6.39
-====================
-
-1. The old VIDIOC_*_OLD symbols and V4L1 support were removed.
-
-2. Multi-planar API added. Does not affect the compatibility of current
- drivers and applications. See :ref:`multi-planar API <planar-apis>`
- for details.
-
-
-V4L2 in Linux 3.1
-=================
-
-1. VIDIOC_QUERYCAP now returns a per-subsystem version instead of a
- per-driver one.
-
- Standardize an error code for invalid ioctl.
-
- Added V4L2_CTRL_TYPE_BITMASK.
-
-
-V4L2 in Linux 3.2
-=================
-
-1. V4L2_CTRL_FLAG_VOLATILE was added to signal volatile controls to
- userspace.
-
-2. Add selection API for extended control over cropping and composing.
- Does not affect the compatibility of current drivers and
- applications. See :ref:`selection API <selection-api>` for details.
-
-
-V4L2 in Linux 3.3
-=================
-
-1. Added ``V4L2_CID_ALPHA_COMPONENT`` control to the
- :ref:`User controls class <control>`.
-
-2. Added the device_caps field to struct v4l2_capabilities and added
- the new V4L2_CAP_DEVICE_CAPS capability.
-
-
-V4L2 in Linux 3.4
-=================
-
-1. Added :ref:`JPEG compression control class <jpeg-controls>`.
-
-2. Extended the DV Timings API:
- :ref:`VIDIOC_ENUM_DV_TIMINGS`,
- :ref:`VIDIOC_QUERY_DV_TIMINGS` and
- :ref:`VIDIOC_DV_TIMINGS_CAP`.
-
-
-V4L2 in Linux 3.5
-=================
-
-1. Added integer menus, the new type will be
- V4L2_CTRL_TYPE_INTEGER_MENU.
-
-2. Added selection API for V4L2 subdev interface:
- :ref:`VIDIOC_SUBDEV_G_SELECTION` and
- :ref:`VIDIOC_SUBDEV_S_SELECTION <VIDIOC_SUBDEV_G_SELECTION>`.
-
-3. Added ``V4L2_COLORFX_ANTIQUE``, ``V4L2_COLORFX_ART_FREEZE``,
- ``V4L2_COLORFX_AQUA``, ``V4L2_COLORFX_SILHOUETTE``,
- ``V4L2_COLORFX_SOLARIZATION``, ``V4L2_COLORFX_VIVID`` and
- ``V4L2_COLORFX_ARBITRARY_CBCR`` menu items to the
- ``V4L2_CID_COLORFX`` control.
-
-4. Added ``V4L2_CID_COLORFX_CBCR`` control.
-
-5. Added camera controls ``V4L2_CID_AUTO_EXPOSURE_BIAS``,
- ``V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE``,
- ``V4L2_CID_IMAGE_STABILIZATION``, ``V4L2_CID_ISO_SENSITIVITY``,
- ``V4L2_CID_ISO_SENSITIVITY_AUTO``, ``V4L2_CID_EXPOSURE_METERING``,
- ``V4L2_CID_SCENE_MODE``, ``V4L2_CID_3A_LOCK``,
- ``V4L2_CID_AUTO_FOCUS_START``, ``V4L2_CID_AUTO_FOCUS_STOP``,
- ``V4L2_CID_AUTO_FOCUS_STATUS`` and ``V4L2_CID_AUTO_FOCUS_RANGE``.
-
-
-V4L2 in Linux 3.6
-=================
-
-1. Replaced ``input`` in :c:type:`struct v4l2_buffer` by
- ``reserved2`` and removed ``V4L2_BUF_FLAG_INPUT``.
-
-2. Added V4L2_CAP_VIDEO_M2M and V4L2_CAP_VIDEO_M2M_MPLANE
- capabilities.
-
-3. Added support for frequency band enumerations:
- :ref:`VIDIOC_ENUM_FREQ_BANDS`.
-
-
-V4L2 in Linux 3.9
-=================
-
-1. Added timestamp types to ``flags`` field in
- :c:type:`struct v4l2_buffer`. See :ref:`buffer-flags`.
-
-2. Added ``V4L2_EVENT_CTRL_CH_RANGE`` control event changes flag. See
- :ref:`ctrl-changes-flags`.
-
-
-V4L2 in Linux 3.10
-==================
-
-1. Removed obsolete and unused DV_PRESET ioctls VIDIOC_G_DV_PRESET,
- VIDIOC_S_DV_PRESET, VIDIOC_QUERY_DV_PRESET and
- VIDIOC_ENUM_DV_PRESET. Remove the related v4l2_input/output
- capability flags V4L2_IN_CAP_PRESETS and V4L2_OUT_CAP_PRESETS.
-
-2. Added new debugging ioctl
- :ref:`VIDIOC_DBG_G_CHIP_INFO`.
-
-
-V4L2 in Linux 3.11
-==================
-
-1. Remove obsolete ``VIDIOC_DBG_G_CHIP_IDENT`` ioctl.
-
-
-V4L2 in Linux 3.14
-==================
-
-1. In struct :c:type:`struct v4l2_rect`, the type of ``width`` and
- ``height`` fields changed from _s32 to _u32.
-
-
-V4L2 in Linux 3.15
-==================
-
-1. Added Software Defined Radio (SDR) Interface.
-
-
-V4L2 in Linux 3.16
-==================
-
-1. Added event V4L2_EVENT_SOURCE_CHANGE.
-
-
-V4L2 in Linux 3.17
-==================
-
-1. Extended struct :ref:`v4l2_pix_format <v4l2-pix-format>`. Added
- format flags.
-
-2. Added compound control types and
- :ref:`VIDIOC_QUERY_EXT_CTRL <VIDIOC_QUERYCTRL>`.
-
-
-V4L2 in Linux 3.18
-==================
-
-1. Added ``V4L2_CID_PAN_SPEED`` and ``V4L2_CID_TILT_SPEED`` camera
- controls.
-
-
-V4L2 in Linux 3.19
-==================
-
-1. Rewrote Colorspace chapter, added new enum
- :ref:`v4l2_ycbcr_encoding <v4l2-ycbcr-encoding>` and enum
- :ref:`v4l2_quantization <v4l2-quantization>` fields to struct
- :ref:`v4l2_pix_format <v4l2-pix-format>`, struct
- :ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` and
- struct :ref:`v4l2_mbus_framefmt <v4l2-mbus-framefmt>`.
-
-
-V4L2 in Linux 4.4
-=================
-
-1. Renamed ``V4L2_TUNER_ADC`` to ``V4L2_TUNER_SDR``. The use of
- ``V4L2_TUNER_ADC`` is deprecated now.
-
-2. Added ``V4L2_CID_RF_TUNER_RF_GAIN`` RF Tuner control.
-
-3. Added transmitter support for Software Defined Radio (SDR) Interface.
-
-
-.. _other:
-
-Relation of V4L2 to other Linux multimedia APIs
-===============================================
-
-
-.. _xvideo:
-
-X Video Extension
------------------
-
-The X Video Extension (abbreviated XVideo or just Xv) is an extension of
-the X Window system, implemented for example by the XFree86 project. Its
-scope is similar to V4L2, an API to video capture and output devices for
-X clients. Xv allows applications to display live video in a window,
-send window contents to a TV output, and capture or output still images
-in XPixmaps [1]_. With their implementation XFree86 makes the extension
-available across many operating systems and architectures.
-
-Because the driver is embedded into the X server Xv has a number of
-advantages over the V4L2 :ref:`video overlay interface <overlay>`. The
-driver can easily determine the overlay target, i. e. visible graphics
-memory or off-screen buffers for a destructive overlay. It can program
-the RAMDAC for a non-destructive overlay, scaling or color-keying, or
-the clipping functions of the video capture hardware, always in sync
-with drawing operations or windows moving or changing their stacking
-order.
-
-To combine the advantages of Xv and V4L a special Xv driver exists in
-XFree86 and XOrg, just programming any overlay capable Video4Linux
-device it finds. To enable it ``/etc/X11/XF86Config`` must contain these
-lines:
-
-::
-
- Section "Module"
- Load "v4l"
- EndSection
-
-As of XFree86 4.2 this driver still supports only V4L ioctls, however it
-should work just fine with all V4L2 devices through the V4L2
-backward-compatibility layer. Since V4L2 permits multiple opens it is
-possible (if supported by the V4L2 driver) to capture video while an X
-client requested video overlay. Restrictions of simultaneous capturing
-and overlay are discussed in :ref:`overlay` apply.
-
-Only marginally related to V4L2, XFree86 extended Xv to support hardware
-YUV to RGB conversion and scaling for faster video playback, and added
-an interface to MPEG-2 decoding hardware. This API is useful to display
-images captured with V4L2 devices.
-
-
-Digital Video
--------------
-
-V4L2 does not support digital terrestrial, cable or satellite broadcast.
-A separate project aiming at digital receivers exists. You can find its
-homepage at `https://linuxtv.org <https://linuxtv.org>`__. The Linux
-DVB API has no connection to the V4L2 API except that drivers for hybrid
-hardware may support both.
-
-
-Audio Interfaces
-----------------
-
-[to do - OSS/ALSA]
-
-
-.. _experimental:
-
-Experimental API Elements
-=========================
-
-The following V4L2 API elements are currently experimental and may
-change in the future.
-
-- :ref:`VIDIOC_DBG_G_REGISTER` and
- :ref:`VIDIOC_DBG_S_REGISTER <VIDIOC_DBG_G_REGISTER>` ioctls.
-
-- :ref:`VIDIOC_DBG_G_CHIP_INFO` ioctl.
-
-
-.. _obsolete:
-
-Obsolete API Elements
-=====================
-
-The following V4L2 API elements were superseded by new interfaces and
-should not be implemented in new drivers.
-
-- ``VIDIOC_G_MPEGCOMP`` and ``VIDIOC_S_MPEGCOMP`` ioctls. Use Extended
- Controls, :ref:`extended-controls`.
-
-- VIDIOC_G_DV_PRESET, VIDIOC_S_DV_PRESET,
- VIDIOC_ENUM_DV_PRESETS and VIDIOC_QUERY_DV_PRESET ioctls. Use
- the DV Timings API (:ref:`dv-timings`).
-
-- ``VIDIOC_SUBDEV_G_CROP`` and ``VIDIOC_SUBDEV_S_CROP`` ioctls. Use
- ``VIDIOC_SUBDEV_G_SELECTION`` and ``VIDIOC_SUBDEV_S_SELECTION``,
- :ref:`VIDIOC_SUBDEV_G_SELECTION`.
-
-.. [1]
- This is not implemented in XFree86.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _io:
-
-############
-Input/Output
-############
-The V4L2 API defines several different methods to read from or write to
-a device. All drivers exchanging data with applications must support at
-least one of them.
-
-The classic I/O method using the :ref:`read() <func-read>` and
-:ref:`write() <func-write>` function is automatically selected after opening a
-V4L2 device. When the driver does not support this method attempts to
-read or write will fail at any time.
-
-Other methods must be negotiated. To select the streaming I/O method
-with memory mapped or user buffers applications call the
-:ref:`VIDIOC_REQBUFS` ioctl. The asynchronous I/O
-method is not defined yet.
-
-Video overlay can be considered another I/O method, although the
-application does not directly receive the image data. It is selected by
-initiating video overlay with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
-ioctl. For more information see :ref:`overlay`.
-
-Generally exactly one I/O method, including overlay, is associated with
-each file descriptor. The only exceptions are applications not
-exchanging data with a driver ("panel applications", see :ref:`open`)
-and drivers permitting simultaneous video capturing and overlay using
-the same file descriptor, for compatibility with V4L and earlier
-versions of V4L2.
-
-:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_REQBUFS` would permit this to some
-degree, but for simplicity drivers need not support switching the I/O
-method (after first switching away from read/write) other than by
-closing and reopening the device.
-
-The following sections describe the various I/O methods in more detail.
-
-
-.. toctree::
- :maxdepth: 1
-
- rw
- mmap
- userp
- dmabuf
- async
- buffer
- field-order
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _libv4l-introduction:
-
-************
-Introduction
-************
-
-libv4l is a collection of libraries which adds a thin abstraction layer
-on top of video4linux2 devices. The purpose of this (thin) layer is to
-make it easy for application writers to support a wide variety of
-devices without having to write separate code for different devices in
-the same class.
-
-An example of using libv4l is provided by
-:ref:`v4l2grab <v4l2grab-example>`.
-
-libv4l consists of 3 different libraries:
-
-
-libv4lconvert
-=============
-
-libv4lconvert is a library that converts several different pixelformats
-found in V4L2 drivers into a few common RGB and YUY formats.
-
-It currently accepts the following V4L2 driver formats:
-:ref:`V4L2_PIX_FMT_BGR24 <V4L2-PIX-FMT-BGR24>`,
-:ref:`V4L2_PIX_FMT_HM12 <V4L2-PIX-FMT-HM12>`,
-:ref:`V4L2_PIX_FMT_JPEG <V4L2-PIX-FMT-JPEG>`,
-:ref:`V4L2_PIX_FMT_MJPEG <V4L2-PIX-FMT-MJPEG>`,
-:ref:`V4L2_PIX_FMT_MR97310A <V4L2-PIX-FMT-MR97310A>`,
-:ref:`V4L2_PIX_FMT_OV511 <V4L2-PIX-FMT-OV511>`,
-:ref:`V4L2_PIX_FMT_OV518 <V4L2-PIX-FMT-OV518>`,
-:ref:`V4L2_PIX_FMT_PAC207 <V4L2-PIX-FMT-PAC207>`,
-:ref:`V4L2_PIX_FMT_PJPG <V4L2-PIX-FMT-PJPG>`,
-:ref:`V4L2_PIX_FMT_RGB24 <V4L2-PIX-FMT-RGB24>`,
-:ref:`V4L2_PIX_FMT_SBGGR8 <V4L2-PIX-FMT-SBGGR8>`,
-:ref:`V4L2_PIX_FMT_SGBRG8 <V4L2-PIX-FMT-SGBRG8>`,
-:ref:`V4L2_PIX_FMT_SGRBG8 <V4L2-PIX-FMT-SGRBG8>`,
-:ref:`V4L2_PIX_FMT_SN9C10X <V4L2-PIX-FMT-SN9C10X>`,
-:ref:`V4L2_PIX_FMT_SN9C20X_I420 <V4L2-PIX-FMT-SN9C20X-I420>`,
-:ref:`V4L2_PIX_FMT_SPCA501 <V4L2-PIX-FMT-SPCA501>`,
-:ref:`V4L2_PIX_FMT_SPCA505 <V4L2-PIX-FMT-SPCA505>`,
-:ref:`V4L2_PIX_FMT_SPCA508 <V4L2-PIX-FMT-SPCA508>`,
-:ref:`V4L2_PIX_FMT_SPCA561 <V4L2-PIX-FMT-SPCA561>`,
-:ref:`V4L2_PIX_FMT_SQ905C <V4L2-PIX-FMT-SQ905C>`,
-:ref:`V4L2_PIX_FMT_SRGGB8 <V4L2-PIX-FMT-SRGGB8>`,
-:ref:`V4L2_PIX_FMT_UYVY <V4L2-PIX-FMT-UYVY>`,
-:ref:`V4L2_PIX_FMT_YUV420 <V4L2-PIX-FMT-YUV420>`,
-:ref:`V4L2_PIX_FMT_YUYV <V4L2-PIX-FMT-YUYV>`,
-:ref:`V4L2_PIX_FMT_YVU420 <V4L2-PIX-FMT-YVU420>`, and
-:ref:`V4L2_PIX_FMT_YVYU <V4L2-PIX-FMT-YVYU>`.
-
-Later on libv4lconvert was expanded to also be able to do various video
-processing functions to improve webcam video quality. The video
-processing is split in to 2 parts: libv4lconvert/control and
-libv4lconvert/processing.
-
-The control part is used to offer video controls which can be used to
-control the video processing functions made available by
-libv4lconvert/processing. These controls are stored application wide
-(until reboot) by using a persistent shared memory object.
-
-libv4lconvert/processing offers the actual video processing
-functionality.
-
-
-libv4l1
-=======
-
-This library offers functions that can be used to quickly make v4l1
-applications work with v4l2 devices. These functions work exactly like
-the normal open/close/etc, except that libv4l1 does full emulation of
-the v4l1 api on top of v4l2 drivers, in case of v4l1 drivers it will
-just pass calls through.
-
-Since those functions are emulations of the old V4L1 API, it shouldn't
-be used for new applications.
-
-
-libv4l2
-=======
-
-This library should be used for all modern V4L2 applications.
-
-It provides handles to call V4L2 open/ioctl/close/poll methods. Instead
-of just providing the raw output of the device, it enhances the calls in
-the sense that it will use libv4lconvert to provide more video formats
-and to enhance the image quality.
-
-In most cases, libv4l2 just passes the calls directly through to the
-v4l2 driver, intercepting the calls to
-:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>`,
-:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`,
-:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`,
-:ref:`VIDIOC_ENUM_FRAMESIZES <VIDIOC_ENUM_FRAMESIZES>` and
-:ref:`VIDIOC_ENUM_FRAMEINTERVALS <VIDIOC_ENUM_FRAMEINTERVALS>` in
-order to emulate the formats
-:ref:`V4L2_PIX_FMT_BGR24 <V4L2-PIX-FMT-BGR24>`,
-:ref:`V4L2_PIX_FMT_RGB24 <V4L2-PIX-FMT-RGB24>`,
-:ref:`V4L2_PIX_FMT_YUV420 <V4L2-PIX-FMT-YUV420>`, and
-:ref:`V4L2_PIX_FMT_YVU420 <V4L2-PIX-FMT-YVU420>`, if they aren't
-available in the driver. :ref:`VIDIOC_ENUM_FMT <VIDIOC_ENUM_FMT>`
-keeps enumerating the hardware supported formats, plus the emulated
-formats offered by libv4l at the end.
-
-
-.. _libv4l-ops:
-
-Libv4l device control functions
--------------------------------
-
-The common file operation methods are provided by libv4l.
-
-Those functions operate just like glibc
-open/close/dup/ioctl/read/mmap/munmap:
-
-- :c:type:`int v4l2_open(const char *file, int oflag, ...)` - operates like the
- standard :ref:`open() <func-open>` function.
-
-- :c:type:`int v4l2_close(int fd)` - operates like the standard
- :ref:`close() <func-close>` function.
-
-- :c:type:`int v4l2_dup(int fd)` - operates like the standard dup() function,
- duplicating a file handler.
-
-- :c:type:`int v4l2_ioctl (int fd, unsigned long int request, ...)` - operates
- like the standard :ref:`ioctl() <func-ioctl>` function.
-
-- :c:type:`int v4l2_read (int fd, void* buffer, size_t n)` - operates like the
- standard :ref:`read() <func-read>` function.
-
-- :c:type:`void v4l2_mmap(void *start, size_t length, int prot, int flags, int
- fd, int64_t offset);` - operates like the standard
- :ref:`mmap() <func-mmap>` function.
-
-- :c:type:`int v4l2_munmap(void *_start, size_t length);` - operates like the
- standard :ref:`munmap() <func-munmap>` function.
-
-Those functions provide additional control:
-
-- :c:type:`int v4l2_fd_open(int fd, int v4l2_flags)` - opens an already opened
- fd for further use through v4l2lib and possibly modify libv4l2's
- default behavior through the v4l2_flags argument. Currently,
- v4l2_flags can be ``V4L2_DISABLE_CONVERSION``, to disable format
- conversion.
-
-- :c:type:`int v4l2_set_control(int fd, int cid, int value)` - This function
- takes a value of 0 - 65535, and then scales that range to the actual
- range of the given v4l control id, and then if the cid exists and is
- not locked sets the cid to the scaled value.
-
-- :c:type:`int v4l2_get_control(int fd, int cid)` - This function returns a
- value of 0 - 65535, scaled to from the actual range of the given v4l
- control id. when the cid does not exist, could not be accessed for
- some reason, or some error occurred 0 is returned.
-
-
-v4l1compat.so wrapper library
-=============================
-
-This library intercepts calls to open/close/ioctl/mmap/mmunmap
-operations and redirects them to the libv4l counterparts, by using
-LD_PRELOAD=/usr/lib/v4l1compat.so. It also emulates V4L1 calls via V4L2
-API.
-
-It allows usage of binary legacy applications that still don't use
-libv4l.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _libv4l:
-
-************************
-Libv4l Userspace Library
-************************
-
-
-.. toctree::
- :maxdepth: 1
-
- libv4l-introduction
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _mmap:
-
-******************************
-Streaming I/O (Memory Mapping)
-******************************
-
-Input and output devices support this I/O method when the
-``V4L2_CAP_STREAMING`` flag in the ``capabilities`` field of struct
-:ref:`v4l2_capability <v4l2-capability>` returned by the
-:ref:`VIDIOC_QUERYCAP` ioctl is set. There are two
-streaming methods, to determine if the memory mapping flavor is
-supported applications must call the
-:ref:`VIDIOC_REQBUFS` ioctl.
-
-Streaming is an I/O method where only pointers to buffers are exchanged
-between application and driver, the data itself is not copied. Memory
-mapping is primarily intended to map buffers in device memory into the
-application's address space. Device memory can be for example the video
-memory on a graphics card with a video capture add-on. However, being
-the most efficient I/O method available for a long time, many other
-drivers support streaming as well, allocating buffers in DMA-able main
-memory.
-
-A driver can support many sets of buffers. Each set is identified by a
-unique buffer type value. The sets are independent and each set can hold
-a different type of data. To access different sets at the same time
-different file descriptors must be used. [1]_
-
-To allocate device buffers applications call the
-:ref:`VIDIOC_REQBUFS` ioctl with the desired number
-of buffers and buffer type, for example ``V4L2_BUF_TYPE_VIDEO_CAPTURE``.
-This ioctl can also be used to change the number of buffers or to free
-the allocated memory, provided none of the buffers are still mapped.
-
-Before applications can access the buffers they must map them into their
-address space with the :ref:`mmap() <func-mmap>` function. The
-location of the buffers in device memory can be determined with the
-:ref:`VIDIOC_QUERYBUF` ioctl. In the single-planar
-API case, the ``m.offset`` and ``length`` returned in a struct
-:ref:`v4l2_buffer <v4l2-buffer>` are passed as sixth and second
-parameter to the :ref:`mmap() <func-mmap>` function. When using the
-multi-planar API, struct :ref:`v4l2_buffer <v4l2-buffer>` contains an
-array of struct :ref:`v4l2_plane <v4l2-plane>` structures, each
-containing its own ``m.offset`` and ``length``. When using the
-multi-planar API, every plane of every buffer has to be mapped
-separately, so the number of calls to :ref:`mmap() <func-mmap>` should
-be equal to number of buffers times number of planes in each buffer. The
-offset and length values must not be modified. Remember, the buffers are
-allocated in physical memory, as opposed to virtual memory, which can be
-swapped out to disk. Applications should free the buffers as soon as
-possible with the :ref:`munmap() <func-munmap>` function.
-
-
-.. code-block:: c
- :caption: Example 3.1. Mapping buffers in the single-planar API
-
- struct v4l2_requestbuffers reqbuf;
- struct {
- void *start;
- size_t length;
- } *buffers;
- unsigned int i;
-
- memset(&reqbuf, 0, sizeof(reqbuf));
- reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- reqbuf.memory = V4L2_MEMORY_MMAP;
- reqbuf.count = 20;
-
- if (-1 == ioctl (fd, VIDIOC_REQBUFS, &reqbuf)) {
- if (errno == EINVAL)
- printf("Video capturing or mmap-streaming is not supported\\n");
- else
- perror("VIDIOC_REQBUFS");
-
- exit(EXIT_FAILURE);
- }
-
- /* We want at least five buffers. */
-
- if (reqbuf.count < 5) {
- /* You may need to free the buffers here. */
- printf("Not enough buffer memory\\n");
- exit(EXIT_FAILURE);
- }
-
- buffers = calloc(reqbuf.count, sizeof(*buffers));
- assert(buffers != NULL);
-
- for (i = 0; i < reqbuf.count; i++) {
- struct v4l2_buffer buffer;
-
- memset(&buffer, 0, sizeof(buffer));
- buffer.type = reqbuf.type;
- buffer.memory = V4L2_MEMORY_MMAP;
- buffer.index = i;
-
- if (-1 == ioctl (fd, VIDIOC_QUERYBUF, &buffer)) {
- perror("VIDIOC_QUERYBUF");
- exit(EXIT_FAILURE);
- }
-
- buffers[i].length = buffer.length; /* remember for munmap() */
-
- buffers[i].start = mmap(NULL, buffer.length,
- PROT_READ | PROT_WRITE, /* recommended */
- MAP_SHARED, /* recommended */
- fd, buffer.m.offset);
-
- if (MAP_FAILED == buffers[i].start) {
- /* If you do not exit here you should unmap() and free()
- the buffers mapped so far. */
- perror("mmap");
- exit(EXIT_FAILURE);
- }
- }
-
- /* Cleanup. */
-
- for (i = 0; i < reqbuf.count; i++)
- munmap(buffers[i].start, buffers[i].length);
-
-
-.. code-block:: c
- :caption: Example 3.2. Mapping buffers in the multi-planar API
-
- struct v4l2_requestbuffers reqbuf;
- /* Our current format uses 3 planes per buffer */
- #define FMT_NUM_PLANES = 3
-
- struct {
- void *start[FMT_NUM_PLANES];
- size_t length[FMT_NUM_PLANES];
- } *buffers;
- unsigned int i, j;
-
- memset(&reqbuf, 0, sizeof(reqbuf));
- reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE;
- reqbuf.memory = V4L2_MEMORY_MMAP;
- reqbuf.count = 20;
-
- if (ioctl(fd, VIDIOC_REQBUFS, &reqbuf) < 0) {
- if (errno == EINVAL)
- printf("Video capturing or mmap-streaming is not supported\\n");
- else
- perror("VIDIOC_REQBUFS");
-
- exit(EXIT_FAILURE);
- }
-
- /* We want at least five buffers. */
-
- if (reqbuf.count < 5) {
- /* You may need to free the buffers here. */
- printf("Not enough buffer memory\\n");
- exit(EXIT_FAILURE);
- }
-
- buffers = calloc(reqbuf.count, sizeof(*buffers));
- assert(buffers != NULL);
-
- for (i = 0; i < reqbuf.count; i++) {
- struct v4l2_buffer buffer;
- struct v4l2_plane planes[FMT_NUM_PLANES];
-
- memset(&buffer, 0, sizeof(buffer));
- buffer.type = reqbuf.type;
- buffer.memory = V4L2_MEMORY_MMAP;
- buffer.index = i;
- /* length in struct v4l2_buffer in multi-planar API stores the size
- * of planes array. */
- buffer.length = FMT_NUM_PLANES;
- buffer.m.planes = planes;
-
- if (ioctl(fd, VIDIOC_QUERYBUF, &buffer) < 0) {
- perror("VIDIOC_QUERYBUF");
- exit(EXIT_FAILURE);
- }
-
- /* Every plane has to be mapped separately */
- for (j = 0; j < FMT_NUM_PLANES; j++) {
- buffers[i].length[j] = buffer.m.planes[j].length; /* remember for munmap() */
-
- buffers[i].start[j] = mmap(NULL, buffer.m.planes[j].length,
- PROT_READ | PROT_WRITE, /* recommended */
- MAP_SHARED, /* recommended */
- fd, buffer.m.planes[j].m.offset);
-
- if (MAP_FAILED == buffers[i].start[j]) {
- /* If you do not exit here you should unmap() and free()
- the buffers and planes mapped so far. */
- perror("mmap");
- exit(EXIT_FAILURE);
- }
- }
- }
-
- /* Cleanup. */
-
- for (i = 0; i < reqbuf.count; i++)
- for (j = 0; j < FMT_NUM_PLANES; j++)
- munmap(buffers[i].start[j], buffers[i].length[j]);
-
-Conceptually streaming drivers maintain two buffer queues, an incoming
-and an outgoing queue. They separate the synchronous capture or output
-operation locked to a video clock from the application which is subject
-to random disk or network delays and preemption by other processes,
-thereby reducing the probability of data loss. The queues are organized
-as FIFOs, buffers will be output in the order enqueued in the incoming
-FIFO, and were captured in the order dequeued from the outgoing FIFO.
-
-The driver may require a minimum number of buffers enqueued at all times
-to function, apart of this no limit exists on the number of buffers
-applications can enqueue in advance, or dequeue and process. They can
-also enqueue in a different order than buffers have been dequeued, and
-the driver can *fill* enqueued *empty* buffers in any order. [2]_ The
-index number of a buffer (struct :ref:`v4l2_buffer <v4l2-buffer>`
-``index``) plays no role here, it only identifies the buffer.
-
-Initially all mapped buffers are in dequeued state, inaccessible by the
-driver. For capturing applications it is customary to first enqueue all
-mapped buffers, then to start capturing and enter the read loop. Here
-the application waits until a filled buffer can be dequeued, and
-re-enqueues the buffer when the data is no longer needed. Output
-applications fill and enqueue buffers, when enough buffers are stacked
-up the output is started with :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`.
-In the write loop, when the application runs out of free buffers, it
-must wait until an empty buffer can be dequeued and reused.
-
-To enqueue and dequeue a buffer applications use the :ref:`VIDIOC_QBUF`
-and :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. The status of a buffer
-being mapped, enqueued, full or empty can be determined at any time
-using the :ref:`VIDIOC_QUERYBUF` ioctl. Two methods exist to suspend
-execution of the application until one or more buffers can be dequeued.
-By default :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` blocks when no buffer is
-in the outgoing queue. When the ``O_NONBLOCK`` flag was given to the
-:ref:`open() <func-open>` function, :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`
-returns immediately with an ``EAGAIN`` error code when no buffer is
-available. The :ref:`select() <func-select>` or :ref:`poll()
-<func-poll>` functions are always available.
-
-To start and stop capturing or output applications call the
-:ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and :ref:`VIDIOC_STREAMOFF
-<VIDIOC_STREAMON>` ioctl. Note :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`
-removes all buffers from both queues as a side effect. Since there is
-no notion of doing anything "now" on a multitasking system, if an
-application needs to synchronize with another event it should examine
-the struct ::ref:`v4l2_buffer <v4l2-buffer>` ``timestamp`` of captured
-or outputted buffers.
-
-Drivers implementing memory mapping I/O must support the
-:ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, :ref:`VIDIOC_QUERYBUF
-<VIDIOC_QUERYBUF>`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_DQBUF
-<VIDIOC_QBUF>`, :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`
-and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls, the :ref:`mmap()
-<func-mmap>`, :ref:`munmap() <func-munmap>`, :ref:`select()
-<func-select>` and :ref:`poll() <func-poll>` function. [3]_
-
-[capture example]
-
-.. [1]
- One could use one file descriptor and set the buffer type field
- accordingly when calling :ref:`VIDIOC_QBUF` etc.,
- but it makes the :ref:`select() <func-select>` function ambiguous. We also
- like the clean approach of one file descriptor per logical stream.
- Video overlay for example is also a logical stream, although the CPU
- is not needed for continuous operation.
-
-.. [2]
- Random enqueue order permits applications processing images out of
- order (such as video codecs) to return buffers earlier, reducing the
- probability of data loss. Random fill order allows drivers to reuse
- buffers on a LIFO-basis, taking advantage of caches holding
- scatter-gather lists and the like.
-
-.. [3]
- At the driver level :ref:`select() <func-select>` and :ref:`poll() <func-poll>` are
- the same, and :ref:`select() <func-select>` is too important to be optional.
- The rest should be evident.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _open:
-
-***************************
-Opening and Closing Devices
-***************************
-
-
-Device Naming
-=============
-
-V4L2 drivers are implemented as kernel modules, loaded manually by the
-system administrator or automatically when a device is first discovered.
-The driver modules plug into the "videodev" kernel module. It provides
-helper functions and a common application interface specified in this
-document.
-
-Each driver thus loaded registers one or more device nodes with major
-number 81 and a minor number between 0 and 255. Minor numbers are
-allocated dynamically unless the kernel is compiled with the kernel
-option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers
-are allocated in ranges depending on the device node type (video, radio,
-etc.).
-
-Many drivers support "video_nr", "radio_nr" or "vbi_nr" module
-options to select specific video/radio/vbi node numbers. This allows the
-user to request that the device node is named e.g. /dev/video5 instead
-of leaving it to chance. When the driver supports multiple devices of
-the same type more than one device node number can be assigned,
-separated by commas:
-
-.. code-block:: none
-
- # modprobe mydriver video_nr=0,1 radio_nr=0,1
-
-In ``/etc/modules.conf`` this may be written as:
-
-::
-
- options mydriver video_nr=0,1 radio_nr=0,1
-
-When no device node number is given as module option the driver supplies
-a default.
-
-Normally udev will create the device nodes in /dev automatically for
-you. If udev is not installed, then you need to enable the
-CONFIG_VIDEO_FIXED_MINOR_RANGES kernel option in order to be able to
-correctly relate a minor number to a device node number. I.e., you need
-to be certain that minor number 5 maps to device node name video5. With
-this kernel option different device types have different minor number
-ranges. These ranges are listed in :ref:`devices`.
-
-The creation of character special files (with mknod) is a privileged
-operation and devices cannot be opened by major and minor number. That
-means applications cannot *reliable* scan for loaded or installed
-drivers. The user must enter a device name, or the application can try
-the conventional device names.
-
-
-.. _related:
-
-Related Devices
-===============
-
-Devices can support several functions. For example video capturing, VBI
-capturing and radio support.
-
-The V4L2 API creates different nodes for each of these functions.
-
-The V4L2 API was designed with the idea that one device node could
-support all functions. However, in practice this never worked: this
-'feature' was never used by applications and many drivers did not
-support it and if they did it was certainly never tested. In addition,
-switching a device node between different functions only works when
-using the streaming I/O API, not with the
-:ref:`read() <func-read>`/\ :ref:`write() <func-write>` API.
-
-Today each device node supports just one function.
-
-Besides video input or output the hardware may also support audio
-sampling or playback. If so, these functions are implemented as ALSA PCM
-devices with optional ALSA audio mixer devices.
-
-One problem with all these devices is that the V4L2 API makes no
-provisions to find these related devices. Some really complex devices
-use the Media Controller (see :ref:`media_controller`) which can be
-used for this purpose. But most drivers do not use it, and while some
-code exists that uses sysfs to discover related devices (see
-libmedia_dev in the
-`v4l-utils <http://git.linuxtv.org/cgit.cgi/v4l-utils.git/>`__ git
-repository), there is no library yet that can provide a single API
-towards both Media Controller-based devices and devices that do not use
-the Media Controller. If you want to work on this please write to the
-linux-media mailing list:
-`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__.
-
-
-Multiple Opens
-==============
-
-V4L2 devices can be opened more than once. [1]_ When this is supported
-by the driver, users can for example start a "panel" application to
-change controls like brightness or audio volume, while another
-application captures video and audio. In other words, panel applications
-are comparable to an ALSA audio mixer application. Just opening a V4L2
-device should not change the state of the device. [2]_
-
-Once an application has allocated the memory buffers needed for
-streaming data (by calling the :ref:`VIDIOC_REQBUFS`
-or :ref:`VIDIOC_CREATE_BUFS` ioctls, or
-implicitly by calling the :ref:`read() <func-read>` or
-:ref:`write() <func-write>` functions) that application (filehandle)
-becomes the owner of the device. It is no longer allowed to make changes
-that would affect the buffer sizes (e.g. by calling the
-:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl) and other applications are
-no longer allowed to allocate buffers or start or stop streaming. The
-EBUSY error code will be returned instead.
-
-Merely opening a V4L2 device does not grant exclusive access. [3]_
-Initiating data exchange however assigns the right to read or write the
-requested type of data, and to change related properties, to this file
-descriptor. Applications can request additional access privileges using
-the priority mechanism described in :ref:`app-pri`.
-
-
-Shared Data Streams
-===================
-
-V4L2 drivers should not support multiple applications reading or writing
-the same data stream on a device by copying buffers, time multiplexing
-or similar means. This is better handled by a proxy application in user
-space.
-
-
-Functions
-=========
-
-To open and close V4L2 devices applications use the
-:ref:`open() <func-open>` and :ref:`close() <func-close>` function,
-respectively. Devices are programmed using the
-:ref:`ioctl() <func-ioctl>` function as explained in the following
-sections.
-
-.. [1]
- There are still some old and obscure drivers that have not been
- updated to allow for multiple opens. This implies that for such
- drivers :ref:`open() <func-open>` can return an ``EBUSY`` error code
- when the device is already in use.
-
-.. [2]
- Unfortunately, opening a radio device often switches the state of the
- device to radio mode in many drivers. This behavior should be fixed
- eventually as it violates the V4L2 specification.
-
-.. [3]
- Drivers could recognize the ``O_EXCL`` open flag. Presently this is
- not required, so applications cannot know if it really works.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-******************************
-Single-planar format structure
-******************************
-
-
-.. _v4l2-pix-format:
-
-.. flat-table:: struct v4l2_pix_format
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``width``
-
- - Image width in pixels.
-
- - .. row 2
-
- - __u32
-
- - ``height``
-
- - Image height in pixels. If ``field`` is one of ``V4L2_FIELD_TOP``,
- ``V4L2_FIELD_BOTTOM`` or ``V4L2_FIELD_ALTERNATE`` then height
- refers to the number of lines in the field, otherwise it refers to
- the number of lines in the frame (which is twice the field height
- for interlaced formats).
-
- - .. row 3
-
- - :cspan:`2` Applications set these fields to request an image
- size, drivers return the closest possible values. In case of
- planar formats the ``width`` and ``height`` applies to the largest
- plane. To avoid ambiguities drivers must return values rounded up
- to a multiple of the scale factor of any smaller planes. For
- example when the image format is YUV 4:2:0, ``width`` and
- ``height`` must be multiples of two.
-
- - .. row 4
-
- - __u32
-
- - ``pixelformat``
-
- - The pixel format or type of compression, set by the application.
- This is a little endian
- :ref:`four character code <v4l2-fourcc>`. V4L2 defines standard
- RGB formats in :ref:`rgb-formats`, YUV formats in
- :ref:`yuv-formats`, and reserved codes in
- :ref:`reserved-formats`
-
- - .. row 5
-
- - enum :ref:`v4l2_field <v4l2-field>`
-
- - ``field``
-
- - Video images are typically interlaced. Applications can request to
- capture or output only the top or bottom field, or both fields
- interlaced or sequentially stored in one buffer or alternating in
- separate buffers. Drivers return the actual field order selected.
- For more details on fields see :ref:`field-order`.
-
- - .. row 6
-
- - __u32
-
- - ``bytesperline``
-
- - Distance in bytes between the leftmost pixels in two adjacent
- lines.
-
- - .. row 7
-
- - :cspan:`2`
-
- Both applications and drivers can set this field to request
- padding bytes at the end of each line. Drivers however may ignore
- the value requested by the application, returning ``width`` times
- bytes per pixel or a larger value required by the hardware. That
- implies applications can just set this field to zero to get a
- reasonable default.
-
- Video hardware may access padding bytes, therefore they must
- reside in accessible memory. Consider cases where padding bytes
- after the last line of an image cross a system page boundary.
- Input devices may write padding bytes, the value is undefined.
- Output devices ignore the contents of padding bytes.
-
- When the image format is planar the ``bytesperline`` value applies
- to the first plane and is divided by the same factor as the
- ``width`` field for the other planes. For example the Cb and Cr
- planes of a YUV 4:2:0 image have half as many padding bytes
- following each line as the Y plane. To avoid ambiguities drivers
- must return a ``bytesperline`` value rounded up to a multiple of
- the scale factor.
-
- For compressed formats the ``bytesperline`` value makes no sense.
- Applications and drivers must set this to 0 in that case.
-
- - .. row 8
-
- - __u32
-
- - ``sizeimage``
-
- - Size in bytes of the buffer to hold a complete image, set by the
- driver. Usually this is ``bytesperline`` times ``height``. When
- the image consists of variable length compressed data this is the
- maximum number of bytes required to hold an image.
-
- - .. row 9
-
- - enum :ref:`v4l2_colorspace <v4l2-colorspace>`
-
- - ``colorspace``
-
- - This information supplements the ``pixelformat`` and must be set
- by the driver for capture streams and by the application for
- output streams, see :ref:`colorspaces`.
-
- - .. row 10
-
- - __u32
-
- - ``priv``
-
- - This field indicates whether the remaining fields of the
- :ref:`struct v4l2_pix_format <v4l2-pix-format>` structure, also called the
- extended fields, are valid. When set to
- ``V4L2_PIX_FMT_PRIV_MAGIC``, it indicates that the extended fields
- have been correctly initialized. When set to any other value it
- indicates that the extended fields contain undefined values.
-
- Applications that wish to use the pixel format extended fields
- must first ensure that the feature is supported by querying the
- device for the :ref:`V4L2_CAP_EXT_PIX_FORMAT <querycap>`
- capability. If the capability isn't set the pixel format extended
- fields are not supported and using the extended fields will lead
- to undefined results.
-
- To use the extended fields, applications must set the ``priv``
- field to ``V4L2_PIX_FMT_PRIV_MAGIC``, initialize all the extended
- fields and zero the unused bytes of the
- :ref:`struct v4l2_format <v4l2-format>` ``raw_data`` field.
-
- When the ``priv`` field isn't set to ``V4L2_PIX_FMT_PRIV_MAGIC``
- drivers must act as if all the extended fields were set to zero.
- On return drivers must set the ``priv`` field to
- ``V4L2_PIX_FMT_PRIV_MAGIC`` and all the extended fields to
- applicable values.
-
- - .. row 11
-
- - __u32
-
- - ``flags``
-
- - Flags set by the application or driver, see :ref:`format-flags`.
-
- - .. row 12
-
- - enum :ref:`v4l2_ycbcr_encoding <v4l2-ycbcr-encoding>`
-
- - ``ycbcr_enc``
-
- - This information supplements the ``colorspace`` and must be set by
- the driver for capture streams and by the application for output
- streams, see :ref:`colorspaces`.
-
- - .. row 13
-
- - enum :ref:`v4l2_quantization <v4l2-quantization>`
-
- - ``quantization``
-
- - This information supplements the ``colorspace`` and must be set by
- the driver for capture streams and by the application for output
- streams, see :ref:`colorspaces`.
-
- - .. row 14
-
- - enum :ref:`v4l2_xfer_func <v4l2-xfer-func>`
-
- - ``xfer_func``
-
- - This information supplements the ``colorspace`` and must be set by
- the driver for capture streams and by the application for output
- streams, see :ref:`colorspaces`.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-******************************
-Multi-planar format structures
-******************************
-
-The :ref:`struct v4l2_plane_pix_format <v4l2-plane-pix-format>` structures define size
-and layout for each of the planes in a multi-planar format. The
-:ref:`struct v4l2_pix_format_mplane <v4l2-pix-format-mplane>` structure contains
-information common to all planes (such as image width and height) and an
-array of :ref:`struct v4l2_plane_pix_format <v4l2-plane-pix-format>` structures,
-describing all planes of that format.
-
-
-.. _v4l2-plane-pix-format:
-
-.. flat-table:: struct v4l2_plane_pix_format
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``sizeimage``
-
- - Maximum size in bytes required for image data in this plane.
-
- - .. row 2
-
- - __u32
-
- - ``bytesperline``
-
- - Distance in bytes between the leftmost pixels in two adjacent
- lines. See struct :ref:`v4l2_pix_format <v4l2-pix-format>`.
-
- - .. row 3
-
- - __u16
-
- - ``reserved[6]``
-
- - Reserved for future extensions. Should be zeroed by drivers and
- applications.
-
-
-
-.. _v4l2-pix-format-mplane:
-
-.. flat-table:: struct v4l2_pix_format_mplane
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``width``
-
- - Image width in pixels. See struct
- :ref:`v4l2_pix_format <v4l2-pix-format>`.
-
- - .. row 2
-
- - __u32
-
- - ``height``
-
- - Image height in pixels. See struct
- :ref:`v4l2_pix_format <v4l2-pix-format>`.
-
- - .. row 3
-
- - __u32
-
- - ``pixelformat``
-
- - The pixel format. Both single- and multi-planar four character
- codes can be used.
-
- - .. row 4
-
- - enum :ref:`v4l2_field <v4l2-field>`
-
- - ``field``
-
- - See struct :ref:`v4l2_pix_format <v4l2-pix-format>`.
-
- - .. row 5
-
- - enum :ref:`v4l2_colorspace <v4l2-colorspace>`
-
- - ``colorspace``
-
- - See struct :ref:`v4l2_pix_format <v4l2-pix-format>`.
-
- - .. row 6
-
- - struct :ref:`v4l2_plane_pix_format <v4l2-plane-pix-format>`
-
- - ``plane_fmt[VIDEO_MAX_PLANES]``
-
- - An array of structures describing format of each plane this pixel
- format consists of. The number of valid entries in this array has
- to be put in the ``num_planes`` field.
-
- - .. row 7
-
- - __u8
-
- - ``num_planes``
-
- - Number of planes (i.e. separate memory buffers) for this format
- and the number of valid entries in the ``plane_fmt`` array.
-
- - .. row 8
-
- - __u8
-
- - ``flags``
-
- - Flags set by the application or driver, see :ref:`format-flags`.
-
- - .. row 9
-
- - enum :ref:`v4l2_ycbcr_encoding <v4l2-ycbcr-encoding>`
-
- - ``ycbcr_enc``
-
- - This information supplements the ``colorspace`` and must be set by
- the driver for capture streams and by the application for output
- streams, see :ref:`colorspaces`.
-
- - .. row 10
-
- - enum :ref:`v4l2_quantization <v4l2-quantization>`
-
- - ``quantization``
-
- - This information supplements the ``colorspace`` and must be set by
- the driver for capture streams and by the application for output
- streams, see :ref:`colorspaces`.
-
- - .. row 11
-
- - enum :ref:`v4l2_xfer_func <v4l2-xfer-func>`
-
- - ``xfer_func``
-
- - This information supplements the ``colorspace`` and must be set by
- the driver for capture streams and by the application for output
- streams, see :ref:`colorspaces`.
-
- - .. row 12
-
- - __u8
-
- - ``reserved[7]``
-
- - Reserved for future extensions. Should be zeroed by drivers and
- applications.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-**********************
-Standard Image Formats
-**********************
-
-In order to exchange images between drivers and applications, it is
-necessary to have standard image data formats which both sides will
-interpret the same way. V4L2 includes several such formats, and this
-section is intended to be an unambiguous specification of the standard
-image data formats in V4L2.
-
-V4L2 drivers are not limited to these formats, however. Driver-specific
-formats are possible. In that case the application may depend on a codec
-to convert images to one of the standard formats when needed. But the
-data can still be stored and retrieved in the proprietary format. For
-example, a device may support a proprietary compressed format.
-Applications can still capture and save the data in the compressed
-format, saving much disk space, and later use a codec to convert the
-images to the X Windows screen format when the video is to be displayed.
-
-Even so, ultimately, some standard formats are needed, so the V4L2
-specification would not be complete without well-defined standard
-formats.
-
-The V4L2 standard formats are mainly uncompressed formats. The pixels
-are always arranged in memory from left to right, and from top to
-bottom. The first byte of data in the image buffer is always for the
-leftmost pixel of the topmost row. Following that is the pixel
-immediately to its right, and so on until the end of the top row of
-pixels. Following the rightmost pixel of the row there may be zero or
-more bytes of padding to guarantee that each row of pixel data has a
-certain alignment. Following the pad bytes, if any, is data for the
-leftmost pixel of the second row from the top, and so on. The last row
-has just as many pad bytes after it as the other rows.
-
-In V4L2 each format has an identifier which looks like ``PIX_FMT_XXX``,
-defined in the :ref:`videodev2.h <videodev>` header file. These
-identifiers represent
-:ref:`four character (FourCC) codes <v4l2-fourcc>` which are also
-listed below, however they are not the same as those used in the Windows
-world.
-
-For some formats, data is stored in separate, discontiguous memory
-buffers. Those formats are identified by a separate set of FourCC codes
-and are referred to as "multi-planar formats". For example, a
-:ref:`YUV422 <V4L2-PIX-FMT-YUV422M>` frame is normally stored in one
-memory buffer, but it can also be placed in two or three separate
-buffers, with Y component in one buffer and CbCr components in another
-in the 2-planar version or with each component in its own buffer in the
-3-planar case. Those sub-buffers are referred to as "*planes*".
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-****************************
-Defining Colorspaces in V4L2
-****************************
-
-In V4L2 colorspaces are defined by four values. The first is the
-colorspace identifier (enum :ref:`v4l2_colorspace <v4l2-colorspace>`)
-which defines the chromaticities, the default transfer function, the
-default Y'CbCr encoding and the default quantization method. The second
-is the transfer function identifier (enum
-:ref:`v4l2_xfer_func <v4l2-xfer-func>`) to specify non-standard
-transfer functions. The third is the Y'CbCr encoding identifier (enum
-:ref:`v4l2_ycbcr_encoding <v4l2-ycbcr-encoding>`) to specify
-non-standard Y'CbCr encodings and the fourth is the quantization
-identifier (enum :ref:`v4l2_quantization <v4l2-quantization>`) to
-specify non-standard quantization methods. Most of the time only the
-colorspace field of struct :ref:`v4l2_pix_format <v4l2-pix-format>`
-or struct :ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>`
-needs to be filled in. Note that the default R'G'B' quantization is full
-range for all colorspaces except for BT.2020 which uses limited range
-R'G'B' quantization.
-
-
-.. _v4l2-colorspace:
-
-.. flat-table:: V4L2 Colorspaces
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - Identifier
-
- - Details
-
- - .. row 2
-
- - ``V4L2_COLORSPACE_DEFAULT``
-
- - The default colorspace. This can be used by applications to let
- the driver fill in the colorspace.
-
- - .. row 3
-
- - ``V4L2_COLORSPACE_SMPTE170M``
-
- - See :ref:`col-smpte-170m`.
-
- - .. row 4
-
- - ``V4L2_COLORSPACE_REC709``
-
- - See :ref:`col-rec709`.
-
- - .. row 5
-
- - ``V4L2_COLORSPACE_SRGB``
-
- - See :ref:`col-srgb`.
-
- - .. row 6
-
- - ``V4L2_COLORSPACE_ADOBERGB``
-
- - See :ref:`col-adobergb`.
-
- - .. row 7
-
- - ``V4L2_COLORSPACE_BT2020``
-
- - See :ref:`col-bt2020`.
-
- - .. row 8
-
- - ``V4L2_COLORSPACE_DCI_P3``
-
- - See :ref:`col-dcip3`.
-
- - .. row 9
-
- - ``V4L2_COLORSPACE_SMPTE240M``
-
- - See :ref:`col-smpte-240m`.
-
- - .. row 10
-
- - ``V4L2_COLORSPACE_470_SYSTEM_M``
-
- - See :ref:`col-sysm`.
-
- - .. row 11
-
- - ``V4L2_COLORSPACE_470_SYSTEM_BG``
-
- - See :ref:`col-sysbg`.
-
- - .. row 12
-
- - ``V4L2_COLORSPACE_JPEG``
-
- - See :ref:`col-jpeg`.
-
- - .. row 13
-
- - ``V4L2_COLORSPACE_RAW``
-
- - The raw colorspace. This is used for raw image capture where the
- image is minimally processed and is using the internal colorspace
- of the device. The software that processes an image using this
- 'colorspace' will have to know the internals of the capture
- device.
-
-
-
-.. _v4l2-xfer-func:
-
-.. flat-table:: V4L2 Transfer Function
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - Identifier
-
- - Details
-
- - .. row 2
-
- - ``V4L2_XFER_FUNC_DEFAULT``
-
- - Use the default transfer function as defined by the colorspace.
-
- - .. row 3
-
- - ``V4L2_XFER_FUNC_709``
-
- - Use the Rec. 709 transfer function.
-
- - .. row 4
-
- - ``V4L2_XFER_FUNC_SRGB``
-
- - Use the sRGB transfer function.
-
- - .. row 5
-
- - ``V4L2_XFER_FUNC_ADOBERGB``
-
- - Use the AdobeRGB transfer function.
-
- - .. row 6
-
- - ``V4L2_XFER_FUNC_SMPTE240M``
-
- - Use the SMPTE 240M transfer function.
-
- - .. row 7
-
- - ``V4L2_XFER_FUNC_NONE``
-
- - Do not use a transfer function (i.e. use linear RGB values).
-
- - .. row 8
-
- - ``V4L2_XFER_FUNC_DCI_P3``
-
- - Use the DCI-P3 transfer function.
-
- - .. row 9
-
- - ``V4L2_XFER_FUNC_SMPTE2084``
-
- - Use the SMPTE 2084 transfer function.
-
-
-
-.. _v4l2-ycbcr-encoding:
-
-.. flat-table:: V4L2 Y'CbCr Encodings
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - Identifier
-
- - Details
-
- - .. row 2
-
- - ``V4L2_YCBCR_ENC_DEFAULT``
-
- - Use the default Y'CbCr encoding as defined by the colorspace.
-
- - .. row 3
-
- - ``V4L2_YCBCR_ENC_601``
-
- - Use the BT.601 Y'CbCr encoding.
-
- - .. row 4
-
- - ``V4L2_YCBCR_ENC_709``
-
- - Use the Rec. 709 Y'CbCr encoding.
-
- - .. row 5
-
- - ``V4L2_YCBCR_ENC_XV601``
-
- - Use the extended gamut xvYCC BT.601 encoding.
-
- - .. row 6
-
- - ``V4L2_YCBCR_ENC_XV709``
-
- - Use the extended gamut xvYCC Rec. 709 encoding.
-
- - .. row 7
-
- - ``V4L2_YCBCR_ENC_SYCC``
-
- - Use the extended gamut sYCC encoding.
-
- - .. row 8
-
- - ``V4L2_YCBCR_ENC_BT2020``
-
- - Use the default non-constant luminance BT.2020 Y'CbCr encoding.
-
- - .. row 9
-
- - ``V4L2_YCBCR_ENC_BT2020_CONST_LUM``
-
- - Use the constant luminance BT.2020 Yc'CbcCrc encoding.
-
-
-
-.. _v4l2-quantization:
-
-.. flat-table:: V4L2 Quantization Methods
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - Identifier
-
- - Details
-
- - .. row 2
-
- - ``V4L2_QUANTIZATION_DEFAULT``
-
- - Use the default quantization encoding as defined by the
- colorspace. This is always full range for R'G'B' (except for the
- BT.2020 colorspace) and usually limited range for Y'CbCr.
-
- - .. row 3
-
- - ``V4L2_QUANTIZATION_FULL_RANGE``
-
- - Use the full range quantization encoding. I.e. the range [0…1] is
- mapped to [0…255] (with possible clipping to [1…254] to avoid the
- 0x00 and 0xff values). Cb and Cr are mapped from [-0.5…0.5] to
- [0…255] (with possible clipping to [1…254] to avoid the 0x00 and
- 0xff values).
-
- - .. row 4
-
- - ``V4L2_QUANTIZATION_LIM_RANGE``
-
- - Use the limited range quantization encoding. I.e. the range [0…1]
- is mapped to [16…235]. Cb and Cr are mapped from [-0.5…0.5] to
- [16…240].
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-********************************
-Detailed Colorspace Descriptions
-********************************
-
-
-.. _col-smpte-170m:
-
-Colorspace SMPTE 170M (V4L2_COLORSPACE_SMPTE170M)
-=================================================
-
-The :ref:`smpte170m` standard defines the colorspace used by NTSC and
-PAL and by SDTV in general. The default transfer function is
-``V4L2_XFER_FUNC_709``. The default Y'CbCr encoding is
-``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is limited
-range. The chromaticities of the primary colors and the white reference
-are:
-
-
-
-.. flat-table:: SMPTE 170M Chromaticities
- :header-rows: 1
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - Color
-
- - x
-
- - y
-
- - .. row 2
-
- - Red
-
- - 0.630
-
- - 0.340
-
- - .. row 3
-
- - Green
-
- - 0.310
-
- - 0.595
-
- - .. row 4
-
- - Blue
-
- - 0.155
-
- - 0.070
-
- - .. row 5
-
- - White Reference (D65)
-
- - 0.3127
-
- - 0.3290
-
-
-The red, green and blue chromaticities are also often referred to as the
-SMPTE C set, so this colorspace is sometimes called SMPTE C as well.
-
-The transfer function defined for SMPTE 170M is the same as the one
-defined in Rec. 709.
-
- L' = -1.099(-L) :sup:`0.45` + 0.099 for L ≤ -0.018
-
- L' = 4.5L for -0.018 < L < 0.018
-
- L' = 1.099L :sup:`0.45` - 0.099 for L ≥ 0.018
-
-Inverse Transfer function:
-
- L = -((L' - 0.099) / -1.099) :sup:`1/0.45` for L' ≤ -0.081
-
- L = L' / 4.5 for -0.081 < L' < 0.081
-
- L = ((L' + 0.099) / 1.099) :sup:`1/0.45` for L' ≥ 0.081
-
-The luminance (Y') and color difference (Cb and Cr) are obtained with
-the following ``V4L2_YCBCR_ENC_601`` encoding:
-
- Y' = 0.299R' + 0.587G' + 0.114B'
-
- Cb = -0.169R' - 0.331G' + 0.5B'
-
- Cr = 0.5R' - 0.419G' - 0.081B'
-
-Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
-[-0.5…0.5]. This conversion to Y'CbCr is identical to the one defined in
-the :ref:`itu601` standard and this colorspace is sometimes called
-BT.601 as well, even though BT.601 does not mention any color primaries.
-
-The default quantization is limited range, but full range is possible
-although rarely seen.
-
-
-.. _col-rec709:
-
-Colorspace Rec. 709 (V4L2_COLORSPACE_REC709)
-============================================
-
-The :ref:`itu709` standard defines the colorspace used by HDTV in
-general. The default transfer function is ``V4L2_XFER_FUNC_709``. The
-default Y'CbCr encoding is ``V4L2_YCBCR_ENC_709``. The default Y'CbCr
-quantization is limited range. The chromaticities of the primary colors
-and the white reference are:
-
-
-
-.. flat-table:: Rec. 709 Chromaticities
- :header-rows: 1
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - Color
-
- - x
-
- - y
-
- - .. row 2
-
- - Red
-
- - 0.640
-
- - 0.330
-
- - .. row 3
-
- - Green
-
- - 0.300
-
- - 0.600
-
- - .. row 4
-
- - Blue
-
- - 0.150
-
- - 0.060
-
- - .. row 5
-
- - White Reference (D65)
-
- - 0.3127
-
- - 0.3290
-
-
-The full name of this standard is Rec. ITU-R BT.709-5.
-
-Transfer function. Normally L is in the range [0…1], but for the
-extended gamut xvYCC encoding values outside that range are allowed.
-
- L' = -1.099(-L) :sup:`0.45` + 0.099 for L ≤ -0.018
-
- L' = 4.5L for -0.018 < L < 0.018
-
- L' = 1.099L :sup:`0.45` - 0.099 for L ≥ 0.018
-
-Inverse Transfer function:
-
- L = -((L' - 0.099) / -1.099) :sup:`1/0.45` for L' ≤ -0.081
-
- L = L' / 4.5 for -0.081 < L' < 0.081
-
- L = ((L' + 0.099) / 1.099) :sup:`1/0.45` for L' ≥ 0.081
-
-The luminance (Y') and color difference (Cb and Cr) are obtained with
-the following ``V4L2_YCBCR_ENC_709`` encoding:
-
- Y' = 0.2126R' + 0.7152G' + 0.0722B'
-
- Cb = -0.1146R' - 0.3854G' + 0.5B'
-
- Cr = 0.5R' - 0.4542G' - 0.0458B'
-
-Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
-[-0.5…0.5].
-
-The default quantization is limited range, but full range is possible
-although rarely seen.
-
-The ``V4L2_YCBCR_ENC_709`` encoding described above is the default for
-this colorspace, but it can be overridden with ``V4L2_YCBCR_ENC_601``,
-in which case the BT.601 Y'CbCr encoding is used.
-
-Two additional extended gamut Y'CbCr encodings are also possible with
-this colorspace:
-
-The xvYCC 709 encoding (``V4L2_YCBCR_ENC_XV709``, :ref:`xvycc`) is
-similar to the Rec. 709 encoding, but it allows for R', G' and B' values
-that are outside the range [0…1]. The resulting Y', Cb and Cr values are
-scaled and offset:
-
- Y' = (219 / 256) * (0.2126R' + 0.7152G' + 0.0722B') + (16 / 256)
-
- Cb = (224 / 256) * (-0.1146R' - 0.3854G' + 0.5B')
-
- Cr = (224 / 256) * (0.5R' - 0.4542G' - 0.0458B')
-
-The xvYCC 601 encoding (``V4L2_YCBCR_ENC_XV601``, :ref:`xvycc`) is
-similar to the BT.601 encoding, but it allows for R', G' and B' values
-that are outside the range [0…1]. The resulting Y', Cb and Cr values are
-scaled and offset:
-
- Y' = (219 / 256) * (0.299R' + 0.587G' + 0.114B') + (16 / 256)
-
- Cb = (224 / 256) * (-0.169R' - 0.331G' + 0.5B')
-
- Cr = (224 / 256) * (0.5R' - 0.419G' - 0.081B')
-
-Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
-[-0.5…0.5]. The non-standard xvYCC 709 or xvYCC 601 encodings can be
-used by selecting ``V4L2_YCBCR_ENC_XV709`` or ``V4L2_YCBCR_ENC_XV601``.
-The xvYCC encodings always use full range quantization.
-
-
-.. _col-srgb:
-
-Colorspace sRGB (V4L2_COLORSPACE_SRGB)
-======================================
-
-The :ref:`srgb` standard defines the colorspace used by most webcams
-and computer graphics. The default transfer function is
-``V4L2_XFER_FUNC_SRGB``. The default Y'CbCr encoding is
-``V4L2_YCBCR_ENC_SYCC``. The default Y'CbCr quantization is full range.
-The chromaticities of the primary colors and the white reference are:
-
-
-
-.. flat-table:: sRGB Chromaticities
- :header-rows: 1
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - Color
-
- - x
-
- - y
-
- - .. row 2
-
- - Red
-
- - 0.640
-
- - 0.330
-
- - .. row 3
-
- - Green
-
- - 0.300
-
- - 0.600
-
- - .. row 4
-
- - Blue
-
- - 0.150
-
- - 0.060
-
- - .. row 5
-
- - White Reference (D65)
-
- - 0.3127
-
- - 0.3290
-
-
-These chromaticities are identical to the Rec. 709 colorspace.
-
-Transfer function. Note that negative values for L are only used by the
-Y'CbCr conversion.
-
- L' = -1.055(-L) :sup:`1/2.4` + 0.055 for L < -0.0031308
-
- L' = 12.92L for -0.0031308 ≤ L ≤ 0.0031308
-
- L' = 1.055L :sup:`1/2.4` - 0.055 for 0.0031308 < L ≤ 1
-
-Inverse Transfer function:
-
- L = -((-L' + 0.055) / 1.055) :sup:`2.4` for L' < -0.04045
-
- L = L' / 12.92 for -0.04045 ≤ L' ≤ 0.04045
-
- L = ((L' + 0.055) / 1.055) :sup:`2.4` for L' > 0.04045
-
-The luminance (Y') and color difference (Cb and Cr) are obtained with
-the following ``V4L2_YCBCR_ENC_SYCC`` encoding as defined by
-:ref:`sycc`:
-
- Y' = 0.2990R' + 0.5870G' + 0.1140B'
-
- Cb = -0.1687R' - 0.3313G' + 0.5B'
-
- Cr = 0.5R' - 0.4187G' - 0.0813B'
-
-Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
-[-0.5…0.5]. The ``V4L2_YCBCR_ENC_SYCC`` quantization is always full
-range. Although this Y'CbCr encoding looks very similar to the
-``V4L2_YCBCR_ENC_XV601`` encoding, it is not. The
-``V4L2_YCBCR_ENC_XV601`` scales and offsets the Y'CbCr values before
-quantization, but this encoding does not do that.
-
-
-.. _col-adobergb:
-
-Colorspace Adobe RGB (V4L2_COLORSPACE_ADOBERGB)
-===============================================
-
-The :ref:`adobergb` standard defines the colorspace used by computer
-graphics that use the AdobeRGB colorspace. This is also known as the
-:ref:`oprgb` standard. The default transfer function is
-``V4L2_XFER_FUNC_ADOBERGB``. The default Y'CbCr encoding is
-``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is limited
-range. The chromaticities of the primary colors and the white reference
-are:
-
-
-
-.. flat-table:: Adobe RGB Chromaticities
- :header-rows: 1
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - Color
-
- - x
-
- - y
-
- - .. row 2
-
- - Red
-
- - 0.6400
-
- - 0.3300
-
- - .. row 3
-
- - Green
-
- - 0.2100
-
- - 0.7100
-
- - .. row 4
-
- - Blue
-
- - 0.1500
-
- - 0.0600
-
- - .. row 5
-
- - White Reference (D65)
-
- - 0.3127
-
- - 0.3290
-
-
-
-Transfer function:
-
- L' = L :sup:`1/2.19921875`
-
-Inverse Transfer function:
-
- L = L' :sup:`2.19921875`
-
-The luminance (Y') and color difference (Cb and Cr) are obtained with
-the following ``V4L2_YCBCR_ENC_601`` encoding:
-
- Y' = 0.299R' + 0.587G' + 0.114B'
-
- Cb = -0.169R' - 0.331G' + 0.5B'
-
- Cr = 0.5R' - 0.419G' - 0.081B'
-
-Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
-[-0.5…0.5]. This transform is identical to one defined in SMPTE
-170M/BT.601. The Y'CbCr quantization is limited range.
-
-
-.. _col-bt2020:
-
-Colorspace BT.2020 (V4L2_COLORSPACE_BT2020)
-===========================================
-
-The :ref:`itu2020` standard defines the colorspace used by Ultra-high
-definition television (UHDTV). The default transfer function is
-``V4L2_XFER_FUNC_709``. The default Y'CbCr encoding is
-``V4L2_YCBCR_ENC_BT2020``. The default R'G'B' quantization is limited
-range (!), and so is the default Y'CbCr quantization. The chromaticities
-of the primary colors and the white reference are:
-
-
-
-.. flat-table:: BT.2020 Chromaticities
- :header-rows: 1
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - Color
-
- - x
-
- - y
-
- - .. row 2
-
- - Red
-
- - 0.708
-
- - 0.292
-
- - .. row 3
-
- - Green
-
- - 0.170
-
- - 0.797
-
- - .. row 4
-
- - Blue
-
- - 0.131
-
- - 0.046
-
- - .. row 5
-
- - White Reference (D65)
-
- - 0.3127
-
- - 0.3290
-
-
-
-Transfer function (same as Rec. 709):
-
- L' = 4.5L for 0 ≤ L < 0.018
-
- L' = 1.099L :sup:`0.45` - 0.099 for 0.018 ≤ L ≤ 1
-
-Inverse Transfer function:
-
- L = L' / 4.5 for L' < 0.081
-
- L = ((L' + 0.099) / 1.099) :sup:`1/0.45` for L' ≥ 0.081
-
-The luminance (Y') and color difference (Cb and Cr) are obtained with
-the following ``V4L2_YCBCR_ENC_BT2020`` encoding:
-
- Y' = 0.2627R' + 0.6780G' + 0.0593B'
-
- Cb = -0.1396R' - 0.3604G' + 0.5B'
-
- Cr = 0.5R' - 0.4598G' - 0.0402B'
-
-Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
-[-0.5…0.5]. The Y'CbCr quantization is limited range.
-
-There is also an alternate constant luminance R'G'B' to Yc'CbcCrc
-(``V4L2_YCBCR_ENC_BT2020_CONST_LUM``) encoding:
-
-Luma:
-
- Yc' = (0.2627R + 0.6780G + 0.0593B)'
-
-B' - Yc' ≤ 0:
-
- Cbc = (B' - Yc') / 1.9404
-
-B' - Yc' > 0:
-
- Cbc = (B' - Yc') / 1.5816
-
-R' - Yc' ≤ 0:
-
- Crc = (R' - Y') / 1.7184
-
-R' - Yc' > 0:
-
- Crc = (R' - Y') / 0.9936
-
-Yc' is clamped to the range [0…1] and Cbc and Crc are clamped to the
-range [-0.5…0.5]. The Yc'CbcCrc quantization is limited range.
-
-
-.. _col-dcip3:
-
-Colorspace DCI-P3 (V4L2_COLORSPACE_DCI_P3)
-==========================================
-
-The :ref:`smpte431` standard defines the colorspace used by cinema
-projectors that use the DCI-P3 colorspace. The default transfer function
-is ``V4L2_XFER_FUNC_DCI_P3``. The default Y'CbCr encoding is
-``V4L2_YCBCR_ENC_709``. Note that this colorspace does not specify a
-Y'CbCr encoding since it is not meant to be encoded to Y'CbCr. So this
-default Y'CbCr encoding was picked because it is the HDTV encoding. The
-default Y'CbCr quantization is limited range. The chromaticities of the
-primary colors and the white reference are:
-
-
-
-.. flat-table:: DCI-P3 Chromaticities
- :header-rows: 1
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - Color
-
- - x
-
- - y
-
- - .. row 2
-
- - Red
-
- - 0.6800
-
- - 0.3200
-
- - .. row 3
-
- - Green
-
- - 0.2650
-
- - 0.6900
-
- - .. row 4
-
- - Blue
-
- - 0.1500
-
- - 0.0600
-
- - .. row 5
-
- - White Reference
-
- - 0.3140
-
- - 0.3510
-
-
-
-Transfer function:
-
- L' = L :sup:`1/2.6`
-
-Inverse Transfer function:
-
- L = L' :sup:`2.6`
-
-Y'CbCr encoding is not specified. V4L2 defaults to Rec. 709.
-
-
-.. _col-smpte-240m:
-
-Colorspace SMPTE 240M (V4L2_COLORSPACE_SMPTE240M)
-=================================================
-
-The :ref:`smpte240m` standard was an interim standard used during the
-early days of HDTV (1988-1998). It has been superseded by Rec. 709. The
-default transfer function is ``V4L2_XFER_FUNC_SMPTE240M``. The default
-Y'CbCr encoding is ``V4L2_YCBCR_ENC_SMPTE240M``. The default Y'CbCr
-quantization is limited range. The chromaticities of the primary colors
-and the white reference are:
-
-
-
-.. flat-table:: SMPTE 240M Chromaticities
- :header-rows: 1
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - Color
-
- - x
-
- - y
-
- - .. row 2
-
- - Red
-
- - 0.630
-
- - 0.340
-
- - .. row 3
-
- - Green
-
- - 0.310
-
- - 0.595
-
- - .. row 4
-
- - Blue
-
- - 0.155
-
- - 0.070
-
- - .. row 5
-
- - White Reference (D65)
-
- - 0.3127
-
- - 0.3290
-
-
-These chromaticities are identical to the SMPTE 170M colorspace.
-
-Transfer function:
-
- L' = 4L for 0 ≤ L < 0.0228
-
- L' = 1.1115L :sup:`0.45` - 0.1115 for 0.0228 ≤ L ≤ 1
-
-Inverse Transfer function:
-
- L = L' / 4 for 0 ≤ L' < 0.0913
-
- L = ((L' + 0.1115) / 1.1115) :sup:`1/0.45` for L' ≥ 0.0913
-
-The luminance (Y') and color difference (Cb and Cr) are obtained with
-the following ``V4L2_YCBCR_ENC_SMPTE240M`` encoding:
-
- Y' = 0.2122R' + 0.7013G' + 0.0865B'
-
- Cb = -0.1161R' - 0.3839G' + 0.5B'
-
- Cr = 0.5R' - 0.4451G' - 0.0549B'
-
-Yc' is clamped to the range [0…1] and Cbc and Crc are clamped to the
-range [-0.5…0.5]. The Y'CbCr quantization is limited range.
-
-
-.. _col-sysm:
-
-Colorspace NTSC 1953 (V4L2_COLORSPACE_470_SYSTEM_M)
-===================================================
-
-This standard defines the colorspace used by NTSC in 1953. In practice
-this colorspace is obsolete and SMPTE 170M should be used instead. The
-default transfer function is ``V4L2_XFER_FUNC_709``. The default Y'CbCr
-encoding is ``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is
-limited range. The chromaticities of the primary colors and the white
-reference are:
-
-
-
-.. flat-table:: NTSC 1953 Chromaticities
- :header-rows: 1
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - Color
-
- - x
-
- - y
-
- - .. row 2
-
- - Red
-
- - 0.67
-
- - 0.33
-
- - .. row 3
-
- - Green
-
- - 0.21
-
- - 0.71
-
- - .. row 4
-
- - Blue
-
- - 0.14
-
- - 0.08
-
- - .. row 5
-
- - White Reference (C)
-
- - 0.310
-
- - 0.316
-
-
-Note that this colorspace uses Illuminant C instead of D65 as the white
-reference. To correctly convert an image in this colorspace to another
-that uses D65 you need to apply a chromatic adaptation algorithm such as
-the Bradford method.
-
-The transfer function was never properly defined for NTSC 1953. The Rec.
-709 transfer function is recommended in the literature:
-
- L' = 4.5L for 0 ≤ L < 0.018
-
- L' = 1.099L :sup:`0.45` - 0.099 for 0.018 ≤ L ≤ 1
-
-Inverse Transfer function:
-
- L = L' / 4.5 for L' < 0.081
-
- L = ((L' + 0.099) / 1.099) :sup:`1/0.45` for L' ≥ 0.081
-
-The luminance (Y') and color difference (Cb and Cr) are obtained with
-the following ``V4L2_YCBCR_ENC_601`` encoding:
-
- Y' = 0.299R' + 0.587G' + 0.114B'
-
- Cb = -0.169R' - 0.331G' + 0.5B'
-
- Cr = 0.5R' - 0.419G' - 0.081B'
-
-Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
-[-0.5…0.5]. The Y'CbCr quantization is limited range. This transform is
-identical to one defined in SMPTE 170M/BT.601.
-
-
-.. _col-sysbg:
-
-Colorspace EBU Tech. 3213 (V4L2_COLORSPACE_470_SYSTEM_BG)
-=========================================================
-
-The :ref:`tech3213` standard defines the colorspace used by PAL/SECAM
-in 1975. In practice this colorspace is obsolete and SMPTE 170M should
-be used instead. The default transfer function is
-``V4L2_XFER_FUNC_709``. The default Y'CbCr encoding is
-``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is limited
-range. The chromaticities of the primary colors and the white reference
-are:
-
-
-
-.. flat-table:: EBU Tech. 3213 Chromaticities
- :header-rows: 1
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - Color
-
- - x
-
- - y
-
- - .. row 2
-
- - Red
-
- - 0.64
-
- - 0.33
-
- - .. row 3
-
- - Green
-
- - 0.29
-
- - 0.60
-
- - .. row 4
-
- - Blue
-
- - 0.15
-
- - 0.06
-
- - .. row 5
-
- - White Reference (D65)
-
- - 0.3127
-
- - 0.3290
-
-
-
-The transfer function was never properly defined for this colorspace.
-The Rec. 709 transfer function is recommended in the literature:
-
- L' = 4.5L for 0 ≤ L < 0.018
-
- L' = 1.099L :sup:`0.45` - 0.099 for 0.018 ≤ L ≤ 1
-
-Inverse Transfer function:
-
- L = L' / 4.5 for L' < 0.081
-
- L = ((L' + 0.099) / 1.099) :sup:`1/0.45` for L' ≥ 0.081
-
-The luminance (Y') and color difference (Cb and Cr) are obtained with
-the following ``V4L2_YCBCR_ENC_601`` encoding:
-
- Y' = 0.299R' + 0.587G' + 0.114B'
-
- Cb = -0.169R' - 0.331G' + 0.5B'
-
- Cr = 0.5R' - 0.419G' - 0.081B'
-
-Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
-[-0.5…0.5]. The Y'CbCr quantization is limited range. This transform is
-identical to one defined in SMPTE 170M/BT.601.
-
-
-.. _col-jpeg:
-
-Colorspace JPEG (V4L2_COLORSPACE_JPEG)
-======================================
-
-This colorspace defines the colorspace used by most (Motion-)JPEG
-formats. The chromaticities of the primary colors and the white
-reference are identical to sRGB. The transfer function use is
-``V4L2_XFER_FUNC_SRGB``. The Y'CbCr encoding is ``V4L2_YCBCR_ENC_601``
-with full range quantization where Y' is scaled to [0…255] and Cb/Cr are
-scaled to [-128…128] and then clipped to [-128…127].
-
-Note that the JPEG standard does not actually store colorspace
-information. So if something other than sRGB is used, then the driver
-will have to set that information explicitly. Effectively
-``V4L2_COLORSPACE_JPEG`` can be considered to be an abbreviation for
-``V4L2_COLORSPACE_SRGB``, ``V4L2_YCBCR_ENC_601`` and
-``V4L2_QUANTIZATION_FULL_RANGE``.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-***************************************
-Detailed Transfer Function Descriptions
-***************************************
-
-
-.. _xf-smpte-2084:
-
-Transfer Function SMPTE 2084 (V4L2_XFER_FUNC_SMPTE2084)
-=======================================================
-
-The :ref:`smpte2084` standard defines the transfer function used by
-High Dynamic Range content.
-
-Constants:
- m1 = (2610 / 4096) / 4
-
- m2 = (2523 / 4096) * 128
-
- c1 = 3424 / 4096
-
- c2 = (2413 / 4096) * 32
-
- c3 = (2392 / 4096) * 32
-
-Transfer function:
- L' = ((c1 + c2 * L\ :sup:`m1`) / (1 + c3 * L\ :sup:`m1`))\ :sup:`m2`
-
-Inverse Transfer function:
- L = (max(L':sup:`1/m2` - c1, 0) / (c2 - c3 *
- L'\ :sup:`1/m2`))\ :sup:`1/m1`
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-******************
-Compressed Formats
-******************
-
-
-.. _compressed-formats:
-
-.. flat-table:: Compressed Image Formats
- :header-rows: 1
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - Identifier
-
- - Code
-
- - Details
-
- - .. _V4L2-PIX-FMT-JPEG:
-
- - ``V4L2_PIX_FMT_JPEG``
-
- - 'JPEG'
-
- - TBD. See also :ref:`VIDIOC_G_JPEGCOMP <VIDIOC_G_JPEGCOMP>`,
- :ref:`VIDIOC_S_JPEGCOMP <VIDIOC_G_JPEGCOMP>`.
-
- - .. _V4L2-PIX-FMT-MPEG:
-
- - ``V4L2_PIX_FMT_MPEG``
-
- - 'MPEG'
-
- - MPEG multiplexed stream. The actual format is determined by
- extended control ``V4L2_CID_MPEG_STREAM_TYPE``, see
- :ref:`mpeg-control-id`.
-
- - .. _V4L2-PIX-FMT-H264:
-
- - ``V4L2_PIX_FMT_H264``
-
- - 'H264'
-
- - H264 video elementary stream with start codes.
-
- - .. _V4L2-PIX-FMT-H264-NO-SC:
-
- - ``V4L2_PIX_FMT_H264_NO_SC``
-
- - 'AVC1'
-
- - H264 video elementary stream without start codes.
-
- - .. _V4L2-PIX-FMT-H264-MVC:
-
- - ``V4L2_PIX_FMT_H264_MVC``
-
- - 'M264'
-
- - H264 MVC video elementary stream.
-
- - .. _V4L2-PIX-FMT-H263:
-
- - ``V4L2_PIX_FMT_H263``
-
- - 'H263'
-
- - H263 video elementary stream.
-
- - .. _V4L2-PIX-FMT-MPEG1:
-
- - ``V4L2_PIX_FMT_MPEG1``
-
- - 'MPG1'
-
- - MPEG1 video elementary stream.
-
- - .. _V4L2-PIX-FMT-MPEG2:
-
- - ``V4L2_PIX_FMT_MPEG2``
-
- - 'MPG2'
-
- - MPEG2 video elementary stream.
-
- - .. _V4L2-PIX-FMT-MPEG4:
-
- - ``V4L2_PIX_FMT_MPEG4``
-
- - 'MPG4'
-
- - MPEG4 video elementary stream.
-
- - .. _V4L2-PIX-FMT-XVID:
-
- - ``V4L2_PIX_FMT_XVID``
-
- - 'XVID'
-
- - Xvid video elementary stream.
-
- - .. _V4L2-PIX-FMT-VC1-ANNEX-G:
-
- - ``V4L2_PIX_FMT_VC1_ANNEX_G``
-
- - 'VC1G'
-
- - VC1, SMPTE 421M Annex G compliant stream.
-
- - .. _V4L2-PIX-FMT-VC1-ANNEX-L:
-
- - ``V4L2_PIX_FMT_VC1_ANNEX_L``
-
- - 'VC1L'
-
- - VC1, SMPTE 421M Annex L compliant stream.
-
- - .. _V4L2-PIX-FMT-VP8:
-
- - ``V4L2_PIX_FMT_VP8``
-
- - 'VP80'
-
- - VP8 video elementary stream.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _V4L2-PIX-FMT-GREY:
-
-**************************
-V4L2_PIX_FMT_GREY ('GREY')
-**************************
-
-*man V4L2_PIX_FMT_GREY(2)*
-
-Grey-scale image
-
-
-Description
-===========
-
-This is a grey-scale image. It is really a degenerate Y'CbCr format
-which simply contains no Cb or Cr data.
-
-**Byte Order.**
-Each cell is one byte.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 2 1 1 1 1
-
-
- - .. row 1
-
- - start + 0:
-
- - Y'\ :sub:`00`
-
- - Y'\ :sub:`01`
-
- - Y'\ :sub:`02`
-
- - Y'\ :sub:`03`
-
- - .. row 2
-
- - start + 4:
-
- - Y'\ :sub:`10`
-
- - Y'\ :sub:`11`
-
- - Y'\ :sub:`12`
-
- - Y'\ :sub:`13`
-
- - .. row 3
-
- - start + 8:
-
- - Y'\ :sub:`20`
-
- - Y'\ :sub:`21`
-
- - Y'\ :sub:`22`
-
- - Y'\ :sub:`23`
-
- - .. row 4
-
- - start + 12:
-
- - Y'\ :sub:`30`
-
- - Y'\ :sub:`31`
-
- - Y'\ :sub:`32`
-
- - Y'\ :sub:`33`
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _pixfmt-indexed:
-
-**************
-Indexed Format
-**************
-
-In this format each pixel is represented by an 8 bit index into a 256
-entry ARGB palette. It is intended for
-:ref:`Video Output Overlays <osd>` only. There are no ioctls to access
-the palette, this must be done with ioctls of the Linux framebuffer API.
-
-
-
-.. flat-table:: Indexed Image Format
- :header-rows: 2
- :stub-columns: 0
-
-
- - .. row 1
-
- - Identifier
-
- - Code
-
- -
- - :cspan:`7` Byte 0
-
- - .. row 2
-
- -
- -
- - Bit
-
- - 7
-
- - 6
-
- - 5
-
- - 4
-
- - 3
-
- - 2
-
- - 1
-
- - 0
-
- - .. _V4L2-PIX-FMT-PAL8:
-
- - ``V4L2_PIX_FMT_PAL8``
-
- - 'PAL8'
-
- -
- - i\ :sub:`7`
-
- - i\ :sub:`6`
-
- - i\ :sub:`5`
-
- - i\ :sub:`4`
-
- - i\ :sub:`3`
-
- - i\ :sub:`2`
-
- - i\ :sub:`1`
-
- - i\ :sub:`0`
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _V4L2-PIX-FMT-M420:
-
-**************************
-V4L2_PIX_FMT_M420 ('M420')
-**************************
-
-*man V4L2_PIX_FMT_M420(2)*
-
-Format with ½ horizontal and vertical chroma resolution, also known as
-YUV 4:2:0. Hybrid plane line-interleaved layout.
-
-
-Description
-===========
-
-M420 is a YUV format with ½ horizontal and vertical chroma subsampling
-(YUV 4:2:0). Pixels are organized as interleaved luma and chroma planes.
-Two lines of luma data are followed by one line of chroma data.
-
-The luma plane has one byte per pixel. The chroma plane contains
-interleaved CbCr pixels subsampled by ½ in the horizontal and vertical
-directions. Each CbCr pair belongs to four pixels. For example,
-Cb\ :sub:`0`/Cr\ :sub:`0` belongs to Y'\ :sub:`00`, Y'\ :sub:`01`,
-Y'\ :sub:`10`, Y'\ :sub:`11`.
-
-All line lengths are identical: if the Y lines include pad bytes so do
-the CbCr lines.
-
-**Byte Order.**
-Each cell is one byte.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 2 1 1 1 1
-
-
- - .. row 1
-
- - start + 0:
-
- - Y'\ :sub:`00`
-
- - Y'\ :sub:`01`
-
- - Y'\ :sub:`02`
-
- - Y'\ :sub:`03`
-
- - .. row 2
-
- - start + 4:
-
- - Y'\ :sub:`10`
-
- - Y'\ :sub:`11`
-
- - Y'\ :sub:`12`
-
- - Y'\ :sub:`13`
-
- - .. row 3
-
- - start + 8:
-
- - Cb\ :sub:`00`
-
- - Cr\ :sub:`00`
-
- - Cb\ :sub:`01`
-
- - Cr\ :sub:`01`
-
- - .. row 4
-
- - start + 16:
-
- - Y'\ :sub:`20`
-
- - Y'\ :sub:`21`
-
- - Y'\ :sub:`22`
-
- - Y'\ :sub:`23`
-
- - .. row 5
-
- - start + 20:
-
- - Y'\ :sub:`30`
-
- - Y'\ :sub:`31`
-
- - Y'\ :sub:`32`
-
- - Y'\ :sub:`33`
-
- - .. row 6
-
- - start + 24:
-
- - Cb\ :sub:`10`
-
- - Cr\ :sub:`10`
-
- - Cb\ :sub:`11`
-
- - Cr\ :sub:`11`
-
-
-**Color Sample Location..**
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- -
- - 0
-
- -
- - 1
-
- - 2
-
- -
- - 3
-
- - .. row 2
-
- - 0
-
- - Y
-
- -
- - Y
-
- - Y
-
- -
- - Y
-
- - .. row 3
-
- -
- -
- - C
-
- -
- -
- - C
-
- -
-
- - .. row 4
-
- - 1
-
- - Y
-
- -
- - Y
-
- - Y
-
- -
- - Y
-
- - .. row 5
-
- -
-
- - .. row 6
-
- - 2
-
- - Y
-
- -
- - Y
-
- - Y
-
- -
- - Y
-
- - .. row 7
-
- -
- -
- - C
-
- -
- -
- - C
-
- -
-
- - .. row 8
-
- - 3
-
- - Y
-
- -
- - Y
-
- - Y
-
- -
- - Y
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _V4L2-PIX-FMT-NV12:
-.. _V4L2-PIX-FMT-NV21:
-
-******************************************************
-V4L2_PIX_FMT_NV12 ('NV12'), V4L2_PIX_FMT_NV21 ('NV21')
-******************************************************
-
-*man V4L2_PIX_FMT_NV12(2)*
-
-V4L2_PIX_FMT_NV21
-Formats with ½ horizontal and vertical chroma resolution, also known as
-YUV 4:2:0. One luminance and one chrominance plane with alternating
-chroma samples as opposed to ``V4L2_PIX_FMT_YVU420``
-
-
-Description
-===========
-
-These are two-plane versions of the YUV 4:2:0 format. The three
-components are separated into two sub-images or planes. The Y plane is
-first. The Y plane has one byte per pixel. For ``V4L2_PIX_FMT_NV12``, a
-combined CbCr plane immediately follows the Y plane in memory. The CbCr
-plane is the same width, in bytes, as the Y plane (and of the image),
-but is half as tall in pixels. Each CbCr pair belongs to four pixels.
-For example, Cb\ :sub:`0`/Cr\ :sub:`0` belongs to Y'\ :sub:`00`,
-Y'\ :sub:`01`, Y'\ :sub:`10`, Y'\ :sub:`11`. ``V4L2_PIX_FMT_NV21`` is
-the same except the Cb and Cr bytes are swapped, the CrCb plane starts
-with a Cr byte.
-
-If the Y plane has pad bytes after each row, then the CbCr plane has as
-many pad bytes after its rows.
-
-**Byte Order.**
-Each cell is one byte.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 2 1 1 1 1
-
-
- - .. row 1
-
- - start + 0:
-
- - Y'\ :sub:`00`
-
- - Y'\ :sub:`01`
-
- - Y'\ :sub:`02`
-
- - Y'\ :sub:`03`
-
- - .. row 2
-
- - start + 4:
-
- - Y'\ :sub:`10`
-
- - Y'\ :sub:`11`
-
- - Y'\ :sub:`12`
-
- - Y'\ :sub:`13`
-
- - .. row 3
-
- - start + 8:
-
- - Y'\ :sub:`20`
-
- - Y'\ :sub:`21`
-
- - Y'\ :sub:`22`
-
- - Y'\ :sub:`23`
-
- - .. row 4
-
- - start + 12:
-
- - Y'\ :sub:`30`
-
- - Y'\ :sub:`31`
-
- - Y'\ :sub:`32`
-
- - Y'\ :sub:`33`
-
- - .. row 5
-
- - start + 16:
-
- - Cb\ :sub:`00`
-
- - Cr\ :sub:`00`
-
- - Cb\ :sub:`01`
-
- - Cr\ :sub:`01`
-
- - .. row 6
-
- - start + 20:
-
- - Cb\ :sub:`10`
-
- - Cr\ :sub:`10`
-
- - Cb\ :sub:`11`
-
- - Cr\ :sub:`11`
-
-
-**Color Sample Location..**
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- -
- - 0
-
- -
- - 1
-
- - 2
-
- -
- - 3
-
- - .. row 2
-
- - 0
-
- - Y
-
- -
- - Y
-
- - Y
-
- -
- - Y
-
- - .. row 3
-
- -
- -
- - C
-
- -
- -
- - C
-
- -
-
- - .. row 4
-
- - 1
-
- - Y
- -
-
- - Y
-
- - Y
-
- -
- - Y
-
- - .. row 5
-
- -
-
- - .. row 6
-
- - 2
-
- - Y
- -
-
- - Y
-
- - Y
-
- -
- - Y
-
- - .. row 7
-
- -
- -
- - C
-
- -
- -
- - C
-
- -
-
- - .. row 8
-
- - 3
-
- - Y
-
- -
- - Y
-
- - Y
-
- -
- - Y
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _V4L2-PIX-FMT-NV12M:
-.. _v4l2-pix-fmt-nv12mt-16x16:
-.. _V4L2-PIX-FMT-NV21M:
-
-***********************************************************************************
-V4L2_PIX_FMT_NV12M ('NM12'), V4L2_PIX_FMT_NV21M ('NM21'), V4L2_PIX_FMT_NV12MT_16X16
-***********************************************************************************
-
-*man V4L2_PIX_FMT_NV12M(2)*
-
-V4L2_PIX_FMT_NV21M
-V4L2_PIX_FMT_NV12MT_16X16
-Variation of ``V4L2_PIX_FMT_NV12`` and ``V4L2_PIX_FMT_NV21`` with planes
-non contiguous in memory.
-
-
-Description
-===========
-
-This is a multi-planar, two-plane version of the YUV 4:2:0 format. The
-three components are separated into two sub-images or planes.
-``V4L2_PIX_FMT_NV12M`` differs from ``V4L2_PIX_FMT_NV12`` in that the
-two planes are non-contiguous in memory, i.e. the chroma plane do not
-necessarily immediately follows the luma plane. The luminance data
-occupies the first plane. The Y plane has one byte per pixel. In the
-second plane there is a chrominance data with alternating chroma
-samples. The CbCr plane is the same width, in bytes, as the Y plane (and
-of the image), but is half as tall in pixels. Each CbCr pair belongs to
-four pixels. For example, Cb\ :sub:`0`/Cr\ :sub:`0` belongs to
-Y'\ :sub:`00`, Y'\ :sub:`01`, Y'\ :sub:`10`, Y'\ :sub:`11`.
-``V4L2_PIX_FMT_NV12MT_16X16`` is the tiled version of
-``V4L2_PIX_FMT_NV12M`` with 16x16 macroblock tiles. Here pixels are
-arranged in 16x16 2D tiles and tiles are arranged in linear order in
-memory. ``V4L2_PIX_FMT_NV21M`` is the same as ``V4L2_PIX_FMT_NV12M``
-except the Cb and Cr bytes are swapped, the CrCb plane starts with a Cr
-byte.
-
-``V4L2_PIX_FMT_NV12M`` is intended to be used only in drivers and
-applications that support the multi-planar API, described in
-:ref:`planar-apis`.
-
-If the Y plane has pad bytes after each row, then the CbCr plane has as
-many pad bytes after its rows.
-
-**Byte Order.**
-Each cell is one byte.
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 2 1 1 1 1
-
-
- - .. row 1
-
- - start0 + 0:
-
- - Y'\ :sub:`00`
-
- - Y'\ :sub:`01`
-
- - Y'\ :sub:`02`
-
- - Y'\ :sub:`03`
-
- - .. row 2
-
- - start0 + 4:
-
- - Y'\ :sub:`10`
-
- - Y'\ :sub:`11`
-
- - Y'\ :sub:`12`
-
- - Y'\ :sub:`13`
-
- - .. row 3
-
- - start0 + 8:
-
- - Y'\ :sub:`20`
-
- - Y'\ :sub:`21`
-
- - Y'\ :sub:`22`
-
- - Y'\ :sub:`23`
-
- - .. row 4
-
- - start0 + 12:
-
- - Y'\ :sub:`30`
-
- - Y'\ :sub:`31`
-
- - Y'\ :sub:`32`
-
- - Y'\ :sub:`33`
-
- - .. row 5
-
- -
-
- - .. row 6
-
- - start1 + 0:
-
- - Cb\ :sub:`00`
-
- - Cr\ :sub:`00`
-
- - Cb\ :sub:`01`
-
- - Cr\ :sub:`01`
-
- - .. row 7
-
- - start1 + 4:
-
- - Cb\ :sub:`10`
-
- - Cr\ :sub:`10`
-
- - Cb\ :sub:`11`
-
- - Cr\ :sub:`11`
-
-
-**Color Sample Location..**
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- -
- - 0
-
- -
- - 1
-
- - 2
-
- -
- - 3
-
- - .. row 2
-
- - 0
-
- - Y
-
- -
- - Y
-
- - Y
-
- -
- - Y
-
- - .. row 3
-
- -
- -
- - C
-
- -
- -
- - C
-
- -
-
- - .. row 4
-
- - 1
-
- - Y
-
- -
- - Y
-
- - Y
-
- -
- - Y
-
- - .. row 5
-
- -
-
- - .. row 6
-
- - 2
-
- - Y
-
- -
- - Y
-
- - Y
-
- -
- - Y
-
- - .. row 7
-
- -
- -
- - C
-
- -
- -
- -
- - C
-
- -
-
- - .. row 8
-
- - 3
-
- - Y
-
- -
- - Y
-
- - Y
-
- -
- - Y
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _V4L2-PIX-FMT-NV12MT:
-
-****************************
-V4L2_PIX_FMT_NV12MT ('TM12')
-****************************
-
-*man V4L2_PIX_FMT_NV12MT(2)*
-
-Formats with ½ horizontal and vertical chroma resolution. This format
-has two planes - one for luminance and one for chrominance. Chroma
-samples are interleaved. The difference to ``V4L2_PIX_FMT_NV12`` is the
-memory layout. Pixels are grouped in macroblocks of 64x32 size. The
-order of macroblocks in memory is also not standard.
-
-
-Description
-===========
-
-This is the two-plane versions of the YUV 4:2:0 format where data is
-grouped into 64x32 macroblocks. The three components are separated into
-two sub-images or planes. The Y plane has one byte per pixel and pixels
-are grouped into 64x32 macroblocks. The CbCr plane has the same width,
-in bytes, as the Y plane (and the image), but is half as tall in pixels.
-The chroma plane is also grouped into 64x32 macroblocks.
-
-Width of the buffer has to be aligned to the multiple of 128, and height
-alignment is 32. Every four adjacent buffers - two horizontally and two
-vertically are grouped together and are located in memory in Z or
-flipped Z order.
-
-Layout of macroblocks in memory is presented in the following figure.
-
-
-.. _nv12mt:
-
-.. figure:: pixfmt-nv12mt_files/nv12mt.*
- :alt: nv12mt.gif
- :align: center
-
- V4L2_PIX_FMT_NV12MT macroblock Z shape memory layout
-
-The requirement that width is multiple of 128 is implemented because,
-the Z shape cannot be cut in half horizontally. In case the vertical
-resolution of macroblocks is odd then the last row of macroblocks is
-arranged in a linear order.
-
-In case of chroma the layout is identical. Cb and Cr samples are
-interleaved. Height of the buffer is aligned to 32.
-
-
-.. _nv12mt_ex:
-
-.. figure:: pixfmt-nv12mt_files/nv12mt_example.*
- :alt: nv12mt_example.gif
- :align: center
-
- Example V4L2_PIX_FMT_NV12MT memory layout of macroblocks
-
-Memory layout of macroblocks of ``V4L2_PIX_FMT_NV12MT`` format in most
-extreme case.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _V4L2-PIX-FMT-NV16:
-.. _V4L2-PIX-FMT-NV61:
-
-******************************************************
-V4L2_PIX_FMT_NV16 ('NV16'), V4L2_PIX_FMT_NV61 ('NV61')
-******************************************************
-
-*man V4L2_PIX_FMT_NV16(2)*
-
-V4L2_PIX_FMT_NV61
-Formats with ½ horizontal chroma resolution, also known as YUV 4:2:2.
-One luminance and one chrominance plane with alternating chroma samples
-as opposed to ``V4L2_PIX_FMT_YVU420``
-
-
-Description
-===========
-
-These are two-plane versions of the YUV 4:2:2 format. The three
-components are separated into two sub-images or planes. The Y plane is
-first. The Y plane has one byte per pixel. For ``V4L2_PIX_FMT_NV16``, a
-combined CbCr plane immediately follows the Y plane in memory. The CbCr
-plane is the same width and height, in bytes, as the Y plane (and of the
-image). Each CbCr pair belongs to two pixels. For example,
-Cb\ :sub:`0`/Cr\ :sub:`0` belongs to Y'\ :sub:`00`, Y'\ :sub:`01`.
-``V4L2_PIX_FMT_NV61`` is the same except the Cb and Cr bytes are
-swapped, the CrCb plane starts with a Cr byte.
-
-If the Y plane has pad bytes after each row, then the CbCr plane has as
-many pad bytes after its rows.
-
-**Byte Order.**
-Each cell is one byte.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 2 1 1 1 1
-
-
- - .. row 1
-
- - start + 0:
-
- - Y'\ :sub:`00`
-
- - Y'\ :sub:`01`
-
- - Y'\ :sub:`02`
-
- - Y'\ :sub:`03`
-
- - .. row 2
-
- - start + 4:
-
- - Y'\ :sub:`10`
-
- - Y'\ :sub:`11`
-
- - Y'\ :sub:`12`
-
- - Y'\ :sub:`13`
-
- - .. row 3
-
- - start + 8:
-
- - Y'\ :sub:`20`
-
- - Y'\ :sub:`21`
-
- - Y'\ :sub:`22`
-
- - Y'\ :sub:`23`
-
- - .. row 4
-
- - start + 12:
-
- - Y'\ :sub:`30`
-
- - Y'\ :sub:`31`
-
- - Y'\ :sub:`32`
-
- - Y'\ :sub:`33`
-
- - .. row 5
-
- - start + 16:
-
- - Cb\ :sub:`00`
-
- - Cr\ :sub:`00`
-
- - Cb\ :sub:`01`
-
- - Cr\ :sub:`01`
-
- - .. row 6
-
- - start + 20:
-
- - Cb\ :sub:`10`
-
- - Cr\ :sub:`10`
-
- - Cb\ :sub:`11`
-
- - Cr\ :sub:`11`
-
- - .. row 7
-
- - start + 24:
-
- - Cb\ :sub:`20`
-
- - Cr\ :sub:`20`
-
- - Cb\ :sub:`21`
-
- - Cr\ :sub:`21`
-
- - .. row 8
-
- - start + 28:
-
- - Cb\ :sub:`30`
-
- - Cr\ :sub:`30`
-
- - Cb\ :sub:`31`
-
- - Cr\ :sub:`31`
-
-
-**Color Sample Location..**
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- -
- - 0
-
- -
- - 1
-
- - 2
-
- -
- - 3
-
- - .. row 2
-
- - 0
-
- - Y
-
- -
- - Y
-
- - Y
-
- -
- - Y
-
- - .. row 3
-
- -
- -
- - C
-
- -
- -
- - C
-
- -
-
- - .. row 4
-
- - 1
-
- - Y
-
- -
- - Y
-
- - Y
-
- -
- - Y
-
- - .. row 5
-
- -
- -
- - C
-
- -
- -
- - C
-
- -
-
- - .. row 6
-
- -
-
- - .. row 7
-
- - 2
-
- - Y
-
- -
- - Y
-
- - Y
-
- -
- - Y
-
- - .. row 8
-
- -
- -
- - C
-
- -
- -
- - C
-
- -
-
- - .. row 9
-
- - 3
-
- - Y
-
- -
- - Y
-
- - Y
-
- -
- - Y
-
- - .. row 10
-
- -
- -
- - C
-
- -
- -
- - C
-
- -
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _V4L2-PIX-FMT-NV16M:
-.. _v4l2-pix-fmt-nv61m:
-
-********************************************************
-V4L2_PIX_FMT_NV16M ('NM16'), V4L2_PIX_FMT_NV61M ('NM61')
-********************************************************
-
-*man V4L2_PIX_FMT_NV16M(2)*
-
-V4L2_PIX_FMT_NV61M
-Variation of ``V4L2_PIX_FMT_NV16`` and ``V4L2_PIX_FMT_NV61`` with planes
-non contiguous in memory.
-
-
-Description
-===========
-
-This is a multi-planar, two-plane version of the YUV 4:2:2 format. The
-three components are separated into two sub-images or planes.
-``V4L2_PIX_FMT_NV16M`` differs from ``V4L2_PIX_FMT_NV16`` in that the
-two planes are non-contiguous in memory, i.e. the chroma plane does not
-necessarily immediately follow the luma plane. The luminance data
-occupies the first plane. The Y plane has one byte per pixel. In the
-second plane there is chrominance data with alternating chroma samples.
-The CbCr plane is the same width and height, in bytes, as the Y plane.
-Each CbCr pair belongs to two pixels. For example,
-Cb\ :sub:`0`/Cr\ :sub:`0` belongs to Y'\ :sub:`00`, Y'\ :sub:`01`.
-``V4L2_PIX_FMT_NV61M`` is the same as ``V4L2_PIX_FMT_NV16M`` except the
-Cb and Cr bytes are swapped, the CrCb plane starts with a Cr byte.
-
-``V4L2_PIX_FMT_NV16M`` and ``V4L2_PIX_FMT_NV61M`` are intended to be
-used only in drivers and applications that support the multi-planar API,
-described in :ref:`planar-apis`.
-
-**Byte Order.**
-Each cell is one byte.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 2 1 1 1 1
-
-
- - .. row 1
-
- - start0 + 0:
-
- - Y'\ :sub:`00`
-
- - Y'\ :sub:`01`
-
- - Y'\ :sub:`02`
-
- - Y'\ :sub:`03`
-
- - .. row 2
-
- - start0 + 4:
-
- - Y'\ :sub:`10`
-
- - Y'\ :sub:`11`
-
- - Y'\ :sub:`12`
-
- - Y'\ :sub:`13`
-
- - .. row 3
-
- - start0 + 8:
-
- - Y'\ :sub:`20`
-
- - Y'\ :sub:`21`
-
- - Y'\ :sub:`22`
-
- - Y'\ :sub:`23`
-
- - .. row 4
-
- - start0 + 12:
-
- - Y'\ :sub:`30`
-
- - Y'\ :sub:`31`
-
- - Y'\ :sub:`32`
-
- - Y'\ :sub:`33`
-
- - .. row 5
-
- -
-
- - .. row 6
-
- - start1 + 0:
-
- - Cb\ :sub:`00`
-
- - Cr\ :sub:`00`
-
- - Cb\ :sub:`02`
-
- - Cr\ :sub:`02`
-
- - .. row 7
-
- - start1 + 4:
-
- - Cb\ :sub:`10`
-
- - Cr\ :sub:`10`
-
- - Cb\ :sub:`12`
-
- - Cr\ :sub:`12`
-
- - .. row 8
-
- - start1 + 8:
-
- - Cb\ :sub:`20`
-
- - Cr\ :sub:`20`
-
- - Cb\ :sub:`22`
-
- - Cr\ :sub:`22`
-
- - .. row 9
-
- - start1 + 12:
-
- - Cb\ :sub:`30`
-
- - Cr\ :sub:`30`
-
- - Cb\ :sub:`32`
-
- - Cr\ :sub:`32`
-
-
-**Color Sample Location..**
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- -
- - 0
-
- -
- - 1
-
- - 2
-
- -
- - 3
-
- - .. row 2
-
- - 0
-
- - Y
-
- -
- - Y
-
- - Y
-
- -
- - Y
-
- - .. row 3
-
- -
- -
- - C
-
- -
- -
- - C
-
- -
-
- - .. row 4
-
- - 1
-
- - Y
-
- -
- - Y
-
- - Y
-
- -
- - Y
-
- - .. row 5
-
- -
- -
- - C
-
- -
- -
- - C
-
- -
-
- - .. row 6
-
- -
-
- - .. row 7
-
- - 2
-
- - Y
-
- -
- - Y
-
- - Y
-
- -
- - Y
-
- - .. row 8
-
- -
- -
- - C
-
- -
- -
- - C
-
- -
-
- - .. row 9
-
- - 3
-
- - Y
-
- -
- - Y
-
- - Y
-
- -
- - Y
-
- - .. row 10
-
- -
- -
- - C
-
- -
- -
- - C
-
- -
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _V4L2-PIX-FMT-NV24:
-.. _V4L2-PIX-FMT-NV42:
-
-******************************************************
-V4L2_PIX_FMT_NV24 ('NV24'), V4L2_PIX_FMT_NV42 ('NV42')
-******************************************************
-
-*man V4L2_PIX_FMT_NV24(2)*
-
-V4L2_PIX_FMT_NV42
-Formats with full horizontal and vertical chroma resolutions, also known
-as YUV 4:4:4. One luminance and one chrominance plane with alternating
-chroma samples as opposed to ``V4L2_PIX_FMT_YVU420``
-
-
-Description
-===========
-
-These are two-plane versions of the YUV 4:4:4 format. The three
-components are separated into two sub-images or planes. The Y plane is
-first, with each Y sample stored in one byte per pixel. For
-``V4L2_PIX_FMT_NV24``, a combined CbCr plane immediately follows the Y
-plane in memory. The CbCr plane has the same width and height, in
-pixels, as the Y plane (and the image). Each line contains one CbCr pair
-per pixel, with each Cb and Cr sample stored in one byte.
-``V4L2_PIX_FMT_NV42`` is the same except that the Cb and Cr samples are
-swapped, the CrCb plane starts with a Cr sample.
-
-If the Y plane has pad bytes after each row, then the CbCr plane has
-twice as many pad bytes after its rows.
-
-**Byte Order.**
-Each cell is one byte.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 2 1 1 1 1 1 1 1 1
-
-
- - .. row 1
-
- - start + 0:
-
- - Y'\ :sub:`00`
-
- - Y'\ :sub:`01`
-
- - Y'\ :sub:`02`
-
- - Y'\ :sub:`03`
-
- - .. row 2
-
- - start + 4:
-
- - Y'\ :sub:`10`
-
- - Y'\ :sub:`11`
-
- - Y'\ :sub:`12`
-
- - Y'\ :sub:`13`
-
- - .. row 3
-
- - start + 8:
-
- - Y'\ :sub:`20`
-
- - Y'\ :sub:`21`
-
- - Y'\ :sub:`22`
-
- - Y'\ :sub:`23`
-
- - .. row 4
-
- - start + 12:
-
- - Y'\ :sub:`30`
-
- - Y'\ :sub:`31`
-
- - Y'\ :sub:`32`
-
- - Y'\ :sub:`33`
-
- - .. row 5
-
- - start + 16:
-
- - Cb\ :sub:`00`
-
- - Cr\ :sub:`00`
-
- - Cb\ :sub:`01`
-
- - Cr\ :sub:`01`
-
- - Cb\ :sub:`02`
-
- - Cr\ :sub:`02`
-
- - Cb\ :sub:`03`
-
- - Cr\ :sub:`03`
-
- - .. row 6
-
- - start + 24:
-
- - Cb\ :sub:`10`
-
- - Cr\ :sub:`10`
-
- - Cb\ :sub:`11`
-
- - Cr\ :sub:`11`
-
- - Cb\ :sub:`12`
-
- - Cr\ :sub:`12`
-
- - Cb\ :sub:`13`
-
- - Cr\ :sub:`13`
-
- - .. row 7
-
- - start + 32:
-
- - Cb\ :sub:`20`
-
- - Cr\ :sub:`20`
-
- - Cb\ :sub:`21`
-
- - Cr\ :sub:`21`
-
- - Cb\ :sub:`22`
-
- - Cr\ :sub:`22`
-
- - Cb\ :sub:`23`
-
- - Cr\ :sub:`23`
-
- - .. row 8
-
- - start + 40:
-
- - Cb\ :sub:`30`
-
- - Cr\ :sub:`30`
-
- - Cb\ :sub:`31`
-
- - Cr\ :sub:`31`
-
- - Cb\ :sub:`32`
-
- - Cr\ :sub:`32`
-
- - Cb\ :sub:`33`
-
- - Cr\ :sub:`33`
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _packed-rgb:
-
-******************
-Packed RGB formats
-******************
-
-*man Packed RGB formats(2)*
-
-Packed RGB formats
-
-
-Description
-===========
-
-These formats are designed to match the pixel formats of typical PC
-graphics frame buffers. They occupy 8, 16, 24 or 32 bits per pixel.
-These are all packed-pixel formats, meaning all the data for a pixel lie
-next to each other in memory.
-
-
-.. _rgb-formats:
-
-.. flat-table:: Packed RGB Image Formats
- :header-rows: 2
- :stub-columns: 0
-
-
- - .. row 1
-
- - Identifier
-
- - Code
-
- -
- - :cspan:`7` Byte 0 in memory
-
- - :cspan:`7` Byte 1
-
- - :cspan:`7` Byte 2
-
- - :cspan:`7` Byte 3
-
- - .. row 2
-
- -
- -
- - Bit
-
- - 7
-
- - 6
-
- - 5
-
- - 4
-
- - 3
-
- - 2
-
- - 1
-
- - 0
-
- -
- - 7
-
- - 6
-
- - 5
-
- - 4
-
- - 3
-
- - 2
-
- - 1
-
- - 0
-
- -
- - 7
-
- - 6
-
- - 5
-
- - 4
-
- - 3
-
- - 2
-
- - 1
-
- - 0
-
- -
- - 7
-
- - 6
-
- - 5
-
- - 4
-
- - 3
-
- - 2
-
- - 1
-
- - 0
-
- - .. _V4L2-PIX-FMT-RGB332:
-
- - ``V4L2_PIX_FMT_RGB332``
-
- - 'RGB1'
-
- -
- - r\ :sub:`2`
-
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- - .. _V4L2-PIX-FMT-ARGB444:
-
- - ``V4L2_PIX_FMT_ARGB444``
-
- - 'AR12'
-
- -
- - g\ :sub:`3`
-
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- -
- - a\ :sub:`3`
-
- - a\ :sub:`2`
-
- - a\ :sub:`1`
-
- - a\ :sub:`0`
-
- - r\ :sub:`3`
-
- - r\ :sub:`2`
-
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
- - .. _V4L2-PIX-FMT-XRGB444:
-
- - ``V4L2_PIX_FMT_XRGB444``
-
- - 'XR12'
-
- -
- - g\ :sub:`3`
-
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - r\ :sub:`3`
-
- - r\ :sub:`2`
-
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
- - .. _V4L2-PIX-FMT-ARGB555:
-
- - ``V4L2_PIX_FMT_ARGB555``
-
- - 'AR15'
-
- -
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- - b\ :sub:`4`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- -
- - a
-
- - r\ :sub:`4`
-
- - r\ :sub:`3`
-
- - r\ :sub:`2`
-
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
- - g\ :sub:`4`
-
- - g\ :sub:`3`
-
- - .. _V4L2-PIX-FMT-XRGB555:
-
- - ``V4L2_PIX_FMT_XRGB555``
-
- - 'XR15'
-
- -
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- - b\ :sub:`4`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- -
- - -
-
- - r\ :sub:`4`
-
- - r\ :sub:`3`
-
- - r\ :sub:`2`
-
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
- - g\ :sub:`4`
-
- - g\ :sub:`3`
-
- - .. _V4L2-PIX-FMT-RGB565:
-
- - ``V4L2_PIX_FMT_RGB565``
-
- - 'RGBP'
-
- -
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- - b\ :sub:`4`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- -
- - r\ :sub:`4`
-
- - r\ :sub:`3`
-
- - r\ :sub:`2`
-
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
- - g\ :sub:`5`
-
- - g\ :sub:`4`
-
- - g\ :sub:`3`
-
- - .. _V4L2-PIX-FMT-ARGB555X:
-
- - ``V4L2_PIX_FMT_ARGB555X``
-
- - 'AR15' | (1 << 31)
-
- -
- - a
-
- - r\ :sub:`4`
-
- - r\ :sub:`3`
-
- - r\ :sub:`2`
-
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
- - g\ :sub:`4`
-
- - g\ :sub:`3`
-
- -
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- - b\ :sub:`4`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- - .. _V4L2-PIX-FMT-XRGB555X:
-
- - ``V4L2_PIX_FMT_XRGB555X``
-
- - 'XR15' | (1 << 31)
-
- -
- - -
-
- - r\ :sub:`4`
-
- - r\ :sub:`3`
-
- - r\ :sub:`2`
-
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
- - g\ :sub:`4`
-
- - g\ :sub:`3`
-
- -
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- - b\ :sub:`4`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- - .. _V4L2-PIX-FMT-RGB565X:
-
- - ``V4L2_PIX_FMT_RGB565X``
-
- - 'RGBR'
-
- -
- - r\ :sub:`4`
-
- - r\ :sub:`3`
-
- - r\ :sub:`2`
-
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
- - g\ :sub:`5`
-
- - g\ :sub:`4`
-
- - g\ :sub:`3`
-
- -
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- - b\ :sub:`4`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- - .. _V4L2-PIX-FMT-BGR24:
-
- - ``V4L2_PIX_FMT_BGR24``
-
- - 'BGR3'
-
- -
- - b\ :sub:`7`
-
- - b\ :sub:`6`
-
- - b\ :sub:`5`
-
- - b\ :sub:`4`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- -
- - g\ :sub:`7`
-
- - g\ :sub:`6`
-
- - g\ :sub:`5`
-
- - g\ :sub:`4`
-
- - g\ :sub:`3`
-
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- -
- - r\ :sub:`7`
-
- - r\ :sub:`6`
-
- - r\ :sub:`5`
-
- - r\ :sub:`4`
-
- - r\ :sub:`3`
-
- - r\ :sub:`2`
-
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
- - .. _V4L2-PIX-FMT-RGB24:
-
- - ``V4L2_PIX_FMT_RGB24``
-
- - 'RGB3'
-
- -
- - r\ :sub:`7`
-
- - r\ :sub:`6`
-
- - r\ :sub:`5`
-
- - r\ :sub:`4`
-
- - r\ :sub:`3`
-
- - r\ :sub:`2`
-
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
- -
- - g\ :sub:`7`
-
- - g\ :sub:`6`
-
- - g\ :sub:`5`
-
- - g\ :sub:`4`
-
- - g\ :sub:`3`
-
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- -
- - b\ :sub:`7`
-
- - b\ :sub:`6`
-
- - b\ :sub:`5`
-
- - b\ :sub:`4`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- - .. _V4L2-PIX-FMT-BGR666:
-
- - ``V4L2_PIX_FMT_BGR666``
-
- - 'BGRH'
-
- -
- - b\ :sub:`5`
-
- - b\ :sub:`4`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- - g\ :sub:`5`
-
- - g\ :sub:`4`
-
- -
- - g\ :sub:`3`
-
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- - r\ :sub:`5`
-
- - r\ :sub:`4`
-
- - r\ :sub:`3`
-
- - r\ :sub:`2`
-
- -
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - .. _V4L2-PIX-FMT-ABGR32:
-
- - ``V4L2_PIX_FMT_ABGR32``
-
- - 'AR24'
-
- -
- - b\ :sub:`7`
-
- - b\ :sub:`6`
-
- - b\ :sub:`5`
-
- - b\ :sub:`4`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- -
- - g\ :sub:`7`
-
- - g\ :sub:`6`
-
- - g\ :sub:`5`
-
- - g\ :sub:`4`
-
- - g\ :sub:`3`
-
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- -
- - r\ :sub:`7`
-
- - r\ :sub:`6`
-
- - r\ :sub:`5`
-
- - r\ :sub:`4`
-
- - r\ :sub:`3`
-
- - r\ :sub:`2`
-
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
- -
- - a\ :sub:`7`
-
- - a\ :sub:`6`
-
- - a\ :sub:`5`
-
- - a\ :sub:`4`
-
- - a\ :sub:`3`
-
- - a\ :sub:`2`
-
- - a\ :sub:`1`
-
- - a\ :sub:`0`
-
- - .. _V4L2-PIX-FMT-XBGR32:
-
- - ``V4L2_PIX_FMT_XBGR32``
-
- - 'XR24'
-
- -
- - b\ :sub:`7`
-
- - b\ :sub:`6`
-
- - b\ :sub:`5`
-
- - b\ :sub:`4`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- -
- - g\ :sub:`7`
-
- - g\ :sub:`6`
-
- - g\ :sub:`5`
-
- - g\ :sub:`4`
-
- - g\ :sub:`3`
-
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- -
- - r\ :sub:`7`
-
- - r\ :sub:`6`
-
- - r\ :sub:`5`
-
- - r\ :sub:`4`
-
- - r\ :sub:`3`
-
- - r\ :sub:`2`
-
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - .. _V4L2-PIX-FMT-ARGB32:
-
- - ``V4L2_PIX_FMT_ARGB32``
-
- - 'BA24'
-
- -
- - a\ :sub:`7`
-
- - a\ :sub:`6`
-
- - a\ :sub:`5`
-
- - a\ :sub:`4`
-
- - a\ :sub:`3`
-
- - a\ :sub:`2`
-
- - a\ :sub:`1`
-
- - a\ :sub:`0`
-
- -
- - r\ :sub:`7`
-
- - r\ :sub:`6`
-
- - r\ :sub:`5`
-
- - r\ :sub:`4`
-
- - r\ :sub:`3`
-
- - r\ :sub:`2`
-
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
- -
- - g\ :sub:`7`
-
- - g\ :sub:`6`
-
- - g\ :sub:`5`
-
- - g\ :sub:`4`
-
- - g\ :sub:`3`
-
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- -
- - b\ :sub:`7`
-
- - b\ :sub:`6`
-
- - b\ :sub:`5`
-
- - b\ :sub:`4`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- - .. _V4L2-PIX-FMT-XRGB32:
-
- - ``V4L2_PIX_FMT_XRGB32``
-
- - 'BX24'
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- -
- - r\ :sub:`7`
-
- - r\ :sub:`6`
-
- - r\ :sub:`5`
-
- - r\ :sub:`4`
-
- - r\ :sub:`3`
-
- - r\ :sub:`2`
-
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
- -
- - g\ :sub:`7`
-
- - g\ :sub:`6`
-
- - g\ :sub:`5`
-
- - g\ :sub:`4`
-
- - g\ :sub:`3`
-
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- -
- - b\ :sub:`7`
-
- - b\ :sub:`6`
-
- - b\ :sub:`5`
-
- - b\ :sub:`4`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
-
-Bit 7 is the most significant bit.
-
-The usage and value of the alpha bits (a) in the ARGB and ABGR formats
-(collectively referred to as alpha formats) depend on the device type
-and hardware operation. :ref:`Capture <capture>` devices (including
-capture queues of mem-to-mem devices) fill the alpha component in
-memory. When the device outputs an alpha channel the alpha component
-will have a meaningful value. Otherwise, when the device doesn't output
-an alpha channel but can set the alpha bit to a user-configurable value,
-the :ref:`V4L2_CID_ALPHA_COMPONENT <v4l2-alpha-component>` control
-is used to specify that alpha value, and the alpha component of all
-pixels will be set to the value specified by that control. Otherwise a
-corresponding format without an alpha component (XRGB or XBGR) must be
-used instead of an alpha format.
-
-:ref:`Output <output>` devices (including output queues of mem-to-mem
-devices and :ref:`video output overlay <osd>` devices) read the alpha
-component from memory. When the device processes the alpha channel the
-alpha component must be filled with meaningful values by applications.
-Otherwise a corresponding format without an alpha component (XRGB or
-XBGR) must be used instead of an alpha format.
-
-The XRGB and XBGR formats contain undefined bits (-). Applications,
-devices and drivers must ignore those bits, for both
-:ref:`capture` and :ref:`output` devices.
-
-**Byte Order.**
-Each cell is one byte.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 2 1 1 1 1 1 1 1 1 1 1 1 1
-
-
- - .. row 1
-
- - start + 0:
-
- - B\ :sub:`00`
-
- - G\ :sub:`00`
-
- - R\ :sub:`00`
-
- - B\ :sub:`01`
-
- - G\ :sub:`01`
-
- - R\ :sub:`01`
-
- - B\ :sub:`02`
-
- - G\ :sub:`02`
-
- - R\ :sub:`02`
-
- - B\ :sub:`03`
-
- - G\ :sub:`03`
-
- - R\ :sub:`03`
-
- - .. row 2
-
- - start + 12:
-
- - B\ :sub:`10`
-
- - G\ :sub:`10`
-
- - R\ :sub:`10`
-
- - B\ :sub:`11`
-
- - G\ :sub:`11`
-
- - R\ :sub:`11`
-
- - B\ :sub:`12`
-
- - G\ :sub:`12`
-
- - R\ :sub:`12`
-
- - B\ :sub:`13`
-
- - G\ :sub:`13`
-
- - R\ :sub:`13`
-
- - .. row 3
-
- - start + 24:
-
- - B\ :sub:`20`
-
- - G\ :sub:`20`
-
- - R\ :sub:`20`
-
- - B\ :sub:`21`
-
- - G\ :sub:`21`
-
- - R\ :sub:`21`
-
- - B\ :sub:`22`
-
- - G\ :sub:`22`
-
- - R\ :sub:`22`
-
- - B\ :sub:`23`
-
- - G\ :sub:`23`
-
- - R\ :sub:`23`
-
- - .. row 4
-
- - start + 36:
-
- - B\ :sub:`30`
-
- - G\ :sub:`30`
-
- - R\ :sub:`30`
-
- - B\ :sub:`31`
-
- - G\ :sub:`31`
-
- - R\ :sub:`31`
-
- - B\ :sub:`32`
-
- - G\ :sub:`32`
-
- - R\ :sub:`32`
-
- - B\ :sub:`33`
-
- - G\ :sub:`33`
-
- - R\ :sub:`33`
-
-
-Formats defined in :ref:`rgb-formats-deprecated` are deprecated and
-must not be used by new drivers. They are documented here for reference.
-The meaning of their alpha bits (a) is ill-defined and interpreted as in
-either the corresponding ARGB or XRGB format, depending on the driver.
-
-
-.. _rgb-formats-deprecated:
-
-.. flat-table:: Deprecated Packed RGB Image Formats
- :header-rows: 2
- :stub-columns: 0
-
-
- - .. row 1
-
- - Identifier
-
- - Code
-
- -
- - :cspan:`7` Byte 0 in memory
-
- - :cspan:`7` Byte 1
-
- - :cspan:`7` Byte 2
-
- - :cspan:`7` Byte 3
-
- - .. row 2
-
- -
- -
- - Bit
-
- - 7
-
- - 6
-
- - 5
-
- - 4
-
- - 3
-
- - 2
-
- - 1
-
- - 0
-
- -
- - 7
-
- - 6
-
- - 5
-
- - 4
-
- - 3
-
- - 2
-
- - 1
-
- - 0
-
- -
- - 7
-
- - 6
-
- - 5
-
- - 4
-
- - 3
-
- - 2
-
- - 1
-
- - 0
-
- -
- - 7
-
- - 6
-
- - 5
-
- - 4
-
- - 3
-
- - 2
-
- - 1
-
- - 0
-
- - .. _V4L2-PIX-FMT-RGB444:
-
- - ``V4L2_PIX_FMT_RGB444``
-
- - 'R444'
-
- -
- - g\ :sub:`3`
-
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- -
- - a\ :sub:`3`
-
- - a\ :sub:`2`
-
- - a\ :sub:`1`
-
- - a\ :sub:`0`
-
- - r\ :sub:`3`
-
- - r\ :sub:`2`
-
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
- - .. _V4L2-PIX-FMT-RGB555:
-
- - ``V4L2_PIX_FMT_RGB555``
-
- - 'RGBO'
-
- -
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- - b\ :sub:`4`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- -
- - a
-
- - r\ :sub:`4`
-
- - r\ :sub:`3`
-
- - r\ :sub:`2`
-
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
- - g\ :sub:`4`
-
- - g\ :sub:`3`
-
- - .. _V4L2-PIX-FMT-RGB555X:
-
- - ``V4L2_PIX_FMT_RGB555X``
-
- - 'RGBQ'
-
- -
- - a
-
- - r\ :sub:`4`
-
- - r\ :sub:`3`
-
- - r\ :sub:`2`
-
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
- - g\ :sub:`4`
-
- - g\ :sub:`3`
-
- -
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- - b\ :sub:`4`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- - .. _V4L2-PIX-FMT-BGR32:
-
- - ``V4L2_PIX_FMT_BGR32``
-
- - 'BGR4'
-
- -
- - b\ :sub:`7`
-
- - b\ :sub:`6`
-
- - b\ :sub:`5`
-
- - b\ :sub:`4`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- -
- - g\ :sub:`7`
-
- - g\ :sub:`6`
-
- - g\ :sub:`5`
-
- - g\ :sub:`4`
-
- - g\ :sub:`3`
-
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- -
- - r\ :sub:`7`
-
- - r\ :sub:`6`
-
- - r\ :sub:`5`
-
- - r\ :sub:`4`
-
- - r\ :sub:`3`
-
- - r\ :sub:`2`
-
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
- -
- - a\ :sub:`7`
-
- - a\ :sub:`6`
-
- - a\ :sub:`5`
-
- - a\ :sub:`4`
-
- - a\ :sub:`3`
-
- - a\ :sub:`2`
-
- - a\ :sub:`1`
-
- - a\ :sub:`0`
-
- - .. _V4L2-PIX-FMT-RGB32:
-
- - ``V4L2_PIX_FMT_RGB32``
-
- - 'RGB4'
-
- -
- - a\ :sub:`7`
-
- - a\ :sub:`6`
-
- - a\ :sub:`5`
-
- - a\ :sub:`4`
-
- - a\ :sub:`3`
-
- - a\ :sub:`2`
-
- - a\ :sub:`1`
-
- - a\ :sub:`0`
-
- -
- - r\ :sub:`7`
-
- - r\ :sub:`6`
-
- - r\ :sub:`5`
-
- - r\ :sub:`4`
-
- - r\ :sub:`3`
-
- - r\ :sub:`2`
-
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
- -
- - g\ :sub:`7`
-
- - g\ :sub:`6`
-
- - g\ :sub:`5`
-
- - g\ :sub:`4`
-
- - g\ :sub:`3`
-
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- -
- - b\ :sub:`7`
-
- - b\ :sub:`6`
-
- - b\ :sub:`5`
-
- - b\ :sub:`4`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
-
-A test utility to determine which RGB formats a driver actually supports
-is available from the LinuxTV v4l-dvb repository. See
-`https://linuxtv.org/repo/ <https://linuxtv.org/repo/>`__ for access
-instructions.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _packed-yuv:
-
-******************
-Packed YUV formats
-******************
-
-*man Packed YUV formats(2)*
-
-Packed YUV formats
-
-
-Description
-===========
-
-Similar to the packed RGB formats these formats store the Y, Cb and Cr
-component of each pixel in one 16 or 32 bit word.
-
-
-
-.. flat-table:: Packed YUV Image Formats
- :header-rows: 2
- :stub-columns: 0
-
-
- - .. row 1
-
- - Identifier
-
- - Code
-
- -
- - :cspan:`7` Byte 0 in memory
-
- -
- - :cspan:`7` Byte 1
-
- -
- - :cspan:`7` Byte 2
-
- -
- - :cspan:`7` Byte 3
-
- - .. row 2
-
- -
- -
- - Bit
-
- - 7
-
- - 6
-
- - 5
-
- - 4
-
- - 3
-
- - 2
-
- - 1
-
- - 0
-
- -
- - 7
-
- - 6
-
- - 5
-
- - 4
-
- - 3
-
- - 2
-
- - 1
-
- - 0
-
- -
- - 7
-
- - 6
-
- - 5
-
- - 4
-
- - 3
-
- - 2
-
- - 1
-
- - 0
-
- -
- - 7
-
- - 6
-
- - 5
-
- - 4
-
- - 3
-
- - 2
-
- - 1
-
- - 0
-
- - .. _V4L2-PIX-FMT-YUV444:
-
- - ``V4L2_PIX_FMT_YUV444``
-
- - 'Y444'
-
- -
- - Cb\ :sub:`3`
-
- - Cb\ :sub:`2`
-
- - Cb\ :sub:`1`
-
- - Cb\ :sub:`0`
-
- - Cr\ :sub:`3`
-
- - Cr\ :sub:`2`
-
- - Cr\ :sub:`1`
-
- - Cr\ :sub:`0`
-
- -
- - a\ :sub:`3`
-
- - a\ :sub:`2`
-
- - a\ :sub:`1`
-
- - a\ :sub:`0`
-
- - Y'\ :sub:`3`
-
- - Y'\ :sub:`2`
-
- - Y'\ :sub:`1`
-
- - Y'\ :sub:`0`
-
- - .. _V4L2-PIX-FMT-YUV555:
-
- - ``V4L2_PIX_FMT_YUV555``
-
- - 'YUVO'
-
- -
- - Cb\ :sub:`2`
-
- - Cb\ :sub:`1`
-
- - Cb\ :sub:`0`
-
- - Cr\ :sub:`4`
-
- - Cr\ :sub:`3`
-
- - Cr\ :sub:`2`
-
- - Cr\ :sub:`1`
-
- - Cr\ :sub:`0`
-
- -
- - a
-
- - Y'\ :sub:`4`
-
- - Y'\ :sub:`3`
-
- - Y'\ :sub:`2`
-
- - Y'\ :sub:`1`
-
- - Y'\ :sub:`0`
-
- - Cb\ :sub:`4`
-
- - Cb\ :sub:`3`
-
- - .. _V4L2-PIX-FMT-YUV565:
-
- - ``V4L2_PIX_FMT_YUV565``
-
- - 'YUVP'
-
- -
- - Cb\ :sub:`2`
-
- - Cb\ :sub:`1`
-
- - Cb\ :sub:`0`
-
- - Cr\ :sub:`4`
-
- - Cr\ :sub:`3`
-
- - Cr\ :sub:`2`
-
- - Cr\ :sub:`1`
-
- - Cr\ :sub:`0`
-
- -
- - Y'\ :sub:`4`
-
- - Y'\ :sub:`3`
-
- - Y'\ :sub:`2`
-
- - Y'\ :sub:`1`
-
- - Y'\ :sub:`0`
-
- - Cb\ :sub:`5`
-
- - Cb\ :sub:`4`
-
- - Cb\ :sub:`3`
-
- - .. _V4L2-PIX-FMT-YUV32:
-
- - ``V4L2_PIX_FMT_YUV32``
-
- - 'YUV4'
-
- -
- - a\ :sub:`7`
-
- - a\ :sub:`6`
-
- - a\ :sub:`5`
-
- - a\ :sub:`4`
-
- - a\ :sub:`3`
-
- - a\ :sub:`2`
-
- - a\ :sub:`1`
-
- - a\ :sub:`0`
-
- -
- - Y'\ :sub:`7`
-
- - Y'\ :sub:`6`
-
- - Y'\ :sub:`5`
-
- - Y'\ :sub:`4`
-
- - Y'\ :sub:`3`
-
- - Y'\ :sub:`2`
-
- - Y'\ :sub:`1`
-
- - Y'\ :sub:`0`
-
- -
- - Cb\ :sub:`7`
-
- - Cb\ :sub:`6`
-
- - Cb\ :sub:`5`
-
- - Cb\ :sub:`4`
-
- - Cb\ :sub:`3`
-
- - Cb\ :sub:`2`
-
- - Cb\ :sub:`1`
-
- - Cb\ :sub:`0`
-
- -
- - Cr\ :sub:`7`
-
- - Cr\ :sub:`6`
-
- - Cr\ :sub:`5`
-
- - Cr\ :sub:`4`
-
- - Cr\ :sub:`3`
-
- - Cr\ :sub:`2`
-
- - Cr\ :sub:`1`
-
- - Cr\ :sub:`0`
-
-
-Bit 7 is the most significant bit. The value of a = alpha bits is
-undefined when reading from the driver, ignored when writing to the
-driver, except when alpha blending has been negotiated for a
-:ref:`Video Overlay <overlay>` or :ref:`Video Output Overlay <osd>`.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _pixfmt-reserved:
-
-***************************
-Reserved Format Identifiers
-***************************
-
-These formats are not defined by this specification, they are just
-listed for reference and to avoid naming conflicts. If you want to
-register your own format, send an e-mail to the linux-media mailing list
-`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__
-for inclusion in the ``videodev2.h`` file. If you want to share your
-format with other developers add a link to your documentation and send a
-copy to the linux-media mailing list for inclusion in this section. If
-you think your format should be listed in a standard format section
-please make a proposal on the linux-media mailing list.
-
-
-.. _reserved-formats:
-
-.. flat-table:: Reserved Image Formats
- :header-rows: 1
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - Identifier
-
- - Code
-
- - Details
-
- - .. _V4L2-PIX-FMT-DV:
-
- - ``V4L2_PIX_FMT_DV``
-
- - 'dvsd'
-
- - unknown
-
- - .. _V4L2-PIX-FMT-ET61X251:
-
- - ``V4L2_PIX_FMT_ET61X251``
-
- - 'E625'
-
- - Compressed format of the ET61X251 driver.
-
- - .. _V4L2-PIX-FMT-HI240:
-
- - ``V4L2_PIX_FMT_HI240``
-
- - 'HI24'
-
- - 8 bit RGB format used by the BTTV driver.
-
- - .. _V4L2-PIX-FMT-HM12:
-
- - ``V4L2_PIX_FMT_HM12``
-
- - 'HM12'
-
- - YUV 4:2:0 format used by the IVTV driver,
- `http://www.ivtvdriver.org/ <http://www.ivtvdriver.org/>`__
-
- The format is documented in the kernel sources in the file
- ``Documentation/video4linux/cx2341x/README.hm12``
-
- - .. _V4L2-PIX-FMT-CPIA1:
-
- - ``V4L2_PIX_FMT_CPIA1``
-
- - 'CPIA'
-
- - YUV format used by the gspca cpia1 driver.
-
- - .. _V4L2-PIX-FMT-JPGL:
-
- - ``V4L2_PIX_FMT_JPGL``
-
- - 'JPGL'
-
- - JPEG-Light format (Pegasus Lossless JPEG) used in Divio webcams NW
- 80x.
-
- - .. _V4L2-PIX-FMT-SPCA501:
-
- - ``V4L2_PIX_FMT_SPCA501``
-
- - 'S501'
-
- - YUYV per line used by the gspca driver.
-
- - .. _V4L2-PIX-FMT-SPCA505:
-
- - ``V4L2_PIX_FMT_SPCA505``
-
- - 'S505'
-
- - YYUV per line used by the gspca driver.
-
- - .. _V4L2-PIX-FMT-SPCA508:
-
- - ``V4L2_PIX_FMT_SPCA508``
-
- - 'S508'
-
- - YUVY per line used by the gspca driver.
-
- - .. _V4L2-PIX-FMT-SPCA561:
-
- - ``V4L2_PIX_FMT_SPCA561``
-
- - 'S561'
-
- - Compressed GBRG Bayer format used by the gspca driver.
-
- - .. _V4L2-PIX-FMT-PAC207:
-
- - ``V4L2_PIX_FMT_PAC207``
-
- - 'P207'
-
- - Compressed BGGR Bayer format used by the gspca driver.
-
- - .. _V4L2-PIX-FMT-MR97310A:
-
- - ``V4L2_PIX_FMT_MR97310A``
-
- - 'M310'
-
- - Compressed BGGR Bayer format used by the gspca driver.
-
- - .. _V4L2-PIX-FMT-JL2005BCD:
-
- - ``V4L2_PIX_FMT_JL2005BCD``
-
- - 'JL20'
-
- - JPEG compressed RGGB Bayer format used by the gspca driver.
-
- - .. _V4L2-PIX-FMT-OV511:
-
- - ``V4L2_PIX_FMT_OV511``
-
- - 'O511'
-
- - OV511 JPEG format used by the gspca driver.
-
- - .. _V4L2-PIX-FMT-OV518:
-
- - ``V4L2_PIX_FMT_OV518``
-
- - 'O518'
-
- - OV518 JPEG format used by the gspca driver.
-
- - .. _V4L2-PIX-FMT-PJPG:
-
- - ``V4L2_PIX_FMT_PJPG``
-
- - 'PJPG'
-
- - Pixart 73xx JPEG format used by the gspca driver.
-
- - .. _V4L2-PIX-FMT-SE401:
-
- - ``V4L2_PIX_FMT_SE401``
-
- - 'S401'
-
- - Compressed RGB format used by the gspca se401 driver
-
- - .. _V4L2-PIX-FMT-SQ905C:
-
- - ``V4L2_PIX_FMT_SQ905C``
-
- - '905C'
-
- - Compressed RGGB bayer format used by the gspca driver.
-
- - .. _V4L2-PIX-FMT-MJPEG:
-
- - ``V4L2_PIX_FMT_MJPEG``
-
- - 'MJPG'
-
- - Compressed format used by the Zoran driver
-
- - .. _V4L2-PIX-FMT-PWC1:
-
- - ``V4L2_PIX_FMT_PWC1``
-
- - 'PWC1'
-
- - Compressed format of the PWC driver.
-
- - .. _V4L2-PIX-FMT-PWC2:
-
- - ``V4L2_PIX_FMT_PWC2``
-
- - 'PWC2'
-
- - Compressed format of the PWC driver.
-
- - .. _V4L2-PIX-FMT-SN9C10X:
-
- - ``V4L2_PIX_FMT_SN9C10X``
-
- - 'S910'
-
- - Compressed format of the SN9C102 driver.
-
- - .. _V4L2-PIX-FMT-SN9C20X-I420:
-
- - ``V4L2_PIX_FMT_SN9C20X_I420``
-
- - 'S920'
-
- - YUV 4:2:0 format of the gspca sn9c20x driver.
-
- - .. _V4L2-PIX-FMT-SN9C2028:
-
- - ``V4L2_PIX_FMT_SN9C2028``
-
- - 'SONX'
-
- - Compressed GBRG bayer format of the gspca sn9c2028 driver.
-
- - .. _V4L2-PIX-FMT-STV0680:
-
- - ``V4L2_PIX_FMT_STV0680``
-
- - 'S680'
-
- - Bayer format of the gspca stv0680 driver.
-
- - .. _V4L2-PIX-FMT-WNVA:
-
- - ``V4L2_PIX_FMT_WNVA``
-
- - 'WNVA'
-
- - Used by the Winnov Videum driver,
- `http://www.thedirks.org/winnov/ <http://www.thedirks.org/winnov/>`__
-
- - .. _V4L2-PIX-FMT-TM6000:
-
- - ``V4L2_PIX_FMT_TM6000``
-
- - 'TM60'
-
- - Used by Trident tm6000
-
- - .. _V4L2-PIX-FMT-CIT-YYVYUY:
-
- - ``V4L2_PIX_FMT_CIT_YYVYUY``
-
- - 'CITV'
-
- - Used by xirlink CIT, found at IBM webcams.
-
- Uses one line of Y then 1 line of VYUY
-
- - .. _V4L2-PIX-FMT-KONICA420:
-
- - ``V4L2_PIX_FMT_KONICA420``
-
- - 'KONI'
-
- - Used by Konica webcams.
-
- YUV420 planar in blocks of 256 pixels.
-
- - .. _V4L2-PIX-FMT-YYUV:
-
- - ``V4L2_PIX_FMT_YYUV``
-
- - 'YYUV'
-
- - unknown
-
- - .. _V4L2-PIX-FMT-Y4:
-
- - ``V4L2_PIX_FMT_Y4``
-
- - 'Y04 '
-
- - Old 4-bit greyscale format. Only the most significant 4 bits of
- each byte are used, the other bits are set to 0.
-
- - .. _V4L2-PIX-FMT-Y6:
-
- - ``V4L2_PIX_FMT_Y6``
-
- - 'Y06 '
-
- - Old 6-bit greyscale format. Only the most significant 6 bits of
- each byte are used, the other bits are set to 0.
-
- - .. _V4L2-PIX-FMT-S5C-UYVY-JPG:
-
- - ``V4L2_PIX_FMT_S5C_UYVY_JPG``
-
- - 'S5CI'
-
- - Two-planar format used by Samsung S5C73MX cameras. The first plane
- contains interleaved JPEG and UYVY image data, followed by meta
- data in form of an array of offsets to the UYVY data blocks. The
- actual pointer array follows immediately the interleaved JPEG/UYVY
- data, the number of entries in this array equals the height of the
- UYVY image. Each entry is a 4-byte unsigned integer in big endian
- order and it's an offset to a single pixel line of the UYVY image.
- The first plane can start either with JPEG or UYVY data chunk. The
- size of a single UYVY block equals the UYVY image's width
- multiplied by 2. The size of a JPEG chunk depends on the image and
- can vary with each line.
-
- The second plane, at an offset of 4084 bytes, contains a 4-byte
- offset to the pointer array in the first plane. This offset is
- followed by a 4-byte value indicating size of the pointer array.
- All numbers in the second plane are also in big endian order.
- Remaining data in the second plane is undefined. The information
- in the second plane allows to easily find location of the pointer
- array, which can be different for each frame. The size of the
- pointer array is constant for given UYVY image height.
-
- In order to extract UYVY and JPEG frames an application can
- initially set a data pointer to the start of first plane and then
- add an offset from the first entry of the pointers table. Such a
- pointer indicates start of an UYVY image pixel line. Whole UYVY
- line can be copied to a separate buffer. These steps should be
- repeated for each line, i.e. the number of entries in the pointer
- array. Anything what's in between the UYVY lines is JPEG data and
- should be concatenated to form the JPEG stream.
-
-
-
-.. _format-flags:
-
-.. flat-table:: Format Flags
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - ``V4L2_PIX_FMT_FLAG_PREMUL_ALPHA``
-
- - 0x00000001
-
- - The color values are premultiplied by the alpha channel value. For
- example, if a light blue pixel with 50% transparency was described
- by RGBA values (128, 192, 255, 128), the same pixel described with
- premultiplied colors would be described by RGBA values (64, 96,
- 128, 128)
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _pixfmt-rgb:
-
-***********
-RGB Formats
-***********
-
-
-.. toctree::
- :maxdepth: 1
-
- pixfmt-packed-rgb
- pixfmt-sbggr8
- pixfmt-sgbrg8
- pixfmt-sgrbg8
- pixfmt-srggb8
- pixfmt-sbggr16
- pixfmt-srggb10
- pixfmt-srggb10p
- pixfmt-srggb10alaw8
- pixfmt-srggb10dpcm8
- pixfmt-srggb12
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _V4L2-PIX-FMT-SBGGR16:
-
-*****************************
-V4L2_PIX_FMT_SBGGR16 ('BYR2')
-*****************************
-
-*man V4L2_PIX_FMT_SBGGR16(2)*
-
-Bayer RGB format
-
-
-Description
-===========
-
-This format is similar to
-:ref:`V4L2_PIX_FMT_SBGGR8 <V4L2-PIX-FMT-SBGGR8>`, except each pixel
-has a depth of 16 bits. The least significant byte is stored at lower
-memory addresses (little-endian). Note the actual sampling precision may
-be lower than 16 bits, for example 10 bits per pixel with values in
-range 0 to 1023.
-
-**Byte Order.**
-Each cell is one byte.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 2 1 1 1 1 1 1 1 1
-
-
- - .. row 1
-
- - start + 0:
-
- - B\ :sub:`00low`
-
- - B\ :sub:`00high`
-
- - G\ :sub:`01low`
-
- - G\ :sub:`01high`
-
- - B\ :sub:`02low`
-
- - B\ :sub:`02high`
-
- - G\ :sub:`03low`
-
- - G\ :sub:`03high`
-
- - .. row 2
-
- - start + 8:
-
- - G\ :sub:`10low`
-
- - G\ :sub:`10high`
-
- - R\ :sub:`11low`
-
- - R\ :sub:`11high`
-
- - G\ :sub:`12low`
-
- - G\ :sub:`12high`
-
- - R\ :sub:`13low`
-
- - R\ :sub:`13high`
-
- - .. row 3
-
- - start + 16:
-
- - B\ :sub:`20low`
-
- - B\ :sub:`20high`
-
- - G\ :sub:`21low`
-
- - G\ :sub:`21high`
-
- - B\ :sub:`22low`
-
- - B\ :sub:`22high`
-
- - G\ :sub:`23low`
-
- - G\ :sub:`23high`
-
- - .. row 4
-
- - start + 24:
-
- - G\ :sub:`30low`
-
- - G\ :sub:`30high`
-
- - R\ :sub:`31low`
-
- - R\ :sub:`31high`
-
- - G\ :sub:`32low`
-
- - G\ :sub:`32high`
-
- - R\ :sub:`33low`
-
- - R\ :sub:`33high`
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _V4L2-PIX-FMT-SBGGR8:
-
-****************************
-V4L2_PIX_FMT_SBGGR8 ('BA81')
-****************************
-
-*man V4L2_PIX_FMT_SBGGR8(2)*
-
-Bayer RGB format
-
-
-Description
-===========
-
-This is commonly the native format of digital cameras, reflecting the
-arrangement of sensors on the CCD device. Only one red, green or blue
-value is given for each pixel. Missing components must be interpolated
-from neighbouring pixels. From left to right the first row consists of a
-blue and green value, the second row of a green and red value. This
-scheme repeats to the right and down for every two columns and rows.
-
-**Byte Order.**
-Each cell is one byte.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 2 1 1 1 1
-
-
- - .. row 1
-
- - start + 0:
-
- - B\ :sub:`00`
-
- - G\ :sub:`01`
-
- - B\ :sub:`02`
-
- - G\ :sub:`03`
-
- - .. row 2
-
- - start + 4:
-
- - G\ :sub:`10`
-
- - R\ :sub:`11`
-
- - G\ :sub:`12`
-
- - R\ :sub:`13`
-
- - .. row 3
-
- - start + 8:
-
- - B\ :sub:`20`
-
- - G\ :sub:`21`
-
- - B\ :sub:`22`
-
- - G\ :sub:`23`
-
- - .. row 4
-
- - start + 12:
-
- - G\ :sub:`30`
-
- - R\ :sub:`31`
-
- - G\ :sub:`32`
-
- - R\ :sub:`33`
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _v4l2-sdr-fmt-cs8:
-
-*************************
-V4L2_SDR_FMT_CS8 ('CS08')
-*************************
-
-*man V4L2_SDR_FMT_CS8(2)*
-
-Complex signed 8-bit IQ sample
-
-
-Description
-===========
-
-This format contains sequence of complex number samples. Each complex
-number consist two parts, called In-phase and Quadrature (IQ). Both I
-and Q are represented as a 8 bit signed number. I value comes first and
-Q value after that.
-
-**Byte Order.**
-Each cell is one byte.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 2 1
-
-
- - .. row 1
-
- - start + 0:
-
- - I'\ :sub:`0`
-
- - .. row 2
-
- - start + 1:
-
- - Q'\ :sub:`0`
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _V4L2-SDR-FMT-CS14LE:
-
-****************************
-V4L2_SDR_FMT_CS14LE ('CS14')
-****************************
-
-*man V4L2_SDR_FMT_CS14LE(2)*
-
-Complex signed 14-bit little endian IQ sample
-
-
-Description
-===========
-
-This format contains sequence of complex number samples. Each complex
-number consist two parts, called In-phase and Quadrature (IQ). Both I
-and Q are represented as a 14 bit signed little endian number. I value
-comes first and Q value after that. 14 bit value is stored in 16 bit
-space with unused high bits padded with 0.
-
-**Byte Order.**
-Each cell is one byte.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 2 1 1
-
-
- - .. row 1
-
- - start + 0:
-
- - I'\ :sub:`0[7:0]`
-
- - I'\ :sub:`0[13:8]`
-
- - .. row 2
-
- - start + 2:
-
- - Q'\ :sub:`0[7:0]`
-
- - Q'\ :sub:`0[13:8]`
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _v4l2-sdr-fmt-cu8:
-
-*************************
-V4L2_SDR_FMT_CU8 ('CU08')
-*************************
-
-*man V4L2_SDR_FMT_CU8(2)*
-
-Complex unsigned 8-bit IQ sample
-
-
-Description
-===========
-
-This format contains sequence of complex number samples. Each complex
-number consist two parts, called In-phase and Quadrature (IQ). Both I
-and Q are represented as a 8 bit unsigned number. I value comes first
-and Q value after that.
-
-**Byte Order.**
-Each cell is one byte.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 2 1
-
-
- - .. row 1
-
- - start + 0:
-
- - I'\ :sub:`0`
-
- - .. row 2
-
- - start + 1:
-
- - Q'\ :sub:`0`
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _V4L2-SDR-FMT-CU16LE:
-
-****************************
-V4L2_SDR_FMT_CU16LE ('CU16')
-****************************
-
-*man V4L2_SDR_FMT_CU16LE(2)*
-
-Complex unsigned 16-bit little endian IQ sample
-
-
-Description
-===========
-
-This format contains sequence of complex number samples. Each complex
-number consist two parts, called In-phase and Quadrature (IQ). Both I
-and Q are represented as a 16 bit unsigned little endian number. I value
-comes first and Q value after that.
-
-**Byte Order.**
-Each cell is one byte.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 2 1 1
-
-
- - .. row 1
-
- - start + 0:
-
- - I'\ :sub:`0[7:0]`
-
- - I'\ :sub:`0[15:8]`
-
- - .. row 2
-
- - start + 2:
-
- - Q'\ :sub:`0[7:0]`
-
- - Q'\ :sub:`0[15:8]`
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _V4L2-SDR-FMT-RU12LE:
-
-****************************
-V4L2_SDR_FMT_RU12LE ('RU12')
-****************************
-
-*man V4L2_SDR_FMT_RU12LE(2)*
-
-Real unsigned 12-bit little endian sample
-
-
-Description
-===========
-
-This format contains sequence of real number samples. Each sample is
-represented as a 12 bit unsigned little endian number. Sample is stored
-in 16 bit space with unused high bits padded with 0.
-
-**Byte Order.**
-Each cell is one byte.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 2 1 1
-
-
- - .. row 1
-
- - start + 0:
-
- - I'\ :sub:`0[7:0]`
-
- - I'\ :sub:`0[11:8]`
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _V4L2-PIX-FMT-SGBRG8:
-
-****************************
-V4L2_PIX_FMT_SGBRG8 ('GBRG')
-****************************
-
-*man V4L2_PIX_FMT_SGBRG8(2)*
-
-Bayer RGB format
-
-
-Description
-===========
-
-This is commonly the native format of digital cameras, reflecting the
-arrangement of sensors on the CCD device. Only one red, green or blue
-value is given for each pixel. Missing components must be interpolated
-from neighbouring pixels. From left to right the first row consists of a
-green and blue value, the second row of a red and green value. This
-scheme repeats to the right and down for every two columns and rows.
-
-**Byte Order.**
-Each cell is one byte.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 2 1 1 1 1
-
-
- - .. row 1
-
- - start + 0:
-
- - G\ :sub:`00`
-
- - B\ :sub:`01`
-
- - G\ :sub:`02`
-
- - B\ :sub:`03`
-
- - .. row 2
-
- - start + 4:
-
- - R\ :sub:`10`
-
- - G\ :sub:`11`
-
- - R\ :sub:`12`
-
- - G\ :sub:`13`
-
- - .. row 3
-
- - start + 8:
-
- - G\ :sub:`20`
-
- - B\ :sub:`21`
-
- - G\ :sub:`22`
-
- - B\ :sub:`23`
-
- - .. row 4
-
- - start + 12:
-
- - R\ :sub:`30`
-
- - G\ :sub:`31`
-
- - R\ :sub:`32`
-
- - G\ :sub:`33`
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _V4L2-PIX-FMT-SGRBG8:
-
-****************************
-V4L2_PIX_FMT_SGRBG8 ('GRBG')
-****************************
-
-*man V4L2_PIX_FMT_SGRBG8(2)*
-
-Bayer RGB format
-
-
-Description
-===========
-
-This is commonly the native format of digital cameras, reflecting the
-arrangement of sensors on the CCD device. Only one red, green or blue
-value is given for each pixel. Missing components must be interpolated
-from neighbouring pixels. From left to right the first row consists of a
-green and blue value, the second row of a red and green value. This
-scheme repeats to the right and down for every two columns and rows.
-
-**Byte Order.**
-Each cell is one byte.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 2 1 1 1 1
-
-
- - .. row 1
-
- - start + 0:
-
- - G\ :sub:`00`
-
- - R\ :sub:`01`
-
- - G\ :sub:`02`
-
- - R\ :sub:`03`
-
- - .. row 2
-
- - start + 4:
-
- - B\ :sub:`10`
-
- - G\ :sub:`11`
-
- - B\ :sub:`12`
-
- - G\ :sub:`13`
-
- - .. row 3
-
- - start + 8:
-
- - G\ :sub:`20`
-
- - R\ :sub:`21`
-
- - G\ :sub:`22`
-
- - R\ :sub:`23`
-
- - .. row 4
-
- - start + 12:
-
- - B\ :sub:`30`
-
- - G\ :sub:`31`
-
- - B\ :sub:`32`
-
- - G\ :sub:`33`
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _V4L2-PIX-FMT-SRGGB10:
-.. _v4l2-pix-fmt-sbggr10:
-.. _v4l2-pix-fmt-sgbrg10:
-.. _v4l2-pix-fmt-sgrbg10:
-
-***************************************************************************************************************************
-V4L2_PIX_FMT_SRGGB10 ('RG10'), V4L2_PIX_FMT_SGRBG10 ('BA10'), V4L2_PIX_FMT_SGBRG10 ('GB10'), V4L2_PIX_FMT_SBGGR10 ('BG10'),
-***************************************************************************************************************************
-
-*man V4L2_PIX_FMT_SRGGB10(2)*
-
-V4L2_PIX_FMT_SGRBG10
-V4L2_PIX_FMT_SGBRG10
-V4L2_PIX_FMT_SBGGR10
-10-bit Bayer formats expanded to 16 bits
-
-
-Description
-===========
-
-These four pixel formats are raw sRGB / Bayer formats with 10 bits per
-colour. Each colour component is stored in a 16-bit word, with 6 unused
-high bits filled with zeros. Each n-pixel row contains n/2 green samples
-and n/2 blue or red samples, with alternating red and blue rows. Bytes
-are stored in memory in little endian order. They are conventionally
-described as GRGR... BGBG..., RGRG... GBGB..., etc. Below is an example
-of one of these formats
-
-**Byte Order.**
-Each cell is one byte, high 6 bits in high bytes are 0.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 2 1 1 1 1 1 1 1 1
-
-
- - .. row 1
-
- - start + 0:
-
- - B\ :sub:`00low`
-
- - B\ :sub:`00high`
-
- - G\ :sub:`01low`
-
- - G\ :sub:`01high`
-
- - B\ :sub:`02low`
-
- - B\ :sub:`02high`
-
- - G\ :sub:`03low`
-
- - G\ :sub:`03high`
-
- - .. row 2
-
- - start + 8:
-
- - G\ :sub:`10low`
-
- - G\ :sub:`10high`
-
- - R\ :sub:`11low`
-
- - R\ :sub:`11high`
-
- - G\ :sub:`12low`
-
- - G\ :sub:`12high`
-
- - R\ :sub:`13low`
-
- - R\ :sub:`13high`
-
- - .. row 3
-
- - start + 16:
-
- - B\ :sub:`20low`
-
- - B\ :sub:`20high`
-
- - G\ :sub:`21low`
-
- - G\ :sub:`21high`
-
- - B\ :sub:`22low`
-
- - B\ :sub:`22high`
-
- - G\ :sub:`23low`
-
- - G\ :sub:`23high`
-
- - .. row 4
-
- - start + 24:
-
- - G\ :sub:`30low`
-
- - G\ :sub:`30high`
-
- - R\ :sub:`31low`
-
- - R\ :sub:`31high`
-
- - G\ :sub:`32low`
-
- - G\ :sub:`32high`
-
- - R\ :sub:`33low`
-
- - R\ :sub:`33high`
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _V4L2-PIX-FMT-SBGGR10ALAW8:
-.. _v4l2-pix-fmt-sgbrg10alaw8:
-.. _v4l2-pix-fmt-sgrbg10alaw8:
-.. _v4l2-pix-fmt-srggb10alaw8:
-
-***********************************************************************************************************************************************
-V4L2_PIX_FMT_SBGGR10ALAW8 ('aBA8'), V4L2_PIX_FMT_SGBRG10ALAW8 ('aGA8'), V4L2_PIX_FMT_SGRBG10ALAW8 ('agA8'), V4L2_PIX_FMT_SRGGB10ALAW8 ('aRA8'),
-***********************************************************************************************************************************************
-
-*man V4L2_PIX_FMT_SBGGR10ALAW8(2)*
-
-V4L2_PIX_FMT_SGBRG10ALAW8
-V4L2_PIX_FMT_SGRBG10ALAW8
-V4L2_PIX_FMT_SRGGB10ALAW8
-10-bit Bayer formats compressed to 8 bits
-
-
-Description
-===========
-
-These four pixel formats are raw sRGB / Bayer formats with 10 bits per
-color compressed to 8 bits each, using the A-LAW algorithm. Each color
-component consumes 8 bits of memory. In other respects this format is
-similar to :ref:`V4L2-PIX-FMT-SRGGB8`.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _V4L2-PIX-FMT-SBGGR10DPCM8:
-.. _v4l2-pix-fmt-sgbrg10dpcm8:
-.. _v4l2-pix-fmt-sgrbg10dpcm8:
-.. _v4l2-pix-fmt-srggb10dpcm8:
-
-
-***********************************************************************************************************************************************
-V4L2_PIX_FMT_SBGGR10DPCM8 ('bBA8'), V4L2_PIX_FMT_SGBRG10DPCM8 ('bGA8'), V4L2_PIX_FMT_SGRBG10DPCM8 ('BD10'), V4L2_PIX_FMT_SRGGB10DPCM8 ('bRA8'),
-***********************************************************************************************************************************************
-
-*man V4L2_PIX_FMT_SBGGR10DPCM8(2)*
-
-V4L2_PIX_FMT_SGBRG10DPCM8
-V4L2_PIX_FMT_SGRBG10DPCM8
-V4L2_PIX_FMT_SRGGB10DPCM8
-10-bit Bayer formats compressed to 8 bits
-
-
-Description
-===========
-
-These four pixel formats are raw sRGB / Bayer formats with 10 bits per
-colour compressed to 8 bits each, using DPCM compression. DPCM,
-differential pulse-code modulation, is lossy. Each colour component
-consumes 8 bits of memory. In other respects this format is similar to
-:ref:`V4L2-PIX-FMT-SRGGB10`.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _V4L2-PIX-FMT-SRGGB10P:
-.. _v4l2-pix-fmt-sbggr10p:
-.. _v4l2-pix-fmt-sgbrg10p:
-.. _v4l2-pix-fmt-sgrbg10p:
-
-*******************************************************************************************************************************
-V4L2_PIX_FMT_SRGGB10P ('pRAA'), V4L2_PIX_FMT_SGRBG10P ('pgAA'), V4L2_PIX_FMT_SGBRG10P ('pGAA'), V4L2_PIX_FMT_SBGGR10P ('pBAA'),
-*******************************************************************************************************************************
-
-*man V4L2_PIX_FMT_SRGGB10P(2)*
-
-V4L2_PIX_FMT_SGRBG10P
-V4L2_PIX_FMT_SGBRG10P
-V4L2_PIX_FMT_SBGGR10P
-10-bit packed Bayer formats
-
-
-Description
-===========
-
-These four pixel formats are packed raw sRGB / Bayer formats with 10
-bits per colour. Every four consecutive colour components are packed
-into 5 bytes. Each of the first 4 bytes contain the 8 high order bits of
-the pixels, and the fifth byte contains the two least significants bits
-of each pixel, in the same order.
-
-Each n-pixel row contains n/2 green samples and n/2 blue or red samples,
-with alternating green-red and green-blue rows. They are conventionally
-described as GRGR... BGBG..., RGRG... GBGB..., etc. Below is an example
-of one of these formats:
-
-**Byte Order.**
-Each cell is one byte.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 2 1 1 1 1 1
-
-
- - .. row 1
-
- - start + 0:
-
- - B\ :sub:`00high`
-
- - G\ :sub:`01high`
-
- - B\ :sub:`02high`
-
- - G\ :sub:`03high`
-
- - B\ :sub:`00low`\ (bits 7--6) G\ :sub:`01low`\ (bits 5--4)
- B\ :sub:`02low`\ (bits 3--2) G\ :sub:`03low`\ (bits 1--0)
-
- - .. row 2
-
- - start + 5:
-
- - G\ :sub:`10high`
-
- - R\ :sub:`11high`
-
- - G\ :sub:`12high`
-
- - R\ :sub:`13high`
-
- - G\ :sub:`10low`\ (bits 7--6) R\ :sub:`11low`\ (bits 5--4)
- G\ :sub:`12low`\ (bits 3--2) R\ :sub:`13low`\ (bits 1--0)
-
- - .. row 3
-
- - start + 10:
-
- - B\ :sub:`20high`
-
- - G\ :sub:`21high`
-
- - B\ :sub:`22high`
-
- - G\ :sub:`23high`
-
- - B\ :sub:`20low`\ (bits 7--6) G\ :sub:`21low`\ (bits 5--4)
- B\ :sub:`22low`\ (bits 3--2) G\ :sub:`23low`\ (bits 1--0)
-
- - .. row 4
-
- - start + 15:
-
- - G\ :sub:`30high`
-
- - R\ :sub:`31high`
-
- - G\ :sub:`32high`
-
- - R\ :sub:`33high`
-
- - G\ :sub:`30low`\ (bits 7--6) R\ :sub:`31low`\ (bits 5--4)
- G\ :sub:`32low`\ (bits 3--2) R\ :sub:`33low`\ (bits 1--0)
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _V4L2-PIX-FMT-SRGGB12:
-.. _v4l2-pix-fmt-sbggr12:
-.. _v4l2-pix-fmt-sgbrg12:
-.. _v4l2-pix-fmt-sgrbg12:
-
-
-***************************************************************************************************************************
-V4L2_PIX_FMT_SRGGB12 ('RG12'), V4L2_PIX_FMT_SGRBG12 ('BA12'), V4L2_PIX_FMT_SGBRG12 ('GB12'), V4L2_PIX_FMT_SBGGR12 ('BG12'),
-***************************************************************************************************************************
-
-*man V4L2_PIX_FMT_SRGGB12(2)*
-
-V4L2_PIX_FMT_SGRBG12
-V4L2_PIX_FMT_SGBRG12
-V4L2_PIX_FMT_SBGGR12
-12-bit Bayer formats expanded to 16 bits
-
-
-Description
-===========
-
-These four pixel formats are raw sRGB / Bayer formats with 12 bits per
-colour. Each colour component is stored in a 16-bit word, with 4 unused
-high bits filled with zeros. Each n-pixel row contains n/2 green samples
-and n/2 blue or red samples, with alternating red and blue rows. Bytes
-are stored in memory in little endian order. They are conventionally
-described as GRGR... BGBG..., RGRG... GBGB..., etc. Below is an example
-of one of these formats
-
-**Byte Order.**
-Each cell is one byte, high 6 bits in high bytes are 0.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 2 1 1 1 1 1 1 1 1
-
-
- - .. row 1
-
- - start + 0:
-
- - B\ :sub:`00low`
-
- - B\ :sub:`00high`
-
- - G\ :sub:`01low`
-
- - G\ :sub:`01high`
-
- - B\ :sub:`02low`
-
- - B\ :sub:`02high`
-
- - G\ :sub:`03low`
-
- - G\ :sub:`03high`
-
- - .. row 2
-
- - start + 8:
-
- - G\ :sub:`10low`
-
- - G\ :sub:`10high`
-
- - R\ :sub:`11low`
-
- - R\ :sub:`11high`
-
- - G\ :sub:`12low`
-
- - G\ :sub:`12high`
-
- - R\ :sub:`13low`
-
- - R\ :sub:`13high`
-
- - .. row 3
-
- - start + 16:
-
- - B\ :sub:`20low`
-
- - B\ :sub:`20high`
-
- - G\ :sub:`21low`
-
- - G\ :sub:`21high`
-
- - B\ :sub:`22low`
-
- - B\ :sub:`22high`
-
- - G\ :sub:`23low`
-
- - G\ :sub:`23high`
-
- - .. row 4
-
- - start + 24:
-
- - G\ :sub:`30low`
-
- - G\ :sub:`30high`
-
- - R\ :sub:`31low`
-
- - R\ :sub:`31high`
-
- - G\ :sub:`32low`
-
- - G\ :sub:`32high`
-
- - R\ :sub:`33low`
-
- - R\ :sub:`33high`
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _V4L2-PIX-FMT-SRGGB8:
-
-****************************
-V4L2_PIX_FMT_SRGGB8 ('RGGB')
-****************************
-
-*man V4L2_PIX_FMT_SRGGB8(2)*
-
-Bayer RGB format
-
-
-Description
-===========
-
-This is commonly the native format of digital cameras, reflecting the
-arrangement of sensors on the CCD device. Only one red, green or blue
-value is given for each pixel. Missing components must be interpolated
-from neighbouring pixels. From left to right the first row consists of a
-red and green value, the second row of a green and blue value. This
-scheme repeats to the right and down for every two columns and rows.
-
-**Byte Order.**
-Each cell is one byte.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 2 1 1 1 1
-
-
- - .. row 1
-
- - start + 0:
-
- - R\ :sub:`00`
-
- - G\ :sub:`01`
-
- - R\ :sub:`02`
-
- - G\ :sub:`03`
-
- - .. row 2
-
- - start + 4:
-
- - G\ :sub:`10`
-
- - B\ :sub:`11`
-
- - G\ :sub:`12`
-
- - B\ :sub:`13`
-
- - .. row 3
-
- - start + 8:
-
- - R\ :sub:`20`
-
- - G\ :sub:`21`
-
- - R\ :sub:`22`
-
- - G\ :sub:`23`
-
- - .. row 4
-
- - start + 12:
-
- - G\ :sub:`30`
-
- - B\ :sub:`31`
-
- - G\ :sub:`32`
-
- - B\ :sub:`33`
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _V4L2-PIX-FMT-UV8:
-
-************************
-V4L2_PIX_FMT_UV8 ('UV8')
-************************
-
-*man V4L2_PIX_FMT_UV8(2)*
-
-UV plane interleaved
-
-
-Description
-===========
-
-In this format there is no Y plane, Only CbCr plane. ie (UV interleaved)
-
-**Byte Order.**
-Each cell is one byte.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 2 1 1 1 1
-
-
- - .. row 1
-
- - start + 0:
-
- - Cb\ :sub:`00`
-
- - Cr\ :sub:`00`
-
- - Cb\ :sub:`01`
-
- - Cr\ :sub:`01`
-
- - .. row 2
-
- - start + 4:
-
- - Cb\ :sub:`10`
-
- - Cr\ :sub:`10`
-
- - Cb\ :sub:`11`
-
- - Cr\ :sub:`11`
-
- - .. row 3
-
- - start + 8:
-
- - Cb\ :sub:`20`
-
- - Cr\ :sub:`20`
-
- - Cb\ :sub:`21`
-
- - Cr\ :sub:`21`
-
- - .. row 4
-
- - start + 12:
-
- - Cb\ :sub:`30`
-
- - Cr\ :sub:`30`
-
- - Cb\ :sub:`31`
-
- - Cr\ :sub:`31`
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _V4L2-PIX-FMT-UYVY:
-
-**************************
-V4L2_PIX_FMT_UYVY ('UYVY')
-**************************
-
-*man V4L2_PIX_FMT_UYVY(2)*
-
-Variation of ``V4L2_PIX_FMT_YUYV`` with different order of samples in
-memory
-
-
-Description
-===========
-
-In this format each four bytes is two pixels. Each four bytes is two
-Y's, a Cb and a Cr. Each Y goes to one of the pixels, and the Cb and Cr
-belong to both pixels. As you can see, the Cr and Cb components have
-half the horizontal resolution of the Y component.
-
-**Byte Order.**
-Each cell is one byte.
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 2 1 1 1 1 1 1 1 1
-
-
- - .. row 1
-
- - start + 0:
-
- - Cb\ :sub:`00`
-
- - Y'\ :sub:`00`
-
- - Cr\ :sub:`00`
-
- - Y'\ :sub:`01`
-
- - Cb\ :sub:`01`
-
- - Y'\ :sub:`02`
-
- - Cr\ :sub:`01`
-
- - Y'\ :sub:`03`
-
- - .. row 2
-
- - start + 8:
-
- - Cb\ :sub:`10`
-
- - Y'\ :sub:`10`
-
- - Cr\ :sub:`10`
-
- - Y'\ :sub:`11`
-
- - Cb\ :sub:`11`
-
- - Y'\ :sub:`12`
-
- - Cr\ :sub:`11`
-
- - Y'\ :sub:`13`
-
- - .. row 3
-
- - start + 16:
-
- - Cb\ :sub:`20`
-
- - Y'\ :sub:`20`
-
- - Cr\ :sub:`20`
-
- - Y'\ :sub:`21`
-
- - Cb\ :sub:`21`
-
- - Y'\ :sub:`22`
-
- - Cr\ :sub:`21`
-
- - Y'\ :sub:`23`
-
- - .. row 4
-
- - start + 24:
-
- - Cb\ :sub:`30`
-
- - Y'\ :sub:`30`
-
- - Cr\ :sub:`30`
-
- - Y'\ :sub:`31`
-
- - Cb\ :sub:`31`
-
- - Y'\ :sub:`32`
-
- - Cr\ :sub:`31`
-
- - Y'\ :sub:`33`
-
-
-**Color Sample Location..**
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- -
- - 0
-
- -
- - 1
-
- - 2
-
- -
- - 3
-
- - .. row 2
-
- - 0
-
- - Y
-
- - C
-
- - Y
-
- - Y
-
- - C
-
- - Y
-
- - .. row 3
-
- - 1
-
- - Y
-
- - C
-
- - Y
-
- - Y
-
- - C
-
- - Y
-
- - .. row 4
-
- - 2
-
- - Y
-
- - C
-
- - Y
-
- - Y
-
- - C
-
- - Y
-
- - .. row 5
-
- - 3
-
- - Y
-
- - C
-
- - Y
-
- - Y
-
- - C
-
- - Y
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _V4L2-PIX-FMT-VYUY:
-
-**************************
-V4L2_PIX_FMT_VYUY ('VYUY')
-**************************
-
-*man V4L2_PIX_FMT_VYUY(2)*
-
-Variation of ``V4L2_PIX_FMT_YUYV`` with different order of samples in
-memory
-
-
-Description
-===========
-
-In this format each four bytes is two pixels. Each four bytes is two
-Y's, a Cb and a Cr. Each Y goes to one of the pixels, and the Cb and Cr
-belong to both pixels. As you can see, the Cr and Cb components have
-half the horizontal resolution of the Y component.
-
-**Byte Order.**
-Each cell is one byte.
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 2 1 1 1 1 1 1 1 1
-
-
- - .. row 1
-
- - start + 0:
-
- - Cr\ :sub:`00`
-
- - Y'\ :sub:`00`
-
- - Cb\ :sub:`00`
-
- - Y'\ :sub:`01`
-
- - Cr\ :sub:`01`
-
- - Y'\ :sub:`02`
-
- - Cb\ :sub:`01`
-
- - Y'\ :sub:`03`
-
- - .. row 2
-
- - start + 8:
-
- - Cr\ :sub:`10`
-
- - Y'\ :sub:`10`
-
- - Cb\ :sub:`10`
-
- - Y'\ :sub:`11`
-
- - Cr\ :sub:`11`
-
- - Y'\ :sub:`12`
-
- - Cb\ :sub:`11`
-
- - Y'\ :sub:`13`
-
- - .. row 3
-
- - start + 16:
-
- - Cr\ :sub:`20`
-
- - Y'\ :sub:`20`
-
- - Cb\ :sub:`20`
-
- - Y'\ :sub:`21`
-
- - Cr\ :sub:`21`
-
- - Y'\ :sub:`22`
-
- - Cb\ :sub:`21`
-
- - Y'\ :sub:`23`
-
- - .. row 4
-
- - start + 24:
-
- - Cr\ :sub:`30`
-
- - Y'\ :sub:`30`
-
- - Cb\ :sub:`30`
-
- - Y'\ :sub:`31`
-
- - Cr\ :sub:`31`
-
- - Y'\ :sub:`32`
-
- - Cb\ :sub:`31`
-
- - Y'\ :sub:`33`
-
-
-**Color Sample Location..**
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- -
- - 0
-
- -
- - 1
-
- -
- - 2
-
- - 3
-
- - .. row 2
-
- - 0
-
- - Y
-
- - C
-
- - Y
-
- - Y
-
- - C
-
- - Y
-
- - .. row 3
-
- - 1
-
- - Y
-
- - C
-
- - Y
-
- - Y
-
- - C
-
- - Y
-
- - .. row 4
-
- - 2
-
- - Y
-
- - C
-
- - Y
-
- - Y
-
- - C
-
- - Y
-
- - .. row 5
-
- - 3
-
- - Y
-
- - C
-
- - Y
-
- - Y
-
- - C
-
- - Y
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _V4L2-PIX-FMT-Y10:
-
-*************************
-V4L2_PIX_FMT_Y10 ('Y10 ')
-*************************
-
-*man V4L2_PIX_FMT_Y10(2)*
-
-Grey-scale image
-
-
-Description
-===========
-
-This is a grey-scale image with a depth of 10 bits per pixel. Pixels are
-stored in 16-bit words with unused high bits padded with 0. The least
-significant byte is stored at lower memory addresses (little-endian).
-
-**Byte Order.**
-Each cell is one byte.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 2 1 1 1 1 1 1 1 1
-
-
- - .. row 1
-
- - start + 0:
-
- - Y'\ :sub:`00low`
-
- - Y'\ :sub:`00high`
-
- - Y'\ :sub:`01low`
-
- - Y'\ :sub:`01high`
-
- - Y'\ :sub:`02low`
-
- - Y'\ :sub:`02high`
-
- - Y'\ :sub:`03low`
-
- - Y'\ :sub:`03high`
-
- - .. row 2
-
- - start + 8:
-
- - Y'\ :sub:`10low`
-
- - Y'\ :sub:`10high`
-
- - Y'\ :sub:`11low`
-
- - Y'\ :sub:`11high`
-
- - Y'\ :sub:`12low`
-
- - Y'\ :sub:`12high`
-
- - Y'\ :sub:`13low`
-
- - Y'\ :sub:`13high`
-
- - .. row 3
-
- - start + 16:
-
- - Y'\ :sub:`20low`
-
- - Y'\ :sub:`20high`
-
- - Y'\ :sub:`21low`
-
- - Y'\ :sub:`21high`
-
- - Y'\ :sub:`22low`
-
- - Y'\ :sub:`22high`
-
- - Y'\ :sub:`23low`
-
- - Y'\ :sub:`23high`
-
- - .. row 4
-
- - start + 24:
-
- - Y'\ :sub:`30low`
-
- - Y'\ :sub:`30high`
-
- - Y'\ :sub:`31low`
-
- - Y'\ :sub:`31high`
-
- - Y'\ :sub:`32low`
-
- - Y'\ :sub:`32high`
-
- - Y'\ :sub:`33low`
-
- - Y'\ :sub:`33high`
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _V4L2-PIX-FMT-Y10BPACK:
-
-******************************
-V4L2_PIX_FMT_Y10BPACK ('Y10B')
-******************************
-
-*man V4L2_PIX_FMT_Y10BPACK(2)*
-
-Grey-scale image as a bit-packed array
-
-
-Description
-===========
-
-This is a packed grey-scale image format with a depth of 10 bits per
-pixel. Pixels are stored in a bit-packed array of 10bit bits per pixel,
-with no padding between them and with the most significant bits coming
-first from the left.
-
-**Bit-packed representation.**
-
-pixels cross the byte boundary and have a ratio of 5 bytes for each 4
-pixels.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 2 1 1 1 1
-
-
- - .. row 1
-
- - Y'\ :sub:`00[9:2]`
-
- - Y'\ :sub:`00[1:0]`\ Y'\ :sub:`01[9:4]`
-
- - Y'\ :sub:`01[3:0]`\ Y'\ :sub:`02[9:6]`
-
- - Y'\ :sub:`02[5:0]`\ Y'\ :sub:`03[9:8]`
-
- - Y'\ :sub:`03[7:0]`
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _V4L2-PIX-FMT-Y12:
-
-*************************
-V4L2_PIX_FMT_Y12 ('Y12 ')
-*************************
-
-*man V4L2_PIX_FMT_Y12(2)*
-
-Grey-scale image
-
-
-Description
-===========
-
-This is a grey-scale image with a depth of 12 bits per pixel. Pixels are
-stored in 16-bit words with unused high bits padded with 0. The least
-significant byte is stored at lower memory addresses (little-endian).
-
-**Byte Order.**
-Each cell is one byte.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 2 1 1 1 1 1 1 1 1
-
-
- - .. row 1
-
- - start + 0:
-
- - Y'\ :sub:`00low`
-
- - Y'\ :sub:`00high`
-
- - Y'\ :sub:`01low`
-
- - Y'\ :sub:`01high`
-
- - Y'\ :sub:`02low`
-
- - Y'\ :sub:`02high`
-
- - Y'\ :sub:`03low`
-
- - Y'\ :sub:`03high`
-
- - .. row 2
-
- - start + 8:
-
- - Y'\ :sub:`10low`
-
- - Y'\ :sub:`10high`
-
- - Y'\ :sub:`11low`
-
- - Y'\ :sub:`11high`
-
- - Y'\ :sub:`12low`
-
- - Y'\ :sub:`12high`
-
- - Y'\ :sub:`13low`
-
- - Y'\ :sub:`13high`
-
- - .. row 3
-
- - start + 16:
-
- - Y'\ :sub:`20low`
-
- - Y'\ :sub:`20high`
-
- - Y'\ :sub:`21low`
-
- - Y'\ :sub:`21high`
-
- - Y'\ :sub:`22low`
-
- - Y'\ :sub:`22high`
-
- - Y'\ :sub:`23low`
-
- - Y'\ :sub:`23high`
-
- - .. row 4
-
- - start + 24:
-
- - Y'\ :sub:`30low`
-
- - Y'\ :sub:`30high`
-
- - Y'\ :sub:`31low`
-
- - Y'\ :sub:`31high`
-
- - Y'\ :sub:`32low`
-
- - Y'\ :sub:`32high`
-
- - Y'\ :sub:`33low`
-
- - Y'\ :sub:`33high`
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _V4L2-PIX-FMT-Y12I:
-
-**************************
-V4L2_PIX_FMT_Y12I ('Y12I')
-**************************
-
-*man V4L2_PIX_FMT_Y12I(2)*
-
-Interleaved grey-scale image, e.g. from a stereo-pair
-
-
-Description
-===========
-
-This is a grey-scale image with a depth of 12 bits per pixel, but with
-pixels from 2 sources interleaved and bit-packed. Each pixel is stored
-in a 24-bit word in the little-endian order. On a little-endian machine
-these pixels can be deinterlaced using
-
-.. code-block:: c
-
- __u8 *buf;
- left0 = 0xfff & *(__u16 *)buf;
- right0 = *(__u16 *)(buf + 1) >> 4;
-
-**Bit-packed representation.**
-pixels cross the byte boundary and have a ratio of 3 bytes for each
-interleaved pixel.
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 2 1 1
-
-
- - .. row 1
-
- - Y'\ :sub:`0left[7:0]`
-
- - Y'\ :sub:`0right[3:0]`\ Y'\ :sub:`0left[11:8]`
-
- - Y'\ :sub:`0right[11:4]`
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _V4L2-PIX-FMT-Y16-BE:
-
-****************************************
-V4L2_PIX_FMT_Y16_BE ('Y16 ' | (1 << 31))
-****************************************
-
-*man V4L2_PIX_FMT_Y16_BE(2)*
-
-Grey-scale image
-
-
-Description
-===========
-
-This is a grey-scale image with a depth of 16 bits per pixel. The most
-significant byte is stored at lower memory addresses (big-endian). Note
-the actual sampling precision may be lower than 16 bits, for example 10
-bits per pixel with values in range 0 to 1023.
-
-**Byte Order.**
-Each cell is one byte.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 2 1 1 1 1 1 1 1 1
-
-
- - .. row 1
-
- - start + 0:
-
- - Y'\ :sub:`00high`
-
- - Y'\ :sub:`00low`
-
- - Y'\ :sub:`01high`
-
- - Y'\ :sub:`01low`
-
- - Y'\ :sub:`02high`
-
- - Y'\ :sub:`02low`
-
- - Y'\ :sub:`03high`
-
- - Y'\ :sub:`03low`
-
- - .. row 2
-
- - start + 8:
-
- - Y'\ :sub:`10high`
-
- - Y'\ :sub:`10low`
-
- - Y'\ :sub:`11high`
-
- - Y'\ :sub:`11low`
-
- - Y'\ :sub:`12high`
-
- - Y'\ :sub:`12low`
-
- - Y'\ :sub:`13high`
-
- - Y'\ :sub:`13low`
-
- - .. row 3
-
- - start + 16:
-
- - Y'\ :sub:`20high`
-
- - Y'\ :sub:`20low`
-
- - Y'\ :sub:`21high`
-
- - Y'\ :sub:`21low`
-
- - Y'\ :sub:`22high`
-
- - Y'\ :sub:`22low`
-
- - Y'\ :sub:`23high`
-
- - Y'\ :sub:`23low`
-
- - .. row 4
-
- - start + 24:
-
- - Y'\ :sub:`30high`
-
- - Y'\ :sub:`30low`
-
- - Y'\ :sub:`31high`
-
- - Y'\ :sub:`31low`
-
- - Y'\ :sub:`32high`
-
- - Y'\ :sub:`32low`
-
- - Y'\ :sub:`33high`
-
- - Y'\ :sub:`33low`
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _V4L2-PIX-FMT-Y16:
-
-*************************
-V4L2_PIX_FMT_Y16 ('Y16 ')
-*************************
-
-*man V4L2_PIX_FMT_Y16(2)*
-
-Grey-scale image
-
-
-Description
-===========
-
-This is a grey-scale image with a depth of 16 bits per pixel. The least
-significant byte is stored at lower memory addresses (little-endian).
-Note the actual sampling precision may be lower than 16 bits, for
-example 10 bits per pixel with values in range 0 to 1023.
-
-**Byte Order.**
-Each cell is one byte.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 2 1 1 1 1 1 1 1 1
-
-
- - .. row 1
-
- - start + 0:
-
- - Y'\ :sub:`00low`
-
- - Y'\ :sub:`00high`
-
- - Y'\ :sub:`01low`
-
- - Y'\ :sub:`01high`
-
- - Y'\ :sub:`02low`
-
- - Y'\ :sub:`02high`
-
- - Y'\ :sub:`03low`
-
- - Y'\ :sub:`03high`
-
- - .. row 2
-
- - start + 8:
-
- - Y'\ :sub:`10low`
-
- - Y'\ :sub:`10high`
-
- - Y'\ :sub:`11low`
-
- - Y'\ :sub:`11high`
-
- - Y'\ :sub:`12low`
-
- - Y'\ :sub:`12high`
-
- - Y'\ :sub:`13low`
-
- - Y'\ :sub:`13high`
-
- - .. row 3
-
- - start + 16:
-
- - Y'\ :sub:`20low`
-
- - Y'\ :sub:`20high`
-
- - Y'\ :sub:`21low`
-
- - Y'\ :sub:`21high`
-
- - Y'\ :sub:`22low`
-
- - Y'\ :sub:`22high`
-
- - Y'\ :sub:`23low`
-
- - Y'\ :sub:`23high`
-
- - .. row 4
-
- - start + 24:
-
- - Y'\ :sub:`30low`
-
- - Y'\ :sub:`30high`
-
- - Y'\ :sub:`31low`
-
- - Y'\ :sub:`31high`
-
- - Y'\ :sub:`32low`
-
- - Y'\ :sub:`32high`
-
- - Y'\ :sub:`33low`
-
- - Y'\ :sub:`33high`
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _V4L2-PIX-FMT-Y41P:
-
-**************************
-V4L2_PIX_FMT_Y41P ('Y41P')
-**************************
-
-*man V4L2_PIX_FMT_Y41P(2)*
-
-Format with ¼ horizontal chroma resolution, also known as YUV 4:1:1
-
-
-Description
-===========
-
-In this format each 12 bytes is eight pixels. In the twelve bytes are
-two CbCr pairs and eight Y's. The first CbCr pair goes with the first
-four Y's, and the second CbCr pair goes with the other four Y's. The Cb
-and Cr components have one fourth the horizontal resolution of the Y
-component.
-
-Do not confuse this format with
-:ref:`V4L2_PIX_FMT_YUV411P <V4L2-PIX-FMT-YUV411P>`. Y41P is derived
-from "YUV 4:1:1 *packed*", while YUV411P stands for "YUV 4:1:1
-*planar*".
-
-**Byte Order.**
-Each cell is one byte.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 2 1 1 1 1 1 1 1 1 1 1 1 1
-
-
- - .. row 1
-
- - start + 0:
-
- - Cb\ :sub:`00`
-
- - Y'\ :sub:`00`
-
- - Cr\ :sub:`00`
-
- - Y'\ :sub:`01`
-
- - Cb\ :sub:`01`
-
- - Y'\ :sub:`02`
-
- - Cr\ :sub:`01`
-
- - Y'\ :sub:`03`
-
- - Y'\ :sub:`04`
-
- - Y'\ :sub:`05`
-
- - Y'\ :sub:`06`
-
- - Y'\ :sub:`07`
-
- - .. row 2
-
- - start + 12:
-
- - Cb\ :sub:`10`
-
- - Y'\ :sub:`10`
-
- - Cr\ :sub:`10`
-
- - Y'\ :sub:`11`
-
- - Cb\ :sub:`11`
-
- - Y'\ :sub:`12`
-
- - Cr\ :sub:`11`
-
- - Y'\ :sub:`13`
-
- - Y'\ :sub:`14`
-
- - Y'\ :sub:`15`
-
- - Y'\ :sub:`16`
-
- - Y'\ :sub:`17`
-
- - .. row 3
-
- - start + 24:
-
- - Cb\ :sub:`20`
-
- - Y'\ :sub:`20`
-
- - Cr\ :sub:`20`
-
- - Y'\ :sub:`21`
-
- - Cb\ :sub:`21`
-
- - Y'\ :sub:`22`
-
- - Cr\ :sub:`21`
-
- - Y'\ :sub:`23`
-
- - Y'\ :sub:`24`
-
- - Y'\ :sub:`25`
-
- - Y'\ :sub:`26`
-
- - Y'\ :sub:`27`
-
- - .. row 4
-
- - start + 36:
-
- - Cb\ :sub:`30`
-
- - Y'\ :sub:`30`
-
- - Cr\ :sub:`30`
-
- - Y'\ :sub:`31`
-
- - Cb\ :sub:`31`
-
- - Y'\ :sub:`32`
-
- - Cr\ :sub:`31`
-
- - Y'\ :sub:`33`
-
- - Y'\ :sub:`34`
-
- - Y'\ :sub:`35`
-
- - Y'\ :sub:`36`
-
- - Y'\ :sub:`37`
-
-
-**Color Sample Location..**
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- -
- - 0
-
- - 1
-
- -
- - 2
-
- - 3
-
- - 4
-
- - 5
-
- -
- - 6
-
- - 7
-
- - .. row 2
-
- - 0
-
- - Y
-
- - Y
-
- - C
-
- - Y
-
- - Y
-
- - Y
-
- - Y
-
- - C
-
- - Y
-
- - Y
-
- - .. row 3
-
- - 1
-
- - Y
-
- - Y
-
- - C
-
- - Y
-
- - Y
-
- - Y
-
- - Y
-
- - C
-
- - Y
-
- - Y
-
- - .. row 4
-
- - 2
-
- - Y
-
- - Y
-
- - C
-
- - Y
-
- - Y
-
- - Y
-
- - Y
-
- - C
-
- - Y
-
- - Y
-
- - .. row 5
-
- - 3
-
- - Y
-
- - Y
-
- - C
-
- - Y
-
- - Y
-
- - Y
-
- - Y
-
- - C
-
- - Y
-
- - Y
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _V4L2-PIX-FMT-Y8I:
-
-*************************
-V4L2_PIX_FMT_Y8I ('Y8I ')
-*************************
-
-*man V4L2_PIX_FMT_Y8I(2)*
-
-Interleaved grey-scale image, e.g. from a stereo-pair
-
-
-Description
-===========
-
-This is a grey-scale image with a depth of 8 bits per pixel, but with
-pixels from 2 sources interleaved. Each pixel is stored in a 16-bit
-word. E.g. the R200 RealSense camera stores pixel from the left sensor
-in lower and from the right sensor in the higher 8 bits.
-
-**Byte Order.**
-Each cell is one byte.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 2 1 1 1 1 1 1 1 1
-
-
- - .. row 1
-
- - start + 0:
-
- - Y'\ :sub:`00left`
-
- - Y'\ :sub:`00right`
-
- - Y'\ :sub:`01left`
-
- - Y'\ :sub:`01right`
-
- - Y'\ :sub:`02left`
-
- - Y'\ :sub:`02right`
-
- - Y'\ :sub:`03left`
-
- - Y'\ :sub:`03right`
-
- - .. row 2
-
- - start + 8:
-
- - Y'\ :sub:`10left`
-
- - Y'\ :sub:`10right`
-
- - Y'\ :sub:`11left`
-
- - Y'\ :sub:`11right`
-
- - Y'\ :sub:`12left`
-
- - Y'\ :sub:`12right`
-
- - Y'\ :sub:`13left`
-
- - Y'\ :sub:`13right`
-
- - .. row 3
-
- - start + 16:
-
- - Y'\ :sub:`20left`
-
- - Y'\ :sub:`20right`
-
- - Y'\ :sub:`21left`
-
- - Y'\ :sub:`21right`
-
- - Y'\ :sub:`22left`
-
- - Y'\ :sub:`22right`
-
- - Y'\ :sub:`23left`
-
- - Y'\ :sub:`23right`
-
- - .. row 4
-
- - start + 24:
-
- - Y'\ :sub:`30left`
-
- - Y'\ :sub:`30right`
-
- - Y'\ :sub:`31left`
-
- - Y'\ :sub:`31right`
-
- - Y'\ :sub:`32left`
-
- - Y'\ :sub:`32right`
-
- - Y'\ :sub:`33left`
-
- - Y'\ :sub:`33right`
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _V4L2-PIX-FMT-YVU410:
-.. _v4l2-pix-fmt-yuv410:
-
-**********************************************************
-V4L2_PIX_FMT_YVU410 ('YVU9'), V4L2_PIX_FMT_YUV410 ('YUV9')
-**********************************************************
-
-*man V4L2_PIX_FMT_YVU410(2)*
-
-V4L2_PIX_FMT_YUV410
-Planar formats with ¼ horizontal and vertical chroma resolution, also
-known as YUV 4:1:0
-
-
-Description
-===========
-
-These are planar formats, as opposed to a packed format. The three
-components are separated into three sub-images or planes. The Y plane is
-first. The Y plane has one byte per pixel. For ``V4L2_PIX_FMT_YVU410``,
-the Cr plane immediately follows the Y plane in memory. The Cr plane is
-¼ the width and ¼ the height of the Y plane (and of the image). Each Cr
-belongs to 16 pixels, a four-by-four square of the image. Following the
-Cr plane is the Cb plane, just like the Cr plane.
-``V4L2_PIX_FMT_YUV410`` is the same, except the Cb plane comes first,
-then the Cr plane.
-
-If the Y plane has pad bytes after each row, then the Cr and Cb planes
-have ¼ as many pad bytes after their rows. In other words, four Cx rows
-(including padding) are exactly as long as one Y row (including
-padding).
-
-**Byte Order.**
-Each cell is one byte.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 2 1 1 1 1
-
-
- - .. row 1
-
- - start + 0:
-
- - Y'\ :sub:`00`
-
- - Y'\ :sub:`01`
-
- - Y'\ :sub:`02`
-
- - Y'\ :sub:`03`
-
- - .. row 2
-
- - start + 4:
-
- - Y'\ :sub:`10`
-
- - Y'\ :sub:`11`
-
- - Y'\ :sub:`12`
-
- - Y'\ :sub:`13`
-
- - .. row 3
-
- - start + 8:
-
- - Y'\ :sub:`20`
-
- - Y'\ :sub:`21`
-
- - Y'\ :sub:`22`
-
- - Y'\ :sub:`23`
-
- - .. row 4
-
- - start + 12:
-
- - Y'\ :sub:`30`
-
- - Y'\ :sub:`31`
-
- - Y'\ :sub:`32`
-
- - Y'\ :sub:`33`
-
- - .. row 5
-
- - start + 16:
-
- - Cr\ :sub:`00`
-
- - .. row 6
-
- - start + 17:
-
- - Cb\ :sub:`00`
-
-
-**Color Sample Location..**
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- -
- - 0
-
- -
- - 1
-
- -
- - 2
-
- -
- - 3
-
- - .. row 2
-
- - 0
-
- - Y
-
- -
- - Y
-
- -
- - Y
-
- -
- - Y
-
- - .. row 3
-
- -
-
- - .. row 4
-
- - 1
-
- - Y
-
- -
- - Y
-
- -
- - Y
-
- -
- - Y
-
- - .. row 5
-
- -
- -
- -
- -
- - C
-
- -
- -
- -
-
- - .. row 6
-
- - 2
-
- - Y
-
- -
- - Y
-
- -
- - Y
-
- -
- - Y
-
- - .. row 7
-
- -
-
- - .. row 8
-
- - 3
-
- - Y
-
- -
- - Y
-
- -
- - Y
-
- -
- - Y
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _V4L2-PIX-FMT-YUV411P:
-
-*****************************
-V4L2_PIX_FMT_YUV411P ('411P')
-*****************************
-
-*man V4L2_PIX_FMT_YUV411P(2)*
-
-Format with ¼ horizontal chroma resolution, also known as YUV 4:1:1.
-Planar layout as opposed to ``V4L2_PIX_FMT_Y41P``
-
-
-Description
-===========
-
-This format is not commonly used. This is a planar format similar to the
-4:2:2 planar format except with half as many chroma. The three
-components are separated into three sub-images or planes. The Y plane is
-first. The Y plane has one byte per pixel. The Cb plane immediately
-follows the Y plane in memory. The Cb plane is ¼ the width of the Y
-plane (and of the image). Each Cb belongs to 4 pixels all on the same
-row. For example, Cb\ :sub:`0` belongs to Y'\ :sub:`00`, Y'\ :sub:`01`,
-Y'\ :sub:`02` and Y'\ :sub:`03`. Following the Cb plane is the Cr plane,
-just like the Cb plane.
-
-If the Y plane has pad bytes after each row, then the Cr and Cb planes
-have ¼ as many pad bytes after their rows. In other words, four C x rows
-(including padding) is exactly as long as one Y row (including padding).
-
-**Byte Order.**
-Each cell is one byte.
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 2 1 1 1 1
-
-
- - .. row 1
-
- - start + 0:
-
- - Y'\ :sub:`00`
-
- - Y'\ :sub:`01`
-
- - Y'\ :sub:`02`
-
- - Y'\ :sub:`03`
-
- - .. row 2
-
- - start + 4:
-
- - Y'\ :sub:`10`
-
- - Y'\ :sub:`11`
-
- - Y'\ :sub:`12`
-
- - Y'\ :sub:`13`
-
- - .. row 3
-
- - start + 8:
-
- - Y'\ :sub:`20`
-
- - Y'\ :sub:`21`
-
- - Y'\ :sub:`22`
-
- - Y'\ :sub:`23`
-
- - .. row 4
-
- - start + 12:
-
- - Y'\ :sub:`30`
-
- - Y'\ :sub:`31`
-
- - Y'\ :sub:`32`
-
- - Y'\ :sub:`33`
-
- - .. row 5
-
- - start + 16:
-
- - Cb\ :sub:`00`
-
- - .. row 6
-
- - start + 17:
-
- - Cb\ :sub:`10`
-
- - .. row 7
-
- - start + 18:
-
- - Cb\ :sub:`20`
-
- - .. row 8
-
- - start + 19:
-
- - Cb\ :sub:`30`
-
- - .. row 9
-
- - start + 20:
-
- - Cr\ :sub:`00`
-
- - .. row 10
-
- - start + 21:
-
- - Cr\ :sub:`10`
-
- - .. row 11
-
- - start + 22:
-
- - Cr\ :sub:`20`
-
- - .. row 12
-
- - start + 23:
-
- - Cr\ :sub:`30`
-
-
-**Color Sample Location..**
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- -
- - 0
-
- - 1
-
- -
- - 2
-
- - 3
-
- - .. row 2
-
- - 0
-
- - Y
-
- - Y
-
- - C
-
- - Y
-
- - Y
-
- - .. row 3
-
- - 1
-
- - Y
-
- - Y
-
- - C
-
- - Y
-
- - Y
-
- - .. row 4
-
- - 2
-
- - Y
-
- - Y
-
- - C
-
- - Y
-
- - Y
-
- - .. row 5
-
- - 3
-
- - Y
-
- - Y
-
- - C
-
- - Y
-
- - Y
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _V4L2-PIX-FMT-YVU420:
-.. _V4L2-PIX-FMT-YUV420:
-
-**********************************************************
-V4L2_PIX_FMT_YVU420 ('YV12'), V4L2_PIX_FMT_YUV420 ('YU12')
-**********************************************************
-
-*man V4L2_PIX_FMT_YVU420(2)*
-
-V4L2_PIX_FMT_YUV420
-Planar formats with ½ horizontal and vertical chroma resolution, also
-known as YUV 4:2:0
-
-
-Description
-===========
-
-These are planar formats, as opposed to a packed format. The three
-components are separated into three sub- images or planes. The Y plane
-is first. The Y plane has one byte per pixel. For
-``V4L2_PIX_FMT_YVU420``, the Cr plane immediately follows the Y plane in
-memory. The Cr plane is half the width and half the height of the Y
-plane (and of the image). Each Cr belongs to four pixels, a two-by-two
-square of the image. For example, Cr\ :sub:`0` belongs to Y'\ :sub:`00`,
-Y'\ :sub:`01`, Y'\ :sub:`10`, and Y'\ :sub:`11`. Following the Cr plane
-is the Cb plane, just like the Cr plane. ``V4L2_PIX_FMT_YUV420`` is the
-same except the Cb plane comes first, then the Cr plane.
-
-If the Y plane has pad bytes after each row, then the Cr and Cb planes
-have half as many pad bytes after their rows. In other words, two Cx
-rows (including padding) is exactly as long as one Y row (including
-padding).
-
-**Byte Order.**
-Each cell is one byte.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 2 1 1 1 1
-
-
- - .. row 1
-
- - start + 0:
-
- - Y'\ :sub:`00`
-
- - Y'\ :sub:`01`
-
- - Y'\ :sub:`02`
-
- - Y'\ :sub:`03`
-
- - .. row 2
-
- - start + 4:
-
- - Y'\ :sub:`10`
-
- - Y'\ :sub:`11`
-
- - Y'\ :sub:`12`
-
- - Y'\ :sub:`13`
-
- - .. row 3
-
- - start + 8:
-
- - Y'\ :sub:`20`
-
- - Y'\ :sub:`21`
-
- - Y'\ :sub:`22`
-
- - Y'\ :sub:`23`
-
- - .. row 4
-
- - start + 12:
-
- - Y'\ :sub:`30`
-
- - Y'\ :sub:`31`
-
- - Y'\ :sub:`32`
-
- - Y'\ :sub:`33`
-
- - .. row 5
-
- - start + 16:
-
- - Cr\ :sub:`00`
-
- - Cr\ :sub:`01`
-
- - .. row 6
-
- - start + 18:
-
- - Cr\ :sub:`10`
-
- - Cr\ :sub:`11`
-
- - .. row 7
-
- - start + 20:
-
- - Cb\ :sub:`00`
-
- - Cb\ :sub:`01`
-
- - .. row 8
-
- - start + 22:
-
- - Cb\ :sub:`10`
-
- - Cb\ :sub:`11`
-
-
-**Color Sample Location..**
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- -
- - 0
-
- -
- - 1
-
- -
- - 2
-
- -
- - 3
-
- - .. row 2
-
- - 0
-
- - Y
-
- -
- - Y
-
- -
- - Y
-
- -
- - Y
-
- - .. row 3
-
- -
- -
- - C
-
- -
- -
- -
- - C
-
- -
-
- - .. row 4
-
- - 1
-
- - Y
-
- -
- - Y
-
- -
- - Y
-
- -
- - Y
-
- - .. row 5
-
- -
-
- - .. row 6
-
- - 2
-
- - Y
-
- -
- - Y
-
- -
- - Y
-
- -
- - Y
-
- - .. row 7
-
- -
- -
- - C
-
- -
- -
- -
- - C
-
- -
-
- - .. row 8
-
- - 3
-
- - Y
-
- -
- - Y
-
- -
- - Y
-
- -
- - Y
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _V4L2-PIX-FMT-YUV420M:
-.. _v4l2-pix-fmt-yvu420m:
-
-************************************************************
-V4L2_PIX_FMT_YUV420M ('YM12'), V4L2_PIX_FMT_YVU420M ('YM21')
-************************************************************
-
-*man V4L2_PIX_FMT_YUV420M(2)*
-
-V4L2_PIX_FMT_YVU420M
-Variation of ``V4L2_PIX_FMT_YUV420`` and ``V4L2_PIX_FMT_YVU420`` with
-planes non contiguous in memory.
-
-
-Description
-===========
-
-This is a multi-planar format, as opposed to a packed format. The three
-components are separated into three sub-images or planes.
-
-The Y plane is first. The Y plane has one byte per pixel. For
-``V4L2_PIX_FMT_YUV420M`` the Cb data constitutes the second plane which
-is half the width and half the height of the Y plane (and of the image).
-Each Cb belongs to four pixels, a two-by-two square of the image. For
-example, Cb\ :sub:`0` belongs to Y'\ :sub:`00`, Y'\ :sub:`01`,
-Y'\ :sub:`10`, and Y'\ :sub:`11`. The Cr data, just like the Cb plane,
-is in the third plane.
-
-``V4L2_PIX_FMT_YVU420M`` is the same except the Cr data is stored in the
-second plane and the Cb data in the third plane.
-
-If the Y plane has pad bytes after each row, then the Cb and Cr planes
-have half as many pad bytes after their rows. In other words, two Cx
-rows (including padding) is exactly as long as one Y row (including
-padding).
-
-``V4L2_PIX_FMT_YUV420M`` and ``V4L2_PIX_FMT_YVU420M`` are intended to be
-used only in drivers and applications that support the multi-planar API,
-described in :ref:`planar-apis`.
-
-**Byte Order.**
-Each cell is one byte.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 2 1 1 1 1
-
-
- - .. row 1
-
- - start0 + 0:
-
- - Y'\ :sub:`00`
-
- - Y'\ :sub:`01`
-
- - Y'\ :sub:`02`
-
- - Y'\ :sub:`03`
-
- - .. row 2
-
- - start0 + 4:
-
- - Y'\ :sub:`10`
-
- - Y'\ :sub:`11`
-
- - Y'\ :sub:`12`
-
- - Y'\ :sub:`13`
-
- - .. row 3
-
- - start0 + 8:
-
- - Y'\ :sub:`20`
-
- - Y'\ :sub:`21`
-
- - Y'\ :sub:`22`
-
- - Y'\ :sub:`23`
-
- - .. row 4
-
- - start0 + 12:
-
- - Y'\ :sub:`30`
-
- - Y'\ :sub:`31`
-
- - Y'\ :sub:`32`
-
- - Y'\ :sub:`33`
-
- - .. row 5
-
- -
-
- - .. row 6
-
- - start1 + 0:
-
- - Cb\ :sub:`00`
-
- - Cb\ :sub:`01`
-
- - .. row 7
-
- - start1 + 2:
-
- - Cb\ :sub:`10`
-
- - Cb\ :sub:`11`
-
- - .. row 8
-
- -
-
- - .. row 9
-
- - start2 + 0:
-
- - Cr\ :sub:`00`
-
- - Cr\ :sub:`01`
-
- - .. row 10
-
- - start2 + 2:
-
- - Cr\ :sub:`10`
-
- - Cr\ :sub:`11`
-
-
-**Color Sample Location..**
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- -
- - 0
-
- -
- - 1
-
- -
- - 2
-
- -
- - 3
-
- - .. row 2
-
- - 0
-
- - Y
-
- -
- - Y
-
- -
- - Y
-
- -
- - Y
-
- - .. row 3
-
- -
- -
- - C
-
- -
- -
- -
- - C
-
- -
-
- - .. row 4
-
- - 1
-
- - Y
-
- -
- - Y
-
- -
- - Y
-
- -
- - Y
-
- - .. row 5
-
- -
-
- - .. row 6
-
- - 2
-
- - Y
-
- -
- - Y
-
- -
- - Y
-
- -
- - Y
-
- - .. row 7
-
- -
- -
- - C
-
- -
- -
- -
- - C
-
- -
-
- - .. row 8
-
- - 3
-
- - Y
-
- -
- - Y
-
- -
- - Y
-
- -
- - Y
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _V4L2-PIX-FMT-YUV422M:
-.. _v4l2-pix-fmt-yvu422m:
-
-************************************************************
-V4L2_PIX_FMT_YUV422M ('YM16'), V4L2_PIX_FMT_YVU422M ('YM61')
-************************************************************
-
-*man V4L2_PIX_FMT_YUV422M(2)*
-
-V4L2_PIX_FMT_YVU422M
-Planar formats with ½ horizontal resolution, also known as YUV and YVU
-4:2:2
-
-
-Description
-===========
-
-This is a multi-planar format, as opposed to a packed format. The three
-components are separated into three sub-images or planes.
-
-The Y plane is first. The Y plane has one byte per pixel. For
-``V4L2_PIX_FMT_YUV422M`` the Cb data constitutes the second plane which
-is half the width of the Y plane (and of the image). Each Cb belongs to
-two pixels. For example, Cb\ :sub:`0` belongs to Y'\ :sub:`00`,
-Y'\ :sub:`01`. The Cr data, just like the Cb plane, is in the third
-plane.
-
-``V4L2_PIX_FMT_YVU422M`` is the same except the Cr data is stored in the
-second plane and the Cb data in the third plane.
-
-If the Y plane has pad bytes after each row, then the Cb and Cr planes
-have half as many pad bytes after their rows. In other words, two Cx
-rows (including padding) is exactly as long as one Y row (including
-padding).
-
-``V4L2_PIX_FMT_YUV422M`` and ``V4L2_PIX_FMT_YVU422M`` are intended to be
-used only in drivers and applications that support the multi-planar API,
-described in :ref:`planar-apis`.
-
-**Byte Order.**
-Each cell is one byte.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 2 1 1 1 1
-
-
- - .. row 1
-
- - start0 + 0:
-
- - Y'\ :sub:`00`
-
- - Y'\ :sub:`01`
-
- - Y'\ :sub:`02`
-
- - Y'\ :sub:`03`
-
- - .. row 2
-
- - start0 + 4:
-
- - Y'\ :sub:`10`
-
- - Y'\ :sub:`11`
-
- - Y'\ :sub:`12`
-
- - Y'\ :sub:`13`
-
- - .. row 3
-
- - start0 + 8:
-
- - Y'\ :sub:`20`
-
- - Y'\ :sub:`21`
-
- - Y'\ :sub:`22`
-
- - Y'\ :sub:`23`
-
- - .. row 4
-
- - start0 + 12:
-
- - Y'\ :sub:`30`
-
- - Y'\ :sub:`31`
-
- - Y'\ :sub:`32`
-
- - Y'\ :sub:`33`
-
- - .. row 5
-
- -
-
- - .. row 6
-
- - start1 + 0:
-
- - Cb\ :sub:`00`
-
- - Cb\ :sub:`01`
-
- - .. row 7
-
- - start1 + 2:
-
- - Cb\ :sub:`10`
-
- - Cb\ :sub:`11`
-
- - .. row 8
-
- - start1 + 4:
-
- - Cb\ :sub:`20`
-
- - Cb\ :sub:`21`
-
- - .. row 9
-
- - start1 + 6:
-
- - Cb\ :sub:`30`
-
- - Cb\ :sub:`31`
-
- - .. row 10
-
- -
-
- - .. row 11
-
- - start2 + 0:
-
- - Cr\ :sub:`00`
-
- - Cr\ :sub:`01`
-
- - .. row 12
-
- - start2 + 2:
-
- - Cr\ :sub:`10`
-
- - Cr\ :sub:`11`
-
- - .. row 13
-
- - start2 + 4:
-
- - Cr\ :sub:`20`
-
- - Cr\ :sub:`21`
-
- - .. row 14
-
- - start2 + 6:
-
- - Cr\ :sub:`30`
-
- - Cr\ :sub:`31`
-
-
-**Color Sample Location..**
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- -
- - 0
-
- -
- - 1
-
- - 2
-
- -
- - 3
-
- - .. row 2
-
- - 0
-
- - Y
-
- - C
-
- - Y
-
- - Y
-
- - C
-
- - Y
-
- - .. row 3
-
- - 1
-
- - Y
-
- - C
-
- - Y
-
- - Y
-
- - C
-
- - Y
-
- - .. row 4
-
- - 2
-
- - Y
-
- - C
-
- - Y
-
- - Y
-
- - C
-
- - Y
-
- - .. row 5
-
- - 3
-
- - Y
-
- - C
-
- - Y
-
- - Y
-
- - C
-
- - Y
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _V4L2-PIX-FMT-YUV422P:
-
-*****************************
-V4L2_PIX_FMT_YUV422P ('422P')
-*****************************
-
-*man V4L2_PIX_FMT_YUV422P(2)*
-
-Format with ½ horizontal chroma resolution, also known as YUV 4:2:2.
-Planar layout as opposed to ``V4L2_PIX_FMT_YUYV``
-
-
-Description
-===========
-
-This format is not commonly used. This is a planar version of the YUYV
-format. The three components are separated into three sub-images or
-planes. The Y plane is first. The Y plane has one byte per pixel. The Cb
-plane immediately follows the Y plane in memory. The Cb plane is half
-the width of the Y plane (and of the image). Each Cb belongs to two
-pixels. For example, Cb\ :sub:`0` belongs to Y'\ :sub:`00`,
-Y'\ :sub:`01`. Following the Cb plane is the Cr plane, just like the Cb
-plane.
-
-If the Y plane has pad bytes after each row, then the Cr and Cb planes
-have half as many pad bytes after their rows. In other words, two Cx
-rows (including padding) is exactly as long as one Y row (including
-padding).
-
-**Byte Order.**
-Each cell is one byte.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 2 1 1 1 1
-
-
- - .. row 1
-
- - start + 0:
-
- - Y'\ :sub:`00`
-
- - Y'\ :sub:`01`
-
- - Y'\ :sub:`02`
-
- - Y'\ :sub:`03`
-
- - .. row 2
-
- - start + 4:
-
- - Y'\ :sub:`10`
-
- - Y'\ :sub:`11`
-
- - Y'\ :sub:`12`
-
- - Y'\ :sub:`13`
-
- - .. row 3
-
- - start + 8:
-
- - Y'\ :sub:`20`
-
- - Y'\ :sub:`21`
-
- - Y'\ :sub:`22`
-
- - Y'\ :sub:`23`
-
- - .. row 4
-
- - start + 12:
-
- - Y'\ :sub:`30`
-
- - Y'\ :sub:`31`
-
- - Y'\ :sub:`32`
-
- - Y'\ :sub:`33`
-
- - .. row 5
-
- - start + 16:
-
- - Cb\ :sub:`00`
-
- - Cb\ :sub:`01`
-
- - .. row 6
-
- - start + 18:
-
- - Cb\ :sub:`10`
-
- - Cb\ :sub:`11`
-
- - .. row 7
-
- - start + 20:
-
- - Cb\ :sub:`20`
-
- - Cb\ :sub:`21`
-
- - .. row 8
-
- - start + 22:
-
- - Cb\ :sub:`30`
-
- - Cb\ :sub:`31`
-
- - .. row 9
-
- - start + 24:
-
- - Cr\ :sub:`00`
-
- - Cr\ :sub:`01`
-
- - .. row 10
-
- - start + 26:
-
- - Cr\ :sub:`10`
-
- - Cr\ :sub:`11`
-
- - .. row 11
-
- - start + 28:
-
- - Cr\ :sub:`20`
-
- - Cr\ :sub:`21`
-
- - .. row 12
-
- - start + 30:
-
- - Cr\ :sub:`30`
-
- - Cr\ :sub:`31`
-
-
-**Color Sample Location..**
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- -
- - 0
-
- -
- - 1
-
- - 2
-
- -
- - 3
-
- - .. row 2
-
- - 0
-
- - Y
-
- - C
-
- - Y
-
- - Y
-
- - C
-
- - Y
-
- - .. row 3
-
- - 1
-
- - Y
-
- - C
-
- - Y
-
- - Y
-
- - C
-
- - Y
-
- - .. row 4
-
- - 2
-
- - Y
-
- - C
-
- - Y
-
- - Y
-
- - C
-
- - Y
-
- - .. row 5
-
- - 3
-
- - Y
-
- - C
-
- - Y
-
- - Y
-
- - C
-
- - Y
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _V4L2-PIX-FMT-YUV444M:
-.. _v4l2-pix-fmt-yvu444m:
-
-************************************************************
-V4L2_PIX_FMT_YUV444M ('YM24'), V4L2_PIX_FMT_YVU444M ('YM42')
-************************************************************
-
-*man V4L2_PIX_FMT_YUV444M(2)*
-
-V4L2_PIX_FMT_YVU444M
-Planar formats with full horizontal resolution, also known as YUV and
-YVU 4:4:4
-
-
-Description
-===========
-
-This is a multi-planar format, as opposed to a packed format. The three
-components are separated into three sub-images or planes.
-
-The Y plane is first. The Y plane has one byte per pixel. For
-``V4L2_PIX_FMT_YUV444M`` the Cb data constitutes the second plane which
-is the same width and height as the Y plane (and as the image). The Cr
-data, just like the Cb plane, is in the third plane.
-
-``V4L2_PIX_FMT_YVU444M`` is the same except the Cr data is stored in the
-second plane and the Cb data in the third plane.
-
-If the Y plane has pad bytes after each row, then the Cb and Cr planes
-have the same number of pad bytes after their rows.
-
-``V4L2_PIX_FMT_YUV444M`` and ``V4L2_PIX_FMT_YUV444M`` are intended to be
-used only in drivers and applications that support the multi-planar API,
-described in :ref:`planar-apis`.
-
-**Byte Order.**
-Each cell is one byte.
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 2 1 1 1 1
-
-
- - .. row 1
-
- - start0 + 0:
-
- - Y'\ :sub:`00`
-
- - Y'\ :sub:`01`
-
- - Y'\ :sub:`02`
-
- - Y'\ :sub:`03`
-
- - .. row 2
-
- - start0 + 4:
-
- - Y'\ :sub:`10`
-
- - Y'\ :sub:`11`
-
- - Y'\ :sub:`12`
-
- - Y'\ :sub:`13`
-
- - .. row 3
-
- - start0 + 8:
-
- - Y'\ :sub:`20`
-
- - Y'\ :sub:`21`
-
- - Y'\ :sub:`22`
-
- - Y'\ :sub:`23`
-
- - .. row 4
-
- - start0 + 12:
-
- - Y'\ :sub:`30`
-
- - Y'\ :sub:`31`
-
- - Y'\ :sub:`32`
-
- - Y'\ :sub:`33`
-
- - .. row 5
-
- -
-
- - .. row 6
-
- - start1 + 0:
-
- - Cb\ :sub:`00`
-
- - Cb\ :sub:`01`
-
- - Cb\ :sub:`02`
-
- - Cb\ :sub:`03`
-
- - .. row 7
-
- - start1 + 4:
-
- - Cb\ :sub:`10`
-
- - Cb\ :sub:`11`
-
- - Cb\ :sub:`12`
-
- - Cb\ :sub:`13`
-
- - .. row 8
-
- - start1 + 8:
-
- - Cb\ :sub:`20`
-
- - Cb\ :sub:`21`
-
- - Cb\ :sub:`22`
-
- - Cb\ :sub:`23`
-
- - .. row 9
-
- - start1 + 12:
-
- - Cb\ :sub:`20`
-
- - Cb\ :sub:`21`
-
- - Cb\ :sub:`32`
-
- - Cb\ :sub:`33`
-
- - .. row 10
-
- -
-
- - .. row 11
-
- - start2 + 0:
-
- - Cr\ :sub:`00`
-
- - Cr\ :sub:`01`
-
- - Cr\ :sub:`02`
-
- - Cr\ :sub:`03`
-
- - .. row 12
-
- - start2 + 4:
-
- - Cr\ :sub:`10`
-
- - Cr\ :sub:`11`
-
- - Cr\ :sub:`12`
-
- - Cr\ :sub:`13`
-
- - .. row 13
-
- - start2 + 8:
-
- - Cr\ :sub:`20`
-
- - Cr\ :sub:`21`
-
- - Cr\ :sub:`22`
-
- - Cr\ :sub:`23`
-
- - .. row 14
-
- - start2 + 12:
-
- - Cr\ :sub:`30`
-
- - Cr\ :sub:`31`
-
- - Cr\ :sub:`32`
-
- - Cr\ :sub:`33`
-
-
-**Color Sample Location..**
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- -
- - 0
-
- - 1
-
- - 2
-
- - 3
-
- - .. row 2
-
- - 0
-
- - YC
-
- - YC
-
- - YC
-
- - YC
-
- - .. row 3
-
- - 1
-
- - YC
-
- - YC
-
- - YC
-
- - YC
-
- - .. row 4
-
- - 2
-
- - YC
-
- - YC
-
- - YC
-
- - YC
-
- - .. row 5
-
- - 3
-
- - YC
-
- - YC
-
- - YC
-
- - YC
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _V4L2-PIX-FMT-YUYV:
-
-**************************
-V4L2_PIX_FMT_YUYV ('YUYV')
-**************************
-
-*man V4L2_PIX_FMT_YUYV(2)*
-
-Packed format with ½ horizontal chroma resolution, also known as YUV
-4:2:2
-
-
-Description
-===========
-
-In this format each four bytes is two pixels. Each four bytes is two
-Y's, a Cb and a Cr. Each Y goes to one of the pixels, and the Cb and Cr
-belong to both pixels. As you can see, the Cr and Cb components have
-half the horizontal resolution of the Y component. ``V4L2_PIX_FMT_YUYV``
-is known in the Windows environment as YUY2.
-
-**Byte Order.**
-Each cell is one byte.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 2 1 1 1 1 1 1 1 1
-
-
- - .. row 1
-
- - start + 0:
-
- - Y'\ :sub:`00`
-
- - Cb\ :sub:`00`
-
- - Y'\ :sub:`01`
-
- - Cr\ :sub:`00`
-
- - Y'\ :sub:`02`
-
- - Cb\ :sub:`01`
-
- - Y'\ :sub:`03`
-
- - Cr\ :sub:`01`
-
- - .. row 2
-
- - start + 8:
-
- - Y'\ :sub:`10`
-
- - Cb\ :sub:`10`
-
- - Y'\ :sub:`11`
-
- - Cr\ :sub:`10`
-
- - Y'\ :sub:`12`
-
- - Cb\ :sub:`11`
-
- - Y'\ :sub:`13`
-
- - Cr\ :sub:`11`
-
- - .. row 3
-
- - start + 16:
-
- - Y'\ :sub:`20`
-
- - Cb\ :sub:`20`
-
- - Y'\ :sub:`21`
-
- - Cr\ :sub:`20`
-
- - Y'\ :sub:`22`
-
- - Cb\ :sub:`21`
-
- - Y'\ :sub:`23`
-
- - Cr\ :sub:`21`
-
- - .. row 4
-
- - start + 24:
-
- - Y'\ :sub:`30`
-
- - Cb\ :sub:`30`
-
- - Y'\ :sub:`31`
-
- - Cr\ :sub:`30`
-
- - Y'\ :sub:`32`
-
- - Cb\ :sub:`31`
-
- - Y'\ :sub:`33`
-
- - Cr\ :sub:`31`
-
-
-**Color Sample Location..**
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- -
- - 0
-
- -
- - 1
-
- -
- - 2
-
- -
- - 3
-
- - .. row 2
-
- - 0
-
- - Y
-
- - C
-
- - Y
-
- -
- - Y
-
- - C
-
- - Y
-
- - .. row 3
-
- - 1
-
- - Y
-
- - C
-
- - Y
-
- -
- - Y
-
- - C
-
- - Y
-
- - .. row 4
-
- - 2
-
- - Y
-
- - C
-
- - Y
-
- -
- - Y
-
- - C
-
- - Y
-
- - .. row 5
-
- - 3
-
- - Y
-
- - C
-
- - Y
-
- -
- - Y
-
- - C
-
- - Y
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _V4L2-PIX-FMT-YVYU:
-
-**************************
-V4L2_PIX_FMT_YVYU ('YVYU')
-**************************
-
-*man V4L2_PIX_FMT_YVYU(2)*
-
-Variation of ``V4L2_PIX_FMT_YUYV`` with different order of samples in
-memory
-
-
-Description
-===========
-
-In this format each four bytes is two pixels. Each four bytes is two
-Y's, a Cb and a Cr. Each Y goes to one of the pixels, and the Cb and Cr
-belong to both pixels. As you can see, the Cr and Cb components have
-half the horizontal resolution of the Y component.
-
-**Byte Order.**
-Each cell is one byte.
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 2 1 1 1 1 1 1 1 1
-
-
- - .. row 1
-
- - start + 0:
-
- - Y'\ :sub:`00`
-
- - Cr\ :sub:`00`
-
- - Y'\ :sub:`01`
-
- - Cb\ :sub:`00`
-
- - Y'\ :sub:`02`
-
- - Cr\ :sub:`01`
-
- - Y'\ :sub:`03`
-
- - Cb\ :sub:`01`
-
- - .. row 2
-
- - start + 8:
-
- - Y'\ :sub:`10`
-
- - Cr\ :sub:`10`
-
- - Y'\ :sub:`11`
-
- - Cb\ :sub:`10`
-
- - Y'\ :sub:`12`
-
- - Cr\ :sub:`11`
-
- - Y'\ :sub:`13`
-
- - Cb\ :sub:`11`
-
- - .. row 3
-
- - start + 16:
-
- - Y'\ :sub:`20`
-
- - Cr\ :sub:`20`
-
- - Y'\ :sub:`21`
-
- - Cb\ :sub:`20`
-
- - Y'\ :sub:`22`
-
- - Cr\ :sub:`21`
-
- - Y'\ :sub:`23`
-
- - Cb\ :sub:`21`
-
- - .. row 4
-
- - start + 24:
-
- - Y'\ :sub:`30`
-
- - Cr\ :sub:`30`
-
- - Y'\ :sub:`31`
-
- - Cb\ :sub:`30`
-
- - Y'\ :sub:`32`
-
- - Cr\ :sub:`31`
-
- - Y'\ :sub:`33`
-
- - Cb\ :sub:`31`
-
-
-**Color Sample Location..**
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- -
- - 0
-
- -
- - 1
-
- - 2
-
- -
- - 3
-
- - .. row 2
-
- - 0
-
- - Y
-
- - C
-
- - Y
-
- - Y
-
- - C
-
- - Y
-
- - .. row 3
-
- - 1
-
- - Y
-
- - C
-
- - Y
-
- - Y
-
- - C
-
- - Y
-
- - .. row 4
-
- - 2
-
- - Y
-
- - C
-
- - Y
-
- - Y
-
- - C
-
- - Y
-
- - .. row 5
-
- - 3
-
- - Y
-
- - C
-
- - Y
-
- - Y
-
- - C
-
- - Y
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _V4L2-PIX-FMT-Z16:
-
-*************************
-V4L2_PIX_FMT_Z16 ('Z16 ')
-*************************
-
-*man V4L2_PIX_FMT_Z16(2)*
-
-Interleaved grey-scale image, e.g. from a stereo-pair
-
-
-Description
-===========
-
-This is a 16-bit format, representing depth data. Each pixel is a
-distance to the respective point in the image coordinates. Distance unit
-can vary and has to be negotiated with the device separately. Each pixel
-is stored in a 16-bit word in the little endian byte order.
-
-**Byte Order.**
-Each cell is one byte.
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 2 1 1 1 1 1 1 1 1
-
-
- - .. row 1
-
- - start + 0:
-
- - Z\ :sub:`00low`
-
- - Z\ :sub:`00high`
-
- - Z\ :sub:`01low`
-
- - Z\ :sub:`01high`
-
- - Z\ :sub:`02low`
-
- - Z\ :sub:`02high`
-
- - Z\ :sub:`03low`
-
- - Z\ :sub:`03high`
-
- - .. row 2
-
- - start + 8:
-
- - Z\ :sub:`10low`
-
- - Z\ :sub:`10high`
-
- - Z\ :sub:`11low`
-
- - Z\ :sub:`11high`
-
- - Z\ :sub:`12low`
-
- - Z\ :sub:`12high`
-
- - Z\ :sub:`13low`
-
- - Z\ :sub:`13high`
-
- - .. row 3
-
- - start + 16:
-
- - Z\ :sub:`20low`
-
- - Z\ :sub:`20high`
-
- - Z\ :sub:`21low`
-
- - Z\ :sub:`21high`
-
- - Z\ :sub:`22low`
-
- - Z\ :sub:`22high`
-
- - Z\ :sub:`23low`
-
- - Z\ :sub:`23high`
-
- - .. row 4
-
- - start + 24:
-
- - Z\ :sub:`30low`
-
- - Z\ :sub:`30high`
-
- - Z\ :sub:`31low`
-
- - Z\ :sub:`31high`
-
- - Z\ :sub:`32low`
-
- - Z\ :sub:`32high`
-
- - Z\ :sub:`33low`
-
- - Z\ :sub:`33high`
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _pixfmt:
-
-#############
-Image Formats
-#############
-The V4L2 API was primarily designed for devices exchanging image data
-with applications. The :ref:`struct v4l2_pix_format <v4l2-pix-format>` and
-:ref:`struct v4l2_pix_format_mplane <v4l2-pix-format-mplane>` structures define the
-format and layout of an image in memory. The former is used with the
-single-planar API, while the latter is used with the multi-planar
-version (see :ref:`planar-apis`). Image formats are negotiated with
-the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. (The explanations here
-focus on video capturing and output, for overlay frame buffer formats
-see also :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`.)
-
-
-.. toctree::
- :maxdepth: 1
-
- pixfmt-002
- pixfmt-003
- pixfmt-004
- colorspaces
- pixfmt-006
- pixfmt-007
- pixfmt-008
- pixfmt-indexed
- pixfmt-rgb
- yuv-formats
- depth-formats
- pixfmt-013
- sdr-formats
- pixfmt-reserved
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _planar-apis:
-
-*****************************
-Single- and multi-planar APIs
-*****************************
-
-Some devices require data for each input or output video frame to be
-placed in discontiguous memory buffers. In such cases, one video frame
-has to be addressed using more than one memory address, i.e. one pointer
-per "plane". A plane is a sub-buffer of the current frame. For examples
-of such formats see :ref:`pixfmt`.
-
-Initially, V4L2 API did not support multi-planar buffers and a set of
-extensions has been introduced to handle them. Those extensions
-constitute what is being referred to as the "multi-planar API".
-
-Some of the V4L2 API calls and structures are interpreted differently,
-depending on whether single- or multi-planar API is being used. An
-application can choose whether to use one or the other by passing a
-corresponding buffer type to its ioctl calls. Multi-planar versions of
-buffer types are suffixed with an ``_MPLANE`` string. For a list of
-available multi-planar buffer types see enum
-:ref:`v4l2_buf_type <v4l2-buf-type>`.
-
-
-Multi-planar formats
-====================
-
-Multi-planar API introduces new multi-planar formats. Those formats use
-a separate set of FourCC codes. It is important to distinguish between
-the multi-planar API and a multi-planar format. Multi-planar API calls
-can handle all single-planar formats as well (as long as they are passed
-in multi-planar API structures), while the single-planar API cannot
-handle multi-planar formats.
-
-
-Calls that distinguish between single and multi-planar APIs
-===========================================================
-
-:ref:`VIDIOC_QUERYCAP <VIDIOC_QUERYCAP>`
- Two additional multi-planar capabilities are added. They can be set
- together with non-multi-planar ones for devices that handle both
- single- and multi-planar formats.
-
-:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>`
- New structures for describing multi-planar formats are added: struct
- :ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` and
- struct :ref:`v4l2_plane_pix_format <v4l2-plane-pix-format>`.
- Drivers may define new multi-planar formats, which have distinct
- FourCC codes from the existing single-planar ones.
-
-:ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_QUERYBUF <VIDIOC_QUERYBUF>`
- A new struct :ref:`v4l2_plane <v4l2-plane>` structure for
- describing planes is added. Arrays of this structure are passed in
- the new ``m.planes`` field of struct
- :ref:`v4l2_buffer <v4l2-buffer>`.
-
-:ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`
- Will allocate multi-planar buffers as requested.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _querycap:
-
-*********************
-Querying Capabilities
-*********************
-
-Because V4L2 covers a wide variety of devices not all aspects of the API
-are equally applicable to all types of devices. Furthermore devices of
-the same type have different capabilities and this specification permits
-the omission of a few complicated and less important parts of the API.
-
-The :ref:`VIDIOC_QUERYCAP` ioctl is available to
-check if the kernel device is compatible with this specification, and to
-query the :ref:`functions <devices>` and :ref:`I/O methods <io>`
-supported by the device.
-
-Starting with kernel version 3.1, :ref:`VIDIOC_QUERYCAP`
-will return the V4L2 API version used by the driver, with generally
-matches the Kernel version. There's no need of using
-:ref:`VIDIOC_QUERYCAP` to check if a specific ioctl
-is supported, the V4L2 core now returns ``ENOTTY`` if a driver doesn't
-provide support for an ioctl.
-
-Other features can be queried by calling the respective ioctl, for
-example :ref:`VIDIOC_ENUMINPUT` to learn about the
-number, types and names of video connectors on the device. Although
-abstraction is a major objective of this API, the
-:ref:`VIDIOC_QUERYCAP` ioctl also allows driver
-specific applications to reliably identify the driver.
-
-All V4L2 drivers must support :ref:`VIDIOC_QUERYCAP`.
-Applications should always call this ioctl after opening the device.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _rw:
-
-**********
-Read/Write
-**********
-
-Input and output devices support the :ref:`read() <func-read>` and
-:ref:`write() <func-write>` function, respectively, when the
-``V4L2_CAP_READWRITE`` flag in the ``capabilities`` field of struct
-:ref:`v4l2_capability <v4l2-capability>` returned by the
-:ref:`VIDIOC_QUERYCAP` ioctl is set.
-
-Drivers may need the CPU to copy the data, but they may also support DMA
-to or from user memory, so this I/O method is not necessarily less
-efficient than other methods merely exchanging buffer pointers. It is
-considered inferior though because no meta-information like frame
-counters or timestamps are passed. This information is necessary to
-recognize frame dropping and to synchronize with other data streams.
-However this is also the simplest I/O method, requiring little or no
-setup to exchange data. It permits command line stunts like this (the
-vidctrl tool is fictitious):
-
-
-.. code-block:: none
-
- $ vidctrl /dev/video --input=0 --format=YUYV --size=352x288
- $ dd if=/dev/video of=myimage.422 bs=202752 count=1
-
-To read from the device applications use the :ref:`read() <func-read>`
-function, to write the :ref:`write() <func-write>` function. Drivers
-must implement one I/O method if they exchange data with applications,
-but it need not be this. [1]_ When reading or writing is supported, the
-driver must also support the :ref:`select() <func-select>` and
-:ref:`poll() <func-poll>` function. [2]_
-
-.. [1]
- It would be desirable if applications could depend on drivers
- supporting all I/O interfaces, but as much as the complex memory
- mapping I/O can be inadequate for some devices we have no reason to
- require this interface, which is most useful for simple applications
- capturing still images.
-
-.. [2]
- At the driver level :ref:`select() <func-select>` and :ref:`poll() <func-poll>` are
- the same, and :ref:`select() <func-select>` is too important to be optional.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _sdr-formats:
-
-***********
-SDR Formats
-***********
-
-These formats are used for :ref:`SDR <sdr>` interface only.
-
-
-.. toctree::
- :maxdepth: 1
-
- pixfmt-sdr-cu08
- pixfmt-sdr-cu16le
- pixfmt-sdr-cs08
- pixfmt-sdr-cs14le
- pixfmt-sdr-ru12le
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-************
-Introduction
-************
-
-Some video capture devices can sample a subsection of a picture and
-shrink or enlarge it to an image of arbitrary size. Next, the devices
-can insert the image into larger one. Some video output devices can crop
-part of an input image, scale it up or down and insert it at an
-arbitrary scan line and horizontal offset into a video signal. We call
-these abilities cropping, scaling and composing.
-
-On a video *capture* device the source is a video signal, and the
-cropping target determine the area actually sampled. The sink is an
-image stored in a memory buffer. The composing area specifies which part
-of the buffer is actually written to by the hardware.
-
-On a video *output* device the source is an image in a memory buffer,
-and the cropping target is a part of an image to be shown on a display.
-The sink is the display or the graphics screen. The application may
-select the part of display where the image should be displayed. The size
-and position of such a window is controlled by the compose target.
-
-Rectangles for all cropping and composing targets are defined even if
-the device does supports neither cropping nor composing. Their size and
-position will be fixed in such a case. If the device does not support
-scaling then the cropping and composing rectangles have the same size.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-*****************
-Selection targets
-*****************
-
-
-.. _sel-targets-capture:
-
-.. figure:: selection-api-003_files/selection.*
- :alt: selection.png
- :align: center
-
- Cropping and composing targets
-
- Targets used by a cropping, composing and scaling process
-
-
-
-See :ref:`v4l2-selection-targets` for more information.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-*************
-Configuration
-*************
-
-Applications can use the :ref:`selection API <VIDIOC_G_SELECTION>` to
-select an area in a video signal or a buffer, and to query for default
-settings and hardware limits.
-
-Video hardware can have various cropping, composing and scaling
-limitations. It may only scale up or down, support only discrete scaling
-factors, or have different scaling abilities in the horizontal and
-vertical directions. Also it may not support scaling at all. At the same
-time the cropping/composing rectangles may have to be aligned, and both
-the source and the sink may have arbitrary upper and lower size limits.
-Therefore, as usual, drivers are expected to adjust the requested
-parameters and return the actual values selected. An application can
-control the rounding behaviour using
-:ref:`constraint flags <v4l2-selection-flags>`.
-
-
-Configuration of video capture
-==============================
-
-See figure :ref:`sel-targets-capture` for examples of the selection
-targets available for a video capture device. It is recommended to
-configure the cropping targets before to the composing targets.
-
-The range of coordinates of the top left corner, width and height of
-areas that can be sampled is given by the ``V4L2_SEL_TGT_CROP_BOUNDS``
-target. It is recommended for the driver developers to put the top/left
-corner at position ``(0,0)``. The rectangle's coordinates are expressed
-in pixels.
-
-The top left corner, width and height of the source rectangle, that is
-the area actually sampled, is given by the ``V4L2_SEL_TGT_CROP`` target.
-It uses the same coordinate system as ``V4L2_SEL_TGT_CROP_BOUNDS``. The
-active cropping area must lie completely inside the capture boundaries.
-The driver may further adjust the requested size and/or position
-according to hardware limitations.
-
-Each capture device has a default source rectangle, given by the
-``V4L2_SEL_TGT_CROP_DEFAULT`` target. This rectangle shall over what the
-driver writer considers the complete picture. Drivers shall set the
-active crop rectangle to the default when the driver is first loaded,
-but not later.
-
-The composing targets refer to a memory buffer. The limits of composing
-coordinates are obtained using ``V4L2_SEL_TGT_COMPOSE_BOUNDS``. All
-coordinates are expressed in pixels. The rectangle's top/left corner
-must be located at position ``(0,0)``. The width and height are equal to
-the image size set by :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`.
-
-The part of a buffer into which the image is inserted by the hardware is
-controlled by the ``V4L2_SEL_TGT_COMPOSE`` target. The rectangle's
-coordinates are also expressed in the same coordinate system as the
-bounds rectangle. The composing rectangle must lie completely inside
-bounds rectangle. The driver must adjust the composing rectangle to fit
-to the bounding limits. Moreover, the driver can perform other
-adjustments according to hardware limitations. The application can
-control rounding behaviour using
-:ref:`constraint flags <v4l2-selection-flags>`.
-
-For capture devices the default composing rectangle is queried using
-``V4L2_SEL_TGT_COMPOSE_DEFAULT``. It is usually equal to the bounding
-rectangle.
-
-The part of a buffer that is modified by the hardware is given by
-``V4L2_SEL_TGT_COMPOSE_PADDED``. It contains all pixels defined using
-``V4L2_SEL_TGT_COMPOSE`` plus all padding data modified by hardware
-during insertion process. All pixels outside this rectangle *must not*
-be changed by the hardware. The content of pixels that lie inside the
-padded area but outside active area is undefined. The application can
-use the padded and active rectangles to detect where the rubbish pixels
-are located and remove them if needed.
-
-
-Configuration of video output
-=============================
-
-For output devices targets and ioctls are used similarly to the video
-capture case. The *composing* rectangle refers to the insertion of an
-image into a video signal. The cropping rectangles refer to a memory
-buffer. It is recommended to configure the composing targets before to
-the cropping targets.
-
-The cropping targets refer to the memory buffer that contains an image
-to be inserted into a video signal or graphical screen. The limits of
-cropping coordinates are obtained using ``V4L2_SEL_TGT_CROP_BOUNDS``.
-All coordinates are expressed in pixels. The top/left corner is always
-point ``(0,0)``. The width and height is equal to the image size
-specified using :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
-
-The top left corner, width and height of the source rectangle, that is
-the area from which image date are processed by the hardware, is given
-by the ``V4L2_SEL_TGT_CROP``. Its coordinates are expressed in in the
-same coordinate system as the bounds rectangle. The active cropping area
-must lie completely inside the crop boundaries and the driver may
-further adjust the requested size and/or position according to hardware
-limitations.
-
-For output devices the default cropping rectangle is queried using
-``V4L2_SEL_TGT_CROP_DEFAULT``. It is usually equal to the bounding
-rectangle.
-
-The part of a video signal or graphics display where the image is
-inserted by the hardware is controlled by ``V4L2_SEL_TGT_COMPOSE``
-target. The rectangle's coordinates are expressed in pixels. The
-composing rectangle must lie completely inside the bounds rectangle. The
-driver must adjust the area to fit to the bounding limits. Moreover, the
-driver can perform other adjustments according to hardware limitations.
-
-The device has a default composing rectangle, given by the
-``V4L2_SEL_TGT_COMPOSE_DEFAULT`` target. This rectangle shall cover what
-the driver writer considers the complete picture. It is recommended for
-the driver developers to put the top/left corner at position ``(0,0)``.
-Drivers shall set the active composing rectangle to the default one when
-the driver is first loaded.
-
-The devices may introduce additional content to video signal other than
-an image from memory buffers. It includes borders around an image.
-However, such a padded area is driver-dependent feature not covered by
-this document. Driver developers are encouraged to keep padded rectangle
-equal to active one. The padded target is accessed by the
-``V4L2_SEL_TGT_COMPOSE_PADDED`` identifier. It must contain all pixels
-from the ``V4L2_SEL_TGT_COMPOSE`` target.
-
-
-Scaling control
-===============
-
-An application can detect if scaling is performed by comparing the width
-and the height of rectangles obtained using ``V4L2_SEL_TGT_CROP`` and
-``V4L2_SEL_TGT_COMPOSE`` targets. If these are not equal then the
-scaling is applied. The application can compute the scaling ratios using
-these values.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-********************************
-Comparison with old cropping API
-********************************
-
-The selection API was introduced to cope with deficiencies of previous
-:ref:`API <crop>`, that was designed to control simple capture
-devices. Later the cropping API was adopted by video output drivers. The
-ioctls are used to select a part of the display were the video signal is
-inserted. It should be considered as an API abuse because the described
-operation is actually the composing. The selection API makes a clear
-distinction between composing and cropping operations by setting the
-appropriate targets. The V4L2 API lacks any support for composing to and
-cropping from an image inside a memory buffer. The application could
-configure a capture device to fill only a part of an image by abusing
-V4L2 API. Cropping a smaller image from a larger one is achieved by
-setting the field ``bytesperline`` at struct
-:ref:`v4l2_pix_format <v4l2-pix-format>`.
-Introducing an image offsets could be done by modifying field ``m_userptr``
-at struct
-:ref:`v4l2_buffer <v4l2-buffer>` before calling
-:ref:`VIDIOC_QBUF`. Those operations should be avoided because they are not
-portable (endianness), and do not work for macroblock and Bayer formats
-and mmap buffers. The selection API deals with configuration of buffer
-cropping/composing in a clear, intuitive and portable way. Next, with
-the selection API the concepts of the padded target and constraints
-flags are introduced. Finally, struct :ref:`v4l2_crop <v4l2-crop>`
-and struct :ref:`v4l2_cropcap <v4l2-cropcap>` have no reserved
-fields. Therefore there is no way to extend their functionality. The new
-struct :ref:`v4l2_selection <v4l2-selection>` provides a lot of place
-for future extensions. Driver developers are encouraged to implement
-only selection API. The former cropping API would be simulated using the
-new one.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-********
-Examples
-********
-
-(A video capture device is assumed; change
-``V4L2_BUF_TYPE_VIDEO_CAPTURE`` for other devices; change target to
-``V4L2_SEL_TGT_COMPOSE_*`` family to configure composing area)
-
-
-.. code-block:: c
- :caption: Example 1.15. Resetting the cropping parameters
-
- struct v4l2_selection sel = {
- .type = V4L2_BUF_TYPE_VIDEO_CAPTURE,
- .target = V4L2_SEL_TGT_CROP_DEFAULT,
- };
- ret = ioctl(fd, VIDIOC_G_SELECTION, &sel);
- if (ret)
- exit(-1);
- sel.target = V4L2_SEL_TGT_CROP;
- ret = ioctl(fd, VIDIOC_S_SELECTION, &sel);
- if (ret)
- exit(-1);
-
-Setting a composing area on output of size of *at most* half of limit
-placed at a center of a display.
-
-
-.. code-block:: c
- :caption: Example 1.16. Simple downscaling
-
- struct v4l2_selection sel = {
- .type = V4L2_BUF_TYPE_VIDEO_OUTPUT,
- .target = V4L2_SEL_TGT_COMPOSE_BOUNDS,
- };
- struct v4l2_rect r;
-
- ret = ioctl(fd, VIDIOC_G_SELECTION, &sel);
- if (ret)
- exit(-1);
- /* setting smaller compose rectangle */
- r.width = sel.r.width / 2;
- r.height = sel.r.height / 2;
- r.left = sel.r.width / 4;
- r.top = sel.r.height / 4;
- sel.r = r;
- sel.target = V4L2_SEL_TGT_COMPOSE;
- sel.flags = V4L2_SEL_FLAG_LE;
- ret = ioctl(fd, VIDIOC_S_SELECTION, &sel);
- if (ret)
- exit(-1);
-
-A video output device is assumed; change ``V4L2_BUF_TYPE_VIDEO_OUTPUT``
-for other devices
-
-
-.. code-block:: c
- :caption: Example 1.17. Querying for scaling factors
-
- struct v4l2_selection compose = {
- .type = V4L2_BUF_TYPE_VIDEO_OUTPUT,
- .target = V4L2_SEL_TGT_COMPOSE,
- };
- struct v4l2_selection crop = {
- .type = V4L2_BUF_TYPE_VIDEO_OUTPUT,
- .target = V4L2_SEL_TGT_CROP,
- };
- double hscale, vscale;
-
- ret = ioctl(fd, VIDIOC_G_SELECTION, &compose);
- if (ret)
- exit(-1);
- ret = ioctl(fd, VIDIOC_G_SELECTION, &crop);
- if (ret)
- exit(-1);
-
- /* computing scaling factors */
- hscale = (double)compose.r.width / crop.r.width;
- vscale = (double)compose.r.height / crop.r.height;
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _selection-api:
-
-API for cropping, composing and scaling
-=======================================
-
-
-.. toctree::
- :maxdepth: 1
-
- selection-api-002
- selection-api-003
- selection-api-004
- selection-api-005
- selection-api-006
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _v4l2-selections-common:
-
-Common selection definitions
-============================
-
-While the :ref:`V4L2 selection API <selection-api>` and
-:ref:`V4L2 subdev selection APIs <v4l2-subdev-selections>` are very
-similar, there's one fundamental difference between the two. On
-sub-device API, the selection rectangle refers to the media bus format,
-and is bound to a sub-device's pad. On the V4L2 interface the selection
-rectangles refer to the in-memory pixel format.
-
-This section defines the common definitions of the selection interfaces
-on the two APIs.
-
-
-.. toctree::
- :maxdepth: 1
-
- v4l2-selection-targets
- v4l2-selection-flags
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _standard:
-
-***************
-Video Standards
-***************
-
-Video devices typically support one or more different video standards or
-variations of standards. Each video input and output may support another
-set of standards. This set is reported by the ``std`` field of struct
-:ref:`v4l2_input <v4l2-input>` and struct
-:ref:`v4l2_output <v4l2-output>` returned by the
-:ref:`VIDIOC_ENUMINPUT` and
-:ref:`VIDIOC_ENUMOUTPUT` ioctls, respectively.
-
-V4L2 defines one bit for each analog video standard currently in use
-worldwide, and sets aside bits for driver defined standards, e. g.
-hybrid standards to watch NTSC video tapes on PAL TVs and vice versa.
-Applications can use the predefined bits to select a particular
-standard, although presenting the user a menu of supported standards is
-preferred. To enumerate and query the attributes of the supported
-standards applications use the :ref:`VIDIOC_ENUMSTD`
-ioctl.
-
-Many of the defined standards are actually just variations of a few
-major standards. The hardware may in fact not distinguish between them,
-or do so internal and switch automatically. Therefore enumerated
-standards also contain sets of one or more standard bits.
-
-Assume a hypothetic tuner capable of demodulating B/PAL, G/PAL and I/PAL
-signals. The first enumerated standard is a set of B and G/PAL, switched
-automatically depending on the selected radio frequency in UHF or VHF
-band. Enumeration gives a "PAL-B/G" or "PAL-I" choice. Similar a
-Composite input may collapse standards, enumerating "PAL-B/G/H/I",
-"NTSC-M" and "SECAM-D/K". [1]_
-
-To query and select the standard used by the current video input or
-output applications call the :ref:`VIDIOC_G_STD <VIDIOC_G_STD>` and
-:ref:`VIDIOC_S_STD <VIDIOC_G_STD>` ioctl, respectively. The
-*received* standard can be sensed with the
-:ref:`VIDIOC_QUERYSTD` ioctl. Note that the
-parameter of all these ioctls is a pointer to a
-:ref:`v4l2_std_id <v4l2-std-id>` type (a standard set), *not* an
-index into the standard enumeration. Drivers must implement all video
-standard ioctls when the device has one or more video inputs or outputs.
-
-Special rules apply to devices such as USB cameras where the notion of
-video standards makes little sense. More generally for any capture or
-output device which is:
-
-- incapable of capturing fields or frames at the nominal rate of the
- video standard, or
-
-- that does not support the video standard formats at all.
-
-Here the driver shall set the ``std`` field of struct
-:ref:`v4l2_input <v4l2-input>` and struct
-:ref:`v4l2_output <v4l2-output>` to zero and the :ref:`VIDIOC_G_STD <VIDIOC_G_STD>`,
-:ref:`VIDIOC_S_STD <VIDIOC_G_STD>`, :ref:`VIDIOC_QUERYSTD` and :ref:`VIDIOC_ENUMSTD` ioctls
-shall return the ``ENOTTY`` error code or the ``EINVAL`` error code.
-
-Applications can make use of the :ref:`input-capabilities` and
-:ref:`output-capabilities` flags to determine whether the video
-standard ioctls can be used with the given input or output.
-
-
-.. code-block:: c
- :caption: Example 1.5. Information about the current video standard
-
- v4l2_std_id std_id;
- struct v4l2_standard standard;
-
- if (-1 == ioctl(fd, VIDIOC_G_STD, &std_id)) {
- /* Note when VIDIOC_ENUMSTD always returns ENOTTY this
- is no video device or it falls under the USB exception,
- and VIDIOC_G_STD returning ENOTTY is no error. */
-
- perror("VIDIOC_G_STD");
- exit(EXIT_FAILURE);
- }
-
- memset(&standard, 0, sizeof(standard));
- standard.index = 0;
-
- while (0 == ioctl(fd, VIDIOC_ENUMSTD, &standard)) {
- if (standard.id & std_id) {
- printf("Current video standard: %s\\n", standard.name);
- exit(EXIT_SUCCESS);
- }
-
- standard.index++;
- }
-
- /* EINVAL indicates the end of the enumeration, which cannot be
- empty unless this device falls under the USB exception. */
-
- if (errno == EINVAL || standard.index == 0) {
- perror("VIDIOC_ENUMSTD");
- exit(EXIT_FAILURE);
- }
-
-
-.. code-block:: c
- :caption: Example 1.6. Listing the video standards supported by the current input
-
- struct v4l2_input input;
- struct v4l2_standard standard;
-
- memset(&input, 0, sizeof(input));
-
- if (-1 == ioctl(fd, VIDIOC_G_INPUT, &input.index)) {
- perror("VIDIOC_G_INPUT");
- exit(EXIT_FAILURE);
- }
-
- if (-1 == ioctl(fd, VIDIOC_ENUMINPUT, &input)) {
- perror("VIDIOC_ENUM_INPUT");
- exit(EXIT_FAILURE);
- }
-
- printf("Current input %s supports:\\n", input.name);
-
- memset(&standard, 0, sizeof(standard));
- standard.index = 0;
-
- while (0 == ioctl(fd, VIDIOC_ENUMSTD, &standard)) {
- if (standard.id & input.std)
- printf("%s\\n", standard.name);
-
- standard.index++;
- }
-
- /* EINVAL indicates the end of the enumeration, which cannot be
- empty unless this device falls under the USB exception. */
-
- if (errno != EINVAL || standard.index == 0) {
- perror("VIDIOC_ENUMSTD");
- exit(EXIT_FAILURE);
- }
-
-
-.. code-block:: c
- :caption: Example 1.7. Selecting a new video standard
-
- struct v4l2_input input;
- v4l2_std_id std_id;
-
- memset(&input, 0, sizeof(input));
-
- if (-1 == ioctl(fd, VIDIOC_G_INPUT, &input.index)) {
- perror("VIDIOC_G_INPUT");
- exit(EXIT_FAILURE);
- }
-
- if (-1 == ioctl(fd, VIDIOC_ENUMINPUT, &input)) {
- perror("VIDIOC_ENUM_INPUT");
- exit(EXIT_FAILURE);
- }
-
- if (0 == (input.std & V4L2_STD_PAL_BG)) {
- fprintf(stderr, "Oops. B/G PAL is not supported.\\n");
- exit(EXIT_FAILURE);
- }
-
- /* Note this is also supposed to work when only B
- or G/PAL is supported. */
-
- std_id = V4L2_STD_PAL_BG;
-
- if (-1 == ioctl(fd, VIDIOC_S_STD, &std_id)) {
- perror("VIDIOC_S_STD");
- exit(EXIT_FAILURE);
- }
-
-.. [1]
- Some users are already confused by technical terms PAL, NTSC and
- SECAM. There is no point asking them to distinguish between B, G, D,
- or K when the software or hardware can do that automatically.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _streaming-par:
-
-********************
-Streaming Parameters
-********************
-
-Streaming parameters are intended to optimize the video capture process
-as well as I/O. Presently applications can request a high quality
-capture mode with the :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` ioctl.
-
-The current video standard determines a nominal number of frames per
-second. If less than this number of frames is to be captured or output,
-applications can request frame skipping or duplicating on the driver
-side. This is especially useful when using the
-:ref:`read() <func-read>` or :ref:`write() <func-write>`, which are
-not augmented by timestamps or sequence counters, and to avoid
-unnecessary data copying.
-
-Finally these ioctls can be used to determine the number of buffers used
-internally by a driver in read/write mode. For implications see the
-section discussing the :ref:`read() <func-read>` function.
-
-To get and set the streaming parameters applications call the
-:ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and
-:ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` ioctl, respectively. They take
-a pointer to a struct :ref:`v4l2_streamparm <v4l2-streamparm>`, which
-contains a union holding separate parameters for input and output
-devices.
-
-These ioctls are optional, drivers need not implement them. If so, they
-return the ``EINVAL`` error code.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _v4l2-mbus-format:
-
-Media Bus Formats
-=================
-
-
-.. _v4l2-mbus-framefmt:
-
-.. flat-table:: struct v4l2_mbus_framefmt
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``width``
-
- - Image width, in pixels.
-
- - .. row 2
-
- - __u32
-
- - ``height``
-
- - Image height, in pixels.
-
- - .. row 3
-
- - __u32
-
- - ``code``
-
- - Format code, from enum
- :ref:`v4l2_mbus_pixelcode <v4l2-mbus-pixelcode>`.
-
- - .. row 4
-
- - __u32
-
- - ``field``
-
- - Field order, from enum :ref:`v4l2_field <v4l2-field>`. See
- :ref:`field-order` for details.
-
- - .. row 5
-
- - __u32
-
- - ``colorspace``
-
- - Image colorspace, from enum
- :ref:`v4l2_colorspace <v4l2-colorspace>`. See
- :ref:`colorspaces` for details.
-
- - .. row 6
-
- - enum :ref:`v4l2_ycbcr_encoding <v4l2-ycbcr-encoding>`
-
- - ``ycbcr_enc``
-
- - This information supplements the ``colorspace`` and must be set by
- the driver for capture streams and by the application for output
- streams, see :ref:`colorspaces`.
-
- - .. row 7
-
- - enum :ref:`v4l2_quantization <v4l2-quantization>`
-
- - ``quantization``
-
- - This information supplements the ``colorspace`` and must be set by
- the driver for capture streams and by the application for output
- streams, see :ref:`colorspaces`.
-
- - .. row 8
-
- - enum :ref:`v4l2_xfer_func <v4l2-xfer-func>`
-
- - ``xfer_func``
-
- - This information supplements the ``colorspace`` and must be set by
- the driver for capture streams and by the application for output
- streams, see :ref:`colorspaces`.
-
- - .. row 9
-
- - __u16
-
- - ``reserved``\ [11]
-
- - Reserved for future extensions. Applications and drivers must set
- the array to zero.
-
-
-
-.. _v4l2-mbus-pixelcode:
-
-Media Bus Pixel Codes
----------------------
-
-The media bus pixel codes describe image formats as flowing over
-physical busses (both between separate physical components and inside
-SoC devices). This should not be confused with the V4L2 pixel formats
-that describe, using four character codes, image formats as stored in
-memory.
-
-While there is a relationship between image formats on busses and image
-formats in memory (a raw Bayer image won't be magically converted to
-JPEG just by storing it to memory), there is no one-to-one
-correspondance between them.
-
-
-Packed RGB Formats
-^^^^^^^^^^^^^^^^^^
-
-Those formats transfer pixel data as red, green and blue components. The
-format code is made of the following information.
-
-- The red, green and blue components order code, as encoded in a pixel
- sample. Possible values are RGB and BGR.
-
-- The number of bits per component, for each component. The values can
- be different for all components. Common values are 555 and 565.
-
-- The number of bus samples per pixel. Pixels that are wider than the
- bus width must be transferred in multiple samples. Common values are
- 1 and 2.
-
-- The bus width.
-
-- For formats where the total number of bits per pixel is smaller than
- the number of bus samples per pixel times the bus width, a padding
- value stating if the bytes are padded in their most high order bits
- (PADHI) or low order bits (PADLO). A "C" prefix is used for
- component-wise padding in the most high order bits (CPADHI) or low
- order bits (CPADLO) of each separate component.
-
-- For formats where the number of bus samples per pixel is larger than
- 1, an endianness value stating if the pixel is transferred MSB first
- (BE) or LSB first (LE).
-
-For instance, a format where pixels are encoded as 5-bits red, 5-bits
-green and 5-bit blue values padded on the high bit, transferred as 2
-8-bit samples per pixel with the most significant bits (padding, red and
-half of the green value) transferred first will be named
-``MEDIA_BUS_FMT_RGB555_2X8_PADHI_BE``.
-
-The following tables list existing packed RGB formats.
-
-
-.. _v4l2-mbus-pixelcode-rgb:
-
-.. flat-table:: RGB formats
- :header-rows: 2
- :stub-columns: 0
-
-
- - .. row 1
-
- - Identifier
-
- - Code
-
- -
- - :cspan:`31` Data organization
-
- - .. row 2
-
- -
- -
- - Bit
-
- - 31
-
- - 30
-
- - 29
-
- - 28
-
- - 27
-
- - 26
-
- - 25
-
- - 24
-
- - 23
-
- - 22
-
- - 21
-
- - 20
-
- - 19
-
- - 18
-
- - 17
-
- - 16
-
- - 15
-
- - 14
-
- - 13
-
- - 12
-
- - 11
-
- - 10
-
- - 9
-
- - 8
-
- - 7
-
- - 6
-
- - 5
-
- - 4
-
- - 3
-
- - 2
-
- - 1
-
- - 0
-
- - .. _MEDIA-BUS-FMT-RGB444-1X12:
-
- - MEDIA_BUS_FMT_RGB444_1X12
-
- - 0x1016
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - r\ :sub:`3`
-
- - r\ :sub:`2`
-
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
- - g\ :sub:`3`
-
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-RGB444-2X8-PADHI-BE:
-
- - MEDIA_BUS_FMT_RGB444_2X8_PADHI_BE
-
- - 0x1001
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - 0
-
- - 0
-
- - 0
-
- - 0
-
- - r\ :sub:`3`
-
- - r\ :sub:`2`
-
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
- - .. row 5
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - g\ :sub:`3`
-
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-RGB444-2X8-PADHI-LE:
-
- - MEDIA_BUS_FMT_RGB444_2X8_PADHI_LE
-
- - 0x1002
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - g\ :sub:`3`
-
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- - .. row 7
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - 0
-
- - 0
-
- - 0
-
- - 0
-
- - r\ :sub:`3`
-
- - r\ :sub:`2`
-
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-RGB555-2X8-PADHI-BE:
-
- - MEDIA_BUS_FMT_RGB555_2X8_PADHI_BE
-
- - 0x1003
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - 0
-
- - r\ :sub:`4`
-
- - r\ :sub:`3`
-
- - r\ :sub:`2`
-
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
- - g\ :sub:`4`
-
- - g\ :sub:`3`
-
- - .. row 9
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- - b\ :sub:`4`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-RGB555-2X8-PADHI-LE:
-
- - MEDIA_BUS_FMT_RGB555_2X8_PADHI_LE
-
- - 0x1004
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- - b\ :sub:`4`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- - .. row 11
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - 0
-
- - r\ :sub:`4`
-
- - r\ :sub:`3`
-
- - r\ :sub:`2`
-
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
- - g\ :sub:`4`
-
- - g\ :sub:`3`
-
- - .. _MEDIA-BUS-FMT-RGB565-1X16:
-
- - MEDIA_BUS_FMT_RGB565_1X16
-
- - 0x1017
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - r\ :sub:`4`
-
- - r\ :sub:`3`
-
- - r\ :sub:`2`
-
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
- - g\ :sub:`5`
-
- - g\ :sub:`4`
-
- - g\ :sub:`3`
-
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- - b\ :sub:`4`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-BGR565-2X8-BE:
-
- - MEDIA_BUS_FMT_BGR565_2X8_BE
-
- - 0x1005
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - b\ :sub:`4`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- - g\ :sub:`5`
-
- - g\ :sub:`4`
-
- - g\ :sub:`3`
-
- - .. row 14
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- - r\ :sub:`4`
-
- - r\ :sub:`3`
-
- - r\ :sub:`2`
-
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-BGR565-2X8-LE:
-
- - MEDIA_BUS_FMT_BGR565_2X8_LE
-
- - 0x1006
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- - r\ :sub:`4`
-
- - r\ :sub:`3`
-
- - r\ :sub:`2`
-
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
- - .. row 16
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - b\ :sub:`4`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- - g\ :sub:`5`
-
- - g\ :sub:`4`
-
- - g\ :sub:`3`
-
- - .. _MEDIA-BUS-FMT-RGB565-2X8-BE:
-
- - MEDIA_BUS_FMT_RGB565_2X8_BE
-
- - 0x1007
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - r\ :sub:`4`
-
- - r\ :sub:`3`
-
- - r\ :sub:`2`
-
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
- - g\ :sub:`5`
-
- - g\ :sub:`4`
-
- - g\ :sub:`3`
-
- - .. row 18
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- - b\ :sub:`4`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-RGB565-2X8-LE:
-
- - MEDIA_BUS_FMT_RGB565_2X8_LE
-
- - 0x1008
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- - b\ :sub:`4`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- - .. row 20
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - r\ :sub:`4`
-
- - r\ :sub:`3`
-
- - r\ :sub:`2`
-
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
- - g\ :sub:`5`
-
- - g\ :sub:`4`
-
- - g\ :sub:`3`
-
- - .. _MEDIA-BUS-FMT-RGB666-1X18:
-
- - MEDIA_BUS_FMT_RGB666_1X18
-
- - 0x1009
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - r\ :sub:`5`
-
- - r\ :sub:`4`
-
- - r\ :sub:`3`
-
- - r\ :sub:`2`
-
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
- - g\ :sub:`5`
-
- - g\ :sub:`4`
-
- - g\ :sub:`3`
-
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- - b\ :sub:`5`
-
- - b\ :sub:`4`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-RBG888-1X24:
-
- - MEDIA_BUS_FMT_RBG888_1X24
-
- - 0x100e
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - r\ :sub:`7`
-
- - r\ :sub:`6`
-
- - r\ :sub:`5`
-
- - r\ :sub:`4`
-
- - r\ :sub:`3`
-
- - r\ :sub:`2`
-
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
- - b\ :sub:`7`
-
- - b\ :sub:`6`
-
- - b\ :sub:`5`
-
- - b\ :sub:`4`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- - g\ :sub:`7`
-
- - g\ :sub:`6`
-
- - g\ :sub:`5`
-
- - g\ :sub:`4`
-
- - g\ :sub:`3`
-
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-RGB666-1X24_CPADHI:
-
- - MEDIA_BUS_FMT_RGB666_1X24_CPADHI
-
- - 0x1015
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - 0
-
- - 0
-
- - r\ :sub:`5`
-
- - r\ :sub:`4`
-
- - r\ :sub:`3`
-
- - r\ :sub:`2`
-
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
- - 0
-
- - 0
-
- - g\ :sub:`5`
-
- - g\ :sub:`4`
-
- - g\ :sub:`3`
-
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- - 0
-
- - 0
-
- - b\ :sub:`5`
-
- - b\ :sub:`4`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-BGR888-1X24:
-
- - MEDIA_BUS_FMT_BGR888_1X24
-
- - 0x1013
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - b\ :sub:`7`
-
- - b\ :sub:`6`
-
- - b\ :sub:`5`
-
- - b\ :sub:`4`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- - g\ :sub:`7`
-
- - g\ :sub:`6`
-
- - g\ :sub:`5`
-
- - g\ :sub:`4`
-
- - g\ :sub:`3`
-
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- - r\ :sub:`7`
-
- - r\ :sub:`6`
-
- - r\ :sub:`5`
-
- - r\ :sub:`4`
-
- - r\ :sub:`3`
-
- - r\ :sub:`2`
-
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-GBR888-1X24:
-
- - MEDIA_BUS_FMT_GBR888_1X24
-
- - 0x1014
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - g\ :sub:`7`
-
- - g\ :sub:`6`
-
- - g\ :sub:`5`
-
- - g\ :sub:`4`
-
- - g\ :sub:`3`
-
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- - b\ :sub:`7`
-
- - b\ :sub:`6`
-
- - b\ :sub:`5`
-
- - b\ :sub:`4`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- - r\ :sub:`7`
-
- - r\ :sub:`6`
-
- - r\ :sub:`5`
-
- - r\ :sub:`4`
-
- - r\ :sub:`3`
-
- - r\ :sub:`2`
-
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-RGB888-1X24:
-
- - MEDIA_BUS_FMT_RGB888_1X24
-
- - 0x100a
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - r\ :sub:`7`
-
- - r\ :sub:`6`
-
- - r\ :sub:`5`
-
- - r\ :sub:`4`
-
- - r\ :sub:`3`
-
- - r\ :sub:`2`
-
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
- - g\ :sub:`7`
-
- - g\ :sub:`6`
-
- - g\ :sub:`5`
-
- - g\ :sub:`4`
-
- - g\ :sub:`3`
-
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- - b\ :sub:`7`
-
- - b\ :sub:`6`
-
- - b\ :sub:`5`
-
- - b\ :sub:`4`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-RGB888-2X12-BE:
-
- - MEDIA_BUS_FMT_RGB888_2X12_BE
-
- - 0x100b
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - r\ :sub:`7`
-
- - r\ :sub:`6`
-
- - r\ :sub:`5`
-
- - r\ :sub:`4`
-
- - r\ :sub:`3`
-
- - r\ :sub:`2`
-
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
- - g\ :sub:`7`
-
- - g\ :sub:`6`
-
- - g\ :sub:`5`
-
- - g\ :sub:`4`
-
- - .. row 28
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - g\ :sub:`3`
-
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- - b\ :sub:`7`
-
- - b\ :sub:`6`
-
- - b\ :sub:`5`
-
- - b\ :sub:`4`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-RGB888-2X12-LE:
-
- - MEDIA_BUS_FMT_RGB888_2X12_LE
-
- - 0x100c
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - g\ :sub:`3`
-
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- - b\ :sub:`7`
-
- - b\ :sub:`6`
-
- - b\ :sub:`5`
-
- - b\ :sub:`4`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- - .. row 30
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - r\ :sub:`7`
-
- - r\ :sub:`6`
-
- - r\ :sub:`5`
-
- - r\ :sub:`4`
-
- - r\ :sub:`3`
-
- - r\ :sub:`2`
-
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
- - g\ :sub:`7`
-
- - g\ :sub:`6`
-
- - g\ :sub:`5`
-
- - g\ :sub:`4`
-
- - .. _MEDIA-BUS-FMT-ARGB888-1X32:
-
- - MEDIA_BUS_FMT_ARGB888_1X32
-
- - 0x100d
-
- -
- - a\ :sub:`7`
-
- - a\ :sub:`6`
-
- - a\ :sub:`5`
-
- - a\ :sub:`4`
-
- - a\ :sub:`3`
-
- - a\ :sub:`2`
-
- - a\ :sub:`1`
-
- - a\ :sub:`0`
-
- - r\ :sub:`7`
-
- - r\ :sub:`6`
-
- - r\ :sub:`5`
-
- - r\ :sub:`4`
-
- - r\ :sub:`3`
-
- - r\ :sub:`2`
-
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
- - g\ :sub:`7`
-
- - g\ :sub:`6`
-
- - g\ :sub:`5`
-
- - g\ :sub:`4`
-
- - g\ :sub:`3`
-
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- - b\ :sub:`7`
-
- - b\ :sub:`6`
-
- - b\ :sub:`5`
-
- - b\ :sub:`4`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-RGB888-1X32-PADHI:
-
- - MEDIA_BUS_FMT_RGB888_1X32_PADHI
-
- - 0x100f
-
- -
- - 0
-
- - 0
-
- - 0
-
- - 0
-
- - 0
-
- - 0
-
- - 0
-
- - 0
-
- - r\ :sub:`7`
-
- - r\ :sub:`6`
-
- - r\ :sub:`5`
-
- - r\ :sub:`4`
-
- - r\ :sub:`3`
-
- - r\ :sub:`2`
-
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
- - g\ :sub:`7`
-
- - g\ :sub:`6`
-
- - g\ :sub:`5`
-
- - g\ :sub:`4`
-
- - g\ :sub:`3`
-
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- - b\ :sub:`7`
-
- - b\ :sub:`6`
-
- - b\ :sub:`5`
-
- - b\ :sub:`4`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
-
-On LVDS buses, usually each sample is transferred serialized in seven
-time slots per pixel clock, on three (18-bit) or four (24-bit)
-differential data pairs at the same time. The remaining bits are used
-for control signals as defined by SPWG/PSWG/VESA or JEIDA standards. The
-24-bit RGB format serialized in seven time slots on four lanes using
-JEIDA defined bit mapping will be named
-``MEDIA_BUS_FMT_RGB888_1X7X4_JEIDA``, for example.
-
-
-.. _v4l2-mbus-pixelcode-rgb-lvds:
-
-.. flat-table:: LVDS RGB formats
- :header-rows: 2
- :stub-columns: 0
-
-
- - .. row 1
-
- - Identifier
-
- - Code
-
- -
- -
- - :cspan:`3` Data organization
-
- - .. row 2
-
- -
- -
- - Timeslot
-
- - Lane
-
- - 3
-
- - 2
-
- - 1
-
- - 0
-
- - .. _MEDIA-BUS-FMT-RGB666-1X7X3-SPWG:
-
- - MEDIA_BUS_FMT_RGB666_1X7X3_SPWG
-
- - 0x1010
-
- - 0
-
- -
- - -
-
- - d
-
- - b\ :sub:`1`
-
- - g\ :sub:`0`
-
- - .. row 4
-
- -
- -
- - 1
-
- -
- - -
-
- - d
-
- - b\ :sub:`0`
-
- - r\ :sub:`5`
-
- - .. row 5
-
- -
- -
- - 2
-
- -
- - -
-
- - d
-
- - g\ :sub:`5`
-
- - r\ :sub:`4`
-
- - .. row 6
-
- -
- -
- - 3
-
- -
- - -
-
- - b\ :sub:`5`
-
- - g\ :sub:`4`
-
- - r\ :sub:`3`
-
- - .. row 7
-
- -
- -
- - 4
-
- -
- - -
-
- - b\ :sub:`4`
-
- - g\ :sub:`3`
-
- - r\ :sub:`2`
-
- - .. row 8
-
- -
- -
- - 5
-
- -
- - -
-
- - b\ :sub:`3`
-
- - g\ :sub:`2`
-
- - r\ :sub:`1`
-
- - .. row 9
-
- -
- -
- - 6
-
- -
- - -
-
- - b\ :sub:`2`
-
- - g\ :sub:`1`
-
- - r\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-RGB888-1X7X4-SPWG:
-
- - MEDIA_BUS_FMT_RGB888_1X7X4_SPWG
-
- - 0x1011
-
- - 0
-
- -
- - d
-
- - d
-
- - b\ :sub:`1`
-
- - g\ :sub:`0`
-
- - .. row 11
-
- -
- -
- - 1
-
- -
- - b\ :sub:`7`
-
- - d
-
- - b\ :sub:`0`
-
- - r\ :sub:`5`
-
- - .. row 12
-
- -
- -
- - 2
-
- -
- - b\ :sub:`6`
-
- - d
-
- - g\ :sub:`5`
-
- - r\ :sub:`4`
-
- - .. row 13
-
- -
- -
- - 3
-
- -
- - g\ :sub:`7`
-
- - b\ :sub:`5`
-
- - g\ :sub:`4`
-
- - r\ :sub:`3`
-
- - .. row 14
-
- -
- -
- - 4
-
- -
- - g\ :sub:`6`
-
- - b\ :sub:`4`
-
- - g\ :sub:`3`
-
- - r\ :sub:`2`
-
- - .. row 15
-
- -
- -
- - 5
-
- -
- - r\ :sub:`7`
-
- - b\ :sub:`3`
-
- - g\ :sub:`2`
-
- - r\ :sub:`1`
-
- - .. row 16
-
- -
- -
- - 6
-
- -
- - r\ :sub:`6`
-
- - b\ :sub:`2`
-
- - g\ :sub:`1`
-
- - r\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-RGB888-1X7X4-JEIDA:
-
- - MEDIA_BUS_FMT_RGB888_1X7X4_JEIDA
-
- - 0x1012
-
- - 0
-
- -
- - d
-
- - d
-
- - b\ :sub:`3`
-
- - g\ :sub:`2`
-
- - .. row 18
-
- -
- -
- - 1
-
- -
- - b\ :sub:`1`
-
- - d
-
- - b\ :sub:`2`
-
- - r\ :sub:`7`
-
- - .. row 19
-
- -
- -
- - 2
-
- -
- - b\ :sub:`0`
-
- - d
-
- - g\ :sub:`7`
-
- - r\ :sub:`6`
-
- - .. row 20
-
- -
- -
- - 3
-
- -
- - g\ :sub:`1`
-
- - b\ :sub:`7`
-
- - g\ :sub:`6`
-
- - r\ :sub:`5`
-
- - .. row 21
-
- -
- -
- - 4
-
- -
- - g\ :sub:`0`
-
- - b\ :sub:`6`
-
- - g\ :sub:`5`
-
- - r\ :sub:`4`
-
- - .. row 22
-
- -
- -
- - 5
-
- -
- - r\ :sub:`1`
-
- - b\ :sub:`5`
-
- - g\ :sub:`4`
-
- - r\ :sub:`3`
-
- - .. row 23
-
- -
- -
- - 6
-
- -
- - r\ :sub:`0`
-
- - b\ :sub:`4`
-
- - g\ :sub:`3`
-
- - r\ :sub:`2`
-
-
-
-Bayer Formats
-^^^^^^^^^^^^^
-
-Those formats transfer pixel data as red, green and blue components. The
-format code is made of the following information.
-
-- The red, green and blue components order code, as encoded in a pixel
- sample. The possible values are shown in :ref:`bayer-patterns`.
-
-- The number of bits per pixel component. All components are
- transferred on the same number of bits. Common values are 8, 10 and
- 12.
-
-- The compression (optional). If the pixel components are ALAW- or
- DPCM-compressed, a mention of the compression scheme and the number
- of bits per compressed pixel component.
-
-- The number of bus samples per pixel. Pixels that are wider than the
- bus width must be transferred in multiple samples. Common values are
- 1 and 2.
-
-- The bus width.
-
-- For formats where the total number of bits per pixel is smaller than
- the number of bus samples per pixel times the bus width, a padding
- value stating if the bytes are padded in their most high order bits
- (PADHI) or low order bits (PADLO).
-
-- For formats where the number of bus samples per pixel is larger than
- 1, an endianness value stating if the pixel is transferred MSB first
- (BE) or LSB first (LE).
-
-For instance, a format with uncompressed 10-bit Bayer components
-arranged in a red, green, green, blue pattern transferred as 2 8-bit
-samples per pixel with the least significant bits transferred first will
-be named ``MEDIA_BUS_FMT_SRGGB10_2X8_PADHI_LE``.
-
-
-.. _bayer-patterns:
-
-.. figure:: subdev-formats_files/bayer.*
- :alt: bayer.png
- :align: center
-
- **Figure 4.8 Bayer Patterns**
-
-
-
-The following table lists existing packed Bayer formats. The data
-organization is given as an example for the first pixel only.
-
-
-.. _v4l2-mbus-pixelcode-bayer:
-
-.. flat-table:: Bayer Formats
- :header-rows: 2
- :stub-columns: 0
-
-
- - .. row 1
-
- - Identifier
-
- - Code
-
- -
- - :cspan:`11` Data organization
-
- - .. row 2
-
- -
- -
- - Bit
-
- - 11
-
- - 10
-
- - 9
-
- - 8
-
- - 7
-
- - 6
-
- - 5
-
- - 4
-
- - 3
-
- - 2
-
- - 1
-
- - 0
-
- - .. _MEDIA-BUS-FMT-SBGGR8-1X8:
-
- - MEDIA_BUS_FMT_SBGGR8_1X8
-
- - 0x3001
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - b\ :sub:`7`
-
- - b\ :sub:`6`
-
- - b\ :sub:`5`
-
- - b\ :sub:`4`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-SGBRG8-1X8:
-
- - MEDIA_BUS_FMT_SGBRG8_1X8
-
- - 0x3013
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - g\ :sub:`7`
-
- - g\ :sub:`6`
-
- - g\ :sub:`5`
-
- - g\ :sub:`4`
-
- - g\ :sub:`3`
-
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-SGRBG8-1X8:
-
- - MEDIA_BUS_FMT_SGRBG8_1X8
-
- - 0x3002
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - g\ :sub:`7`
-
- - g\ :sub:`6`
-
- - g\ :sub:`5`
-
- - g\ :sub:`4`
-
- - g\ :sub:`3`
-
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-SRGGB8-1X8:
-
- - MEDIA_BUS_FMT_SRGGB8_1X8
-
- - 0x3014
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - r\ :sub:`7`
-
- - r\ :sub:`6`
-
- - r\ :sub:`5`
-
- - r\ :sub:`4`
-
- - r\ :sub:`3`
-
- - r\ :sub:`2`
-
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-SBGGR10-ALAW8-1X8:
-
- - MEDIA_BUS_FMT_SBGGR10_ALAW8_1X8
-
- - 0x3015
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - b\ :sub:`7`
-
- - b\ :sub:`6`
-
- - b\ :sub:`5`
-
- - b\ :sub:`4`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-SGBRG10-ALAW8-1X8:
-
- - MEDIA_BUS_FMT_SGBRG10_ALAW8_1X8
-
- - 0x3016
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - g\ :sub:`7`
-
- - g\ :sub:`6`
-
- - g\ :sub:`5`
-
- - g\ :sub:`4`
-
- - g\ :sub:`3`
-
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-SGRBG10-ALAW8-1X8:
-
- - MEDIA_BUS_FMT_SGRBG10_ALAW8_1X8
-
- - 0x3017
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - g\ :sub:`7`
-
- - g\ :sub:`6`
-
- - g\ :sub:`5`
-
- - g\ :sub:`4`
-
- - g\ :sub:`3`
-
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-SRGGB10-ALAW8-1X8:
-
- - MEDIA_BUS_FMT_SRGGB10_ALAW8_1X8
-
- - 0x3018
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - r\ :sub:`7`
-
- - r\ :sub:`6`
-
- - r\ :sub:`5`
-
- - r\ :sub:`4`
-
- - r\ :sub:`3`
-
- - r\ :sub:`2`
-
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-SBGGR10-DPCM8-1X8:
-
- - MEDIA_BUS_FMT_SBGGR10_DPCM8_1X8
-
- - 0x300b
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - b\ :sub:`7`
-
- - b\ :sub:`6`
-
- - b\ :sub:`5`
-
- - b\ :sub:`4`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-SGBRG10-DPCM8-1X8:
-
- - MEDIA_BUS_FMT_SGBRG10_DPCM8_1X8
-
- - 0x300c
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - g\ :sub:`7`
-
- - g\ :sub:`6`
-
- - g\ :sub:`5`
-
- - g\ :sub:`4`
-
- - g\ :sub:`3`
-
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-SGRBG10-DPCM8-1X8:
-
- - MEDIA_BUS_FMT_SGRBG10_DPCM8_1X8
-
- - 0x3009
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - g\ :sub:`7`
-
- - g\ :sub:`6`
-
- - g\ :sub:`5`
-
- - g\ :sub:`4`
-
- - g\ :sub:`3`
-
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-SRGGB10-DPCM8-1X8:
-
- - MEDIA_BUS_FMT_SRGGB10_DPCM8_1X8
-
- - 0x300d
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - r\ :sub:`7`
-
- - r\ :sub:`6`
-
- - r\ :sub:`5`
-
- - r\ :sub:`4`
-
- - r\ :sub:`3`
-
- - r\ :sub:`2`
-
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-SBGGR10-2X8-PADHI-BE:
-
- - MEDIA_BUS_FMT_SBGGR10_2X8_PADHI_BE
-
- - 0x3003
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - 0
-
- - 0
-
- - 0
-
- - 0
-
- - 0
-
- - 0
-
- - b\ :sub:`9`
-
- - b\ :sub:`8`
-
- - .. row 16
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - b\ :sub:`7`
-
- - b\ :sub:`6`
-
- - b\ :sub:`5`
-
- - b\ :sub:`4`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-SBGGR10-2X8-PADHI-LE:
-
- - MEDIA_BUS_FMT_SBGGR10_2X8_PADHI_LE
-
- - 0x3004
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - b\ :sub:`7`
-
- - b\ :sub:`6`
-
- - b\ :sub:`5`
-
- - b\ :sub:`4`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- - .. row 18
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - 0
-
- - 0
-
- - 0
-
- - 0
-
- - 0
-
- - 0
-
- - b\ :sub:`9`
-
- - b\ :sub:`8`
-
- - .. _MEDIA-BUS-FMT-SBGGR10-2X8-PADLO-BE:
-
- - MEDIA_BUS_FMT_SBGGR10_2X8_PADLO_BE
-
- - 0x3005
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - b\ :sub:`9`
-
- - b\ :sub:`8`
-
- - b\ :sub:`7`
-
- - b\ :sub:`6`
-
- - b\ :sub:`5`
-
- - b\ :sub:`4`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - .. row 20
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- - 0
-
- - 0
-
- - 0
-
- - 0
-
- - 0
-
- - 0
-
- - .. _MEDIA-BUS-FMT-SBGGR10-2X8-PADLO-LE:
-
- - MEDIA_BUS_FMT_SBGGR10_2X8_PADLO_LE
-
- - 0x3006
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- - 0
-
- - 0
-
- - 0
-
- - 0
-
- - 0
-
- - 0
-
- - .. row 22
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - b\ :sub:`9`
-
- - b\ :sub:`8`
-
- - b\ :sub:`7`
-
- - b\ :sub:`6`
-
- - b\ :sub:`5`
-
- - b\ :sub:`4`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - .. _MEDIA-BUS-FMT-SBGGR10-1X10:
-
- - MEDIA_BUS_FMT_SBGGR10_1X10
-
- - 0x3007
-
- -
- - -
-
- - -
-
- - b\ :sub:`9`
-
- - b\ :sub:`8`
-
- - b\ :sub:`7`
-
- - b\ :sub:`6`
-
- - b\ :sub:`5`
-
- - b\ :sub:`4`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-SGBRG10-1X10:
-
- - MEDIA_BUS_FMT_SGBRG10_1X10
-
- - 0x300e
-
- -
- - -
-
- - -
-
- - g\ :sub:`9`
-
- - g\ :sub:`8`
-
- - g\ :sub:`7`
-
- - g\ :sub:`6`
-
- - g\ :sub:`5`
-
- - g\ :sub:`4`
-
- - g\ :sub:`3`
-
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-SGRBG10-1X10:
-
- - MEDIA_BUS_FMT_SGRBG10_1X10
-
- - 0x300a
-
- -
- - -
-
- - -
-
- - g\ :sub:`9`
-
- - g\ :sub:`8`
-
- - g\ :sub:`7`
-
- - g\ :sub:`6`
-
- - g\ :sub:`5`
-
- - g\ :sub:`4`
-
- - g\ :sub:`3`
-
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-SRGGB10-1X10:
-
- - MEDIA_BUS_FMT_SRGGB10_1X10
-
- - 0x300f
-
- -
- - -
-
- - -
-
- - r\ :sub:`9`
-
- - r\ :sub:`8`
-
- - r\ :sub:`7`
-
- - r\ :sub:`6`
-
- - r\ :sub:`5`
-
- - r\ :sub:`4`
-
- - r\ :sub:`3`
-
- - r\ :sub:`2`
-
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-SBGGR12-1X12:
-
- - MEDIA_BUS_FMT_SBGGR12_1X12
-
- - 0x3008
-
- -
- - b\ :sub:`11`
-
- - b\ :sub:`10`
-
- - b\ :sub:`9`
-
- - b\ :sub:`8`
-
- - b\ :sub:`7`
-
- - b\ :sub:`6`
-
- - b\ :sub:`5`
-
- - b\ :sub:`4`
-
- - b\ :sub:`3`
-
- - b\ :sub:`2`
-
- - b\ :sub:`1`
-
- - b\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-SGBRG12-1X12:
-
- - MEDIA_BUS_FMT_SGBRG12_1X12
-
- - 0x3010
-
- -
- - g\ :sub:`11`
-
- - g\ :sub:`10`
-
- - g\ :sub:`9`
-
- - g\ :sub:`8`
-
- - g\ :sub:`7`
-
- - g\ :sub:`6`
-
- - g\ :sub:`5`
-
- - g\ :sub:`4`
-
- - g\ :sub:`3`
-
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-SGRBG12-1X12:
-
- - MEDIA_BUS_FMT_SGRBG12_1X12
-
- - 0x3011
-
- -
- - g\ :sub:`11`
-
- - g\ :sub:`10`
-
- - g\ :sub:`9`
-
- - g\ :sub:`8`
-
- - g\ :sub:`7`
-
- - g\ :sub:`6`
-
- - g\ :sub:`5`
-
- - g\ :sub:`4`
-
- - g\ :sub:`3`
-
- - g\ :sub:`2`
-
- - g\ :sub:`1`
-
- - g\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-SRGGB12-1X12:
-
- - MEDIA_BUS_FMT_SRGGB12_1X12
-
- - 0x3012
-
- -
- - r\ :sub:`11`
-
- - r\ :sub:`10`
-
- - r\ :sub:`9`
-
- - r\ :sub:`8`
-
- - r\ :sub:`7`
-
- - r\ :sub:`6`
-
- - r\ :sub:`5`
-
- - r\ :sub:`4`
-
- - r\ :sub:`3`
-
- - r\ :sub:`2`
-
- - r\ :sub:`1`
-
- - r\ :sub:`0`
-
-
-
-Packed YUV Formats
-^^^^^^^^^^^^^^^^^^
-
-Those data formats transfer pixel data as (possibly downsampled) Y, U
-and V components. Some formats include dummy bits in some of their
-samples and are collectively referred to as "YDYC" (Y-Dummy-Y-Chroma)
-formats. One cannot rely on the values of these dummy bits as those are
-undefined.
-
-The format code is made of the following information.
-
-- The Y, U and V components order code, as transferred on the bus.
- Possible values are YUYV, UYVY, YVYU and VYUY for formats with no
- dummy bit, and YDYUYDYV, YDYVYDYU, YUYDYVYD and YVYDYUYD for YDYC
- formats.
-
-- The number of bits per pixel component. All components are
- transferred on the same number of bits. Common values are 8, 10 and
- 12.
-
-- The number of bus samples per pixel. Pixels that are wider than the
- bus width must be transferred in multiple samples. Common values are
- 1, 1.5 (encoded as 1_5) and 2.
-
-- The bus width. When the bus width is larger than the number of bits
- per pixel component, several components are packed in a single bus
- sample. The components are ordered as specified by the order code,
- with components on the left of the code transferred in the high order
- bits. Common values are 8 and 16.
-
-For instance, a format where pixels are encoded as 8-bit YUV values
-downsampled to 4:2:2 and transferred as 2 8-bit bus samples per pixel in
-the U, Y, V, Y order will be named ``MEDIA_BUS_FMT_UYVY8_2X8``.
-
-:ref:`v4l2-mbus-pixelcode-yuv8` lists existing packed YUV formats and
-describes the organization of each pixel data in each sample. When a
-format pattern is split across multiple samples each of the samples in
-the pattern is described.
-
-The role of each bit transferred over the bus is identified by one of
-the following codes.
-
-- y\ :sub:`x` for luma component bit number x
-
-- u\ :sub:`x` for blue chroma component bit number x
-
-- v\ :sub:`x` for red chroma component bit number x
-
-- a\ :sub:`x` for alpha component bit number x
-
-- - for non-available bits (for positions higher than the bus width)
-
-- d for dummy bits
-
-
-.. _v4l2-mbus-pixelcode-yuv8:
-
-.. flat-table:: YUV Formats
- :header-rows: 2
- :stub-columns: 0
-
-
- - .. row 1
-
- - Identifier
-
- - Code
-
- -
- - :cspan:`31` Data organization
-
- - .. row 2
-
- -
- -
- - Bit
-
- - 31
-
- - 30
-
- - 29
-
- - 28
-
- - 27
-
- - 26
-
- - 25
-
- - 24
-
- - 23
-
- - 22
-
- - 21
-
- - 10
-
- - 19
-
- - 18
-
- - 17
-
- - 16
-
- - 15
-
- - 14
-
- - 13
-
- - 12
-
- - 11
-
- - 10
-
- - 9
-
- - 8
-
- - 7
-
- - 6
-
- - 5
-
- - 4
-
- - 3
-
- - 2
-
- - 1
-
- - 0
-
- - .. _MEDIA-BUS-FMT-Y8-1X8:
-
- - MEDIA_BUS_FMT_Y8_1X8
-
- - 0x2001
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-UV8-1X8:
-
- - MEDIA_BUS_FMT_UV8_1X8
-
- - 0x2015
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - u\ :sub:`7`
-
- - u\ :sub:`6`
-
- - u\ :sub:`5`
-
- - u\ :sub:`4`
-
- - u\ :sub:`3`
-
- - u\ :sub:`2`
-
- - u\ :sub:`1`
-
- - u\ :sub:`0`
-
- - .. row 5
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - v\ :sub:`7`
-
- - v\ :sub:`6`
-
- - v\ :sub:`5`
-
- - v\ :sub:`4`
-
- - v\ :sub:`3`
-
- - v\ :sub:`2`
-
- - v\ :sub:`1`
-
- - v\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-UYVY8-1_5X8:
-
- - MEDIA_BUS_FMT_UYVY8_1_5X8
-
- - 0x2002
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - u\ :sub:`7`
-
- - u\ :sub:`6`
-
- - u\ :sub:`5`
-
- - u\ :sub:`4`
-
- - u\ :sub:`3`
-
- - u\ :sub:`2`
-
- - u\ :sub:`1`
-
- - u\ :sub:`0`
-
- - .. row 7
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. row 8
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. row 9
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - v\ :sub:`7`
-
- - v\ :sub:`6`
-
- - v\ :sub:`5`
-
- - v\ :sub:`4`
-
- - v\ :sub:`3`
-
- - v\ :sub:`2`
-
- - v\ :sub:`1`
-
- - v\ :sub:`0`
-
- - .. row 10
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. row 11
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-VYUY8-1_5X8:
-
- - MEDIA_BUS_FMT_VYUY8_1_5X8
-
- - 0x2003
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - v\ :sub:`7`
-
- - v\ :sub:`6`
-
- - v\ :sub:`5`
-
- - v\ :sub:`4`
-
- - v\ :sub:`3`
-
- - v\ :sub:`2`
-
- - v\ :sub:`1`
-
- - v\ :sub:`0`
-
- - .. row 13
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. row 14
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. row 15
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - u\ :sub:`7`
-
- - u\ :sub:`6`
-
- - u\ :sub:`5`
-
- - u\ :sub:`4`
-
- - u\ :sub:`3`
-
- - u\ :sub:`2`
-
- - u\ :sub:`1`
-
- - u\ :sub:`0`
-
- - .. row 16
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. row 17
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-YUYV8-1_5X8:
-
- - MEDIA_BUS_FMT_YUYV8_1_5X8
-
- - 0x2004
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. row 19
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. row 20
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - u\ :sub:`7`
-
- - u\ :sub:`6`
-
- - u\ :sub:`5`
-
- - u\ :sub:`4`
-
- - u\ :sub:`3`
-
- - u\ :sub:`2`
-
- - u\ :sub:`1`
-
- - u\ :sub:`0`
-
- - .. row 21
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. row 22
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. row 23
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - v\ :sub:`7`
-
- - v\ :sub:`6`
-
- - v\ :sub:`5`
-
- - v\ :sub:`4`
-
- - v\ :sub:`3`
-
- - v\ :sub:`2`
-
- - v\ :sub:`1`
-
- - v\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-YVYU8-1_5X8:
-
- - MEDIA_BUS_FMT_YVYU8_1_5X8
-
- - 0x2005
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. row 25
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. row 26
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - v\ :sub:`7`
-
- - v\ :sub:`6`
-
- - v\ :sub:`5`
-
- - v\ :sub:`4`
-
- - v\ :sub:`3`
-
- - v\ :sub:`2`
-
- - v\ :sub:`1`
-
- - v\ :sub:`0`
-
- - .. row 27
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. row 28
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. row 29
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - u\ :sub:`7`
-
- - u\ :sub:`6`
-
- - u\ :sub:`5`
-
- - u\ :sub:`4`
-
- - u\ :sub:`3`
-
- - u\ :sub:`2`
-
- - u\ :sub:`1`
-
- - u\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-UYVY8-2X8:
-
- - MEDIA_BUS_FMT_UYVY8_2X8
-
- - 0x2006
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - u\ :sub:`7`
-
- - u\ :sub:`6`
-
- - u\ :sub:`5`
-
- - u\ :sub:`4`
-
- - u\ :sub:`3`
-
- - u\ :sub:`2`
-
- - u\ :sub:`1`
-
- - u\ :sub:`0`
-
- - .. row 31
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. row 32
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - v\ :sub:`7`
-
- - v\ :sub:`6`
-
- - v\ :sub:`5`
-
- - v\ :sub:`4`
-
- - v\ :sub:`3`
-
- - v\ :sub:`2`
-
- - v\ :sub:`1`
-
- - v\ :sub:`0`
-
- - .. row 33
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-VYUY8-2X8:
-
- - MEDIA_BUS_FMT_VYUY8_2X8
-
- - 0x2007
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - v\ :sub:`7`
-
- - v\ :sub:`6`
-
- - v\ :sub:`5`
-
- - v\ :sub:`4`
-
- - v\ :sub:`3`
-
- - v\ :sub:`2`
-
- - v\ :sub:`1`
-
- - v\ :sub:`0`
-
- - .. row 35
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. row 36
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - u\ :sub:`7`
-
- - u\ :sub:`6`
-
- - u\ :sub:`5`
-
- - u\ :sub:`4`
-
- - u\ :sub:`3`
-
- - u\ :sub:`2`
-
- - u\ :sub:`1`
-
- - u\ :sub:`0`
-
- - .. row 37
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-YUYV8-2X8:
-
- - MEDIA_BUS_FMT_YUYV8_2X8
-
- - 0x2008
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. row 39
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - u\ :sub:`7`
-
- - u\ :sub:`6`
-
- - u\ :sub:`5`
-
- - u\ :sub:`4`
-
- - u\ :sub:`3`
-
- - u\ :sub:`2`
-
- - u\ :sub:`1`
-
- - u\ :sub:`0`
-
- - .. row 40
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. row 41
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - v\ :sub:`7`
-
- - v\ :sub:`6`
-
- - v\ :sub:`5`
-
- - v\ :sub:`4`
-
- - v\ :sub:`3`
-
- - v\ :sub:`2`
-
- - v\ :sub:`1`
-
- - v\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-YVYU8-2X8:
-
- - MEDIA_BUS_FMT_YVYU8_2X8
-
- - 0x2009
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. row 43
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - v\ :sub:`7`
-
- - v\ :sub:`6`
-
- - v\ :sub:`5`
-
- - v\ :sub:`4`
-
- - v\ :sub:`3`
-
- - v\ :sub:`2`
-
- - v\ :sub:`1`
-
- - v\ :sub:`0`
-
- - .. row 44
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. row 45
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - u\ :sub:`7`
-
- - u\ :sub:`6`
-
- - u\ :sub:`5`
-
- - u\ :sub:`4`
-
- - u\ :sub:`3`
-
- - u\ :sub:`2`
-
- - u\ :sub:`1`
-
- - u\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-Y10-1X10:
-
- - MEDIA_BUS_FMT_Y10_1X10
-
- - 0x200a
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`9`
-
- - y\ :sub:`8`
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-UYVY10-2X10:
-
- - MEDIA_BUS_FMT_UYVY10_2X10
-
- - 0x2018
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - u\ :sub:`9`
-
- - u\ :sub:`8`
-
- - u\ :sub:`7`
-
- - u\ :sub:`6`
-
- - u\ :sub:`5`
-
- - u\ :sub:`4`
-
- - u\ :sub:`3`
-
- - u\ :sub:`2`
-
- - u\ :sub:`1`
-
- - u\ :sub:`0`
-
- - .. row 48
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`9`
-
- - y\ :sub:`8`
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. row 49
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - v\ :sub:`9`
-
- - v\ :sub:`8`
-
- - v\ :sub:`7`
-
- - v\ :sub:`6`
-
- - v\ :sub:`5`
-
- - v\ :sub:`4`
-
- - v\ :sub:`3`
-
- - v\ :sub:`2`
-
- - v\ :sub:`1`
-
- - v\ :sub:`0`
-
- - .. row 50
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`9`
-
- - y\ :sub:`8`
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-VYUY10-2X10:
-
- - MEDIA_BUS_FMT_VYUY10_2X10
-
- - 0x2019
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - v\ :sub:`9`
-
- - v\ :sub:`8`
-
- - v\ :sub:`7`
-
- - v\ :sub:`6`
-
- - v\ :sub:`5`
-
- - v\ :sub:`4`
-
- - v\ :sub:`3`
-
- - v\ :sub:`2`
-
- - v\ :sub:`1`
-
- - v\ :sub:`0`
-
- - .. row 52
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`9`
-
- - y\ :sub:`8`
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. row 53
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - u\ :sub:`9`
-
- - u\ :sub:`8`
-
- - u\ :sub:`7`
-
- - u\ :sub:`6`
-
- - u\ :sub:`5`
-
- - u\ :sub:`4`
-
- - u\ :sub:`3`
-
- - u\ :sub:`2`
-
- - u\ :sub:`1`
-
- - u\ :sub:`0`
-
- - .. row 54
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`9`
-
- - y\ :sub:`8`
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-YUYV10-2X10:
-
- - MEDIA_BUS_FMT_YUYV10_2X10
-
- - 0x200b
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`9`
-
- - y\ :sub:`8`
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. row 56
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - u\ :sub:`9`
-
- - u\ :sub:`8`
-
- - u\ :sub:`7`
-
- - u\ :sub:`6`
-
- - u\ :sub:`5`
-
- - u\ :sub:`4`
-
- - u\ :sub:`3`
-
- - u\ :sub:`2`
-
- - u\ :sub:`1`
-
- - u\ :sub:`0`
-
- - .. row 57
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`9`
-
- - y\ :sub:`8`
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. row 58
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - v\ :sub:`9`
-
- - v\ :sub:`8`
-
- - v\ :sub:`7`
-
- - v\ :sub:`6`
-
- - v\ :sub:`5`
-
- - v\ :sub:`4`
-
- - v\ :sub:`3`
-
- - v\ :sub:`2`
-
- - v\ :sub:`1`
-
- - v\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-YVYU10-2X10:
-
- - MEDIA_BUS_FMT_YVYU10_2X10
-
- - 0x200c
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`9`
-
- - y\ :sub:`8`
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. row 60
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - v\ :sub:`9`
-
- - v\ :sub:`8`
-
- - v\ :sub:`7`
-
- - v\ :sub:`6`
-
- - v\ :sub:`5`
-
- - v\ :sub:`4`
-
- - v\ :sub:`3`
-
- - v\ :sub:`2`
-
- - v\ :sub:`1`
-
- - v\ :sub:`0`
-
- - .. row 61
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`9`
-
- - y\ :sub:`8`
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. row 62
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - u\ :sub:`9`
-
- - u\ :sub:`8`
-
- - u\ :sub:`7`
-
- - u\ :sub:`6`
-
- - u\ :sub:`5`
-
- - u\ :sub:`4`
-
- - u\ :sub:`3`
-
- - u\ :sub:`2`
-
- - u\ :sub:`1`
-
- - u\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-Y12-1X12:
-
- - MEDIA_BUS_FMT_Y12_1X12
-
- - 0x2013
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`11`
-
- - y\ :sub:`10`
-
- - y\ :sub:`9`
-
- - y\ :sub:`8`
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-UYVY12-2X12:
-
- - MEDIA_BUS_FMT_UYVY12_2X12
-
- - 0x201c
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - u\ :sub:`11`
-
- - u\ :sub:`10`
-
- - u\ :sub:`9`
-
- - u\ :sub:`8`
-
- - u\ :sub:`7`
-
- - u\ :sub:`6`
-
- - u\ :sub:`5`
-
- - u\ :sub:`4`
-
- - u\ :sub:`3`
-
- - u\ :sub:`2`
-
- - u\ :sub:`1`
-
- - u\ :sub:`0`
-
- - .. row 65
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`11`
-
- - y\ :sub:`10`
-
- - y\ :sub:`9`
-
- - y\ :sub:`8`
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. row 66
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - v\ :sub:`11`
-
- - v\ :sub:`10`
-
- - v\ :sub:`9`
-
- - v\ :sub:`8`
-
- - v\ :sub:`7`
-
- - v\ :sub:`6`
-
- - v\ :sub:`5`
-
- - v\ :sub:`4`
-
- - v\ :sub:`3`
-
- - v\ :sub:`2`
-
- - v\ :sub:`1`
-
- - v\ :sub:`0`
-
- - .. row 67
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`11`
-
- - y\ :sub:`10`
-
- - y\ :sub:`9`
-
- - y\ :sub:`8`
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-VYUY12-2X12:
-
- - MEDIA_BUS_FMT_VYUY12_2X12
-
- - 0x201d
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - v\ :sub:`11`
-
- - v\ :sub:`10`
-
- - v\ :sub:`9`
-
- - v\ :sub:`8`
-
- - v\ :sub:`7`
-
- - v\ :sub:`6`
-
- - v\ :sub:`5`
-
- - v\ :sub:`4`
-
- - v\ :sub:`3`
-
- - v\ :sub:`2`
-
- - v\ :sub:`1`
-
- - v\ :sub:`0`
-
- - .. row 69
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`11`
-
- - y\ :sub:`10`
-
- - y\ :sub:`9`
-
- - y\ :sub:`8`
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. row 70
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - u\ :sub:`11`
-
- - u\ :sub:`10`
-
- - u\ :sub:`9`
-
- - u\ :sub:`8`
-
- - u\ :sub:`7`
-
- - u\ :sub:`6`
-
- - u\ :sub:`5`
-
- - u\ :sub:`4`
-
- - u\ :sub:`3`
-
- - u\ :sub:`2`
-
- - u\ :sub:`1`
-
- - u\ :sub:`0`
-
- - .. row 71
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`11`
-
- - y\ :sub:`10`
-
- - y\ :sub:`9`
-
- - y\ :sub:`8`
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-YUYV12-2X12:
-
- - MEDIA_BUS_FMT_YUYV12_2X12
-
- - 0x201e
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`11`
-
- - y\ :sub:`10`
-
- - y\ :sub:`9`
-
- - y\ :sub:`8`
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. row 73
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - u\ :sub:`11`
-
- - u\ :sub:`10`
-
- - u\ :sub:`9`
-
- - u\ :sub:`8`
-
- - u\ :sub:`7`
-
- - u\ :sub:`6`
-
- - u\ :sub:`5`
-
- - u\ :sub:`4`
-
- - u\ :sub:`3`
-
- - u\ :sub:`2`
-
- - u\ :sub:`1`
-
- - u\ :sub:`0`
-
- - .. row 74
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`11`
-
- - y\ :sub:`10`
-
- - y\ :sub:`9`
-
- - y\ :sub:`8`
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. row 75
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - v\ :sub:`11`
-
- - v\ :sub:`10`
-
- - v\ :sub:`9`
-
- - v\ :sub:`8`
-
- - v\ :sub:`7`
-
- - v\ :sub:`6`
-
- - v\ :sub:`5`
-
- - v\ :sub:`4`
-
- - v\ :sub:`3`
-
- - v\ :sub:`2`
-
- - v\ :sub:`1`
-
- - v\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-YVYU12-2X12:
-
- - MEDIA_BUS_FMT_YVYU12_2X12
-
- - 0x201f
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`11`
-
- - y\ :sub:`10`
-
- - y\ :sub:`9`
-
- - y\ :sub:`8`
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. row 77
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - v\ :sub:`11`
-
- - v\ :sub:`10`
-
- - v\ :sub:`9`
-
- - v\ :sub:`8`
-
- - v\ :sub:`7`
-
- - v\ :sub:`6`
-
- - v\ :sub:`5`
-
- - v\ :sub:`4`
-
- - v\ :sub:`3`
-
- - v\ :sub:`2`
-
- - v\ :sub:`1`
-
- - v\ :sub:`0`
-
- - .. row 78
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`11`
-
- - y\ :sub:`10`
-
- - y\ :sub:`9`
-
- - y\ :sub:`8`
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. row 79
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - u\ :sub:`11`
-
- - u\ :sub:`10`
-
- - u\ :sub:`9`
-
- - u\ :sub:`8`
-
- - u\ :sub:`7`
-
- - u\ :sub:`6`
-
- - u\ :sub:`5`
-
- - u\ :sub:`4`
-
- - u\ :sub:`3`
-
- - u\ :sub:`2`
-
- - u\ :sub:`1`
-
- - u\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-UYVY8-1X16:
-
- - MEDIA_BUS_FMT_UYVY8_1X16
-
- - 0x200f
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - u\ :sub:`7`
-
- - u\ :sub:`6`
-
- - u\ :sub:`5`
-
- - u\ :sub:`4`
-
- - u\ :sub:`3`
-
- - u\ :sub:`2`
-
- - u\ :sub:`1`
-
- - u\ :sub:`0`
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. row 81
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - v\ :sub:`7`
-
- - v\ :sub:`6`
-
- - v\ :sub:`5`
-
- - v\ :sub:`4`
-
- - v\ :sub:`3`
-
- - v\ :sub:`2`
-
- - v\ :sub:`1`
-
- - v\ :sub:`0`
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-VYUY8-1X16:
-
- - MEDIA_BUS_FMT_VYUY8_1X16
-
- - 0x2010
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - v\ :sub:`7`
-
- - v\ :sub:`6`
-
- - v\ :sub:`5`
-
- - v\ :sub:`4`
-
- - v\ :sub:`3`
-
- - v\ :sub:`2`
-
- - v\ :sub:`1`
-
- - v\ :sub:`0`
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. row 83
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - u\ :sub:`7`
-
- - u\ :sub:`6`
-
- - u\ :sub:`5`
-
- - u\ :sub:`4`
-
- - u\ :sub:`3`
-
- - u\ :sub:`2`
-
- - u\ :sub:`1`
-
- - u\ :sub:`0`
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-YUYV8-1X16:
-
- - MEDIA_BUS_FMT_YUYV8_1X16
-
- - 0x2011
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - u\ :sub:`7`
-
- - u\ :sub:`6`
-
- - u\ :sub:`5`
-
- - u\ :sub:`4`
-
- - u\ :sub:`3`
-
- - u\ :sub:`2`
-
- - u\ :sub:`1`
-
- - u\ :sub:`0`
-
- - .. row 85
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - v\ :sub:`7`
-
- - v\ :sub:`6`
-
- - v\ :sub:`5`
-
- - v\ :sub:`4`
-
- - v\ :sub:`3`
-
- - v\ :sub:`2`
-
- - v\ :sub:`1`
-
- - v\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-YVYU8-1X16:
-
- - MEDIA_BUS_FMT_YVYU8_1X16
-
- - 0x2012
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - v\ :sub:`7`
-
- - v\ :sub:`6`
-
- - v\ :sub:`5`
-
- - v\ :sub:`4`
-
- - v\ :sub:`3`
-
- - v\ :sub:`2`
-
- - v\ :sub:`1`
-
- - v\ :sub:`0`
-
- - .. row 87
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - u\ :sub:`7`
-
- - u\ :sub:`6`
-
- - u\ :sub:`5`
-
- - u\ :sub:`4`
-
- - u\ :sub:`3`
-
- - u\ :sub:`2`
-
- - u\ :sub:`1`
-
- - u\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-YDYUYDYV8-1X16:
-
- - MEDIA_BUS_FMT_YDYUYDYV8_1X16
-
- - 0x2014
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - d
-
- - d
-
- - d
-
- - d
-
- - d
-
- - d
-
- - d
-
- - d
-
- - .. row 89
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - u\ :sub:`7`
-
- - u\ :sub:`6`
-
- - u\ :sub:`5`
-
- - u\ :sub:`4`
-
- - u\ :sub:`3`
-
- - u\ :sub:`2`
-
- - u\ :sub:`1`
-
- - u\ :sub:`0`
-
- - .. row 90
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - d
-
- - d
-
- - d
-
- - d
-
- - d
-
- - d
-
- - d
-
- - d
-
- - .. row 91
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - v\ :sub:`7`
-
- - v\ :sub:`6`
-
- - v\ :sub:`5`
-
- - v\ :sub:`4`
-
- - v\ :sub:`3`
-
- - v\ :sub:`2`
-
- - v\ :sub:`1`
-
- - v\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-UYVY10-1X20:
-
- - MEDIA_BUS_FMT_UYVY10_1X20
-
- - 0x201a
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - u\ :sub:`9`
-
- - u\ :sub:`8`
-
- - u\ :sub:`7`
-
- - u\ :sub:`6`
-
- - u\ :sub:`5`
-
- - u\ :sub:`4`
-
- - u\ :sub:`3`
-
- - u\ :sub:`2`
-
- - u\ :sub:`1`
-
- - u\ :sub:`0`
-
- - y\ :sub:`9`
-
- - y\ :sub:`8`
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. row 93
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - v\ :sub:`9`
-
- - v\ :sub:`8`
-
- - v\ :sub:`7`
-
- - v\ :sub:`6`
-
- - v\ :sub:`5`
-
- - v\ :sub:`4`
-
- - v\ :sub:`3`
-
- - v\ :sub:`2`
-
- - v\ :sub:`1`
-
- - v\ :sub:`0`
-
- - y\ :sub:`9`
-
- - y\ :sub:`8`
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-VYUY10-1X20:
-
- - MEDIA_BUS_FMT_VYUY10_1X20
-
- - 0x201b
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - v\ :sub:`9`
-
- - v\ :sub:`8`
-
- - v\ :sub:`7`
-
- - v\ :sub:`6`
-
- - v\ :sub:`5`
-
- - v\ :sub:`4`
-
- - v\ :sub:`3`
-
- - v\ :sub:`2`
-
- - v\ :sub:`1`
-
- - v\ :sub:`0`
-
- - y\ :sub:`9`
-
- - y\ :sub:`8`
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. row 95
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - u\ :sub:`9`
-
- - u\ :sub:`8`
-
- - u\ :sub:`7`
-
- - u\ :sub:`6`
-
- - u\ :sub:`5`
-
- - u\ :sub:`4`
-
- - u\ :sub:`3`
-
- - u\ :sub:`2`
-
- - u\ :sub:`1`
-
- - u\ :sub:`0`
-
- - y\ :sub:`9`
-
- - y\ :sub:`8`
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-YUYV10-1X20:
-
- - MEDIA_BUS_FMT_YUYV10_1X20
-
- - 0x200d
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`9`
-
- - y\ :sub:`8`
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - u\ :sub:`9`
-
- - u\ :sub:`8`
-
- - u\ :sub:`7`
-
- - u\ :sub:`6`
-
- - u\ :sub:`5`
-
- - u\ :sub:`4`
-
- - u\ :sub:`3`
-
- - u\ :sub:`2`
-
- - u\ :sub:`1`
-
- - u\ :sub:`0`
-
- - .. row 97
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`9`
-
- - y\ :sub:`8`
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - v\ :sub:`9`
-
- - v\ :sub:`8`
-
- - v\ :sub:`7`
-
- - v\ :sub:`6`
-
- - v\ :sub:`5`
-
- - v\ :sub:`4`
-
- - v\ :sub:`3`
-
- - v\ :sub:`2`
-
- - v\ :sub:`1`
-
- - v\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-YVYU10-1X20:
-
- - MEDIA_BUS_FMT_YVYU10_1X20
-
- - 0x200e
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`9`
-
- - y\ :sub:`8`
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - v\ :sub:`9`
-
- - v\ :sub:`8`
-
- - v\ :sub:`7`
-
- - v\ :sub:`6`
-
- - v\ :sub:`5`
-
- - v\ :sub:`4`
-
- - v\ :sub:`3`
-
- - v\ :sub:`2`
-
- - v\ :sub:`1`
-
- - v\ :sub:`0`
-
- - .. row 99
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`9`
-
- - y\ :sub:`8`
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - u\ :sub:`9`
-
- - u\ :sub:`8`
-
- - u\ :sub:`7`
-
- - u\ :sub:`6`
-
- - u\ :sub:`5`
-
- - u\ :sub:`4`
-
- - u\ :sub:`3`
-
- - u\ :sub:`2`
-
- - u\ :sub:`1`
-
- - u\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-VUY8-1X24:
-
- - MEDIA_BUS_FMT_VUY8_1X24
-
- - 0x201a
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - v\ :sub:`7`
-
- - v\ :sub:`6`
-
- - v\ :sub:`5`
-
- - v\ :sub:`4`
-
- - v\ :sub:`3`
-
- - v\ :sub:`2`
-
- - v\ :sub:`1`
-
- - v\ :sub:`0`
-
- - u\ :sub:`7`
-
- - u\ :sub:`6`
-
- - u\ :sub:`5`
-
- - u\ :sub:`4`
-
- - u\ :sub:`3`
-
- - u\ :sub:`2`
-
- - u\ :sub:`1`
-
- - u\ :sub:`0`
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-YUV8-1X24:
-
- - MEDIA_BUS_FMT_YUV8_1X24
-
- - 0x2025
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - u\ :sub:`7`
-
- - u\ :sub:`6`
-
- - u\ :sub:`5`
-
- - u\ :sub:`4`
-
- - u\ :sub:`3`
-
- - u\ :sub:`2`
-
- - u\ :sub:`1`
-
- - u\ :sub:`0`
-
- - v\ :sub:`7`
-
- - v\ :sub:`6`
-
- - v\ :sub:`5`
-
- - v\ :sub:`4`
-
- - v\ :sub:`3`
-
- - v\ :sub:`2`
-
- - v\ :sub:`1`
-
- - v\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-UYVY12-1X24:
-
- - MEDIA_BUS_FMT_UYVY12_1X24
-
- - 0x2020
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - u\ :sub:`11`
-
- - u\ :sub:`10`
-
- - u\ :sub:`9`
-
- - u\ :sub:`8`
-
- - u\ :sub:`7`
-
- - u\ :sub:`6`
-
- - u\ :sub:`5`
-
- - u\ :sub:`4`
-
- - u\ :sub:`3`
-
- - u\ :sub:`2`
-
- - u\ :sub:`1`
-
- - u\ :sub:`0`
-
- - y\ :sub:`11`
-
- - y\ :sub:`10`
-
- - y\ :sub:`9`
-
- - y\ :sub:`8`
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. row 103
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - v\ :sub:`11`
-
- - v\ :sub:`10`
-
- - v\ :sub:`9`
-
- - v\ :sub:`8`
-
- - v\ :sub:`7`
-
- - v\ :sub:`6`
-
- - v\ :sub:`5`
-
- - v\ :sub:`4`
-
- - v\ :sub:`3`
-
- - v\ :sub:`2`
-
- - v\ :sub:`1`
-
- - v\ :sub:`0`
-
- - y\ :sub:`11`
-
- - y\ :sub:`10`
-
- - y\ :sub:`9`
-
- - y\ :sub:`8`
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-VYUY12-1X24:
-
- - MEDIA_BUS_FMT_VYUY12_1X24
-
- - 0x2021
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - v\ :sub:`11`
-
- - v\ :sub:`10`
-
- - v\ :sub:`9`
-
- - v\ :sub:`8`
-
- - v\ :sub:`7`
-
- - v\ :sub:`6`
-
- - v\ :sub:`5`
-
- - v\ :sub:`4`
-
- - v\ :sub:`3`
-
- - v\ :sub:`2`
-
- - v\ :sub:`1`
-
- - v\ :sub:`0`
-
- - y\ :sub:`11`
-
- - y\ :sub:`10`
-
- - y\ :sub:`9`
-
- - y\ :sub:`8`
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. row 105
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - u\ :sub:`11`
-
- - u\ :sub:`10`
-
- - u\ :sub:`9`
-
- - u\ :sub:`8`
-
- - u\ :sub:`7`
-
- - u\ :sub:`6`
-
- - u\ :sub:`5`
-
- - u\ :sub:`4`
-
- - u\ :sub:`3`
-
- - u\ :sub:`2`
-
- - u\ :sub:`1`
-
- - u\ :sub:`0`
-
- - y\ :sub:`11`
-
- - y\ :sub:`10`
-
- - y\ :sub:`9`
-
- - y\ :sub:`8`
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-YUYV12-1X24:
-
- - MEDIA_BUS_FMT_YUYV12_1X24
-
- - 0x2022
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`11`
-
- - y\ :sub:`10`
-
- - y\ :sub:`9`
-
- - y\ :sub:`8`
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - u\ :sub:`11`
-
- - u\ :sub:`10`
-
- - u\ :sub:`9`
-
- - u\ :sub:`8`
-
- - u\ :sub:`7`
-
- - u\ :sub:`6`
-
- - u\ :sub:`5`
-
- - u\ :sub:`4`
-
- - u\ :sub:`3`
-
- - u\ :sub:`2`
-
- - u\ :sub:`1`
-
- - u\ :sub:`0`
-
- - .. row 107
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`11`
-
- - y\ :sub:`10`
-
- - y\ :sub:`9`
-
- - y\ :sub:`8`
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - v\ :sub:`11`
-
- - v\ :sub:`10`
-
- - v\ :sub:`9`
-
- - v\ :sub:`8`
-
- - v\ :sub:`7`
-
- - v\ :sub:`6`
-
- - v\ :sub:`5`
-
- - v\ :sub:`4`
-
- - v\ :sub:`3`
-
- - v\ :sub:`2`
-
- - v\ :sub:`1`
-
- - v\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-YVYU12-1X24:
-
- - MEDIA_BUS_FMT_YVYU12_1X24
-
- - 0x2023
-
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`11`
-
- - y\ :sub:`10`
-
- - y\ :sub:`9`
-
- - y\ :sub:`8`
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - v\ :sub:`11`
-
- - v\ :sub:`10`
-
- - v\ :sub:`9`
-
- - v\ :sub:`8`
-
- - v\ :sub:`7`
-
- - v\ :sub:`6`
-
- - v\ :sub:`5`
-
- - v\ :sub:`4`
-
- - v\ :sub:`3`
-
- - v\ :sub:`2`
-
- - v\ :sub:`1`
-
- - v\ :sub:`0`
-
- - .. row 109
-
- -
- -
- -
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - -
-
- - y\ :sub:`11`
-
- - y\ :sub:`10`
-
- - y\ :sub:`9`
-
- - y\ :sub:`8`
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - u\ :sub:`11`
-
- - u\ :sub:`10`
-
- - u\ :sub:`9`
-
- - u\ :sub:`8`
-
- - u\ :sub:`7`
-
- - u\ :sub:`6`
-
- - u\ :sub:`5`
-
- - u\ :sub:`4`
-
- - u\ :sub:`3`
-
- - u\ :sub:`2`
-
- - u\ :sub:`1`
-
- - u\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-YUV10-1X30:
-
- - MEDIA_BUS_FMT_YUV10_1X30
-
- - 0x2016
-
- -
- - -
-
- - -
-
- - y\ :sub:`9`
-
- - y\ :sub:`8`
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - u\ :sub:`9`
-
- - u\ :sub:`8`
-
- - u\ :sub:`7`
-
- - u\ :sub:`6`
-
- - u\ :sub:`5`
-
- - u\ :sub:`4`
-
- - u\ :sub:`3`
-
- - u\ :sub:`2`
-
- - u\ :sub:`1`
-
- - u\ :sub:`0`
-
- - v\ :sub:`9`
-
- - v\ :sub:`8`
-
- - v\ :sub:`7`
-
- - v\ :sub:`6`
-
- - v\ :sub:`5`
-
- - v\ :sub:`4`
-
- - v\ :sub:`3`
-
- - v\ :sub:`2`
-
- - v\ :sub:`1`
-
- - v\ :sub:`0`
-
- - .. _MEDIA-BUS-FMT-AYUV8-1X32:
-
- - MEDIA_BUS_FMT_AYUV8_1X32
-
- - 0x2017
-
- -
- - a\ :sub:`7`
-
- - a\ :sub:`6`
-
- - a\ :sub:`5`
-
- - a\ :sub:`4`
-
- - a\ :sub:`3`
-
- - a\ :sub:`2`
-
- - a\ :sub:`1`
-
- - a\ :sub:`0`
-
- - y\ :sub:`7`
-
- - y\ :sub:`6`
-
- - y\ :sub:`5`
-
- - y\ :sub:`4`
-
- - y\ :sub:`3`
-
- - y\ :sub:`2`
-
- - y\ :sub:`1`
-
- - y\ :sub:`0`
-
- - u\ :sub:`7`
-
- - u\ :sub:`6`
-
- - u\ :sub:`5`
-
- - u\ :sub:`4`
-
- - u\ :sub:`3`
-
- - u\ :sub:`2`
-
- - u\ :sub:`1`
-
- - u\ :sub:`0`
-
- - v\ :sub:`7`
-
- - v\ :sub:`6`
-
- - v\ :sub:`5`
-
- - v\ :sub:`4`
-
- - v\ :sub:`3`
-
- - v\ :sub:`2`
-
- - v\ :sub:`1`
-
- - v\ :sub:`0`
-
-
-
-HSV/HSL Formats
-^^^^^^^^^^^^^^^
-
-Those formats transfer pixel data as RGB values in a
-cylindrical-coordinate system using Hue-Saturation-Value or
-Hue-Saturation-Lightness components. The format code is made of the
-following information.
-
-- The hue, saturation, value or lightness and optional alpha components
- order code, as encoded in a pixel sample. The only currently
- supported value is AHSV.
-
-- The number of bits per component, for each component. The values can
- be different for all components. The only currently supported value
- is 8888.
-
-- The number of bus samples per pixel. Pixels that are wider than the
- bus width must be transferred in multiple samples. The only currently
- supported value is 1.
-
-- The bus width.
-
-- For formats where the total number of bits per pixel is smaller than
- the number of bus samples per pixel times the bus width, a padding
- value stating if the bytes are padded in their most high order bits
- (PADHI) or low order bits (PADLO).
-
-- For formats where the number of bus samples per pixel is larger than
- 1, an endianness value stating if the pixel is transferred MSB first
- (BE) or LSB first (LE).
-
-The following table lists existing HSV/HSL formats.
-
-
-.. _v4l2-mbus-pixelcode-hsv:
-
-.. flat-table:: HSV/HSL formats
- :header-rows: 2
- :stub-columns: 0
-
-
- - .. row 1
-
- - Identifier
-
- - Code
-
- -
- - :cspan:`31` Data organization
-
- - .. row 2
-
- -
- -
- - Bit
-
- - 31
-
- - 30
-
- - 29
-
- - 28
-
- - 27
-
- - 26
-
- - 25
-
- - 24
-
- - 23
-
- - 22
-
- - 21
-
- - 20
-
- - 19
-
- - 18
-
- - 17
-
- - 16
-
- - 15
-
- - 14
-
- - 13
-
- - 12
-
- - 11
-
- - 10
-
- - 9
-
- - 8
-
- - 7
-
- - 6
-
- - 5
-
- - 4
-
- - 3
-
- - 2
-
- - 1
-
- - 0
-
- - .. _MEDIA-BUS-FMT-AHSV8888-1X32:
-
- - MEDIA_BUS_FMT_AHSV8888_1X32
-
- - 0x6001
-
- -
- - a\ :sub:`7`
-
- - a\ :sub:`6`
-
- - a\ :sub:`5`
-
- - a\ :sub:`4`
-
- - a\ :sub:`3`
-
- - a\ :sub:`2`
-
- - a\ :sub:`1`
-
- - a\ :sub:`0`
-
- - h\ :sub:`7`
-
- - h\ :sub:`6`
-
- - h\ :sub:`5`
-
- - h\ :sub:`4`
-
- - h\ :sub:`3`
-
- - h\ :sub:`2`
-
- - h\ :sub:`1`
-
- - h\ :sub:`0`
-
- - s\ :sub:`7`
-
- - s\ :sub:`6`
-
- - s\ :sub:`5`
-
- - s\ :sub:`4`
-
- - s\ :sub:`3`
-
- - s\ :sub:`2`
-
- - s\ :sub:`1`
-
- - s\ :sub:`0`
-
- - v\ :sub:`7`
-
- - v\ :sub:`6`
-
- - v\ :sub:`5`
-
- - v\ :sub:`4`
-
- - v\ :sub:`3`
-
- - v\ :sub:`2`
-
- - v\ :sub:`1`
-
- - v\ :sub:`0`
-
-
-
-JPEG Compressed Formats
-^^^^^^^^^^^^^^^^^^^^^^^
-
-Those data formats consist of an ordered sequence of 8-bit bytes
-obtained from JPEG compression process. Additionally to the ``_JPEG``
-postfix the format code is made of the following information.
-
-- The number of bus samples per entropy encoded byte.
-
-- The bus width.
-
-For instance, for a JPEG baseline process and an 8-bit bus width the
-format will be named ``MEDIA_BUS_FMT_JPEG_1X8``.
-
-The following table lists existing JPEG compressed formats.
-
-
-.. _v4l2-mbus-pixelcode-jpeg:
-
-.. flat-table:: JPEG Formats
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - Identifier
-
- - Code
-
- - Remarks
-
- - .. _MEDIA-BUS-FMT-JPEG-1X8:
-
- - MEDIA_BUS_FMT_JPEG_1X8
-
- - 0x4001
-
- - Besides of its usage for the parallel bus this format is
- recommended for transmission of JPEG data over MIPI CSI bus using
- the User Defined 8-bit Data types.
-
-
-
-.. _v4l2-mbus-vendor-spec-fmts:
-
-Vendor and Device Specific Formats
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This section lists complex data formats that are either vendor or device
-specific.
-
-The following table lists the existing vendor and device specific
-formats.
-
-
-.. _v4l2-mbus-pixelcode-vendor-specific:
-
-.. flat-table:: Vendor and device specific formats
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - Identifier
-
- - Code
-
- - Comments
-
- - .. _MEDIA-BUS-FMT-S5C-UYVY-JPEG-1X8:
-
- - MEDIA_BUS_FMT_S5C_UYVY_JPEG_1X8
-
- - 0x5001
-
- - Interleaved raw UYVY and JPEG image format with embedded meta-data
- used by Samsung S3C73MX camera sensors.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _tuner:
-
-*********************
-Tuners and Modulators
-*********************
-
-
-Tuners
-======
-
-Video input devices can have one or more tuners demodulating a RF
-signal. Each tuner is associated with one or more video inputs,
-depending on the number of RF connectors on the tuner. The ``type``
-field of the respective struct :ref:`v4l2_input <v4l2-input>`
-returned by the :ref:`VIDIOC_ENUMINPUT` ioctl is
-set to ``V4L2_INPUT_TYPE_TUNER`` and its ``tuner`` field contains the
-index number of the tuner.
-
-Radio input devices have exactly one tuner with index zero, no video
-inputs.
-
-To query and change tuner properties applications use the
-:ref:`VIDIOC_G_TUNER <VIDIOC_G_TUNER>` and
-:ref:`VIDIOC_S_TUNER <VIDIOC_G_TUNER>` ioctls, respectively. The
-struct :ref:`v4l2_tuner <v4l2-tuner>` returned by :ref:`VIDIOC_G_TUNER <VIDIOC_G_TUNER>`
-also contains signal status information applicable when the tuner of the
-current video or radio input is queried. Note that :ref:`VIDIOC_S_TUNER <VIDIOC_G_TUNER>`
-does not switch the current tuner, when there is more than one at all.
-The tuner is solely determined by the current video input. Drivers must
-support both ioctls and set the ``V4L2_CAP_TUNER`` flag in the struct
-:ref:`v4l2_capability <v4l2-capability>` returned by the
-:ref:`VIDIOC_QUERYCAP` ioctl when the device has
-one or more tuners.
-
-
-Modulators
-==========
-
-Video output devices can have one or more modulators, uh, modulating a
-video signal for radiation or connection to the antenna input of a TV
-set or video recorder. Each modulator is associated with one or more
-video outputs, depending on the number of RF connectors on the
-modulator. The ``type`` field of the respective struct
-:ref:`v4l2_output <v4l2-output>` returned by the
-:ref:`VIDIOC_ENUMOUTPUT` ioctl is set to
-``V4L2_OUTPUT_TYPE_MODULATOR`` and its ``modulator`` field contains the
-index number of the modulator.
-
-Radio output devices have exactly one modulator with index zero, no
-video outputs.
-
-A video or radio device cannot support both a tuner and a modulator. Two
-separate device nodes will have to be used for such hardware, one that
-supports the tuner functionality and one that supports the modulator
-functionality. The reason is a limitation with the
-:ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl where you
-cannot specify whether the frequency is for a tuner or a modulator.
-
-To query and change modulator properties applications use the
-:ref:`VIDIOC_G_MODULATOR <VIDIOC_G_MODULATOR>` and
-:ref:`VIDIOC_S_MODULATOR <VIDIOC_G_MODULATOR>` ioctl. Note that
-:ref:`VIDIOC_S_MODULATOR <VIDIOC_G_MODULATOR>` does not switch the current modulator, when there
-is more than one at all. The modulator is solely determined by the
-current video output. Drivers must support both ioctls and set the
-``V4L2_CAP_MODULATOR`` flag in the struct
-:ref:`v4l2_capability <v4l2-capability>` returned by the
-:ref:`VIDIOC_QUERYCAP` ioctl when the device has
-one or more modulators.
-
-
-Radio Frequency
-===============
-
-To get and set the tuner or modulator radio frequency applications use
-the :ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` and
-:ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl which both take
-a pointer to a struct :ref:`v4l2_frequency <v4l2-frequency>`. These
-ioctls are used for TV and radio devices alike. Drivers must support
-both ioctls when the tuner or modulator ioctls are supported, or when
-the device is a radio device.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _user-func:
-
-******************
-Function Reference
-******************
-
-
-.. toctree::
- :maxdepth: 1
-
- func-close
- func-ioctl
- vidioc-create-bufs
- vidioc-cropcap
- vidioc-dbg-g-chip-info
- vidioc-dbg-g-register
- vidioc-decoder-cmd
- vidioc-dqevent
- vidioc-dv-timings-cap
- vidioc-encoder-cmd
- vidioc-enumaudio
- vidioc-enumaudioout
- vidioc-enum-dv-timings
- vidioc-enum-fmt
- vidioc-enum-framesizes
- vidioc-enum-frameintervals
- vidioc-enum-freq-bands
- vidioc-enuminput
- vidioc-enumoutput
- vidioc-enumstd
- vidioc-expbuf
- vidioc-g-audio
- vidioc-g-audioout
- vidioc-g-crop
- vidioc-g-ctrl
- vidioc-g-dv-timings
- vidioc-g-edid
- vidioc-g-enc-index
- vidioc-g-ext-ctrls
- vidioc-g-fbuf
- vidioc-g-fmt
- vidioc-g-frequency
- vidioc-g-input
- vidioc-g-jpegcomp
- vidioc-g-modulator
- vidioc-g-output
- vidioc-g-parm
- vidioc-g-priority
- vidioc-g-selection
- vidioc-g-sliced-vbi-cap
- vidioc-g-std
- vidioc-g-tuner
- vidioc-log-status
- vidioc-overlay
- vidioc-prepare-buf
- vidioc-qbuf
- vidioc-querybuf
- vidioc-querycap
- vidioc-queryctrl
- vidioc-query-dv-timings
- vidioc-querystd
- vidioc-reqbufs
- vidioc-s-hw-freq-seek
- vidioc-streamon
- vidioc-subdev-enum-frame-interval
- vidioc-subdev-enum-frame-size
- vidioc-subdev-enum-mbus-code
- vidioc-subdev-g-crop
- vidioc-subdev-g-fmt
- vidioc-subdev-g-frame-interval
- vidioc-subdev-g-selection
- vidioc-subscribe-event
- func-mmap
- func-munmap
- func-open
- func-poll
- func-read
- func-select
- func-write
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _userp:
-
-*****************************
-Streaming I/O (User Pointers)
-*****************************
-
-Input and output devices support this I/O method when the
-``V4L2_CAP_STREAMING`` flag in the ``capabilities`` field of struct
-:ref:`v4l2_capability <v4l2-capability>` returned by the
-:ref:`VIDIOC_QUERYCAP` ioctl is set. If the
-particular user pointer method (not only memory mapping) is supported
-must be determined by calling the
-:ref:`VIDIOC_REQBUFS` ioctl.
-
-This I/O method combines advantages of the read/write and memory mapping
-methods. Buffers (planes) are allocated by the application itself, and
-can reside for example in virtual or shared memory. Only pointers to
-data are exchanged, these pointers and meta-information are passed in
-struct :ref:`v4l2_buffer <v4l2-buffer>` (or in struct
-:ref:`v4l2_plane <v4l2-plane>` in the multi-planar API case). The
-driver must be switched into user pointer I/O mode by calling the
-:ref:`VIDIOC_REQBUFS` with the desired buffer type.
-No buffers (planes) are allocated beforehand, consequently they are not
-indexed and cannot be queried like mapped buffers with the
-:ref:`VIDIOC_QUERYBUF <VIDIOC_QUERYBUF>` ioctl.
-
-
-.. code-block:: c
- :caption: Example 3.3. Initiating streaming I/O with user pointers
-
- struct v4l2_requestbuffers reqbuf;
-
- memset (&reqbuf, 0, sizeof (reqbuf));
- reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- reqbuf.memory = V4L2_MEMORY_USERPTR;
-
- if (ioctl (fd, VIDIOC_REQBUFS, &reqbuf) == -1) {
- if (errno == EINVAL)
- printf ("Video capturing or user pointer streaming is not supported\\n");
- else
- perror ("VIDIOC_REQBUFS");
-
- exit (EXIT_FAILURE);
- }
-
-Buffer (plane) addresses and sizes are passed on the fly with the
-:ref:`VIDIOC_QBUF <VIDIOC_QBUF>` ioctl. Although buffers are commonly
-cycled, applications can pass different addresses and sizes at each
-:ref:`VIDIOC_QBUF <VIDIOC_QBUF>` call. If required by the hardware the
-driver swaps memory pages within physical memory to create a continuous
-area of memory. This happens transparently to the application in the
-virtual memory subsystem of the kernel. When buffer pages have been
-swapped out to disk they are brought back and finally locked in physical
-memory for DMA. [1]_
-
-Filled or displayed buffers are dequeued with the
-:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. The driver can unlock the
-memory pages at any time between the completion of the DMA and this
-ioctl. The memory is also unlocked when
-:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` is called,
-:ref:`VIDIOC_REQBUFS`, or when the device is closed.
-Applications must take care not to free buffers without dequeuing. For
-once, the buffers remain locked until further, wasting physical memory.
-Second the driver will not be notified when the memory is returned to
-the application's free list and subsequently reused for other purposes,
-possibly completing the requested DMA and overwriting valuable data.
-
-For capturing applications it is customary to enqueue a number of empty
-buffers, to start capturing and enter the read loop. Here the
-application waits until a filled buffer can be dequeued, and re-enqueues
-the buffer when the data is no longer needed. Output applications fill
-and enqueue buffers, when enough buffers are stacked up output is
-started. In the write loop, when the application runs out of free
-buffers it must wait until an empty buffer can be dequeued and reused.
-Two methods exist to suspend execution of the application until one or
-more buffers can be dequeued. By default :ref:`VIDIOC_DQBUF
-<VIDIOC_QBUF>` blocks when no buffer is in the outgoing queue. When the
-``O_NONBLOCK`` flag was given to the :ref:`open() <func-open>` function,
-:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` returns immediately with an ``EAGAIN``
-error code when no buffer is available. The :ref:`select()
-<func-select>` or :ref:`poll() <func-poll>` function are always
-available.
-
-To start and stop capturing or output applications call the
-:ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and
-:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctl. Note
-:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` removes all buffers from both
-queues and unlocks all buffers as a side effect. Since there is no
-notion of doing anything "now" on a multitasking system, if an
-application needs to synchronize with another event it should examine
-the struct :ref:`v4l2_buffer <v4l2-buffer>` ``timestamp`` of captured or
-outputted buffers.
-
-Drivers implementing user pointer I/O must support the
-:ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`,
-:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`
-and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls, the
-:ref:`select() <func-select>` and :ref:`poll() <func-poll>` function. [2]_
-
-.. [1]
- We expect that frequently used buffers are typically not swapped out.
- Anyway, the process of swapping, locking or generating scatter-gather
- lists may be time consuming. The delay can be masked by the depth of
- the incoming buffer queue, and perhaps by maintaining caches assuming
- a buffer will be soon enqueued again. On the other hand, to optimize
- memory usage drivers can limit the number of buffers locked in
- advance and recycle the most recently used buffers first. Of course,
- the pages of empty buffers in the incoming queue need not be saved to
- disk. Output buffers must be saved on the incoming and outgoing queue
- because an application may share them with other processes.
-
-.. [2]
- At the driver level :ref:`select() <func-select>` and :ref:`poll() <func-poll>` are
- the same, and :ref:`select() <func-select>` is too important to be optional.
- The rest should be evident.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _v4l2-selection-flags:
-
-***************
-Selection flags
-***************
-
-
-.. _v4l2-selection-flags-table:
-
-.. flat-table:: Selection flag definitions
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - Flag name
-
- - id
-
- - Definition
-
- - Valid for V4L2
-
- - Valid for V4L2 subdev
-
- - .. row 2
-
- - ``V4L2_SEL_FLAG_GE``
-
- - (1 << 0)
-
- - Suggest the driver it should choose greater or equal rectangle (in
- size) than was requested. Albeit the driver may choose a lesser
- size, it will only do so due to hardware limitations. Without this
- flag (and ``V4L2_SEL_FLAG_LE``) the behaviour is to choose the
- closest possible rectangle.
-
- - Yes
-
- - Yes
-
- - .. row 3
-
- - ``V4L2_SEL_FLAG_LE``
-
- - (1 << 1)
-
- - Suggest the driver it should choose lesser or equal rectangle (in
- size) than was requested. Albeit the driver may choose a greater
- size, it will only do so due to hardware limitations.
-
- - Yes
-
- - Yes
-
- - .. row 4
-
- - ``V4L2_SEL_FLAG_KEEP_CONFIG``
-
- - (1 << 2)
-
- - The configuration must not be propagated to any further processing
- steps. If this flag is not given, the configuration is propagated
- inside the subdevice to all further processing steps.
-
- - No
-
- - Yes
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _v4l2-selection-targets:
-
-*****************
-Selection targets
-*****************
-
-The precise meaning of the selection targets may be dependent on which
-of the two interfaces they are used.
-
-
-.. _v4l2-selection-targets-table:
-
-.. flat-table:: Selection target definitions
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - Target name
-
- - id
-
- - Definition
-
- - Valid for V4L2
-
- - Valid for V4L2 subdev
-
- - .. row 2
-
- - ``V4L2_SEL_TGT_CROP``
-
- - 0x0000
-
- - Crop rectangle. Defines the cropped area.
-
- - Yes
-
- - Yes
-
- - .. row 3
-
- - ``V4L2_SEL_TGT_CROP_DEFAULT``
-
- - 0x0001
-
- - Suggested cropping rectangle that covers the "whole picture".
-
- - Yes
-
- - No
-
- - .. row 4
-
- - ``V4L2_SEL_TGT_CROP_BOUNDS``
-
- - 0x0002
-
- - Bounds of the crop rectangle. All valid crop rectangles fit inside
- the crop bounds rectangle.
-
- - Yes
-
- - Yes
-
- - .. row 5
-
- - ``V4L2_SEL_TGT_NATIVE_SIZE``
-
- - 0x0003
-
- - The native size of the device, e.g. a sensor's pixel array.
- ``left`` and ``top`` fields are zero for this target. Setting the
- native size will generally only make sense for memory to memory
- devices where the software can create a canvas of a given size in
- which for example a video frame can be composed. In that case
- V4L2_SEL_TGT_NATIVE_SIZE can be used to configure the size of
- that canvas.
-
- - Yes
-
- - Yes
-
- - .. row 6
-
- - ``V4L2_SEL_TGT_COMPOSE``
-
- - 0x0100
-
- - Compose rectangle. Used to configure scaling and composition.
-
- - Yes
-
- - Yes
-
- - .. row 7
-
- - ``V4L2_SEL_TGT_COMPOSE_DEFAULT``
-
- - 0x0101
-
- - Suggested composition rectangle that covers the "whole picture".
-
- - Yes
-
- - No
-
- - .. row 8
-
- - ``V4L2_SEL_TGT_COMPOSE_BOUNDS``
-
- - 0x0102
-
- - Bounds of the compose rectangle. All valid compose rectangles fit
- inside the compose bounds rectangle.
-
- - Yes
-
- - Yes
-
- - .. row 9
-
- - ``V4L2_SEL_TGT_COMPOSE_PADDED``
-
- - 0x0103
-
- - The active area and all padding pixels that are inserted or
- modified by hardware.
-
- - Yes
-
- - No
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. include:: <isonum.txt>
-.. _v4l2spec:
-
-###################
-Video for Linux API
-###################
-
-This part describes the Video for Linux API version 2 (V4L2 API) specification.
-
-**Revision 4.5**
-
-.. toctree::
- :numbered:
- :maxdepth: 1
- :caption: Table of Contents
-
- common
- pixfmt
- io
- devices
- driver
- libv4l
- compat
- user-func
- common-defs
- videodev
- capture-example
- v4l2grab-example
- biblio
-
-
-**********************
-Revision and Copyright
-**********************
-
-Authors, in alphabetical order:
-
-- Ailus, Sakari <sakari.ailus@iki.fi>
-
- - Subdev selections API.
-
-- Carvalho Chehab, Mauro <m.chehab@kernel.org>
-
- - Documented libv4l, designed and added v4l2grab example, Remote Controller chapter.
-
-- Dirks, Bill
-
- - Original author of the V4L2 API and documentation.
-
-- H Schimek, Michael <mschimek@gmx.at>
-
- - Original author of the V4L2 API and documentation.
-
-- Karicheri, Muralidharan <m-karicheri2@ti.com>
-
- - Documented the Digital Video timings API.
-
-- Osciak, Pawel <pawel@osciak.com>
-
- - Designed and documented the multi-planar API.
-
-- Palosaari, Antti <crope@iki.fi>
-
- - SDR API.
-
-- Rubli, Martin
-
- - Designed and documented the VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS ioctls.
-
-- Walls, Andy <awalls@md.metrocast.net>
-
- - Documented the fielded V4L2_MPEG_STREAM_VBI_FMT_IVTV MPEG stream embedded, sliced VBI data format in this specification.
-
-- Verkuil, Hans <hverkuil@xs4all.nl>
-
- - Designed and documented the VIDIOC_LOG_STATUS ioctl, the extended control ioctls, major parts of the sliced VBI API, the MPEG encoder and decoder APIs and the DV Timings API.
-
-**Copyright** |copy| 1999-2016: Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab, Pawel Osciak, Sakari Ailus & Antti Palosaari.
-
-Except when explicitly stated as GPL, programming examples within this
-part can be used and distributed without restrictions.
-
-****************
-Revision History
-****************
-
-:revision: 4.5 / 2015-10-29 (*rr*)
-
-Extend VIDIOC_G_EXT_CTRLS;. Replace ctrl_class with a new union with
-ctrl_class and which. Which is used to select the current value of the
-control or the default value.
-
-
-:revision: 4.4 / 2015-05-26 (*ap*)
-
-Renamed V4L2_TUNER_ADC to V4L2_TUNER_SDR. Added
-V4L2_CID_RF_TUNER_RF_GAIN control. Added transmitter support for
-Software Defined Radio (SDR) Interface.
-
-
-:revision: 4.1 / 2015-02-13 (*mcc*)
-
-Fix documentation for media controller device nodes and add support for
-DVB device nodes. Add support for Tuner sub-device.
-
-
-:revision: 3.19 / 2014-12-05 (*hv*)
-
-Rewrote Colorspace chapter, added new enum
-:ref:`v4l2_ycbcr_encoding <v4l2-ycbcr-encoding>` and enum
-:ref:`v4l2_quantization <v4l2-quantization>` fields to struct
-:ref:`v4l2_pix_format <v4l2-pix-format>`, struct
-:ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` and struct
-:ref:`v4l2_mbus_framefmt <v4l2-mbus-framefmt>`.
-
-
-:revision: 3.17 / 2014-08-04 (*lp, hv*)
-
-Extended struct :ref:`v4l2_pix_format <v4l2-pix-format>`. Added
-format flags. Added compound control types and VIDIOC_QUERY_EXT_CTRL.
-
-
-:revision: 3.15 / 2014-02-03 (*hv, ap*)
-
-Update several sections of "Common API Elements": "Opening and Closing
-Devices" "Querying Capabilities", "Application Priority", "Video Inputs
-and Outputs", "Audio Inputs and Outputs" "Tuners and Modulators", "Video
-Standards" and "Digital Video (DV) Timings". Added SDR API.
-
-
-:revision: 3.14 / 2013-11-25 (*rr*)
-
-Set width and height as unsigned on v4l2_rect.
-
-
-:revision: 3.11 / 2013-05-26 (*hv*)
-
-Remove obsolete VIDIOC_DBG_G_CHIP_IDENT ioctl.
-
-
-:revision: 3.10 / 2013-03-25 (*hv*)
-
-Remove obsolete and unused DV_PRESET ioctls: VIDIOC_G_DV_PRESET,
-VIDIOC_S_DV_PRESET, VIDIOC_QUERY_DV_PRESET and
-VIDIOC_ENUM_DV_PRESET. Remove the related v4l2_input/output
-capability flags V4L2_IN_CAP_PRESETS and V4L2_OUT_CAP_PRESETS.
-Added VIDIOC_DBG_G_CHIP_INFO.
-
-
-:revision: 3.9 / 2012-12-03 (*sa, sn*)
-
-Added timestamp types to v4l2_buffer. Added
-V4L2_EVENT_CTRL_CH_RANGE control event changes flag.
-
-
-:revision: 3.6 / 2012-07-02 (*hv*)
-
-Added VIDIOC_ENUM_FREQ_BANDS.
-
-
-:revision: 3.5 / 2012-05-07 (*sa, sn, hv*)
-
-Added V4L2_CTRL_TYPE_INTEGER_MENU and V4L2 subdev selections API.
-Improved the description of V4L2_CID_COLORFX control, added
-V4L2_CID_COLORFX_CBCR control. Added camera controls
-V4L2_CID_AUTO_EXPOSURE_BIAS,
-V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE,
-V4L2_CID_IMAGE_STABILIZATION, V4L2_CID_ISO_SENSITIVITY,
-V4L2_CID_ISO_SENSITIVITY_AUTO, V4L2_CID_EXPOSURE_METERING,
-V4L2_CID_SCENE_MODE, V4L2_CID_3A_LOCK,
-V4L2_CID_AUTO_FOCUS_START, V4L2_CID_AUTO_FOCUS_STOP,
-V4L2_CID_AUTO_FOCUS_STATUS and V4L2_CID_AUTO_FOCUS_RANGE. Added
-VIDIOC_ENUM_DV_TIMINGS, VIDIOC_QUERY_DV_TIMINGS and
-VIDIOC_DV_TIMINGS_CAP.
-
-
-:revision: 3.4 / 2012-01-25 (*sn*)
-
-Added :ref:`JPEG compression control class. <jpeg-controls>`
-
-
-:revision: 3.3 / 2012-01-11 (*hv*)
-
-Added device_caps field to struct v4l2_capabilities.
-
-
-:revision: 3.2 / 2011-08-26 (*hv*)
-
-Added V4L2_CTRL_FLAG_VOLATILE.
-
-
-:revision: 3.1 / 2011-06-27 (*mcc, po, hv*)
-
-Documented that VIDIOC_QUERYCAP now returns a per-subsystem version
-instead of a per-driver one. Standardize an error code for invalid
-ioctl. Added V4L2_CTRL_TYPE_BITMASK.
-
-
-:revision: 2.6.39 / 2011-03-01 (*mcc, po*)
-
-Removed VIDIOC_*_OLD from videodev2.h header and update it to reflect
-latest changes. Added the :ref:`multi-planar API <planar-apis>`.
-
-
-:revision: 2.6.37 / 2010-08-06 (*hv*)
-
-Removed obsolete vtx (videotext) API.
-
-
-:revision: 2.6.33 / 2009-12-03 (*mk*)
-
-Added documentation for the Digital Video timings API.
-
-
-:revision: 2.6.32 / 2009-08-31 (*mcc*)
-
-Now, revisions will match the kernel version where the V4L2 API changes
-will be used by the Linux Kernel. Also added Remote Controller chapter.
-
-
-:revision: 0.29 / 2009-08-26 (*ev*)
-
-Added documentation for string controls and for FM Transmitter controls.
-
-
-:revision: 0.28 / 2009-08-26 (*gl*)
-
-Added V4L2_CID_BAND_STOP_FILTER documentation.
-
-
-:revision: 0.27 / 2009-08-15 (*mcc*)
-
-Added libv4l and Remote Controller documentation; added v4l2grab and
-keytable application examples.
-
-
-:revision: 0.26 / 2009-07-23 (*hv*)
-
-Finalized the RDS capture API. Added modulator and RDS encoder
-capabilities. Added support for string controls.
-
-
-:revision: 0.25 / 2009-01-18 (*hv*)
-
-Added pixel formats VYUY, NV16 and NV61, and changed the debug ioctls
-VIDIOC_DBG_G/S_REGISTER and VIDIOC_DBG_G_CHIP_IDENT. Added camera
-controls V4L2_CID_ZOOM_ABSOLUTE, V4L2_CID_ZOOM_RELATIVE,
-V4L2_CID_ZOOM_CONTINUOUS and V4L2_CID_PRIVACY.
-
-
-:revision: 0.24 / 2008-03-04 (*mhs*)
-
-Added pixel formats Y16 and SBGGR16, new controls and a camera controls
-class. Removed VIDIOC_G/S_MPEGCOMP.
-
-
-:revision: 0.23 / 2007-08-30 (*mhs*)
-
-Fixed a typo in VIDIOC_DBG_G/S_REGISTER. Clarified the byte order of
-packed pixel formats.
-
-
-:revision: 0.22 / 2007-08-29 (*mhs*)
-
-Added the Video Output Overlay interface, new MPEG controls,
-V4L2_FIELD_INTERLACED_TB and V4L2_FIELD_INTERLACED_BT,
-VIDIOC_DBG_G/S_REGISTER, VIDIOC\_(TRY\_)ENCODER_CMD,
-VIDIOC_G_CHIP_IDENT, VIDIOC_G_ENC_INDEX, new pixel formats.
-Clarifications in the cropping chapter, about RGB pixel formats, the
-mmap(), poll(), select(), read() and write() functions. Typographical
-fixes.
-
-
-:revision: 0.21 / 2006-12-19 (*mhs*)
-
-Fixed a link in the VIDIOC_G_EXT_CTRLS section.
-
-
-:revision: 0.20 / 2006-11-24 (*mhs*)
-
-Clarified the purpose of the audioset field in struct v4l2_input and
-v4l2_output.
-
-
-:revision: 0.19 / 2006-10-19 (*mhs*)
-
-Documented V4L2_PIX_FMT_RGB444.
-
-
-:revision: 0.18 / 2006-10-18 (*mhs*)
-
-Added the description of extended controls by Hans Verkuil. Linked
-V4L2_PIX_FMT_MPEG to V4L2_CID_MPEG_STREAM_TYPE.
-
-
-:revision: 0.17 / 2006-10-12 (*mhs*)
-
-Corrected V4L2_PIX_FMT_HM12 description.
-
-
-:revision: 0.16 / 2006-10-08 (*mhs*)
-
-VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS are now part
-of the API.
-
-
-:revision: 0.15 / 2006-09-23 (*mhs*)
-
-Cleaned up the bibliography, added BT.653 and BT.1119.
-capture.c/start_capturing() for user pointer I/O did not initialize the
-buffer index. Documented the V4L MPEG and MJPEG VID_TYPEs and
-V4L2_PIX_FMT_SBGGR8. Updated the list of reserved pixel formats. See
-the history chapter for API changes.
-
-
-:revision: 0.14 / 2006-09-14 (*mr*)
-
-Added VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS proposal
-for frame format enumeration of digital devices.
-
-
-:revision: 0.13 / 2006-04-07 (*mhs*)
-
-Corrected the description of struct v4l2_window clips. New V4L2_STD\_
-and V4L2_TUNER_MODE_LANG1_LANG2 defines.
-
-
-:revision: 0.12 / 2006-02-03 (*mhs*)
-
-Corrected the description of struct v4l2_captureparm and
-v4l2_outputparm.
-
-
-:revision: 0.11 / 2006-01-27 (*mhs*)
-
-Improved the description of struct v4l2_tuner.
-
-
-:revision: 0.10 / 2006-01-10 (*mhs*)
-
-VIDIOC_G_INPUT and VIDIOC_S_PARM clarifications.
-
-
-:revision: 0.9 / 2005-11-27 (*mhs*)
-
-Improved the 525 line numbering diagram. Hans Verkuil and I rewrote the
-sliced VBI section. He also contributed a VIDIOC_LOG_STATUS page.
-Fixed VIDIOC_S_STD call in the video standard selection example.
-Various updates.
-
-
-:revision: 0.8 / 2004-10-04 (*mhs*)
-
-Somehow a piece of junk slipped into the capture example, removed.
-
-
-:revision: 0.7 / 2004-09-19 (*mhs*)
-
-Fixed video standard selection, control enumeration, downscaling and
-aspect example. Added read and user pointer i/o to video capture
-example.
-
-
-:revision: 0.6 / 2004-08-01 (*mhs*)
-
-v4l2_buffer changes, added video capture example, various corrections.
-
-
-:revision: 0.5 / 2003-11-05 (*mhs*)
-
-Pixel format erratum.
-
-
-:revision: 0.4 / 2003-09-17 (*mhs*)
-
-Corrected source and Makefile to generate a PDF. SGML fixes. Added
-latest API changes. Closed gaps in the history chapter.
-
-
-:revision: 0.3 / 2003-02-05 (*mhs*)
-
-Another draft, more corrections.
-
-
-:revision: 0.2 / 2003-01-15 (*mhs*)
-
-Second draft, with corrections pointed out by Gerd Knorr.
-
-
-:revision: 0.1 / 2002-12-01 (*mhs*)
-
-First draft, based on documentation by Bill Dirks and discussions on the
-V4L mailing list.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _v4l2grab-example:
-
-**********************************
-Video Grabber example using libv4l
-**********************************
-
-This program demonstrates how to grab V4L2 images in ppm format by using
-libv4l handlers. The advantage is that this grabber can potentially work
-with any V4L2 driver.
-
-
-.. toctree::
- :maxdepth: 1
-
- v4l2grab.c
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-file: media/v4l/v4l2grab.c
-==========================
-
-.. code-block:: c
-
- /* V4L2 video picture grabber
- Copyright (C) 2009 Mauro Carvalho Chehab <mchehab@infradead.org>
-
- This program is free software; you can redistribute it and/or modify
- it under the terms of the GNU General Public License as published by
- the Free Software Foundation version 2 of the License.
-
- This program is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- GNU General Public License for more details.
- */
-
- #include <stdio.h>
- #include <stdlib.h>
- #include <string.h>
- #include <fcntl.h>
- #include <errno.h>
- #include <sys/ioctl.h>
- #include <sys/types.h>
- #include <sys/time.h>
- #include <sys/mman.h>
- #include <linux/videodev2.h>
- #include "../libv4l/include/libv4l2.h"
-
- #define CLEAR(x) memset(&(x), 0, sizeof(x))
-
- struct buffer {
- void *start;
- size_t length;
- };
-
- static void xioctl(int fh, int request, void *arg)
- {
- int r;
-
- do {
- r = v4l2_ioctl(fh, request, arg);
- } while (r == -1 && ((errno == EINTR) || (errno == EAGAIN)));
-
- if (r == -1) {
- fprintf(stderr, "error %d, %s\\n", errno, strerror(errno));
- exit(EXIT_FAILURE);
- }
- }
-
- int main(int argc, char **argv)
- {
- struct v4l2_format fmt;
- struct v4l2_buffer buf;
- struct v4l2_requestbuffers req;
- enum v4l2_buf_type type;
- fd_set fds;
- struct timeval tv;
- int r, fd = -1;
- unsigned int i, n_buffers;
- char *dev_name = "/dev/video0";
- char out_name[256];
- FILE *fout;
- struct buffer *buffers;
-
- fd = v4l2_open(dev_name, O_RDWR | O_NONBLOCK, 0);
- if (fd < 0) {
- perror("Cannot open device");
- exit(EXIT_FAILURE);
- }
-
- CLEAR(fmt);
- fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- fmt.fmt.pix.width = 640;
- fmt.fmt.pix.height = 480;
- fmt.fmt.pix.pixelformat = V4L2_PIX_FMT_RGB24;
- fmt.fmt.pix.field = V4L2_FIELD_INTERLACED;
- xioctl(fd, VIDIOC_S_FMT, &fmt);
- if (fmt.fmt.pix.pixelformat != V4L2_PIX_FMT_RGB24) {
- printf("Libv4l didn't accept RGB24 format. Can't proceed.\\n");
- exit(EXIT_FAILURE);
- }
- if ((fmt.fmt.pix.width != 640) || (fmt.fmt.pix.height != 480))
- printf("Warning: driver is sending image at %dx%d\\n",
- fmt.fmt.pix.width, fmt.fmt.pix.height);
-
- CLEAR(req);
- req.count = 2;
- req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- req.memory = V4L2_MEMORY_MMAP;
- xioctl(fd, VIDIOC_REQBUFS, &req);
-
- buffers = calloc(req.count, sizeof(*buffers));
- for (n_buffers = 0; n_buffers < req.count; ++n_buffers) {
- CLEAR(buf);
-
- buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- buf.memory = V4L2_MEMORY_MMAP;
- buf.index = n_buffers;
-
- xioctl(fd, VIDIOC_QUERYBUF, &buf);
-
- buffers[n_buffers].length = buf.length;
- buffers[n_buffers].start = v4l2_mmap(NULL, buf.length,
- PROT_READ | PROT_WRITE, MAP_SHARED,
- fd, buf.m.offset);
-
- if (MAP_FAILED == buffers[n_buffers].start) {
- perror("mmap");
- exit(EXIT_FAILURE);
- }
- }
-
- for (i = 0; i < n_buffers; ++i) {
- CLEAR(buf);
- buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- buf.memory = V4L2_MEMORY_MMAP;
- buf.index = i;
- xioctl(fd, VIDIOC_QBUF, &buf);
- }
- type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
-
- xioctl(fd, VIDIOC_STREAMON, &type);
- for (i = 0; i < 20; i++) {
- do {
- FD_ZERO(&fds);
- FD_SET(fd, &fds);
-
- /* Timeout. */
- tv.tv_sec = 2;
- tv.tv_usec = 0;
-
- r = select(fd + 1, &fds, NULL, NULL, &tv);
- } while ((r == -1 && (errno = EINTR)));
- if (r == -1) {
- perror("select");
- return errno;
- }
-
- CLEAR(buf);
- buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- buf.memory = V4L2_MEMORY_MMAP;
- xioctl(fd, VIDIOC_DQBUF, &buf);
-
- sprintf(out_name, "out%03d.ppm", i);
- fout = fopen(out_name, "w");
- if (!fout) {
- perror("Cannot open image");
- exit(EXIT_FAILURE);
- }
- fprintf(fout, "P6\\n%d %d 255\\n",
- fmt.fmt.pix.width, fmt.fmt.pix.height);
- fwrite(buffers[buf.index].start, buf.bytesused, 1, fout);
- fclose(fout);
-
- xioctl(fd, VIDIOC_QBUF, &buf);
- }
-
- type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
- xioctl(fd, VIDIOC_STREAMOFF, &type);
- for (i = 0; i < n_buffers; ++i)
- v4l2_munmap(buffers[i].start, buffers[i].length);
- v4l2_close(fd);
-
- return 0;
- }
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _video:
-
-************************
-Video Inputs and Outputs
-************************
-
-Video inputs and outputs are physical connectors of a device. These can
-be for example RF connectors (antenna/cable), CVBS a.k.a. Composite
-Video, S-Video or RGB connectors. Video and VBI capture devices have
-inputs. Video and VBI output devices have outputs, at least one each.
-Radio devices have no video inputs or outputs.
-
-To learn about the number and attributes of the available inputs and
-outputs applications can enumerate them with the
-:ref:`VIDIOC_ENUMINPUT` and
-:ref:`VIDIOC_ENUMOUTPUT` ioctl, respectively. The
-struct :ref:`v4l2_input <v4l2-input>` returned by the
-:ref:`VIDIOC_ENUMINPUT` ioctl also contains signal
-:status information applicable when the current video input is queried.
-
-The :ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` and
-:ref:`VIDIOC_G_OUTPUT <VIDIOC_G_OUTPUT>` ioctls return the index of
-the current video input or output. To select a different input or output
-applications call the :ref:`VIDIOC_S_INPUT <VIDIOC_G_INPUT>` and
-:ref:`VIDIOC_S_OUTPUT <VIDIOC_G_OUTPUT>` ioctls. Drivers must
-implement all the input ioctls when the device has one or more inputs,
-all the output ioctls when the device has one or more outputs.
-
-.. code-block:: c
- :caption: Example 1.1. Information about the current video input
-
- struct v4l2_input input;
- int index;
-
- if (-1 == ioctl(fd, VIDIOC_G_INPUT, &index)) {
- perror("VIDIOC_G_INPUT");
- exit(EXIT_FAILURE);
- }
-
- memset(&input, 0, sizeof(input));
- input.index = index;
-
- if (-1 == ioctl(fd, VIDIOC_ENUMINPUT, &input)) {
- perror("VIDIOC_ENUMINPUT");
- exit(EXIT_FAILURE);
- }
-
- printf("Current input: %s\\n", input.name);
-
-
-.. code-block:: c
- :caption: Example 1.2. Switching to the first video input
-
- int index;
-
- index = 0;
-
- if (-1 == ioctl(fd, VIDIOC_S_INPUT, &index)) {
- perror("VIDIOC_S_INPUT");
- exit(EXIT_FAILURE);
- }
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _videodev:
-
-*******************************
-Video For Linux Two Header File
-*******************************
-
-.. kernel-include:: $BUILDDIR/videodev2.h.rst
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_CREATE_BUFS:
-
-************************
-ioctl VIDIOC_CREATE_BUFS
-************************
-
-Name
-====
-
-VIDIOC_CREATE_BUFS - Create buffers for Memory Mapped or User Pointer or DMA Buffer I/O
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_create_buffers *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_CREATE_BUFS
-
-``argp``
-
-
-Description
-===========
-
-This ioctl is used to create buffers for :ref:`memory mapped <mmap>`
-or :ref:`user pointer <userp>` or :ref:`DMA buffer <dmabuf>` I/O. It
-can be used as an alternative or in addition to the
-:ref:`VIDIOC_REQBUFS` ioctl, when a tighter control
-over buffers is required. This ioctl can be called multiple times to
-create buffers of different sizes.
-
-To allocate the device buffers applications must initialize the relevant
-fields of the :ref:`struct v4l2_create_buffers <v4l2-create-buffers>` structure. The
-``count`` field must be set to the number of requested buffers, the
-``memory`` field specifies the requested I/O method and the ``reserved``
-array must be zeroed.
-
-The ``format`` field specifies the image format that the buffers must be
-able to handle. The application has to fill in this struct
-:ref:`v4l2_format <v4l2-format>`. Usually this will be done using the
-:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` or
-:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctls to ensure that the
-requested format is supported by the driver. Based on the format's
-``type`` field the requested buffer size (for single-planar) or plane
-sizes (for multi-planar formats) will be used for the allocated buffers.
-The driver may return an error if the size(s) are not supported by the
-hardware (usually because they are too small).
-
-The buffers created by this ioctl will have as minimum size the size
-defined by the ``format.pix.sizeimage`` field (or the corresponding
-fields for other format types). Usually if the ``format.pix.sizeimage``
-field is less than the minimum required for the given format, then an
-error will be returned since drivers will typically not allow this. If
-it is larger, then the value will be used as-is. In other words, the
-driver may reject the requested size, but if it is accepted the driver
-will use it unchanged.
-
-When the ioctl is called with a pointer to this structure the driver
-will attempt to allocate up to the requested number of buffers and store
-the actual number allocated and the starting index in the ``count`` and
-the ``index`` fields respectively. On return ``count`` can be smaller
-than the number requested.
-
-
-.. _v4l2-create-buffers:
-
-.. flat-table:: struct v4l2_create_buffers
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``index``
-
- - The starting buffer index, returned by the driver.
-
- - .. row 2
-
- - __u32
-
- - ``count``
-
- - The number of buffers requested or granted. If count == 0, then
- :ref:`VIDIOC_CREATE_BUFS` will set ``index`` to the current number of
- created buffers, and it will check the validity of ``memory`` and
- ``format.type``. If those are invalid -1 is returned and errno is
- set to ``EINVAL`` error code, otherwise :ref:`VIDIOC_CREATE_BUFS` returns
- 0. It will never set errno to ``EBUSY`` error code in this particular
- case.
-
- - .. row 3
-
- - __u32
-
- - ``memory``
-
- - Applications set this field to ``V4L2_MEMORY_MMAP``,
- ``V4L2_MEMORY_DMABUF`` or ``V4L2_MEMORY_USERPTR``. See
- :ref:`v4l2-memory`
-
- - .. row 4
-
- - struct :ref:`v4l2_format <v4l2-format>`
-
- - ``format``
-
- - Filled in by the application, preserved by the driver.
-
- - .. row 5
-
- - __u32
-
- - ``reserved``\ [8]
-
- - A place holder for future extensions. Drivers and applications
- must set the array to zero.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-ENOMEM
- No memory to allocate buffers for :ref:`memory mapped <mmap>` I/O.
-
-EINVAL
- The buffer type (``format.type`` field), requested I/O method
- (``memory``) or format (``format`` field) is not valid.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_CROPCAP:
-
-********************
-ioctl VIDIOC_CROPCAP
-********************
-
-Name
-====
-
-VIDIOC_CROPCAP - Information about the video cropping and scaling abilities
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_cropcap *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_CROPCAP
-
-``argp``
-
-
-Description
-===========
-
-Applications use this function to query the cropping limits, the pixel
-aspect of images and to calculate scale factors. They set the ``type``
-field of a v4l2_cropcap structure to the respective buffer (stream)
-type and call the :ref:`VIDIOC_CROPCAP` ioctl with a pointer to this
-structure. Drivers fill the rest of the structure. The results are
-constant except when switching the video standard. Remember this switch
-can occur implicit when switching the video input or output.
-
-Do not use the multiplanar buffer types. Use
-``V4L2_BUF_TYPE_VIDEO_CAPTURE`` instead of
-``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and use
-``V4L2_BUF_TYPE_VIDEO_OUTPUT`` instead of
-``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``.
-
-This ioctl must be implemented for video capture or output devices that
-support cropping and/or scaling and/or have non-square pixels, and for
-overlay devices.
-
-
-.. _v4l2-cropcap:
-
-.. flat-table:: struct v4l2_cropcap
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``type``
-
- - Type of the data stream, set by the application. Only these types
- are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``,
- ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` and
- ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :ref:`v4l2-buf-type`.
-
- - .. row 2
-
- - struct :ref:`v4l2_rect <v4l2-rect-crop>`
-
- - ``bounds``
-
- - Defines the window within capturing or output is possible, this
- may exclude for example the horizontal and vertical blanking
- areas. The cropping rectangle cannot exceed these limits. Width
- and height are defined in pixels, the driver writer is free to
- choose origin and units of the coordinate system in the analog
- domain.
-
- - .. row 3
-
- - struct :ref:`v4l2_rect <v4l2-rect-crop>`
-
- - ``defrect``
-
- - Default cropping rectangle, it shall cover the "whole picture".
- Assuming pixel aspect 1/1 this could be for example a 640 × 480
- rectangle for NTSC, a 768 × 576 rectangle for PAL and SECAM
- centered over the active picture area. The same co-ordinate system
- as for ``bounds`` is used.
-
- - .. row 4
-
- - struct :ref:`v4l2_fract <v4l2-fract>`
-
- - ``pixelaspect``
-
- - This is the pixel aspect (y / x) when no scaling is applied, the
- ratio of the actual sampling frequency and the frequency required
- to get square pixels.
-
- When cropping coordinates refer to square pixels, the driver sets
- ``pixelaspect`` to 1/1. Other common values are 54/59 for PAL and
- SECAM, 11/10 for NTSC sampled according to [:ref:`itu601`].
-
-
-
-.. _v4l2-rect-crop:
-
-.. flat-table:: struct v4l2_rect
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __s32
-
- - ``left``
-
- - Horizontal offset of the top, left corner of the rectangle, in
- pixels.
-
- - .. row 2
-
- - __s32
-
- - ``top``
-
- - Vertical offset of the top, left corner of the rectangle, in
- pixels.
-
- - .. row 3
-
- - __u32
-
- - ``width``
-
- - Width of the rectangle, in pixels.
-
- - .. row 4
-
- - __u32
-
- - ``height``
-
- - Height of the rectangle, in pixels.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EINVAL
- The struct :ref:`v4l2_cropcap <v4l2-cropcap>` ``type`` is
- invalid.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_DBG_G_CHIP_INFO:
-
-****************************
-ioctl VIDIOC_DBG_G_CHIP_INFO
-****************************
-
-Name
-====
-
-VIDIOC_DBG_G_CHIP_INFO - Identify the chips on a TV card
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_dbg_chip_info *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_DBG_G_CHIP_INFO
-
-``argp``
-
-
-Description
-===========
-
- **Note**
-
- This is an :ref:`experimental` interface and may
- change in the future.
-
-For driver debugging purposes this ioctl allows test applications to
-query the driver about the chips present on the TV card. Regular
-applications must not use it. When you found a chip specific bug, please
-contact the linux-media mailing list
-(`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__)
-so it can be fixed.
-
-Additionally the Linux kernel must be compiled with the
-``CONFIG_VIDEO_ADV_DEBUG`` option to enable this ioctl.
-
-To query the driver applications must initialize the ``match.type`` and
-``match.addr`` or ``match.name`` fields of a struct
-:ref:`v4l2_dbg_chip_info <v4l2-dbg-chip-info>` and call
-:ref:`VIDIOC_DBG_G_CHIP_INFO` with a pointer to this structure. On success
-the driver stores information about the selected chip in the ``name``
-and ``flags`` fields.
-
-When ``match.type`` is ``V4L2_CHIP_MATCH_BRIDGE``, ``match.addr``
-selects the nth bridge 'chip' on the TV card. You can enumerate all
-chips by starting at zero and incrementing ``match.addr`` by one until
-:ref:`VIDIOC_DBG_G_CHIP_INFO` fails with an ``EINVAL`` error code. The number
-zero always selects the bridge chip itself, e. g. the chip connected to
-the PCI or USB bus. Non-zero numbers identify specific parts of the
-bridge chip such as an AC97 register block.
-
-When ``match.type`` is ``V4L2_CHIP_MATCH_SUBDEV``, ``match.addr``
-selects the nth sub-device. This allows you to enumerate over all
-sub-devices.
-
-On success, the ``name`` field will contain a chip name and the
-``flags`` field will contain ``V4L2_CHIP_FL_READABLE`` if the driver
-supports reading registers from the device or ``V4L2_CHIP_FL_WRITABLE``
-if the driver supports writing registers to the device.
-
-We recommended the v4l2-dbg utility over calling this ioctl directly. It
-is available from the LinuxTV v4l-dvb repository; see
-`https://linuxtv.org/repo/ <https://linuxtv.org/repo/>`__ for access
-instructions.
-
-
-.. _name-v4l2-dbg-match:
-
-.. flat-table:: struct v4l2_dbg_match
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``type``
-
- - See :ref:`name-chip-match-types` for a list of possible types.
-
- - .. row 2
-
- - union
-
- - (anonymous)
-
- - .. row 3
-
- -
- - __u32
-
- - ``addr``
-
- - Match a chip by this number, interpreted according to the ``type``
- field.
-
- - .. row 4
-
- -
- - char
-
- - ``name[32]``
-
- - Match a chip by this name, interpreted according to the ``type``
- field. Currently unused.
-
-
-
-.. _v4l2-dbg-chip-info:
-
-.. flat-table:: struct v4l2_dbg_chip_info
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - struct v4l2_dbg_match
-
- - ``match``
-
- - How to match the chip, see :ref:`name-v4l2-dbg-match`.
-
- - .. row 2
-
- - char
-
- - ``name[32]``
-
- - The name of the chip.
-
- - .. row 3
-
- - __u32
-
- - ``flags``
-
- - Set by the driver. If ``V4L2_CHIP_FL_READABLE`` is set, then the
- driver supports reading registers from the device. If
- ``V4L2_CHIP_FL_WRITABLE`` is set, then it supports writing
- registers.
-
- - .. row 4
-
- - __u32
-
- - ``reserved[8]``
-
- - Reserved fields, both application and driver must set these to 0.
-
-
-
-.. _name-chip-match-types:
-
-.. flat-table:: Chip Match Types
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - ``V4L2_CHIP_MATCH_BRIDGE``
-
- - 0
-
- - Match the nth chip on the card, zero for the bridge chip. Does not
- match sub-devices.
-
- - .. row 2
-
- - ``V4L2_CHIP_MATCH_SUBDEV``
-
- - 4
-
- - Match the nth sub-device.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EINVAL
- The ``match_type`` is invalid or no device could be matched.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_DBG_G_REGISTER:
-
-**************************************************
-ioctl VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER
-**************************************************
-
-Name
-====
-
-VIDIOC_DBG_G_REGISTER - VIDIOC_DBG_S_REGISTER - Read or write hardware registers
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_dbg_register *argp )
-
-.. cpp:function:: int ioctl( int fd, int request, const struct v4l2_dbg_register *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER
-
-``argp``
-
-
-Description
-===========
-
- **Note**
-
- This is an :ref:`experimental` interface and may
- change in the future.
-
-For driver debugging purposes these ioctls allow test applications to
-access hardware registers directly. Regular applications must not use
-them.
-
-Since writing or even reading registers can jeopardize the system
-security, its stability and damage the hardware, both ioctls require
-superuser privileges. Additionally the Linux kernel must be compiled
-with the ``CONFIG_VIDEO_ADV_DEBUG`` option to enable these ioctls.
-
-To write a register applications must initialize all fields of a struct
-:ref:`v4l2_dbg_register <v4l2-dbg-register>` except for ``size`` and
-call ``VIDIOC_DBG_S_REGISTER`` with a pointer to this structure. The
-``match.type`` and ``match.addr`` or ``match.name`` fields select a chip
-on the TV card, the ``reg`` field specifies a register number and the
-``val`` field the value to be written into the register.
-
-To read a register applications must initialize the ``match.type``,
-``match.addr`` or ``match.name`` and ``reg`` fields, and call
-``VIDIOC_DBG_G_REGISTER`` with a pointer to this structure. On success
-the driver stores the register value in the ``val`` field and the size
-(in bytes) of the value in ``size``.
-
-When ``match.type`` is ``V4L2_CHIP_MATCH_BRIDGE``, ``match.addr``
-selects the nth non-sub-device chip on the TV card. The number zero
-always selects the host chip, e. g. the chip connected to the PCI or USB
-bus. You can find out which chips are present with the
-:ref:`VIDIOC_DBG_G_CHIP_INFO` ioctl.
-
-When ``match.type`` is ``V4L2_CHIP_MATCH_SUBDEV``, ``match.addr``
-selects the nth sub-device.
-
-These ioctls are optional, not all drivers may support them. However
-when a driver supports these ioctls it must also support
-:ref:`VIDIOC_DBG_G_CHIP_INFO`. Conversely
-it may support ``VIDIOC_DBG_G_CHIP_INFO`` but not these ioctls.
-
-``VIDIOC_DBG_G_REGISTER`` and ``VIDIOC_DBG_S_REGISTER`` were introduced
-in Linux 2.6.21, but their API was changed to the one described here in
-kernel 2.6.29.
-
-We recommended the v4l2-dbg utility over calling these ioctls directly.
-It is available from the LinuxTV v4l-dvb repository; see
-`https://linuxtv.org/repo/ <https://linuxtv.org/repo/>`__ for access
-instructions.
-
-
-.. _v4l2-dbg-match:
-
-.. flat-table:: struct v4l2_dbg_match
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``type``
-
- - See :ref:`chip-match-types` for a list of possible types.
-
- - .. row 2
-
- - union
-
- - (anonymous)
-
- - .. row 3
-
- -
- - __u32
-
- - ``addr``
-
- - Match a chip by this number, interpreted according to the ``type``
- field.
-
- - .. row 4
-
- -
- - char
-
- - ``name[32]``
-
- - Match a chip by this name, interpreted according to the ``type``
- field. Currently unused.
-
-
-
-.. _v4l2-dbg-register:
-
-.. flat-table:: struct v4l2_dbg_register
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - struct v4l2_dbg_match
-
- - ``match``
-
- - How to match the chip, see :ref:`v4l2-dbg-match`.
-
- - .. row 2
-
- - __u32
-
- - ``size``
-
- - The register size in bytes.
-
- - .. row 3
-
- - __u64
-
- - ``reg``
-
- - A register number.
-
- - .. row 4
-
- - __u64
-
- - ``val``
-
- - The value read from, or to be written into the register.
-
-
-
-.. _chip-match-types:
-
-.. flat-table:: Chip Match Types
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - ``V4L2_CHIP_MATCH_BRIDGE``
-
- - 0
-
- - Match the nth chip on the card, zero for the bridge chip. Does not
- match sub-devices.
-
- - .. row 2
-
- - ``V4L2_CHIP_MATCH_SUBDEV``
-
- - 4
-
- - Match the nth sub-device.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EPERM
- Insufficient permissions. Root privileges are required to execute
- these ioctls.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_DECODER_CMD:
-
-************************************************
-ioctl VIDIOC_DECODER_CMD, VIDIOC_TRY_DECODER_CMD
-************************************************
-
-Name
-====
-
-VIDIOC_DECODER_CMD - VIDIOC_TRY_DECODER_CMD - Execute an decoder command
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_decoder_cmd *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_DECODER_CMD, VIDIOC_TRY_DECODER_CMD
-
-``argp``
-
-
-Description
-===========
-
-These ioctls control an audio/video (usually MPEG-) decoder.
-``VIDIOC_DECODER_CMD`` sends a command to the decoder,
-``VIDIOC_TRY_DECODER_CMD`` can be used to try a command without actually
-executing it. To send a command applications must initialize all fields
-of a struct :ref:`v4l2_decoder_cmd <v4l2-decoder-cmd>` and call
-``VIDIOC_DECODER_CMD`` or ``VIDIOC_TRY_DECODER_CMD`` with a pointer to
-this structure.
-
-The ``cmd`` field must contain the command code. Some commands use the
-``flags`` field for additional information.
-
-A :ref:`write() <func-write>` or :ref:`VIDIOC_STREAMON`
-call sends an implicit START command to the decoder if it has not been
-started yet.
-
-A :ref:`close() <func-close>` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`
-call of a streaming file descriptor sends an implicit immediate STOP
-command to the decoder, and all buffered data is discarded.
-
-These ioctls are optional, not all drivers may support them. They were
-introduced in Linux 3.3.
-
-
-.. _v4l2-decoder-cmd:
-
-.. flat-table:: struct v4l2_decoder_cmd
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2 1 1
-
-
- - .. row 1
-
- - __u32
-
- - ``cmd``
-
- -
- -
- - The decoder command, see :ref:`decoder-cmds`.
-
- - .. row 2
-
- - __u32
-
- - ``flags``
-
- -
- -
- - Flags to go with the command. If no flags are defined for this
- command, drivers and applications must set this field to zero.
-
- - .. row 3
-
- - union
-
- - (anonymous)
-
- -
- -
- -
-
- - .. row 4
-
- -
- - struct
-
- - ``start``
-
- -
- - Structure containing additional data for the
- ``V4L2_DEC_CMD_START`` command.
-
- - .. row 5
-
- -
- -
- - __s32
-
- - ``speed``
-
- - Playback speed and direction. The playback speed is defined as
- ``speed``/1000 of the normal speed. So 1000 is normal playback.
- Negative numbers denote reverse playback, so -1000 does reverse
- playback at normal speed. Speeds -1, 0 and 1 have special
- meanings: speed 0 is shorthand for 1000 (normal playback). A speed
- of 1 steps just one frame forward, a speed of -1 steps just one
- frame back.
-
- - .. row 6
-
- -
- -
- - __u32
-
- - ``format``
-
- - Format restrictions. This field is set by the driver, not the
- application. Possible values are ``V4L2_DEC_START_FMT_NONE`` if
- there are no format restrictions or ``V4L2_DEC_START_FMT_GOP`` if
- the decoder operates on full GOPs (*Group Of Pictures*). This is
- usually the case for reverse playback: the decoder needs full
- GOPs, which it can then play in reverse order. So to implement
- reverse playback the application must feed the decoder the last
- GOP in the video file, then the GOP before that, etc. etc.
-
- - .. row 7
-
- -
- - struct
-
- - ``stop``
-
- -
- - Structure containing additional data for the ``V4L2_DEC_CMD_STOP``
- command.
-
- - .. row 8
-
- -
- -
- - __u64
-
- - ``pts``
-
- - Stop playback at this ``pts`` or immediately if the playback is
- already past that timestamp. Leave to 0 if you want to stop after
- the last frame was decoded.
-
- - .. row 9
-
- -
- - struct
-
- - ``raw``
-
- -
- -
-
- - .. row 10
-
- -
- -
- - __u32
-
- - ``data``\ [16]
-
- - Reserved for future extensions. Drivers and applications must set
- the array to zero.
-
-
-
-.. _decoder-cmds:
-
-.. flat-table:: Decoder Commands
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - ``V4L2_DEC_CMD_START``
-
- - 0
-
- - Start the decoder. When the decoder is already running or paused,
- this command will just change the playback speed. That means that
- calling ``V4L2_DEC_CMD_START`` when the decoder was paused will
- *not* resume the decoder. You have to explicitly call
- ``V4L2_DEC_CMD_RESUME`` for that. This command has one flag:
- ``V4L2_DEC_CMD_START_MUTE_AUDIO``. If set, then audio will be
- muted when playing back at a non-standard speed.
-
- - .. row 2
-
- - ``V4L2_DEC_CMD_STOP``
-
- - 1
-
- - Stop the decoder. When the decoder is already stopped, this
- command does nothing. This command has two flags: if
- ``V4L2_DEC_CMD_STOP_TO_BLACK`` is set, then the decoder will set
- the picture to black after it stopped decoding. Otherwise the last
- image will repeat. mem2mem decoders will stop producing new frames
- altogether. They will send a ``V4L2_EVENT_EOS`` event when the
- last frame has been decoded and all frames are ready to be
- dequeued and will set the ``V4L2_BUF_FLAG_LAST`` buffer flag on
- the last buffer of the capture queue to indicate there will be no
- new buffers produced to dequeue. This buffer may be empty,
- indicated by the driver setting the ``bytesused`` field to 0. Once
- the ``V4L2_BUF_FLAG_LAST`` flag was set, the
- :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will not block anymore,
- but return an ``EPIPE`` error code. If
- ``V4L2_DEC_CMD_STOP_IMMEDIATELY`` is set, then the decoder stops
- immediately (ignoring the ``pts`` value), otherwise it will keep
- decoding until timestamp >= pts or until the last of the pending
- data from its internal buffers was decoded.
-
- - .. row 3
-
- - ``V4L2_DEC_CMD_PAUSE``
-
- - 2
-
- - Pause the decoder. When the decoder has not been started yet, the
- driver will return an ``EPERM`` error code. When the decoder is
- already paused, this command does nothing. This command has one
- flag: if ``V4L2_DEC_CMD_PAUSE_TO_BLACK`` is set, then set the
- decoder output to black when paused.
-
- - .. row 4
-
- - ``V4L2_DEC_CMD_RESUME``
-
- - 3
-
- - Resume decoding after a PAUSE command. When the decoder has not
- been started yet, the driver will return an ``EPERM`` error code. When
- the decoder is already running, this command does nothing. No
- flags are defined for this command.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EINVAL
- The ``cmd`` field is invalid.
-
-EPERM
- The application sent a PAUSE or RESUME command when the decoder was
- not running.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_DQEVENT:
-
-********************
-ioctl VIDIOC_DQEVENT
-********************
-
-Name
-====
-
-VIDIOC_DQEVENT - Dequeue event
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_event *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_DQEVENT
-
-``argp``
-
-
-Description
-===========
-
-Dequeue an event from a video device. No input is required for this
-ioctl. All the fields of the struct :ref:`v4l2_event <v4l2-event>`
-structure are filled by the driver. The file handle will also receive
-exceptions which the application may get by e.g. using the select system
-call.
-
-
-.. _v4l2-event:
-
-.. flat-table:: struct v4l2_event
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2 1
-
-
- - .. row 1
-
- - __u32
-
- - ``type``
-
- -
- - Type of the event, see :ref:`event-type`.
-
- - .. row 2
-
- - union
-
- - ``u``
-
- -
- -
-
- - .. row 3
-
- -
- - struct :ref:`v4l2_event_vsync <v4l2-event-vsync>`
-
- - ``vsync``
-
- - Event data for event ``V4L2_EVENT_VSYNC``.
-
- - .. row 4
-
- -
- - struct :ref:`v4l2_event_ctrl <v4l2-event-ctrl>`
-
- - ``ctrl``
-
- - Event data for event ``V4L2_EVENT_CTRL``.
-
- - .. row 5
-
- -
- - struct :ref:`v4l2_event_frame_sync <v4l2-event-frame-sync>`
-
- - ``frame_sync``
-
- - Event data for event ``V4L2_EVENT_FRAME_SYNC``.
-
- - .. row 6
-
- -
- - struct :ref:`v4l2_event_motion_det <v4l2-event-motion-det>`
-
- - ``motion_det``
-
- - Event data for event V4L2_EVENT_MOTION_DET.
-
- - .. row 7
-
- -
- - struct :ref:`v4l2_event_src_change <v4l2-event-src-change>`
-
- - ``src_change``
-
- - Event data for event V4L2_EVENT_SOURCE_CHANGE.
-
- - .. row 8
-
- -
- - __u8
-
- - ``data``\ [64]
-
- - Event data. Defined by the event type. The union should be used to
- define easily accessible type for events.
-
- - .. row 9
-
- - __u32
-
- - ``pending``
-
- -
- - Number of pending events excluding this one.
-
- - .. row 10
-
- - __u32
-
- - ``sequence``
-
- -
- - Event sequence number. The sequence number is incremented for
- every subscribed event that takes place. If sequence numbers are
- not contiguous it means that events have been lost.
-
- - .. row 11
-
- - struct timespec
-
- - ``timestamp``
-
- -
- - Event timestamp. The timestamp has been taken from the
- ``CLOCK_MONOTONIC`` clock. To access the same clock outside V4L2,
- use :c:func:`clock_gettime(2)`.
-
- - .. row 12
-
- - u32
-
- - ``id``
-
- -
- - The ID associated with the event source. If the event does not
- have an associated ID (this depends on the event type), then this
- is 0.
-
- - .. row 13
-
- - __u32
-
- - ``reserved``\ [8]
-
- -
- - Reserved for future extensions. Drivers must set the array to
- zero.
-
-
-
-.. _event-type:
-
-.. flat-table:: Event Types
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - ``V4L2_EVENT_ALL``
-
- - 0
-
- - All events. V4L2_EVENT_ALL is valid only for
- VIDIOC_UNSUBSCRIBE_EVENT for unsubscribing all events at once.
-
- - .. row 2
-
- - ``V4L2_EVENT_VSYNC``
-
- - 1
-
- - This event is triggered on the vertical sync. This event has a
- struct :ref:`v4l2_event_vsync <v4l2-event-vsync>` associated
- with it.
-
- - .. row 3
-
- - ``V4L2_EVENT_EOS``
-
- - 2
-
- - This event is triggered when the end of a stream is reached. This
- is typically used with MPEG decoders to report to the application
- when the last of the MPEG stream has been decoded.
-
- - .. row 4
-
- - ``V4L2_EVENT_CTRL``
-
- - 3
-
- - This event requires that the ``id`` matches the control ID from
- which you want to receive events. This event is triggered if the
- control's value changes, if a button control is pressed or if the
- control's flags change. This event has a struct
- :ref:`v4l2_event_ctrl <v4l2-event-ctrl>` associated with it.
- This struct contains much of the same information as struct
- :ref:`v4l2_queryctrl <v4l2-queryctrl>` and struct
- :ref:`v4l2_control <v4l2-control>`.
-
- If the event is generated due to a call to
- :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` or
- :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`, then the
- event will *not* be sent to the file handle that called the ioctl
- function. This prevents nasty feedback loops. If you *do* want to
- get the event, then set the ``V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK``
- flag.
-
- This event type will ensure that no information is lost when more
- events are raised than there is room internally. In that case the
- struct :ref:`v4l2_event_ctrl <v4l2-event-ctrl>` of the
- second-oldest event is kept, but the ``changes`` field of the
- second-oldest event is ORed with the ``changes`` field of the
- oldest event.
-
- - .. row 5
-
- - ``V4L2_EVENT_FRAME_SYNC``
-
- - 4
-
- - Triggered immediately when the reception of a frame has begun.
- This event has a struct
- :ref:`v4l2_event_frame_sync <v4l2-event-frame-sync>`
- associated with it.
-
- If the hardware needs to be stopped in the case of a buffer
- underrun it might not be able to generate this event. In such
- cases the ``frame_sequence`` field in struct
- :ref:`v4l2_event_frame_sync <v4l2-event-frame-sync>` will not
- be incremented. This causes two consecutive frame sequence numbers
- to have n times frame interval in between them.
-
- - .. row 6
-
- - ``V4L2_EVENT_SOURCE_CHANGE``
-
- - 5
-
- - This event is triggered when a source parameter change is detected
- during runtime by the video device. It can be a runtime resolution
- change triggered by a video decoder or the format change happening
- on an input connector. This event requires that the ``id`` matches
- the input index (when used with a video device node) or the pad
- index (when used with a subdevice node) from which you want to
- receive events.
-
- This event has a struct
- :ref:`v4l2_event_src_change <v4l2-event-src-change>`
- associated with it. The ``changes`` bitfield denotes what has
- changed for the subscribed pad. If multiple events occurred before
- application could dequeue them, then the changes will have the
- ORed value of all the events generated.
-
- - .. row 7
-
- - ``V4L2_EVENT_MOTION_DET``
-
- - 6
-
- - Triggered whenever the motion detection state for one or more of
- the regions changes. This event has a struct
- :ref:`v4l2_event_motion_det <v4l2-event-motion-det>`
- associated with it.
-
- - .. row 8
-
- - ``V4L2_EVENT_PRIVATE_START``
-
- - 0x08000000
-
- - Base event number for driver-private events.
-
-
-
-.. _v4l2-event-vsync:
-
-.. flat-table:: struct v4l2_event_vsync
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u8
-
- - ``field``
-
- - The upcoming field. See enum :ref:`v4l2_field <v4l2-field>`.
-
-
-
-.. _v4l2-event-ctrl:
-
-.. flat-table:: struct v4l2_event_ctrl
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2 1
-
-
- - .. row 1
-
- - __u32
-
- - ``changes``
-
- -
- - A bitmask that tells what has changed. See
- :ref:`ctrl-changes-flags`.
-
- - .. row 2
-
- - __u32
-
- - ``type``
-
- -
- - The type of the control. See enum
- :ref:`v4l2_ctrl_type <v4l2-ctrl-type>`.
-
- - .. row 3
-
- - union (anonymous)
-
- -
- -
- -
-
- - .. row 4
-
- -
- - __s32
-
- - ``value``
-
- - The 32-bit value of the control for 32-bit control types. This is
- 0 for string controls since the value of a string cannot be passed
- using :ref:`VIDIOC_DQEVENT`.
-
- - .. row 5
-
- -
- - __s64
-
- - ``value64``
-
- - The 64-bit value of the control for 64-bit control types.
-
- - .. row 6
-
- - __u32
-
- - ``flags``
-
- -
- - The control flags. See :ref:`control-flags`.
-
- - .. row 7
-
- - __s32
-
- - ``minimum``
-
- -
- - The minimum value of the control. See struct
- :ref:`v4l2_queryctrl <v4l2-queryctrl>`.
-
- - .. row 8
-
- - __s32
-
- - ``maximum``
-
- -
- - The maximum value of the control. See struct
- :ref:`v4l2_queryctrl <v4l2-queryctrl>`.
-
- - .. row 9
-
- - __s32
-
- - ``step``
-
- -
- - The step value of the control. See struct
- :ref:`v4l2_queryctrl <v4l2-queryctrl>`.
-
- - .. row 10
-
- - __s32
-
- - ``default_value``
-
- -
- - The default value value of the control. See struct
- :ref:`v4l2_queryctrl <v4l2-queryctrl>`.
-
-
-
-.. _v4l2-event-frame-sync:
-
-.. flat-table:: struct v4l2_event_frame_sync
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``frame_sequence``
-
- - The sequence number of the frame being received.
-
-
-
-.. _v4l2-event-src-change:
-
-.. flat-table:: struct v4l2_event_src_change
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``changes``
-
- - A bitmask that tells what has changed. See
- :ref:`src-changes-flags`.
-
-
-
-.. _v4l2-event-motion-det:
-
-.. flat-table:: struct v4l2_event_motion_det
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``flags``
-
- - Currently only one flag is available: if
- ``V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ`` is set, then the
- ``frame_sequence`` field is valid, otherwise that field should be
- ignored.
-
- - .. row 2
-
- - __u32
-
- - ``frame_sequence``
-
- - The sequence number of the frame being received. Only valid if the
- ``V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ`` flag was set.
-
- - .. row 3
-
- - __u32
-
- - ``region_mask``
-
- - The bitmask of the regions that reported motion. There is at least
- one region. If this field is 0, then no motion was detected at
- all. If there is no ``V4L2_CID_DETECT_MD_REGION_GRID`` control
- (see :ref:`detect-controls`) to assign a different region to
- each cell in the motion detection grid, then that all cells are
- automatically assigned to the default region 0.
-
-
-
-.. _ctrl-changes-flags:
-
-.. flat-table:: Control Changes
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - ``V4L2_EVENT_CTRL_CH_VALUE``
-
- - 0x0001
-
- - This control event was triggered because the value of the control
- changed. Special cases: Volatile controls do no generate this
- event; If a control has the ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE``
- flag set, then this event is sent as well, regardless its value.
-
- - .. row 2
-
- - ``V4L2_EVENT_CTRL_CH_FLAGS``
-
- - 0x0002
-
- - This control event was triggered because the control flags
- changed.
-
- - .. row 3
-
- - ``V4L2_EVENT_CTRL_CH_RANGE``
-
- - 0x0004
-
- - This control event was triggered because the minimum, maximum,
- step or the default value of the control changed.
-
-
-
-.. _src-changes-flags:
-
-.. flat-table:: Source Changes
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - ``V4L2_EVENT_SRC_CH_RESOLUTION``
-
- - 0x0001
-
- - This event gets triggered when a resolution change is detected at
- an input. This can come from an input connector or from a video
- decoder.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_DV_TIMINGS_CAP:
-
-*********************************************************
-ioctl VIDIOC_DV_TIMINGS_CAP, VIDIOC_SUBDEV_DV_TIMINGS_CAP
-*********************************************************
-
-Name
-====
-
-VIDIOC_DV_TIMINGS_CAP - VIDIOC_SUBDEV_DV_TIMINGS_CAP - The capabilities of the Digital Video receiver/transmitter
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_dv_timings_cap *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_DV_TIMINGS_CAP, VIDIOC_SUBDEV_DV_TIMINGS_CAP
-
-``argp``
-
-
-Description
-===========
-
-To query the capabilities of the DV receiver/transmitter applications
-initialize the ``pad`` field to 0, zero the reserved array of struct
-:ref:`v4l2_dv_timings_cap <v4l2-dv-timings-cap>` and call the
-``VIDIOC_DV_TIMINGS_CAP`` ioctl on a video node and the driver will fill
-in the structure. Note that drivers may return different values after
-switching the video input or output.
-
-When implemented by the driver DV capabilities of subdevices can be
-queried by calling the ``VIDIOC_SUBDEV_DV_TIMINGS_CAP`` ioctl directly
-on a subdevice node. The capabilities are specific to inputs (for DV
-receivers) or outputs (for DV transmitters), applications must specify
-the desired pad number in the struct
-:ref:`v4l2_dv_timings_cap <v4l2-dv-timings-cap>` ``pad`` field and
-zero the ``reserved`` array. Attempts to query capabilities on a pad
-that doesn't support them will return an ``EINVAL`` error code.
-
-
-.. _v4l2-bt-timings-cap:
-
-.. flat-table:: struct v4l2_bt_timings_cap
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``min_width``
-
- - Minimum width of the active video in pixels.
-
- - .. row 2
-
- - __u32
-
- - ``max_width``
-
- - Maximum width of the active video in pixels.
-
- - .. row 3
-
- - __u32
-
- - ``min_height``
-
- - Minimum height of the active video in lines.
-
- - .. row 4
-
- - __u32
-
- - ``max_height``
-
- - Maximum height of the active video in lines.
-
- - .. row 5
-
- - __u64
-
- - ``min_pixelclock``
-
- - Minimum pixelclock frequency in Hz.
-
- - .. row 6
-
- - __u64
-
- - ``max_pixelclock``
-
- - Maximum pixelclock frequency in Hz.
-
- - .. row 7
-
- - __u32
-
- - ``standards``
-
- - The video standard(s) supported by the hardware. See
- :ref:`dv-bt-standards` for a list of standards.
-
- - .. row 8
-
- - __u32
-
- - ``capabilities``
-
- - Several flags giving more information about the capabilities. See
- :ref:`dv-bt-cap-capabilities` for a description of the flags.
-
- - .. row 9
-
- - __u32
-
- - ``reserved``\ [16]
-
- - Reserved for future extensions. Drivers must set the array to
- zero.
-
-
-
-.. _v4l2-dv-timings-cap:
-
-.. flat-table:: struct v4l2_dv_timings_cap
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2 1
-
-
- - .. row 1
-
- - __u32
-
- - ``type``
-
- - Type of DV timings as listed in :ref:`dv-timing-types`.
-
- - .. row 2
-
- - __u32
-
- - ``pad``
-
- - Pad number as reported by the media controller API. This field is
- only used when operating on a subdevice node. When operating on a
- video node applications must set this field to zero.
-
- - .. row 3
-
- - __u32
-
- - ``reserved``\ [2]
-
- - Reserved for future extensions. Drivers and applications must set
- the array to zero.
-
- - .. row 4
-
- - union
-
- -
- -
-
- - .. row 5
-
- -
- - struct :ref:`v4l2_bt_timings_cap <v4l2-bt-timings-cap>`
-
- - ``bt``
-
- - BT.656/1120 timings capabilities of the hardware.
-
- - .. row 6
-
- -
- - __u32
-
- - ``raw_data``\ [32]
-
- -
-
-
-
-.. _dv-bt-cap-capabilities:
-
-.. flat-table:: DV BT Timing capabilities
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - Flag
-
- - Description
-
- - .. row 2
-
- -
- -
-
- - .. row 3
-
- - ``V4L2_DV_BT_CAP_INTERLACED``
-
- - Interlaced formats are supported.
-
- - .. row 4
-
- - ``V4L2_DV_BT_CAP_PROGRESSIVE``
-
- - Progressive formats are supported.
-
- - .. row 5
-
- - ``V4L2_DV_BT_CAP_REDUCED_BLANKING``
-
- - CVT/GTF specific: the timings can make use of reduced blanking
- (CVT) or the 'Secondary GTF' curve (GTF).
-
- - .. row 6
-
- - ``V4L2_DV_BT_CAP_CUSTOM``
-
- - Can support non-standard timings, i.e. timings not belonging to
- the standards set in the ``standards`` field.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_ENCODER_CMD:
-
-************************************************
-ioctl VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD
-************************************************
-
-Name
-====
-
-VIDIOC_ENCODER_CMD - VIDIOC_TRY_ENCODER_CMD - Execute an encoder command
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_encoder_cmd *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD
-
-``argp``
-
-
-Description
-===========
-
-These ioctls control an audio/video (usually MPEG-) encoder.
-``VIDIOC_ENCODER_CMD`` sends a command to the encoder,
-``VIDIOC_TRY_ENCODER_CMD`` can be used to try a command without actually
-executing it.
-
-To send a command applications must initialize all fields of a struct
-:ref:`v4l2_encoder_cmd <v4l2-encoder-cmd>` and call
-``VIDIOC_ENCODER_CMD`` or ``VIDIOC_TRY_ENCODER_CMD`` with a pointer to
-this structure.
-
-The ``cmd`` field must contain the command code. The ``flags`` field is
-currently only used by the STOP command and contains one bit: If the
-``V4L2_ENC_CMD_STOP_AT_GOP_END`` flag is set, encoding will continue
-until the end of the current *Group Of Pictures*, otherwise it will stop
-immediately.
-
-A :ref:`read() <func-read>` or :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`
-call sends an implicit START command to the encoder if it has not been
-started yet. After a STOP command, :ref:`read() <func-read>` calls will read
-the remaining data buffered by the driver. When the buffer is empty,
-:ref:`read() <func-read>` will return zero and the next :ref:`read() <func-read>`
-call will restart the encoder.
-
-A :ref:`close() <func-close>` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`
-call of a streaming file descriptor sends an implicit immediate STOP to
-the encoder, and all buffered data is discarded.
-
-These ioctls are optional, not all drivers may support them. They were
-introduced in Linux 2.6.21.
-
-
-.. _v4l2-encoder-cmd:
-
-.. flat-table:: struct v4l2_encoder_cmd
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``cmd``
-
- - The encoder command, see :ref:`encoder-cmds`.
-
- - .. row 2
-
- - __u32
-
- - ``flags``
-
- - Flags to go with the command, see :ref:`encoder-flags`. If no
- flags are defined for this command, drivers and applications must
- set this field to zero.
-
- - .. row 3
-
- - __u32
-
- - ``data``\ [8]
-
- - Reserved for future extensions. Drivers and applications must set
- the array to zero.
-
-
-
-.. _encoder-cmds:
-
-.. flat-table:: Encoder Commands
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - ``V4L2_ENC_CMD_START``
-
- - 0
-
- - Start the encoder. When the encoder is already running or paused,
- this command does nothing. No flags are defined for this command.
-
- - .. row 2
-
- - ``V4L2_ENC_CMD_STOP``
-
- - 1
-
- - Stop the encoder. When the ``V4L2_ENC_CMD_STOP_AT_GOP_END`` flag
- is set, encoding will continue until the end of the current *Group
- Of Pictures*, otherwise encoding will stop immediately. When the
- encoder is already stopped, this command does nothing. mem2mem
- encoders will send a ``V4L2_EVENT_EOS`` event when the last frame
- has been encoded and all frames are ready to be dequeued and will
- set the ``V4L2_BUF_FLAG_LAST`` buffer flag on the last buffer of
- the capture queue to indicate there will be no new buffers
- produced to dequeue. This buffer may be empty, indicated by the
- driver setting the ``bytesused`` field to 0. Once the
- ``V4L2_BUF_FLAG_LAST`` flag was set, the
- :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will not block anymore,
- but return an ``EPIPE`` error code.
-
- - .. row 3
-
- - ``V4L2_ENC_CMD_PAUSE``
-
- - 2
-
- - Pause the encoder. When the encoder has not been started yet, the
- driver will return an ``EPERM`` error code. When the encoder is
- already paused, this command does nothing. No flags are defined
- for this command.
-
- - .. row 4
-
- - ``V4L2_ENC_CMD_RESUME``
-
- - 3
-
- - Resume encoding after a PAUSE command. When the encoder has not
- been started yet, the driver will return an ``EPERM`` error code. When
- the encoder is already running, this command does nothing. No
- flags are defined for this command.
-
-
-
-.. _encoder-flags:
-
-.. flat-table:: Encoder Command Flags
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - ``V4L2_ENC_CMD_STOP_AT_GOP_END``
-
- - 0x0001
-
- - Stop encoding at the end of the current *Group Of Pictures*,
- rather than immediately.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EINVAL
- The ``cmd`` field is invalid.
-
-EPERM
- The application sent a PAUSE or RESUME command when the encoder was
- not running.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_ENUM_DV_TIMINGS:
-
-***********************************************************
-ioctl VIDIOC_ENUM_DV_TIMINGS, VIDIOC_SUBDEV_ENUM_DV_TIMINGS
-***********************************************************
-
-Name
-====
-
-VIDIOC_ENUM_DV_TIMINGS - VIDIOC_SUBDEV_ENUM_DV_TIMINGS - Enumerate supported Digital Video timings
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_enum_dv_timings *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_ENUM_DV_TIMINGS, VIDIOC_SUBDEV_ENUM_DV_TIMINGS
-
-``argp``
-
-
-Description
-===========
-
-While some DV receivers or transmitters support a wide range of timings,
-others support only a limited number of timings. With this ioctl
-applications can enumerate a list of known supported timings. Call
-:ref:`VIDIOC_DV_TIMINGS_CAP` to check if it
-also supports other standards or even custom timings that are not in
-this list.
-
-To query the available timings, applications initialize the ``index``
-field, set the ``pad`` field to 0, zero the reserved array of struct
-:ref:`v4l2_enum_dv_timings <v4l2-enum-dv-timings>` and call the
-``VIDIOC_ENUM_DV_TIMINGS`` ioctl on a video node with a pointer to this
-structure. Drivers fill the rest of the structure or return an ``EINVAL``
-error code when the index is out of bounds. To enumerate all supported
-DV timings, applications shall begin at index zero, incrementing by one
-until the driver returns ``EINVAL``. Note that drivers may enumerate a
-different set of DV timings after switching the video input or output.
-
-When implemented by the driver DV timings of subdevices can be queried
-by calling the ``VIDIOC_SUBDEV_ENUM_DV_TIMINGS`` ioctl directly on a
-subdevice node. The DV timings are specific to inputs (for DV receivers)
-or outputs (for DV transmitters), applications must specify the desired
-pad number in the struct
-:ref:`v4l2_enum_dv_timings <v4l2-enum-dv-timings>` ``pad`` field.
-Attempts to enumerate timings on a pad that doesn't support them will
-return an ``EINVAL`` error code.
-
-
-.. _v4l2-enum-dv-timings:
-
-.. flat-table:: struct v4l2_enum_dv_timings
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``index``
-
- - Number of the DV timings, set by the application.
-
- - .. row 2
-
- - __u32
-
- - ``pad``
-
- - Pad number as reported by the media controller API. This field is
- only used when operating on a subdevice node. When operating on a
- video node applications must set this field to zero.
-
- - .. row 3
-
- - __u32
-
- - ``reserved``\ [2]
-
- - Reserved for future extensions. Drivers and applications must set
- the array to zero.
-
- - .. row 4
-
- - struct :ref:`v4l2_dv_timings <v4l2-dv-timings>`
-
- - ``timings``
-
- - The timings.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EINVAL
- The struct :ref:`v4l2_enum_dv_timings <v4l2-enum-dv-timings>`
- ``index`` is out of bounds or the ``pad`` number is invalid.
-
-ENODATA
- Digital video presets are not supported for this input or output.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_ENUM_FMT:
-
-*********************
-ioctl VIDIOC_ENUM_FMT
-*********************
-
-Name
-====
-
-VIDIOC_ENUM_FMT - Enumerate image formats
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_fmtdesc *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_ENUM_FMT
-
-``argp``
-
-
-Description
-===========
-
-To enumerate image formats applications initialize the ``type`` and
-``index`` field of struct :ref:`v4l2_fmtdesc <v4l2-fmtdesc>` and call
-the :ref:`VIDIOC_ENUM_FMT` ioctl with a pointer to this structure. Drivers
-fill the rest of the structure or return an ``EINVAL`` error code. All
-formats are enumerable by beginning at index zero and incrementing by
-one until ``EINVAL`` is returned.
-
-Note that after switching input or output the list of enumerated image
-formats may be different.
-
-
-.. _v4l2-fmtdesc:
-
-.. flat-table:: struct v4l2_fmtdesc
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``index``
-
- - Number of the format in the enumeration, set by the application.
- This is in no way related to the ``pixelformat`` field.
-
- - .. row 2
-
- - __u32
-
- - ``type``
-
- - Type of the data stream, set by the application. Only these types
- are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``,
- ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``,
- ``V4L2_BUF_TYPE_VIDEO_OUTPUT``,
- ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE`` and
- ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :ref:`v4l2-buf-type`.
-
- - .. row 3
-
- - __u32
-
- - ``flags``
-
- - See :ref:`fmtdesc-flags`
-
- - .. row 4
-
- - __u8
-
- - ``description``\ [32]
-
- - Description of the format, a NUL-terminated ASCII string. This
- information is intended for the user, for example: "YUV 4:2:2".
-
- - .. row 5
-
- - __u32
-
- - ``pixelformat``
-
- - The image format identifier. This is a four character code as
- computed by the v4l2_fourcc() macro:
-
- - .. row 6
-
- - :cspan:`2`
-
-
- .. _v4l2-fourcc:
- .. code-block:: c
-
- #define v4l2_fourcc(a,b,c,d) (((__u32)(a)<<0)|((__u32)(b)<<8)|((__u32)(c)<<16)|((__u32)(d)<<24))
-
- Several image formats are already defined by this specification in
- :ref:`pixfmt`. Note these codes are not the same as those used
- in the Windows world.
-
- - .. row 7
-
- - __u32
-
- - ``reserved``\ [4]
-
- - Reserved for future extensions. Drivers must set the array to
- zero.
-
-
-
-.. _fmtdesc-flags:
-
-.. flat-table:: Image Format Description Flags
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - ``V4L2_FMT_FLAG_COMPRESSED``
-
- - 0x0001
-
- - This is a compressed format.
-
- - .. row 2
-
- - ``V4L2_FMT_FLAG_EMULATED``
-
- - 0x0002
-
- - This format is not native to the device but emulated through
- software (usually libv4l2), where possible try to use a native
- format instead for better performance.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EINVAL
- The struct :ref:`v4l2_fmtdesc <v4l2-fmtdesc>` ``type`` is not
- supported or the ``index`` is out of bounds.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_ENUM_FRAMEINTERVALS:
-
-********************************
-ioctl VIDIOC_ENUM_FRAMEINTERVALS
-********************************
-
-Name
-====
-
-VIDIOC_ENUM_FRAMEINTERVALS - Enumerate frame intervals
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_frmivalenum *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_ENUM_FRAMEINTERVALS
-
-``argp``
- Pointer to a struct :ref:`v4l2_frmivalenum <v4l2-frmivalenum>`
- structure that contains a pixel format and size and receives a frame
- interval.
-
-
-Description
-===========
-
-This ioctl allows applications to enumerate all frame intervals that the
-device supports for the given pixel format and frame size.
-
-The supported pixel formats and frame sizes can be obtained by using the
-:ref:`VIDIOC_ENUM_FMT` and
-:ref:`VIDIOC_ENUM_FRAMESIZES` functions.
-
-The return value and the content of the ``v4l2_frmivalenum.type`` field
-depend on the type of frame intervals the device supports. Here are the
-semantics of the function for the different cases:
-
-- **Discrete:** The function returns success if the given index value
- (zero-based) is valid. The application should increase the index by
- one for each call until ``EINVAL`` is returned. The
- `v4l2_frmivalenum.type` field is set to
- `V4L2_FRMIVAL_TYPE_DISCRETE` by the driver. Of the union only
- the `discrete` member is valid.
-
-- **Step-wise:** The function returns success if the given index value
- is zero and ``EINVAL`` for any other index value. The
- ``v4l2_frmivalenum.type`` field is set to
- ``V4L2_FRMIVAL_TYPE_STEPWISE`` by the driver. Of the union only the
- ``stepwise`` member is valid.
-
-- **Continuous:** This is a special case of the step-wise type above.
- The function returns success if the given index value is zero and
- ``EINVAL`` for any other index value. The ``v4l2_frmivalenum.type``
- field is set to ``V4L2_FRMIVAL_TYPE_CONTINUOUS`` by the driver. Of
- the union only the ``stepwise`` member is valid and the ``step``
- value is set to 1.
-
-When the application calls the function with index zero, it must check
-the ``type`` field to determine the type of frame interval enumeration
-the device supports. Only for the ``V4L2_FRMIVAL_TYPE_DISCRETE`` type
-does it make sense to increase the index value to receive more frame
-intervals.
-
-Note that the order in which the frame intervals are returned has no
-special meaning. In particular does it not say anything about potential
-default frame intervals.
-
-Applications can assume that the enumeration data does not change
-without any interaction from the application itself. This means that the
-enumeration data is consistent if the application does not perform any
-other ioctl calls while it runs the frame interval enumeration.
-
-
-Notes
-=====
-
-- **Frame intervals and frame rates:** The V4L2 API uses frame
- intervals instead of frame rates. Given the frame interval the frame
- rate can be computed as follows:
-
-
-
- ::
-
- frame_rate = 1 / frame_interval
-
-
-Structs
-=======
-
-In the structs below, *IN* denotes a value that has to be filled in by
-the application, *OUT* denotes values that the driver fills in. The
-application should zero out all members except for the *IN* fields.
-
-
-.. _v4l2-frmival-stepwise:
-
-.. flat-table:: struct v4l2_frmival_stepwise
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - struct :ref:`v4l2_fract <v4l2-fract>`
-
- - ``min``
-
- - Minimum frame interval [s].
-
- - .. row 2
-
- - struct :ref:`v4l2_fract <v4l2-fract>`
-
- - ``max``
-
- - Maximum frame interval [s].
-
- - .. row 3
-
- - struct :ref:`v4l2_fract <v4l2-fract>`
-
- - ``step``
-
- - Frame interval step size [s].
-
-
-
-.. _v4l2-frmivalenum:
-
-.. flat-table:: struct v4l2_frmivalenum
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - __u32
-
- - ``index``
-
- -
- - IN: Index of the given frame interval in the enumeration.
-
- - .. row 2
-
- - __u32
-
- - ``pixel_format``
-
- -
- - IN: Pixel format for which the frame intervals are enumerated.
-
- - .. row 3
-
- - __u32
-
- - ``width``
-
- -
- - IN: Frame width for which the frame intervals are enumerated.
-
- - .. row 4
-
- - __u32
-
- - ``height``
-
- -
- - IN: Frame height for which the frame intervals are enumerated.
-
- - .. row 5
-
- - __u32
-
- - ``type``
-
- -
- - OUT: Frame interval type the device supports.
-
- - .. row 6
-
- - union
-
- -
- -
- - OUT: Frame interval with the given index.
-
- - .. row 7
-
- -
- - struct :ref:`v4l2_fract <v4l2-fract>`
-
- - ``discrete``
-
- - Frame interval [s].
-
- - .. row 8
-
- -
- - struct :ref:`v4l2_frmival_stepwise <v4l2-frmival-stepwise>`
-
- - ``stepwise``
-
- -
-
- - .. row 9
-
- - __u32
-
- - ``reserved[2]``
-
- -
- - Reserved space for future use. Must be zeroed by drivers and
- applications.
-
-
-
-Enums
-=====
-
-
-.. _v4l2-frmivaltypes:
-
-.. flat-table:: enum v4l2_frmivaltypes
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - ``V4L2_FRMIVAL_TYPE_DISCRETE``
-
- - 1
-
- - Discrete frame interval.
-
- - .. row 2
-
- - ``V4L2_FRMIVAL_TYPE_CONTINUOUS``
-
- - 2
-
- - Continuous frame interval.
-
- - .. row 3
-
- - ``V4L2_FRMIVAL_TYPE_STEPWISE``
-
- - 3
-
- - Step-wise defined frame interval.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_ENUM_FRAMESIZES:
-
-****************************
-ioctl VIDIOC_ENUM_FRAMESIZES
-****************************
-
-Name
-====
-
-VIDIOC_ENUM_FRAMESIZES - Enumerate frame sizes
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_frmsizeenum *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_ENUM_FRAMESIZES
-
-``argp``
- Pointer to a struct :ref:`v4l2_frmsizeenum <v4l2-frmsizeenum>`
- that contains an index and pixel format and receives a frame width
- and height.
-
-
-Description
-===========
-
-This ioctl allows applications to enumerate all frame sizes (i. e. width
-and height in pixels) that the device supports for the given pixel
-format.
-
-The supported pixel formats can be obtained by using the
-:ref:`VIDIOC_ENUM_FMT` function.
-
-The return value and the content of the ``v4l2_frmsizeenum.type`` field
-depend on the type of frame sizes the device supports. Here are the
-semantics of the function for the different cases:
-
-- **Discrete:** The function returns success if the given index value
- (zero-based) is valid. The application should increase the index by
- one for each call until ``EINVAL`` is returned. The
- ``v4l2_frmsizeenum.type`` field is set to
- ``V4L2_FRMSIZE_TYPE_DISCRETE`` by the driver. Of the union only the
- ``discrete`` member is valid.
-
-- **Step-wise:** The function returns success if the given index value
- is zero and ``EINVAL`` for any other index value. The
- ``v4l2_frmsizeenum.type`` field is set to
- ``V4L2_FRMSIZE_TYPE_STEPWISE`` by the driver. Of the union only the
- ``stepwise`` member is valid.
-
-- **Continuous:** This is a special case of the step-wise type above.
- The function returns success if the given index value is zero and
- ``EINVAL`` for any other index value. The ``v4l2_frmsizeenum.type``
- field is set to ``V4L2_FRMSIZE_TYPE_CONTINUOUS`` by the driver. Of
- the union only the ``stepwise`` member is valid and the
- ``step_width`` and ``step_height`` values are set to 1.
-
-When the application calls the function with index zero, it must check
-the ``type`` field to determine the type of frame size enumeration the
-device supports. Only for the ``V4L2_FRMSIZE_TYPE_DISCRETE`` type does
-it make sense to increase the index value to receive more frame sizes.
-
-Note that the order in which the frame sizes are returned has no special
-meaning. In particular does it not say anything about potential default
-format sizes.
-
-Applications can assume that the enumeration data does not change
-without any interaction from the application itself. This means that the
-enumeration data is consistent if the application does not perform any
-other ioctl calls while it runs the frame size enumeration.
-
-
-Structs
-=======
-
-In the structs below, *IN* denotes a value that has to be filled in by
-the application, *OUT* denotes values that the driver fills in. The
-application should zero out all members except for the *IN* fields.
-
-
-.. _v4l2-frmsize-discrete:
-
-.. flat-table:: struct v4l2_frmsize_discrete
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``width``
-
- - Width of the frame [pixel].
-
- - .. row 2
-
- - __u32
-
- - ``height``
-
- - Height of the frame [pixel].
-
-
-
-.. _v4l2-frmsize-stepwise:
-
-.. flat-table:: struct v4l2_frmsize_stepwise
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``min_width``
-
- - Minimum frame width [pixel].
-
- - .. row 2
-
- - __u32
-
- - ``max_width``
-
- - Maximum frame width [pixel].
-
- - .. row 3
-
- - __u32
-
- - ``step_width``
-
- - Frame width step size [pixel].
-
- - .. row 4
-
- - __u32
-
- - ``min_height``
-
- - Minimum frame height [pixel].
-
- - .. row 5
-
- - __u32
-
- - ``max_height``
-
- - Maximum frame height [pixel].
-
- - .. row 6
-
- - __u32
-
- - ``step_height``
-
- - Frame height step size [pixel].
-
-
-
-.. _v4l2-frmsizeenum:
-
-.. flat-table:: struct v4l2_frmsizeenum
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - __u32
-
- - ``index``
-
- -
- - IN: Index of the given frame size in the enumeration.
-
- - .. row 2
-
- - __u32
-
- - ``pixel_format``
-
- -
- - IN: Pixel format for which the frame sizes are enumerated.
-
- - .. row 3
-
- - __u32
-
- - ``type``
-
- -
- - OUT: Frame size type the device supports.
-
- - .. row 4
-
- - union
-
- -
- -
- - OUT: Frame size with the given index.
-
- - .. row 5
-
- -
- - struct :ref:`v4l2_frmsize_discrete <v4l2-frmsize-discrete>`
-
- - ``discrete``
-
- -
-
- - .. row 6
-
- -
- - struct :ref:`v4l2_frmsize_stepwise <v4l2-frmsize-stepwise>`
-
- - ``stepwise``
-
- -
-
- - .. row 7
-
- - __u32
-
- - ``reserved[2]``
-
- -
- - Reserved space for future use. Must be zeroed by drivers and
- applications.
-
-
-
-Enums
-=====
-
-
-.. _v4l2-frmsizetypes:
-
-.. flat-table:: enum v4l2_frmsizetypes
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - ``V4L2_FRMSIZE_TYPE_DISCRETE``
-
- - 1
-
- - Discrete frame size.
-
- - .. row 2
-
- - ``V4L2_FRMSIZE_TYPE_CONTINUOUS``
-
- - 2
-
- - Continuous frame size.
-
- - .. row 3
-
- - ``V4L2_FRMSIZE_TYPE_STEPWISE``
-
- - 3
-
- - Step-wise defined frame size.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_ENUM_FREQ_BANDS:
-
-****************************
-ioctl VIDIOC_ENUM_FREQ_BANDS
-****************************
-
-Name
-====
-
-VIDIOC_ENUM_FREQ_BANDS - Enumerate supported frequency bands
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_frequency_band *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_ENUM_FREQ_BANDS
-
-``argp``
-
-
-Description
-===========
-
-Enumerates the frequency bands that a tuner or modulator supports. To do
-this applications initialize the ``tuner``, ``type`` and ``index``
-fields, and zero out the ``reserved`` array of a struct
-:ref:`v4l2_frequency_band <v4l2-frequency-band>` and call the
-:ref:`VIDIOC_ENUM_FREQ_BANDS` ioctl with a pointer to this structure.
-
-This ioctl is supported if the ``V4L2_TUNER_CAP_FREQ_BANDS`` capability
-of the corresponding tuner/modulator is set.
-
-
-.. _v4l2-frequency-band:
-
-.. flat-table:: struct v4l2_frequency_band
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2 1 1
-
-
- - .. row 1
-
- - __u32
-
- - ``tuner``
-
- - The tuner or modulator index number. This is the same value as in
- the struct :ref:`v4l2_input <v4l2-input>` ``tuner`` field and
- the struct :ref:`v4l2_tuner <v4l2-tuner>` ``index`` field, or
- the struct :ref:`v4l2_output <v4l2-output>` ``modulator`` field
- and the struct :ref:`v4l2_modulator <v4l2-modulator>` ``index``
- field.
-
- - .. row 2
-
- - __u32
-
- - ``type``
-
- - The tuner type. This is the same value as in the struct
- :ref:`v4l2_tuner <v4l2-tuner>` ``type`` field. The type must be
- set to ``V4L2_TUNER_RADIO`` for ``/dev/radioX`` device nodes, and
- to ``V4L2_TUNER_ANALOG_TV`` for all others. Set this field to
- ``V4L2_TUNER_RADIO`` for modulators (currently only radio
- modulators are supported). See :ref:`v4l2-tuner-type`
-
- - .. row 3
-
- - __u32
-
- - ``index``
-
- - Identifies the frequency band, set by the application.
-
- - .. row 4
-
- - __u32
-
- - ``capability``
-
- - :cspan:`2` The tuner/modulator capability flags for this
- frequency band, see :ref:`tuner-capability`. The
- ``V4L2_TUNER_CAP_LOW`` or ``V4L2_TUNER_CAP_1HZ`` capability must
- be the same for all frequency bands of the selected
- tuner/modulator. So either all bands have that capability set, or
- none of them have that capability.
-
- - .. row 5
-
- - __u32
-
- - ``rangelow``
-
- - :cspan:`2` The lowest tunable frequency in units of 62.5 kHz, or
- if the ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in units
- of 62.5 Hz, for this frequency band. A 1 Hz unit is used when the
- ``capability`` flag ``V4L2_TUNER_CAP_1HZ`` is set.
-
- - .. row 6
-
- - __u32
-
- - ``rangehigh``
-
- - :cspan:`2` The highest tunable frequency in units of 62.5 kHz,
- or if the ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in
- units of 62.5 Hz, for this frequency band. A 1 Hz unit is used
- when the ``capability`` flag ``V4L2_TUNER_CAP_1HZ`` is set.
-
- - .. row 7
-
- - __u32
-
- - ``modulation``
-
- - :cspan:`2` The supported modulation systems of this frequency
- band. See :ref:`band-modulation`. Note that currently only one
- modulation system per frequency band is supported. More work will
- need to be done if multiple modulation systems are possible.
- Contact the linux-media mailing list
- (`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__)
- if you need that functionality.
-
- - .. row 8
-
- - __u32
-
- - ``reserved``\ [9]
-
- - Reserved for future extensions. Applications and drivers must set
- the array to zero.
-
-
-
-.. _band-modulation:
-
-.. flat-table:: Band Modulation Systems
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - ``V4L2_BAND_MODULATION_VSB``
-
- - 0x02
-
- - Vestigial Sideband modulation, used for analog TV.
-
- - .. row 2
-
- - ``V4L2_BAND_MODULATION_FM``
-
- - 0x04
-
- - Frequency Modulation, commonly used for analog radio.
-
- - .. row 3
-
- - ``V4L2_BAND_MODULATION_AM``
-
- - 0x08
-
- - Amplitude Modulation, commonly used for analog radio.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EINVAL
- The ``tuner`` or ``index`` is out of bounds or the ``type`` field is
- wrong.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_ENUMAUDIO:
-
-**********************
-ioctl VIDIOC_ENUMAUDIO
-**********************
-
-Name
-====
-
-VIDIOC_ENUMAUDIO - Enumerate audio inputs
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_audio *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_ENUMAUDIO
-
-``argp``
-
-
-Description
-===========
-
-To query the attributes of an audio input applications initialize the
-``index`` field and zero out the ``reserved`` array of a struct
-:ref:`v4l2_audio <v4l2-audio>` and call the :ref:`VIDIOC_ENUMAUDIO`
-ioctl with a pointer to this structure. Drivers fill the rest of the
-structure or return an ``EINVAL`` error code when the index is out of
-bounds. To enumerate all audio inputs applications shall begin at index
-zero, incrementing by one until the driver returns ``EINVAL``.
-
-See :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` for a description of struct
-:ref:`v4l2_audio <v4l2-audio>`.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EINVAL
- The number of the audio input is out of bounds.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_ENUMAUDOUT:
-
-***********************
-ioctl VIDIOC_ENUMAUDOUT
-***********************
-
-Name
-====
-
-VIDIOC_ENUMAUDOUT - Enumerate audio outputs
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_audioout *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_ENUMAUDOUT
-
-``argp``
-
-
-Description
-===========
-
-To query the attributes of an audio output applications initialize the
-``index`` field and zero out the ``reserved`` array of a struct
-:ref:`v4l2_audioout <v4l2-audioout>` and call the ``VIDIOC_G_AUDOUT``
-ioctl with a pointer to this structure. Drivers fill the rest of the
-structure or return an ``EINVAL`` error code when the index is out of
-bounds. To enumerate all audio outputs applications shall begin at index
-zero, incrementing by one until the driver returns ``EINVAL``.
-
-Note connectors on a TV card to loop back the received audio signal to a
-sound card are not audio outputs in this sense.
-
-See :ref:`VIDIOC_G_AUDIOout <VIDIOC_G_AUDOUT>` for a description of struct
-:ref:`v4l2_audioout <v4l2-audioout>`.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EINVAL
- The number of the audio output is out of bounds.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_ENUMINPUT:
-
-**********************
-ioctl VIDIOC_ENUMINPUT
-**********************
-
-Name
-====
-
-VIDIOC_ENUMINPUT - Enumerate video inputs
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_input *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_ENUMINPUT
-
-``argp``
-
-
-Description
-===========
-
-To query the attributes of a video input applications initialize the
-``index`` field of struct :ref:`v4l2_input <v4l2-input>` and call the
-:ref:`VIDIOC_ENUMINPUT` ioctl with a pointer to this structure. Drivers
-fill the rest of the structure or return an ``EINVAL`` error code when the
-index is out of bounds. To enumerate all inputs applications shall begin
-at index zero, incrementing by one until the driver returns ``EINVAL``.
-
-
-.. _v4l2-input:
-
-.. flat-table:: struct v4l2_input
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``index``
-
- - Identifies the input, set by the application.
-
- - .. row 2
-
- - __u8
-
- - ``name``\ [32]
-
- - Name of the video input, a NUL-terminated ASCII string, for
- example: "Vin (Composite 2)". This information is intended for the
- user, preferably the connector label on the device itself.
-
- - .. row 3
-
- - __u32
-
- - ``type``
-
- - Type of the input, see :ref:`input-type`.
-
- - .. row 4
-
- - __u32
-
- - ``audioset``
-
- - Drivers can enumerate up to 32 video and audio inputs. This field
- shows which audio inputs were selectable as audio source if this
- was the currently selected video input. It is a bit mask. The LSB
- corresponds to audio input 0, the MSB to input 31. Any number of
- bits can be set, or none.
-
- When the driver does not enumerate audio inputs no bits must be
- set. Applications shall not interpret this as lack of audio
- support. Some drivers automatically select audio sources and do
- not enumerate them since there is no choice anyway.
-
- For details on audio inputs and how to select the current input
- see :ref:`audio`.
-
- - .. row 5
-
- - __u32
-
- - ``tuner``
-
- - Capture devices can have zero or more tuners (RF demodulators).
- When the ``type`` is set to ``V4L2_INPUT_TYPE_TUNER`` this is an
- RF connector and this field identifies the tuner. It corresponds
- to struct :ref:`v4l2_tuner <v4l2-tuner>` field ``index``. For
- details on tuners see :ref:`tuner`.
-
- - .. row 6
-
- - :ref:`v4l2_std_id <v4l2-std-id>`
-
- - ``std``
-
- - Every video input supports one or more different video standards.
- This field is a set of all supported standards. For details on
- video standards and how to switch see :ref:`standard`.
-
- - .. row 7
-
- - __u32
-
- - ``status``
-
- - This field provides status information about the input. See
- :ref:`input-status` for flags. With the exception of the sensor
- orientation bits ``status`` is only valid when this is the current
- input.
-
- - .. row 8
-
- - __u32
-
- - ``capabilities``
-
- - This field provides capabilities for the input. See
- :ref:`input-capabilities` for flags.
-
- - .. row 9
-
- - __u32
-
- - ``reserved``\ [3]
-
- - Reserved for future extensions. Drivers must set the array to
- zero.
-
-
-
-.. _input-type:
-
-.. flat-table:: Input Types
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - ``V4L2_INPUT_TYPE_TUNER``
-
- - 1
-
- - This input uses a tuner (RF demodulator).
-
- - .. row 2
-
- - ``V4L2_INPUT_TYPE_CAMERA``
-
- - 2
-
- - Analog baseband input, for example CVBS / Composite Video,
- S-Video, RGB.
-
-
-
-.. _input-status:
-
-.. flat-table:: Input Status Flags
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - :cspan:`2` General
-
- - .. row 2
-
- - ``V4L2_IN_ST_NO_POWER``
-
- - 0x00000001
-
- - Attached device is off.
-
- - .. row 3
-
- - ``V4L2_IN_ST_NO_SIGNAL``
-
- - 0x00000002
-
- -
-
- - .. row 4
-
- - ``V4L2_IN_ST_NO_COLOR``
-
- - 0x00000004
-
- - The hardware supports color decoding, but does not detect color
- modulation in the signal.
-
- - .. row 5
-
- - :cspan:`2` Sensor Orientation
-
- - .. row 6
-
- - ``V4L2_IN_ST_HFLIP``
-
- - 0x00000010
-
- - The input is connected to a device that produces a signal that is
- flipped horizontally and does not correct this before passing the
- signal to userspace.
-
- - .. row 7
-
- - ``V4L2_IN_ST_VFLIP``
-
- - 0x00000020
-
- - The input is connected to a device that produces a signal that is
- flipped vertically and does not correct this before passing the
- signal to userspace. Note that a 180 degree rotation is the same
- as HFLIP | VFLIP
-
- - .. row 8
-
- - :cspan:`2` Analog Video
-
- - .. row 9
-
- - ``V4L2_IN_ST_NO_H_LOCK``
-
- - 0x00000100
-
- - No horizontal sync lock.
-
- - .. row 10
-
- - ``V4L2_IN_ST_COLOR_KILL``
-
- - 0x00000200
-
- - A color killer circuit automatically disables color decoding when
- it detects no color modulation. When this flag is set the color
- killer is enabled *and* has shut off color decoding.
-
- - .. row 11
-
- - :cspan:`2` Digital Video
-
- - .. row 12
-
- - ``V4L2_IN_ST_NO_SYNC``
-
- - 0x00010000
-
- - No synchronization lock.
-
- - .. row 13
-
- - ``V4L2_IN_ST_NO_EQU``
-
- - 0x00020000
-
- - No equalizer lock.
-
- - .. row 14
-
- - ``V4L2_IN_ST_NO_CARRIER``
-
- - 0x00040000
-
- - Carrier recovery failed.
-
- - .. row 15
-
- - :cspan:`2` VCR and Set-Top Box
-
- - .. row 16
-
- - ``V4L2_IN_ST_MACROVISION``
-
- - 0x01000000
-
- - Macrovision is an analog copy prevention system mangling the video
- signal to confuse video recorders. When this flag is set
- Macrovision has been detected.
-
- - .. row 17
-
- - ``V4L2_IN_ST_NO_ACCESS``
-
- - 0x02000000
-
- - Conditional access denied.
-
- - .. row 18
-
- - ``V4L2_IN_ST_VTR``
-
- - 0x04000000
-
- - VTR time constant. [?]
-
-
-
-.. _input-capabilities:
-
-.. flat-table:: Input capabilities
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - ``V4L2_IN_CAP_DV_TIMINGS``
-
- - 0x00000002
-
- - This input supports setting video timings by using
- VIDIOC_S_DV_TIMINGS.
-
- - .. row 2
-
- - ``V4L2_IN_CAP_STD``
-
- - 0x00000004
-
- - This input supports setting the TV standard by using
- VIDIOC_S_STD.
-
- - .. row 3
-
- - ``V4L2_IN_CAP_NATIVE_SIZE``
-
- - 0x00000008
-
- - This input supports setting the native size using the
- ``V4L2_SEL_TGT_NATIVE_SIZE`` selection target, see
- :ref:`v4l2-selections-common`.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EINVAL
- The struct :ref:`v4l2_input <v4l2-input>` ``index`` is out of
- bounds.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_ENUMOUTPUT:
-
-***********************
-ioctl VIDIOC_ENUMOUTPUT
-***********************
-
-Name
-====
-
-VIDIOC_ENUMOUTPUT - Enumerate video outputs
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_output *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_ENUMOUTPUT
-
-``argp``
-
-
-Description
-===========
-
-To query the attributes of a video outputs applications initialize the
-``index`` field of struct :ref:`v4l2_output <v4l2-output>` and call
-the :ref:`VIDIOC_ENUMOUTPUT` ioctl with a pointer to this structure.
-Drivers fill the rest of the structure or return an ``EINVAL`` error code
-when the index is out of bounds. To enumerate all outputs applications
-shall begin at index zero, incrementing by one until the driver returns
-EINVAL.
-
-
-.. _v4l2-output:
-
-.. flat-table:: struct v4l2_output
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``index``
-
- - Identifies the output, set by the application.
-
- - .. row 2
-
- - __u8
-
- - ``name``\ [32]
-
- - Name of the video output, a NUL-terminated ASCII string, for
- example: "Vout". This information is intended for the user,
- preferably the connector label on the device itself.
-
- - .. row 3
-
- - __u32
-
- - ``type``
-
- - Type of the output, see :ref:`output-type`.
-
- - .. row 4
-
- - __u32
-
- - ``audioset``
-
- - Drivers can enumerate up to 32 video and audio outputs. This field
- shows which audio outputs were selectable as the current output if
- this was the currently selected video output. It is a bit mask.
- The LSB corresponds to audio output 0, the MSB to output 31. Any
- number of bits can be set, or none.
-
- When the driver does not enumerate audio outputs no bits must be
- set. Applications shall not interpret this as lack of audio
- support. Drivers may automatically select audio outputs without
- enumerating them.
-
- For details on audio outputs and how to select the current output
- see :ref:`audio`.
-
- - .. row 5
-
- - __u32
-
- - ``modulator``
-
- - Output devices can have zero or more RF modulators. When the
- ``type`` is ``V4L2_OUTPUT_TYPE_MODULATOR`` this is an RF connector
- and this field identifies the modulator. It corresponds to struct
- :ref:`v4l2_modulator <v4l2-modulator>` field ``index``. For
- details on modulators see :ref:`tuner`.
-
- - .. row 6
-
- - :ref:`v4l2_std_id <v4l2-std-id>`
-
- - ``std``
-
- - Every video output supports one or more different video standards.
- This field is a set of all supported standards. For details on
- video standards and how to switch see :ref:`standard`.
-
- - .. row 7
-
- - __u32
-
- - ``capabilities``
-
- - This field provides capabilities for the output. See
- :ref:`output-capabilities` for flags.
-
- - .. row 8
-
- - __u32
-
- - ``reserved``\ [3]
-
- - Reserved for future extensions. Drivers must set the array to
- zero.
-
-
-
-.. _output-type:
-
-.. flat-table:: Output Type
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - ``V4L2_OUTPUT_TYPE_MODULATOR``
-
- - 1
-
- - This output is an analog TV modulator.
-
- - .. row 2
-
- - ``V4L2_OUTPUT_TYPE_ANALOG``
-
- - 2
-
- - Analog baseband output, for example Composite / CVBS, S-Video,
- RGB.
-
- - .. row 3
-
- - ``V4L2_OUTPUT_TYPE_ANALOGVGAOVERLAY``
-
- - 3
-
- - [?]
-
-
-
-.. _output-capabilities:
-
-.. flat-table:: Output capabilities
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - ``V4L2_OUT_CAP_DV_TIMINGS``
-
- - 0x00000002
-
- - This output supports setting video timings by using
- VIDIOC_S_DV_TIMINGS.
-
- - .. row 2
-
- - ``V4L2_OUT_CAP_STD``
-
- - 0x00000004
-
- - This output supports setting the TV standard by using
- VIDIOC_S_STD.
-
- - .. row 3
-
- - ``V4L2_OUT_CAP_NATIVE_SIZE``
-
- - 0x00000008
-
- - This output supports setting the native size using the
- ``V4L2_SEL_TGT_NATIVE_SIZE`` selection target, see
- :ref:`v4l2-selections-common`.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EINVAL
- The struct :ref:`v4l2_output <v4l2-output>` ``index`` is out of
- bounds.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_ENUMSTD:
-
-********************
-ioctl VIDIOC_ENUMSTD
-********************
-
-Name
-====
-
-VIDIOC_ENUMSTD - Enumerate supported video standards
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_standard *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_ENUMSTD
-
-``argp``
-
-
-Description
-===========
-
-To query the attributes of a video standard, especially a custom (driver
-defined) one, applications initialize the ``index`` field of struct
-:ref:`v4l2_standard <v4l2-standard>` and call the :ref:`VIDIOC_ENUMSTD`
-ioctl with a pointer to this structure. Drivers fill the rest of the
-structure or return an ``EINVAL`` error code when the index is out of
-bounds. To enumerate all standards applications shall begin at index
-zero, incrementing by one until the driver returns ``EINVAL``. Drivers may
-enumerate a different set of standards after switching the video input
-or output. [1]_
-
-
-.. _v4l2-standard:
-
-.. flat-table:: struct v4l2_standard
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``index``
-
- - Number of the video standard, set by the application.
-
- - .. row 2
-
- - :ref:`v4l2_std_id <v4l2-std-id>`
-
- - ``id``
-
- - The bits in this field identify the standard as one of the common
- standards listed in :ref:`v4l2-std-id`, or if bits 32 to 63 are
- set as custom standards. Multiple bits can be set if the hardware
- does not distinguish between these standards, however separate
- indices do not indicate the opposite. The ``id`` must be unique.
- No other enumerated :ref:`struct v4l2_standard <v4l2-standard>` structure,
- for this input or output anyway, can contain the same set of bits.
-
- - .. row 3
-
- - __u8
-
- - ``name``\ [24]
-
- - Name of the standard, a NUL-terminated ASCII string, for example:
- "PAL-B/G", "NTSC Japan". This information is intended for the
- user.
-
- - .. row 4
-
- - struct :ref:`v4l2_fract <v4l2-fract>`
-
- - ``frameperiod``
-
- - The frame period (not field period) is numerator / denominator.
- For example M/NTSC has a frame period of 1001 / 30000 seconds.
-
- - .. row 5
-
- - __u32
-
- - ``framelines``
-
- - Total lines per frame including blanking, e. g. 625 for B/PAL.
-
- - .. row 6
-
- - __u32
-
- - ``reserved``\ [4]
-
- - Reserved for future extensions. Drivers must set the array to
- zero.
-
-
-
-.. _v4l2-fract:
-
-.. flat-table:: struct v4l2_fract
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``numerator``
-
- -
-
- - .. row 2
-
- - __u32
-
- - ``denominator``
-
- -
-
-
-
-.. _v4l2-std-id:
-
-.. flat-table:: typedef v4l2_std_id
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u64
-
- - ``v4l2_std_id``
-
- - This type is a set, each bit representing another video standard
- as listed below and in :ref:`video-standards`. The 32 most
- significant bits are reserved for custom (driver defined) video
- standards.
-
-
-
-.. code-block:: c
-
- #define V4L2_STD_PAL_B ((v4l2_std_id)0x00000001)
- #define V4L2_STD_PAL_B1 ((v4l2_std_id)0x00000002)
- #define V4L2_STD_PAL_G ((v4l2_std_id)0x00000004)
- #define V4L2_STD_PAL_H ((v4l2_std_id)0x00000008)
- #define V4L2_STD_PAL_I ((v4l2_std_id)0x00000010)
- #define V4L2_STD_PAL_D ((v4l2_std_id)0x00000020)
- #define V4L2_STD_PAL_D1 ((v4l2_std_id)0x00000040)
- #define V4L2_STD_PAL_K ((v4l2_std_id)0x00000080)
-
- #define V4L2_STD_PAL_M ((v4l2_std_id)0x00000100)
- #define V4L2_STD_PAL_N ((v4l2_std_id)0x00000200)
- #define V4L2_STD_PAL_Nc ((v4l2_std_id)0x00000400)
- #define V4L2_STD_PAL_60 ((v4l2_std_id)0x00000800)
-
-``V4L2_STD_PAL_60`` is a hybrid standard with 525 lines, 60 Hz refresh
-rate, and PAL color modulation with a 4.43 MHz color subcarrier. Some
-PAL video recorders can play back NTSC tapes in this mode for display on
-a 50/60 Hz agnostic PAL TV.
-
-
-.. code-block:: c
-
- #define V4L2_STD_NTSC_M ((v4l2_std_id)0x00001000)
- #define V4L2_STD_NTSC_M_JP ((v4l2_std_id)0x00002000)
- #define V4L2_STD_NTSC_443 ((v4l2_std_id)0x00004000)
-
-``V4L2_STD_NTSC_443`` is a hybrid standard with 525 lines, 60 Hz refresh
-rate, and NTSC color modulation with a 4.43 MHz color subcarrier.
-
-
-.. code-block:: c
-
- #define V4L2_STD_NTSC_M_KR ((v4l2_std_id)0x00008000)
-
- #define V4L2_STD_SECAM_B ((v4l2_std_id)0x00010000)
- #define V4L2_STD_SECAM_D ((v4l2_std_id)0x00020000)
- #define V4L2_STD_SECAM_G ((v4l2_std_id)0x00040000)
- #define V4L2_STD_SECAM_H ((v4l2_std_id)0x00080000)
- #define V4L2_STD_SECAM_K ((v4l2_std_id)0x00100000)
- #define V4L2_STD_SECAM_K1 ((v4l2_std_id)0x00200000)
- #define V4L2_STD_SECAM_L ((v4l2_std_id)0x00400000)
- #define V4L2_STD_SECAM_LC ((v4l2_std_id)0x00800000)
-
- /* ATSC/HDTV */
- #define V4L2_STD_ATSC_8_VSB ((v4l2_std_id)0x01000000)
- #define V4L2_STD_ATSC_16_VSB ((v4l2_std_id)0x02000000)
-
-``V4L2_STD_ATSC_8_VSB`` and ``V4L2_STD_ATSC_16_VSB`` are U.S.
-terrestrial digital TV standards. Presently the V4L2 API does not
-support digital TV. See also the Linux DVB API at
-`https://linuxtv.org <https://linuxtv.org>`__.
-
-
-.. code-block:: c
-
- #define V4L2_STD_PAL_BG (V4L2_STD_PAL_B |
- V4L2_STD_PAL_B1 |
- V4L2_STD_PAL_G)
- #define V4L2_STD_B (V4L2_STD_PAL_B |
- V4L2_STD_PAL_B1 |
- V4L2_STD_SECAM_B)
- #define V4L2_STD_GH (V4L2_STD_PAL_G |
- V4L2_STD_PAL_H |
- V4L2_STD_SECAM_G |
- V4L2_STD_SECAM_H)
- #define V4L2_STD_PAL_DK (V4L2_STD_PAL_D |
- V4L2_STD_PAL_D1 |
- V4L2_STD_PAL_K)
- #define V4L2_STD_PAL (V4L2_STD_PAL_BG |
- V4L2_STD_PAL_DK |
- V4L2_STD_PAL_H |
- V4L2_STD_PAL_I)
- #define V4L2_STD_NTSC (V4L2_STD_NTSC_M |
- V4L2_STD_NTSC_M_JP |
- V4L2_STD_NTSC_M_KR)
- #define V4L2_STD_MN (V4L2_STD_PAL_M |
- V4L2_STD_PAL_N |
- V4L2_STD_PAL_Nc |
- V4L2_STD_NTSC)
- #define V4L2_STD_SECAM_DK (V4L2_STD_SECAM_D |
- V4L2_STD_SECAM_K |
- V4L2_STD_SECAM_K1)
- #define V4L2_STD_DK (V4L2_STD_PAL_DK |
- V4L2_STD_SECAM_DK)
-
- #define V4L2_STD_SECAM (V4L2_STD_SECAM_B |
- V4L2_STD_SECAM_G |
- V4L2_STD_SECAM_H |
- V4L2_STD_SECAM_DK |
- V4L2_STD_SECAM_L |
- V4L2_STD_SECAM_LC)
-
- #define V4L2_STD_525_60 (V4L2_STD_PAL_M |
- V4L2_STD_PAL_60 |
- V4L2_STD_NTSC |
- V4L2_STD_NTSC_443)
- #define V4L2_STD_625_50 (V4L2_STD_PAL |
- V4L2_STD_PAL_N |
- V4L2_STD_PAL_Nc |
- V4L2_STD_SECAM)
-
- #define V4L2_STD_UNKNOWN 0
- #define V4L2_STD_ALL (V4L2_STD_525_60 |
- V4L2_STD_625_50)
-
-
-.. _video-standards:
-
-.. flat-table:: Video Standards (based on [])
- :header-rows: 1
- :stub-columns: 0
-
-
- - .. row 1
-
- - Characteristics
-
- - M/NTSC [2]_
-
- - M/PAL
-
- - N/PAL [3]_
-
- - B, B1, G/PAL
-
- - D, D1, K/PAL
-
- - H/PAL
-
- - I/PAL
-
- - B, G/SECAM
-
- - D, K/SECAM
-
- - K1/SECAM
-
- - L/SECAM
-
- - .. row 2
-
- - Frame lines
-
- - :cspan:`1` 525
-
- - :cspan:`9` 625
-
- - .. row 3
-
- - Frame period (s)
-
- - :cspan:`1` 1001/30000
-
- - :cspan:`9` 1/25
-
- - .. row 4
-
- - Chrominance sub-carrier frequency (Hz)
-
- - 3579545 ± 10
-
- - 3579611.49 ± 10
-
- - 4433618.75 ± 5 (3582056.25 ± 5)
-
- - :cspan:`3` 4433618.75 ± 5
-
- - 4433618.75 ± 1
-
- - :cspan:`3` f\ :sub:`OR` = 4406250 ± 2000, f\ :sub:`OB` = 4250000
- ± 2000
-
- - .. row 5
-
- - Nominal radio-frequency channel bandwidth (MHz)
-
- - 6
-
- - 6
-
- - 6
-
- - B: 7; B1, G: 8
-
- - 8
-
- - 8
-
- - 8
-
- - 8
-
- - 8
-
- - 8
-
- - 8
-
- - .. row 6
-
- - Sound carrier relative to vision carrier (MHz)
-
- - + 4.5
-
- - + 4.5
-
- - + 4.5
-
- - + 5.5 ± 0.001 [4]_ [5]_ [6]_ [7]_
-
- - + 6.5 ± 0.001
-
- - + 5.5
-
- - + 5.9996 ± 0.0005
-
- - + 5.5 ± 0.001
-
- - + 6.5 ± 0.001
-
- - + 6.5
-
- - + 6.5 [8]_
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EINVAL
- The struct :ref:`v4l2_standard <v4l2-standard>` ``index`` is out
- of bounds.
-
-ENODATA
- Standard video timings are not supported for this input or output.
-
-.. [1]
- The supported standards may overlap and we need an unambiguous set to
- find the current standard returned by :ref:`VIDIOC_G_STD <VIDIOC_G_STD>`.
-
-.. [2]
- Japan uses a standard similar to M/NTSC (V4L2_STD_NTSC_M_JP).
-
-.. [3]
- The values in brackets apply to the combination N/PAL a.k.a.
- N\ :sub:`C` used in Argentina (V4L2_STD_PAL_Nc).
-
-.. [4]
- In the Federal Republic of Germany, Austria, Italy, the Netherlands,
- Slovakia and Switzerland a system of two sound carriers is used, the
- frequency of the second carrier being 242.1875 kHz above the
- frequency of the first sound carrier. For stereophonic sound
- transmissions a similar system is used in Australia.
-
-.. [5]
- New Zealand uses a sound carrier displaced 5.4996 ± 0.0005 MHz from
- the vision carrier.
-
-.. [6]
- In Denmark, Finland, New Zealand, Sweden and Spain a system of two
- sound carriers is used. In Iceland, Norway and Poland the same system
- is being introduced. The second carrier is 5.85 MHz above the vision
- carrier and is DQPSK modulated with 728 kbit/s sound and data
- multiplex. (NICAM system)
-
-.. [7]
- In the United Kingdom, a system of two sound carriers is used. The
- second sound carrier is 6.552 MHz above the vision carrier and is
- DQPSK modulated with a 728 kbit/s sound and data multiplex able to
- carry two sound channels. (NICAM system)
-
-.. [8]
- In France, a digital carrier 5.85 MHz away from the vision carrier
- may be used in addition to the main sound carrier. It is modulated in
- differentially encoded QPSK with a 728 kbit/s sound and data
- multiplexer capable of carrying two sound channels. (NICAM system)
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_EXPBUF:
-
-*******************
-ioctl VIDIOC_EXPBUF
-*******************
-
-Name
-====
-
-VIDIOC_EXPBUF - Export a buffer as a DMABUF file descriptor.
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_exportbuffer *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_EXPBUF
-
-``argp``
-
-
-Description
-===========
-
-This ioctl is an extension to the :ref:`memory mapping <mmap>` I/O
-method, therefore it is available only for ``V4L2_MEMORY_MMAP`` buffers.
-It can be used to export a buffer as a DMABUF file at any time after
-buffers have been allocated with the
-:ref:`VIDIOC_REQBUFS` ioctl.
-
-To export a buffer, applications fill struct
-:ref:`v4l2_exportbuffer <v4l2-exportbuffer>`. The ``type`` field is
-set to the same buffer type as was previously used with struct
-:ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``type``.
-Applications must also set the ``index`` field. Valid index numbers
-range from zero to the number of buffers allocated with
-:ref:`VIDIOC_REQBUFS` (struct
-:ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``count``) minus
-one. For the multi-planar API, applications set the ``plane`` field to
-the index of the plane to be exported. Valid planes range from zero to
-the maximal number of valid planes for the currently active format. For
-the single-planar API, applications must set ``plane`` to zero.
-Additional flags may be posted in the ``flags`` field. Refer to a manual
-for open() for details. Currently only O_CLOEXEC, O_RDONLY, O_WRONLY,
-and O_RDWR are supported. All other fields must be set to zero. In the
-case of multi-planar API, every plane is exported separately using
-multiple :ref:`VIDIOC_EXPBUF` calls.
-
-After calling :ref:`VIDIOC_EXPBUF` the ``fd`` field will be set by a
-driver. This is a DMABUF file descriptor. The application may pass it to
-other DMABUF-aware devices. Refer to :ref:`DMABUF importing <dmabuf>`
-for details about importing DMABUF files into V4L2 nodes. It is
-recommended to close a DMABUF file when it is no longer used to allow
-the associated memory to be reclaimed.
-
-
-Examples
-========
-
-
-.. code-block:: c
-
- int buffer_export(int v4lfd, enum v4l2_buf_type bt, int index, int *dmafd)
- {
- struct v4l2_exportbuffer expbuf;
-
- memset(&expbuf, 0, sizeof(expbuf));
- expbuf.type = bt;
- expbuf.index = index;
- if (ioctl(v4lfd, VIDIOC_EXPBUF, &expbuf) == -1) {
- perror("VIDIOC_EXPBUF");
- return -1;
- }
-
- *dmafd = expbuf.fd;
-
- return 0;
- }
-
-
-.. code-block:: c
-
- int buffer_export_mp(int v4lfd, enum v4l2_buf_type bt, int index,
- int dmafd[], int n_planes)
- {
- int i;
-
- for (i = 0; i < n_planes; ++i) {
- struct v4l2_exportbuffer expbuf;
-
- memset(&expbuf, 0, sizeof(expbuf));
- expbuf.type = bt;
- expbuf.index = index;
- expbuf.plane = i;
- if (ioctl(v4lfd, VIDIOC_EXPBUF, &expbuf) == -1) {
- perror("VIDIOC_EXPBUF");
- while (i)
- close(dmafd[--i]);
- return -1;
- }
- dmafd[i] = expbuf.fd;
- }
-
- return 0;
- }
-
-
-.. _v4l2-exportbuffer:
-
-.. flat-table:: struct v4l2_exportbuffer
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``type``
-
- - Type of the buffer, same as struct
- :ref:`v4l2_format <v4l2-format>` ``type`` or struct
- :ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``type``, set
- by the application. See :ref:`v4l2-buf-type`
-
- - .. row 2
-
- - __u32
-
- - ``index``
-
- - Number of the buffer, set by the application. This field is only
- used for :ref:`memory mapping <mmap>` I/O and can range from
- zero to the number of buffers allocated with the
- :ref:`VIDIOC_REQBUFS` and/or
- :ref:`VIDIOC_CREATE_BUFS` ioctls.
-
- - .. row 3
-
- - __u32
-
- - ``plane``
-
- - Index of the plane to be exported when using the multi-planar API.
- Otherwise this value must be set to zero.
-
- - .. row 4
-
- - __u32
-
- - ``flags``
-
- - Flags for the newly created file, currently only ``O_CLOEXEC``,
- ``O_RDONLY``, ``O_WRONLY``, and ``O_RDWR`` are supported, refer to
- the manual of open() for more details.
-
- - .. row 5
-
- - __s32
-
- - ``fd``
-
- - The DMABUF file descriptor associated with a buffer. Set by the
- driver.
-
- - .. row 6
-
- - __u32
-
- - ``reserved[11]``
-
- - Reserved field for future use. Drivers and applications must set
- the array to zero.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EINVAL
- A queue is not in MMAP mode or DMABUF exporting is not supported or
- ``flags`` or ``type`` or ``index`` or ``plane`` fields are invalid.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_G_AUDIO:
-
-************************************
-ioctl VIDIOC_G_AUDIO, VIDIOC_S_AUDIO
-************************************
-
-Name
-====
-
-VIDIOC_G_AUDIO - VIDIOC_S_AUDIO - Query or select the current audio input and its attributes
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_audio *argp )
-
-.. cpp:function:: int ioctl( int fd, int request, const struct v4l2_audio *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_G_AUDIO, VIDIOC_S_AUDIO
-
-``argp``
-
-
-Description
-===========
-
-To query the current audio input applications zero out the ``reserved``
-array of a struct :ref:`v4l2_audio <v4l2-audio>` and call the
-:ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` ioctl with a pointer to this structure. Drivers fill
-the rest of the structure or return an ``EINVAL`` error code when the device
-has no audio inputs, or none which combine with the current video input.
-
-Audio inputs have one writable property, the audio mode. To select the
-current audio input *and* change the audio mode, applications initialize
-the ``index`` and ``mode`` fields, and the ``reserved`` array of a
-:ref:`struct v4l2_audio <v4l2-audio>` structure and call the :ref:`VIDIOC_S_AUDIO <VIDIOC_G_AUDIO>`
-ioctl. Drivers may switch to a different audio mode if the request
-cannot be satisfied. However, this is a write-only ioctl, it does not
-return the actual new audio mode.
-
-
-.. _v4l2-audio:
-
-.. flat-table:: struct v4l2_audio
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``index``
-
- - Identifies the audio input, set by the driver or application.
-
- - .. row 2
-
- - __u8
-
- - ``name``\ [32]
-
- - Name of the audio input, a NUL-terminated ASCII string, for
- example: "Line In". This information is intended for the user,
- preferably the connector label on the device itself.
-
- - .. row 3
-
- - __u32
-
- - ``capability``
-
- - Audio capability flags, see :ref:`audio-capability`.
-
- - .. row 4
-
- - __u32
-
- - ``mode``
-
- - Audio mode flags set by drivers and applications (on
- :ref:`VIDIOC_S_AUDIO <VIDIOC_G_AUDIO>` ioctl), see :ref:`audio-mode`.
-
- - .. row 5
-
- - __u32
-
- - ``reserved``\ [2]
-
- - Reserved for future extensions. Drivers and applications must set
- the array to zero.
-
-
-
-.. _audio-capability:
-
-.. flat-table:: Audio Capability Flags
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - ``V4L2_AUDCAP_STEREO``
-
- - 0x00001
-
- - This is a stereo input. The flag is intended to automatically
- disable stereo recording etc. when the signal is always monaural.
- The API provides no means to detect if stereo is *received*,
- unless the audio input belongs to a tuner.
-
- - .. row 2
-
- - ``V4L2_AUDCAP_AVL``
-
- - 0x00002
-
- - Automatic Volume Level mode is supported.
-
-
-
-.. _audio-mode:
-
-.. flat-table:: Audio Mode Flags
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - ``V4L2_AUDMODE_AVL``
-
- - 0x00001
-
- - AVL mode is on.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EINVAL
- No audio inputs combine with the current video input, or the number
- of the selected audio input is out of bounds or it does not combine.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_G_AUDOUT:
-
-**************************************
-ioctl VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT
-**************************************
-
-Name
-====
-
-VIDIOC_G_AUDOUT - VIDIOC_S_AUDOUT - Query or select the current audio output
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_audioout *argp )
-
-.. cpp:function:: int ioctl( int fd, int request, const struct v4l2_audioout *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT
-
-``argp``
-
-
-Description
-===========
-
-To query the current audio output applications zero out the ``reserved``
-array of a struct :ref:`v4l2_audioout <v4l2-audioout>` and call the
-``VIDIOC_G_AUDOUT`` ioctl with a pointer to this structure. Drivers fill
-the rest of the structure or return an ``EINVAL`` error code when the device
-has no audio inputs, or none which combine with the current video
-output.
-
-Audio outputs have no writable properties. Nevertheless, to select the
-current audio output applications can initialize the ``index`` field and
-``reserved`` array (which in the future may contain writable properties)
-of a :ref:`struct v4l2_audioout <v4l2-audioout>` structure and call the
-``VIDIOC_S_AUDOUT`` ioctl. Drivers switch to the requested output or
-return the ``EINVAL`` error code when the index is out of bounds. This is a
-write-only ioctl, it does not return the current audio output attributes
-as ``VIDIOC_G_AUDOUT`` does.
-
-Note connectors on a TV card to loop back the received audio signal to a
-sound card are not audio outputs in this sense.
-
-
-.. _v4l2-audioout:
-
-.. flat-table:: struct v4l2_audioout
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``index``
-
- - Identifies the audio output, set by the driver or application.
-
- - .. row 2
-
- - __u8
-
- - ``name``\ [32]
-
- - Name of the audio output, a NUL-terminated ASCII string, for
- example: "Line Out". This information is intended for the user,
- preferably the connector label on the device itself.
-
- - .. row 3
-
- - __u32
-
- - ``capability``
-
- - Audio capability flags, none defined yet. Drivers must set this
- field to zero.
-
- - .. row 4
-
- - __u32
-
- - ``mode``
-
- - Audio mode, none defined yet. Drivers and applications (on
- ``VIDIOC_S_AUDOUT``) must set this field to zero.
-
- - .. row 5
-
- - __u32
-
- - ``reserved``\ [2]
-
- - Reserved for future extensions. Drivers and applications must set
- the array to zero.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EINVAL
- No audio outputs combine with the current video output, or the
- number of the selected audio output is out of bounds or it does not
- combine.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_G_CROP:
-
-**********************************
-ioctl VIDIOC_G_CROP, VIDIOC_S_CROP
-**********************************
-
-Name
-====
-
-VIDIOC_G_CROP - VIDIOC_S_CROP - Get or set the current cropping rectangle
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_crop *argp )
-
-.. cpp:function:: int ioctl( int fd, int request, const struct v4l2_crop *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_G_CROP, VIDIOC_S_CROP
-
-``argp``
-
-
-Description
-===========
-
-To query the cropping rectangle size and position applications set the
-``type`` field of a :ref:`struct v4l2_crop <v4l2-crop>` structure to the
-respective buffer (stream) type and call the :ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` ioctl
-with a pointer to this structure. The driver fills the rest of the
-structure or returns the ``EINVAL`` error code if cropping is not supported.
-
-To change the cropping rectangle applications initialize the ``type``
-and struct :ref:`v4l2_rect <v4l2-rect>` substructure named ``c`` of a
-v4l2_crop structure and call the :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` ioctl with a pointer
-to this structure.
-
-Do not use the multiplanar buffer types. Use
-``V4L2_BUF_TYPE_VIDEO_CAPTURE`` instead of
-``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and use
-``V4L2_BUF_TYPE_VIDEO_OUTPUT`` instead of
-``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``.
-
-The driver first adjusts the requested dimensions against hardware
-limits, i. e. the bounds given by the capture/output window, and it
-rounds to the closest possible values of horizontal and vertical offset,
-width and height. In particular the driver must round the vertical
-offset of the cropping rectangle to frame lines modulo two, such that
-the field order cannot be confused.
-
-Second the driver adjusts the image size (the opposite rectangle of the
-scaling process, source or target depending on the data direction) to
-the closest size possible while maintaining the current horizontal and
-vertical scaling factor.
-
-Finally the driver programs the hardware with the actual cropping and
-image parameters. :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` is a write-only ioctl, it does not
-return the actual parameters. To query them applications must call
-:ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and :ref:`VIDIOC_G_FMT`. When the
-parameters are unsuitable the application may modify the cropping or
-image parameters and repeat the cycle until satisfactory parameters have
-been negotiated.
-
-When cropping is not supported then no parameters are changed and
-:ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` returns the ``EINVAL`` error code.
-
-
-.. _v4l2-crop:
-
-.. flat-table:: struct v4l2_crop
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``type``
-
- - Type of the data stream, set by the application. Only these types
- are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``,
- ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` and
- ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :ref:`v4l2-buf-type`.
-
- - .. row 2
-
- - struct :ref:`v4l2_rect <v4l2-rect>`
-
- - ``c``
-
- - Cropping rectangle. The same co-ordinate system as for struct
- :ref:`v4l2_cropcap <v4l2-cropcap>` ``bounds`` is used.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_G_CTRL:
-
-**********************************
-ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL
-**********************************
-
-Name
-====
-
-VIDIOC_G_CTRL - VIDIOC_S_CTRL - Get or set the value of a control
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_control *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_G_CTRL, VIDIOC_S_CTRL
-
-``argp``
-
-
-Description
-===========
-
-To get the current value of a control applications initialize the ``id``
-field of a struct :ref:`struct v4l2_control <v4l2-control>` and call the
-:ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` ioctl with a pointer to this structure. To change the
-value of a control applications initialize the ``id`` and ``value``
-fields of a struct :ref:`struct v4l2_control <v4l2-control>` and call the
-:ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctl.
-
-When the ``id`` is invalid drivers return an ``EINVAL`` error code. When the
-``value`` is out of bounds drivers can choose to take the closest valid
-value or return an ``ERANGE`` error code, whatever seems more appropriate.
-However, :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` is a write-only ioctl, it does not return the
-actual new value. If the ``value`` is inappropriate for the control
-(e.g. if it refers to an unsupported menu index of a menu control), then
-EINVAL error code is returned as well.
-
-These ioctls work only with user controls. For other control classes the
-:ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`,
-:ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` or
-:ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` must be used.
-
-
-.. _v4l2-control:
-
-.. flat-table:: struct v4l2_control
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``id``
-
- - Identifies the control, set by the application.
-
- - .. row 2
-
- - __s32
-
- - ``value``
-
- - New value or current value.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EINVAL
- The struct :ref:`v4l2_control <v4l2-control>` ``id`` is invalid
- or the ``value`` is inappropriate for the given control (i.e. if a
- menu item is selected that is not supported by the driver according
- to :ref:`VIDIOC_QUERYMENU <VIDIOC_QUERYCTRL>`).
-
-ERANGE
- The struct :ref:`v4l2_control <v4l2-control>` ``value`` is out of
- bounds.
-
-EBUSY
- The control is temporarily not changeable, possibly because another
- applications took over control of the device function this control
- belongs to.
-
-EACCES
- Attempt to set a read-only control or to get a write-only control.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_G_DV_TIMINGS:
-
-**********************************************
-ioctl VIDIOC_G_DV_TIMINGS, VIDIOC_S_DV_TIMINGS
-**********************************************
-
-Name
-====
-
-VIDIOC_G_DV_TIMINGS - VIDIOC_S_DV_TIMINGS - VIDIOC_SUBDEV_G_DV_TIMINGS - VIDIOC_SUBDEV_S_DV_TIMINGS - Get or set DV timings for input or output
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_dv_timings *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_G_DV_TIMINGS, VIDIOC_S_DV_TIMINGS,
- VIDIOC_SUBDEV_G_DV_TIMINGS, VIDIOC_SUBDEV_S_DV_TIMINGS
-
-``argp``
-
-
-Description
-===========
-
-To set DV timings for the input or output, applications use the
-:ref:`VIDIOC_S_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>` ioctl and to get the current timings,
-applications use the :ref:`VIDIOC_G_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>` ioctl. The detailed timing
-information is filled in using the structure struct
-:ref:`v4l2_dv_timings <v4l2-dv-timings>`. These ioctls take a
-pointer to the struct :ref:`v4l2_dv_timings <v4l2-dv-timings>`
-structure as argument. If the ioctl is not supported or the timing
-values are not correct, the driver returns ``EINVAL`` error code.
-
-The ``linux/v4l2-dv-timings.h`` header can be used to get the timings of
-the formats in the :ref:`cea861` and :ref:`vesadmt` standards. If
-the current input or output does not support DV timings (e.g. if
-:ref:`VIDIOC_ENUMINPUT` does not set the
-``V4L2_IN_CAP_DV_TIMINGS`` flag), then ``ENODATA`` error code is returned.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EINVAL
- This ioctl is not supported, or the :ref:`VIDIOC_S_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>`
- parameter was unsuitable.
-
-ENODATA
- Digital video timings are not supported for this input or output.
-
-EBUSY
- The device is busy and therefore can not change the timings.
-
-
-.. _v4l2-bt-timings:
-
-.. flat-table:: struct v4l2_bt_timings
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``width``
-
- - Width of the active video in pixels.
-
- - .. row 2
-
- - __u32
-
- - ``height``
-
- - Height of the active video frame in lines. So for interlaced
- formats the height of the active video in each field is
- ``height``/2.
-
- - .. row 3
-
- - __u32
-
- - ``interlaced``
-
- - Progressive (0) or interlaced (1)
-
- - .. row 4
-
- - __u32
-
- - ``polarities``
-
- - This is a bit mask that defines polarities of sync signals. bit 0
- (``V4L2_DV_VSYNC_POS_POL``) is for vertical sync polarity and bit
- 1 (``V4L2_DV_HSYNC_POS_POL``) is for horizontal sync polarity. If
- the bit is set (1) it is positive polarity and if is cleared (0),
- it is negative polarity.
-
- - .. row 5
-
- - __u64
-
- - ``pixelclock``
-
- - Pixel clock in Hz. Ex. 74.25MHz->74250000
-
- - .. row 6
-
- - __u32
-
- - ``hfrontporch``
-
- - Horizontal front porch in pixels
-
- - .. row 7
-
- - __u32
-
- - ``hsync``
-
- - Horizontal sync length in pixels
-
- - .. row 8
-
- - __u32
-
- - ``hbackporch``
-
- - Horizontal back porch in pixels
-
- - .. row 9
-
- - __u32
-
- - ``vfrontporch``
-
- - Vertical front porch in lines. For interlaced formats this refers
- to the odd field (aka field 1).
-
- - .. row 10
-
- - __u32
-
- - ``vsync``
-
- - Vertical sync length in lines. For interlaced formats this refers
- to the odd field (aka field 1).
-
- - .. row 11
-
- - __u32
-
- - ``vbackporch``
-
- - Vertical back porch in lines. For interlaced formats this refers
- to the odd field (aka field 1).
-
- - .. row 12
-
- - __u32
-
- - ``il_vfrontporch``
-
- - Vertical front porch in lines for the even field (aka field 2) of
- interlaced field formats. Must be 0 for progressive formats.
-
- - .. row 13
-
- - __u32
-
- - ``il_vsync``
-
- - Vertical sync length in lines for the even field (aka field 2) of
- interlaced field formats. Must be 0 for progressive formats.
-
- - .. row 14
-
- - __u32
-
- - ``il_vbackporch``
-
- - Vertical back porch in lines for the even field (aka field 2) of
- interlaced field formats. Must be 0 for progressive formats.
-
- - .. row 15
-
- - __u32
-
- - ``standards``
-
- - The video standard(s) this format belongs to. This will be filled
- in by the driver. Applications must set this to 0. See
- :ref:`dv-bt-standards` for a list of standards.
-
- - .. row 16
-
- - __u32
-
- - ``flags``
-
- - Several flags giving more information about the format. See
- :ref:`dv-bt-flags` for a description of the flags.
-
-
-
-.. _v4l2-dv-timings:
-
-.. flat-table:: struct v4l2_dv_timings
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2 1
-
-
- - .. row 1
-
- - __u32
-
- - ``type``
-
- -
- - Type of DV timings as listed in :ref:`dv-timing-types`.
-
- - .. row 2
-
- - union
-
- -
- -
-
- - .. row 3
-
- -
- - struct :ref:`v4l2_bt_timings <v4l2-bt-timings>`
-
- - ``bt``
-
- - Timings defined by BT.656/1120 specifications
-
- - .. row 4
-
- -
- - __u32
-
- - ``reserved``\ [32]
-
- -
-
-
-
-.. _dv-timing-types:
-
-.. flat-table:: DV Timing types
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - Timing type
-
- - value
-
- - Description
-
- - .. row 2
-
- -
- -
- -
-
- - .. row 3
-
- - ``V4L2_DV_BT_656_1120``
-
- - 0
-
- - BT.656/1120 timings
-
-
-
-.. _dv-bt-standards:
-
-.. flat-table:: DV BT Timing standards
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - Timing standard
-
- - Description
-
- - .. row 2
-
- -
- -
-
- - .. row 3
-
- - ``V4L2_DV_BT_STD_CEA861``
-
- - The timings follow the CEA-861 Digital TV Profile standard
-
- - .. row 4
-
- - ``V4L2_DV_BT_STD_DMT``
-
- - The timings follow the VESA Discrete Monitor Timings standard
-
- - .. row 5
-
- - ``V4L2_DV_BT_STD_CVT``
-
- - The timings follow the VESA Coordinated Video Timings standard
-
- - .. row 6
-
- - ``V4L2_DV_BT_STD_GTF``
-
- - The timings follow the VESA Generalized Timings Formula standard
-
-
-
-.. _dv-bt-flags:
-
-.. flat-table:: DV BT Timing flags
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - Flag
-
- - Description
-
- - .. row 2
-
- -
- -
-
- - .. row 3
-
- - ``V4L2_DV_FL_REDUCED_BLANKING``
-
- - CVT/GTF specific: the timings use reduced blanking (CVT) or the
- 'Secondary GTF' curve (GTF). In both cases the horizontal and/or
- vertical blanking intervals are reduced, allowing a higher
- resolution over the same bandwidth. This is a read-only flag,
- applications must not set this.
-
- - .. row 4
-
- - ``V4L2_DV_FL_CAN_REDUCE_FPS``
-
- - CEA-861 specific: set for CEA-861 formats with a framerate that is
- a multiple of six. These formats can be optionally played at 1 /
- 1.001 speed to be compatible with 60 Hz based standards such as
- NTSC and PAL-M that use a framerate of 29.97 frames per second. If
- the transmitter can't generate such frequencies, then the flag
- will also be cleared. This is a read-only flag, applications must
- not set this.
-
- - .. row 5
-
- - ``V4L2_DV_FL_REDUCED_FPS``
-
- - CEA-861 specific: only valid for video transmitters, the flag is
- cleared by receivers. It is also only valid for formats with the
- ``V4L2_DV_FL_CAN_REDUCE_FPS`` flag set, for other formats the
- flag will be cleared by the driver. If the application sets this
- flag, then the pixelclock used to set up the transmitter is
- divided by 1.001 to make it compatible with NTSC framerates. If
- the transmitter can't generate such frequencies, then the flag
- will also be cleared.
-
- - .. row 6
-
- - ``V4L2_DV_FL_HALF_LINE``
-
- - Specific to interlaced formats: if set, then the vertical
- frontporch of field 1 (aka the odd field) is really one half-line
- longer and the vertical backporch of field 2 (aka the even field)
- is really one half-line shorter, so each field has exactly the
- same number of half-lines. Whether half-lines can be detected or
- used depends on the hardware.
-
- - .. row 7
-
- - ``V4L2_DV_FL_IS_CE_VIDEO``
-
- - If set, then this is a Consumer Electronics (CE) video format.
- Such formats differ from other formats (commonly called IT
- formats) in that if R'G'B' encoding is used then by default the
- R'G'B' values use limited range (i.e. 16-235) as opposed to full
- range (i.e. 0-255). All formats defined in CEA-861 except for the
- 640x480p59.94 format are CE formats.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_G_EDID:
-
-******************************************************************************
-ioctl VIDIOC_G_EDID, VIDIOC_S_EDID, VIDIOC_SUBDEV_G_EDID, VIDIOC_SUBDEV_S_EDID
-******************************************************************************
-
-Name
-====
-
-VIDIOC_G_EDID - VIDIOC_S_EDID - VIDIOC_SUBDEV_G_EDID - VIDIOC_SUBDEV_S_EDID - Get or set the EDID of a video receiver/transmitter
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_edid *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_G_EDID, VIDIOC_S_EDID, VIDIOC_SUBDEV_G_EDID,
- VIDIOC_SUBDEV_S_EDID
-
-``argp``
-
-
-Description
-===========
-
-These ioctls can be used to get or set an EDID associated with an input
-from a receiver or an output of a transmitter device. They can be used
-with subdevice nodes (/dev/v4l-subdevX) or with video nodes
-(/dev/videoX).
-
-When used with video nodes the ``pad`` field represents the input (for
-video capture devices) or output (for video output devices) index as is
-returned by :ref:`VIDIOC_ENUMINPUT` and
-:ref:`VIDIOC_ENUMOUTPUT` respectively. When used
-with subdevice nodes the ``pad`` field represents the input or output
-pad of the subdevice. If there is no EDID support for the given ``pad``
-value, then the ``EINVAL`` error code will be returned.
-
-To get the EDID data the application has to fill in the ``pad``,
-``start_block``, ``blocks`` and ``edid`` fields, zero the ``reserved``
-array and call :ref:`VIDIOC_G_EDID <VIDIOC_G_EDID>`. The current EDID from block
-``start_block`` and of size ``blocks`` will be placed in the memory
-``edid`` points to. The ``edid`` pointer must point to memory at least
-``blocks`` * 128 bytes large (the size of one block is 128 bytes).
-
-If there are fewer blocks than specified, then the driver will set
-``blocks`` to the actual number of blocks. If there are no EDID blocks
-available at all, then the error code ``ENODATA`` is set.
-
-If blocks have to be retrieved from the sink, then this call will block
-until they have been read.
-
-If ``start_block`` and ``blocks`` are both set to 0 when
-:ref:`VIDIOC_G_EDID <VIDIOC_G_EDID>` is called, then the driver will set ``blocks`` to the
-total number of available EDID blocks and it will return 0 without
-copying any data. This is an easy way to discover how many EDID blocks
-there are. Note that if there are no EDID blocks available at all, then
-the driver will set ``blocks`` to 0 and it returns 0.
-
-To set the EDID blocks of a receiver the application has to fill in the
-``pad``, ``blocks`` and ``edid`` fields, set ``start_block`` to 0 and
-zero the ``reserved`` array. It is not possible to set part of an EDID,
-it is always all or nothing. Setting the EDID data is only valid for
-receivers as it makes no sense for a transmitter.
-
-The driver assumes that the full EDID is passed in. If there are more
-EDID blocks than the hardware can handle then the EDID is not written,
-but instead the error code ``E2BIG`` is set and ``blocks`` is set to the
-maximum that the hardware supports. If ``start_block`` is any value
-other than 0 then the error code ``EINVAL`` is set.
-
-To disable an EDID you set ``blocks`` to 0. Depending on the hardware
-this will drive the hotplug pin low and/or block the source from reading
-the EDID data in some way. In any case, the end result is the same: the
-EDID is no longer available.
-
-
-.. _v4l2-edid:
-
-.. flat-table:: struct v4l2_edid
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``pad``
-
- - Pad for which to get/set the EDID blocks. When used with a video
- device node the pad represents the input or output index as
- returned by :ref:`VIDIOC_ENUMINPUT` and
- :ref:`VIDIOC_ENUMOUTPUT` respectively.
-
- - .. row 2
-
- - __u32
-
- - ``start_block``
-
- - Read the EDID from starting with this block. Must be 0 when
- setting the EDID.
-
- - .. row 3
-
- - __u32
-
- - ``blocks``
-
- - The number of blocks to get or set. Must be less or equal to 256
- (the maximum number of blocks as defined by the standard). When
- you set the EDID and ``blocks`` is 0, then the EDID is disabled or
- erased.
-
- - .. row 4
-
- - __u32
-
- - ``reserved``\ [5]
-
- - Reserved for future extensions. Applications and drivers must set
- the array to zero.
-
- - .. row 5
-
- - __u8 *
-
- - ``edid``
-
- - Pointer to memory that contains the EDID. The minimum size is
- ``blocks`` * 128.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-``ENODATA``
- The EDID data is not available.
-
-``E2BIG``
- The EDID data you provided is more than the hardware can handle.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_G_ENC_INDEX:
-
-************************
-ioctl VIDIOC_G_ENC_INDEX
-************************
-
-Name
-====
-
-VIDIOC_G_ENC_INDEX - Get meta data about a compressed video stream
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_enc_idx *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_G_ENC_INDEX
-
-``argp``
-
-
-Description
-===========
-
-The :ref:`VIDIOC_G_ENC_INDEX <VIDIOC_G_ENC_INDEX>` ioctl provides meta data about a compressed
-video stream the same or another application currently reads from the
-driver, which is useful for random access into the stream without
-decoding it.
-
-To read the data applications must call :ref:`VIDIOC_G_ENC_INDEX <VIDIOC_G_ENC_INDEX>` with a
-pointer to a struct :ref:`v4l2_enc_idx <v4l2-enc-idx>`. On success
-the driver fills the ``entry`` array, stores the number of elements
-written in the ``entries`` field, and initializes the ``entries_cap``
-field.
-
-Each element of the ``entry`` array contains meta data about one
-picture. A :ref:`VIDIOC_G_ENC_INDEX <VIDIOC_G_ENC_INDEX>` call reads up to
-``V4L2_ENC_IDX_ENTRIES`` entries from a driver buffer, which can hold up
-to ``entries_cap`` entries. This number can be lower or higher than
-``V4L2_ENC_IDX_ENTRIES``, but not zero. When the application fails to
-read the meta data in time the oldest entries will be lost. When the
-buffer is empty or no capturing/encoding is in progress, ``entries``
-will be zero.
-
-Currently this ioctl is only defined for MPEG-2 program streams and
-video elementary streams.
-
-
-.. _v4l2-enc-idx:
-
-.. flat-table:: struct v4l2_enc_idx
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2 1 1
-
-
- - .. row 1
-
- - __u32
-
- - ``entries``
-
- - The number of entries the driver stored in the ``entry`` array.
-
- - .. row 2
-
- - __u32
-
- - ``entries_cap``
-
- - The number of entries the driver can buffer. Must be greater than
- zero.
-
- - .. row 3
-
- - __u32
-
- - ``reserved``\ [4]
-
- - :cspan:`2` Reserved for future extensions. Drivers must set the
- array to zero.
-
- - .. row 4
-
- - struct :ref:`v4l2_enc_idx_entry <v4l2-enc-idx-entry>`
-
- - ``entry``\ [``V4L2_ENC_IDX_ENTRIES``]
-
- - Meta data about a compressed video stream. Each element of the
- array corresponds to one picture, sorted in ascending order by
- their ``offset``.
-
-
-
-.. _v4l2-enc-idx-entry:
-
-.. flat-table:: struct v4l2_enc_idx_entry
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u64
-
- - ``offset``
-
- - The offset in bytes from the beginning of the compressed video
- stream to the beginning of this picture, that is a *PES packet
- header* as defined in :ref:`mpeg2part1` or a *picture header* as
- defined in :ref:`mpeg2part2`. When the encoder is stopped, the
- driver resets the offset to zero.
-
- - .. row 2
-
- - __u64
-
- - ``pts``
-
- - The 33 bit *Presentation Time Stamp* of this picture as defined in
- :ref:`mpeg2part1`.
-
- - .. row 3
-
- - __u32
-
- - ``length``
-
- - The length of this picture in bytes.
-
- - .. row 4
-
- - __u32
-
- - ``flags``
-
- - Flags containing the coding type of this picture, see
- :ref:`enc-idx-flags`.
-
- - .. row 5
-
- - __u32
-
- - ``reserved``\ [2]
-
- - Reserved for future extensions. Drivers must set the array to
- zero.
-
-
-
-.. _enc-idx-flags:
-
-.. flat-table:: Index Entry Flags
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - ``V4L2_ENC_IDX_FRAME_I``
-
- - 0x00
-
- - This is an Intra-coded picture.
-
- - .. row 2
-
- - ``V4L2_ENC_IDX_FRAME_P``
-
- - 0x01
-
- - This is a Predictive-coded picture.
-
- - .. row 3
-
- - ``V4L2_ENC_IDX_FRAME_B``
-
- - 0x02
-
- - This is a Bidirectionally predictive-coded picture.
-
- - .. row 4
-
- - ``V4L2_ENC_IDX_FRAME_MASK``
-
- - 0x0F
-
- - *AND* the flags field with this mask to obtain the picture coding
- type.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_G_EXT_CTRLS:
-
-******************************************************************
-ioctl VIDIOC_G_EXT_CTRLS, VIDIOC_S_EXT_CTRLS, VIDIOC_TRY_EXT_CTRLS
-******************************************************************
-
-Name
-====
-
-VIDIOC_G_EXT_CTRLS - VIDIOC_S_EXT_CTRLS - VIDIOC_TRY_EXT_CTRLS - Get or set the value of several controls, try control values
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_ext_controls *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_G_EXT_CTRLS, VIDIOC_S_EXT_CTRLS,
- VIDIOC_TRY_EXT_CTRLS
-
-``argp``
-
-
-Description
-===========
-
-These ioctls allow the caller to get or set multiple controls
-atomically. Control IDs are grouped into control classes (see
-:ref:`ctrl-class`) and all controls in the control array must belong
-to the same control class.
-
-Applications must always fill in the ``count``, ``which``, ``controls``
-and ``reserved`` fields of struct
-:ref:`v4l2_ext_controls <v4l2-ext-controls>`, and initialize the
-struct :ref:`v4l2_ext_control <v4l2-ext-control>` array pointed to
-by the ``controls`` fields.
-
-To get the current value of a set of controls applications initialize
-the ``id``, ``size`` and ``reserved2`` fields of each struct
-:ref:`v4l2_ext_control <v4l2-ext-control>` and call the
-:ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctl. String controls controls must also set the
-``string`` field. Controls of compound types
-(``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is set) must set the ``ptr`` field.
-
-If the ``size`` is too small to receive the control result (only
-relevant for pointer-type controls like strings), then the driver will
-set ``size`` to a valid value and return an ``ENOSPC`` error code. You
-should re-allocate the memory to this new size and try again. For the
-string type it is possible that the same issue occurs again if the
-string has grown in the meantime. It is recommended to call
-:ref:`VIDIOC_QUERYCTRL` first and use
-``maximum``\ +1 as the new ``size`` value. It is guaranteed that that is
-sufficient memory.
-
-N-dimensional arrays are set and retrieved row-by-row. You cannot set a
-partial array, all elements have to be set or retrieved. The total size
-is calculated as ``elems`` * ``elem_size``. These values can be obtained
-by calling :ref:`VIDIOC_QUERY_EXT_CTRL <VIDIOC_QUERYCTRL>`.
-
-To change the value of a set of controls applications initialize the
-``id``, ``size``, ``reserved2`` and ``value/value64/string/ptr`` fields
-of each struct :ref:`v4l2_ext_control <v4l2-ext-control>` and call
-the :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctl. The controls will only be set if *all*
-control values are valid.
-
-To check if a set of controls have correct values applications
-initialize the ``id``, ``size``, ``reserved2`` and
-``value/value64/string/ptr`` fields of each struct
-:ref:`v4l2_ext_control <v4l2-ext-control>` and call the
-:ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctl. It is up to the driver whether wrong
-values are automatically adjusted to a valid value or if an error is
-returned.
-
-When the ``id`` or ``which`` is invalid drivers return an ``EINVAL`` error
-code. When the value is out of bounds drivers can choose to take the
-closest valid value or return an ``ERANGE`` error code, whatever seems more
-appropriate. In the first case the new value is set in struct
-:ref:`v4l2_ext_control <v4l2-ext-control>`. If the new control value
-is inappropriate (e.g. the given menu index is not supported by the menu
-control), then this will also result in an ``EINVAL`` error code error.
-
-The driver will only set/get these controls if all control values are
-correct. This prevents the situation where only some of the controls
-were set/get. Only low-level errors (e. g. a failed i2c command) can
-still cause this situation.
-
-
-.. _v4l2-ext-control:
-
-.. flat-table:: struct v4l2_ext_control
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``id``
-
- -
- - Identifies the control, set by the application.
-
- - .. row 2
-
- - __u32
-
- - ``size``
-
- -
- - The total size in bytes of the payload of this control. This is
- normally 0, but for pointer controls this should be set to the
- size of the memory containing the payload, or that will receive
- the payload. If :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` finds that this value is
- less than is required to store the payload result, then it is set
- to a value large enough to store the payload result and ``ENOSPC`` is
- returned. Note that for string controls this ``size`` field should
- not be confused with the length of the string. This field refers
- to the size of the memory that contains the string. The actual
- *length* of the string may well be much smaller.
-
- - .. row 3
-
- - __u32
-
- - ``reserved2``\ [1]
-
- -
- - Reserved for future extensions. Drivers and applications must set
- the array to zero.
-
- - .. row 4
-
- - union
-
- - (anonymous)
-
- - .. row 5
-
- -
- - __s32
-
- - ``value``
-
- - New value or current value. Valid if this control is not of type
- ``V4L2_CTRL_TYPE_INTEGER64`` and ``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is
- not set.
-
- - .. row 6
-
- -
- - __s64
-
- - ``value64``
-
- - New value or current value. Valid if this control is of type
- ``V4L2_CTRL_TYPE_INTEGER64`` and ``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is
- not set.
-
- - .. row 7
-
- -
- - char *
-
- - ``string``
-
- - A pointer to a string. Valid if this control is of type
- ``V4L2_CTRL_TYPE_STRING``.
-
- - .. row 8
-
- -
- - __u8 *
-
- - ``p_u8``
-
- - A pointer to a matrix control of unsigned 8-bit values. Valid if
- this control is of type ``V4L2_CTRL_TYPE_U8``.
-
- - .. row 9
-
- -
- - __u16 *
-
- - ``p_u16``
-
- - A pointer to a matrix control of unsigned 16-bit values. Valid if
- this control is of type ``V4L2_CTRL_TYPE_U16``.
-
- - .. row 10
-
- -
- - __u32 *
-
- - ``p_u32``
-
- - A pointer to a matrix control of unsigned 32-bit values. Valid if
- this control is of type ``V4L2_CTRL_TYPE_U32``.
-
- - .. row 11
-
- -
- - void *
-
- - ``ptr``
-
- - A pointer to a compound type which can be an N-dimensional array
- and/or a compound type (the control's type is >=
- ``V4L2_CTRL_COMPOUND_TYPES``). Valid if
- ``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is set for this control.
-
-
-
-.. _v4l2-ext-controls:
-
-.. flat-table:: struct v4l2_ext_controls
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2 1
-
-
- - .. row 1
-
- - union
-
- - (anonymous)
-
- - .. row 2
-
- -
- - __u32
-
- - ``ctrl_class``
-
- - The control class to which all controls belong, see
- :ref:`ctrl-class`. Drivers that use a kernel framework for
- handling controls will also accept a value of 0 here, meaning that
- the controls can belong to any control class. Whether drivers
- support this can be tested by setting ``ctrl_class`` to 0 and
- calling :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` with a ``count`` of 0. If that
- succeeds, then the driver supports this feature.
-
- - .. row 3
-
- -
- - __u32
-
- - ``which``
-
- - Which value of the control to get/set/try.
- ``V4L2_CTRL_WHICH_CUR_VAL`` will return the current value of the
- control and ``V4L2_CTRL_WHICH_DEF_VAL`` will return the default
- value of the control. Please note that you can only get the
- default value of the control, you cannot set or try it.
-
- For backwards compatibility you can also use a control class here
- (see :ref:`ctrl-class`). In that case all controls have to
- belong to that control class. This usage is deprecated, instead
- just use ``V4L2_CTRL_WHICH_CUR_VAL``. There are some very old
- drivers that do not yet support ``V4L2_CTRL_WHICH_CUR_VAL`` and
- that require a control class here. You can test for such drivers
- by setting ctrl_class to ``V4L2_CTRL_WHICH_CUR_VAL`` and calling
- VIDIOC_TRY_EXT_CTRLS with a count of 0. If that fails, then the
- driver does not support ``V4L2_CTRL_WHICH_CUR_VAL``.
-
- - .. row 4
-
- - __u32
-
- - ``count``
-
- - The number of controls in the controls array. May also be zero.
-
- - .. row 5
-
- - __u32
-
- - ``error_idx``
-
- - Set by the driver in case of an error. If the error is associated
- with a particular control, then ``error_idx`` is set to the index
- of that control. If the error is not related to a specific
- control, or the validation step failed (see below), then
- ``error_idx`` is set to ``count``. The value is undefined if the
- ioctl returned 0 (success).
-
- Before controls are read from/written to hardware a validation
- step takes place: this checks if all controls in the list are
- valid controls, if no attempt is made to write to a read-only
- control or read from a write-only control, and any other up-front
- checks that can be done without accessing the hardware. The exact
- validations done during this step are driver dependent since some
- checks might require hardware access for some devices, thus making
- it impossible to do those checks up-front. However, drivers should
- make a best-effort to do as many up-front checks as possible.
-
- This check is done to avoid leaving the hardware in an
- inconsistent state due to easy-to-avoid problems. But it leads to
- another problem: the application needs to know whether an error
- came from the validation step (meaning that the hardware was not
- touched) or from an error during the actual reading from/writing
- to hardware.
-
- The, in hindsight quite poor, solution for that is to set
- ``error_idx`` to ``count`` if the validation failed. This has the
- unfortunate side-effect that it is not possible to see which
- control failed the validation. If the validation was successful
- and the error happened while accessing the hardware, then
- ``error_idx`` is less than ``count`` and only the controls up to
- ``error_idx-1`` were read or written correctly, and the state of
- the remaining controls is undefined.
-
- Since :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` does not access hardware there is
- also no need to handle the validation step in this special way, so
- ``error_idx`` will just be set to the control that failed the
- validation step instead of to ``count``. This means that if
- :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` fails with ``error_idx`` set to ``count``,
- then you can call :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` to try to discover the
- actual control that failed the validation step. Unfortunately,
- there is no ``TRY`` equivalent for :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`.
-
- - .. row 6
-
- - __u32
-
- - ``reserved``\ [2]
-
- - Reserved for future extensions. Drivers and applications must set
- the array to zero.
-
- - .. row 7
-
- - struct :ref:`v4l2_ext_control <v4l2-ext-control>` *
-
- - ``controls``
-
- - Pointer to an array of ``count`` v4l2_ext_control structures.
- Ignored if ``count`` equals zero.
-
-
-
-.. _ctrl-class:
-
-.. flat-table:: Control classes
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - ``V4L2_CTRL_CLASS_USER``
-
- - 0x980000
-
- - The class containing user controls. These controls are described
- in :ref:`control`. All controls that can be set using the
- :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` and
- :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` ioctl belong to this
- class.
-
- - .. row 2
-
- - ``V4L2_CTRL_CLASS_MPEG``
-
- - 0x990000
-
- - The class containing MPEG compression controls. These controls are
- described in :ref:`mpeg-controls`.
-
- - .. row 3
-
- - ``V4L2_CTRL_CLASS_CAMERA``
-
- - 0x9a0000
-
- - The class containing camera controls. These controls are described
- in :ref:`camera-controls`.
-
- - .. row 4
-
- - ``V4L2_CTRL_CLASS_FM_TX``
-
- - 0x9b0000
-
- - The class containing FM Transmitter (FM TX) controls. These
- controls are described in :ref:`fm-tx-controls`.
-
- - .. row 5
-
- - ``V4L2_CTRL_CLASS_FLASH``
-
- - 0x9c0000
-
- - The class containing flash device controls. These controls are
- described in :ref:`flash-controls`.
-
- - .. row 6
-
- - ``V4L2_CTRL_CLASS_JPEG``
-
- - 0x9d0000
-
- - The class containing JPEG compression controls. These controls are
- described in :ref:`jpeg-controls`.
-
- - .. row 7
-
- - ``V4L2_CTRL_CLASS_IMAGE_SOURCE``
-
- - 0x9e0000
-
- - The class containing image source controls. These controls are
- described in :ref:`image-source-controls`.
-
- - .. row 8
-
- - ``V4L2_CTRL_CLASS_IMAGE_PROC``
-
- - 0x9f0000
-
- - The class containing image processing controls. These controls are
- described in :ref:`image-process-controls`.
-
- - .. row 9
-
- - ``V4L2_CTRL_CLASS_FM_RX``
-
- - 0xa10000
-
- - The class containing FM Receiver (FM RX) controls. These controls
- are described in :ref:`fm-rx-controls`.
-
- - .. row 10
-
- - ``V4L2_CTRL_CLASS_RF_TUNER``
-
- - 0xa20000
-
- - The class containing RF tuner controls. These controls are
- described in :ref:`rf-tuner-controls`.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EINVAL
- The struct :ref:`v4l2_ext_control <v4l2-ext-control>` ``id`` is
- invalid, the struct :ref:`v4l2_ext_controls <v4l2-ext-controls>`
- ``which`` is invalid, or the struct
- :ref:`v4l2_ext_control <v4l2-ext-control>` ``value`` was
- inappropriate (e.g. the given menu index is not supported by the
- driver). This error code is also returned by the
- :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` and :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctls if two or
- more control values are in conflict.
-
-ERANGE
- The struct :ref:`v4l2_ext_control <v4l2-ext-control>` ``value``
- is out of bounds.
-
-EBUSY
- The control is temporarily not changeable, possibly because another
- applications took over control of the device function this control
- belongs to.
-
-ENOSPC
- The space reserved for the control's payload is insufficient. The
- field ``size`` is set to a value that is enough to store the payload
- and this error code is returned.
-
-EACCES
- Attempt to try or set a read-only control or to get a write-only
- control.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_G_FBUF:
-
-**********************************
-ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF
-**********************************
-
-Name
-====
-
-VIDIOC_G_FBUF - VIDIOC_S_FBUF - Get or set frame buffer overlay parameters
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_framebuffer *argp )
-
-.. cpp:function:: int ioctl( int fd, int request, const struct v4l2_framebuffer *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_G_FBUF, VIDIOC_S_FBUF
-
-``argp``
-
-
-Description
-===========
-
-Applications can use the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` and :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctl
-to get and set the framebuffer parameters for a
-:ref:`Video Overlay <overlay>` or :ref:`Video Output Overlay <osd>`
-(OSD). The type of overlay is implied by the device type (capture or
-output device) and can be determined with the
-:ref:`VIDIOC_QUERYCAP` ioctl. One ``/dev/videoN``
-device must not support both kinds of overlay.
-
-The V4L2 API distinguishes destructive and non-destructive overlays. A
-destructive overlay copies captured video images into the video memory
-of a graphics card. A non-destructive overlay blends video images into a
-VGA signal or graphics into a video signal. *Video Output Overlays* are
-always non-destructive.
-
-To get the current parameters applications call the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`
-ioctl with a pointer to a :ref:`struct v4l2_framebuffer <v4l2-framebuffer>`
-structure. The driver fills all fields of the structure or returns an
-EINVAL error code when overlays are not supported.
-
-To set the parameters for a *Video Output Overlay*, applications must
-initialize the ``flags`` field of a struct
-:ref:`struct v4l2_framebuffer <v4l2-framebuffer>`. Since the framebuffer is
-implemented on the TV card all other parameters are determined by the
-driver. When an application calls :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` with a pointer to
-this structure, the driver prepares for the overlay and returns the
-framebuffer parameters as :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` does, or it returns an error
-code.
-
-To set the parameters for a *non-destructive Video Overlay*,
-applications must initialize the ``flags`` field, the ``fmt``
-substructure, and call :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`. Again the driver prepares for
-the overlay and returns the framebuffer parameters as :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`
-does, or it returns an error code.
-
-For a *destructive Video Overlay* applications must additionally provide
-a ``base`` address. Setting up a DMA to a random memory location can
-jeopardize the system security, its stability or even damage the
-hardware, therefore only the superuser can set the parameters for a
-destructive video overlay.
-
-
-.. _v4l2-framebuffer:
-
-.. flat-table:: struct v4l2_framebuffer
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``capability``
-
- -
- - Overlay capability flags set by the driver, see
- :ref:`framebuffer-cap`.
-
- - .. row 2
-
- - __u32
-
- - ``flags``
-
- -
- - Overlay control flags set by application and driver, see
- :ref:`framebuffer-flags`
-
- - .. row 3
-
- - void *
-
- - ``base``
-
- -
- - Physical base address of the framebuffer, that is the address of
- the pixel in the top left corner of the framebuffer. [1]_
-
- - .. row 4
-
- -
- -
- -
- - This field is irrelevant to *non-destructive Video Overlays*. For
- *destructive Video Overlays* applications must provide a base
- address. The driver may accept only base addresses which are a
- multiple of two, four or eight bytes. For *Video Output Overlays*
- the driver must return a valid base address, so applications can
- find the corresponding Linux framebuffer device (see
- :ref:`osd`).
-
- - .. row 5
-
- - struct
-
- - ``fmt``
-
- -
- - Layout of the frame buffer.
-
- - .. row 6
-
- -
- - __u32
-
- - ``width``
-
- - Width of the frame buffer in pixels.
-
- - .. row 7
-
- -
- - __u32
-
- - ``height``
-
- - Height of the frame buffer in pixels.
-
- - .. row 8
-
- -
- - __u32
-
- - ``pixelformat``
-
- - The pixel format of the framebuffer.
-
- - .. row 9
-
- -
- -
- -
- - For *non-destructive Video Overlays* this field only defines a
- format for the struct :ref:`v4l2_window <v4l2-window>`
- ``chromakey`` field.
-
- - .. row 10
-
- -
- -
- -
- - For *destructive Video Overlays* applications must initialize this
- field. For *Video Output Overlays* the driver must return a valid
- format.
-
- - .. row 11
-
- -
- -
- -
- - Usually this is an RGB format (for example
- :ref:`V4L2_PIX_FMT_RGB565 <V4L2-PIX-FMT-RGB565>`) but YUV
- formats (only packed YUV formats when chroma keying is used, not
- including ``V4L2_PIX_FMT_YUYV`` and ``V4L2_PIX_FMT_UYVY``) and the
- ``V4L2_PIX_FMT_PAL8`` format are also permitted. The behavior of
- the driver when an application requests a compressed format is
- undefined. See :ref:`pixfmt` for information on pixel formats.
-
- - .. row 12
-
- -
- - enum :ref:`v4l2_field <v4l2-field>`
-
- - ``field``
-
- - Drivers and applications shall ignore this field. If applicable,
- the field order is selected with the
- :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, using the ``field``
- field of struct :ref:`v4l2_window <v4l2-window>`.
-
- - .. row 13
-
- -
- - __u32
-
- - ``bytesperline``
-
- - Distance in bytes between the leftmost pixels in two adjacent
- lines.
-
- - .. row 14
-
- - :cspan:`3`
-
- This field is irrelevant to *non-destructive Video Overlays*.
-
- For *destructive Video Overlays* both applications and drivers can
- set this field to request padding bytes at the end of each line.
- Drivers however may ignore the requested value, returning
- ``width`` times bytes-per-pixel or a larger value required by the
- hardware. That implies applications can just set this field to
- zero to get a reasonable default.
-
- For *Video Output Overlays* the driver must return a valid value.
-
- Video hardware may access padding bytes, therefore they must
- reside in accessible memory. Consider for example the case where
- padding bytes after the last line of an image cross a system page
- boundary. Capture devices may write padding bytes, the value is
- undefined. Output devices ignore the contents of padding bytes.
-
- When the image format is planar the ``bytesperline`` value applies
- to the first plane and is divided by the same factor as the
- ``width`` field for the other planes. For example the Cb and Cr
- planes of a YUV 4:2:0 image have half as many padding bytes
- following each line as the Y plane. To avoid ambiguities drivers
- must return a ``bytesperline`` value rounded up to a multiple of
- the scale factor.
-
- - .. row 15
-
- -
- - __u32
-
- - ``sizeimage``
-
- - This field is irrelevant to *non-destructive Video Overlays*. For
- *destructive Video Overlays* applications must initialize this
- field. For *Video Output Overlays* the driver must return a valid
- format.
-
- Together with ``base`` it defines the framebuffer memory
- accessible by the driver.
-
- - .. row 16
-
- -
- - enum :ref:`v4l2_colorspace <v4l2-colorspace>`
-
- - ``colorspace``
-
- - This information supplements the ``pixelformat`` and must be set
- by the driver, see :ref:`colorspaces`.
-
- - .. row 17
-
- -
- - __u32
-
- - ``priv``
-
- - Reserved. Drivers and applications must set this field to zero.
-
-
-
-.. _framebuffer-cap:
-
-.. flat-table:: Frame Buffer Capability Flags
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - ``V4L2_FBUF_CAP_EXTERNOVERLAY``
-
- - 0x0001
-
- - The device is capable of non-destructive overlays. When the driver
- clears this flag, only destructive overlays are supported. There
- are no drivers yet which support both destructive and
- non-destructive overlays. Video Output Overlays are in practice
- always non-destructive.
-
- - .. row 2
-
- - ``V4L2_FBUF_CAP_CHROMAKEY``
-
- - 0x0002
-
- - The device supports clipping by chroma-keying the images. That is,
- image pixels replace pixels in the VGA or video signal only where
- the latter assume a certain color. Chroma-keying makes no sense
- for destructive overlays.
-
- - .. row 3
-
- - ``V4L2_FBUF_CAP_LIST_CLIPPING``
-
- - 0x0004
-
- - The device supports clipping using a list of clip rectangles.
-
- - .. row 4
-
- - ``V4L2_FBUF_CAP_BITMAP_CLIPPING``
-
- - 0x0008
-
- - The device supports clipping using a bit mask.
-
- - .. row 5
-
- - ``V4L2_FBUF_CAP_LOCAL_ALPHA``
-
- - 0x0010
-
- - The device supports clipping/blending using the alpha channel of
- the framebuffer or VGA signal. Alpha blending makes no sense for
- destructive overlays.
-
- - .. row 6
-
- - ``V4L2_FBUF_CAP_GLOBAL_ALPHA``
-
- - 0x0020
-
- - The device supports alpha blending using a global alpha value.
- Alpha blending makes no sense for destructive overlays.
-
- - .. row 7
-
- - ``V4L2_FBUF_CAP_LOCAL_INV_ALPHA``
-
- - 0x0040
-
- - The device supports clipping/blending using the inverted alpha
- channel of the framebuffer or VGA signal. Alpha blending makes no
- sense for destructive overlays.
-
- - .. row 8
-
- - ``V4L2_FBUF_CAP_SRC_CHROMAKEY``
-
- - 0x0080
-
- - The device supports Source Chroma-keying. Video pixels with the
- chroma-key colors are replaced by framebuffer pixels, which is
- exactly opposite of ``V4L2_FBUF_CAP_CHROMAKEY``
-
-
-
-.. _framebuffer-flags:
-
-.. flat-table:: Frame Buffer Flags
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - ``V4L2_FBUF_FLAG_PRIMARY``
-
- - 0x0001
-
- - The framebuffer is the primary graphics surface. In other words,
- the overlay is destructive. This flag is typically set by any
- driver that doesn't have the ``V4L2_FBUF_CAP_EXTERNOVERLAY``
- capability and it is cleared otherwise.
-
- - .. row 2
-
- - ``V4L2_FBUF_FLAG_OVERLAY``
-
- - 0x0002
-
- - If this flag is set for a video capture device, then the driver
- will set the initial overlay size to cover the full framebuffer
- size, otherwise the existing overlay size (as set by
- :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`) will be used. Only one
- video capture driver (bttv) supports this flag. The use of this
- flag for capture devices is deprecated. There is no way to detect
- which drivers support this flag, so the only reliable method of
- setting the overlay size is through
- :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. If this flag is set for a
- video output device, then the video output overlay window is
- relative to the top-left corner of the framebuffer and restricted
- to the size of the framebuffer. If it is cleared, then the video
- output overlay window is relative to the video output display.
-
- - .. row 3
-
- - ``V4L2_FBUF_FLAG_CHROMAKEY``
-
- - 0x0004
-
- - Use chroma-keying. The chroma-key color is determined by the
- ``chromakey`` field of struct :ref:`v4l2_window <v4l2-window>`
- and negotiated with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
- ioctl, see :ref:`overlay` and :ref:`osd`.
-
- - .. row 4
-
- - :cspan:`2` There are no flags to enable clipping using a list of
- clip rectangles or a bitmap. These methods are negotiated with the
- :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay`
- and :ref:`osd`.
-
- - .. row 5
-
- - ``V4L2_FBUF_FLAG_LOCAL_ALPHA``
-
- - 0x0008
-
- - Use the alpha channel of the framebuffer to clip or blend
- framebuffer pixels with video images. The blend function is:
- output = framebuffer pixel * alpha + video pixel * (1 - alpha).
- The actual alpha depth depends on the framebuffer pixel format.
-
- - .. row 6
-
- - ``V4L2_FBUF_FLAG_GLOBAL_ALPHA``
-
- - 0x0010
-
- - Use a global alpha value to blend the framebuffer with video
- images. The blend function is: output = (framebuffer pixel * alpha
- + video pixel * (255 - alpha)) / 255. The alpha value is
- determined by the ``global_alpha`` field of struct
- :ref:`v4l2_window <v4l2-window>` and negotiated with the
- :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay`
- and :ref:`osd`.
-
- - .. row 7
-
- - ``V4L2_FBUF_FLAG_LOCAL_INV_ALPHA``
-
- - 0x0020
-
- - Like ``V4L2_FBUF_FLAG_LOCAL_ALPHA``, use the alpha channel of the
- framebuffer to clip or blend framebuffer pixels with video images,
- but with an inverted alpha value. The blend function is: output =
- framebuffer pixel * (1 - alpha) + video pixel * alpha. The actual
- alpha depth depends on the framebuffer pixel format.
-
- - .. row 8
-
- - ``V4L2_FBUF_FLAG_SRC_CHROMAKEY``
-
- - 0x0040
-
- - Use source chroma-keying. The source chroma-key color is
- determined by the ``chromakey`` field of struct
- :ref:`v4l2_window <v4l2-window>` and negotiated with the
- :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay`
- and :ref:`osd`. Both chroma-keying are mutual exclusive to each
- other, so same ``chromakey`` field of struct
- :ref:`v4l2_window <v4l2-window>` is being used.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EPERM
- :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` can only be called by a privileged user to
- negotiate the parameters for a destructive overlay.
-
-EINVAL
- The :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` parameters are unsuitable.
-
-.. [1]
- A physical base address may not suit all platforms. GK notes in
- theory we should pass something like PCI device + memory region +
- offset instead. If you encounter problems please discuss on the
- linux-media mailing list:
- `https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_G_FMT:
-
-************************************************
-ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT
-************************************************
-
-Name
-====
-
-VIDIOC_G_FMT - VIDIOC_S_FMT - VIDIOC_TRY_FMT - Get or set the data format, try a format
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_format *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT
-
-``argp``
-
-
-Description
-===========
-
-These ioctls are used to negotiate the format of data (typically image
-format) exchanged between driver and application.
-
-To query the current parameters applications set the ``type`` field of a
-struct :ref:`struct v4l2_format <v4l2-format>` to the respective buffer (stream)
-type. For example video capture devices use
-``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or
-``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``. When the application calls the
-:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl with a pointer to this structure the driver fills
-the respective member of the ``fmt`` union. In case of video capture
-devices that is either the struct
-:ref:`v4l2_pix_format <v4l2-pix-format>` ``pix`` or the struct
-:ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` ``pix_mp``
-member. When the requested buffer type is not supported drivers return
-an ``EINVAL`` error code.
-
-To change the current format parameters applications initialize the
-``type`` field and all fields of the respective ``fmt`` union member.
-For details see the documentation of the various devices types in
-:ref:`devices`. Good practice is to query the current parameters
-first, and to modify only those parameters not suitable for the
-application. When the application calls the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with
-a pointer to a :ref:`struct v4l2_format <v4l2-format>` structure the driver
-checks and adjusts the parameters against hardware abilities. Drivers
-should not return an error code unless the ``type`` field is invalid,
-this is a mechanism to fathom device capabilities and to approach
-parameters acceptable for both the application and driver. On success
-the driver may program the hardware, allocate resources and generally
-prepare for data exchange. Finally the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl returns
-the current format parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. Very simple,
-inflexible devices may even ignore all input and always return the
-default parameters. However all V4L2 devices exchanging data with the
-application must implement the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
-ioctl. When the requested buffer type is not supported drivers return an
-EINVAL error code on a :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` attempt. When I/O is already in
-progress or the resource is not available for other reasons drivers
-return the ``EBUSY`` error code.
-
-The :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl is equivalent to :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` with one
-exception: it does not change driver state. It can also be called at any
-time, never returning ``EBUSY``. This function is provided to negotiate
-parameters, to learn about hardware limitations, without disabling I/O
-or possibly time consuming hardware preparations. Although strongly
-recommended drivers are not required to implement this ioctl.
-
-The format as returned by :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` must be identical to what
-:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` returns for the same input or output.
-
-
-.. _v4l2-format:
-
-.. flat-table:: struct v4l2_format
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - __u32
-
- - ``type``
-
- -
- - Type of the data stream, see :ref:`v4l2-buf-type`.
-
- - .. row 2
-
- - union
-
- - ``fmt``
-
- - .. row 3
-
- -
- - struct :ref:`v4l2_pix_format <v4l2-pix-format>`
-
- - ``pix``
-
- - Definition of an image format, see :ref:`pixfmt`, used by video
- capture and output devices.
-
- - .. row 4
-
- -
- - struct :ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>`
-
- - ``pix_mp``
-
- - Definition of an image format, see :ref:`pixfmt`, used by video
- capture and output devices that support the
- :ref:`multi-planar version of the API <planar-apis>`.
-
- - .. row 5
-
- -
- - struct :ref:`v4l2_window <v4l2-window>`
-
- - ``win``
-
- - Definition of an overlaid image, see :ref:`overlay`, used by
- video overlay devices.
-
- - .. row 6
-
- -
- - struct :ref:`v4l2_vbi_format <v4l2-vbi-format>`
-
- - ``vbi``
-
- - Raw VBI capture or output parameters. This is discussed in more
- detail in :ref:`raw-vbi`. Used by raw VBI capture and output
- devices.
-
- - .. row 7
-
- -
- - struct :ref:`v4l2_sliced_vbi_format <v4l2-sliced-vbi-format>`
-
- - ``sliced``
-
- - Sliced VBI capture or output parameters. See :ref:`sliced` for
- details. Used by sliced VBI capture and output devices.
-
- - .. row 8
-
- -
- - struct :ref:`v4l2_sdr_format <v4l2-sdr-format>`
-
- - ``sdr``
-
- - Definition of a data format, see :ref:`pixfmt`, used by SDR
- capture and output devices.
-
- - .. row 9
-
- -
- - __u8
-
- - ``raw_data``\ [200]
-
- - Place holder for future extensions.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EINVAL
- The struct :ref:`v4l2_format <v4l2-format>` ``type`` field is
- invalid or the requested buffer type not supported.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_G_FREQUENCY:
-
-********************************************
-ioctl VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY
-********************************************
-
-Name
-====
-
-VIDIOC_G_FREQUENCY - VIDIOC_S_FREQUENCY - Get or set tuner or modulator radio frequency
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_frequency *argp )
-
-.. cpp:function:: int ioctl( int fd, int request, const struct v4l2_frequency *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY
-
-``argp``
-
-
-Description
-===========
-
-To get the current tuner or modulator radio frequency applications set
-the ``tuner`` field of a struct
-:ref:`v4l2_frequency <v4l2-frequency>` to the respective tuner or
-modulator number (only input devices have tuners, only output devices
-have modulators), zero out the ``reserved`` array and call the
-:ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl with a pointer to this structure. The
-driver stores the current frequency in the ``frequency`` field.
-
-To change the current tuner or modulator radio frequency applications
-initialize the ``tuner``, ``type`` and ``frequency`` fields, and the
-``reserved`` array of a struct :ref:`v4l2_frequency <v4l2-frequency>`
-and call the :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl with a pointer to this
-structure. When the requested frequency is not possible the driver
-assumes the closest possible value. However :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` is a
-write-only ioctl, it does not return the actual new frequency.
-
-
-.. _v4l2-frequency:
-
-.. flat-table:: struct v4l2_frequency
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``tuner``
-
- - The tuner or modulator index number. This is the same value as in
- the struct :ref:`v4l2_input <v4l2-input>` ``tuner`` field and
- the struct :ref:`v4l2_tuner <v4l2-tuner>` ``index`` field, or
- the struct :ref:`v4l2_output <v4l2-output>` ``modulator`` field
- and the struct :ref:`v4l2_modulator <v4l2-modulator>` ``index``
- field.
-
- - .. row 2
-
- - __u32
-
- - ``type``
-
- - The tuner type. This is the same value as in the struct
- :ref:`v4l2_tuner <v4l2-tuner>` ``type`` field. The type must be
- set to ``V4L2_TUNER_RADIO`` for ``/dev/radioX`` device nodes, and
- to ``V4L2_TUNER_ANALOG_TV`` for all others. Set this field to
- ``V4L2_TUNER_RADIO`` for modulators (currently only radio
- modulators are supported). See :ref:`v4l2-tuner-type`
-
- - .. row 3
-
- - __u32
-
- - ``frequency``
-
- - Tuning frequency in units of 62.5 kHz, or if the struct
- :ref:`v4l2_tuner <v4l2-tuner>` or struct
- :ref:`v4l2_modulator <v4l2-modulator>` ``capability`` flag
- ``V4L2_TUNER_CAP_LOW`` is set, in units of 62.5 Hz. A 1 Hz unit is
- used when the ``capability`` flag ``V4L2_TUNER_CAP_1HZ`` is set.
-
- - .. row 4
-
- - __u32
-
- - ``reserved``\ [8]
-
- - Reserved for future extensions. Drivers and applications must set
- the array to zero.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EINVAL
- The ``tuner`` index is out of bounds or the value in the ``type``
- field is wrong.
-
-EBUSY
- A hardware seek is in progress.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_G_INPUT:
-
-************************************
-ioctl VIDIOC_G_INPUT, VIDIOC_S_INPUT
-************************************
-
-Name
-====
-
-VIDIOC_G_INPUT - VIDIOC_S_INPUT - Query or select the current video input
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, int *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_G_INPUT, VIDIOC_S_INPUT
-
-``argp``
-
-
-Description
-===========
-
-To query the current video input applications call the
-:ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` ioctl with a pointer to an integer where the driver
-stores the number of the input, as in the struct
-:ref:`v4l2_input <v4l2-input>` ``index`` field. This ioctl will fail
-only when there are no video inputs, returning ``EINVAL``.
-
-To select a video input applications store the number of the desired
-input in an integer and call the :ref:`VIDIOC_S_INPUT <VIDIOC_G_INPUT>` ioctl with a pointer
-to this integer. Side effects are possible. For example inputs may
-support different video standards, so the driver may implicitly switch
-the current standard. Because of these possible side effects
-applications must select an input before querying or negotiating any
-other parameters.
-
-Information about video inputs is available using the
-:ref:`VIDIOC_ENUMINPUT` ioctl.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EINVAL
- The number of the video input is out of bounds.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_G_JPEGCOMP:
-
-******************************************
-ioctl VIDIOC_G_JPEGCOMP, VIDIOC_S_JPEGCOMP
-******************************************
-
-Name
-====
-
-VIDIOC_G_JPEGCOMP - VIDIOC_S_JPEGCOMP
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, v4l2_jpegcompression *argp )
-
-.. cpp:function:: int ioctl( int fd, int request, const v4l2_jpegcompression *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_G_JPEGCOMP, VIDIOC_S_JPEGCOMP
-
-``argp``
-
-
-Description
-===========
-
-These ioctls are **deprecated**. New drivers and applications should use
-:ref:`JPEG class controls <jpeg-controls>` for image quality and JPEG
-markers control.
-
-[to do]
-
-Ronald Bultje elaborates:
-
-APP is some application-specific information. The application can set it
-itself, and it'll be stored in the JPEG-encoded fields (eg; interlacing
-information for in an AVI or so). COM is the same, but it's comments,
-like 'encoded by me' or so.
-
-jpeg_markers describes whether the huffman tables, quantization tables
-and the restart interval information (all JPEG-specific stuff) should be
-stored in the JPEG-encoded fields. These define how the JPEG field is
-encoded. If you omit them, applications assume you've used standard
-encoding. You usually do want to add them.
-
-
-.. _v4l2-jpegcompression:
-
-.. flat-table:: struct v4l2_jpegcompression
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - int
-
- - ``quality``
-
- - Deprecated. If
- :ref:`V4L2_CID_JPEG_COMPRESSION_QUALITY <jpeg-quality-control>`
- control is exposed by a driver applications should use it instead
- and ignore this field.
-
- - .. row 2
-
- - int
-
- - ``APPn``
-
- -
-
- - .. row 3
-
- - int
-
- - ``APP_len``
-
- -
-
- - .. row 4
-
- - char
-
- - ``APP_data``\ [60]
-
- -
-
- - .. row 5
-
- - int
-
- - ``COM_len``
-
- -
-
- - .. row 6
-
- - char
-
- - ``COM_data``\ [60]
-
- -
-
- - .. row 7
-
- - __u32
-
- - ``jpeg_markers``
-
- - See :ref:`jpeg-markers`. Deprecated. If
- :ref:`V4L2_CID_JPEG_ACTIVE_MARKER <jpeg-active-marker-control>`
- control is exposed by a driver applications should use it instead
- and ignore this field.
-
-
-
-.. _jpeg-markers:
-
-.. flat-table:: JPEG Markers Flags
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - ``V4L2_JPEG_MARKER_DHT``
-
- - (1<<3)
-
- - Define Huffman Tables
-
- - .. row 2
-
- - ``V4L2_JPEG_MARKER_DQT``
-
- - (1<<4)
-
- - Define Quantization Tables
-
- - .. row 3
-
- - ``V4L2_JPEG_MARKER_DRI``
-
- - (1<<5)
-
- - Define Restart Interval
-
- - .. row 4
-
- - ``V4L2_JPEG_MARKER_COM``
-
- - (1<<6)
-
- - Comment segment
-
- - .. row 5
-
- - ``V4L2_JPEG_MARKER_APP``
-
- - (1<<7)
-
- - App segment, driver will always use APP0
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_G_MODULATOR:
-
-********************************************
-ioctl VIDIOC_G_MODULATOR, VIDIOC_S_MODULATOR
-********************************************
-
-Name
-====
-
-VIDIOC_G_MODULATOR - VIDIOC_S_MODULATOR - Get or set modulator attributes
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_modulator *argp )
-
-.. cpp:function:: int ioctl( int fd, int request, const struct v4l2_modulator *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_G_MODULATOR, VIDIOC_S_MODULATOR
-
-``argp``
-
-
-Description
-===========
-
-To query the attributes of a modulator applications initialize the
-``index`` field and zero out the ``reserved`` array of a struct
-:ref:`v4l2_modulator <v4l2-modulator>` and call the
-:ref:`VIDIOC_G_MODULATOR <VIDIOC_G_MODULATOR>` ioctl with a pointer to this structure. Drivers
-fill the rest of the structure or return an ``EINVAL`` error code when the
-index is out of bounds. To enumerate all modulators applications shall
-begin at index zero, incrementing by one until the driver returns
-EINVAL.
-
-Modulators have two writable properties, an audio modulation set and the
-radio frequency. To change the modulated audio subprograms, applications
-initialize the ``index`` and ``txsubchans`` fields and the ``reserved``
-array and call the :ref:`VIDIOC_S_MODULATOR <VIDIOC_G_MODULATOR>` ioctl. Drivers may choose a
-different audio modulation if the request cannot be satisfied. However
-this is a write-only ioctl, it does not return the actual audio
-modulation selected.
-
-:ref:`SDR <sdr>` specific modulator types are ``V4L2_TUNER_SDR`` and
-``V4L2_TUNER_RF``. For SDR devices ``txsubchans`` field must be
-initialized to zero. The term 'modulator' means SDR transmitter in this
-context.
-
-To change the radio frequency the
-:ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl is available.
-
-
-.. _v4l2-modulator:
-
-.. flat-table:: struct v4l2_modulator
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2 1 1
-
-
- - .. row 1
-
- - __u32
-
- - ``index``
-
- - Identifies the modulator, set by the application.
-
- - .. row 2
-
- - __u8
-
- - ``name``\ [32]
-
- - Name of the modulator, a NUL-terminated ASCII string. This
- information is intended for the user.
-
- - .. row 3
-
- - __u32
-
- - ``capability``
-
- - Modulator capability flags. No flags are defined for this field,
- the tuner flags in struct :ref:`v4l2_tuner <v4l2-tuner>` are
- used accordingly. The audio flags indicate the ability to encode
- audio subprograms. They will *not* change for example with the
- current video standard.
-
- - .. row 4
-
- - __u32
-
- - ``rangelow``
-
- - The lowest tunable frequency in units of 62.5 KHz, or if the
- ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in units of
- 62.5 Hz, or if the ``capability`` flag ``V4L2_TUNER_CAP_1HZ`` is
- set, in units of 1 Hz.
-
- - .. row 5
-
- - __u32
-
- - ``rangehigh``
-
- - The highest tunable frequency in units of 62.5 KHz, or if the
- ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in units of
- 62.5 Hz, or if the ``capability`` flag ``V4L2_TUNER_CAP_1HZ`` is
- set, in units of 1 Hz.
-
- - .. row 6
-
- - __u32
-
- - ``txsubchans``
-
- - With this field applications can determine how audio sub-carriers
- shall be modulated. It contains a set of flags as defined in
- :ref:`modulator-txsubchans`. Note the tuner ``rxsubchans`` flags
- are reused, but the semantics are different. Video output devices
- are assumed to have an analog or PCM audio input with 1-3
- channels. The ``txsubchans`` flags select one or more channels for
- modulation, together with some audio subprogram indicator, for
- example a stereo pilot tone.
-
- - .. row 7
-
- - __u32
-
- - ``type``
-
- - :cspan:`2` Type of the modulator, see :ref:`v4l2-tuner-type`.
-
- - .. row 8
-
- - __u32
-
- - ``reserved``\ [3]
-
- - Reserved for future extensions. Drivers and applications must set
- the array to zero.
-
-
-
-.. _modulator-txsubchans:
-
-.. flat-table:: Modulator Audio Transmission Flags
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - ``V4L2_TUNER_SUB_MONO``
-
- - 0x0001
-
- - Modulate channel 1 as mono audio, when the input has more
- channels, a down-mix of channel 1 and 2. This flag does not
- combine with ``V4L2_TUNER_SUB_STEREO`` or
- ``V4L2_TUNER_SUB_LANG1``.
-
- - .. row 2
-
- - ``V4L2_TUNER_SUB_STEREO``
-
- - 0x0002
-
- - Modulate channel 1 and 2 as left and right channel of a stereo
- audio signal. When the input has only one channel or two channels
- and ``V4L2_TUNER_SUB_SAP`` is also set, channel 1 is encoded as
- left and right channel. This flag does not combine with
- ``V4L2_TUNER_SUB_MONO`` or ``V4L2_TUNER_SUB_LANG1``. When the
- driver does not support stereo audio it shall fall back to mono.
-
- - .. row 3
-
- - ``V4L2_TUNER_SUB_LANG1``
-
- - 0x0008
-
- - Modulate channel 1 and 2 as primary and secondary language of a
- bilingual audio signal. When the input has only one channel it is
- used for both languages. It is not possible to encode the primary
- or secondary language only. This flag does not combine with
- ``V4L2_TUNER_SUB_MONO``, ``V4L2_TUNER_SUB_STEREO`` or
- ``V4L2_TUNER_SUB_SAP``. If the hardware does not support the
- respective audio matrix, or the current video standard does not
- permit bilingual audio the :ref:`VIDIOC_S_MODULATOR <VIDIOC_G_MODULATOR>` ioctl shall
- return an ``EINVAL`` error code and the driver shall fall back to mono
- or stereo mode.
-
- - .. row 4
-
- - ``V4L2_TUNER_SUB_LANG2``
-
- - 0x0004
-
- - Same effect as ``V4L2_TUNER_SUB_SAP``.
-
- - .. row 5
-
- - ``V4L2_TUNER_SUB_SAP``
-
- - 0x0004
-
- - When combined with ``V4L2_TUNER_SUB_MONO`` the first channel is
- encoded as mono audio, the last channel as Second Audio Program.
- When the input has only one channel it is used for both audio
- tracks. When the input has three channels the mono track is a
- down-mix of channel 1 and 2. When combined with
- ``V4L2_TUNER_SUB_STEREO`` channel 1 and 2 are encoded as left and
- right stereo audio, channel 3 as Second Audio Program. When the
- input has only two channels, the first is encoded as left and
- right channel and the second as SAP. When the input has only one
- channel it is used for all audio tracks. It is not possible to
- encode a Second Audio Program only. This flag must combine with
- ``V4L2_TUNER_SUB_MONO`` or ``V4L2_TUNER_SUB_STEREO``. If the
- hardware does not support the respective audio matrix, or the
- current video standard does not permit SAP the
- :ref:`VIDIOC_S_MODULATOR <VIDIOC_G_MODULATOR>` ioctl shall return an ``EINVAL`` error code and
- driver shall fall back to mono or stereo mode.
-
- - .. row 6
-
- - ``V4L2_TUNER_SUB_RDS``
-
- - 0x0010
-
- - Enable the RDS encoder for a radio FM transmitter.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EINVAL
- The struct :ref:`v4l2_modulator <v4l2-modulator>` ``index`` is
- out of bounds.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_G_OUTPUT:
-
-**************************************
-ioctl VIDIOC_G_OUTPUT, VIDIOC_S_OUTPUT
-**************************************
-
-Name
-====
-
-VIDIOC_G_OUTPUT - VIDIOC_S_OUTPUT - Query or select the current video output
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, int *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_G_OUTPUT, VIDIOC_S_OUTPUT
-
-``argp``
-
-
-Description
-===========
-
-To query the current video output applications call the
-:ref:`VIDIOC_G_OUTPUT <VIDIOC_G_OUTPUT>` ioctl with a pointer to an integer where the driver
-stores the number of the output, as in the struct
-:ref:`v4l2_output <v4l2-output>` ``index`` field. This ioctl will
-fail only when there are no video outputs, returning the ``EINVAL`` error
-code.
-
-To select a video output applications store the number of the desired
-output in an integer and call the :ref:`VIDIOC_S_OUTPUT <VIDIOC_G_OUTPUT>` ioctl with a
-pointer to this integer. Side effects are possible. For example outputs
-may support different video standards, so the driver may implicitly
-switch the current standard. standard. Because of these possible side
-effects applications must select an output before querying or
-negotiating any other parameters.
-
-Information about video outputs is available using the
-:ref:`VIDIOC_ENUMOUTPUT` ioctl.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EINVAL
- The number of the video output is out of bounds, or there are no
- video outputs at all.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_G_PARM:
-
-**********************************
-ioctl VIDIOC_G_PARM, VIDIOC_S_PARM
-**********************************
-
-Name
-====
-
-VIDIOC_G_PARM - VIDIOC_S_PARM - Get or set streaming parameters
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, v4l2_streamparm *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_G_PARM, VIDIOC_S_PARM
-
-``argp``
-
-
-Description
-===========
-
-The current video standard determines a nominal number of frames per
-second. If less than this number of frames is to be captured or output,
-applications can request frame skipping or duplicating on the driver
-side. This is especially useful when using the :ref:`read() <func-read>` or
-:ref:`write() <func-write>`, which are not augmented by timestamps or sequence
-counters, and to avoid unnecessary data copying.
-
-Further these ioctls can be used to determine the number of buffers used
-internally by a driver in read/write mode. For implications see the
-section discussing the :ref:`read() <func-read>` function.
-
-To get and set the streaming parameters applications call the
-:ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` ioctl, respectively. They take a
-pointer to a struct :ref:`struct v4l2_streamparm <v4l2-streamparm>` which contains a
-union holding separate parameters for input and output devices.
-
-
-.. _v4l2-streamparm:
-
-.. flat-table:: struct v4l2_streamparm
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``type``
-
- -
- - The buffer (stream) type, same as struct
- :ref:`v4l2_format <v4l2-format>` ``type``, set by the
- application. See :ref:`v4l2-buf-type`
-
- - .. row 2
-
- - union
-
- - ``parm``
-
- -
- -
-
- - .. row 3
-
- -
- - struct :ref:`v4l2_captureparm <v4l2-captureparm>`
-
- - ``capture``
-
- - Parameters for capture devices, used when ``type`` is
- ``V4L2_BUF_TYPE_VIDEO_CAPTURE``.
-
- - .. row 4
-
- -
- - struct :ref:`v4l2_outputparm <v4l2-outputparm>`
-
- - ``output``
-
- - Parameters for output devices, used when ``type`` is
- ``V4L2_BUF_TYPE_VIDEO_OUTPUT``.
-
- - .. row 5
-
- -
- - __u8
-
- - ``raw_data``\ [200]
-
- - A place holder for future extensions.
-
-
-
-.. _v4l2-captureparm:
-
-.. flat-table:: struct v4l2_captureparm
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``capability``
-
- - See :ref:`parm-caps`.
-
- - .. row 2
-
- - __u32
-
- - ``capturemode``
-
- - Set by drivers and applications, see :ref:`parm-flags`.
-
- - .. row 3
-
- - struct :ref:`v4l2_fract <v4l2-fract>`
-
- - ``timeperframe``
-
- - This is the desired period between successive frames captured by
- the driver, in seconds. The field is intended to skip frames on
- the driver side, saving I/O bandwidth.
-
- Applications store here the desired frame period, drivers return
- the actual frame period, which must be greater or equal to the
- nominal frame period determined by the current video standard
- (struct :ref:`v4l2_standard <v4l2-standard>` ``frameperiod``
- field). Changing the video standard (also implicitly by switching
- the video input) may reset this parameter to the nominal frame
- period. To reset manually applications can just set this field to
- zero.
-
- Drivers support this function only when they set the
- ``V4L2_CAP_TIMEPERFRAME`` flag in the ``capability`` field.
-
- - .. row 4
-
- - __u32
-
- - ``extendedmode``
-
- - Custom (driver specific) streaming parameters. When unused,
- applications and drivers must set this field to zero. Applications
- using this field should check the driver name and version, see
- :ref:`querycap`.
-
- - .. row 5
-
- - __u32
-
- - ``readbuffers``
-
- - Applications set this field to the desired number of buffers used
- internally by the driver in :ref:`read() <func-read>` mode.
- Drivers return the actual number of buffers. When an application
- requests zero buffers, drivers should just return the current
- setting rather than the minimum or an error code. For details see
- :ref:`rw`.
-
- - .. row 6
-
- - __u32
-
- - ``reserved``\ [4]
-
- - Reserved for future extensions. Drivers and applications must set
- the array to zero.
-
-
-
-.. _v4l2-outputparm:
-
-.. flat-table:: struct v4l2_outputparm
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``capability``
-
- - See :ref:`parm-caps`.
-
- - .. row 2
-
- - __u32
-
- - ``outputmode``
-
- - Set by drivers and applications, see :ref:`parm-flags`.
-
- - .. row 3
-
- - struct :ref:`v4l2_fract <v4l2-fract>`
-
- - ``timeperframe``
-
- - This is the desired period between successive frames output by the
- driver, in seconds.
-
- - .. row 4
-
- - :cspan:`2`
-
- The field is intended to repeat frames on the driver side in
- :ref:`write() <func-write>` mode (in streaming mode timestamps
- can be used to throttle the output), saving I/O bandwidth.
-
- Applications store here the desired frame period, drivers return
- the actual frame period, which must be greater or equal to the
- nominal frame period determined by the current video standard
- (struct :ref:`v4l2_standard <v4l2-standard>` ``frameperiod``
- field). Changing the video standard (also implicitly by switching
- the video output) may reset this parameter to the nominal frame
- period. To reset manually applications can just set this field to
- zero.
-
- Drivers support this function only when they set the
- ``V4L2_CAP_TIMEPERFRAME`` flag in the ``capability`` field.
-
- - .. row 5
-
- - __u32
-
- - ``extendedmode``
-
- - Custom (driver specific) streaming parameters. When unused,
- applications and drivers must set this field to zero. Applications
- using this field should check the driver name and version, see
- :ref:`querycap`.
-
- - .. row 6
-
- - __u32
-
- - ``writebuffers``
-
- - Applications set this field to the desired number of buffers used
- internally by the driver in :ref:`write() <func-write>` mode. Drivers
- return the actual number of buffers. When an application requests
- zero buffers, drivers should just return the current setting
- rather than the minimum or an error code. For details see
- :ref:`rw`.
-
- - .. row 7
-
- - __u32
-
- - ``reserved``\ [4]
-
- - Reserved for future extensions. Drivers and applications must set
- the array to zero.
-
-
-
-.. _parm-caps:
-
-.. flat-table:: Streaming Parameters Capabilites
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - ``V4L2_CAP_TIMEPERFRAME``
-
- - 0x1000
-
- - The frame skipping/repeating controlled by the ``timeperframe``
- field is supported.
-
-
-
-.. _parm-flags:
-
-.. flat-table:: Capture Parameters Flags
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - ``V4L2_MODE_HIGHQUALITY``
-
- - 0x0001
-
- - High quality imaging mode. High quality mode is intended for still
- imaging applications. The idea is to get the best possible image
- quality that the hardware can deliver. It is not defined how the
- driver writer may achieve that; it will depend on the hardware and
- the ingenuity of the driver writer. High quality mode is a
- different mode from the regular motion video capture modes. In
- high quality mode:
-
- - The driver may be able to capture higher resolutions than for
- motion capture.
-
- - The driver may support fewer pixel formats than motion capture
- (eg; true color).
-
- - The driver may capture and arithmetically combine multiple
- successive fields or frames to remove color edge artifacts and
- reduce the noise in the video data.
-
- - The driver may capture images in slices like a scanner in order
- to handle larger format images than would otherwise be
- possible.
-
- - An image capture operation may be significantly slower than
- motion capture.
-
- - Moving objects in the image might have excessive motion blur.
-
- - Capture might only work through the :ref:`read() <func-read>` call.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_G_PRIORITY:
-
-******************************************
-ioctl VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY
-******************************************
-
-Name
-====
-
-VIDIOC_G_PRIORITY - VIDIOC_S_PRIORITY - Query or request the access priority associated with a file descriptor
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, enum v4l2_priority *argp )
-
-.. cpp:function:: int ioctl( int fd, int request, const enum v4l2_priority *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY
-
-``argp``
- Pointer to an enum v4l2_priority type.
-
-
-Description
-===========
-
-To query the current access priority applications call the
-:ref:`VIDIOC_G_PRIORITY <VIDIOC_G_PRIORITY>` ioctl with a pointer to an enum v4l2_priority
-variable where the driver stores the current priority.
-
-To request an access priority applications store the desired priority in
-an enum v4l2_priority variable and call :ref:`VIDIOC_S_PRIORITY <VIDIOC_G_PRIORITY>` ioctl
-with a pointer to this variable.
-
-
-.. _v4l2-priority:
-
-.. flat-table:: enum v4l2_priority
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - ``V4L2_PRIORITY_UNSET``
-
- - 0
-
- -
-
- - .. row 2
-
- - ``V4L2_PRIORITY_BACKGROUND``
-
- - 1
-
- - Lowest priority, usually applications running in background, for
- example monitoring VBI transmissions. A proxy application running
- in user space will be necessary if multiple applications want to
- read from a device at this priority.
-
- - .. row 3
-
- - ``V4L2_PRIORITY_INTERACTIVE``
-
- - 2
-
- -
-
- - .. row 4
-
- - ``V4L2_PRIORITY_DEFAULT``
-
- - 2
-
- - Medium priority, usually applications started and interactively
- controlled by the user. For example TV viewers, Teletext browsers,
- or just "panel" applications to change the channel or video
- controls. This is the default priority unless an application
- requests another.
-
- - .. row 5
-
- - ``V4L2_PRIORITY_RECORD``
-
- - 3
-
- - Highest priority. Only one file descriptor can have this priority,
- it blocks any other fd from changing device properties. Usually
- applications which must not be interrupted, like video recording.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EINVAL
- The requested priority value is invalid.
-
-EBUSY
- Another application already requested higher priority.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_G_SELECTION:
-
-********************************************
-ioctl VIDIOC_G_SELECTION, VIDIOC_S_SELECTION
-********************************************
-
-Name
-====
-
-VIDIOC_G_SELECTION - VIDIOC_S_SELECTION - Get or set one of the selection rectangles
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_selection *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_G_SELECTION, VIDIOC_S_SELECTION
-
-``argp``
-
-
-Description
-===========
-
-The ioctls are used to query and configure selection rectangles.
-
-To query the cropping (composing) rectangle set struct
-:ref:`v4l2_selection <v4l2-selection>` ``type`` field to the
-respective buffer type. Do not use the multiplanar buffer types. Use
-``V4L2_BUF_TYPE_VIDEO_CAPTURE`` instead of
-``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and use
-``V4L2_BUF_TYPE_VIDEO_OUTPUT`` instead of
-``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``. The next step is setting the
-value of struct :ref:`v4l2_selection <v4l2-selection>` ``target``
-field to ``V4L2_SEL_TGT_CROP`` (``V4L2_SEL_TGT_COMPOSE``). Please refer
-to table :ref:`v4l2-selections-common` or :ref:`selection-api` for
-additional targets. The ``flags`` and ``reserved`` fields of struct
-:ref:`v4l2_selection <v4l2-selection>` are ignored and they must be
-filled with zeros. The driver fills the rest of the structure or returns
-EINVAL error code if incorrect buffer type or target was used. If
-cropping (composing) is not supported then the active rectangle is not
-mutable and it is always equal to the bounds rectangle. Finally, the
-struct :ref:`v4l2_rect <v4l2-rect>` ``r`` rectangle is filled with
-the current cropping (composing) coordinates. The coordinates are
-expressed in driver-dependent units. The only exception are rectangles
-for images in raw formats, whose coordinates are always expressed in
-pixels.
-
-To change the cropping (composing) rectangle set the struct
-:ref:`v4l2_selection <v4l2-selection>` ``type`` field to the
-respective buffer type. Do not use multiplanar buffers. Use
-``V4L2_BUF_TYPE_VIDEO_CAPTURE`` instead of
-``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``. Use
-``V4L2_BUF_TYPE_VIDEO_OUTPUT`` instead of
-``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``. The next step is setting the
-value of struct :ref:`v4l2_selection <v4l2-selection>` ``target`` to
-``V4L2_SEL_TGT_CROP`` (``V4L2_SEL_TGT_COMPOSE``). Please refer to table
-:ref:`v4l2-selections-common` or :ref:`selection-api` for additional
-targets. The struct :ref:`v4l2_rect <v4l2-rect>` ``r`` rectangle need
-to be set to the desired active area. Field struct
-:ref:`v4l2_selection <v4l2-selection>` ``reserved`` is ignored and
-must be filled with zeros. The driver may adjust coordinates of the
-requested rectangle. An application may introduce constraints to control
-rounding behaviour. The struct :ref:`v4l2_selection <v4l2-selection>`
-``flags`` field must be set to one of the following:
-
-- ``0`` - The driver can adjust the rectangle size freely and shall
- choose a crop/compose rectangle as close as possible to the requested
- one.
-
-- ``V4L2_SEL_FLAG_GE`` - The driver is not allowed to shrink the
- rectangle. The original rectangle must lay inside the adjusted one.
-
-- ``V4L2_SEL_FLAG_LE`` - The driver is not allowed to enlarge the
- rectangle. The adjusted rectangle must lay inside the original one.
-
-- ``V4L2_SEL_FLAG_GE | V4L2_SEL_FLAG_LE`` - The driver must choose the
- size exactly the same as in the requested rectangle.
-
-Please refer to :ref:`sel-const-adjust`.
-
-The driver may have to adjusts the requested dimensions against hardware
-limits and other parts as the pipeline, i.e. the bounds given by the
-capture/output window or TV display. The closest possible values of
-horizontal and vertical offset and sizes are chosen according to
-following priority:
-
-1. Satisfy constraints from struct
- :ref:`v4l2_selection <v4l2-selection>` ``flags``.
-
-2. Adjust width, height, left, and top to hardware limits and
- alignments.
-
-3. Keep center of adjusted rectangle as close as possible to the
- original one.
-
-4. Keep width and height as close as possible to original ones.
-
-5. Keep horizontal and vertical offset as close as possible to original
- ones.
-
-On success the struct :ref:`v4l2_rect <v4l2-rect>` ``r`` field
-contains the adjusted rectangle. When the parameters are unsuitable the
-application may modify the cropping (composing) or image parameters and
-repeat the cycle until satisfactory parameters have been negotiated. If
-constraints flags have to be violated at then ``ERANGE`` is returned. The
-error indicates that *there exist no rectangle* that satisfies the
-constraints.
-
-Selection targets and flags are documented in
-:ref:`v4l2-selections-common`.
-
-
-.. _sel-const-adjust:
-
-.. figure:: vidioc-g-selection_files/constraints.*
- :alt: constraints.png
- :align: center
-
- Size adjustments with constraint flags.
-
- Behaviour of rectangle adjustment for different constraint flags.
-
-
-
-
-.. _v4l2-selection:
-
-.. flat-table:: struct v4l2_selection
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``type``
-
- - Type of the buffer (from enum
- :ref:`v4l2_buf_type <v4l2-buf-type>`).
-
- - .. row 2
-
- - __u32
-
- - ``target``
-
- - Used to select between
- :ref:`cropping and composing rectangles <v4l2-selections-common>`.
-
- - .. row 3
-
- - __u32
-
- - ``flags``
-
- - Flags controlling the selection rectangle adjustments, refer to
- :ref:`selection flags <v4l2-selection-flags>`.
-
- - .. row 4
-
- - struct :ref:`v4l2_rect <v4l2-rect>`
-
- - ``r``
-
- - The selection rectangle.
-
- - .. row 5
-
- - __u32
-
- - ``reserved[9]``
-
- - Reserved fields for future use. Drivers and applications must zero
- this array.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EINVAL
- Given buffer type ``type`` or the selection target ``target`` is not
- supported, or the ``flags`` argument is not valid.
-
-ERANGE
- It is not possible to adjust struct :ref:`v4l2_rect <v4l2-rect>`
- ``r`` rectangle to satisfy all constraints given in the ``flags``
- argument.
-
-EBUSY
- It is not possible to apply change of the selection rectangle at the
- moment. Usually because streaming is in progress.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_G_SLICED_VBI_CAP:
-
-*****************************
-ioctl VIDIOC_G_SLICED_VBI_CAP
-*****************************
-
-Name
-====
-
-VIDIOC_G_SLICED_VBI_CAP - Query sliced VBI capabilities
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_sliced_vbi_cap *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_G_SLICED_VBI_CAP
-
-``argp``
-
-
-Description
-===========
-
-To find out which data services are supported by a sliced VBI capture or
-output device, applications initialize the ``type`` field of a struct
-:ref:`v4l2_sliced_vbi_cap <v4l2-sliced-vbi-cap>`, clear the
-``reserved`` array and call the :ref:`VIDIOC_G_SLICED_VBI_CAP <VIDIOC_G_SLICED_VBI_CAP>` ioctl. The
-driver fills in the remaining fields or returns an ``EINVAL`` error code if
-the sliced VBI API is unsupported or ``type`` is invalid.
-
-Note the ``type`` field was added, and the ioctl changed from read-only
-to write-read, in Linux 2.6.19.
-
-
-.. _v4l2-sliced-vbi-cap:
-
-.. flat-table:: struct v4l2_sliced_vbi_cap
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 3 2 2 2
-
-
- - .. row 1
-
- - __u16
-
- - ``service_set``
-
- - :cspan:`2` A set of all data services supported by the driver.
- Equal to the union of all elements of the ``service_lines`` array.
-
- - .. row 2
-
- - __u16
-
- - ``service_lines``\ [2][24]
-
- - :cspan:`2` Each element of this array contains a set of data
- services the hardware can look for or insert into a particular
- scan line. Data services are defined in :ref:`vbi-services`.
- Array indices map to ITU-R line numbers (see also :ref:`vbi-525`
- and :ref:`vbi-625`) as follows:
-
- - .. row 3
-
- -
- -
- - Element
-
- - 525 line systems
-
- - 625 line systems
-
- - .. row 4
-
- -
- -
- - ``service_lines``\ [0][1]
-
- - 1
-
- - 1
-
- - .. row 5
-
- -
- -
- - ``service_lines``\ [0][23]
-
- - 23
-
- - 23
-
- - .. row 6
-
- -
- -
- - ``service_lines``\ [1][1]
-
- - 264
-
- - 314
-
- - .. row 7
-
- -
- -
- - ``service_lines``\ [1][23]
-
- - 286
-
- - 336
-
- - .. row 8
-
- -
-
- - .. row 9
-
- -
- -
- - :cspan:`2` The number of VBI lines the hardware can capture or
- output per frame, or the number of services it can identify on a
- given line may be limited. For example on PAL line 16 the hardware
- may be able to look for a VPS or Teletext signal, but not both at
- the same time. Applications can learn about these limits using the
- :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl as described in
- :ref:`sliced`.
-
- - .. row 10
-
- -
-
- - .. row 11
-
- -
- -
- - :cspan:`2` Drivers must set ``service_lines`` [0][0] and
- ``service_lines``\ [1][0] to zero.
-
- - .. row 12
-
- - __u32
-
- - ``type``
-
- - Type of the data stream, see :ref:`v4l2-buf-type`. Should be
- ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE`` or
- ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT``.
-
- - .. row 13
-
- - __u32
-
- - ``reserved``\ [3]
-
- - :cspan:`2` This array is reserved for future extensions.
- Applications and drivers must set it to zero.
-
-
-
-.. _vbi-services:
-
-.. flat-table:: Sliced VBI services
- :header-rows: 1
- :stub-columns: 0
- :widths: 2 1 1 2 2
-
-
- - .. row 1
-
- - Symbol
-
- - Value
-
- - Reference
-
- - Lines, usually
-
- - Payload
-
- - .. row 2
-
- - ``V4L2_SLICED_TELETEXT_B`` (Teletext System B)
-
- - 0x0001
-
- - :ref:`ets300706`, :ref:`itu653`
-
- - PAL/SECAM line 7-22, 320-335 (second field 7-22)
-
- - Last 42 of the 45 byte Teletext packet, that is without clock
- run-in and framing code, lsb first transmitted.
-
- - .. row 3
-
- - ``V4L2_SLICED_VPS``
-
- - 0x0400
-
- - :ref:`ets300231`
-
- - PAL line 16
-
- - Byte number 3 to 15 according to Figure 9 of ETS 300 231, lsb
- first transmitted.
-
- - .. row 4
-
- - ``V4L2_SLICED_CAPTION_525``
-
- - 0x1000
-
- - :ref:`cea608`
-
- - NTSC line 21, 284 (second field 21)
-
- - Two bytes in transmission order, including parity bit, lsb first
- transmitted.
-
- - .. row 5
-
- - ``V4L2_SLICED_WSS_625``
-
- - 0x4000
-
- - :ref:`en300294`, :ref:`itu1119`
-
- - PAL/SECAM line 23
-
- -
-
- ::
-
- Byte 0 1
- msb lsb msb lsb
- Bit 7 6 5 4 3 2 1 0 x x 13 12 11 10 9
-
- - .. row 6
-
- - ``V4L2_SLICED_VBI_525``
-
- - 0x1000
-
- - :cspan:`2` Set of services applicable to 525 line systems.
-
- - .. row 7
-
- - ``V4L2_SLICED_VBI_625``
-
- - 0x4401
-
- - :cspan:`2` Set of services applicable to 625 line systems.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EINVAL
- The value in the ``type`` field is wrong.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_G_STD:
-
-********************************
-ioctl VIDIOC_G_STD, VIDIOC_S_STD
-********************************
-
-Name
-====
-
-VIDIOC_G_STD - VIDIOC_S_STD - Query or select the video standard of the current input
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, v4l2_std_id *argp )
-
-.. cpp:function:: int ioctl( int fd, int request, const v4l2_std_id *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_G_STD, VIDIOC_S_STD
-
-``argp``
-
-
-Description
-===========
-
-To query and select the current video standard applications use the
-:ref:`VIDIOC_G_STD <VIDIOC_G_STD>` and :ref:`VIDIOC_S_STD <VIDIOC_G_STD>` ioctls which take a pointer to a
-:ref:`v4l2_std_id <v4l2-std-id>` type as argument. :ref:`VIDIOC_G_STD <VIDIOC_G_STD>`
-can return a single flag or a set of flags as in struct
-:ref:`v4l2_standard <v4l2-standard>` field ``id``. The flags must be
-unambiguous such that they appear in only one enumerated
-:ref:`struct v4l2_standard <v4l2-standard>` structure.
-
-:ref:`VIDIOC_S_STD <VIDIOC_G_STD>` accepts one or more flags, being a write-only ioctl it
-does not return the actual new standard as :ref:`VIDIOC_G_STD <VIDIOC_G_STD>` does. When
-no flags are given or the current input does not support the requested
-standard the driver returns an ``EINVAL`` error code. When the standard set
-is ambiguous drivers may return ``EINVAL`` or choose any of the requested
-standards. If the current input or output does not support standard
-video timings (e.g. if :ref:`VIDIOC_ENUMINPUT`
-does not set the ``V4L2_IN_CAP_STD`` flag), then ``ENODATA`` error code is
-returned.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EINVAL
- The :ref:`VIDIOC_S_STD <VIDIOC_G_STD>` parameter was unsuitable.
-
-ENODATA
- Standard video timings are not supported for this input or output.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_G_TUNER:
-
-************************************
-ioctl VIDIOC_G_TUNER, VIDIOC_S_TUNER
-************************************
-
-Name
-====
-
-VIDIOC_G_TUNER - VIDIOC_S_TUNER - Get or set tuner attributes
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_tuner *argp )
-
-.. cpp:function:: int ioctl( int fd, int request, const struct v4l2_tuner *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_G_TUNER, VIDIOC_S_TUNER
-
-``argp``
-
-
-Description
-===========
-
-To query the attributes of a tuner applications initialize the ``index``
-field and zero out the ``reserved`` array of a struct
-:ref:`v4l2_tuner <v4l2-tuner>` and call the ``VIDIOC_G_TUNER`` ioctl
-with a pointer to this structure. Drivers fill the rest of the structure
-or return an ``EINVAL`` error code when the index is out of bounds. To
-enumerate all tuners applications shall begin at index zero,
-incrementing by one until the driver returns ``EINVAL``.
-
-Tuners have two writable properties, the audio mode and the radio
-frequency. To change the audio mode, applications initialize the
-``index``, ``audmode`` and ``reserved`` fields and call the
-``VIDIOC_S_TUNER`` ioctl. This will *not* change the current tuner,
-which is determined by the current video input. Drivers may choose a
-different audio mode if the requested mode is invalid or unsupported.
-Since this is a write-only ioctl, it does not return the actually
-selected audio mode.
-
-:ref:`SDR <sdr>` specific tuner types are ``V4L2_TUNER_SDR`` and
-``V4L2_TUNER_RF``. For SDR devices ``audmode`` field must be initialized
-to zero. The term 'tuner' means SDR receiver in this context.
-
-To change the radio frequency the
-:ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl is available.
-
-
-.. _v4l2-tuner:
-
-.. flat-table:: struct v4l2_tuner
- :header-rows: 0
- :stub-columns: 0
-
-
- - .. row 1
-
- - __u32
-
- - ``index``
-
- - :cspan:`1` Identifies the tuner, set by the application.
-
- - .. row 2
-
- - __u8
-
- - ``name``\ [32]
-
- - :cspan:`1`
-
- Name of the tuner, a NUL-terminated ASCII string. This information
- is intended for the user.
-
- - .. row 3
-
- - __u32
-
- - ``type``
-
- - :cspan:`1` Type of the tuner, see :ref:`v4l2-tuner-type`.
-
- - .. row 4
-
- - __u32
-
- - ``capability``
-
- - :cspan:`1`
-
- Tuner capability flags, see :ref:`tuner-capability`. Audio flags
- indicate the ability to decode audio subprograms. They will *not*
- change, for example with the current video standard.
-
- When the structure refers to a radio tuner the
- ``V4L2_TUNER_CAP_LANG1``, ``V4L2_TUNER_CAP_LANG2`` and
- ``V4L2_TUNER_CAP_NORM`` flags can't be used.
-
- If multiple frequency bands are supported, then ``capability`` is
- the union of all ``capability`` fields of each struct
- :ref:`v4l2_frequency_band <v4l2-frequency-band>`.
-
- - .. row 5
-
- - __u32
-
- - ``rangelow``
-
- - :cspan:`1` The lowest tunable frequency in units of 62.5 kHz, or
- if the ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in units
- of 62.5 Hz, or if the ``capability`` flag ``V4L2_TUNER_CAP_1HZ``
- is set, in units of 1 Hz. If multiple frequency bands are
- supported, then ``rangelow`` is the lowest frequency of all the
- frequency bands.
-
- - .. row 6
-
- - __u32
-
- - ``rangehigh``
-
- - :cspan:`1` The highest tunable frequency in units of 62.5 kHz,
- or if the ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in
- units of 62.5 Hz, or if the ``capability`` flag
- ``V4L2_TUNER_CAP_1HZ`` is set, in units of 1 Hz. If multiple
- frequency bands are supported, then ``rangehigh`` is the highest
- frequency of all the frequency bands.
-
- - .. row 7
-
- - __u32
-
- - ``rxsubchans``
-
- - :cspan:`1`
-
- Some tuners or audio decoders can determine the received audio
- subprograms by analyzing audio carriers, pilot tones or other
- indicators. To pass this information drivers set flags defined in
- :ref:`tuner-rxsubchans` in this field. For example:
-
- - .. row 8
-
- -
- -
- - ``V4L2_TUNER_SUB_MONO``
-
- - receiving mono audio
-
- - .. row 9
-
- -
- -
- - ``STEREO | SAP``
-
- - receiving stereo audio and a secondary audio program
-
- - .. row 10
-
- -
- -
- - ``MONO | STEREO``
-
- - receiving mono or stereo audio, the hardware cannot distinguish
-
- - .. row 11
-
- -
- -
- - ``LANG1 | LANG2``
-
- - receiving bilingual audio
-
- - .. row 12
-
- -
- -
- - ``MONO | STEREO | LANG1 | LANG2``
-
- - receiving mono, stereo or bilingual audio
-
- - .. row 13
-
- -
- -
- - :cspan:`1`
-
- When the ``V4L2_TUNER_CAP_STEREO``, ``_LANG1``, ``_LANG2`` or
- ``_SAP`` flag is cleared in the ``capability`` field, the
- corresponding ``V4L2_TUNER_SUB_`` flag must not be set here.
-
- This field is valid only if this is the tuner of the current video
- input, or when the structure refers to a radio tuner.
-
- - .. row 14
-
- - __u32
-
- - ``audmode``
-
- - :cspan:`1`
-
- The selected audio mode, see :ref:`tuner-audmode` for valid
- values. The audio mode does not affect audio subprogram detection,
- and like a :ref:`control` it does not automatically
- change unless the requested mode is invalid or unsupported. See
- :ref:`tuner-matrix` for possible results when the selected and
- received audio programs do not match.
-
- Currently this is the only field of struct
- :ref:`struct v4l2_tuner <v4l2-tuner>` applications can change.
-
- - .. row 15
-
- - __u32
-
- - ``signal``
-
- - :cspan:`1` The signal strength if known, ranging from 0 to
- 65535. Higher values indicate a better signal.
-
- - .. row 16
-
- - __s32
-
- - ``afc``
-
- - :cspan:`1` Automatic frequency control: When the ``afc`` value
- is negative, the frequency is too low, when positive too high.
-
- - .. row 17
-
- - __u32
-
- - ``reserved``\ [4]
-
- - :cspan:`1` Reserved for future extensions. Drivers and
- applications must set the array to zero.
-
-
-
-.. _v4l2-tuner-type:
-
-.. flat-table:: enum v4l2_tuner_type
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - ``V4L2_TUNER_RADIO``
-
- - 1
-
- -
-
- - .. row 2
-
- - ``V4L2_TUNER_ANALOG_TV``
-
- - 2
-
- -
-
- - .. row 3
-
- - ``V4L2_TUNER_SDR``
-
- - 4
-
- -
-
- - .. row 4
-
- - ``V4L2_TUNER_RF``
-
- - 5
-
- -
-
-
-
-.. _tuner-capability:
-
-.. flat-table:: Tuner and Modulator Capability Flags
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - ``V4L2_TUNER_CAP_LOW``
-
- - 0x0001
-
- - When set, tuning frequencies are expressed in units of 62.5 Hz
- instead of 62.5 kHz.
-
- - .. row 2
-
- - ``V4L2_TUNER_CAP_NORM``
-
- - 0x0002
-
- - This is a multi-standard tuner; the video standard can or must be
- switched. (B/G PAL tuners for example are typically not considered
- multi-standard because the video standard is automatically
- determined from the frequency band.) The set of supported video
- standards is available from the struct
- :ref:`v4l2_input <v4l2-input>` pointing to this tuner, see the
- description of ioctl :ref:`VIDIOC_ENUMINPUT`
- for details. Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this
- capability.
-
- - .. row 3
-
- - ``V4L2_TUNER_CAP_HWSEEK_BOUNDED``
-
- - 0x0004
-
- - If set, then this tuner supports the hardware seek functionality
- where the seek stops when it reaches the end of the frequency
- range.
-
- - .. row 4
-
- - ``V4L2_TUNER_CAP_HWSEEK_WRAP``
-
- - 0x0008
-
- - If set, then this tuner supports the hardware seek functionality
- where the seek wraps around when it reaches the end of the
- frequency range.
-
- - .. row 5
-
- - ``V4L2_TUNER_CAP_STEREO``
-
- - 0x0010
-
- - Stereo audio reception is supported.
-
- - .. row 6
-
- - ``V4L2_TUNER_CAP_LANG1``
-
- - 0x0040
-
- - Reception of the primary language of a bilingual audio program is
- supported. Bilingual audio is a feature of two-channel systems,
- transmitting the primary language monaural on the main audio
- carrier and a secondary language monaural on a second carrier.
- Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this capability.
-
- - .. row 7
-
- - ``V4L2_TUNER_CAP_LANG2``
-
- - 0x0020
-
- - Reception of the secondary language of a bilingual audio program
- is supported. Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this
- capability.
-
- - .. row 8
-
- - ``V4L2_TUNER_CAP_SAP``
-
- - 0x0020
-
- - Reception of a secondary audio program is supported. This is a
- feature of the BTSC system which accompanies the NTSC video
- standard. Two audio carriers are available for mono or stereo
- transmissions of a primary language, and an independent third
- carrier for a monaural secondary language. Only
- ``V4L2_TUNER_ANALOG_TV`` tuners can have this capability.
-
- Note the ``V4L2_TUNER_CAP_LANG2`` and ``V4L2_TUNER_CAP_SAP`` flags
- are synonyms. ``V4L2_TUNER_CAP_SAP`` applies when the tuner
- supports the ``V4L2_STD_NTSC_M`` video standard.
-
- - .. row 9
-
- - ``V4L2_TUNER_CAP_RDS``
-
- - 0x0080
-
- - RDS capture is supported. This capability is only valid for radio
- tuners.
-
- - .. row 10
-
- - ``V4L2_TUNER_CAP_RDS_BLOCK_IO``
-
- - 0x0100
-
- - The RDS data is passed as unparsed RDS blocks.
-
- - .. row 11
-
- - ``V4L2_TUNER_CAP_RDS_CONTROLS``
-
- - 0x0200
-
- - The RDS data is parsed by the hardware and set via controls.
-
- - .. row 12
-
- - ``V4L2_TUNER_CAP_FREQ_BANDS``
-
- - 0x0400
-
- - The :ref:`VIDIOC_ENUM_FREQ_BANDS`
- ioctl can be used to enumerate the available frequency bands.
-
- - .. row 13
-
- - ``V4L2_TUNER_CAP_HWSEEK_PROG_LIM``
-
- - 0x0800
-
- - The range to search when using the hardware seek functionality is
- programmable, see
- :ref:`VIDIOC_S_HW_FREQ_SEEK` for
- details.
-
- - .. row 14
-
- - ``V4L2_TUNER_CAP_1HZ``
-
- - 0x1000
-
- - When set, tuning frequencies are expressed in units of 1 Hz
- instead of 62.5 kHz.
-
-
-
-.. _tuner-rxsubchans:
-
-.. flat-table:: Tuner Audio Reception Flags
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - ``V4L2_TUNER_SUB_MONO``
-
- - 0x0001
-
- - The tuner receives a mono audio signal.
-
- - .. row 2
-
- - ``V4L2_TUNER_SUB_STEREO``
-
- - 0x0002
-
- - The tuner receives a stereo audio signal.
-
- - .. row 3
-
- - ``V4L2_TUNER_SUB_LANG1``
-
- - 0x0008
-
- - The tuner receives the primary language of a bilingual audio
- signal. Drivers must clear this flag when the current video
- standard is ``V4L2_STD_NTSC_M``.
-
- - .. row 4
-
- - ``V4L2_TUNER_SUB_LANG2``
-
- - 0x0004
-
- - The tuner receives the secondary language of a bilingual audio
- signal (or a second audio program).
-
- - .. row 5
-
- - ``V4L2_TUNER_SUB_SAP``
-
- - 0x0004
-
- - The tuner receives a Second Audio Program. Note the
- ``V4L2_TUNER_SUB_LANG2`` and ``V4L2_TUNER_SUB_SAP`` flags are
- synonyms. The ``V4L2_TUNER_SUB_SAP`` flag applies when the current
- video standard is ``V4L2_STD_NTSC_M``.
-
- - .. row 6
-
- - ``V4L2_TUNER_SUB_RDS``
-
- - 0x0010
-
- - The tuner receives an RDS channel.
-
-
-
-.. _tuner-audmode:
-
-.. flat-table:: Tuner Audio Modes
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - ``V4L2_TUNER_MODE_MONO``
-
- - 0
-
- - Play mono audio. When the tuner receives a stereo signal this a
- down-mix of the left and right channel. When the tuner receives a
- bilingual or SAP signal this mode selects the primary language.
-
- - .. row 2
-
- - ``V4L2_TUNER_MODE_STEREO``
-
- - 1
-
- - Play stereo audio. When the tuner receives bilingual audio it may
- play different languages on the left and right channel or the
- primary language is played on both channels.
-
- Playing different languages in this mode is deprecated. New
- drivers should do this only in ``MODE_LANG1_LANG2``.
-
- When the tuner receives no stereo signal or does not support
- stereo reception the driver shall fall back to ``MODE_MONO``.
-
- - .. row 3
-
- - ``V4L2_TUNER_MODE_LANG1``
-
- - 3
-
- - Play the primary language, mono or stereo. Only
- ``V4L2_TUNER_ANALOG_TV`` tuners support this mode.
-
- - .. row 4
-
- - ``V4L2_TUNER_MODE_LANG2``
-
- - 2
-
- - Play the secondary language, mono. When the tuner receives no
- bilingual audio or SAP, or their reception is not supported the
- driver shall fall back to mono or stereo mode. Only
- ``V4L2_TUNER_ANALOG_TV`` tuners support this mode.
-
- - .. row 5
-
- - ``V4L2_TUNER_MODE_SAP``
-
- - 2
-
- - Play the Second Audio Program. When the tuner receives no
- bilingual audio or SAP, or their reception is not supported the
- driver shall fall back to mono or stereo mode. Only
- ``V4L2_TUNER_ANALOG_TV`` tuners support this mode. Note the
- ``V4L2_TUNER_MODE_LANG2`` and ``V4L2_TUNER_MODE_SAP`` are
- synonyms.
-
- - .. row 6
-
- - ``V4L2_TUNER_MODE_LANG1_LANG2``
-
- - 4
-
- - Play the primary language on the left channel, the secondary
- language on the right channel. When the tuner receives no
- bilingual audio or SAP, it shall fall back to ``MODE_LANG1`` or
- ``MODE_MONO``. Only ``V4L2_TUNER_ANALOG_TV`` tuners support this
- mode.
-
-
-
-.. _tuner-matrix:
-
-.. flat-table:: Tuner Audio Matrix
- :header-rows: 2
- :stub-columns: 0
-
-
- - .. row 1
-
- -
- - :cspan:`5` Selected ``V4L2_TUNER_MODE_``
-
- - .. row 2
-
- - Received ``V4L2_TUNER_SUB_``
-
- - ``MONO``
-
- - ``STEREO``
-
- - ``LANG1``
-
- - ``LANG2 = SAP``
-
- - ``LANG1_LANG2``\ [1]_
-
- - .. row 3
-
- - ``MONO``
-
- - Mono
-
- - Mono/Mono
-
- - Mono
-
- - Mono
-
- - Mono/Mono
-
- - .. row 4
-
- - ``MONO | SAP``
-
- - Mono
-
- - Mono/Mono
-
- - Mono
-
- - SAP
-
- - Mono/SAP (preferred) or Mono/Mono
-
- - .. row 5
-
- - ``STEREO``
-
- - L+R
-
- - L/R
-
- - Stereo L/R (preferred) or Mono L+R
-
- - Stereo L/R (preferred) or Mono L+R
-
- - L/R (preferred) or L+R/L+R
-
- - .. row 6
-
- - ``STEREO | SAP``
-
- - L+R
-
- - L/R
-
- - Stereo L/R (preferred) or Mono L+R
-
- - SAP
-
- - L+R/SAP (preferred) or L/R or L+R/L+R
-
- - .. row 7
-
- - ``LANG1 | LANG2``
-
- - Language 1
-
- - Lang1/Lang2 (deprecated [2]_) or Lang1/Lang1
-
- - Language 1
-
- - Language 2
-
- - Lang1/Lang2 (preferred) or Lang1/Lang1
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EINVAL
- The struct :ref:`v4l2_tuner <v4l2-tuner>` ``index`` is out of
- bounds.
-
-.. [1]
- This mode has been added in Linux 2.6.17 and may not be supported by
- older drivers.
-
-.. [2]
- Playback of both languages in ``MODE_STEREO`` is deprecated. In the
- future drivers should produce only the primary language in this mode.
- Applications should request ``MODE_LANG1_LANG2`` to record both
- languages or a stereo signal.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_LOG_STATUS:
-
-***********************
-ioctl VIDIOC_LOG_STATUS
-***********************
-
-Name
-====
-
-VIDIOC_LOG_STATUS - Log driver status information
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request )
-
-
-Arguments
-=========
-
-
-
-Description
-===========
-
-As the video/audio devices become more complicated it becomes harder to
-debug problems. When this ioctl is called the driver will output the
-current device status to the kernel log. This is particular useful when
-dealing with problems like no sound, no video and incorrectly tuned
-channels. Also many modern devices autodetect video and audio standards
-and this ioctl will report what the device thinks what the standard is.
-Mismatches may give an indication where the problem is.
-
-This ioctl is optional and not all drivers support it. It was introduced
-in Linux 2.6.15.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_OVERLAY:
-
-********************
-ioctl VIDIOC_OVERLAY
-********************
-
-Name
-====
-
-VIDIOC_OVERLAY - Start or stop video overlay
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, const int *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_OVERLAY
-
-``argp``
-
-
-Description
-===========
-
-This ioctl is part of the :ref:`video overlay <overlay>` I/O method.
-Applications call :ref:`VIDIOC_OVERLAY` to start or stop the overlay. It
-takes a pointer to an integer which must be set to zero by the
-application to stop overlay, to one to start.
-
-Drivers do not support :ref:`VIDIOC_STREAMON` or
-:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` with
-``V4L2_BUF_TYPE_VIDEO_OVERLAY``.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EINVAL
- The overlay parameters have not been set up. See :ref:`overlay`
- for the necessary steps.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_PREPARE_BUF:
-
-************************
-ioctl VIDIOC_PREPARE_BUF
-************************
-
-Name
-====
-
-VIDIOC_PREPARE_BUF - Prepare a buffer for I/O
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_buffer *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_PREPARE_BUF
-
-``argp``
-
-
-Description
-===========
-
-Applications can optionally call the :ref:`VIDIOC_PREPARE_BUF` ioctl to
-pass ownership of the buffer to the driver before actually enqueuing it,
-using the :ref:`VIDIOC_QBUF` ioctl, and to prepare it for future I/O. Such
-preparations may include cache invalidation or cleaning. Performing them
-in advance saves time during the actual I/O. In case such cache
-operations are not required, the application can use one of
-``V4L2_BUF_FLAG_NO_CACHE_INVALIDATE`` and
-``V4L2_BUF_FLAG_NO_CACHE_CLEAN`` flags to skip the respective step.
-
-The :ref:`struct v4l2_buffer <v4l2-buffer>` structure is specified in
-:ref:`buffer`.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EBUSY
- File I/O is in progress.
-
-EINVAL
- The buffer ``type`` is not supported, or the ``index`` is out of
- bounds, or no buffers have been allocated yet, or the ``userptr`` or
- ``length`` are invalid.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_QBUF:
-
-*******************************
-ioctl VIDIOC_QBUF, VIDIOC_DQBUF
-*******************************
-
-Name
-====
-
-VIDIOC_QBUF - VIDIOC_DQBUF - Exchange a buffer with the driver
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_buffer *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_QBUF, VIDIOC_DQBUF
-
-``argp``
-
-
-Description
-===========
-
-Applications call the ``VIDIOC_QBUF`` ioctl to enqueue an empty
-(capturing) or filled (output) buffer in the driver's incoming queue.
-The semantics depend on the selected I/O method.
-
-To enqueue a buffer applications set the ``type`` field of a struct
-:ref:`v4l2_buffer <v4l2-buffer>` to the same buffer type as was
-previously used with struct :ref:`v4l2_format <v4l2-format>` ``type``
-and struct :ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``type``.
-Applications must also set the ``index`` field. Valid index numbers
-range from zero to the number of buffers allocated with
-:ref:`VIDIOC_REQBUFS` (struct
-:ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``count``) minus
-one. The contents of the struct :ref:`struct v4l2_buffer <v4l2-buffer>` returned
-by a :ref:`VIDIOC_QUERYBUF` ioctl will do as well.
-When the buffer is intended for output (``type`` is
-``V4L2_BUF_TYPE_VIDEO_OUTPUT``, ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``,
-or ``V4L2_BUF_TYPE_VBI_OUTPUT``) applications must also initialize the
-``bytesused``, ``field`` and ``timestamp`` fields, see :ref:`buffer`
-for details. Applications must also set ``flags`` to 0. The
-``reserved2`` and ``reserved`` fields must be set to 0. When using the
-:ref:`multi-planar API <planar-apis>`, the ``m.planes`` field must
-contain a userspace pointer to a filled-in array of struct
-:ref:`v4l2_plane <v4l2-plane>` and the ``length`` field must be set
-to the number of elements in that array.
-
-To enqueue a :ref:`memory mapped <mmap>` buffer applications set the
-``memory`` field to ``V4L2_MEMORY_MMAP``. When ``VIDIOC_QBUF`` is called
-with a pointer to this structure the driver sets the
-``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_QUEUED`` flags and clears
-the ``V4L2_BUF_FLAG_DONE`` flag in the ``flags`` field, or it returns an
-EINVAL error code.
-
-To enqueue a :ref:`user pointer <userp>` buffer applications set the
-``memory`` field to ``V4L2_MEMORY_USERPTR``, the ``m.userptr`` field to
-the address of the buffer and ``length`` to its size. When the
-multi-planar API is used, ``m.userptr`` and ``length`` members of the
-passed array of struct :ref:`v4l2_plane <v4l2-plane>` have to be used
-instead. When ``VIDIOC_QBUF`` is called with a pointer to this structure
-the driver sets the ``V4L2_BUF_FLAG_QUEUED`` flag and clears the
-``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_DONE`` flags in the
-``flags`` field, or it returns an error code. This ioctl locks the
-memory pages of the buffer in physical memory, they cannot be swapped
-out to disk. Buffers remain locked until dequeued, until the
-:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or
-:ref:`VIDIOC_REQBUFS` ioctl is called, or until the
-device is closed.
-
-To enqueue a :ref:`DMABUF <dmabuf>` buffer applications set the
-``memory`` field to ``V4L2_MEMORY_DMABUF`` and the ``m.fd`` field to a
-file descriptor associated with a DMABUF buffer. When the multi-planar
-API is used the ``m.fd`` fields of the passed array of struct
-:ref:`v4l2_plane <v4l2-plane>` have to be used instead. When
-``VIDIOC_QBUF`` is called with a pointer to this structure the driver
-sets the ``V4L2_BUF_FLAG_QUEUED`` flag and clears the
-``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_DONE`` flags in the
-``flags`` field, or it returns an error code. This ioctl locks the
-buffer. Locking a buffer means passing it to a driver for a hardware
-access (usually DMA). If an application accesses (reads/writes) a locked
-buffer then the result is undefined. Buffers remain locked until
-dequeued, until the :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or
-:ref:`VIDIOC_REQBUFS` ioctl is called, or until the
-device is closed.
-
-Applications call the ``VIDIOC_DQBUF`` ioctl to dequeue a filled
-(capturing) or displayed (output) buffer from the driver's outgoing
-queue. They just set the ``type``, ``memory`` and ``reserved`` fields of
-a struct :ref:`v4l2_buffer <v4l2-buffer>` as above, when
-``VIDIOC_DQBUF`` is called with a pointer to this structure the driver
-fills the remaining fields or returns an error code. The driver may also
-set ``V4L2_BUF_FLAG_ERROR`` in the ``flags`` field. It indicates a
-non-critical (recoverable) streaming error. In such case the application
-may continue as normal, but should be aware that data in the dequeued
-buffer might be corrupted. When using the multi-planar API, the planes
-array must be passed in as well.
-
-By default ``VIDIOC_DQBUF`` blocks when no buffer is in the outgoing
-queue. When the ``O_NONBLOCK`` flag was given to the
-:ref:`open() <func-open>` function, ``VIDIOC_DQBUF`` returns
-immediately with an ``EAGAIN`` error code when no buffer is available.
-
-The :ref:`struct v4l2_buffer <v4l2-buffer>` structure is specified in
-:ref:`buffer`.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EAGAIN
- Non-blocking I/O has been selected using ``O_NONBLOCK`` and no
- buffer was in the outgoing queue.
-
-EINVAL
- The buffer ``type`` is not supported, or the ``index`` is out of
- bounds, or no buffers have been allocated yet, or the ``userptr`` or
- ``length`` are invalid.
-
-EIO
- ``VIDIOC_DQBUF`` failed due to an internal error. Can also indicate
- temporary problems like signal loss. Note the driver might dequeue
- an (empty) buffer despite returning an error, or even stop
- capturing. Reusing such buffer may be unsafe though and its details
- (e.g. ``index``) may not be returned either. It is recommended that
- drivers indicate recoverable errors by setting the
- ``V4L2_BUF_FLAG_ERROR`` and returning 0 instead. In that case the
- application should be able to safely reuse the buffer and continue
- streaming.
-
-EPIPE
- ``VIDIOC_DQBUF`` returns this on an empty capture queue for mem2mem
- codecs if a buffer with the ``V4L2_BUF_FLAG_LAST`` was already
- dequeued and no new buffers are expected to become available.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_QUERY_DV_TIMINGS:
-
-*****************************
-ioctl VIDIOC_QUERY_DV_TIMINGS
-*****************************
-
-Name
-====
-
-VIDIOC_QUERY_DV_TIMINGS - VIDIOC_SUBDEV_QUERY_DV_TIMINGS - Sense the DV preset received by the current input
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_dv_timings *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_QUERY_DV_TIMINGS, VIDIOC_SUBDEV_QUERY_DV_TIMINGS
-
-``argp``
-
-
-Description
-===========
-
-The hardware may be able to detect the current DV timings automatically,
-similar to sensing the video standard. To do so, applications call
-:ref:`VIDIOC_QUERY_DV_TIMINGS` with a pointer to a struct
-:ref:`v4l2_dv_timings <v4l2-dv-timings>`. Once the hardware detects
-the timings, it will fill in the timings structure.
-
-Please note that drivers shall *not* switch timings automatically if new
-timings are detected. Instead, drivers should send the
-``V4L2_EVENT_SOURCE_CHANGE`` event (if they support this) and expect
-that userspace will take action by calling :ref:`VIDIOC_QUERY_DV_TIMINGS`.
-The reason is that new timings usually mean different buffer sizes as
-well, and you cannot change buffer sizes on the fly. In general,
-applications that receive the Source Change event will have to call
-:ref:`VIDIOC_QUERY_DV_TIMINGS`, and if the detected timings are valid they
-will have to stop streaming, set the new timings, allocate new buffers
-and start streaming again.
-
-If the timings could not be detected because there was no signal, then
-ENOLINK is returned. If a signal was detected, but it was unstable and
-the receiver could not lock to the signal, then ``ENOLCK`` is returned. If
-the receiver could lock to the signal, but the format is unsupported
-(e.g. because the pixelclock is out of range of the hardware
-capabilities), then the driver fills in whatever timings it could find
-and returns ``ERANGE``. In that case the application can call
-:ref:`VIDIOC_DV_TIMINGS_CAP` to compare the
-found timings with the hardware's capabilities in order to give more
-precise feedback to the user.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-ENODATA
- Digital video timings are not supported for this input or output.
-
-ENOLINK
- No timings could be detected because no signal was found.
-
-ENOLCK
- The signal was unstable and the hardware could not lock on to it.
-
-ERANGE
- Timings were found, but they are out of range of the hardware
- capabilities.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_QUERYBUF:
-
-*********************
-ioctl VIDIOC_QUERYBUF
-*********************
-
-Name
-====
-
-VIDIOC_QUERYBUF - Query the status of a buffer
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_buffer *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_QUERYBUF
-
-``argp``
-
-
-Description
-===========
-
-This ioctl is part of the :ref:`streaming <mmap>` I/O method. It can
-be used to query the status of a buffer at any time after buffers have
-been allocated with the :ref:`VIDIOC_REQBUFS` ioctl.
-
-Applications set the ``type`` field of a struct
-:ref:`v4l2_buffer <v4l2-buffer>` to the same buffer type as was
-previously used with struct :ref:`v4l2_format <v4l2-format>` ``type``
-and struct :ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``type``,
-and the ``index`` field. Valid index numbers range from zero to the
-number of buffers allocated with
-:ref:`VIDIOC_REQBUFS` (struct
-:ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``count``) minus
-one. The ``reserved`` and ``reserved2`` fields must be set to 0. When
-using the :ref:`multi-planar API <planar-apis>`, the ``m.planes``
-field must contain a userspace pointer to an array of struct
-:ref:`v4l2_plane <v4l2-plane>` and the ``length`` field has to be set
-to the number of elements in that array. After calling
-:ref:`VIDIOC_QUERYBUF` with a pointer to this structure drivers return an
-error code or fill the rest of the structure.
-
-In the ``flags`` field the ``V4L2_BUF_FLAG_MAPPED``,
-``V4L2_BUF_FLAG_PREPARED``, ``V4L2_BUF_FLAG_QUEUED`` and
-``V4L2_BUF_FLAG_DONE`` flags will be valid. The ``memory`` field will be
-set to the current I/O method. For the single-planar API, the
-``m.offset`` contains the offset of the buffer from the start of the
-device memory, the ``length`` field its size. For the multi-planar API,
-fields ``m.mem_offset`` and ``length`` in the ``m.planes`` array
-elements will be used instead and the ``length`` field of struct
-:ref:`v4l2_buffer <v4l2-buffer>` is set to the number of filled-in
-array elements. The driver may or may not set the remaining fields and
-flags, they are meaningless in this context.
-
-The :ref:`struct v4l2_buffer <v4l2-buffer>` structure is specified in
-:ref:`buffer`.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EINVAL
- The buffer ``type`` is not supported, or the ``index`` is out of
- bounds.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_QUERYCAP:
-
-*********************
-ioctl VIDIOC_QUERYCAP
-*********************
-
-Name
-====
-
-VIDIOC_QUERYCAP - Query device capabilities
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_capability *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_QUERYCAP
-
-``argp``
-
-
-Description
-===========
-
-All V4L2 devices support the ``VIDIOC_QUERYCAP`` ioctl. It is used to
-identify kernel devices compatible with this specification and to obtain
-information about driver and hardware capabilities. The ioctl takes a
-pointer to a struct :ref:`v4l2_capability <v4l2-capability>` which is
-filled by the driver. When the driver is not compatible with this
-specification the ioctl returns an ``EINVAL`` error code.
-
-
-.. _v4l2-capability:
-
-.. flat-table:: struct v4l2_capability
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u8
-
- - ``driver``\ [16]
-
- - Name of the driver, a unique NUL-terminated ASCII string. For
- example: "bttv". Driver specific applications can use this
- information to verify the driver identity. It is also useful to
- work around known bugs, or to identify drivers in error reports.
-
- Storing strings in fixed sized arrays is bad practice but
- unavoidable here. Drivers and applications should take precautions
- to never read or write beyond the end of the array and to make
- sure the strings are properly NUL-terminated.
-
- - .. row 2
-
- - __u8
-
- - ``card``\ [32]
-
- - Name of the device, a NUL-terminated UTF-8 string. For example:
- "Yoyodyne TV/FM". One driver may support different brands or
- models of video hardware. This information is intended for users,
- for example in a menu of available devices. Since multiple TV
- cards of the same brand may be installed which are supported by
- the same driver, this name should be combined with the character
- device file name (e. g. ``/dev/video2``) or the ``bus_info``
- string to avoid ambiguities.
-
- - .. row 3
-
- - __u8
-
- - ``bus_info``\ [32]
-
- - Location of the device in the system, a NUL-terminated ASCII
- string. For example: "PCI:0000:05:06.0". This information is
- intended for users, to distinguish multiple identical devices. If
- no such information is available the field must simply count the
- devices controlled by the driver ("platform:vivi-000"). The
- bus_info must start with "PCI:" for PCI boards, "PCIe:" for PCI
- Express boards, "usb-" for USB devices, "I2C:" for i2c devices,
- "ISA:" for ISA devices, "parport" for parallel port devices and
- "platform:" for platform devices.
-
- - .. row 4
-
- - __u32
-
- - ``version``
-
- - Version number of the driver.
-
- Starting with kernel 3.1, the version reported is provided by the
- V4L2 subsystem following the kernel numbering scheme. However, it
- may not always return the same version as the kernel if, for
- example, a stable or distribution-modified kernel uses the V4L2
- stack from a newer kernel.
-
- The version number is formatted using the ``KERNEL_VERSION()``
- macro:
-
- - .. row 5
-
- - :cspan:`2`
-
-
- .. code-block:: c
-
- #define KERNEL_VERSION(a,b,c) (((a) << 16) + ((b) << 8) + (c))
-
- __u32 version = KERNEL_VERSION(0, 8, 1);
-
- printf ("Version: %u.%u.%u\\n",
- (version >> 16) & 0xFF,
- (version >> 8) & 0xFF,
- version & 0xFF);
-
- - .. row 6
-
- - __u32
-
- - ``capabilities``
-
- - Available capabilities of the physical device as a whole, see
- :ref:`device-capabilities`. The same physical device can export
- multiple devices in /dev (e.g. /dev/videoX, /dev/vbiY and
- /dev/radioZ). The ``capabilities`` field should contain a union of
- all capabilities available around the several V4L2 devices
- exported to userspace. For all those devices the ``capabilities``
- field returns the same set of capabilities. This allows
- applications to open just one of the devices (typically the video
- device) and discover whether video, vbi and/or radio are also
- supported.
-
- - .. row 7
-
- - __u32
-
- - ``device_caps``
-
- - Device capabilities of the opened device, see
- :ref:`device-capabilities`. Should contain the available
- capabilities of that specific device node. So, for example,
- ``device_caps`` of a radio device will only contain radio related
- capabilities and no video or vbi capabilities. This field is only
- set if the ``capabilities`` field contains the
- ``V4L2_CAP_DEVICE_CAPS`` capability. Only the ``capabilities``
- field can have the ``V4L2_CAP_DEVICE_CAPS`` capability,
- ``device_caps`` will never set ``V4L2_CAP_DEVICE_CAPS``.
-
- - .. row 8
-
- - __u32
-
- - ``reserved``\ [3]
-
- - Reserved for future extensions. Drivers must set this array to
- zero.
-
-
-
-.. _device-capabilities:
-
-.. flat-table:: Device Capabilities Flags
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - ``V4L2_CAP_VIDEO_CAPTURE``
-
- - 0x00000001
-
- - The device supports the single-planar API through the
- :ref:`Video Capture <capture>` interface.
-
- - .. row 2
-
- - ``V4L2_CAP_VIDEO_CAPTURE_MPLANE``
-
- - 0x00001000
-
- - The device supports the :ref:`multi-planar API <planar-apis>`
- through the :ref:`Video Capture <capture>` interface.
-
- - .. row 3
-
- - ``V4L2_CAP_VIDEO_OUTPUT``
-
- - 0x00000002
-
- - The device supports the single-planar API through the
- :ref:`Video Output <output>` interface.
-
- - .. row 4
-
- - ``V4L2_CAP_VIDEO_OUTPUT_MPLANE``
-
- - 0x00002000
-
- - The device supports the :ref:`multi-planar API <planar-apis>`
- through the :ref:`Video Output <output>` interface.
-
- - .. row 5
-
- - ``V4L2_CAP_VIDEO_M2M``
-
- - 0x00004000
-
- - The device supports the single-planar API through the Video
- Memory-To-Memory interface.
-
- - .. row 6
-
- - ``V4L2_CAP_VIDEO_M2M_MPLANE``
-
- - 0x00008000
-
- - The device supports the :ref:`multi-planar API <planar-apis>`
- through the Video Memory-To-Memory interface.
-
- - .. row 7
-
- - ``V4L2_CAP_VIDEO_OVERLAY``
-
- - 0x00000004
-
- - The device supports the :ref:`Video Overlay <overlay>`
- interface. A video overlay device typically stores captured images
- directly in the video memory of a graphics card, with hardware
- clipping and scaling.
-
- - .. row 8
-
- - ``V4L2_CAP_VBI_CAPTURE``
-
- - 0x00000010
-
- - The device supports the :ref:`Raw VBI Capture <raw-vbi>`
- interface, providing Teletext and Closed Caption data.
-
- - .. row 9
-
- - ``V4L2_CAP_VBI_OUTPUT``
-
- - 0x00000020
-
- - The device supports the :ref:`Raw VBI Output <raw-vbi>`
- interface.
-
- - .. row 10
-
- - ``V4L2_CAP_SLICED_VBI_CAPTURE``
-
- - 0x00000040
-
- - The device supports the :ref:`Sliced VBI Capture <sliced>`
- interface.
-
- - .. row 11
-
- - ``V4L2_CAP_SLICED_VBI_OUTPUT``
-
- - 0x00000080
-
- - The device supports the :ref:`Sliced VBI Output <sliced>`
- interface.
-
- - .. row 12
-
- - ``V4L2_CAP_RDS_CAPTURE``
-
- - 0x00000100
-
- - The device supports the :ref:`RDS <rds>` capture interface.
-
- - .. row 13
-
- - ``V4L2_CAP_VIDEO_OUTPUT_OVERLAY``
-
- - 0x00000200
-
- - The device supports the :ref:`Video Output Overlay <osd>` (OSD)
- interface. Unlike the *Video Overlay* interface, this is a
- secondary function of video output devices and overlays an image
- onto an outgoing video signal. When the driver sets this flag, it
- must clear the ``V4L2_CAP_VIDEO_OVERLAY`` flag and vice
- versa. [1]_
-
- - .. row 14
-
- - ``V4L2_CAP_HW_FREQ_SEEK``
-
- - 0x00000400
-
- - The device supports the
- :ref:`VIDIOC_S_HW_FREQ_SEEK` ioctl
- for hardware frequency seeking.
-
- - .. row 15
-
- - ``V4L2_CAP_RDS_OUTPUT``
-
- - 0x00000800
-
- - The device supports the :ref:`RDS <rds>` output interface.
-
- - .. row 16
-
- - ``V4L2_CAP_TUNER``
-
- - 0x00010000
-
- - The device has some sort of tuner to receive RF-modulated video
- signals. For more information about tuner programming see
- :ref:`tuner`.
-
- - .. row 17
-
- - ``V4L2_CAP_AUDIO``
-
- - 0x00020000
-
- - The device has audio inputs or outputs. It may or may not support
- audio recording or playback, in PCM or compressed formats. PCM
- audio support must be implemented as ALSA or OSS interface. For
- more information on audio inputs and outputs see :ref:`audio`.
-
- - .. row 18
-
- - ``V4L2_CAP_RADIO``
-
- - 0x00040000
-
- - This is a radio receiver.
-
- - .. row 19
-
- - ``V4L2_CAP_MODULATOR``
-
- - 0x00080000
-
- - The device has some sort of modulator to emit RF-modulated
- video/audio signals. For more information about modulator
- programming see :ref:`tuner`.
-
- - .. row 20
-
- - ``V4L2_CAP_SDR_CAPTURE``
-
- - 0x00100000
-
- - The device supports the :ref:`SDR Capture <sdr>` interface.
-
- - .. row 21
-
- - ``V4L2_CAP_EXT_PIX_FORMAT``
-
- - 0x00200000
-
- - The device supports the struct
- :ref:`v4l2_pix_format <v4l2-pix-format>` extended fields.
-
- - .. row 22
-
- - ``V4L2_CAP_SDR_OUTPUT``
-
- - 0x00400000
-
- - The device supports the :ref:`SDR Output <sdr>` interface.
-
- - .. row 23
-
- - ``V4L2_CAP_READWRITE``
-
- - 0x01000000
-
- - The device supports the :ref:`read() <rw>` and/or
- :ref:`write() <rw>` I/O methods.
-
- - .. row 24
-
- - ``V4L2_CAP_ASYNCIO``
-
- - 0x02000000
-
- - The device supports the :ref:`asynchronous <async>` I/O methods.
-
- - .. row 25
-
- - ``V4L2_CAP_STREAMING``
-
- - 0x04000000
-
- - The device supports the :ref:`streaming <mmap>` I/O method.
-
- - .. row 26
-
- - ``V4L2_CAP_DEVICE_CAPS``
-
- - 0x80000000
-
- - The driver fills the ``device_caps`` field. This capability can
- only appear in the ``capabilities`` field and never in the
- ``device_caps`` field.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-.. [1]
- The struct :ref:`v4l2_framebuffer <v4l2-framebuffer>` lacks an
- enum :ref:`v4l2_buf_type <v4l2-buf-type>` field, therefore the
- type of overlay is implied by the driver capabilities.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_QUERYCTRL:
-
-*******************************************************************
-ioctls VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL and VIDIOC_QUERYMENU
-*******************************************************************
-
-Name
-====
-
-VIDIOC_QUERYCTRL - VIDIOC_QUERY_EXT_CTRL - VIDIOC_QUERYMENU - Enumerate controls and menu control items
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_queryctrl *argp )
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_query_ext_ctrl *argp )
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_querymenu *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL, VIDIOC_QUERYMENU
-
-``argp``
-
-
-Description
-===========
-
-To query the attributes of a control applications set the ``id`` field
-of a struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` and call the
-``VIDIOC_QUERYCTRL`` ioctl with a pointer to this structure. The driver
-fills the rest of the structure or returns an ``EINVAL`` error code when the
-``id`` is invalid.
-
-It is possible to enumerate controls by calling ``VIDIOC_QUERYCTRL``
-with successive ``id`` values starting from ``V4L2_CID_BASE`` up to and
-exclusive ``V4L2_CID_LASTP1``. Drivers may return ``EINVAL`` if a control in
-this range is not supported. Further applications can enumerate private
-controls, which are not defined in this specification, by starting at
-``V4L2_CID_PRIVATE_BASE`` and incrementing ``id`` until the driver
-returns ``EINVAL``.
-
-In both cases, when the driver sets the ``V4L2_CTRL_FLAG_DISABLED`` flag
-in the ``flags`` field this control is permanently disabled and should
-be ignored by the application. [1]_
-
-When the application ORs ``id`` with ``V4L2_CTRL_FLAG_NEXT_CTRL`` the
-driver returns the next supported non-compound control, or ``EINVAL`` if
-there is none. In addition, the ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` flag
-can be specified to enumerate all compound controls (i.e. controls with
-type ≥ ``V4L2_CTRL_COMPOUND_TYPES`` and/or array control, in other words
-controls that contain more than one value). Specify both
-``V4L2_CTRL_FLAG_NEXT_CTRL`` and ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` in
-order to enumerate all controls, compound or not. Drivers which do not
-support these flags yet always return ``EINVAL``.
-
-The ``VIDIOC_QUERY_EXT_CTRL`` ioctl was introduced in order to better
-support controls that can use compound types, and to expose additional
-control information that cannot be returned in struct
-:ref:`v4l2_queryctrl <v4l2-queryctrl>` since that structure is full.
-
-``VIDIOC_QUERY_EXT_CTRL`` is used in the same way as
-``VIDIOC_QUERYCTRL``, except that the ``reserved`` array must be zeroed
-as well.
-
-Additional information is required for menu controls: the names of the
-menu items. To query them applications set the ``id`` and ``index``
-fields of struct :ref:`v4l2_querymenu <v4l2-querymenu>` and call the
-``VIDIOC_QUERYMENU`` ioctl with a pointer to this structure. The driver
-fills the rest of the structure or returns an ``EINVAL`` error code when the
-``id`` or ``index`` is invalid. Menu items are enumerated by calling
-``VIDIOC_QUERYMENU`` with successive ``index`` values from struct
-:ref:`v4l2_queryctrl <v4l2-queryctrl>` ``minimum`` to ``maximum``,
-inclusive. Note that it is possible for ``VIDIOC_QUERYMENU`` to return
-an ``EINVAL`` error code for some indices between ``minimum`` and
-``maximum``. In that case that particular menu item is not supported by
-this driver. Also note that the ``minimum`` value is not necessarily 0.
-
-See also the examples in :ref:`control`.
-
-
-.. _v4l2-queryctrl:
-
-.. flat-table:: struct v4l2_queryctrl
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``id``
-
- - Identifies the control, set by the application. See
- :ref:`control-id` for predefined IDs. When the ID is ORed with
- V4L2_CTRL_FLAG_NEXT_CTRL the driver clears the flag and
- returns the first control with a higher ID. Drivers which do not
- support this flag yet always return an ``EINVAL`` error code.
-
- - .. row 2
-
- - __u32
-
- - ``type``
-
- - Type of control, see :ref:`v4l2-ctrl-type`.
-
- - .. row 3
-
- - __u8
-
- - ``name``\ [32]
-
- - Name of the control, a NUL-terminated ASCII string. This
- information is intended for the user.
-
- - .. row 4
-
- - __s32
-
- - ``minimum``
-
- - Minimum value, inclusive. This field gives a lower bound for the
- control. See enum :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how
- the minimum value is to be used for each possible control type.
- Note that this a signed 32-bit value.
-
- - .. row 5
-
- - __s32
-
- - ``maximum``
-
- - Maximum value, inclusive. This field gives an upper bound for the
- control. See enum :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how
- the maximum value is to be used for each possible control type.
- Note that this a signed 32-bit value.
-
- - .. row 6
-
- - __s32
-
- - ``step``
-
- - This field gives a step size for the control. See enum
- :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how the step value is
- to be used for each possible control type. Note that this an
- unsigned 32-bit value.
-
- Generally drivers should not scale hardware control values. It may
- be necessary for example when the ``name`` or ``id`` imply a
- particular unit and the hardware actually accepts only multiples
- of said unit. If so, drivers must take care values are properly
- rounded when scaling, such that errors will not accumulate on
- repeated read-write cycles.
-
- This field gives the smallest change of an integer control
- actually affecting hardware. Often the information is needed when
- the user can change controls by keyboard or GUI buttons, rather
- than a slider. When for example a hardware register accepts values
- 0-511 and the driver reports 0-65535, step should be 128.
-
- Note that although signed, the step value is supposed to be always
- positive.
-
- - .. row 7
-
- - __s32
-
- - ``default_value``
-
- - The default value of a ``V4L2_CTRL_TYPE_INTEGER``, ``_BOOLEAN``,
- ``_BITMASK``, ``_MENU`` or ``_INTEGER_MENU`` control. Not valid
- for other types of controls. Note that drivers reset controls to
- their default value only when the driver is first loaded, never
- afterwards.
-
- - .. row 8
-
- - __u32
-
- - ``flags``
-
- - Control flags, see :ref:`control-flags`.
-
- - .. row 9
-
- - __u32
-
- - ``reserved``\ [2]
-
- - Reserved for future extensions. Drivers must set the array to
- zero.
-
-
-
-.. _v4l2-query-ext-ctrl:
-
-.. flat-table:: struct v4l2_query_ext_ctrl
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``id``
-
- - Identifies the control, set by the application. See
- :ref:`control-id` for predefined IDs. When the ID is ORed with
- ``V4L2_CTRL_FLAG_NEXT_CTRL`` the driver clears the flag and
- returns the first non-compound control with a higher ID. When the
- ID is ORed with ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` the driver clears
- the flag and returns the first compound control with a higher ID.
- Set both to get the first control (compound or not) with a higher
- ID.
-
- - .. row 2
-
- - __u32
-
- - ``type``
-
- - Type of control, see :ref:`v4l2-ctrl-type`.
-
- - .. row 3
-
- - char
-
- - ``name``\ [32]
-
- - Name of the control, a NUL-terminated ASCII string. This
- information is intended for the user.
-
- - .. row 4
-
- - __s64
-
- - ``minimum``
-
- - Minimum value, inclusive. This field gives a lower bound for the
- control. See enum :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how
- the minimum value is to be used for each possible control type.
- Note that this a signed 64-bit value.
-
- - .. row 5
-
- - __s64
-
- - ``maximum``
-
- - Maximum value, inclusive. This field gives an upper bound for the
- control. See enum :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how
- the maximum value is to be used for each possible control type.
- Note that this a signed 64-bit value.
-
- - .. row 6
-
- - __u64
-
- - ``step``
-
- - This field gives a step size for the control. See enum
- :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how the step value is
- to be used for each possible control type. Note that this an
- unsigned 64-bit value.
-
- Generally drivers should not scale hardware control values. It may
- be necessary for example when the ``name`` or ``id`` imply a
- particular unit and the hardware actually accepts only multiples
- of said unit. If so, drivers must take care values are properly
- rounded when scaling, such that errors will not accumulate on
- repeated read-write cycles.
-
- This field gives the smallest change of an integer control
- actually affecting hardware. Often the information is needed when
- the user can change controls by keyboard or GUI buttons, rather
- than a slider. When for example a hardware register accepts values
- 0-511 and the driver reports 0-65535, step should be 128.
-
- - .. row 7
-
- - __s64
-
- - ``default_value``
-
- - The default value of a ``V4L2_CTRL_TYPE_INTEGER``, ``_INTEGER64``,
- ``_BOOLEAN``, ``_BITMASK``, ``_MENU``, ``_INTEGER_MENU``, ``_U8``
- or ``_U16`` control. Not valid for other types of controls. Note
- that drivers reset controls to their default value only when the
- driver is first loaded, never afterwards.
-
- - .. row 8
-
- - __u32
-
- - ``flags``
-
- - Control flags, see :ref:`control-flags`.
-
- - .. row 9
-
- - __u32
-
- - ``elem_size``
-
- - The size in bytes of a single element of the array. Given a char
- pointer ``p`` to a 3-dimensional array you can find the position
- of cell ``(z, y, x)`` as follows:
- ``p + ((z * dims[1] + y) * dims[0] + x) * elem_size``.
- ``elem_size`` is always valid, also when the control isn't an
- array. For string controls ``elem_size`` is equal to
- ``maximum + 1``.
-
- - .. row 10
-
- - __u32
-
- - ``elems``
-
- - The number of elements in the N-dimensional array. If this control
- is not an array, then ``elems`` is 1. The ``elems`` field can
- never be 0.
-
- - .. row 11
-
- - __u32
-
- - ``nr_of_dims``
-
- - The number of dimension in the N-dimensional array. If this
- control is not an array, then this field is 0.
-
- - .. row 12
-
- - __u32
-
- - ``dims[V4L2_CTRL_MAX_DIMS]``
-
- - The size of each dimension. The first ``nr_of_dims`` elements of
- this array must be non-zero, all remaining elements must be zero.
-
- - .. row 13
-
- - __u32
-
- - ``reserved``\ [32]
-
- - Reserved for future extensions. Applications and drivers must set
- the array to zero.
-
-
-
-.. _v4l2-querymenu:
-
-.. flat-table:: struct v4l2_querymenu
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2 1
-
-
- - .. row 1
-
- - __u32
-
- -
- - ``id``
-
- - Identifies the control, set by the application from the respective
- struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``id``.
-
- - .. row 2
-
- - __u32
-
- -
- - ``index``
-
- - Index of the menu item, starting at zero, set by the application.
-
- - .. row 3
-
- - union
-
- -
- -
- -
-
- - .. row 4
-
- -
- - __u8
-
- - ``name``\ [32]
-
- - Name of the menu item, a NUL-terminated ASCII string. This
- information is intended for the user. This field is valid for
- ``V4L2_CTRL_FLAG_MENU`` type controls.
-
- - .. row 5
-
- -
- - __s64
-
- - ``value``
-
- - Value of the integer menu item. This field is valid for
- ``V4L2_CTRL_FLAG_INTEGER_MENU`` type controls.
-
- - .. row 6
-
- - __u32
-
- -
- - ``reserved``
-
- - Reserved for future extensions. Drivers must set the array to
- zero.
-
-
-
-.. _v4l2-ctrl-type:
-
-.. flat-table:: enum v4l2_ctrl_type
- :header-rows: 1
- :stub-columns: 0
- :widths: 30 5 5 5 55
-
-
- - .. row 1
-
- - Type
-
- - ``minimum``
-
- - ``step``
-
- - ``maximum``
-
- - Description
-
- - .. row 2
-
- - ``V4L2_CTRL_TYPE_INTEGER``
-
- - any
-
- - any
-
- - any
-
- - An integer-valued control ranging from minimum to maximum
- inclusive. The step value indicates the increment between values.
-
- - .. row 3
-
- - ``V4L2_CTRL_TYPE_BOOLEAN``
-
- - 0
-
- - 1
-
- - 1
-
- - A boolean-valued control. Zero corresponds to "disabled", and one
- means "enabled".
-
- - .. row 4
-
- - ``V4L2_CTRL_TYPE_MENU``
-
- - ≥ 0
-
- - 1
-
- - N-1
-
- - The control has a menu of N choices. The names of the menu items
- can be enumerated with the ``VIDIOC_QUERYMENU`` ioctl.
-
- - .. row 5
-
- - ``V4L2_CTRL_TYPE_INTEGER_MENU``
-
- - ≥ 0
-
- - 1
-
- - N-1
-
- - The control has a menu of N choices. The values of the menu items
- can be enumerated with the ``VIDIOC_QUERYMENU`` ioctl. This is
- similar to ``V4L2_CTRL_TYPE_MENU`` except that instead of strings,
- the menu items are signed 64-bit integers.
-
- - .. row 6
-
- - ``V4L2_CTRL_TYPE_BITMASK``
-
- - 0
-
- - n/a
-
- - any
-
- - A bitmask field. The maximum value is the set of bits that can be
- used, all other bits are to be 0. The maximum value is interpreted
- as a __u32, allowing the use of bit 31 in the bitmask.
-
- - .. row 7
-
- - ``V4L2_CTRL_TYPE_BUTTON``
-
- - 0
-
- - 0
-
- - 0
-
- - A control which performs an action when set. Drivers must ignore
- the value passed with ``VIDIOC_S_CTRL`` and return an ``EINVAL`` error
- code on a ``VIDIOC_G_CTRL`` attempt.
-
- - .. row 8
-
- - ``V4L2_CTRL_TYPE_INTEGER64``
-
- - any
-
- - any
-
- - any
-
- - A 64-bit integer valued control. Minimum, maximum and step size
- cannot be queried using ``VIDIOC_QUERYCTRL``. Only
- ``VIDIOC_QUERY_EXT_CTRL`` can retrieve the 64-bit min/max/step
- values, they should be interpreted as n/a when using
- ``VIDIOC_QUERYCTRL``.
-
- - .. row 9
-
- - ``V4L2_CTRL_TYPE_STRING``
-
- - ≥ 0
-
- - ≥ 1
-
- - ≥ 0
-
- - The minimum and maximum string lengths. The step size means that
- the string must be (minimum + N * step) characters long for N ≥ 0.
- These lengths do not include the terminating zero, so in order to
- pass a string of length 8 to
- :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` you need to
- set the ``size`` field of struct
- :ref:`v4l2_ext_control <v4l2-ext-control>` to 9. For
- :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` you can set
- the ``size`` field to ``maximum`` + 1. Which character encoding is
- used will depend on the string control itself and should be part
- of the control documentation.
-
- - .. row 10
-
- - ``V4L2_CTRL_TYPE_CTRL_CLASS``
-
- - n/a
-
- - n/a
-
- - n/a
-
- - This is not a control. When ``VIDIOC_QUERYCTRL`` is called with a
- control ID equal to a control class code (see :ref:`ctrl-class`)
- + 1, the ioctl returns the name of the control class and this
- control type. Older drivers which do not support this feature
- return an ``EINVAL`` error code.
-
- - .. row 11
-
- - ``V4L2_CTRL_TYPE_U8``
-
- - any
-
- - any
-
- - any
-
- - An unsigned 8-bit valued control ranging from minimum to maximum
- inclusive. The step value indicates the increment between values.
-
- - .. row 12
-
- - ``V4L2_CTRL_TYPE_U16``
-
- - any
-
- - any
-
- - any
-
- - An unsigned 16-bit valued control ranging from minimum to maximum
- inclusive. The step value indicates the increment between values.
-
- - .. row 13
-
- - ``V4L2_CTRL_TYPE_U32``
-
- - any
-
- - any
-
- - any
-
- - An unsigned 32-bit valued control ranging from minimum to maximum
- inclusive. The step value indicates the increment between values.
-
-
-
-.. _control-flags:
-
-.. flat-table:: Control Flags
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - ``V4L2_CTRL_FLAG_DISABLED``
-
- - 0x0001
-
- - This control is permanently disabled and should be ignored by the
- application. Any attempt to change the control will result in an
- ``EINVAL`` error code.
-
- - .. row 2
-
- - ``V4L2_CTRL_FLAG_GRABBED``
-
- - 0x0002
-
- - This control is temporarily unchangeable, for example because
- another application took over control of the respective resource.
- Such controls may be displayed specially in a user interface.
- Attempts to change the control may result in an ``EBUSY`` error code.
-
- - .. row 3
-
- - ``V4L2_CTRL_FLAG_READ_ONLY``
-
- - 0x0004
-
- - This control is permanently readable only. Any attempt to change
- the control will result in an ``EINVAL`` error code.
-
- - .. row 4
-
- - ``V4L2_CTRL_FLAG_UPDATE``
-
- - 0x0008
-
- - A hint that changing this control may affect the value of other
- controls within the same control class. Applications should update
- their user interface accordingly.
-
- - .. row 5
-
- - ``V4L2_CTRL_FLAG_INACTIVE``
-
- - 0x0010
-
- - This control is not applicable to the current configuration and
- should be displayed accordingly in a user interface. For example
- the flag may be set on a MPEG audio level 2 bitrate control when
- MPEG audio encoding level 1 was selected with another control.
-
- - .. row 6
-
- - ``V4L2_CTRL_FLAG_SLIDER``
-
- - 0x0020
-
- - A hint that this control is best represented as a slider-like
- element in a user interface.
-
- - .. row 7
-
- - ``V4L2_CTRL_FLAG_WRITE_ONLY``
-
- - 0x0040
-
- - This control is permanently writable only. Any attempt to read the
- control will result in an ``EACCES`` error code error code. This flag
- is typically present for relative controls or action controls
- where writing a value will cause the device to carry out a given
- action (e. g. motor control) but no meaningful value can be
- returned.
-
- - .. row 8
-
- - ``V4L2_CTRL_FLAG_VOLATILE``
-
- - 0x0080
-
- - This control is volatile, which means that the value of the
- control changes continuously. A typical example would be the
- current gain value if the device is in auto-gain mode. In such a
- case the hardware calculates the gain value based on the lighting
- conditions which can change over time. Note that setting a new
- value for a volatile control will have no effect and no
- ``V4L2_EVENT_CTRL_CH_VALUE`` will be sent, unless the
- ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE`` flag (see below) is also set.
- Otherwise the new value will just be ignored.
-
- - .. row 9
-
- - ``V4L2_CTRL_FLAG_HAS_PAYLOAD``
-
- - 0x0100
-
- - This control has a pointer type, so its value has to be accessed
- using one of the pointer fields of struct
- :ref:`v4l2_ext_control <v4l2-ext-control>`. This flag is set
- for controls that are an array, string, or have a compound type.
- In all cases you have to set a pointer to memory containing the
- payload of the control.
-
- - .. row 10
-
- - ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE``
-
- - 0x0200
-
- - The value provided to the control will be propagated to the driver
- even if it remains constant. This is required when the control
- represents an action on the hardware. For example: clearing an
- error flag or triggering the flash. All the controls of the type
- ``V4L2_CTRL_TYPE_BUTTON`` have this flag set.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EINVAL
- The struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``id`` is
- invalid. The struct :ref:`v4l2_querymenu <v4l2-querymenu>` ``id``
- is invalid or ``index`` is out of range (less than ``minimum`` or
- greater than ``maximum``) or this particular menu item is not
- supported by the driver.
-
-EACCES
- An attempt was made to read a write-only control.
-
-.. [1]
- ``V4L2_CTRL_FLAG_DISABLED`` was intended for two purposes: Drivers
- can skip predefined controls not supported by the hardware (although
- returning ``EINVAL`` would do as well), or disable predefined and private
- controls after hardware detection without the trouble of reordering
- control arrays and indices (``EINVAL`` cannot be used to skip private
- controls because it would prematurely end the enumeration).
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_QUERYSTD:
-
-*********************
-ioctl VIDIOC_QUERYSTD
-*********************
-
-Name
-====
-
-VIDIOC_QUERYSTD - Sense the video standard received by the current input
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, v4l2_std_id *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_QUERYSTD
-
-``argp``
-
-
-Description
-===========
-
-The hardware may be able to detect the current video standard
-automatically. To do so, applications call :ref:`VIDIOC_QUERYSTD` with a
-pointer to a :ref:`v4l2_std_id <v4l2-std-id>` type. The driver
-stores here a set of candidates, this can be a single flag or a set of
-supported standards if for example the hardware can only distinguish
-between 50 and 60 Hz systems. If no signal was detected, then the driver
-will return V4L2_STD_UNKNOWN. When detection is not possible or fails,
-the set must contain all standards supported by the current video input
-or output.
-
-Please note that drivers shall *not* switch the video standard
-automatically if a new video standard is detected. Instead, drivers
-should send the ``V4L2_EVENT_SOURCE_CHANGE`` event (if they support
-this) and expect that userspace will take action by calling
-:ref:`VIDIOC_QUERYSTD`. The reason is that a new video standard can mean
-different buffer sizes as well, and you cannot change buffer sizes on
-the fly. In general, applications that receive the Source Change event
-will have to call :ref:`VIDIOC_QUERYSTD`, and if the detected video
-standard is valid they will have to stop streaming, set the new
-standard, allocate new buffers and start streaming again.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-ENODATA
- Standard video timings are not supported for this input or output.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_REQBUFS:
-
-********************
-ioctl VIDIOC_REQBUFS
-********************
-
-Name
-====
-
-VIDIOC_REQBUFS - Initiate Memory Mapping or User Pointer I/O
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_requestbuffers *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_REQBUFS
-
-``argp``
-
-
-Description
-===========
-
-This ioctl is used to initiate :ref:`memory mapped <mmap>`,
-:ref:`user pointer <userp>` or :ref:`DMABUF <dmabuf>` based I/O.
-Memory mapped buffers are located in device memory and must be allocated
-with this ioctl before they can be mapped into the application's address
-space. User buffers are allocated by applications themselves, and this
-ioctl is merely used to switch the driver into user pointer I/O mode and
-to setup some internal structures. Similarly, DMABUF buffers are
-allocated by applications through a device driver, and this ioctl only
-configures the driver into DMABUF I/O mode without performing any direct
-allocation.
-
-To allocate device buffers applications initialize all fields of the
-:ref:`struct v4l2_requestbuffers <v4l2-requestbuffers>` structure. They set the ``type``
-field to the respective stream or buffer type, the ``count`` field to
-the desired number of buffers, ``memory`` must be set to the requested
-I/O method and the ``reserved`` array must be zeroed. When the ioctl is
-called with a pointer to this structure the driver will attempt to
-allocate the requested number of buffers and it stores the actual number
-allocated in the ``count`` field. It can be smaller than the number
-requested, even zero, when the driver runs out of free memory. A larger
-number is also possible when the driver requires more buffers to
-function correctly. For example video output requires at least two
-buffers, one displayed and one filled by the application.
-
-When the I/O method is not supported the ioctl returns an ``EINVAL`` error
-code.
-
-Applications can call :ref:`VIDIOC_REQBUFS` again to change the number of
-buffers, however this cannot succeed when any buffers are still mapped.
-A ``count`` value of zero frees all buffers, after aborting or finishing
-any DMA in progress, an implicit
-:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`.
-
-
-.. _v4l2-requestbuffers:
-
-.. flat-table:: struct v4l2_requestbuffers
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``count``
-
- - The number of buffers requested or granted.
-
- - .. row 2
-
- - __u32
-
- - ``type``
-
- - Type of the stream or buffers, this is the same as the struct
- :ref:`v4l2_format <v4l2-format>` ``type`` field. See
- :ref:`v4l2-buf-type` for valid values.
-
- - .. row 3
-
- - __u32
-
- - ``memory``
-
- - Applications set this field to ``V4L2_MEMORY_MMAP``,
- ``V4L2_MEMORY_DMABUF`` or ``V4L2_MEMORY_USERPTR``. See
- :ref:`v4l2-memory`.
-
- - .. row 4
-
- - __u32
-
- - ``reserved``\ [2]
-
- - A place holder for future extensions. Drivers and applications
- must set the array to zero.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EINVAL
- The buffer type (``type`` field) or the requested I/O method
- (``memory``) is not supported.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_S_HW_FREQ_SEEK:
-
-***************************
-ioctl VIDIOC_S_HW_FREQ_SEEK
-***************************
-
-Name
-====
-
-VIDIOC_S_HW_FREQ_SEEK - Perform a hardware frequency seek
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_hw_freq_seek *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_S_HW_FREQ_SEEK
-
-``argp``
-
-
-Description
-===========
-
-Start a hardware frequency seek from the current frequency. To do this
-applications initialize the ``tuner``, ``type``, ``seek_upward``,
-``wrap_around``, ``spacing``, ``rangelow`` and ``rangehigh`` fields, and
-zero out the ``reserved`` array of a struct
-:ref:`v4l2_hw_freq_seek <v4l2-hw-freq-seek>` and call the
-``VIDIOC_S_HW_FREQ_SEEK`` ioctl with a pointer to this structure.
-
-The ``rangelow`` and ``rangehigh`` fields can be set to a non-zero value
-to tell the driver to search a specific band. If the struct
-:ref:`v4l2_tuner <v4l2-tuner>` ``capability`` field has the
-``V4L2_TUNER_CAP_HWSEEK_PROG_LIM`` flag set, these values must fall
-within one of the bands returned by
-:ref:`VIDIOC_ENUM_FREQ_BANDS`. If the
-``V4L2_TUNER_CAP_HWSEEK_PROG_LIM`` flag is not set, then these values
-must exactly match those of one of the bands returned by
-:ref:`VIDIOC_ENUM_FREQ_BANDS`. If the
-current frequency of the tuner does not fall within the selected band it
-will be clamped to fit in the band before the seek is started.
-
-If an error is returned, then the original frequency will be restored.
-
-This ioctl is supported if the ``V4L2_CAP_HW_FREQ_SEEK`` capability is
-set.
-
-If this ioctl is called from a non-blocking filehandle, then ``EAGAIN``
-error code is returned and no seek takes place.
-
-
-.. _v4l2-hw-freq-seek:
-
-.. flat-table:: struct v4l2_hw_freq_seek
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``tuner``
-
- - The tuner index number. This is the same value as in the struct
- :ref:`v4l2_input <v4l2-input>` ``tuner`` field and the struct
- :ref:`v4l2_tuner <v4l2-tuner>` ``index`` field.
-
- - .. row 2
-
- - __u32
-
- - ``type``
-
- - The tuner type. This is the same value as in the struct
- :ref:`v4l2_tuner <v4l2-tuner>` ``type`` field. See
- :ref:`v4l2-tuner-type`
-
- - .. row 3
-
- - __u32
-
- - ``seek_upward``
-
- - If non-zero, seek upward from the current frequency, else seek
- downward.
-
- - .. row 4
-
- - __u32
-
- - ``wrap_around``
-
- - If non-zero, wrap around when at the end of the frequency range,
- else stop seeking. The struct :ref:`v4l2_tuner <v4l2-tuner>`
- ``capability`` field will tell you what the hardware supports.
-
- - .. row 5
-
- - __u32
-
- - ``spacing``
-
- - If non-zero, defines the hardware seek resolution in Hz. The
- driver selects the nearest value that is supported by the device.
- If spacing is zero a reasonable default value is used.
-
- - .. row 6
-
- - __u32
-
- - ``rangelow``
-
- - If non-zero, the lowest tunable frequency of the band to search in
- units of 62.5 kHz, or if the struct
- :ref:`v4l2_tuner <v4l2-tuner>` ``capability`` field has the
- ``V4L2_TUNER_CAP_LOW`` flag set, in units of 62.5 Hz or if the
- struct :ref:`v4l2_tuner <v4l2-tuner>` ``capability`` field has
- the ``V4L2_TUNER_CAP_1HZ`` flag set, in units of 1 Hz. If
- ``rangelow`` is zero a reasonable default value is used.
-
- - .. row 7
-
- - __u32
-
- - ``rangehigh``
-
- - If non-zero, the highest tunable frequency of the band to search
- in units of 62.5 kHz, or if the struct
- :ref:`v4l2_tuner <v4l2-tuner>` ``capability`` field has the
- ``V4L2_TUNER_CAP_LOW`` flag set, in units of 62.5 Hz or if the
- struct :ref:`v4l2_tuner <v4l2-tuner>` ``capability`` field has
- the ``V4L2_TUNER_CAP_1HZ`` flag set, in units of 1 Hz. If
- ``rangehigh`` is zero a reasonable default value is used.
-
- - .. row 8
-
- - __u32
-
- - ``reserved``\ [5]
-
- - Reserved for future extensions. Applications must set the array to
- zero.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EINVAL
- The ``tuner`` index is out of bounds, the ``wrap_around`` value is
- not supported or one of the values in the ``type``, ``rangelow`` or
- ``rangehigh`` fields is wrong.
-
-EAGAIN
- Attempted to call ``VIDIOC_S_HW_FREQ_SEEK`` with the filehandle in
- non-blocking mode.
-
-ENODATA
- The hardware seek found no channels.
-
-EBUSY
- Another hardware seek is already in progress.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_STREAMON:
-
-***************************************
-ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF
-***************************************
-
-Name
-====
-
-VIDIOC_STREAMON - VIDIOC_STREAMOFF - Start or stop streaming I/O
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, const int *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_STREAMON, VIDIOC_STREAMOFF
-
-``argp``
-
-
-Description
-===========
-
-The ``VIDIOC_STREAMON`` and ``VIDIOC_STREAMOFF`` ioctl start and stop
-the capture or output process during streaming
-(:ref:`memory mapping <mmap>`, :ref:`user pointer <userp>` or
-:ref:`DMABUF <dmabuf>`) I/O.
-
-Capture hardware is disabled and no input buffers are filled (if there
-are any empty buffers in the incoming queue) until ``VIDIOC_STREAMON``
-has been called. Output hardware is disabled and no video signal is
-produced until ``VIDIOC_STREAMON`` has been called. The ioctl will
-succeed when at least one output buffer is in the incoming queue.
-
-Memory-to-memory devices will not start until ``VIDIOC_STREAMON`` has
-been called for both the capture and output stream types.
-
-If ``VIDIOC_STREAMON`` fails then any already queued buffers will remain
-queued.
-
-The ``VIDIOC_STREAMOFF`` ioctl, apart of aborting or finishing any DMA
-in progress, unlocks any user pointer buffers locked in physical memory,
-and it removes all buffers from the incoming and outgoing queues. That
-means all images captured but not dequeued yet will be lost, likewise
-all images enqueued for output but not transmitted yet. I/O returns to
-the same state as after calling
-:ref:`VIDIOC_REQBUFS` and can be restarted
-accordingly.
-
-If buffers have been queued with :ref:`VIDIOC_QBUF` and
-``VIDIOC_STREAMOFF`` is called without ever having called
-``VIDIOC_STREAMON``, then those queued buffers will also be removed from
-the incoming queue and all are returned to the same state as after
-calling :ref:`VIDIOC_REQBUFS` and can be restarted
-accordingly.
-
-Both ioctls take a pointer to an integer, the desired buffer or stream
-type. This is the same as struct
-:ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``type``.
-
-If ``VIDIOC_STREAMON`` is called when streaming is already in progress,
-or if ``VIDIOC_STREAMOFF`` is called when streaming is already stopped,
-then 0 is returned. Nothing happens in the case of ``VIDIOC_STREAMON``,
-but ``VIDIOC_STREAMOFF`` will return queued buffers to their starting
-state as mentioned above.
-
-Note that applications can be preempted for unknown periods right before
-or after the ``VIDIOC_STREAMON`` or ``VIDIOC_STREAMOFF`` calls, there is
-no notion of starting or stopping "now". Buffer timestamps can be used
-to synchronize with other events.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EINVAL
- The buffer ``type`` is not supported, or no buffers have been
- allocated (memory mapping) or enqueued (output) yet.
-
-EPIPE
- The driver implements
- :ref:`pad-level format configuration <pad-level-formats>` and the
- pipeline configuration is invalid.
-
-ENOLINK
- The driver implements Media Controller interface and the pipeline
- link configuration is invalid.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL:
-
-***************************************
-ioctl VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL
-***************************************
-
-Name
-====
-
-VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL - Enumerate frame intervals
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_subdev_frame_interval_enum * argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL
-
-``argp``
-
-
-Description
-===========
-
-This ioctl lets applications enumerate available frame intervals on a
-given sub-device pad. Frame intervals only makes sense for sub-devices
-that can control the frame period on their own. This includes, for
-instance, image sensors and TV tuners.
-
-For the common use case of image sensors, the frame intervals available
-on the sub-device output pad depend on the frame format and size on the
-same pad. Applications must thus specify the desired format and size
-when enumerating frame intervals.
-
-To enumerate frame intervals applications initialize the ``index``,
-``pad``, ``which``, ``code``, ``width`` and ``height`` fields of struct
-:ref:`v4l2_subdev_frame_interval_enum <v4l2-subdev-frame-interval-enum>`
-and call the :ref:`VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL` ioctl with a pointer
-to this structure. Drivers fill the rest of the structure or return an
-EINVAL error code if one of the input fields is invalid. All frame
-intervals are enumerable by beginning at index zero and incrementing by
-one until ``EINVAL`` is returned.
-
-Available frame intervals may depend on the current 'try' formats at
-other pads of the sub-device, as well as on the current active links.
-See :ref:`VIDIOC_SUBDEV_G_FMT` for more
-information about the try formats.
-
-Sub-devices that support the frame interval enumeration ioctl should
-implemented it on a single pad only. Its behaviour when supported on
-multiple pads of the same sub-device is not defined.
-
-
-.. _v4l2-subdev-frame-interval-enum:
-
-.. flat-table:: struct v4l2_subdev_frame_interval_enum
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``index``
-
- - Number of the format in the enumeration, set by the application.
-
- - .. row 2
-
- - __u32
-
- - ``pad``
-
- - Pad number as reported by the media controller API.
-
- - .. row 3
-
- - __u32
-
- - ``code``
-
- - The media bus format code, as defined in
- :ref:`v4l2-mbus-format`.
-
- - .. row 4
-
- - __u32
-
- - ``width``
-
- - Frame width, in pixels.
-
- - .. row 5
-
- - __u32
-
- - ``height``
-
- - Frame height, in pixels.
-
- - .. row 6
-
- - struct :ref:`v4l2_fract <v4l2-fract>`
-
- - ``interval``
-
- - Period, in seconds, between consecutive video frames.
-
- - .. row 7
-
- - __u32
-
- - ``which``
-
- - Frame intervals to be enumerated, from enum
- :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
-
- - .. row 8
-
- - __u32
-
- - ``reserved``\ [8]
-
- - Reserved for future extensions. Applications and drivers must set
- the array to zero.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EINVAL
- The struct
- :ref:`v4l2_subdev_frame_interval_enum <v4l2-subdev-frame-interval-enum>`
- ``pad`` references a non-existing pad, one of the ``code``,
- ``width`` or ``height`` fields are invalid for the given pad or the
- ``index`` field is out of bounds.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_SUBDEV_ENUM_FRAME_SIZE:
-
-***********************************
-ioctl VIDIOC_SUBDEV_ENUM_FRAME_SIZE
-***********************************
-
-Name
-====
-
-VIDIOC_SUBDEV_ENUM_FRAME_SIZE - Enumerate media bus frame sizes
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_subdev_frame_size_enum * argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_SUBDEV_ENUM_FRAME_SIZE
-
-``argp``
-
-
-Description
-===========
-
-This ioctl allows applications to enumerate all frame sizes supported by
-a sub-device on the given pad for the given media bus format. Supported
-formats can be retrieved with the
-:ref:`VIDIOC_SUBDEV_ENUM_MBUS_CODE`
-ioctl.
-
-To enumerate frame sizes applications initialize the ``pad``, ``which``
-, ``code`` and ``index`` fields of the struct
-:ref:`v4l2_subdev_mbus_code_enum <v4l2-subdev-mbus-code-enum>` and
-call the :ref:`VIDIOC_SUBDEV_ENUM_FRAME_SIZE` ioctl with a pointer to the
-structure. Drivers fill the minimum and maximum frame sizes or return an
-EINVAL error code if one of the input parameters is invalid.
-
-Sub-devices that only support discrete frame sizes (such as most
-sensors) will return one or more frame sizes with identical minimum and
-maximum values.
-
-Not all possible sizes in given [minimum, maximum] ranges need to be
-supported. For instance, a scaler that uses a fixed-point scaling ratio
-might not be able to produce every frame size between the minimum and
-maximum values. Applications must use the
-:ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` ioctl to try the
-sub-device for an exact supported frame size.
-
-Available frame sizes may depend on the current 'try' formats at other
-pads of the sub-device, as well as on the current active links and the
-current values of V4L2 controls. See
-:ref:`VIDIOC_SUBDEV_G_FMT` for more
-information about try formats.
-
-
-.. _v4l2-subdev-frame-size-enum:
-
-.. flat-table:: struct v4l2_subdev_frame_size_enum
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``index``
-
- - Number of the format in the enumeration, set by the application.
-
- - .. row 2
-
- - __u32
-
- - ``pad``
-
- - Pad number as reported by the media controller API.
-
- - .. row 3
-
- - __u32
-
- - ``code``
-
- - The media bus format code, as defined in
- :ref:`v4l2-mbus-format`.
-
- - .. row 4
-
- - __u32
-
- - ``min_width``
-
- - Minimum frame width, in pixels.
-
- - .. row 5
-
- - __u32
-
- - ``max_width``
-
- - Maximum frame width, in pixels.
-
- - .. row 6
-
- - __u32
-
- - ``min_height``
-
- - Minimum frame height, in pixels.
-
- - .. row 7
-
- - __u32
-
- - ``max_height``
-
- - Maximum frame height, in pixels.
-
- - .. row 8
-
- - __u32
-
- - ``which``
-
- - Frame sizes to be enumerated, from enum
- :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
-
- - .. row 9
-
- - __u32
-
- - ``reserved``\ [8]
-
- - Reserved for future extensions. Applications and drivers must set
- the array to zero.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EINVAL
- The struct
- :ref:`v4l2_subdev_frame_size_enum <v4l2-subdev-frame-size-enum>`
- ``pad`` references a non-existing pad, the ``code`` is invalid for
- the given pad or the ``index`` field is out of bounds.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_SUBDEV_ENUM_MBUS_CODE:
-
-**********************************
-ioctl VIDIOC_SUBDEV_ENUM_MBUS_CODE
-**********************************
-
-Name
-====
-
-VIDIOC_SUBDEV_ENUM_MBUS_CODE - Enumerate media bus formats
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_subdev_mbus_code_enum * argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_SUBDEV_ENUM_MBUS_CODE
-
-``argp``
-
-
-Description
-===========
-
-To enumerate media bus formats available at a given sub-device pad
-applications initialize the ``pad``, ``which`` and ``index`` fields of
-struct
-:ref:`v4l2_subdev_mbus_code_enum <v4l2-subdev-mbus-code-enum>` and
-call the :ref:`VIDIOC_SUBDEV_ENUM_MBUS_CODE` ioctl with a pointer to this
-structure. Drivers fill the rest of the structure or return an ``EINVAL``
-error code if either the ``pad`` or ``index`` are invalid. All media bus
-formats are enumerable by beginning at index zero and incrementing by
-one until ``EINVAL`` is returned.
-
-Available media bus formats may depend on the current 'try' formats at
-other pads of the sub-device, as well as on the current active links.
-See :ref:`VIDIOC_SUBDEV_G_FMT` for more
-information about the try formats.
-
-
-.. _v4l2-subdev-mbus-code-enum:
-
-.. flat-table:: struct v4l2_subdev_mbus_code_enum
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``pad``
-
- - Pad number as reported by the media controller API.
-
- - .. row 2
-
- - __u32
-
- - ``index``
-
- - Number of the format in the enumeration, set by the application.
-
- - .. row 3
-
- - __u32
-
- - ``code``
-
- - The media bus format code, as defined in
- :ref:`v4l2-mbus-format`.
-
- - .. row 4
-
- - __u32
-
- - ``which``
-
- - Media bus format codes to be enumerated, from enum
- :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
-
- - .. row 5
-
- - __u32
-
- - ``reserved``\ [8]
-
- - Reserved for future extensions. Applications and drivers must set
- the array to zero.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EINVAL
- The struct
- :ref:`v4l2_subdev_mbus_code_enum <v4l2-subdev-mbus-code-enum>`
- ``pad`` references a non-existing pad, or the ``index`` field is out
- of bounds.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_SUBDEV_G_CROP:
-
-************************************************
-ioctl VIDIOC_SUBDEV_G_CROP, VIDIOC_SUBDEV_S_CROP
-************************************************
-
-Name
-====
-
-VIDIOC_SUBDEV_G_CROP - VIDIOC_SUBDEV_S_CROP - Get or set the crop rectangle on a subdev pad
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_subdev_crop *argp )
-
-.. cpp:function:: int ioctl( int fd, int request, const struct v4l2_subdev_crop *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_SUBDEV_G_CROP, VIDIOC_SUBDEV_S_CROP
-
-``argp``
-
-
-Description
-===========
-
- **Note**
-
- This is an :ref:`obsolete` interface and may be removed
- in the future. It is superseded by
- :ref:`the selection API <VIDIOC_SUBDEV_G_SELECTION>`.
-
-To retrieve the current crop rectangle applications set the ``pad``
-field of a struct :ref:`v4l2_subdev_crop <v4l2-subdev-crop>` to the
-desired pad number as reported by the media API and the ``which`` field
-to ``V4L2_SUBDEV_FORMAT_ACTIVE``. They then call the
-``VIDIOC_SUBDEV_G_CROP`` ioctl with a pointer to this structure. The
-driver fills the members of the ``rect`` field or returns ``EINVAL`` error
-code if the input arguments are invalid, or if cropping is not supported
-on the given pad.
-
-To change the current crop rectangle applications set both the ``pad``
-and ``which`` fields and all members of the ``rect`` field. They then
-call the ``VIDIOC_SUBDEV_S_CROP`` ioctl with a pointer to this
-structure. The driver verifies the requested crop rectangle, adjusts it
-based on the hardware capabilities and configures the device. Upon
-return the struct :ref:`v4l2_subdev_crop <v4l2-subdev-crop>`
-contains the current format as would be returned by a
-``VIDIOC_SUBDEV_G_CROP`` call.
-
-Applications can query the device capabilities by setting the ``which``
-to ``V4L2_SUBDEV_FORMAT_TRY``. When set, 'try' crop rectangles are not
-applied to the device by the driver, but are mangled exactly as active
-crop rectangles and stored in the sub-device file handle. Two
-applications querying the same sub-device would thus not interact with
-each other.
-
-Drivers must not return an error solely because the requested crop
-rectangle doesn't match the device capabilities. They must instead
-modify the rectangle to match what the hardware can provide. The
-modified format should be as close as possible to the original request.
-
-
-.. _v4l2-subdev-crop:
-
-.. flat-table:: struct v4l2_subdev_crop
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``pad``
-
- - Pad number as reported by the media framework.
-
- - .. row 2
-
- - __u32
-
- - ``which``
-
- - Crop rectangle to get or set, from enum
- :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
-
- - .. row 3
-
- - struct :ref:`v4l2_rect <v4l2-rect>`
-
- - ``rect``
-
- - Crop rectangle boundaries, in pixels.
-
- - .. row 4
-
- - __u32
-
- - ``reserved``\ [8]
-
- - Reserved for future extensions. Applications and drivers must set
- the array to zero.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EBUSY
- The crop rectangle can't be changed because the pad is currently
- busy. This can be caused, for instance, by an active video stream on
- the pad. The ioctl must not be retried without performing another
- action to fix the problem first. Only returned by
- ``VIDIOC_SUBDEV_S_CROP``
-
-EINVAL
- The struct :ref:`v4l2_subdev_crop <v4l2-subdev-crop>` ``pad``
- references a non-existing pad, the ``which`` field references a
- non-existing format, or cropping is not supported on the given
- subdev pad.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_SUBDEV_G_FMT:
-
-**********************************************
-ioctl VIDIOC_SUBDEV_G_FMT, VIDIOC_SUBDEV_S_FMT
-**********************************************
-
-Name
-====
-
-VIDIOC_SUBDEV_G_FMT - VIDIOC_SUBDEV_S_FMT - Get or set the data format on a subdev pad
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_subdev_format *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_SUBDEV_G_FMT, VIDIOC_SUBDEV_S_FMT
-
-``argp``
-
-
-Description
-===========
-
-These ioctls are used to negotiate the frame format at specific subdev
-pads in the image pipeline.
-
-To retrieve the current format applications set the ``pad`` field of a
-struct :ref:`v4l2_subdev_format <v4l2-subdev-format>` to the desired
-pad number as reported by the media API and the ``which`` field to
-``V4L2_SUBDEV_FORMAT_ACTIVE``. When they call the
-``VIDIOC_SUBDEV_G_FMT`` ioctl with a pointer to this structure the
-driver fills the members of the ``format`` field.
-
-To change the current format applications set both the ``pad`` and
-``which`` fields and all members of the ``format`` field. When they call
-the ``VIDIOC_SUBDEV_S_FMT`` ioctl with a pointer to this structure the
-driver verifies the requested format, adjusts it based on the hardware
-capabilities and configures the device. Upon return the struct
-:ref:`v4l2_subdev_format <v4l2-subdev-format>` contains the current
-format as would be returned by a ``VIDIOC_SUBDEV_G_FMT`` call.
-
-Applications can query the device capabilities by setting the ``which``
-to ``V4L2_SUBDEV_FORMAT_TRY``. When set, 'try' formats are not applied
-to the device by the driver, but are changed exactly as active formats
-and stored in the sub-device file handle. Two applications querying the
-same sub-device would thus not interact with each other.
-
-For instance, to try a format at the output pad of a sub-device,
-applications would first set the try format at the sub-device input with
-the ``VIDIOC_SUBDEV_S_FMT`` ioctl. They would then either retrieve the
-default format at the output pad with the ``VIDIOC_SUBDEV_G_FMT`` ioctl,
-or set the desired output pad format with the ``VIDIOC_SUBDEV_S_FMT``
-ioctl and check the returned value.
-
-Try formats do not depend on active formats, but can depend on the
-current links configuration or sub-device controls value. For instance,
-a low-pass noise filter might crop pixels at the frame boundaries,
-modifying its output frame size.
-
-Drivers must not return an error solely because the requested format
-doesn't match the device capabilities. They must instead modify the
-format to match what the hardware can provide. The modified format
-should be as close as possible to the original request.
-
-
-.. _v4l2-subdev-format:
-
-.. flat-table:: struct v4l2_subdev_format
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``pad``
-
- - Pad number as reported by the media controller API.
-
- - .. row 2
-
- - __u32
-
- - ``which``
-
- - Format to modified, from enum
- :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
-
- - .. row 3
-
- - struct :ref:`v4l2_mbus_framefmt <v4l2-mbus-framefmt>`
-
- - ``format``
-
- - Definition of an image format, see :ref:`v4l2-mbus-framefmt` for
- details.
-
- - .. row 4
-
- - __u32
-
- - ``reserved``\ [8]
-
- - Reserved for future extensions. Applications and drivers must set
- the array to zero.
-
-
-
-.. _v4l2-subdev-format-whence:
-
-.. flat-table:: enum v4l2_subdev_format_whence
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - V4L2_SUBDEV_FORMAT_TRY
-
- - 0
-
- - Try formats, used for querying device capabilities.
-
- - .. row 2
-
- - V4L2_SUBDEV_FORMAT_ACTIVE
-
- - 1
-
- - Active formats, applied to the hardware.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EBUSY
- The format can't be changed because the pad is currently busy. This
- can be caused, for instance, by an active video stream on the pad.
- The ioctl must not be retried without performing another action to
- fix the problem first. Only returned by ``VIDIOC_SUBDEV_S_FMT``
-
-EINVAL
- The struct :ref:`v4l2_subdev_format <v4l2-subdev-format>`
- ``pad`` references a non-existing pad, or the ``which`` field
- references a non-existing format.
-
-
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_SUBDEV_G_FRAME_INTERVAL:
-
-********************************************************************
-ioctl VIDIOC_SUBDEV_G_FRAME_INTERVAL, VIDIOC_SUBDEV_S_FRAME_INTERVAL
-********************************************************************
-
-Name
-====
-
-VIDIOC_SUBDEV_G_FRAME_INTERVAL - VIDIOC_SUBDEV_S_FRAME_INTERVAL - Get or set the frame interval on a subdev pad
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_subdev_frame_interval *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_SUBDEV_G_FRAME_INTERVAL,
- VIDIOC_SUBDEV_S_FRAME_INTERVAL
-
-``argp``
-
-
-Description
-===========
-
-These ioctls are used to get and set the frame interval at specific
-subdev pads in the image pipeline. The frame interval only makes sense
-for sub-devices that can control the frame period on their own. This
-includes, for instance, image sensors and TV tuners. Sub-devices that
-don't support frame intervals must not implement these ioctls.
-
-To retrieve the current frame interval applications set the ``pad``
-field of a struct
-:ref:`v4l2_subdev_frame_interval <v4l2-subdev-frame-interval>` to
-the desired pad number as reported by the media controller API. When
-they call the ``VIDIOC_SUBDEV_G_FRAME_INTERVAL`` ioctl with a pointer to
-this structure the driver fills the members of the ``interval`` field.
-
-To change the current frame interval applications set both the ``pad``
-field and all members of the ``interval`` field. When they call the
-``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` ioctl with a pointer to this
-structure the driver verifies the requested interval, adjusts it based
-on the hardware capabilities and configures the device. Upon return the
-struct
-:ref:`v4l2_subdev_frame_interval <v4l2-subdev-frame-interval>`
-contains the current frame interval as would be returned by a
-``VIDIOC_SUBDEV_G_FRAME_INTERVAL`` call.
-
-Drivers must not return an error solely because the requested interval
-doesn't match the device capabilities. They must instead modify the
-interval to match what the hardware can provide. The modified interval
-should be as close as possible to the original request.
-
-Sub-devices that support the frame interval ioctls should implement them
-on a single pad only. Their behaviour when supported on multiple pads of
-the same sub-device is not defined.
-
-
-.. _v4l2-subdev-frame-interval:
-
-.. flat-table:: struct v4l2_subdev_frame_interval
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``pad``
-
- - Pad number as reported by the media controller API.
-
- - .. row 2
-
- - struct :ref:`v4l2_fract <v4l2-fract>`
-
- - ``interval``
-
- - Period, in seconds, between consecutive video frames.
-
- - .. row 3
-
- - __u32
-
- - ``reserved``\ [9]
-
- - Reserved for future extensions. Applications and drivers must set
- the array to zero.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EBUSY
- The frame interval can't be changed because the pad is currently
- busy. This can be caused, for instance, by an active video stream on
- the pad. The ioctl must not be retried without performing another
- action to fix the problem first. Only returned by
- ``VIDIOC_SUBDEV_S_FRAME_INTERVAL``
-
-EINVAL
- The struct
- :ref:`v4l2_subdev_frame_interval <v4l2-subdev-frame-interval>`
- ``pad`` references a non-existing pad, or the pad doesn't support
- frame intervals.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_SUBDEV_G_SELECTION:
-
-**********************************************************
-ioctl VIDIOC_SUBDEV_G_SELECTION, VIDIOC_SUBDEV_S_SELECTION
-**********************************************************
-
-Name
-====
-
-VIDIOC_SUBDEV_G_SELECTION - VIDIOC_SUBDEV_S_SELECTION - Get or set selection rectangles on a subdev pad
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_subdev_selection *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_SUBDEV_G_SELECTION, VIDIOC_SUBDEV_S_SELECTION
-
-``argp``
-
-
-Description
-===========
-
-The selections are used to configure various image processing
-functionality performed by the subdevs which affect the image size. This
-currently includes cropping, scaling and composition.
-
-The selection API replaces
-:ref:`the old subdev crop API <VIDIOC_SUBDEV_G_CROP>`. All the
-function of the crop API, and more, are supported by the selections API.
-
-See :ref:`subdev` for more information on how each selection target
-affects the image processing pipeline inside the subdevice.
-
-
-Types of selection targets
---------------------------
-
-There are two types of selection targets: actual and bounds. The actual
-targets are the targets which configure the hardware. The BOUNDS target
-will return a rectangle that contain all possible actual rectangles.
-
-
-Discovering supported features
-------------------------------
-
-To discover which targets are supported, the user can perform
-``VIDIOC_SUBDEV_G_SELECTION`` on them. Any unsupported target will
-return ``EINVAL``.
-
-Selection targets and flags are documented in
-:ref:`v4l2-selections-common`.
-
-
-.. _v4l2-subdev-selection:
-
-.. flat-table:: struct v4l2_subdev_selection
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``which``
-
- - Active or try selection, from enum
- :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
-
- - .. row 2
-
- - __u32
-
- - ``pad``
-
- - Pad number as reported by the media framework.
-
- - .. row 3
-
- - __u32
-
- - ``target``
-
- - Target selection rectangle. See :ref:`v4l2-selections-common`.
-
- - .. row 4
-
- - __u32
-
- - ``flags``
-
- - Flags. See :ref:`v4l2-selection-flags`.
-
- - .. row 5
-
- - struct :ref:`v4l2_rect <v4l2-rect>`
-
- - ``r``
-
- - Selection rectangle, in pixels.
-
- - .. row 6
-
- - __u32
-
- - ``reserved``\ [8]
-
- - Reserved for future extensions. Applications and drivers must set
- the array to zero.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EBUSY
- The selection rectangle can't be changed because the pad is
- currently busy. This can be caused, for instance, by an active video
- stream on the pad. The ioctl must not be retried without performing
- another action to fix the problem first. Only returned by
- ``VIDIOC_SUBDEV_S_SELECTION``
-
-EINVAL
- The struct :ref:`v4l2_subdev_selection <v4l2-subdev-selection>`
- ``pad`` references a non-existing pad, the ``which`` field
- references a non-existing format, or the selection target is not
- supported on the given subdev pad.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _VIDIOC_SUBSCRIBE_EVENT:
-
-******************************************************
-ioctl VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT
-******************************************************
-
-Name
-====
-
-VIDIOC_SUBSCRIBE_EVENT - VIDIOC_UNSUBSCRIBE_EVENT - Subscribe or unsubscribe event
-
-
-Synopsis
-========
-
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_event_subscription *argp )
-
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``request``
- VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT
-
-``argp``
-
-
-Description
-===========
-
-Subscribe or unsubscribe V4L2 event. Subscribed events are dequeued by
-using the :ref:`VIDIOC_DQEVENT` ioctl.
-
-
-.. _v4l2-event-subscription:
-
-.. flat-table:: struct v4l2_event_subscription
- :header-rows: 0
- :stub-columns: 0
- :widths: 1 1 2
-
-
- - .. row 1
-
- - __u32
-
- - ``type``
-
- - Type of the event, see :ref:`event-type`. Note that
- ``V4L2_EVENT_ALL`` can be used with VIDIOC_UNSUBSCRIBE_EVENT for
- unsubscribing all events at once.
-
- - .. row 2
-
- - __u32
-
- - ``id``
-
- - ID of the event source. If there is no ID associated with the
- event source, then set this to 0. Whether or not an event needs an
- ID depends on the event type.
-
- - .. row 3
-
- - __u32
-
- - ``flags``
-
- - Event flags, see :ref:`event-flags`.
-
- - .. row 4
-
- - __u32
-
- - ``reserved``\ [5]
-
- - Reserved for future extensions. Drivers and applications must set
- the array to zero.
-
-
-
-.. _event-flags:
-
-.. flat-table:: Event Flags
- :header-rows: 0
- :stub-columns: 0
- :widths: 3 1 4
-
-
- - .. row 1
-
- - ``V4L2_EVENT_SUB_FL_SEND_INITIAL``
-
- - 0x0001
-
- - When this event is subscribed an initial event will be sent
- containing the current status. This only makes sense for events
- that are triggered by a status change such as ``V4L2_EVENT_CTRL``.
- Other events will ignore this flag.
-
- - .. row 2
-
- - ``V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK``
-
- - 0x0002
-
- - If set, then events directly caused by an ioctl will also be sent
- to the filehandle that called that ioctl. For example, changing a
- control using :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` will cause
- a V4L2_EVENT_CTRL to be sent back to that same filehandle.
- Normally such events are suppressed to prevent feedback loops
- where an application changes a control to a one value and then
- another, and then receives an event telling it that that control
- has changed to the first value.
-
- Since it can't tell whether that event was caused by another
- application or by the :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>`
- call it is hard to decide whether to set the control to the value
- in the event, or ignore it.
-
- Think carefully when you set this flag so you won't get into
- situations like that.
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
+++ /dev/null
-.. -*- coding: utf-8; mode: rst -*-
-
-.. _yuv-formats:
-
-***********
-YUV Formats
-***********
-
-YUV is the format native to TV broadcast and composite video signals. It
-separates the brightness information (Y) from the color information (U
-and V or Cb and Cr). The color information consists of red and blue
-*color difference* signals, this way the green component can be
-reconstructed by subtracting from the brightness component. See
-:ref:`colorspaces` for conversion examples. YUV was chosen because
-early television would only transmit brightness information. To add
-color in a way compatible with existing receivers a new signal carrier
-was added to transmit the color difference signals. Secondary in the YUV
-format the U and V components usually have lower resolution than the Y
-component. This is an analog video compression technique taking
-advantage of a property of the human visual system, being more sensitive
-to brightness information.
-
-
-.. toctree::
- :maxdepth: 1
-
- pixfmt-packed-yuv
- pixfmt-grey
- pixfmt-y10
- pixfmt-y12
- pixfmt-y10b
- pixfmt-y16
- pixfmt-y16-be
- pixfmt-y8i
- pixfmt-y12i
- pixfmt-uv8
- pixfmt-yuyv
- pixfmt-uyvy
- pixfmt-yvyu
- pixfmt-vyuy
- pixfmt-y41p
- pixfmt-yuv420
- pixfmt-yuv420m
- pixfmt-yuv422m
- pixfmt-yuv444m
- pixfmt-yuv410
- pixfmt-yuv422p
- pixfmt-yuv411p
- pixfmt-nv12
- pixfmt-nv12m
- pixfmt-nv12mt
- pixfmt-nv16
- pixfmt-nv16m
- pixfmt-nv24
- pixfmt-m420
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<svg stroke-linejoin="round" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns="http://www.w3.org/2000/svg" clip-path="url(#a)" xml:space="preserve" fill-rule="evenodd" height="178.78mm" viewBox="0 0 24285.662 17877.829" width="251.99mm" version="1.2" xmlns:cc="http://creativecommons.org/ns#" xmlns:dc="http://purl.org/dc/elements/1.1/" preserveAspectRatio="xMidYMid" stroke-width="28.222"><defs><clipPath id="a" clipPathUnits="userSpaceOnUse"><rect y="0" x="0" width="28000" height="21000"/></clipPath></defs><g transform="matrix(1.004 0 0 1 -2185.6 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#fcf" d="m12231 4800c-516 0-1031 515-1031 1031v4124c0 516 515 1032 1031 1032h8538c516 0 1032-516 1032-1032v-4124c0-516-516-1031-1032-1031h-8538z"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#ffc" d="m3595 15607c-293 0-585 292-585 585v2340c0 293 292 586 585 586h3275c293 0 586-293 586-586v-2340c0-293-293-585-586-585h-3275z"/></g><g transform="translate(-2197.3 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#e6e6e6" d="m2663 2186c-461 0-922 461-922 922v11169c0 461 461 923 922 923h3692c461 0 922-462 922-923v-11169c0-461-461-922-922-922h-3692z"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.RectangleShape"><path fill="#ff8080" d="m4461 8602h-2260v-1086h4520v1086h-2260z"/><path fill="none" d="m4461 8602h-2260v-1086h4520v1086h-2260z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="8275" x="2579" class="TextPosition"><tspan fill="#000000">Audio decoder</tspan></tspan></tspan></text>
-</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.RectangleShape"><path fill="#ff8080" d="m4461 11772h-2260v-1270h4520v1270h-2260z"/><path fill="none" d="m4461 11772h-2260v-1270h4520v1270h-2260z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="11353" x="2617" class="TextPosition"><tspan fill="#000000">Video decoder</tspan></tspan></tspan></text>
-</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.RectangleShape"><path fill="#ff8080" d="m4453 10217h-2269v-1224h4537v1224h-2268z"/><path fill="none" d="m4453 10217h-2269v-1224h4537v1224h-2268z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="9821" x="2571" class="TextPosition"><tspan fill="#000000">Audio encoder</tspan></tspan></tspan></text>
-</g><g transform="translate(-2140.9 -2468.2)" class="com.sun.star.drawing.RectangleShape"><path fill="#cfc" d="m15711 12832h-3810v-1281h7620v1281h-3810z"/><path fill="none" d="m15711 12832h-3810v-1281h7620v1281h-3810z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="12407" x="12377" class="TextPosition"><tspan fill="#000000">Button Key/IR input logic</tspan></tspan></tspan></text>
-</g><g transform="translate(-2140.9 -2411.8)" class="com.sun.star.drawing.RectangleShape"><path fill="#cfe7f5" d="m14169 14572h-2268v-1412h4536v1412h-2268z"/><path fill="none" d="m14169 14572h-2268v-1412h4536v1412h-2268z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="14082" x="12882" class="TextPosition"><tspan fill="#000000">EEPROM</tspan></tspan></tspan></text>
-</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.RectangleShape"><path fill="#fc9" d="m5140 17662h-1563v-1715h3126v1715h-1563z"/><path fill="none" d="m5140 17662h-1563v-1715h3126v1715h-1563z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="17020" x="4276" class="TextPosition"><tspan fill="#000000">Sensor</tspan></tspan></tspan></text>
-</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m6719 8030 385-353v176h1167v-176l386 353-386 354v-177h-1167v177l-385-354z"/><path fill="none" d="m6719 8030 385-353v176h1167v-176l386 353-386 354v-177h-1167v177l-385-354z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m6719 9612 385-353v176h1167v-176l386 353-386 354v-177h-1167v177l-385-354z"/><path fill="none" d="m6719 9612 385-353v176h1167v-176l386 353-386 354v-177h-1167v177l-385-354z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m6721 11100 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z"/><path fill="none" d="m6721 11100 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2411.8)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m9962 13854 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z"/><path fill="none" d="m9962 13854 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2468.2)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m9962 12163 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z"/><path fill="none" d="m9962 12163 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m9962 17158 670-353v176h2028v-176l671 353-671 354v-177h-2028v177l-670-354z"/><path fill="none" d="m9962 17158 670-353v176h2028v-176l671 353-671 354v-177h-2028v177l-670-354z" stroke="#3465af"/></g><g transform="matrix(0 .83339 -1.0005 0 30268 -5276.3)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m23229 12779 1009-978 1009 978h-505v2959h505l-1009 979-1009-979h504v-2959h-504z"/><path fill="none" d="m23229 12779 1009-978 1009 978h-505v2959h505l-1009 979-1009-979h504v-2959h-504z" stroke="#3465af"/></g><g transform="translate(-9973.6 -666.6)" class="com.sun.star.drawing.TextShape"><text class="TextShape"><tspan font-size="706px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="15832" x="24341" class="TextPosition" transform="matrix(0,-1,1,0,8509,40173)"><tspan fill="#000000">System Bus</tspan></tspan></tspan></text>
-</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.RectangleShape"><path fill="#cff" d="m13151 9262h-1250v-875h2499v875h-1249z"/><path fill="none" d="m13151 9262h-1250v-875h2499v875h-1249z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="9040" x="12215" class="TextPosition"><tspan fill="#000000">Demux</tspan></tspan></tspan></text>
-</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m9996 8765 373-357v178h1130v-178l374 357-374 358v-179h-1130v179l-373-358z"/><path fill="none" d="m9996 8765 373-357v178h1130v-178l374 357-374 358v-179h-1130v179l-373-358z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m9996 7378 373-358v179h1130v-179l374 358-374 358v-179h-1130v179l-373-358z"/><path fill="none" d="m9996 7378 373-358v179h1130v-179l374 358-374 358v-179h-1130v179l-373-358z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.RectangleShape"><path fill="#cff" d="m16322 7992h-4421v-1270h8841v1270h-4420z"/><path fill="none" d="m16322 7992h-4421v-1270h8841v1270h-4420z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="7573" x="12786" class="TextPosition"><tspan fill="#000000">Conditional Access Module</tspan></tspan></tspan></text>
-</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.RectangleShape"><path fill="#ff8080" d="m4445 13287h-2269v-1224h4537v1224h-2268z"/><path fill="none" d="m4445 13287h-2269v-1224h4537v1224h-2268z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="12891" x="2601" class="TextPosition"><tspan fill="#000000">Video encoder</tspan></tspan></tspan></text>
-</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m6721 12634 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z"/><path fill="none" d="m6721 12634 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m20791 7545 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z"/><path fill="none" d="m20791 7545 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z" stroke="#3465af"/></g><g transform="translate(-2028 -2186)" class="com.sun.star.drawing.TextShape"><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="14478" x="1990" class="TextPosition"><tspan fill="#000000">Radio / Analog TV</tspan></tspan></tspan></text>
-</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.TextShape"><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="700" class="TextParagraph"><tspan y="10724" x="14956" class="TextPosition"><tspan fill="#000000">Digital TV</tspan></tspan></tspan></text>
-</g><g transform="translate(-8970.5 -1395.8)" class="com.sun.star.drawing.TextShape"><text class="TextShape"><tspan font-size="494px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="19167" x="14724" class="TextPosition"><tspan fill="#000000">PS.: picture is not complete: other blocks may be present</tspan></tspan></tspan></text>
-</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.TextShape"><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="18561" x="4199" class="TextPosition"><tspan fill="#000000">Webcam</tspan></tspan></tspan></text>
-</g><g transform="translate(-2140.9 -2468.2)" class="com.sun.star.drawing.RectangleShape"><path fill="#f90" d="m14552 16372h-2650v-1412h5299v1412h-2649z"/><path fill="none" d="m14552 16372h-2650v-1412h5299v1412h-2649z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="15882" x="12265" class="TextPosition"><tspan fill="#000000">Processing blocks</tspan></tspan></tspan></text>
-</g><g transform="translate(-2140.9 -2468.2)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m9962 15654 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z"/><path fill="none" d="m9962 15654 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m6702 16954 397-353v176h1201v-176l398 353-398 354v-177h-1201v177l-397-354z"/><path fill="none" d="m6702 16954 397-353v176h1201v-176l398 353-398 354v-177h-1201v177l-397-354z" stroke="#3465af"/></g><g transform="translate(-2479.5 -2186)" class="com.sun.star.drawing.TextShape"><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="8792" x="22850" class="TextPosition"><tspan fill="#000000">Smartcard</tspan></tspan></tspan></text>
-</g><g transform="matrix(1.0048 0 0 1 -2207.4 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#fcf" d="m2766 2600c-333 0-666 333-666 666v2668c0 333 333 666 666 666h18368c333 0 667-333 667-666v-2668c0-333-334-666-667-666h-18368z"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.RectangleShape"><path fill="#ff8080" d="m5121 5155h-1614v-1816h3227v1816h-1613z"/><path fill="none" d="m5121 5155h-1614v-1816h3227v1816h-1613z" stroke="#3465af"/><text font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextShape"><tspan class="TextParagraph"><tspan y="4111" x="4374" class="TextPosition"><tspan fill="#000000">Tuner</tspan></tspan></tspan><tspan class="TextParagraph"><tspan y="4814" x="4151" class="TextPosition"><tspan fill="#000000">FM/TV</tspan></tspan></tspan></text>
-</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#ff8080" d="m2902 3702c0 111 40 202 88 202h530c48 0 89-91 89-202 0-110-41-202-89-202h-530c-48 0-88 92-88 202z"/><path fill="none" d="m2902 3702c0 111 40 202 88 202h530c48 0 89-91 89-202 0-110-41-202-89-202h-530c-48 0-88 92-88 202z" stroke="#3465af"/><path fill="#ffb3b3" d="m2902 3702c0 111 40 202 88 202s88-91 88-202c0-110-40-202-88-202s-88 92-88 202z"/><path fill="none" d="m2902 3702c0 111 40 202 88 202s88-91 88-202c0-110-40-202-88-202s-88 92-88 202z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#ff8080" d="m2903 4267c0 110 40 202 88 202h530c48 0 89-92 89-202s-41-203-89-203h-530c-48 0-88 93-88 203z"/><path fill="none" d="m2903 4267c0 110 40 202 88 202h530c48 0 89-92 89-202s-41-203-89-203h-530c-48 0-88 93-88 203z" stroke="#3465af"/><path fill="#ffb3b3" d="m2903 4267c0 110 40 202 88 202s88-92 88-202-40-203-88-203-88 93-88 203z"/><path fill="none" d="m2903 4267c0 110 40 202 88 202s88-92 88-202-40-203-88-203-88 93-88 203z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m6719 4196 385-353v176h1167v-176l386 353-386 354v-177h-1167v177l-385-354z"/><path fill="none" d="m6719 4196 385-353v176h1167v-176l386 353-386 354v-177h-1167v177l-385-354z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m9979 4150 402-368v184h1217v-184l403 368-403 369v-185h-1217v185l-402-369z"/><path fill="none" d="m9979 4150 402-368v184h1217v-184l403 368-403 369v-185h-1217v185l-402-369z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.RectangleShape"><path fill="#cff" d="m16500 6189h-4500v-1389h9e3v1389h-4500z"/><path fill="none" d="m16500 6189h-4500v-1389h9e3v1389h-4500z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="5710" x="12051" class="TextPosition"><tspan fill="#000000">Satellite Equipment Control (SEC)</tspan></tspan></tspan></text>
-</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#cff" d="m13400 4600h-1400v-1e3h2800v1e3h-1400z"/><path fill="none" d="m13400 4600h-1400v-1e3h2800v1e3h-1400z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="4316" x="12465" class="TextPosition"><tspan fill="#000000">Demod</tspan></tspan></tspan></text>
-</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m9979 5451 402-368v184h1217v-184l403 368-403 369v-185h-1217v185l-402-369z"/><path fill="none" d="m9979 5451 402-368v184h1217v-184l403 368-403 369v-185h-1217v185l-402-369z" stroke="#3465af"/></g><path fill="#ff9" d="m7855.1 9099v7302h-1270v-14605h1270v7303z"/><path fill="none" d="m7855.1 9099v7302h-1270v-14605h1270v7303z" stroke="#3465af"/><text y="-6640.4663" x="-20770.572" transform="rotate(-90)" class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="7409.5396" x="-11193.634" class="TextPosition" transform="matrix(0,-1,1,0,-4473,23627)"><tspan fill="#000000">I2C Bus (control bus)</tspan></tspan></tspan></text>
-<g transform="translate(-2197.3 -2186)" class="com.sun.star.drawing.TextShape"><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="3278" x="9391" class="TextPosition"><tspan fill="#000000">Digital TV Frontend</tspan></tspan></tspan></text>
-</g><g transform="matrix(1.015 0 0 .99994 -2233.3 -2185.7)" class="com.sun.star.drawing.CustomShape"><g stroke="#3465af" fill="none"><path d="m3e3 2800c-18 0-35 1-53 3"/><path d="m2915 2808c-17 3-35 7-52 12"/><path d="m2832 2830c-16 6-33 12-49 20"/><path d="m2754 2864c-15 8-31 17-46 27"/><path d="m2681 2909c-14 10-28 21-42 32"/><path d="m2614 2962c-13 12-26 24-38 37"/><path d="m2554 3023c-11 13-22 27-33 41"/><path d="m2502 3091c-10 14-19 29-28 45"/><path d="m2459 3164c-8 16-15 32-22 49"/><path d="m2426 3243c-5 17-10 34-14 51"/><path d="m2406 3326c-3 18-5 35-6 53"/><path d="m2400 3411v53"/><path d="m2400 3497v53"/><path d="m2400 3582v53"/><path d="m2400 3668v53"/><path d="m2400 3753v53"/><path d="m2400 3839v53"/><path d="m2400 3924v53"/><path d="m2400 4009v54"/><path d="m2400 4095v53"/><path d="m2400 4180v53"/><path d="m2400 4266v53"/><path d="m2400 4351v53"/><path d="m2400 4437v53"/><path d="m2400 4522v53"/><path d="m2400 4607v54"/><path d="m2400 4693v53"/><path d="m2400 4778v53"/><path d="m2400 4864v53"/><path d="m2400 4949v53"/><path d="m2400 5035v53"/><path d="m2400 5120v53"/><path d="m2400 5205v54"/><path d="m2400 5291v53"/><path d="m2400 5376v53"/><path d="m2400 5462v53"/><path d="m2400 5547v53"/><path d="m2400 5633v53"/><path d="m2400 5718v53"/><path d="m2400 5803c0 18 1 36 3 53"/><path d="m2408 5888c4 18 8 35 13 52"/><path d="m2431 5971c6 16 13 33 20 49"/><path d="m2466 6049c8 15 17 31 27 46"/><path d="m2511 6122c10 14 21 28 32 42"/><path d="m2564 6188c12 13 25 26 38 38"/><path d="m2626 6248c13 11 27 23 41 33"/><path d="m2694 6300c14 10 29 19 45 27"/><path d="m2768 6343c15 7 32 15 48 21"/><path d="m2847 6375c17 5 34 10 51 14"/><path d="m2930 6395c17 2 35 4 53 5"/><path d="m3015 6400h53"/><path d="m3100 6400h53"/><path d="m3186 6400h53"/><path d="m3271 6400h53"/><path d="m3357 6400h53"/><path d="m3442 6400h53"/><path d="m3527 6400h54"/><path d="m3613 6400h53"/><path d="m3698 6400h53"/><path d="m3784 6400h53"/><path d="m3869 6400h53"/><path d="m3955 6400h53"/><path d="m4040 6400h53"/><path d="m4125 6400h54"/><path d="m4211 6400h53"/><path d="m4296 6400h53"/><path d="m4382 6400h53"/><path d="m4467 6400h53"/><path d="m4553 6400h53"/><path d="m4638 6400h53"/><path d="m4723 6400h54"/><path d="m4809 6400h53"/><path d="m4894 6400h53"/><path d="m4980 6400h53"/><path d="m5065 6400h53"/><path d="m5151 6400h53"/><path d="m5236 6400h53"/><path d="m5322 6400h53"/><path d="m5407 6400h53"/><path d="m5492 6400h53"/><path d="m5578 6400h53"/><path d="m5663 6400h53"/><path d="m5749 6400h53"/><path d="m5834 6400h53"/><path d="m5920 6400h53"/><path d="m6005 6400h53"/><path d="m6090 6400h53"/><path d="m6176 6400h53"/><path d="m6261 6400h53"/><path d="m6347 6400h53"/><path d="m6432 6400h53"/><path d="m6518 6400h53"/><path d="m6603 6400h53"/><path d="m6688 6400h54"/><path d="m6774 6400h53"/><path d="m6859 6400h53"/><path d="m6945 6400h53"/><path d="m7030 6400h53"/><path d="m7116 6400h53"/><path d="m7201 6400h53"/><path d="m7286 6400h54"/><path d="m7372 6400h53"/><path d="m7457 6400h53"/><path d="m7543 6400h53"/><path d="m7628 6400h53"/><path d="m7714 6400h53"/><path d="m7799 6400h53"/><path d="m7884 6400h54"/><path d="m7970 6400h53"/><path d="m8055 6400h53"/><path d="m8141 6400h53"/><path d="m8226 6400h53"/><path d="m8312 6400h53"/><path d="m8397 6400h53"/><path d="m8482 6400h54"/><path d="m8568 6400h53"/><path d="m8653 6400h53"/><path d="m8739 6400h53"/><path d="m8824 6400h53"/><path d="m8910 6400h53"/><path d="m8995 6400h53"/><path d="m9081 6400h53"/><path d="m9166 6400h53"/><path d="m9251 6400h53"/><path d="m9337 6400h53"/><path d="m9422 6400h53"/><path d="m9508 6400h53"/><path d="m9593 6400h53"/><path d="m9679 6400h53"/><path d="m9764 6400h53"/><path d="m9849 6400h53"/><path d="m9935 6400h53"/><path d="m10020 6400h53"/><path d="m10106 6400h53"/><path d="m10191 6400h53"/><path d="m10277 6400h53"/><path d="m10362 6400h53"/><path d="m10447 6400h53"/><path d="m10533 6400h53"/><path d="m10618 6400h53"/><path d="m10704 6400h53"/><path d="m10789 6400h53"/><path d="m10875 6400h53"/><path d="m10960 6400h53"/><path d="m11045 6400h54"/><path d="m11131 6400h53"/><path d="m11216 6400h53"/><path d="m11302 6400h53"/><path d="m11387 6400h53"/><path d="m11473 6400h53"/><path d="m11558 6400h53"/><path d="m11643 6400h54"/><path d="m11729 6400h53"/><path d="m11814 6400h53"/><path d="m11900 6400h53"/><path d="m11985 6400h53"/><path d="m12071 6400h53"/><path d="m12156 6400h53"/><path d="m12241 6400h54"/><path d="m12327 6400h53"/><path d="m12412 6400h53"/><path d="m12498 6400h53"/><path d="m12583 6400h53"/><path d="m12669 6400h53"/><path d="m12754 6400h53"/><path d="m12839 6400h54"/><path d="m12925 6400h53"/><path d="m13010 6400h53"/><path d="m13096 6400h53"/><path d="m13181 6400h53"/><path d="m13267 6400h53"/><path d="m13352 6400h53"/><path d="m13438 6400h53"/><path d="m13523 6400h53"/><path d="m13608 6400h53"/><path d="m13694 6400h53"/><path d="m13779 6400h53"/><path d="m13865 6400h53"/><path d="m13950 6400h53"/><path d="m14036 6400h53"/><path d="m14121 6400h53"/><path d="m14206 6400h53"/><path d="m14292 6400h53"/><path d="m14377 6400h53"/><path d="m14463 6400h53"/><path d="m14548 6400h53"/><path d="m14634 6400h53"/><path d="m14719 6400h53"/><path d="m14804 6400h54"/><path d="m14890 6400h53"/><path d="m14975 6400h53"/><path d="m15061 6400h53"/><path d="m15146 6400h53"/><path d="m15232 6400h53"/><path d="m15317 6400h53"/><path d="m15402 6400h54"/><path d="m15488 6400h53"/><path d="m15573 6400h53"/><path d="m15659 6400h53"/><path d="m15744 6400h53"/><path d="m15830 6400h53"/><path d="m15915 6400h53"/><path d="m16000 6400h54"/><path d="m16086 6400h53"/><path d="m16171 6400h53"/><path d="m16257 6400h53"/><path d="m16342 6400h53"/><path d="m16428 6400h53"/><path d="m16513 6400h53"/><path d="m16598 6400h54"/><path d="m16684 6400h53"/><path d="m16769 6400h53"/><path d="m16855 6400h53"/><path d="m16940 6400h53"/><path d="m17026 6400h53"/><path d="m17111 6400h53"/><path d="m17196 6400h54"/><path d="m17282 6400h53"/><path d="m17367 6400h53"/><path d="m17453 6400h53"/><path d="m17538 6400h53"/><path d="m17624 6400h53"/><path d="m17709 6400h53"/><path d="m17795 6400h53"/><path d="m17880 6400h53"/><path d="m17965 6400h53"/><path d="m18051 6400h53"/><path d="m18136 6400h53"/><path d="m18222 6400h53"/><path d="m18307 6400h53"/><path d="m18393 6400h53"/><path d="m18478 6400h53"/><path d="m18563 6400h53"/><path d="m18649 6400h53"/><path d="m18734 6400h53"/><path d="m18820 6400h53"/><path d="m18905 6400h53"/><path d="m18991 6400h53"/><path d="m19076 6400h53"/><path d="m19161 6400h54"/><path d="m19247 6400h53"/><path d="m19332 6400h53"/><path d="m19418 6400h53"/><path d="m19503 6400h53"/><path d="m19589 6400h53"/><path d="m19674 6400h53"/><path d="m19759 6400h54"/><path d="m19845 6400h53"/><path d="m19930 6400h53"/><path d="m20016 6400h53"/><path d="m20101 6400h53"/><path d="m20187 6400h53"/><path d="m20272 6400h53"/><path d="m20357 6400h54"/><path d="m20443 6400h53"/><path d="m20528 6400h53"/><path d="m20614 6400c17-1 35-2 53-5"/><path d="m20699 6390c17-4 34-9 51-14"/><path d="m20781 6365c16-6 32-13 48-21"/><path d="m20858 6329c15-8 31-17 45-27"/><path d="m20930 6283c14-10 28-21 42-32"/><path d="m20996 6229c13-12 25-25 37-38"/><path d="m21055 6167c11-14 22-28 33-42"/><path d="m21106 6098c10-15 19-30 27-45"/><path d="m21148 6024c7-16 14-33 20-49"/><path d="m21179 5944c5-17 9-34 13-51"/><path d="m21197 5861c2-18 4-35 4-53"/><path d="m21201 5776v-54"/><path d="m21201 5690v-53"/><path d="m21201 5605v-53"/><path d="m21201 5519v-53"/><path d="m21201 5434v-53"/><path d="m21201 5348v-53"/><path d="m21201 5263v-53"/><path d="m21201 5178v-54"/><path d="m21201 5092v-53"/><path d="m21201 5007v-53"/><path d="m21201 4921v-53"/><path d="m21201 4836v-53"/><path d="m21201 4750v-53"/><path d="m21201 4665v-53"/><path d="m21201 4579v-53"/><path d="m21201 4494v-53"/><path d="m21201 4409v-53"/><path d="m21201 4323v-53"/><path d="m21201 4238v-53"/><path d="m21201 4152v-53"/><path d="m21201 4067v-53"/><path d="m21201 3981v-53"/><path d="m21201 3896v-53"/><path d="m21201 3811v-53"/><path d="m21201 3725v-53"/><path d="m21201 3640v-53"/><path d="m21201 3554v-53"/><path d="m21201 3469v-53"/><path d="m21201 3383c-1-17-3-35-5-52"/><path d="m21190 3299c-4-17-8-35-14-51"/><path d="m21165 3217c-6-16-13-33-21-49"/><path d="m21129 3140c-9-16-18-31-28-46"/><path d="m21082 3068c-10-14-21-28-33-42"/><path d="m21027 3002c-12-13-24-25-37-37"/><path d="m20965 2944c-14-12-28-22-42-33"/><path d="m20896 2893c-15-9-30-18-46-27"/><path d="m20821 2852c-16-8-32-14-49-20"/><path d="m20741 2821c-17-5-34-9-51-12"/><path d="m20658 2804c-18-3-35-4-53-4"/><path d="m20573 2800h-53"/><path d="m20487 2800h-53"/><path d="m20402 2800h-53"/><path d="m20316 2800h-53"/><path d="m20231 2800h-53"/><path d="m20146 2800h-54"/><path d="m20060 2800h-53"/><path d="m19975 2800h-53"/><path d="m19889 2800h-53"/><path d="m19804 2800h-53"/><path d="m19718 2800h-53"/><path d="m19633 2800h-53"/><path d="m19548 2800h-54"/><path d="m19462 2800h-53"/><path d="m19377 2800h-53"/><path d="m19291 2800h-53"/><path d="m19206 2800h-53"/><path d="m19120 2800h-53"/><path d="m19035 2800h-53"/><path d="m18950 2800h-54"/><path d="m18864 2800h-53"/><path d="m18779 2800h-53"/><path d="m18693 2800h-53"/><path d="m18608 2800h-53"/><path d="m18522 2800h-53"/><path d="m18437 2800h-53"/><path d="m18352 2800h-54"/><path d="m18266 2800h-53"/><path d="m18181 2800h-53"/><path d="m18095 2800h-53"/><path d="m18010 2800h-53"/><path d="m17924 2800h-53"/><path d="m17839 2800h-53"/><path d="m17753 2800h-53"/><path d="m17668 2800h-53"/><path d="m17583 2800h-53"/><path d="m17497 2800h-53"/><path d="m17412 2800h-53"/><path d="m17326 2800h-53"/><path d="m17241 2800h-53"/><path d="m17155 2800h-53"/><path d="m17070 2800h-53"/><path d="m16985 2800h-53"/><path d="m16899 2800h-53"/><path d="m16814 2800h-53"/><path d="m16728 2800h-53"/><path d="m16643 2800h-53"/><path d="m16557 2800h-53"/><path d="m16472 2800h-53"/><path d="m16387 2800h-54"/><path d="m16301 2800h-53"/><path d="m16216 2800h-53"/><path d="m16130 2800h-53"/><path d="m16045 2800h-53"/><path d="m15959 2800h-53"/><path d="m15874 2800h-53"/><path d="m15789 2800h-54"/><path d="m15703 2800h-53"/><path d="m15618 2800h-53"/><path d="m15532 2800h-53"/><path d="m15447 2800h-53"/><path d="m15361 2800h-53"/><path d="m15276 2800h-53"/><path d="m15191 2800h-54"/><path d="m15105 2800h-53"/><path d="m15020 2800h-53"/><path d="m14934 2800h-53"/><path d="m14849 2800h-53"/><path d="m14763 2800h-53"/><path d="m14678 2800h-53"/><path d="m14593 2800h-54"/><path d="m14507 2800h-53"/><path d="m14422 2800h-53"/><path d="m14336 2800h-53"/><path d="m14251 2800h-53"/><path d="m14165 2800h-53"/><path d="m14080 2800h-53"/><path d="m13994 2800h-53"/><path d="m13909 2800h-53"/><path d="m13824 2800h-53"/><path d="m13738 2800h-53"/><path d="m13653 2800h-53"/><path d="m13567 2800h-53"/><path d="m13482 2800h-53"/><path d="m13396 2800h-53"/><path d="m13311 2800h-53"/><path d="m13226 2800h-53"/><path d="m13140 2800h-53"/><path d="m13055 2800h-53"/><path d="m12969 2800h-53"/><path d="m12884 2800h-53"/><path d="m12798 2800h-53"/><path d="m12713 2800h-53"/><path d="m12628 2800h-53"/><path d="m12542 2800h-53"/><path d="m12457 2800h-53"/><path d="m12371 2800h-53"/><path d="m12286 2800h-53"/><path d="m12200 2800h-53"/><path d="m12115 2800h-53"/><path d="m12030 2800h-54"/><path d="m11944 2800h-53"/><path d="m11859 2800h-53"/><path d="m11773 2800h-53"/><path d="m11688 2800h-53"/><path d="m11602 2800h-53"/><path d="m11517 2800h-53"/><path d="m11432 2800h-54"/><path d="m11346 2800h-53"/><path d="m11261 2800h-53"/><path d="m11175 2800h-53"/><path d="m11090 2800h-53"/><path d="m11004 2800h-53"/><path d="m10919 2800h-53"/><path d="m10834 2800h-54"/><path d="m10748 2800h-53"/><path d="m10663 2800h-53"/><path d="m10577 2800h-53"/><path d="m10492 2800h-53"/><path d="m10406 2800h-53"/><path d="m10321 2800h-53"/><path d="m10236 2800h-54"/><path d="m10150 2800h-53"/><path d="m10065 2800h-53"/><path d="m9979 2800h-53"/><path d="m9894 2800h-53"/><path d="m9808 2800h-53"/><path d="m9723 2800h-53"/><path d="m9637 2800h-53"/><path d="m9552 2800h-53"/><path d="m9467 2800h-53"/><path d="m9381 2800h-53"/><path d="m9296 2800h-53"/><path d="m9210 2800h-53"/><path d="m9125 2800h-53"/><path d="m9039 2800h-53"/><path d="m8954 2800h-53"/><path d="m8869 2800h-53"/><path d="m8783 2800h-53"/><path d="m8698 2800h-53"/><path d="m8612 2800h-53"/><path d="m8527 2800h-53"/><path d="m8441 2800h-53"/><path d="m8356 2800h-53"/><path d="m8271 2800h-54"/><path d="m8185 2800h-53"/><path d="m8100 2800h-53"/><path d="m8014 2800h-53"/><path d="m7929 2800h-53"/><path d="m7843 2800h-53"/><path d="m7758 2800h-53"/><path d="m7673 2800h-54"/><path d="m7587 2800h-53"/><path d="m7502 2800h-53"/><path d="m7416 2800h-53"/><path d="m7331 2800h-53"/><path d="m7245 2800h-53"/><path d="m7160 2800h-53"/><path d="m7075 2800h-54"/><path d="m6989 2800h-53"/><path d="m6904 2800h-53"/><path d="m6818 2800h-53"/><path d="m6733 2800h-53"/><path d="m6647 2800h-53"/><path d="m6562 2800h-53"/><path d="m6477 2800h-54"/><path d="m6391 2800h-53"/><path d="m6306 2800h-53"/><path d="m6220 2800h-53"/><path d="m6135 2800h-53"/><path d="m6049 2800h-53"/><path d="m5964 2800h-53"/><path d="m5879 2800h-54"/><path d="m5793 2800h-53"/><path d="m5708 2800h-53"/><path d="m5622 2800h-53"/><path d="m5537 2800h-53"/><path d="m5451 2800h-53"/><path d="m5366 2800h-53"/><path d="m5280 2800h-53"/><path d="m5195 2800h-53"/><path d="m5110 2800h-53"/><path d="m5024 2800h-53"/><path d="m4939 2800h-53"/><path d="m4853 2800h-53"/><path d="m4768 2800h-53"/><path d="m4682 2800h-53"/><path d="m4597 2800h-53"/><path d="m4512 2800h-53"/><path d="m4426 2800h-53"/><path d="m4341 2800h-53"/><path d="m4255 2800h-53"/><path d="m4170 2800h-53"/><path d="m4084 2800h-53"/><path d="m3999 2800h-53"/><path d="m3914 2800h-54"/><path d="m3828 2800h-53"/><path d="m3743 2800h-53"/><path d="m3657 2800h-53"/><path d="m3572 2800h-53"/><path d="m3486 2800h-53"/><path d="m3401 2800h-53"/><path d="m3316 2800h-54"/><path d="m3230 2800h-53"/><path d="m3145 2800h-53"/><path d="m3059 2800h-53"/></g></g><g transform="translate(-2197.3 -2186)"><rect height="1100.7" width="1213.6" y="6917.1" x="23255" fill="#f3e777"/><path fill="#ca4677" d="m22802 7700.4v-405.46l150.7-169.16c82.886-93.039 170.53-186.62 194.77-207.96l44.069-38.798 783.23-0.086 783.23-0.086v613.5 613.5h-978-978v-405.46zm1027.7 136.98v-78.372l-169.91 4.925-169.91 4.9249-5.09 45.854c-8.249 74.303 46.711 101.04 207.69 101.04h137.21v-78.372zm235.86-262.94 4.495-341.31 207.2-8.6408 207.2-8.6408 5.144-46.443c9.596-86.615-41.863-102.05-322.02-96.607l-246.71 4.7956-4.438 419.08-4.439 419.08h74.537 74.538l4.494-341.31zm391.3 313.72c26.41-19.286 36.255-41.399 32.697-73.447l-5.09-45.854h-174.05-174.05l-5.38 48.984c-9.97 90.771 0.993 97.91 150.36 97.91 99.305 0 148.27-7.6982 175.52-27.594zm-627.16-274.84v-77.768h-174.05-174.05v66.246c0 36.436 4.973 71.431 11.051 77.768 6.078 6.3366 84.401 11.521 174.05 11.521h163v-77.768zm659.89-4.9154 5.125-74.042-179.18 4.9155-179.18 4.9155-5.38 48.984c-10.473 95.348-2.259 99.57 183.28 94.197l170.2-4.9284 5.125-74.042zm-659.89-237.63v-78.372l-169.91 4.925-169.91 4.925-5.097 73.447-5.097 73.447h175 175v-78.372zm659.86 4.925-5.097-73.447h-174.05-174.05l-5.38 48.984c-10.289 93.673-2.146 97.91 188.15 97.91h175.52l-5.097-73.447zm-659.86-228.98v-77.768h-137.21c-97.358 0-147.91 7.8138-174.05 26.902-34.952 25.523-49.645 92.242-25.79 117.11 6.078 6.3366 84.401 11.521 174.05 11.521h163v-77.768z"/></g><g transform="matrix(.84874 0 0 .76147 2408.1 3615.3)"><rect height="3076.2" width="2734.3" y="13264" x="19249" fill="#6076b3"/><g stroke-linejoin="round" fill-rule="evenodd" stroke-width="28.222" fill="#e0ee2c"><rect y="13369" width="356.65" x="18937" height="180.95"/><rect y="13708" width="356.65" x="18937" height="180.95"/><rect y="14048" width="356.65" x="18937" height="180.95"/><rect y="14387" width="356.65" x="18937" height="180.95"/><rect y="14726" width="356.65" x="18937" height="180.95"/><rect y="15066" width="356.65" x="18937" height="180.95"/><rect y="15405" width="356.65" x="18937" height="180.95"/><rect y="15744" width="356.65" x="18937" height="180.95"/><rect y="16083" width="356.65" x="18937" height="180.95"/><rect y="13324" width="356.65" x="21939" height="180.95"/><rect y="13663" width="356.65" x="21939" height="180.95"/><rect y="14002" width="356.65" x="21939" height="180.95"/><rect y="14342" width="356.65" x="21939" height="180.95"/><rect y="14681" width="356.65" x="21939" height="180.95"/><rect y="15020" width="356.65" x="21939" height="180.95"/><rect y="15360" width="356.65" x="21939" height="180.95"/><rect y="15699" width="356.65" x="21939" height="180.95"/><rect y="16038" width="356.65" x="21939" height="180.95"/></g><g stroke-linejoin="round" fill-rule="evenodd" transform="matrix(.98702 0 0 .90336 -2675 7020.8)" class="com.sun.star.drawing.TextShape" stroke-width="28.222"><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"/></text>
-<text style="word-spacing:0px;letter-spacing:0px" xml:space="preserve" font-size="1128.9px" y="9042.0264" x="22439.668" font-family="Sans" line-height="125%" fill="#000000"><tspan y="9042.0264" x="22439.668">CPU</tspan></text>
-</g></g><g stroke-linejoin="round" fill-rule="evenodd" transform="translate(-11752 543.6)" class="com.sun.star.drawing.TextShape" stroke-width="28.222"><text class="TextShape"><tspan font-size="706px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="15832" x="24341" class="TextPosition" transform="matrix(0,-1,1,0,8509,40173)"><tspan fill="#000000">PCI, USB, SPI, I2C, ...</tspan></tspan></tspan></text>
-</g><g stroke-linejoin="round" fill-rule="evenodd" transform="translate(-655.31 963.83)" class="com.sun.star.drawing.RectangleShape" stroke-width="28.222"><g transform="matrix(.49166 0 0 1.0059 6045.6 -82.24)"><path fill="#cfe7f5" d="m14169 14572h-2268v-1412h4536v1412h-2268z"/><path fill="none" d="m14169 14572h-2268v-1412h4536v1412h-2268z" stroke="#3465af"/></g><text y="-395.11282" x="-790.22229" class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="13686.9" x="12091.779" class="TextPosition"><tspan fill="#000000">Bridge</tspan></tspan></tspan></text>
-<text y="338.66486" x="-846.66675" class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="14420.677" x="12035.335" class="TextPosition"><tspan fill="#000000"> DMA</tspan></tspan></tspan></text>
-</g></svg>
+++ /dev/null
-# Ignore header name
-ignore define _DVBNET_H_
-
-# Ignore old ioctls/structs
-ignore ioctl __NET_ADD_IF_OLD
-ignore ioctl __NET_GET_IF_OLD
-ignore struct __dvb_net_if_old
-
-# Macros used at struct dvb_net_if
-replace define DVB_NET_FEEDTYPE_MPE dvb-net-if
-replace define DVB_NET_FEEDTYPE_ULE dvb-net-if
+++ /dev/null
-# Ignore header name
-ignore define _UAPI_DVBVIDEO_H_
-
-# This is a deprecated obscure API. Just ignore things we don't know
-ignore define VIDEO_CMD_PLAY
-ignore define VIDEO_CMD_STOP
-ignore define VIDEO_CMD_FREEZE
-ignore define VIDEO_CMD_CONTINUE
-ignore define VIDEO_CMD_FREEZE_TO_BLACK
-ignore define VIDEO_CMD_STOP_TO_BLACK
-ignore define VIDEO_CMD_STOP_IMMEDIATELY
-ignore define VIDEO_PLAY_FMT_NONE
-ignore define VIDEO_PLAY_FMT_GOP
-ignore define VIDEO_VSYNC_FIELD_UNKNOWN
-ignore define VIDEO_VSYNC_FIELD_ODD
-ignore define VIDEO_VSYNC_FIELD_EVEN
-ignore define VIDEO_VSYNC_FIELD_PROGRESSIVE
-ignore define VIDEO_EVENT_SIZE_CHANGED
-ignore define VIDEO_EVENT_FRAME_RATE_CHANGED
-ignore define VIDEO_EVENT_DECODER_STOPPED
-ignore define VIDEO_EVENT_VSYNC
-ignore define VIDEO_CAP_MPEG1
-ignore define VIDEO_CAP_MPEG2
-ignore define VIDEO_CAP_SYS
-ignore define VIDEO_CAP_PROG
-ignore define VIDEO_CAP_SPU
-ignore define VIDEO_CAP_NAVI
-ignore define VIDEO_CAP_CSS
-
-# some typedefs should point to struct/enums
-replace typedef video_format_t video-format
-replace typedef video_system_t video-system
-replace typedef video_displayformat_t video-displayformat
-replace typedef video_size_t video-size
-replace typedef video_stream_source_t video-stream-source
-replace typedef video_play_state_t video-play-state
-replace typedef video_highlight_t video-highlight
-replace typedef video_spu_t video-spu
-replace typedef video_spu_palette_t video-spu-palette
-replace typedef video_navi_pack_t video-navi-pack
+++ /dev/null
-# Ignore header name
-ignore define _UAPI__LINUX_VIDEODEV2_H
-
-#
-# The cross reference valitator for videodev2.h DocBook never cared
-# about enum symbols or defines. Yet, they're all (or almost all?)
-# handled inside V4L API sections. So, for now, it is safe to just
-# ignore. This should be revisited, as validating it helps to avoid
-# having something not documented at the uAPI.
-#
-
-# Those symbols should not be used by uAPI - don't document them
-ignore symbol V4L2_BUF_TYPE_PRIVATE
-ignore symbol V4L2_TUNER_DIGITAL_TV
-ignore symbol V4L2_COLORSPACE_BT878
-
-# Documented enum v4l2_field
-replace symbol V4L2_FIELD_ALTERNATE v4l2-field
-replace symbol V4L2_FIELD_ANY v4l2-field
-replace symbol V4L2_FIELD_BOTTOM v4l2-field
-replace symbol V4L2_FIELD_INTERLACED v4l2-field
-replace symbol V4L2_FIELD_INTERLACED_BT v4l2-field
-replace symbol V4L2_FIELD_INTERLACED_TB v4l2-field
-replace symbol V4L2_FIELD_NONE v4l2-field
-replace symbol V4L2_FIELD_SEQ_BT v4l2-field
-replace symbol V4L2_FIELD_SEQ_TB v4l2-field
-replace symbol V4L2_FIELD_TOP v4l2-field
-
-# Documented enum v4l2_buf_type
-replace symbol V4L2_BUF_TYPE_SDR_CAPTURE v4l2-buf-type
-replace symbol V4L2_BUF_TYPE_SDR_OUTPUT v4l2-buf-type
-replace symbol V4L2_BUF_TYPE_SLICED_VBI_CAPTURE v4l2-buf-type
-replace symbol V4L2_BUF_TYPE_SLICED_VBI_OUTPUT v4l2-buf-type
-replace symbol V4L2_BUF_TYPE_VBI_CAPTURE v4l2-buf-type
-replace symbol V4L2_BUF_TYPE_VBI_OUTPUT v4l2-buf-type
-replace symbol V4L2_BUF_TYPE_VIDEO_CAPTURE v4l2-buf-type
-replace symbol V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE v4l2-buf-type
-replace symbol V4L2_BUF_TYPE_VIDEO_OUTPUT v4l2-buf-type
-replace symbol V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE v4l2-buf-type
-replace symbol V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY v4l2-buf-type
-replace symbol V4L2_BUF_TYPE_VIDEO_OVERLAY v4l2-buf-type
-
-# Documented enum v4l2_tuner_type
-replace symbol V4L2_TUNER_ANALOG_TV v4l2-tuner-type
-replace symbol V4L2_TUNER_RADIO v4l2-tuner-type
-replace symbol V4L2_TUNER_RF v4l2-tuner-type
-replace symbol V4L2_TUNER_SDR v4l2-tuner-type
-
-# Documented enum v4l2_memory
-replace symbol V4L2_MEMORY_DMABUF v4l2-memory
-replace symbol V4L2_MEMORY_MMAP v4l2-memory
-replace symbol V4L2_MEMORY_OVERLAY v4l2-memory
-replace symbol V4L2_MEMORY_USERPTR v4l2-memory
-
-# Documented enum v4l2_colorspace
-replace symbol V4L2_COLORSPACE_470_SYSTEM_BG v4l2-colorspace
-replace symbol V4L2_COLORSPACE_470_SYSTEM_M v4l2-colorspace
-replace symbol V4L2_COLORSPACE_ADOBERGB v4l2-colorspace
-replace symbol V4L2_COLORSPACE_BT2020 v4l2-colorspace
-replace symbol V4L2_COLORSPACE_DCI_P3 v4l2-colorspace
-replace symbol V4L2_COLORSPACE_DEFAULT v4l2-colorspace
-replace symbol V4L2_COLORSPACE_JPEG v4l2-colorspace
-replace symbol V4L2_COLORSPACE_RAW v4l2-colorspace
-replace symbol V4L2_COLORSPACE_REC709 v4l2-colorspace
-replace symbol V4L2_COLORSPACE_SMPTE170M v4l2-colorspace
-replace symbol V4L2_COLORSPACE_SMPTE240M v4l2-colorspace
-replace symbol V4L2_COLORSPACE_SRGB v4l2-colorspace
-
-# Documented enum v4l2_xfer_func
-replace symbol V4L2_XFER_FUNC_709 v4l2-xfer-func
-replace symbol V4L2_XFER_FUNC_ADOBERGB v4l2-xfer-func
-replace symbol V4L2_XFER_FUNC_DCI_P3 v4l2-xfer-func
-replace symbol V4L2_XFER_FUNC_DEFAULT v4l2-xfer-func
-replace symbol V4L2_XFER_FUNC_NONE v4l2-xfer-func
-replace symbol V4L2_XFER_FUNC_SMPTE2084 v4l2-xfer-func
-replace symbol V4L2_XFER_FUNC_SMPTE240M v4l2-xfer-func
-replace symbol V4L2_XFER_FUNC_SRGB v4l2-xfer-func
-
-# Documented enum v4l2_ycbcr_encoding
-replace symbol V4L2_YCBCR_ENC_601 v4l2-ycbcr-encoding
-replace symbol V4L2_YCBCR_ENC_709 v4l2-ycbcr-encoding
-replace symbol V4L2_YCBCR_ENC_BT2020 v4l2-ycbcr-encoding
-replace symbol V4L2_YCBCR_ENC_BT2020_CONST_LUM v4l2-ycbcr-encoding
-replace symbol V4L2_YCBCR_ENC_DEFAULT v4l2-ycbcr-encoding
-replace symbol V4L2_YCBCR_ENC_SYCC v4l2-ycbcr-encoding
-replace symbol V4L2_YCBCR_ENC_XV601 v4l2-ycbcr-encoding
-replace symbol V4L2_YCBCR_ENC_XV709 v4l2-ycbcr-encoding
-
-# Is this deprecated, or just a missing reference?
-replace symbol V4L2_YCBCR_ENC_SMPTE240M v4l2-ycbcr-encoding-FIXME
-
-# Documented enum v4l2_quantization
-replace symbol V4L2_QUANTIZATION_DEFAULT v4l2-quantization
-replace symbol V4L2_QUANTIZATION_FULL_RANGE v4l2-quantization
-replace symbol V4L2_QUANTIZATION_LIM_RANGE v4l2-quantization
-
-# Documented enum v4l2_priority
-replace symbol V4L2_PRIORITY_BACKGROUND v4l2-priority
-replace symbol V4L2_PRIORITY_DEFAULT v4l2-priority
-replace symbol V4L2_PRIORITY_INTERACTIVE v4l2-priority
-replace symbol V4L2_PRIORITY_RECORD v4l2-priority
-replace symbol V4L2_PRIORITY_UNSET v4l2-priority
-
-# Documented enum v4l2_frmsizetypes
-replace symbol V4L2_FRMSIZE_TYPE_CONTINUOUS v4l2-frmsizetypes
-replace symbol V4L2_FRMSIZE_TYPE_DISCRETE v4l2-frmsizetypes
-replace symbol V4L2_FRMSIZE_TYPE_STEPWISE v4l2-frmsizetypes
-
-# Documented enum frmivaltypes
-replace symbol V4L2_FRMIVAL_TYPE_CONTINUOUS v4l2-frmivaltypes
-replace symbol V4L2_FRMIVAL_TYPE_DISCRETE v4l2-frmivaltypes
-replace symbol V4L2_FRMIVAL_TYPE_STEPWISE v4l2-frmivaltypes
-
-# Documented enum v4l2-ctrl-type
-replace symbol V4L2_CTRL_COMPOUND_TYPES vidioc_queryctrl
-
-replace symbol V4L2_CTRL_TYPE_BITMASK v4l2-ctrl-type
-replace symbol V4L2_CTRL_TYPE_BOOLEAN v4l2-ctrl-type
-replace symbol V4L2_CTRL_TYPE_BUTTON v4l2-ctrl-type
-replace symbol V4L2_CTRL_TYPE_CTRL_CLASS v4l2-ctrl-type
-replace symbol V4L2_CTRL_TYPE_INTEGER v4l2-ctrl-type
-replace symbol V4L2_CTRL_TYPE_INTEGER64 v4l2-ctrl-type
-replace symbol V4L2_CTRL_TYPE_INTEGER_MENU v4l2-ctrl-type
-replace symbol V4L2_CTRL_TYPE_MENU v4l2-ctrl-type
-replace symbol V4L2_CTRL_TYPE_STRING v4l2-ctrl-type
-replace symbol V4L2_CTRL_TYPE_U16 v4l2-ctrl-type
-replace symbol V4L2_CTRL_TYPE_U32 v4l2-ctrl-type
-replace symbol V4L2_CTRL_TYPE_U8 v4l2-ctrl-type
-
-# V4L2 capability defines
-replace define V4L2_CAP_VIDEO_CAPTURE device-capabilities
-replace define V4L2_CAP_VIDEO_CAPTURE_MPLANE device-capabilities
-replace define V4L2_CAP_VIDEO_OUTPUT device-capabilities
-replace define V4L2_CAP_VIDEO_OUTPUT_MPLANE device-capabilities
-replace define V4L2_CAP_VIDEO_M2M device-capabilities
-replace define V4L2_CAP_VIDEO_M2M_MPLANE device-capabilities
-replace define V4L2_CAP_VIDEO_OVERLAY device-capabilities
-replace define V4L2_CAP_VBI_CAPTURE device-capabilities
-replace define V4L2_CAP_VBI_OUTPUT device-capabilities
-replace define V4L2_CAP_SLICED_VBI_CAPTURE device-capabilities
-replace define V4L2_CAP_SLICED_VBI_OUTPUT device-capabilities
-replace define V4L2_CAP_RDS_CAPTURE device-capabilities
-replace define V4L2_CAP_VIDEO_OUTPUT_OVERLAY device-capabilities
-replace define V4L2_CAP_HW_FREQ_SEEK device-capabilities
-replace define V4L2_CAP_RDS_OUTPUT device-capabilities
-replace define V4L2_CAP_TUNER device-capabilities
-replace define V4L2_CAP_AUDIO device-capabilities
-replace define V4L2_CAP_RADIO device-capabilities
-replace define V4L2_CAP_MODULATOR device-capabilities
-replace define V4L2_CAP_SDR_CAPTURE device-capabilities
-replace define V4L2_CAP_EXT_PIX_FORMAT device-capabilities
-replace define V4L2_CAP_SDR_OUTPUT device-capabilities
-replace define V4L2_CAP_READWRITE device-capabilities
-replace define V4L2_CAP_ASYNCIO device-capabilities
-replace define V4L2_CAP_STREAMING device-capabilities
-replace define V4L2_CAP_DEVICE_CAPS device-capabilities
-
-# V4L2 pix flags
-replace define V4L2_PIX_FMT_PRIV_MAGIC v4l2-pix-format
-replace define V4L2_PIX_FMT_FLAG_PREMUL_ALPHA reserved-formats
-
-# V4L2 format flags
-replace define V4L2_FMT_FLAG_COMPRESSED fmtdesc-flags
-replace define V4L2_FMT_FLAG_EMULATED fmtdesc-flags
-
-# V4L2 tymecode types
-replace define V4L2_TC_TYPE_24FPS timecode-type
-replace define V4L2_TC_TYPE_25FPS timecode-type
-replace define V4L2_TC_TYPE_30FPS timecode-type
-replace define V4L2_TC_TYPE_50FPS timecode-type
-replace define V4L2_TC_TYPE_60FPS timecode-type
-
-# V4L2 tymecode flags
-replace define V4L2_TC_FLAG_DROPFRAME timecode-flags
-replace define V4L2_TC_FLAG_COLORFRAME timecode-flags
-replace define V4L2_TC_USERBITS_field timecode-flags
-replace define V4L2_TC_USERBITS_USERDEFINED timecode-flags
-replace define V4L2_TC_USERBITS_8BITCHARS timecode-flags
-
-# V4L2 JPEG markers
-replace define V4L2_JPEG_MARKER_DHT jpeg-markers
-replace define V4L2_JPEG_MARKER_DQT jpeg-markers
-replace define V4L2_JPEG_MARKER_DRI jpeg-markers
-replace define V4L2_JPEG_MARKER_COM jpeg-markers
-replace define V4L2_JPEG_MARKER_APP jpeg-markers
-
-#V4L2 buffer flags
-replace define V4L2_BUF_FLAG_MAPPED buffer-flags
-replace define V4L2_BUF_FLAG_QUEUED buffer-flags
-replace define V4L2_BUF_FLAG_DONE buffer-flags
-replace define V4L2_BUF_FLAG_ERROR buffer-flags
-replace define V4L2_BUF_FLAG_KEYFRAME buffer-flags
-replace define V4L2_BUF_FLAG_PFRAME buffer-flags
-replace define V4L2_BUF_FLAG_BFRAME buffer-flags
-replace define V4L2_BUF_FLAG_TIMECODE buffer-flags
-replace define V4L2_BUF_FLAG_PREPARED buffer-flags
-replace define V4L2_BUF_FLAG_NO_CACHE_INVALIDATE buffer-flags
-replace define V4L2_BUF_FLAG_NO_CACHE_CLEAN buffer-flags
-replace define V4L2_BUF_FLAG_TIMESTAMP_MASK buffer-flags
-replace define V4L2_BUF_FLAG_TIMESTAMP_UNKNOWN buffer-flags
-replace define V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC buffer-flags
-replace define V4L2_BUF_FLAG_TIMESTAMP_COPY buffer-flags
-replace define V4L2_BUF_FLAG_TSTAMP_SRC_MASK buffer-flags
-replace define V4L2_BUF_FLAG_TSTAMP_SRC_EOF buffer-flags
-replace define V4L2_BUF_FLAG_TSTAMP_SRC_SOE buffer-flags
-replace define V4L2_BUF_FLAG_LAST buffer-flags-FIXME
-
-# V4L2 framebuffer caps and flags
-
-replace define V4L2_FBUF_CAP_EXTERNOVERLAY framebuffer-cap
-replace define V4L2_FBUF_CAP_CHROMAKEY framebuffer-cap
-replace define V4L2_FBUF_CAP_LIST_CLIPPING framebuffer-cap
-replace define V4L2_FBUF_CAP_BITMAP_CLIPPING framebuffer-cap
-replace define V4L2_FBUF_CAP_LOCAL_ALPHA framebuffer-cap
-replace define V4L2_FBUF_CAP_GLOBAL_ALPHA framebuffer-cap
-replace define V4L2_FBUF_CAP_LOCAL_INV_ALPHA framebuffer-cap
-replace define V4L2_FBUF_CAP_SRC_CHROMAKEY framebuffer-cap
-
-replace define V4L2_FBUF_FLAG_PRIMARY framebuffer-flags
-replace define V4L2_FBUF_FLAG_OVERLAY framebuffer-flags
-replace define V4L2_FBUF_FLAG_CHROMAKEY framebuffer-flags
-replace define V4L2_FBUF_FLAG_LOCAL_ALPHA framebuffer-flags
-replace define V4L2_FBUF_FLAG_GLOBAL_ALPHA framebuffer-flags
-replace define V4L2_FBUF_FLAG_LOCAL_INV_ALPHA framebuffer-flags
-replace define V4L2_FBUF_FLAG_SRC_CHROMAKEY framebuffer-flags
-
-# Used on VIDIOC_G_PARM
-
-replace define V4L2_MODE_HIGHQUALITY parm-flags
-replace define V4L2_CAP_TIMEPERFRAME v4l2-captureparm
-
-# The V4L2_STD_foo are all defined at v4l2_std_id table
-
-replace define V4L2_STD_PAL_B v4l2-std-id
-replace define V4L2_STD_PAL_B1 v4l2-std-id
-replace define V4L2_STD_PAL_G v4l2-std-id
-replace define V4L2_STD_PAL_H v4l2-std-id
-replace define V4L2_STD_PAL_I v4l2-std-id
-replace define V4L2_STD_PAL_D v4l2-std-id
-replace define V4L2_STD_PAL_D1 v4l2-std-id
-replace define V4L2_STD_PAL_K v4l2-std-id
-replace define V4L2_STD_PAL_M v4l2-std-id
-replace define V4L2_STD_PAL_N v4l2-std-id
-replace define V4L2_STD_PAL_Nc v4l2-std-id
-replace define V4L2_STD_PAL_60 v4l2-std-id
-replace define V4L2_STD_NTSC_M v4l2-std-id
-replace define V4L2_STD_NTSC_M_JP v4l2-std-id
-replace define V4L2_STD_NTSC_443 v4l2-std-id
-replace define V4L2_STD_NTSC_M_KR v4l2-std-id
-replace define V4L2_STD_SECAM_B v4l2-std-id
-replace define V4L2_STD_SECAM_D v4l2-std-id
-replace define V4L2_STD_SECAM_G v4l2-std-id
-replace define V4L2_STD_SECAM_H v4l2-std-id
-replace define V4L2_STD_SECAM_K v4l2-std-id
-replace define V4L2_STD_SECAM_K1 v4l2-std-id
-replace define V4L2_STD_SECAM_L v4l2-std-id
-replace define V4L2_STD_SECAM_LC v4l2-std-id
-replace define V4L2_STD_ATSC_8_VSB v4l2-std-id
-replace define V4L2_STD_ATSC_16_VSB v4l2-std-id
-replace define V4L2_STD_NTSC v4l2-std-id
-replace define V4L2_STD_SECAM_DK v4l2-std-id
-replace define V4L2_STD_SECAM v4l2-std-id
-replace define V4L2_STD_PAL_BG v4l2-std-id
-replace define V4L2_STD_PAL_DK v4l2-std-id
-replace define V4L2_STD_PAL v4l2-std-id
-replace define V4L2_STD_B v4l2-std-id
-replace define V4L2_STD_G v4l2-std-id
-replace define V4L2_STD_H v4l2-std-id
-replace define V4L2_STD_L v4l2-std-id
-replace define V4L2_STD_GH v4l2-std-id
-replace define V4L2_STD_DK v4l2-std-id
-replace define V4L2_STD_BG v4l2-std-id
-replace define V4L2_STD_MN v4l2-std-id
-replace define V4L2_STD_MTS v4l2-std-id
-replace define V4L2_STD_525_60 v4l2-std-id
-replace define V4L2_STD_625_50 v4l2-std-id
-replace define V4L2_STD_ATSC v4l2-std-id
-replace define V4L2_STD_UNKNOWN v4l2-std-id
-replace define V4L2_STD_ALL v4l2-std-id
-
-# V4L2 DT BT timings definitions
-
-replace define V4L2_DV_PROGRESSIVE v4l2-dv-fixme
-replace define V4L2_DV_INTERLACED v4l2-dv-fixme
-
-replace define V4L2_DV_VSYNC_POS_POL v4l2-bt-timings
-replace define V4L2_DV_HSYNC_POS_POL v4l2-bt-timings
-
-replace define V4L2_DV_BT_STD_CEA861 dv-bt-standards
-replace define V4L2_DV_BT_STD_DMT dv-bt-standards
-replace define V4L2_DV_BT_STD_CVT dv-bt-standards
-replace define V4L2_DV_BT_STD_GTF dv-bt-standards
-
-replace define V4L2_DV_FL_REDUCED_BLANKING dv-bt-standards
-replace define V4L2_DV_FL_CAN_REDUCE_FPS dv-bt-standards
-replace define V4L2_DV_FL_REDUCED_FPS dv-bt-standards
-replace define V4L2_DV_FL_HALF_LINE dv-bt-standards
-replace define V4L2_DV_FL_IS_CE_VIDEO dv-bt-standards
-
-replace define V4L2_DV_BT_656_1120 dv-timing-types
-
-replace define V4L2_DV_BT_CAP_INTERLACED framebuffer-cap
-replace define V4L2_DV_BT_CAP_PROGRESSIVE framebuffer-cap
-replace define V4L2_DV_BT_CAP_REDUCED_BLANKING framebuffer-cap
-replace define V4L2_DV_BT_CAP_CUSTOM framebuffer-cap
-
-# V4L2 input
-
-replace define V4L2_INPUT_TYPE_TUNER input-type
-replace define V4L2_INPUT_TYPE_CAMERA input-type
-
-replace define V4L2_IN_ST_NO_POWER input-status
-replace define V4L2_IN_ST_NO_SIGNAL input-status
-replace define V4L2_IN_ST_NO_COLOR input-status
-replace define V4L2_IN_ST_HFLIP input-status
-replace define V4L2_IN_ST_VFLIP input-status
-replace define V4L2_IN_ST_NO_H_LOCK input-status
-replace define V4L2_IN_ST_COLOR_KILL input-status
-replace define V4L2_IN_ST_NO_SYNC input-status
-replace define V4L2_IN_ST_NO_EQU input-status
-replace define V4L2_IN_ST_NO_CARRIER input-status
-replace define V4L2_IN_ST_MACROVISION input-status
-replace define V4L2_IN_ST_NO_ACCESS input-status
-replace define V4L2_IN_ST_VTR input-status
-
-replace define V4L2_IN_CAP_DV_TIMINGS input-capabilities
-replace define V4L2_IN_CAP_STD input-capabilities
-replace define V4L2_IN_CAP_NATIVE_SIZE input-capabilities
-
-# V4L2 output
-
-replace define V4L2_OUTPUT_TYPE_MODULATOR output-type
-replace define V4L2_OUTPUT_TYPE_ANALOG output-type
-replace define V4L2_OUTPUT_TYPE_ANALOGVGAOVERLAY output-type
-
-replace define V4L2_OUT_CAP_DV_TIMINGS output-capabilities
-replace define V4L2_OUT_CAP_STD output-capabilities
-replace define V4L2_OUT_CAP_NATIVE_SIZE output-capabilities
-
-# V4L2 control flags
-
-replace define V4L2_CTRL_FLAG_DISABLED control-flags
-replace define V4L2_CTRL_FLAG_GRABBED control-flags
-replace define V4L2_CTRL_FLAG_READ_ONLY control-flags
-replace define V4L2_CTRL_FLAG_UPDATE control-flags
-replace define V4L2_CTRL_FLAG_INACTIVE control-flags
-replace define V4L2_CTRL_FLAG_SLIDER control-flags
-replace define V4L2_CTRL_FLAG_WRITE_ONLY control-flags
-replace define V4L2_CTRL_FLAG_VOLATILE control-flags
-replace define V4L2_CTRL_FLAG_HAS_PAYLOAD control-flags
-replace define V4L2_CTRL_FLAG_EXECUTE_ON_WRITE control-flags
-
-replace define V4L2_CTRL_FLAG_NEXT_CTRL control
-replace define V4L2_CTRL_FLAG_NEXT_COMPOUND control
-replace define V4L2_CID_PRIVATE_BASE control
-
-# V4L2 tuner
-
-replace define V4L2_TUNER_CAP_LOW tuner-capability
-replace define V4L2_TUNER_CAP_NORM tuner-capability
-replace define V4L2_TUNER_CAP_HWSEEK_BOUNDED tuner-capability
-replace define V4L2_TUNER_CAP_HWSEEK_WRAP tuner-capability
-replace define V4L2_TUNER_CAP_STEREO tuner-capability
-replace define V4L2_TUNER_CAP_LANG2 tuner-capability
-replace define V4L2_TUNER_CAP_SAP tuner-capability
-replace define V4L2_TUNER_CAP_LANG1 tuner-capability
-replace define V4L2_TUNER_CAP_RDS tuner-capability
-replace define V4L2_TUNER_CAP_RDS_BLOCK_IO tuner-capability
-replace define V4L2_TUNER_CAP_RDS_CONTROLS tuner-capability
-replace define V4L2_TUNER_CAP_FREQ_BANDS tuner-capability
-replace define V4L2_TUNER_CAP_HWSEEK_PROG_LIM tuner-capability
-replace define V4L2_TUNER_CAP_1HZ tuner-capability
-
-replace define V4L2_TUNER_SUB_MONO tuner-rxsubchans
-replace define V4L2_TUNER_SUB_STEREO tuner-rxsubchans
-replace define V4L2_TUNER_SUB_LANG2 tuner-rxsubchans
-replace define V4L2_TUNER_SUB_SAP tuner-rxsubchans
-replace define V4L2_TUNER_SUB_LANG1 tuner-rxsubchans
-replace define V4L2_TUNER_SUB_RDS tuner-rxsubchans
-
-replace define V4L2_TUNER_MODE_MONO tuner-audmode
-replace define V4L2_TUNER_MODE_STEREO tuner-audmode
-replace define V4L2_TUNER_MODE_LANG2 tuner-audmode
-replace define V4L2_TUNER_MODE_SAP tuner-audmode
-replace define V4L2_TUNER_MODE_LANG1 tuner-audmode
-replace define V4L2_TUNER_MODE_LANG1_LANG2 tuner-audmode
-
-replace define V4L2_BAND_MODULATION_VSB band-modulation
-replace define V4L2_BAND_MODULATION_FM band-modulation
-replace define V4L2_BAND_MODULATION_AM band-modulation
-
-replace define V4L2_RDS_BLOCK_MSK v4l2-rds-block
-replace define V4L2_RDS_BLOCK_A v4l2-rds-block
-replace define V4L2_RDS_BLOCK_B v4l2-rds-block
-replace define V4L2_RDS_BLOCK_C v4l2-rds-block
-replace define V4L2_RDS_BLOCK_D v4l2-rds-block
-replace define V4L2_RDS_BLOCK_C_ALT v4l2-rds-block
-replace define V4L2_RDS_BLOCK_INVALID v4l2-rds-block
-replace define V4L2_RDS_BLOCK_CORRECTED v4l2-rds-block
-replace define V4L2_RDS_BLOCK_ERROR v4l2-rds-block
-
-# V4L2 audio
-
-replace define V4L2_AUDCAP_STEREO audio-capability
-replace define V4L2_AUDCAP_AVL audio-capability
-
-replace define V4L2_AUDMODE_AVL audio-mode
-
-# MPEG
-
-replace define V4L2_ENC_IDX_FRAME_I v4l2-enc-idx
-replace define V4L2_ENC_IDX_FRAME_P v4l2-enc-idx
-replace define V4L2_ENC_IDX_FRAME_B v4l2-enc-idx
-replace define V4L2_ENC_IDX_FRAME_MASK v4l2-enc-idx
-replace define V4L2_ENC_IDX_ENTRIES v4l2-enc-idx
-
-replace define V4L2_ENC_CMD_START encoder-cmds
-replace define V4L2_ENC_CMD_STOP encoder-cmds
-replace define V4L2_ENC_CMD_PAUSE encoder-cmds
-replace define V4L2_ENC_CMD_RESUME encoder-cmds
-
-replace define V4L2_ENC_CMD_STOP_AT_GOP_END encoder-flags
-
-replace define V4L2_DEC_CMD_START decoder-cmds
-replace define V4L2_DEC_CMD_STOP decoder-cmds
-replace define V4L2_DEC_CMD_PAUSE decoder-cmds
-replace define V4L2_DEC_CMD_RESUME decoder-cmds
-
-replace define V4L2_DEC_CMD_START_MUTE_AUDIO decoder-cmds
-replace define V4L2_DEC_CMD_PAUSE_TO_BLACK decoder-cmds
-replace define V4L2_DEC_CMD_STOP_TO_BLACK decoder-cmds
-replace define V4L2_DEC_CMD_STOP_IMMEDIATELY decoder-cmds
-
-replace define V4L2_DEC_START_FMT_NONE decoder-cmds
-replace define V4L2_DEC_START_FMT_GOP decoder-cmds
-
-# V4L2 VBI
-
-replace define V4L2_VBI_UNSYNC vbifmt-flags
-replace define V4L2_VBI_INTERLACED vbifmt-flags
-
-replace define V4L2_VBI_ITU_525_F1_START v4l2-vbi-format
-replace define V4L2_VBI_ITU_525_F2_START v4l2-vbi-format
-replace define V4L2_VBI_ITU_625_F1_START v4l2-vbi-format
-replace define V4L2_VBI_ITU_625_F2_START v4l2-vbi-format
-
-
-replace define V4L2_SLICED_TELETEXT_B vbi-services
-replace define V4L2_SLICED_VPS vbi-services
-replace define V4L2_SLICED_CAPTION_525 vbi-services
-replace define V4L2_SLICED_WSS_625 vbi-services
-replace define V4L2_SLICED_VBI_525 vbi-services
-replace define V4L2_SLICED_VBI_625 vbi-services
-
-replace define V4L2_MPEG_VBI_IVTV_TELETEXT_B ITV0-Line-Identifier-Constants
-replace define V4L2_MPEG_VBI_IVTV_CAPTION_525 ITV0-Line-Identifier-Constants
-replace define V4L2_MPEG_VBI_IVTV_WSS_625 ITV0-Line-Identifier-Constants
-replace define V4L2_MPEG_VBI_IVTV_VPS ITV0-Line-Identifier-Constants
-
-replace define V4L2_MPEG_VBI_IVTV_MAGIC0 v4l2-mpeg-vbi-fmt-ivtv-magic
-replace define V4L2_MPEG_VBI_IVTV_MAGIC1 v4l2-mpeg-vbi-fmt-ivtv-magic
-
-# V4L2 events
-
-replace define V4L2_EVENT_ALL event-type
-replace define V4L2_EVENT_VSYNC event-type
-replace define V4L2_EVENT_EOS event-type
-replace define V4L2_EVENT_CTRL event-type
-replace define V4L2_EVENT_FRAME_SYNC event-type
-replace define V4L2_EVENT_SOURCE_CHANGE event-type
-replace define V4L2_EVENT_MOTION_DET event-type
-replace define V4L2_EVENT_PRIVATE_START event-type
-
-replace define V4L2_EVENT_CTRL_CH_VALUE ctrl-changes-flags
-replace define V4L2_EVENT_CTRL_CH_FLAGS ctrl-changes-flags
-replace define V4L2_EVENT_CTRL_CH_RANGE ctrl-changes-flags
-
-replace define V4L2_EVENT_SRC_CH_RESOLUTION src-changes-flags
-
-replace define V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ v4l2-event-motion-det
-
-replace define V4L2_EVENT_SUB_FL_SEND_INITIAL event-flags
-replace define V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK event-flags
-
-# V4L2 debugging
-replace define V4L2_CHIP_MATCH_BRIDGE vidioc_dbg_g_register
-replace define V4L2_CHIP_MATCH_SUBDEV vidioc_dbg_g_register
-replace define V4L2_CHIP_MATCH_HOST vidioc_dbg_g_register
-replace define V4L2_CHIP_MATCH_I2C_DRIVER vidioc_dbg_g_register
-replace define V4L2_CHIP_MATCH_I2C_ADDR vidioc_dbg_g_register
-replace define V4L2_CHIP_MATCH_AC97 vidioc_dbg_g_register
-
-replace define V4L2_CHIP_FL_READABLE vidioc_dbg_g_register
-replace define V4L2_CHIP_FL_WRITABLE vidioc_dbg_g_register
-
-# Ignore reserved ioctl and ancillary macros
-
-ignore define VIDEO_MAX_FRAME
-ignore define VIDEO_MAX_PLANES
-ignore define v4l2_fourcc
-ignore define v4l2_fourcc_be
-ignore define V4L2_FIELD_HAS_TOP
-ignore define V4L2_FIELD_HAS_BOTTOM
-ignore define V4L2_FIELD_HAS_BOTH
-ignore define V4L2_FIELD_HAS_T_OR_B
-ignore define V4L2_TYPE_IS_MULTIPLANAR
-ignore define V4L2_TYPE_IS_OUTPUT
-ignore define V4L2_TUNER_ADC
-ignore define V4L2_MAP_COLORSPACE_DEFAULT
-ignore define V4L2_MAP_XFER_FUNC_DEFAULT
-ignore define V4L2_MAP_YCBCR_ENC_DEFAULT
-ignore define V4L2_DV_BT_BLANKING_WIDTH
-ignore define V4L2_DV_BT_FRAME_WIDTH
-ignore define V4L2_DV_BT_BLANKING_HEIGHT
-ignore define V4L2_DV_BT_FRAME_HEIGHT
-ignore define V4L2_IN_CAP_CUSTOM_TIMINGS
-ignore define V4L2_CTRL_ID_MASK
-ignore define V4L2_CTRL_ID2CLASS
-ignore define V4L2_CTRL_ID2WHICH
-ignore define V4L2_CTRL_DRIVER_PRIV
-ignore define V4L2_CTRL_MAX_DIMS
-ignore define V4L2_CTRL_WHICH_CUR_VAL
-ignore define V4L2_CTRL_WHICH_DEF_VAL
-ignore define V4L2_OUT_CAP_CUSTOM_TIMINGS
-ignore define V4L2_CID_MAX_CTRLS
-
-ignore ioctl VIDIOC_RESERVED
-ignore define BASE_VIDIOC_PRIVATE
-
-# Associate ioctls with their counterparts
-replace ioctl VIDIOC_DBG_S_REGISTER vidioc_dbg_g_register
-replace ioctl VIDIOC_DQBUF vidioc_qbuf
-replace ioctl VIDIOC_S_AUDOUT vidioc_g_audout
-replace ioctl VIDIOC_S_CROP vidioc_g_crop
-replace ioctl VIDIOC_S_CTRL vidioc_g_ctrl
-replace ioctl VIDIOC_S_DV_TIMINGS vidioc_g_dv_timings
-replace ioctl VIDIOC_S_EDID vidioc_g_edid
-replace ioctl VIDIOC_S_EXT_CTRLS vidioc_g_ext_ctrls
-replace ioctl VIDIOC_S_FBUF vidioc_g_fbuf
-replace ioctl VIDIOC_S_FMT vidioc_g_fmt
-replace ioctl VIDIOC_S_FREQUENCY vidioc_g_frequency
-replace ioctl VIDIOC_S_INPUT vidioc_g_input
-replace ioctl VIDIOC_S_JPEGCOMP vidioc_g_jpegcomp
-replace ioctl VIDIOC_S_MODULATOR vidioc_g_modulator
-replace ioctl VIDIOC_S_OUTPUT vidioc_g_output
-replace ioctl VIDIOC_S_PARM vidioc_g_parm
-replace ioctl VIDIOC_S_PRIORITY vidioc_g_priority
-replace ioctl VIDIOC_S_SELECTION vidioc_g_selection
-replace ioctl VIDIOC_S_STD vidioc_g_std
-replace ioctl VIDIOC_S_AUDIO vidioc_g_audio
-replace ioctl VIDIOC_S_TUNER vidioc_g_tuner
-replace ioctl VIDIOC_TRY_DECODER_CMD vidioc_decoder_cmd
-replace ioctl VIDIOC_TRY_ENCODER_CMD vidioc_encoder_cmd
-replace ioctl VIDIOC_TRY_EXT_CTRLS vidioc_g_ext_ctrls
-replace ioctl VIDIOC_TRY_FMT vidioc_g_fmt
-replace ioctl VIDIOC_STREAMOFF vidioc_streamon
-replace ioctl VIDIOC_UNSUBSCRIBE_EVENT vidioc_subscribe_event
-replace ioctl VIDIOC_QUERY_EXT_CTRL vidioc_queryctrl
-replace ioctl VIDIOC_QUERYMENU vidioc_queryctrl
--- /dev/null
+# Generate the *.h.rst files from uAPI headers
+
+PARSER = $(srctree)/Documentation/sphinx/parse-headers.pl
+UAPI = $(srctree)/include/uapi/linux
+SRC_DIR=$(srctree)/Documentation/media
+
+FILES = audio.h.rst ca.h.rst dmx.h.rst frontend.h.rst net.h.rst video.h.rst \
+ videodev2.h.rst
+
+TARGETS := $(addprefix $(BUILDDIR)/, $(FILES))
+
+htmldocs: $(BUILDDIR) ${TARGETS}
+
+$(BUILDDIR):
+ $(Q)mkdir -p $@
+
+# Rule to convert a .h file to inline RST documentation
+
+gen_rst = \
+ echo ${PARSER} $< $@ $(SRC_DIR)/$(notdir $@).exceptions; \
+ ${PARSER} $< $@ $(SRC_DIR)/$(notdir $@).exceptions
+
+quiet_gen_rst = echo ' PARSE $(patsubst $(srctree)/%,%,$<)'; \
+ ${PARSER} $< $@ $(SRC_DIR)/$(notdir $@).exceptions
+
+silent_gen_rst = ${gen_rst}
+
+$(BUILDDIR)/audio.h.rst: ${UAPI}/dvb/audio.h ${PARSER} $(SRC_DIR)/audio.h.rst.exceptions
+ @$($(quiet)gen_rst)
+
+$(BUILDDIR)/ca.h.rst: ${UAPI}/dvb/ca.h ${PARSER} $(SRC_DIR)/ca.h.rst.exceptions
+ @$($(quiet)gen_rst)
+
+$(BUILDDIR)/dmx.h.rst: ${UAPI}/dvb/dmx.h ${PARSER} $(SRC_DIR)/dmx.h.rst.exceptions
+ @$($(quiet)gen_rst)
+
+$(BUILDDIR)/frontend.h.rst: ${UAPI}/dvb/frontend.h ${PARSER} $(SRC_DIR)/frontend.h.rst.exceptions
+ @$($(quiet)gen_rst)
+
+$(BUILDDIR)/net.h.rst: ${UAPI}/dvb/net.h ${PARSER} $(SRC_DIR)/net.h.rst.exceptions
+ @$($(quiet)gen_rst)
+
+$(BUILDDIR)/video.h.rst: ${UAPI}/dvb/video.h ${PARSER} $(SRC_DIR)/video.h.rst.exceptions
+ @$($(quiet)gen_rst)
+
+$(BUILDDIR)/videodev2.h.rst: ${UAPI}/videodev2.h ${PARSER} $(SRC_DIR)/videodev2.h.rst.exceptions
+ @$($(quiet)gen_rst)
+
+cleandocs:
+ -rm ${TARGETS}
--- /dev/null
+# Ignore header name
+ignore define _DVBAUDIO_H_
+
+# Typedef pointing to structs
+replace typedef audio_karaoke_t audio-karaoke
+
+# Undocumented audio caps, as this is a deprecated API anyway
+ignore define AUDIO_CAP_DTS
+ignore define AUDIO_CAP_LPCM
+ignore define AUDIO_CAP_MP1
+ignore define AUDIO_CAP_MP2
+ignore define AUDIO_CAP_MP3
+ignore define AUDIO_CAP_AAC
+ignore define AUDIO_CAP_OGG
+ignore define AUDIO_CAP_SDDS
+ignore define AUDIO_CAP_AC3
+
+# some typedefs should point to struct/enums
+replace typedef audio_mixer_t audio-mixer
+replace typedef audio_status_t audio-status
--- /dev/null
+# Ignore header name
+ignore define _DVBCA_H_
+
+# struct ca_slot_info defines
+replace define CA_CI ca-slot-info
+replace define CA_CI_LINK ca-slot-info
+replace define CA_CI_PHYS ca-slot-info
+replace define CA_DESCR ca-slot-info
+replace define CA_SC ca-slot-info
+replace define CA_CI_MODULE_PRESENT ca-slot-info
+replace define CA_CI_MODULE_READY ca-slot-info
+
+# struct ca_descr_info defines
+replace define CA_ECD ca-descr-info
+replace define CA_NDS ca-descr-info
+replace define CA_DSS ca-descr-info
+
+# some typedefs should point to struct/enums
+replace typedef ca_pid_t ca-pid
+replace typedef ca_slot_info_t ca-slot-info
+replace typedef ca_descr_info_t ca-descr-info
+replace typedef ca_caps_t ca-caps
+replace typedef ca_msg_t ca-msg
+replace typedef ca_descr_t ca-descr
--- /dev/null
+# Ignore header name
+ignore define _UAPI_DVBDMX_H_
+
+# Ignore limit constants
+ignore define DMX_FILTER_SIZE
+
+# dmx-pes-type-t enum symbols
+replace enum dmx_ts_pes dmx-pes-type-t
+replace symbol DMX_PES_AUDIO0 dmx-pes-type-t
+replace symbol DMX_PES_VIDEO0 dmx-pes-type-t
+replace symbol DMX_PES_TELETEXT0 dmx-pes-type-t
+replace symbol DMX_PES_SUBTITLE0 dmx-pes-type-t
+replace symbol DMX_PES_PCR0 dmx-pes-type-t
+replace symbol DMX_PES_AUDIO1 dmx-pes-type-t
+replace symbol DMX_PES_VIDEO1 dmx-pes-type-t
+replace symbol DMX_PES_TELETEXT1 dmx-pes-type-t
+replace symbol DMX_PES_SUBTITLE1 dmx-pes-type-t
+replace symbol DMX_PES_PCR1 dmx-pes-type-t
+replace symbol DMX_PES_AUDIO2 dmx-pes-type-t
+replace symbol DMX_PES_VIDEO2 dmx-pes-type-t
+replace symbol DMX_PES_TELETEXT2 dmx-pes-type-t
+replace symbol DMX_PES_SUBTITLE2 dmx-pes-type-t
+replace symbol DMX_PES_PCR2 dmx-pes-type-t
+replace symbol DMX_PES_AUDIO3 dmx-pes-type-t
+replace symbol DMX_PES_VIDEO3 dmx-pes-type-t
+replace symbol DMX_PES_TELETEXT3 dmx-pes-type-t
+replace symbol DMX_PES_SUBTITLE3 dmx-pes-type-t
+replace symbol DMX_PES_PCR3 dmx-pes-type-t
+replace symbol DMX_PES_OTHER dmx-pes-type-t
+
+# Ignore obsolete symbols
+ignore define DMX_PES_AUDIO
+ignore define DMX_PES_VIDEO
+ignore define DMX_PES_TELETEXT
+ignore define DMX_PES_SUBTITLE
+ignore define DMX_PES_PCR
+
+# dmx_input_t symbols
+replace enum dmx_input dmx-input-t
+replace symbol DMX_IN_FRONTEND dmx-input-t
+replace symbol DMX_IN_DVR dmx-input-t
+
+# dmx_source_t symbols
+replace enum dmx_source dmx-source-t
+replace symbol DMX_SOURCE_FRONT0 dmx-source-t
+replace symbol DMX_SOURCE_FRONT1 dmx-source-t
+replace symbol DMX_SOURCE_FRONT2 dmx-source-t
+replace symbol DMX_SOURCE_FRONT3 dmx-source-t
+replace symbol DMX_SOURCE_DVR0 dmx-source-t
+replace symbol DMX_SOURCE_DVR1 dmx-source-t
+replace symbol DMX_SOURCE_DVR2 dmx-source-t
+replace symbol DMX_SOURCE_DVR3 dmx-source-t
+
+
+# Flags for struct dmx_sct_filter_params
+replace define DMX_CHECK_CRC dmx-sct-filter-params
+replace define DMX_ONESHOT dmx-sct-filter-params
+replace define DMX_IMMEDIATE_START dmx-sct-filter-params
+replace define DMX_KERNEL_CLIENT dmx-sct-filter-params
+
+# some typedefs should point to struct/enums
+replace typedef dmx_caps_t dmx-caps
+replace typedef dmx_filter_t dmx-filter
--- /dev/null
+# Ignore header name
+ignore define _DVBFRONTEND_H_
+
+# Group layer A-C symbols together
+replace define DTV_ISDBT_LAYERA_FEC dtv-isdbt-layer-fec
+replace define DTV_ISDBT_LAYERB_FEC dtv-isdbt-layer-fec
+replace define DTV_ISDBT_LAYERC_FEC dtv-isdbt-layer-fec
+replace define DTV_ISDBT_LAYERA_MODULATION dtv-isdbt-layer-modulation
+replace define DTV_ISDBT_LAYERB_MODULATION dtv-isdbt-layer-modulation
+replace define DTV_ISDBT_LAYERC_MODULATION dtv-isdbt-layer-modulation
+replace define DTV_ISDBT_LAYERA_SEGMENT_COUNT dtv-isdbt-layer-segment-count
+replace define DTV_ISDBT_LAYERB_SEGMENT_COUNT dtv-isdbt-layer-segment-count
+replace define DTV_ISDBT_LAYERC_SEGMENT_COUNT dtv-isdbt-layer-segment-count
+replace define DTV_ISDBT_LAYERA_TIME_INTERLEAVING dtv-isdbt-layer-time-interleaving
+replace define DTV_ISDBT_LAYERB_TIME_INTERLEAVING dtv-isdbt-layer-time-interleaving
+replace define DTV_ISDBT_LAYERC_TIME_INTERLEAVING dtv-isdbt-layer-time-interleaving
+
+# Ignore legacy defines
+ignore define DTV_ISDBS_TS_ID_LEGACY
+ignore define SYS_DVBC_ANNEX_AC
+ignore define SYS_DMBTH
+
+# Ignore limits
+ignore define DTV_MAX_COMMAND
+ignore define MAX_DTV_STATS
+ignore define DTV_IOCTL_MAX_MSGS
+
+# Stats enum is documented altogether
+replace enum fecap_scale_params frontend-stat-properties
+replace symbol FE_SCALE_COUNTER frontend-stat-properties
+replace symbol FE_SCALE_DECIBEL frontend-stat-properties
+replace symbol FE_SCALE_NOT_AVAILABLE frontend-stat-properties
+replace symbol FE_SCALE_RELATIVE frontend-stat-properties
+
+# the same reference is used for both get and set ioctls
+replace ioctl FE_SET_PROPERTY FE_GET_PROPERTY
+
+# Ignore struct used only internally at Kernel
+ignore struct dtv_cmds_h
+
+# Typedefs that use the enum reference
+replace typedef fe_sec_voltage_t fe-sec-voltage
+
+# Replaces for flag constants
+replace define FE_TUNE_MODE_ONESHOT fe_set_frontend_tune_mode
+replace define LNA_AUTO dtv-lna
+replace define NO_STREAM_ID_FILTER dtv-stream-id
--- /dev/null
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg stroke-linejoin="round" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns="http://www.w3.org/2000/svg" clip-path="url(#a)" xml:space="preserve" fill-rule="evenodd" height="178.78mm" viewBox="0 0 24285.662 17877.829" width="251.99mm" version="1.2" xmlns:cc="http://creativecommons.org/ns#" xmlns:dc="http://purl.org/dc/elements/1.1/" preserveAspectRatio="xMidYMid" stroke-width="28.222"><defs><clipPath id="a" clipPathUnits="userSpaceOnUse"><rect y="0" x="0" width="28000" height="21000"/></clipPath></defs><g transform="matrix(1.004 0 0 1 -2185.6 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#fcf" d="m12231 4800c-516 0-1031 515-1031 1031v4124c0 516 515 1032 1031 1032h8538c516 0 1032-516 1032-1032v-4124c0-516-516-1031-1032-1031h-8538z"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#ffc" d="m3595 15607c-293 0-585 292-585 585v2340c0 293 292 586 585 586h3275c293 0 586-293 586-586v-2340c0-293-293-585-586-585h-3275z"/></g><g transform="translate(-2197.3 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#e6e6e6" d="m2663 2186c-461 0-922 461-922 922v11169c0 461 461 923 922 923h3692c461 0 922-462 922-923v-11169c0-461-461-922-922-922h-3692z"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.RectangleShape"><path fill="#ff8080" d="m4461 8602h-2260v-1086h4520v1086h-2260z"/><path fill="none" d="m4461 8602h-2260v-1086h4520v1086h-2260z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="8275" x="2579" class="TextPosition"><tspan fill="#000000">Audio decoder</tspan></tspan></tspan></text>
+</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.RectangleShape"><path fill="#ff8080" d="m4461 11772h-2260v-1270h4520v1270h-2260z"/><path fill="none" d="m4461 11772h-2260v-1270h4520v1270h-2260z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="11353" x="2617" class="TextPosition"><tspan fill="#000000">Video decoder</tspan></tspan></tspan></text>
+</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.RectangleShape"><path fill="#ff8080" d="m4453 10217h-2269v-1224h4537v1224h-2268z"/><path fill="none" d="m4453 10217h-2269v-1224h4537v1224h-2268z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="9821" x="2571" class="TextPosition"><tspan fill="#000000">Audio encoder</tspan></tspan></tspan></text>
+</g><g transform="translate(-2140.9 -2468.2)" class="com.sun.star.drawing.RectangleShape"><path fill="#cfc" d="m15711 12832h-3810v-1281h7620v1281h-3810z"/><path fill="none" d="m15711 12832h-3810v-1281h7620v1281h-3810z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="12407" x="12377" class="TextPosition"><tspan fill="#000000">Button Key/IR input logic</tspan></tspan></tspan></text>
+</g><g transform="translate(-2140.9 -2411.8)" class="com.sun.star.drawing.RectangleShape"><path fill="#cfe7f5" d="m14169 14572h-2268v-1412h4536v1412h-2268z"/><path fill="none" d="m14169 14572h-2268v-1412h4536v1412h-2268z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="14082" x="12882" class="TextPosition"><tspan fill="#000000">EEPROM</tspan></tspan></tspan></text>
+</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.RectangleShape"><path fill="#fc9" d="m5140 17662h-1563v-1715h3126v1715h-1563z"/><path fill="none" d="m5140 17662h-1563v-1715h3126v1715h-1563z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="17020" x="4276" class="TextPosition"><tspan fill="#000000">Sensor</tspan></tspan></tspan></text>
+</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m6719 8030 385-353v176h1167v-176l386 353-386 354v-177h-1167v177l-385-354z"/><path fill="none" d="m6719 8030 385-353v176h1167v-176l386 353-386 354v-177h-1167v177l-385-354z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m6719 9612 385-353v176h1167v-176l386 353-386 354v-177h-1167v177l-385-354z"/><path fill="none" d="m6719 9612 385-353v176h1167v-176l386 353-386 354v-177h-1167v177l-385-354z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m6721 11100 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z"/><path fill="none" d="m6721 11100 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2411.8)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m9962 13854 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z"/><path fill="none" d="m9962 13854 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2468.2)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m9962 12163 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z"/><path fill="none" d="m9962 12163 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m9962 17158 670-353v176h2028v-176l671 353-671 354v-177h-2028v177l-670-354z"/><path fill="none" d="m9962 17158 670-353v176h2028v-176l671 353-671 354v-177h-2028v177l-670-354z" stroke="#3465af"/></g><g transform="matrix(0 .83339 -1.0005 0 30268 -5276.3)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m23229 12779 1009-978 1009 978h-505v2959h505l-1009 979-1009-979h504v-2959h-504z"/><path fill="none" d="m23229 12779 1009-978 1009 978h-505v2959h505l-1009 979-1009-979h504v-2959h-504z" stroke="#3465af"/></g><g transform="translate(-9973.6 -666.6)" class="com.sun.star.drawing.TextShape"><text class="TextShape"><tspan font-size="706px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="15832" x="24341" class="TextPosition" transform="matrix(0,-1,1,0,8509,40173)"><tspan fill="#000000">System Bus</tspan></tspan></tspan></text>
+</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.RectangleShape"><path fill="#cff" d="m13151 9262h-1250v-875h2499v875h-1249z"/><path fill="none" d="m13151 9262h-1250v-875h2499v875h-1249z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="9040" x="12215" class="TextPosition"><tspan fill="#000000">Demux</tspan></tspan></tspan></text>
+</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m9996 8765 373-357v178h1130v-178l374 357-374 358v-179h-1130v179l-373-358z"/><path fill="none" d="m9996 8765 373-357v178h1130v-178l374 357-374 358v-179h-1130v179l-373-358z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m9996 7378 373-358v179h1130v-179l374 358-374 358v-179h-1130v179l-373-358z"/><path fill="none" d="m9996 7378 373-358v179h1130v-179l374 358-374 358v-179h-1130v179l-373-358z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.RectangleShape"><path fill="#cff" d="m16322 7992h-4421v-1270h8841v1270h-4420z"/><path fill="none" d="m16322 7992h-4421v-1270h8841v1270h-4420z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="7573" x="12786" class="TextPosition"><tspan fill="#000000">Conditional Access Module</tspan></tspan></tspan></text>
+</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.RectangleShape"><path fill="#ff8080" d="m4445 13287h-2269v-1224h4537v1224h-2268z"/><path fill="none" d="m4445 13287h-2269v-1224h4537v1224h-2268z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="12891" x="2601" class="TextPosition"><tspan fill="#000000">Video encoder</tspan></tspan></tspan></text>
+</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m6721 12634 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z"/><path fill="none" d="m6721 12634 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m20791 7545 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z"/><path fill="none" d="m20791 7545 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z" stroke="#3465af"/></g><g transform="translate(-2028 -2186)" class="com.sun.star.drawing.TextShape"><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="14478" x="1990" class="TextPosition"><tspan fill="#000000">Radio / Analog TV</tspan></tspan></tspan></text>
+</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.TextShape"><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="700" class="TextParagraph"><tspan y="10724" x="14956" class="TextPosition"><tspan fill="#000000">Digital TV</tspan></tspan></tspan></text>
+</g><g transform="translate(-8970.5 -1395.8)" class="com.sun.star.drawing.TextShape"><text class="TextShape"><tspan font-size="494px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="19167" x="14724" class="TextPosition"><tspan fill="#000000">PS.: picture is not complete: other blocks may be present</tspan></tspan></tspan></text>
+</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.TextShape"><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="18561" x="4199" class="TextPosition"><tspan fill="#000000">Webcam</tspan></tspan></tspan></text>
+</g><g transform="translate(-2140.9 -2468.2)" class="com.sun.star.drawing.RectangleShape"><path fill="#f90" d="m14552 16372h-2650v-1412h5299v1412h-2649z"/><path fill="none" d="m14552 16372h-2650v-1412h5299v1412h-2649z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="15882" x="12265" class="TextPosition"><tspan fill="#000000">Processing blocks</tspan></tspan></tspan></text>
+</g><g transform="translate(-2140.9 -2468.2)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m9962 15654 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z"/><path fill="none" d="m9962 15654 385-353v176h1166v-176l386 353-386 354v-177h-1166v177l-385-354z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m6702 16954 397-353v176h1201v-176l398 353-398 354v-177h-1201v177l-397-354z"/><path fill="none" d="m6702 16954 397-353v176h1201v-176l398 353-398 354v-177h-1201v177l-397-354z" stroke="#3465af"/></g><g transform="translate(-2479.5 -2186)" class="com.sun.star.drawing.TextShape"><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="8792" x="22850" class="TextPosition"><tspan fill="#000000">Smartcard</tspan></tspan></tspan></text>
+</g><g transform="matrix(1.0048 0 0 1 -2207.4 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#fcf" d="m2766 2600c-333 0-666 333-666 666v2668c0 333 333 666 666 666h18368c333 0 667-333 667-666v-2668c0-333-334-666-667-666h-18368z"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.RectangleShape"><path fill="#ff8080" d="m5121 5155h-1614v-1816h3227v1816h-1613z"/><path fill="none" d="m5121 5155h-1614v-1816h3227v1816h-1613z" stroke="#3465af"/><text font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextShape"><tspan class="TextParagraph"><tspan y="4111" x="4374" class="TextPosition"><tspan fill="#000000">Tuner</tspan></tspan></tspan><tspan class="TextParagraph"><tspan y="4814" x="4151" class="TextPosition"><tspan fill="#000000">FM/TV</tspan></tspan></tspan></text>
+</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#ff8080" d="m2902 3702c0 111 40 202 88 202h530c48 0 89-91 89-202 0-110-41-202-89-202h-530c-48 0-88 92-88 202z"/><path fill="none" d="m2902 3702c0 111 40 202 88 202h530c48 0 89-91 89-202 0-110-41-202-89-202h-530c-48 0-88 92-88 202z" stroke="#3465af"/><path fill="#ffb3b3" d="m2902 3702c0 111 40 202 88 202s88-91 88-202c0-110-40-202-88-202s-88 92-88 202z"/><path fill="none" d="m2902 3702c0 111 40 202 88 202s88-91 88-202c0-110-40-202-88-202s-88 92-88 202z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#ff8080" d="m2903 4267c0 110 40 202 88 202h530c48 0 89-92 89-202s-41-203-89-203h-530c-48 0-88 93-88 203z"/><path fill="none" d="m2903 4267c0 110 40 202 88 202h530c48 0 89-92 89-202s-41-203-89-203h-530c-48 0-88 93-88 203z" stroke="#3465af"/><path fill="#ffb3b3" d="m2903 4267c0 110 40 202 88 202s88-92 88-202-40-203-88-203-88 93-88 203z"/><path fill="none" d="m2903 4267c0 110 40 202 88 202s88-92 88-202-40-203-88-203-88 93-88 203z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m6719 4196 385-353v176h1167v-176l386 353-386 354v-177h-1167v177l-385-354z"/><path fill="none" d="m6719 4196 385-353v176h1167v-176l386 353-386 354v-177h-1167v177l-385-354z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m9979 4150 402-368v184h1217v-184l403 368-403 369v-185h-1217v185l-402-369z"/><path fill="none" d="m9979 4150 402-368v184h1217v-184l403 368-403 369v-185h-1217v185l-402-369z" stroke="#3465af"/></g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.RectangleShape"><path fill="#cff" d="m16500 6189h-4500v-1389h9e3v1389h-4500z"/><path fill="none" d="m16500 6189h-4500v-1389h9e3v1389h-4500z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="5710" x="12051" class="TextPosition"><tspan fill="#000000">Satellite Equipment Control (SEC)</tspan></tspan></tspan></text>
+</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#cff" d="m13400 4600h-1400v-1e3h2800v1e3h-1400z"/><path fill="none" d="m13400 4600h-1400v-1e3h2800v1e3h-1400z" stroke="#3465af"/><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="4316" x="12465" class="TextPosition"><tspan fill="#000000">Demod</tspan></tspan></tspan></text>
+</g><g transform="translate(-2140.9 -2186)" class="com.sun.star.drawing.CustomShape"><path fill="#729fcf" d="m9979 5451 402-368v184h1217v-184l403 368-403 369v-185h-1217v185l-402-369z"/><path fill="none" d="m9979 5451 402-368v184h1217v-184l403 368-403 369v-185h-1217v185l-402-369z" stroke="#3465af"/></g><path fill="#ff9" d="m7855.1 9099v7302h-1270v-14605h1270v7303z"/><path fill="none" d="m7855.1 9099v7302h-1270v-14605h1270v7303z" stroke="#3465af"/><text y="-6640.4663" x="-20770.572" transform="rotate(-90)" class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="7409.5396" x="-11193.634" class="TextPosition" transform="matrix(0,-1,1,0,-4473,23627)"><tspan fill="#000000">I2C Bus (control bus)</tspan></tspan></tspan></text>
+<g transform="translate(-2197.3 -2186)" class="com.sun.star.drawing.TextShape"><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="3278" x="9391" class="TextPosition"><tspan fill="#000000">Digital TV Frontend</tspan></tspan></tspan></text>
+</g><g transform="matrix(1.015 0 0 .99994 -2233.3 -2185.7)" class="com.sun.star.drawing.CustomShape"><g stroke="#3465af" fill="none"><path d="m3e3 2800c-18 0-35 1-53 3"/><path d="m2915 2808c-17 3-35 7-52 12"/><path d="m2832 2830c-16 6-33 12-49 20"/><path d="m2754 2864c-15 8-31 17-46 27"/><path d="m2681 2909c-14 10-28 21-42 32"/><path d="m2614 2962c-13 12-26 24-38 37"/><path d="m2554 3023c-11 13-22 27-33 41"/><path d="m2502 3091c-10 14-19 29-28 45"/><path d="m2459 3164c-8 16-15 32-22 49"/><path d="m2426 3243c-5 17-10 34-14 51"/><path d="m2406 3326c-3 18-5 35-6 53"/><path d="m2400 3411v53"/><path d="m2400 3497v53"/><path d="m2400 3582v53"/><path d="m2400 3668v53"/><path d="m2400 3753v53"/><path d="m2400 3839v53"/><path d="m2400 3924v53"/><path d="m2400 4009v54"/><path d="m2400 4095v53"/><path d="m2400 4180v53"/><path d="m2400 4266v53"/><path d="m2400 4351v53"/><path d="m2400 4437v53"/><path d="m2400 4522v53"/><path d="m2400 4607v54"/><path d="m2400 4693v53"/><path d="m2400 4778v53"/><path d="m2400 4864v53"/><path d="m2400 4949v53"/><path d="m2400 5035v53"/><path d="m2400 5120v53"/><path d="m2400 5205v54"/><path d="m2400 5291v53"/><path d="m2400 5376v53"/><path d="m2400 5462v53"/><path d="m2400 5547v53"/><path d="m2400 5633v53"/><path d="m2400 5718v53"/><path d="m2400 5803c0 18 1 36 3 53"/><path d="m2408 5888c4 18 8 35 13 52"/><path d="m2431 5971c6 16 13 33 20 49"/><path d="m2466 6049c8 15 17 31 27 46"/><path d="m2511 6122c10 14 21 28 32 42"/><path d="m2564 6188c12 13 25 26 38 38"/><path d="m2626 6248c13 11 27 23 41 33"/><path d="m2694 6300c14 10 29 19 45 27"/><path d="m2768 6343c15 7 32 15 48 21"/><path d="m2847 6375c17 5 34 10 51 14"/><path d="m2930 6395c17 2 35 4 53 5"/><path d="m3015 6400h53"/><path d="m3100 6400h53"/><path d="m3186 6400h53"/><path d="m3271 6400h53"/><path d="m3357 6400h53"/><path d="m3442 6400h53"/><path d="m3527 6400h54"/><path d="m3613 6400h53"/><path d="m3698 6400h53"/><path d="m3784 6400h53"/><path d="m3869 6400h53"/><path d="m3955 6400h53"/><path d="m4040 6400h53"/><path d="m4125 6400h54"/><path d="m4211 6400h53"/><path d="m4296 6400h53"/><path d="m4382 6400h53"/><path d="m4467 6400h53"/><path d="m4553 6400h53"/><path d="m4638 6400h53"/><path d="m4723 6400h54"/><path d="m4809 6400h53"/><path d="m4894 6400h53"/><path d="m4980 6400h53"/><path d="m5065 6400h53"/><path d="m5151 6400h53"/><path d="m5236 6400h53"/><path d="m5322 6400h53"/><path d="m5407 6400h53"/><path d="m5492 6400h53"/><path d="m5578 6400h53"/><path d="m5663 6400h53"/><path d="m5749 6400h53"/><path d="m5834 6400h53"/><path d="m5920 6400h53"/><path d="m6005 6400h53"/><path d="m6090 6400h53"/><path d="m6176 6400h53"/><path d="m6261 6400h53"/><path d="m6347 6400h53"/><path d="m6432 6400h53"/><path d="m6518 6400h53"/><path d="m6603 6400h53"/><path d="m6688 6400h54"/><path d="m6774 6400h53"/><path d="m6859 6400h53"/><path d="m6945 6400h53"/><path d="m7030 6400h53"/><path d="m7116 6400h53"/><path d="m7201 6400h53"/><path d="m7286 6400h54"/><path d="m7372 6400h53"/><path d="m7457 6400h53"/><path d="m7543 6400h53"/><path d="m7628 6400h53"/><path d="m7714 6400h53"/><path d="m7799 6400h53"/><path d="m7884 6400h54"/><path d="m7970 6400h53"/><path d="m8055 6400h53"/><path d="m8141 6400h53"/><path d="m8226 6400h53"/><path d="m8312 6400h53"/><path d="m8397 6400h53"/><path d="m8482 6400h54"/><path d="m8568 6400h53"/><path d="m8653 6400h53"/><path d="m8739 6400h53"/><path d="m8824 6400h53"/><path d="m8910 6400h53"/><path d="m8995 6400h53"/><path d="m9081 6400h53"/><path d="m9166 6400h53"/><path d="m9251 6400h53"/><path d="m9337 6400h53"/><path d="m9422 6400h53"/><path d="m9508 6400h53"/><path d="m9593 6400h53"/><path d="m9679 6400h53"/><path d="m9764 6400h53"/><path d="m9849 6400h53"/><path d="m9935 6400h53"/><path d="m10020 6400h53"/><path d="m10106 6400h53"/><path d="m10191 6400h53"/><path d="m10277 6400h53"/><path d="m10362 6400h53"/><path d="m10447 6400h53"/><path d="m10533 6400h53"/><path d="m10618 6400h53"/><path d="m10704 6400h53"/><path d="m10789 6400h53"/><path d="m10875 6400h53"/><path d="m10960 6400h53"/><path d="m11045 6400h54"/><path d="m11131 6400h53"/><path d="m11216 6400h53"/><path d="m11302 6400h53"/><path d="m11387 6400h53"/><path d="m11473 6400h53"/><path d="m11558 6400h53"/><path d="m11643 6400h54"/><path d="m11729 6400h53"/><path d="m11814 6400h53"/><path d="m11900 6400h53"/><path d="m11985 6400h53"/><path d="m12071 6400h53"/><path d="m12156 6400h53"/><path d="m12241 6400h54"/><path d="m12327 6400h53"/><path d="m12412 6400h53"/><path d="m12498 6400h53"/><path d="m12583 6400h53"/><path d="m12669 6400h53"/><path d="m12754 6400h53"/><path d="m12839 6400h54"/><path d="m12925 6400h53"/><path d="m13010 6400h53"/><path d="m13096 6400h53"/><path d="m13181 6400h53"/><path d="m13267 6400h53"/><path d="m13352 6400h53"/><path d="m13438 6400h53"/><path d="m13523 6400h53"/><path d="m13608 6400h53"/><path d="m13694 6400h53"/><path d="m13779 6400h53"/><path d="m13865 6400h53"/><path d="m13950 6400h53"/><path d="m14036 6400h53"/><path d="m14121 6400h53"/><path d="m14206 6400h53"/><path d="m14292 6400h53"/><path d="m14377 6400h53"/><path d="m14463 6400h53"/><path d="m14548 6400h53"/><path d="m14634 6400h53"/><path d="m14719 6400h53"/><path d="m14804 6400h54"/><path d="m14890 6400h53"/><path d="m14975 6400h53"/><path d="m15061 6400h53"/><path d="m15146 6400h53"/><path d="m15232 6400h53"/><path d="m15317 6400h53"/><path d="m15402 6400h54"/><path d="m15488 6400h53"/><path d="m15573 6400h53"/><path d="m15659 6400h53"/><path d="m15744 6400h53"/><path d="m15830 6400h53"/><path d="m15915 6400h53"/><path d="m16000 6400h54"/><path d="m16086 6400h53"/><path d="m16171 6400h53"/><path d="m16257 6400h53"/><path d="m16342 6400h53"/><path d="m16428 6400h53"/><path d="m16513 6400h53"/><path d="m16598 6400h54"/><path d="m16684 6400h53"/><path d="m16769 6400h53"/><path d="m16855 6400h53"/><path d="m16940 6400h53"/><path d="m17026 6400h53"/><path d="m17111 6400h53"/><path d="m17196 6400h54"/><path d="m17282 6400h53"/><path d="m17367 6400h53"/><path d="m17453 6400h53"/><path d="m17538 6400h53"/><path d="m17624 6400h53"/><path d="m17709 6400h53"/><path d="m17795 6400h53"/><path d="m17880 6400h53"/><path d="m17965 6400h53"/><path d="m18051 6400h53"/><path d="m18136 6400h53"/><path d="m18222 6400h53"/><path d="m18307 6400h53"/><path d="m18393 6400h53"/><path d="m18478 6400h53"/><path d="m18563 6400h53"/><path d="m18649 6400h53"/><path d="m18734 6400h53"/><path d="m18820 6400h53"/><path d="m18905 6400h53"/><path d="m18991 6400h53"/><path d="m19076 6400h53"/><path d="m19161 6400h54"/><path d="m19247 6400h53"/><path d="m19332 6400h53"/><path d="m19418 6400h53"/><path d="m19503 6400h53"/><path d="m19589 6400h53"/><path d="m19674 6400h53"/><path d="m19759 6400h54"/><path d="m19845 6400h53"/><path d="m19930 6400h53"/><path d="m20016 6400h53"/><path d="m20101 6400h53"/><path d="m20187 6400h53"/><path d="m20272 6400h53"/><path d="m20357 6400h54"/><path d="m20443 6400h53"/><path d="m20528 6400h53"/><path d="m20614 6400c17-1 35-2 53-5"/><path d="m20699 6390c17-4 34-9 51-14"/><path d="m20781 6365c16-6 32-13 48-21"/><path d="m20858 6329c15-8 31-17 45-27"/><path d="m20930 6283c14-10 28-21 42-32"/><path d="m20996 6229c13-12 25-25 37-38"/><path d="m21055 6167c11-14 22-28 33-42"/><path d="m21106 6098c10-15 19-30 27-45"/><path d="m21148 6024c7-16 14-33 20-49"/><path d="m21179 5944c5-17 9-34 13-51"/><path d="m21197 5861c2-18 4-35 4-53"/><path d="m21201 5776v-54"/><path d="m21201 5690v-53"/><path d="m21201 5605v-53"/><path d="m21201 5519v-53"/><path d="m21201 5434v-53"/><path d="m21201 5348v-53"/><path d="m21201 5263v-53"/><path d="m21201 5178v-54"/><path d="m21201 5092v-53"/><path d="m21201 5007v-53"/><path d="m21201 4921v-53"/><path d="m21201 4836v-53"/><path d="m21201 4750v-53"/><path d="m21201 4665v-53"/><path d="m21201 4579v-53"/><path d="m21201 4494v-53"/><path d="m21201 4409v-53"/><path d="m21201 4323v-53"/><path d="m21201 4238v-53"/><path d="m21201 4152v-53"/><path d="m21201 4067v-53"/><path d="m21201 3981v-53"/><path d="m21201 3896v-53"/><path d="m21201 3811v-53"/><path d="m21201 3725v-53"/><path d="m21201 3640v-53"/><path d="m21201 3554v-53"/><path d="m21201 3469v-53"/><path d="m21201 3383c-1-17-3-35-5-52"/><path d="m21190 3299c-4-17-8-35-14-51"/><path d="m21165 3217c-6-16-13-33-21-49"/><path d="m21129 3140c-9-16-18-31-28-46"/><path d="m21082 3068c-10-14-21-28-33-42"/><path d="m21027 3002c-12-13-24-25-37-37"/><path d="m20965 2944c-14-12-28-22-42-33"/><path d="m20896 2893c-15-9-30-18-46-27"/><path d="m20821 2852c-16-8-32-14-49-20"/><path d="m20741 2821c-17-5-34-9-51-12"/><path d="m20658 2804c-18-3-35-4-53-4"/><path d="m20573 2800h-53"/><path d="m20487 2800h-53"/><path d="m20402 2800h-53"/><path d="m20316 2800h-53"/><path d="m20231 2800h-53"/><path d="m20146 2800h-54"/><path d="m20060 2800h-53"/><path d="m19975 2800h-53"/><path d="m19889 2800h-53"/><path d="m19804 2800h-53"/><path d="m19718 2800h-53"/><path d="m19633 2800h-53"/><path d="m19548 2800h-54"/><path d="m19462 2800h-53"/><path d="m19377 2800h-53"/><path d="m19291 2800h-53"/><path d="m19206 2800h-53"/><path d="m19120 2800h-53"/><path d="m19035 2800h-53"/><path d="m18950 2800h-54"/><path d="m18864 2800h-53"/><path d="m18779 2800h-53"/><path d="m18693 2800h-53"/><path d="m18608 2800h-53"/><path d="m18522 2800h-53"/><path d="m18437 2800h-53"/><path d="m18352 2800h-54"/><path d="m18266 2800h-53"/><path d="m18181 2800h-53"/><path d="m18095 2800h-53"/><path d="m18010 2800h-53"/><path d="m17924 2800h-53"/><path d="m17839 2800h-53"/><path d="m17753 2800h-53"/><path d="m17668 2800h-53"/><path d="m17583 2800h-53"/><path d="m17497 2800h-53"/><path d="m17412 2800h-53"/><path d="m17326 2800h-53"/><path d="m17241 2800h-53"/><path d="m17155 2800h-53"/><path d="m17070 2800h-53"/><path d="m16985 2800h-53"/><path d="m16899 2800h-53"/><path d="m16814 2800h-53"/><path d="m16728 2800h-53"/><path d="m16643 2800h-53"/><path d="m16557 2800h-53"/><path d="m16472 2800h-53"/><path d="m16387 2800h-54"/><path d="m16301 2800h-53"/><path d="m16216 2800h-53"/><path d="m16130 2800h-53"/><path d="m16045 2800h-53"/><path d="m15959 2800h-53"/><path d="m15874 2800h-53"/><path d="m15789 2800h-54"/><path d="m15703 2800h-53"/><path d="m15618 2800h-53"/><path d="m15532 2800h-53"/><path d="m15447 2800h-53"/><path d="m15361 2800h-53"/><path d="m15276 2800h-53"/><path d="m15191 2800h-54"/><path d="m15105 2800h-53"/><path d="m15020 2800h-53"/><path d="m14934 2800h-53"/><path d="m14849 2800h-53"/><path d="m14763 2800h-53"/><path d="m14678 2800h-53"/><path d="m14593 2800h-54"/><path d="m14507 2800h-53"/><path d="m14422 2800h-53"/><path d="m14336 2800h-53"/><path d="m14251 2800h-53"/><path d="m14165 2800h-53"/><path d="m14080 2800h-53"/><path d="m13994 2800h-53"/><path d="m13909 2800h-53"/><path d="m13824 2800h-53"/><path d="m13738 2800h-53"/><path d="m13653 2800h-53"/><path d="m13567 2800h-53"/><path d="m13482 2800h-53"/><path d="m13396 2800h-53"/><path d="m13311 2800h-53"/><path d="m13226 2800h-53"/><path d="m13140 2800h-53"/><path d="m13055 2800h-53"/><path d="m12969 2800h-53"/><path d="m12884 2800h-53"/><path d="m12798 2800h-53"/><path d="m12713 2800h-53"/><path d="m12628 2800h-53"/><path d="m12542 2800h-53"/><path d="m12457 2800h-53"/><path d="m12371 2800h-53"/><path d="m12286 2800h-53"/><path d="m12200 2800h-53"/><path d="m12115 2800h-53"/><path d="m12030 2800h-54"/><path d="m11944 2800h-53"/><path d="m11859 2800h-53"/><path d="m11773 2800h-53"/><path d="m11688 2800h-53"/><path d="m11602 2800h-53"/><path d="m11517 2800h-53"/><path d="m11432 2800h-54"/><path d="m11346 2800h-53"/><path d="m11261 2800h-53"/><path d="m11175 2800h-53"/><path d="m11090 2800h-53"/><path d="m11004 2800h-53"/><path d="m10919 2800h-53"/><path d="m10834 2800h-54"/><path d="m10748 2800h-53"/><path d="m10663 2800h-53"/><path d="m10577 2800h-53"/><path d="m10492 2800h-53"/><path d="m10406 2800h-53"/><path d="m10321 2800h-53"/><path d="m10236 2800h-54"/><path d="m10150 2800h-53"/><path d="m10065 2800h-53"/><path d="m9979 2800h-53"/><path d="m9894 2800h-53"/><path d="m9808 2800h-53"/><path d="m9723 2800h-53"/><path d="m9637 2800h-53"/><path d="m9552 2800h-53"/><path d="m9467 2800h-53"/><path d="m9381 2800h-53"/><path d="m9296 2800h-53"/><path d="m9210 2800h-53"/><path d="m9125 2800h-53"/><path d="m9039 2800h-53"/><path d="m8954 2800h-53"/><path d="m8869 2800h-53"/><path d="m8783 2800h-53"/><path d="m8698 2800h-53"/><path d="m8612 2800h-53"/><path d="m8527 2800h-53"/><path d="m8441 2800h-53"/><path d="m8356 2800h-53"/><path d="m8271 2800h-54"/><path d="m8185 2800h-53"/><path d="m8100 2800h-53"/><path d="m8014 2800h-53"/><path d="m7929 2800h-53"/><path d="m7843 2800h-53"/><path d="m7758 2800h-53"/><path d="m7673 2800h-54"/><path d="m7587 2800h-53"/><path d="m7502 2800h-53"/><path d="m7416 2800h-53"/><path d="m7331 2800h-53"/><path d="m7245 2800h-53"/><path d="m7160 2800h-53"/><path d="m7075 2800h-54"/><path d="m6989 2800h-53"/><path d="m6904 2800h-53"/><path d="m6818 2800h-53"/><path d="m6733 2800h-53"/><path d="m6647 2800h-53"/><path d="m6562 2800h-53"/><path d="m6477 2800h-54"/><path d="m6391 2800h-53"/><path d="m6306 2800h-53"/><path d="m6220 2800h-53"/><path d="m6135 2800h-53"/><path d="m6049 2800h-53"/><path d="m5964 2800h-53"/><path d="m5879 2800h-54"/><path d="m5793 2800h-53"/><path d="m5708 2800h-53"/><path d="m5622 2800h-53"/><path d="m5537 2800h-53"/><path d="m5451 2800h-53"/><path d="m5366 2800h-53"/><path d="m5280 2800h-53"/><path d="m5195 2800h-53"/><path d="m5110 2800h-53"/><path d="m5024 2800h-53"/><path d="m4939 2800h-53"/><path d="m4853 2800h-53"/><path d="m4768 2800h-53"/><path d="m4682 2800h-53"/><path d="m4597 2800h-53"/><path d="m4512 2800h-53"/><path d="m4426 2800h-53"/><path d="m4341 2800h-53"/><path d="m4255 2800h-53"/><path d="m4170 2800h-53"/><path d="m4084 2800h-53"/><path d="m3999 2800h-53"/><path d="m3914 2800h-54"/><path d="m3828 2800h-53"/><path d="m3743 2800h-53"/><path d="m3657 2800h-53"/><path d="m3572 2800h-53"/><path d="m3486 2800h-53"/><path d="m3401 2800h-53"/><path d="m3316 2800h-54"/><path d="m3230 2800h-53"/><path d="m3145 2800h-53"/><path d="m3059 2800h-53"/></g></g><g transform="translate(-2197.3 -2186)"><rect height="1100.7" width="1213.6" y="6917.1" x="23255" fill="#f3e777"/><path fill="#ca4677" d="m22802 7700.4v-405.46l150.7-169.16c82.886-93.039 170.53-186.62 194.77-207.96l44.069-38.798 783.23-0.086 783.23-0.086v613.5 613.5h-978-978v-405.46zm1027.7 136.98v-78.372l-169.91 4.925-169.91 4.9249-5.09 45.854c-8.249 74.303 46.711 101.04 207.69 101.04h137.21v-78.372zm235.86-262.94 4.495-341.31 207.2-8.6408 207.2-8.6408 5.144-46.443c9.596-86.615-41.863-102.05-322.02-96.607l-246.71 4.7956-4.438 419.08-4.439 419.08h74.537 74.538l4.494-341.31zm391.3 313.72c26.41-19.286 36.255-41.399 32.697-73.447l-5.09-45.854h-174.05-174.05l-5.38 48.984c-9.97 90.771 0.993 97.91 150.36 97.91 99.305 0 148.27-7.6982 175.52-27.594zm-627.16-274.84v-77.768h-174.05-174.05v66.246c0 36.436 4.973 71.431 11.051 77.768 6.078 6.3366 84.401 11.521 174.05 11.521h163v-77.768zm659.89-4.9154 5.125-74.042-179.18 4.9155-179.18 4.9155-5.38 48.984c-10.473 95.348-2.259 99.57 183.28 94.197l170.2-4.9284 5.125-74.042zm-659.89-237.63v-78.372l-169.91 4.925-169.91 4.925-5.097 73.447-5.097 73.447h175 175v-78.372zm659.86 4.925-5.097-73.447h-174.05-174.05l-5.38 48.984c-10.289 93.673-2.146 97.91 188.15 97.91h175.52l-5.097-73.447zm-659.86-228.98v-77.768h-137.21c-97.358 0-147.91 7.8138-174.05 26.902-34.952 25.523-49.645 92.242-25.79 117.11 6.078 6.3366 84.401 11.521 174.05 11.521h163v-77.768z"/></g><g transform="matrix(.84874 0 0 .76147 2408.1 3615.3)"><rect height="3076.2" width="2734.3" y="13264" x="19249" fill="#6076b3"/><g stroke-linejoin="round" fill-rule="evenodd" stroke-width="28.222" fill="#e0ee2c"><rect y="13369" width="356.65" x="18937" height="180.95"/><rect y="13708" width="356.65" x="18937" height="180.95"/><rect y="14048" width="356.65" x="18937" height="180.95"/><rect y="14387" width="356.65" x="18937" height="180.95"/><rect y="14726" width="356.65" x="18937" height="180.95"/><rect y="15066" width="356.65" x="18937" height="180.95"/><rect y="15405" width="356.65" x="18937" height="180.95"/><rect y="15744" width="356.65" x="18937" height="180.95"/><rect y="16083" width="356.65" x="18937" height="180.95"/><rect y="13324" width="356.65" x="21939" height="180.95"/><rect y="13663" width="356.65" x="21939" height="180.95"/><rect y="14002" width="356.65" x="21939" height="180.95"/><rect y="14342" width="356.65" x="21939" height="180.95"/><rect y="14681" width="356.65" x="21939" height="180.95"/><rect y="15020" width="356.65" x="21939" height="180.95"/><rect y="15360" width="356.65" x="21939" height="180.95"/><rect y="15699" width="356.65" x="21939" height="180.95"/><rect y="16038" width="356.65" x="21939" height="180.95"/></g><g stroke-linejoin="round" fill-rule="evenodd" transform="matrix(.98702 0 0 .90336 -2675 7020.8)" class="com.sun.star.drawing.TextShape" stroke-width="28.222"><text class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"/></text>
+<text style="word-spacing:0px;letter-spacing:0px" xml:space="preserve" font-size="1128.9px" y="9042.0264" x="22439.668" font-family="Sans" line-height="125%" fill="#000000"><tspan y="9042.0264" x="22439.668">CPU</tspan></text>
+</g></g><g stroke-linejoin="round" fill-rule="evenodd" transform="translate(-11752 543.6)" class="com.sun.star.drawing.TextShape" stroke-width="28.222"><text class="TextShape"><tspan font-size="706px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="15832" x="24341" class="TextPosition" transform="matrix(0,-1,1,0,8509,40173)"><tspan fill="#000000">PCI, USB, SPI, I2C, ...</tspan></tspan></tspan></text>
+</g><g stroke-linejoin="round" fill-rule="evenodd" transform="translate(-655.31 963.83)" class="com.sun.star.drawing.RectangleShape" stroke-width="28.222"><g transform="matrix(.49166 0 0 1.0059 6045.6 -82.24)"><path fill="#cfe7f5" d="m14169 14572h-2268v-1412h4536v1412h-2268z"/><path fill="none" d="m14169 14572h-2268v-1412h4536v1412h-2268z" stroke="#3465af"/></g><text y="-395.11282" x="-790.22229" class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="13686.9" x="12091.779" class="TextPosition"><tspan fill="#000000">Bridge</tspan></tspan></tspan></text>
+<text y="338.66486" x="-846.66675" class="TextShape"><tspan font-size="635px" font-family="'Times New Roman', serif" font-weight="400" class="TextParagraph"><tspan y="14420.677" x="12035.335" class="TextPosition"><tspan fill="#000000"> DMA</tspan></tspan></tspan></text>
+</g></svg>
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. include:: <isonum.txt>
+
+##############################
+Linux Media Infrastructure API
+##############################
+
+**Copyright** |copy| 2009-2016 : LinuxTV Developers
+
+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. A copy of
+the license is included in the chapter entitled "GNU Free Documentation
+License".
+
+
+============
+Introduction
+============
+
+This document covers the Linux Kernel to Userspace API's used by video
+and radio streaming devices, including video cameras, analog and digital
+TV receiver cards, AM/FM receiver cards, Software Defined Radio (SDR),
+streaming capture and output devices, codec devices and remote controllers.
+
+A typical media device hardware is shown at
+:ref:`typical_media_device`.
+
+
+.. _typical_media_device:
+
+.. figure:: media_api_files/typical_media_device.*
+ :alt: typical_media_device.svg
+ :align: center
+
+ Typical Media Device
+
+The media infrastructure API was designed to control such devices. It is
+divided into four parts.
+
+The :Ref:`first part <v4l2spec>` covers radio, video capture and output,
+cameras, analog TV devices and codecs.
+
+The :Ref:`second part <dvbapi>` covers the API used for digital TV and
+Internet reception via one of the several digital tv standards. While it
+is called as DVB API, in fact it covers several different video
+standards including DVB-T/T2, DVB-S/S2, DVB-C, ATSC, ISDB-T, ISDB-S,
+DTMB, etc. The complete list of supported standards can be found at
+:ref:`fe-delivery-system-t`.
+
+The :Ref:`third part <remote_controllers>` covers the Remote Controller API.
+
+The :Ref:`fourth part <media_controller>` covers the Media Controller API.
+
+It should also be noted that a media device may also have audio
+components, like mixers, PCM capture, PCM playback, etc, which are
+controlled via ALSA API.
+
+For additional information and for the latest development code, see:
+`https://linuxtv.org <https://linuxtv.org>`__.
+
+For discussing improvements, reporting troubles, sending new drivers,
+etc, please mail to:
+`Linux Media Mailing List (LMML). <http://vger.kernel.org/vger-lists.html#linux-media>`__.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ uapi/v4l/v4l2
+ uapi/dvb/dvbapi
+ uapi/rc/remote_controllers
+ uapi/mediactl/media-controller
+ uapi/gen-errors
+ uapi/fdl-appendix
+
+.. only:: html
+
+ Retrieval
+ =========
+
+ * :ref:`genindex`
--- /dev/null
+# Ignore header name
+ignore define _DVBNET_H_
+
+# Ignore old ioctls/structs
+ignore ioctl __NET_ADD_IF_OLD
+ignore ioctl __NET_GET_IF_OLD
+ignore struct __dvb_net_if_old
+
+# Macros used at struct dvb_net_if
+replace define DVB_NET_FEEDTYPE_MPE dvb-net-if
+replace define DVB_NET_FEEDTYPE_ULE dvb-net-if
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _AUDIO_BILINGUAL_CHANNEL_SELECT:
+
+==============================
+AUDIO_BILINGUAL_CHANNEL_SELECT
+==============================
+
+Name
+----
+
+AUDIO_BILINGUAL_CHANNEL_SELECT
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(int fd, int request = AUDIO_BILINGUAL_CHANNEL_SELECT, audio_channel_select_t)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals AUDIO_BILINGUAL_CHANNEL_SELECT for this command.
+
+ - .. row 3
+
+ - audio_channel_select_t ch
+
+ - Select the output format of the audio (mono left/right, stereo).
+
+
+Description
+-----------
+
+This ioctl is obsolete. Do not use in new drivers. It has been replaced
+by the V4L2 ``V4L2_CID_MPEG_AUDIO_DEC_MULTILINGUAL_PLAYBACK`` control
+for MPEG decoders controlled through V4L2.
+
+This ioctl call asks the Audio Device to select the requested channel
+for bilingual streams if possible.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _AUDIO_CHANNEL_SELECT:
+
+====================
+AUDIO_CHANNEL_SELECT
+====================
+
+Name
+----
+
+AUDIO_CHANNEL_SELECT
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(int fd, int request = AUDIO_CHANNEL_SELECT, audio_channel_select_t)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals AUDIO_CHANNEL_SELECT for this command.
+
+ - .. row 3
+
+ - audio_channel_select_t ch
+
+ - Select the output format of the audio (mono left/right, stereo).
+
+
+Description
+-----------
+
+This ioctl is for DVB devices only. To control a V4L2 decoder use the
+V4L2 ``V4L2_CID_MPEG_AUDIO_DEC_PLAYBACK`` control instead.
+
+This ioctl call asks the Audio Device to select the requested channel if
+possible.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _AUDIO_CLEAR_BUFFER:
+
+==================
+AUDIO_CLEAR_BUFFER
+==================
+
+Name
+----
+
+AUDIO_CLEAR_BUFFER
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(int fd, int request = AUDIO_CLEAR_BUFFER)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals AUDIO_CLEAR_BUFFER for this command.
+
+
+Description
+-----------
+
+This ioctl call asks the Audio Device to clear all software and hardware
+buffers of the audio decoder device.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _AUDIO_CONTINUE:
+
+==============
+AUDIO_CONTINUE
+==============
+
+Name
+----
+
+AUDIO_CONTINUE
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(int fd, int request = AUDIO_CONTINUE)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals AUDIO_CONTINUE for this command.
+
+
+Description
+-----------
+
+This ioctl restarts the decoding and playing process previously paused
+with AUDIO_PAUSE command.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _audio_fclose:
+
+=================
+DVB audio close()
+=================
+
+Name
+----
+
+DVB audio close()
+
+
+Synopsis
+--------
+
+.. cpp:function:: int close(int fd)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+
+Description
+-----------
+
+This system call closes a previously opened audio device.
+
+
+Return Value
+------------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``EBADF``
+
+ - fd is not a valid open file descriptor.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _audio_fopen:
+
+================
+DVB audio open()
+================
+
+Name
+----
+
+DVB audio open()
+
+
+Synopsis
+--------
+
+.. cpp:function:: int open(const char *deviceName, int flags)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - const char \*deviceName
+
+ - Name of specific audio device.
+
+ - .. row 2
+
+ - int flags
+
+ - A bit-wise OR of the following flags:
+
+ - .. row 3
+
+ -
+ - O_RDONLY read-only access
+
+ - .. row 4
+
+ -
+ - O_RDWR read/write access
+
+ - .. row 5
+
+ -
+ - O_NONBLOCK open in non-blocking mode
+
+ - .. row 6
+
+ -
+ - (blocking mode is the default)
+
+
+Description
+-----------
+
+This system call opens a named audio device (e.g.
+/dev/dvb/adapter0/audio0) for subsequent use. When an open() call has
+succeeded, the device will be ready for use. The significance of
+blocking or non-blocking mode is described in the documentation for
+functions where there is a difference. It does not affect the semantics
+of the open() call itself. A device opened in blocking mode can later be
+put into non-blocking mode (and vice versa) using the F_SETFL command
+of the fcntl system call. This is a standard system call, documented in
+the Linux manual page for fcntl. Only one user can open the Audio Device
+in O_RDWR mode. All other attempts to open the device in this mode will
+fail, and an error code will be returned. If the Audio Device is opened
+in O_RDONLY mode, the only ioctl call that can be used is
+AUDIO_GET_STATUS. All other call will return with an error code.
+
+
+Return Value
+------------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``ENODEV``
+
+ - Device driver not loaded/available.
+
+ - .. row 2
+
+ - ``EBUSY``
+
+ - Device or resource busy.
+
+ - .. row 3
+
+ - ``EINVAL``
+
+ - Invalid argument.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _audio_fwrite:
+
+=================
+DVB audio write()
+=================
+
+Name
+----
+
+DVB audio write()
+
+
+Synopsis
+--------
+
+.. cpp:function:: size_t write(int fd, const void *buf, size_t count)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - void \*buf
+
+ - Pointer to the buffer containing the PES data.
+
+ - .. row 3
+
+ - size_t count
+
+ - Size of buf.
+
+
+Description
+-----------
+
+This system call can only be used if AUDIO_SOURCE_MEMORY is selected
+in the ioctl call AUDIO_SELECT_SOURCE. The data provided shall be in
+PES format. If O_NONBLOCK is not specified the function will block
+until buffer space is available. The amount of data to be transferred is
+implied by count.
+
+
+Return Value
+------------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``EPERM``
+
+ - Mode AUDIO_SOURCE_MEMORY not selected.
+
+ - .. row 2
+
+ - ``ENOMEM``
+
+ - Attempted to write more data than the internal buffer can hold.
+
+ - .. row 3
+
+ - ``EBADF``
+
+ - fd is not a valid open file descriptor.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _AUDIO_GET_CAPABILITIES:
+
+======================
+AUDIO_GET_CAPABILITIES
+======================
+
+Name
+----
+
+AUDIO_GET_CAPABILITIES
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(int fd, int request = AUDIO_GET_CAPABILITIES, unsigned int *cap)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals AUDIO_GET_CAPABILITIES for this command.
+
+ - .. row 3
+
+ - unsigned int \*cap
+
+ - Returns a bit array of supported sound formats.
+
+
+Description
+-----------
+
+This ioctl call asks the Audio Device to tell us about the decoding
+capabilities of the audio hardware.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _AUDIO_GET_PTS:
+
+=============
+AUDIO_GET_PTS
+=============
+
+Name
+----
+
+AUDIO_GET_PTS
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(int fd, int request = AUDIO_GET_PTS, __u64 *pts)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals AUDIO_GET_PTS for this command.
+
+ - .. row 3
+
+ - __u64 \*pts
+
+ - Returns the 33-bit timestamp as defined in ITU T-REC-H.222.0 /
+ ISO/IEC 13818-1.
+
+ The PTS should belong to the currently played frame if possible,
+ but may also be a value close to it like the PTS of the last
+ decoded frame or the last PTS extracted by the PES parser.
+
+
+Description
+-----------
+
+This ioctl is obsolete. Do not use in new drivers. If you need this
+functionality, then please contact the linux-media mailing list
+(`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__).
+
+This ioctl call asks the Audio Device to return the current PTS
+timestamp.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _AUDIO_GET_STATUS:
+
+================
+AUDIO_GET_STATUS
+================
+
+Name
+----
+
+AUDIO_GET_STATUS
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(int fd, int request = AUDIO_GET_STATUS, struct audio_status *status)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals AUDIO_GET_STATUS for this command.
+
+ - .. row 3
+
+ - struct audio_status \*status
+
+ - Returns the current state of Audio Device.
+
+
+Description
+-----------
+
+This ioctl call asks the Audio Device to return the current state of the
+Audio Device.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _AUDIO_PAUSE:
+
+===========
+AUDIO_PAUSE
+===========
+
+Name
+----
+
+AUDIO_PAUSE
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(int fd, int request = AUDIO_PAUSE)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals AUDIO_PAUSE for this command.
+
+
+Description
+-----------
+
+This ioctl call suspends the audio stream being played. Decoding and
+playing are paused. It is then possible to restart again decoding and
+playing process of the audio stream using AUDIO_CONTINUE command.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _AUDIO_PLAY:
+
+==========
+AUDIO_PLAY
+==========
+
+Name
+----
+
+AUDIO_PLAY
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(int fd, int request = AUDIO_PLAY)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals AUDIO_PLAY for this command.
+
+
+Description
+-----------
+
+This ioctl call asks the Audio Device to start playing an audio stream
+from the selected source.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _AUDIO_SELECT_SOURCE:
+
+===================
+AUDIO_SELECT_SOURCE
+===================
+
+Name
+----
+
+AUDIO_SELECT_SOURCE
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(int fd, int request = AUDIO_SELECT_SOURCE, audio_stream_source_t source)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals AUDIO_SELECT_SOURCE for this command.
+
+ - .. row 3
+
+ - audio_stream_source_t source
+
+ - Indicates the source that shall be used for the Audio stream.
+
+
+Description
+-----------
+
+This ioctl call informs the audio device which source shall be used for
+the input data. The possible sources are demux or memory. If
+AUDIO_SOURCE_MEMORY is selected, the data is fed to the Audio Device
+through the write command.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _AUDIO_SET_ATTRIBUTES:
+
+====================
+AUDIO_SET_ATTRIBUTES
+====================
+
+Name
+----
+
+AUDIO_SET_ATTRIBUTES
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(fd, int request = AUDIO_SET_ATTRIBUTES, audio_attributes_t attr )
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals AUDIO_SET_ATTRIBUTES for this command.
+
+ - .. row 3
+
+ - audio_attributes_t attr
+
+ - audio attributes according to section ??
+
+
+Description
+-----------
+
+This ioctl is intended for DVD playback and allows you to set certain
+information about the audio stream.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``EINVAL``
+
+ - attr is not a valid or supported attribute setting.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _AUDIO_SET_AV_SYNC:
+
+=================
+AUDIO_SET_AV_SYNC
+=================
+
+Name
+----
+
+AUDIO_SET_AV_SYNC
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(int fd, int request = AUDIO_SET_AV_SYNC, boolean state)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals AUDIO_AV_SYNC for this command.
+
+ - .. row 3
+
+ - boolean state
+
+ - Tells the DVB subsystem if A/V synchronization shall be ON or OFF.
+
+ - .. row 4
+
+ -
+ - TRUE AV-sync ON
+
+ - .. row 5
+
+ -
+ - FALSE AV-sync OFF
+
+
+Description
+-----------
+
+This ioctl call asks the Audio Device to turn ON or OFF A/V
+synchronization.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _AUDIO_SET_BYPASS_MODE:
+
+=====================
+AUDIO_SET_BYPASS_MODE
+=====================
+
+Name
+----
+
+AUDIO_SET_BYPASS_MODE
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(int fd, int request = AUDIO_SET_BYPASS_MODE, boolean mode)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals AUDIO_SET_BYPASS_MODE for this command.
+
+ - .. row 3
+
+ - boolean mode
+
+ - Enables or disables the decoding of the current Audio stream in
+ the DVB subsystem.
+
+ - .. row 4
+
+ -
+ - TRUE Bypass is disabled
+
+ - .. row 5
+
+ -
+ - FALSE Bypass is enabled
+
+
+Description
+-----------
+
+This ioctl call asks the Audio Device to bypass the Audio decoder and
+forward the stream without decoding. This mode shall be used if streams
+that can’t be handled by the DVB system shall be decoded. Dolby
+DigitalTM streams are automatically forwarded by the DVB subsystem if
+the hardware can handle it.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _AUDIO_SET_EXT_ID:
+
+================
+AUDIO_SET_EXT_ID
+================
+
+Name
+----
+
+AUDIO_SET_EXT_ID
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(fd, int request = AUDIO_SET_EXT_ID, int id)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals AUDIO_SET_EXT_ID for this command.
+
+ - .. row 3
+
+ - int id
+
+ - audio sub_stream_id
+
+
+Description
+-----------
+
+This ioctl can be used to set the extension id for MPEG streams in DVD
+playback. Only the first 3 bits are recognized.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``EINVAL``
+
+ - id is not a valid id.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _AUDIO_SET_ID:
+
+============
+AUDIO_SET_ID
+============
+
+Name
+----
+
+AUDIO_SET_ID
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(int fd, int request = AUDIO_SET_ID, int id)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals AUDIO_SET_ID for this command.
+
+ - .. row 3
+
+ - int id
+
+ - audio sub-stream id
+
+
+Description
+-----------
+
+This ioctl selects which sub-stream is to be decoded if a program or
+system stream is sent to the video device. If no audio stream type is
+set the id has to be in [0xC0,0xDF] for MPEG sound, in [0x80,0x87] for
+AC3 and in [0xA0,0xA7] for LPCM. More specifications may follow for
+other stream types. If the stream type is set the id just specifies the
+substream id of the audio stream and only the first 5 bits are
+recognized.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _AUDIO_SET_KARAOKE:
+
+=================
+AUDIO_SET_KARAOKE
+=================
+
+Name
+----
+
+AUDIO_SET_KARAOKE
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(fd, int request = AUDIO_SET_KARAOKE, audio_karaoke_t *karaoke)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals AUDIO_SET_KARAOKE for this command.
+
+ - .. row 3
+
+ - audio_karaoke_t \*karaoke
+
+ - karaoke settings according to section ??.
+
+
+Description
+-----------
+
+This ioctl allows one to set the mixer settings for a karaoke DVD.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``EINVAL``
+
+ - karaoke is not a valid or supported karaoke setting.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _AUDIO_SET_MIXER:
+
+===============
+AUDIO_SET_MIXER
+===============
+
+Name
+----
+
+AUDIO_SET_MIXER
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(int fd, int request = AUDIO_SET_MIXER, audio_mixer_t *mix)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals AUDIO_SET_ID for this command.
+
+ - .. row 3
+
+ - audio_mixer_t \*mix
+
+ - mixer settings.
+
+
+Description
+-----------
+
+This ioctl lets you adjust the mixer settings of the audio decoder.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _AUDIO_SET_MUTE:
+
+==============
+AUDIO_SET_MUTE
+==============
+
+Name
+----
+
+AUDIO_SET_MUTE
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(int fd, int request = AUDIO_SET_MUTE, boolean state)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals AUDIO_SET_MUTE for this command.
+
+ - .. row 3
+
+ - boolean state
+
+ - Indicates if audio device shall mute or not.
+
+ - .. row 4
+
+ -
+ - TRUE Audio Mute
+
+ - .. row 5
+
+ -
+ - FALSE Audio Un-mute
+
+
+Description
+-----------
+
+This ioctl is for DVB devices only. To control a V4L2 decoder use the
+V4L2 :ref:`VIDIOC_DECODER_CMD` with the
+``V4L2_DEC_CMD_START_MUTE_AUDIO`` flag instead.
+
+This ioctl call asks the audio device to mute the stream that is
+currently being played.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _AUDIO_SET_STREAMTYPE:
+
+====================
+AUDIO_SET_STREAMTYPE
+====================
+
+Name
+----
+
+AUDIO_SET_STREAMTYPE
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(fd, int request = AUDIO_SET_STREAMTYPE, int type)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals AUDIO_SET_STREAMTYPE for this command.
+
+ - .. row 3
+
+ - int type
+
+ - stream type
+
+
+Description
+-----------
+
+This ioctl tells the driver which kind of audio stream to expect. This
+is useful if the stream offers several audio sub-streams like LPCM and
+AC3.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``EINVAL``
+
+ - type is not a valid or supported stream type.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _AUDIO_STOP:
+
+==========
+AUDIO_STOP
+==========
+
+Name
+----
+
+AUDIO_STOP
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(int fd, int request = AUDIO_STOP)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals AUDIO_STOP for this command.
+
+
+Description
+-----------
+
+This ioctl call asks the Audio Device to stop playing the current
+stream.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _dvb_audio:
+
+################
+DVB Audio Device
+################
+The DVB audio device controls the MPEG2 audio decoder of the DVB
+hardware. It can be accessed through ``/dev/dvb/adapter?/audio?``. Data
+types and and ioctl definitions can be accessed by including
+``linux/dvb/audio.h`` in your application.
+
+Please note that some DVB cards don’t have their own MPEG decoder, which
+results in the omission of the audio and video device.
+
+These ioctls were also used by V4L2 to control MPEG decoders implemented
+in V4L2. The use of these ioctls for that purpose has been made obsolete
+and proper V4L2 ioctls or controls have been created to replace that
+functionality.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ audio_data_types
+ audio_function_calls
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _audio_data_types:
+
+****************
+Audio Data Types
+****************
+
+This section describes the structures, data types and defines used when
+talking to the audio device.
+
+
+.. _audio-stream-source-t:
+
+audio_stream_source_t
+=====================
+
+The audio stream source is set through the AUDIO_SELECT_SOURCE call
+and can take the following values, depending on whether we are replaying
+from an internal (demux) or external (user write) source.
+
+
+.. code-block:: c
+
+ typedef enum {
+ AUDIO_SOURCE_DEMUX,
+ AUDIO_SOURCE_MEMORY
+ } audio_stream_source_t;
+
+AUDIO_SOURCE_DEMUX selects the demultiplexer (fed either by the
+frontend or the DVR device) as the source of the video stream. If
+AUDIO_SOURCE_MEMORY is selected the stream comes from the application
+through the ``write()`` system call.
+
+
+.. _audio-play-state-t:
+
+audio_play_state_t
+==================
+
+The following values can be returned by the AUDIO_GET_STATUS call
+representing the state of audio playback.
+
+
+.. code-block:: c
+
+ typedef enum {
+ AUDIO_STOPPED,
+ AUDIO_PLAYING,
+ AUDIO_PAUSED
+ } audio_play_state_t;
+
+
+.. _audio-channel-select-t:
+
+audio_channel_select_t
+======================
+
+The audio channel selected via AUDIO_CHANNEL_SELECT is determined by
+the following values.
+
+
+.. code-block:: c
+
+ typedef enum {
+ AUDIO_STEREO,
+ AUDIO_MONO_LEFT,
+ AUDIO_MONO_RIGHT,
+ AUDIO_MONO,
+ AUDIO_STEREO_SWAPPED
+ } audio_channel_select_t;
+
+
+.. _audio-status:
+
+struct audio_status
+===================
+
+The AUDIO_GET_STATUS call returns the following structure informing
+about various states of the playback operation.
+
+
+.. code-block:: c
+
+ typedef struct audio_status {
+ boolean AV_sync_state;
+ boolean mute_state;
+ audio_play_state_t play_state;
+ audio_stream_source_t stream_source;
+ audio_channel_select_t channel_select;
+ boolean bypass_mode;
+ audio_mixer_t mixer_state;
+ } audio_status_t;
+
+
+.. _audio-mixer:
+
+struct audio_mixer
+==================
+
+The following structure is used by the AUDIO_SET_MIXER call to set the
+audio volume.
+
+
+.. code-block:: c
+
+ typedef struct audio_mixer {
+ unsigned int volume_left;
+ unsigned int volume_right;
+ } audio_mixer_t;
+
+
+.. _audio_encodings:
+
+audio encodings
+===============
+
+A call to AUDIO_GET_CAPABILITIES returns an unsigned integer with the
+following bits set according to the hardwares capabilities.
+
+
+.. code-block:: c
+
+ #define AUDIO_CAP_DTS 1
+ #define AUDIO_CAP_LPCM 2
+ #define AUDIO_CAP_MP1 4
+ #define AUDIO_CAP_MP2 8
+ #define AUDIO_CAP_MP3 16
+ #define AUDIO_CAP_AAC 32
+ #define AUDIO_CAP_OGG 64
+ #define AUDIO_CAP_SDDS 128
+ #define AUDIO_CAP_AC3 256
+
+
+.. _audio-karaoke:
+
+struct audio_karaoke
+====================
+
+The ioctl AUDIO_SET_KARAOKE uses the following format:
+
+
+.. code-block:: c
+
+ typedef
+ struct audio_karaoke {
+ int vocal1;
+ int vocal2;
+ int melody;
+ } audio_karaoke_t;
+
+If Vocal1 or Vocal2 are non-zero, they get mixed into left and right t
+at 70% each. If both, Vocal1 and Vocal2 are non-zero, Vocal1 gets mixed
+into the left channel and Vocal2 into the right channel at 100% each. Ff
+Melody is non-zero, the melody channel gets mixed into left and right.
+
+
+.. _audio-attributes-t:
+
+audio attributes
+================
+
+The following attributes can be set by a call to AUDIO_SET_ATTRIBUTES:
+
+
+.. code-block:: c
+
+ typedef uint16_t audio_attributes_t;
+ /* bits: descr. */
+ /* 15-13 audio coding mode (0=ac3, 2=mpeg1, 3=mpeg2ext, 4=LPCM, 6=DTS, */
+ /* 12 multichannel extension */
+ /* 11-10 audio type (0=not spec, 1=language included) */
+ /* 9- 8 audio application mode (0=not spec, 1=karaoke, 2=surround) */
+ /* 7- 6 Quantization / DRC (mpeg audio: 1=DRC exists)(lpcm: 0=16bit, */
+ /* 5- 4 Sample frequency fs (0=48kHz, 1=96kHz) */
+ /* 2- 0 number of audio channels (n+1 channels) */
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _audio_function_calls:
+
+********************
+Audio Function Calls
+********************
+
+.. toctree::
+ :maxdepth: 1
+
+ audio-fopen
+ audio-fclose
+ audio-fwrite
+ audio-stop
+ audio-play
+ audio-pause
+ audio-continue
+ audio-select-source
+ audio-set-mute
+ audio-set-av-sync
+ audio-set-bypass-mode
+ audio-channel-select
+ audio-bilingual-channel-select
+ audio-get-pts
+ audio-get-status
+ audio-get-capabilities
+ audio-clear-buffer
+ audio-set-id
+ audio-set-mixer
+ audio-set-streamtype
+ audio-set-ext-id
+ audio-set-attributes
+ audio-set-karaoke
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _audio_h:
+
+*********************
+DVB Audio Header File
+*********************
+
+.. kernel-include:: $BUILDDIR/audio.h.rst
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _ca_fclose:
+
+==============
+DVB CA close()
+==============
+
+Name
+----
+
+DVB CA close()
+
+
+Synopsis
+--------
+
+.. cpp:function:: int close(int fd)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+
+Description
+-----------
+
+This system call closes a previously opened audio device.
+
+
+Return Value
+------------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``EBADF``
+
+ - fd is not a valid open file descriptor.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _ca_fopen:
+
+=============
+DVB CA open()
+=============
+
+Name
+----
+
+DVB CA open()
+
+
+Synopsis
+--------
+
+.. cpp:function:: int open(const char *deviceName, int flags)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - const char \*deviceName
+
+ - Name of specific video device.
+
+ - .. row 2
+
+ - int flags
+
+ - A bit-wise OR of the following flags:
+
+ - .. row 3
+
+ -
+ - O_RDONLY read-only access
+
+ - .. row 4
+
+ -
+ - O_RDWR read/write access
+
+ - .. row 5
+
+ -
+ - O_NONBLOCK open in non-blocking mode
+
+ - .. row 6
+
+ -
+ - (blocking mode is the default)
+
+
+Description
+-----------
+
+This system call opens a named ca device (e.g. /dev/ost/ca) for
+subsequent use.
+
+When an open() call has succeeded, the device will be ready for use. The
+significance of blocking or non-blocking mode is described in the
+documentation for functions where there is a difference. It does not
+affect the semantics of the open() call itself. A device opened in
+blocking mode can later be put into non-blocking mode (and vice versa)
+using the F_SETFL command of the fcntl system call. This is a standard
+system call, documented in the Linux manual page for fcntl. Only one
+user can open the CA Device in O_RDWR mode. All other attempts to open
+the device in this mode will fail, and an error code will be returned.
+
+
+Return Value
+------------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``ENODEV``
+
+ - Device driver not loaded/available.
+
+ - .. row 2
+
+ - ``EINTERNAL``
+
+ - Internal error.
+
+ - .. row 3
+
+ - ``EBUSY``
+
+ - Device or resource busy.
+
+ - .. row 4
+
+ - ``EINVAL``
+
+ - Invalid argument.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _CA_GET_CAP:
+
+==========
+CA_GET_CAP
+==========
+
+Name
+----
+
+CA_GET_CAP
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(fd, int request = CA_GET_CAP, ca_caps_t *)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals CA_GET_CAP for this command.
+
+ - .. row 3
+
+ - ca_caps_t *
+
+ - Undocumented.
+
+
+Description
+-----------
+
+This ioctl is undocumented. Documentation is welcome.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _CA_GET_DESCR_INFO:
+
+=================
+CA_GET_DESCR_INFO
+=================
+
+Name
+----
+
+CA_GET_DESCR_INFO
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(fd, int request = CA_GET_DESCR_INFO, ca_descr_info_t *)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals CA_GET_DESCR_INFO for this command.
+
+ - .. row 3
+
+ - ca_descr_info_t \*
+
+ - Undocumented.
+
+
+Description
+-----------
+
+This ioctl is undocumented. Documentation is welcome.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _CA_GET_MSG:
+
+==========
+CA_GET_MSG
+==========
+
+Name
+----
+
+CA_GET_MSG
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(fd, int request = CA_GET_MSG, ca_msg_t *)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals CA_GET_MSG for this command.
+
+ - .. row 3
+
+ - ca_msg_t \*
+
+ - Undocumented.
+
+
+Description
+-----------
+
+This ioctl is undocumented. Documentation is welcome.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _CA_GET_SLOT_INFO:
+
+================
+CA_GET_SLOT_INFO
+================
+
+Name
+----
+
+CA_GET_SLOT_INFO
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(fd, int request = CA_GET_SLOT_INFO, ca_slot_info_t *)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals CA_GET_SLOT_INFO for this command.
+
+ - .. row 3
+
+ - ca_slot_info_t \*
+
+ - Undocumented.
+
+
+Description
+-----------
+
+This ioctl is undocumented. Documentation is welcome.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _CA_RESET:
+
+========
+CA_RESET
+========
+
+Name
+----
+
+CA_RESET
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(fd, int request = CA_RESET)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals CA_RESET for this command.
+
+
+Description
+-----------
+
+This ioctl is undocumented. Documentation is welcome.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _CA_SEND_MSG:
+
+===========
+CA_SEND_MSG
+===========
+
+Name
+----
+
+CA_SEND_MSG
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(fd, int request = CA_SEND_MSG, ca_msg_t *)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals CA_SEND_MSG for this command.
+
+ - .. row 3
+
+ - ca_msg_t \*
+
+ - Undocumented.
+
+
+Description
+-----------
+
+This ioctl is undocumented. Documentation is welcome.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _CA_SET_DESCR:
+
+============
+CA_SET_DESCR
+============
+
+Name
+----
+
+CA_SET_DESCR
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(fd, int request = CA_SET_DESCR, ca_descr_t *)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals CA_SET_DESCR for this command.
+
+ - .. row 3
+
+ - ca_descr_t \*
+
+ - Undocumented.
+
+
+Description
+-----------
+
+This ioctl is undocumented. Documentation is welcome.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _CA_SET_PID:
+
+==========
+CA_SET_PID
+==========
+
+Name
+----
+
+CA_SET_PID
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(fd, int request = CA_SET_PID, ca_pid_t *)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals CA_SET_PID for this command.
+
+ - .. row 3
+
+ - ca_pid_t \*
+
+ - Undocumented.
+
+
+Description
+-----------
+
+This ioctl is undocumented. Documentation is welcome.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _dvb_ca:
+
+#############
+DVB CA Device
+#############
+The DVB CA device controls the conditional access hardware. It can be
+accessed through ``/dev/dvb/adapter?/ca?``. Data types and and ioctl
+definitions can be accessed by including ``linux/dvb/ca.h`` in your
+application.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ ca_data_types
+ ca_function_calls
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _ca_data_types:
+
+*************
+CA Data Types
+*************
+
+
+.. _ca-slot-info:
+
+ca_slot_info_t
+==============
+
+
+.. code-block:: c
+
+ typedef struct ca_slot_info {
+ int num; /* slot number */
+
+ int type; /* CA interface this slot supports */
+ #define CA_CI 1 /* CI high level interface */
+ #define CA_CI_LINK 2 /* CI link layer level interface */
+ #define CA_CI_PHYS 4 /* CI physical layer level interface */
+ #define CA_DESCR 8 /* built-in descrambler */
+ #define CA_SC 128 /* simple smart card interface */
+
+ unsigned int flags;
+ #define CA_CI_MODULE_PRESENT 1 /* module (or card) inserted */
+ #define CA_CI_MODULE_READY 2
+ } ca_slot_info_t;
+
+
+.. _ca-descr-info:
+
+ca_descr_info_t
+===============
+
+
+.. code-block:: c
+
+ typedef struct ca_descr_info {
+ unsigned int num; /* number of available descramblers (keys) */
+ unsigned int type; /* type of supported scrambling system */
+ #define CA_ECD 1
+ #define CA_NDS 2
+ #define CA_DSS 4
+ } ca_descr_info_t;
+
+
+.. _ca-caps:
+
+ca_caps_t
+=========
+
+
+.. code-block:: c
+
+ typedef struct ca_caps {
+ unsigned int slot_num; /* total number of CA card and module slots */
+ unsigned int slot_type; /* OR of all supported types */
+ unsigned int descr_num; /* total number of descrambler slots (keys) */
+ unsigned int descr_type;/* OR of all supported types */
+ } ca_cap_t;
+
+
+.. _ca-msg:
+
+ca_msg_t
+========
+
+
+.. code-block:: c
+
+ /* a message to/from a CI-CAM */
+ typedef struct ca_msg {
+ unsigned int index;
+ unsigned int type;
+ unsigned int length;
+ unsigned char msg[256];
+ } ca_msg_t;
+
+
+.. _ca-descr:
+
+ca_descr_t
+==========
+
+
+.. code-block:: c
+
+ typedef struct ca_descr {
+ unsigned int index;
+ unsigned int parity;
+ unsigned char cw[8];
+ } ca_descr_t;
+
+
+.. _ca-pid:
+
+ca-pid
+======
+
+
+.. code-block:: c
+
+ typedef struct ca_pid {
+ unsigned int pid;
+ int index; /* -1 == disable*/
+ } ca_pid_t;
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _ca_function_calls:
+
+*****************
+CA Function Calls
+*****************
+
+.. toctree::
+ :maxdepth: 1
+
+ ca-fopen
+ ca-fclose
+ ca-reset
+ ca-get-cap
+ ca-get-slot-info
+ ca-get-descr-info
+ ca-get-msg
+ ca-send-msg
+ ca-set-descr
+ ca-set-pid
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _ca_h:
+
+**********************************
+DVB Conditional Access Header File
+**********************************
+
+.. kernel-include:: $BUILDDIR/ca.h.rst
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _dvb_demux:
+
+################
+DVB Demux Device
+################
+The DVB demux device controls the filters of the DVB hardware/software.
+It can be accessed through ``/dev/adapter?/demux?``. Data types and and
+ioctl definitions can be accessed by including ``linux/dvb/dmx.h`` in
+your application.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ dmx_types
+ dmx_fcalls
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _DMX_ADD_PID:
+
+===========
+DMX_ADD_PID
+===========
+
+Name
+----
+
+DMX_ADD_PID
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(fd, int request = DMX_ADD_PID, __u16 *)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals DMX_ADD_PID for this command.
+
+ - .. row 3
+
+ - __u16 *
+
+ - PID number to be filtered.
+
+
+Description
+-----------
+
+This ioctl call allows to add multiple PIDs to a transport stream filter
+previously set up with DMX_SET_PES_FILTER and output equal to
+DMX_OUT_TSDEMUX_TAP.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _dmx_fclose:
+
+=================
+DVB demux close()
+=================
+
+Name
+----
+
+DVB demux close()
+
+
+Synopsis
+--------
+
+.. cpp:function:: int close(int fd)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+
+Description
+-----------
+
+This system call deactivates and deallocates a filter that was
+previously allocated via the open() call.
+
+
+Return Value
+------------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``EBADF``
+
+ - fd is not a valid open file descriptor.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _dmx_fopen:
+
+================
+DVB demux open()
+================
+
+Name
+----
+
+DVB demux open()
+
+
+Synopsis
+--------
+
+.. cpp:function:: int open(const char *deviceName, int flags)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - const char \*deviceName
+
+ - Name of demux device.
+
+ - .. row 2
+
+ - int flags
+
+ - A bit-wise OR of the following flags:
+
+ - .. row 3
+
+ -
+ - O_RDWR read/write access
+
+ - .. row 4
+
+ -
+ - O_NONBLOCK open in non-blocking mode
+
+ - .. row 5
+
+ -
+ - (blocking mode is the default)
+
+
+Description
+-----------
+
+This system call, used with a device name of /dev/dvb/adapter0/demux0,
+allocates a new filter and returns a handle which can be used for
+subsequent control of that filter. This call has to be made for each
+filter to be used, i.e. every returned file descriptor is a reference to
+a single filter. /dev/dvb/adapter0/dvr0 is a logical device to be used
+for retrieving Transport Streams for digital video recording. When
+reading from this device a transport stream containing the packets from
+all PES filters set in the corresponding demux device
+(/dev/dvb/adapter0/demux0) having the output set to DMX_OUT_TS_TAP. A
+recorded Transport Stream is replayed by writing to this device.
+
+The significance of blocking or non-blocking mode is described in the
+documentation for functions where there is a difference. It does not
+affect the semantics of the open() call itself. A device opened in
+blocking mode can later be put into non-blocking mode (and vice versa)
+using the F_SETFL command of the fcntl system call.
+
+
+Return Value
+------------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``ENODEV``
+
+ - Device driver not loaded/available.
+
+ - .. row 2
+
+ - ``EINVAL``
+
+ - Invalid argument.
+
+ - .. row 3
+
+ - ``EMFILE``
+
+ - “Too many open files”, i.e. no more filters available.
+
+ - .. row 4
+
+ - ``ENOMEM``
+
+ - The driver failed to allocate enough memory.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _dmx_fread:
+
+================
+DVB demux read()
+================
+
+Name
+----
+
+DVB demux read()
+
+
+Synopsis
+--------
+
+.. cpp:function:: size_t read(int fd, void *buf, size_t count)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - void \*buf
+
+ - Pointer to the buffer to be used for returned filtered data.
+
+ - .. row 3
+
+ - size_t count
+
+ - Size of buf.
+
+
+Description
+-----------
+
+This system call returns filtered data, which might be section or PES
+data. The filtered data is transferred from the driver’s internal
+circular buffer to buf. The maximum amount of data to be transferred is
+implied by count.
+
+
+Return Value
+------------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``EWOULDBLOCK``
+
+ - No data to return and O_NONBLOCK was specified.
+
+ - .. row 2
+
+ - ``EBADF``
+
+ - fd is not a valid open file descriptor.
+
+ - .. row 3
+
+ - ``ECRC``
+
+ - Last section had a CRC error - no data returned. The buffer is
+ flushed.
+
+ - .. row 4
+
+ - ``EOVERFLOW``
+
+ -
+
+ - .. row 5
+
+ -
+ - The filtered data was not read from the buffer in due time,
+ resulting in non-read data being lost. The buffer is flushed.
+
+ - .. row 6
+
+ - ``ETIMEDOUT``
+
+ - The section was not loaded within the stated timeout period. See
+ ioctl DMX_SET_FILTER for how to set a timeout.
+
+ - .. row 7
+
+ - ``EFAULT``
+
+ - The driver failed to write to the callers buffer due to an invalid
+ \*buf pointer.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _dmx_fwrite:
+
+=================
+DVB demux write()
+=================
+
+Name
+----
+
+DVB demux write()
+
+
+Synopsis
+--------
+
+.. cpp:function:: ssize_t write(int fd, const void *buf, size_t count)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - void \*buf
+
+ - Pointer to the buffer containing the Transport Stream.
+
+ - .. row 3
+
+ - size_t count
+
+ - Size of buf.
+
+
+Description
+-----------
+
+This system call is only provided by the logical device
+/dev/dvb/adapter0/dvr0, associated with the physical demux device that
+provides the actual DVR functionality. It is used for replay of a
+digitally recorded Transport Stream. Matching filters have to be defined
+in the corresponding physical demux device, /dev/dvb/adapter0/demux0.
+The amount of data to be transferred is implied by count.
+
+
+Return Value
+------------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``EWOULDBLOCK``
+
+ - No data was written. This might happen if O_NONBLOCK was
+ specified and there is no more buffer space available (if
+ O_NONBLOCK is not specified the function will block until buffer
+ space is available).
+
+ - .. row 2
+
+ - ``EBUSY``
+
+ - This error code indicates that there are conflicting requests. The
+ corresponding demux device is setup to receive data from the
+ front- end. Make sure that these filters are stopped and that the
+ filters with input set to DMX_IN_DVR are started.
+
+ - .. row 3
+
+ - ``EBADF``
+
+ - fd is not a valid open file descriptor.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _DMX_GET_CAPS:
+
+============
+DMX_GET_CAPS
+============
+
+Name
+----
+
+DMX_GET_CAPS
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(fd, int request = DMX_GET_CAPS, dmx_caps_t *)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals DMX_GET_CAPS for this command.
+
+ - .. row 3
+
+ - dmx_caps_t *
+
+ - Undocumented.
+
+
+Description
+-----------
+
+This ioctl is undocumented. Documentation is welcome.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _DMX_GET_EVENT:
+
+=============
+DMX_GET_EVENT
+=============
+
+Name
+----
+
+DMX_GET_EVENT
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl( int fd, int request = DMX_GET_EVENT, struct dmx_event *ev)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals DMX_GET_EVENT for this command.
+
+ - .. row 3
+
+ - struct dmx_event \*ev
+
+ - Pointer to the location where the event is to be stored.
+
+
+Description
+-----------
+
+This ioctl call returns an event if available. If an event is not
+available, the behavior depends on whether the device is in blocking or
+non-blocking mode. In the latter case, the call fails immediately with
+errno set to ``EWOULDBLOCK``. In the former case, the call blocks until an
+event becomes available.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``EWOULDBLOCK``
+
+ - There is no event pending, and the device is in non-blocking mode.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _DMX_GET_PES_PIDS:
+
+================
+DMX_GET_PES_PIDS
+================
+
+Name
+----
+
+DMX_GET_PES_PIDS
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(fd, int request = DMX_GET_PES_PIDS, __u16[5])
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals DMX_GET_PES_PIDS for this command.
+
+ - .. row 3
+
+ - __u16[5]
+
+ - Undocumented.
+
+
+Description
+-----------
+
+This ioctl is undocumented. Documentation is welcome.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _DMX_GET_STC:
+
+===========
+DMX_GET_STC
+===========
+
+Name
+----
+
+DMX_GET_STC
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl( int fd, int request = DMX_GET_STC, struct dmx_stc *stc)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals DMX_GET_STC for this command.
+
+ - .. row 3
+
+ - struct dmx_stc \*stc
+
+ - Pointer to the location where the stc is to be stored.
+
+
+Description
+-----------
+
+This ioctl call returns the current value of the system time counter
+(which is driven by a PES filter of type DMX_PES_PCR). Some hardware
+supports more than one STC, so you must specify which one by setting the
+num field of stc before the ioctl (range 0...n). The result is returned
+in form of a ratio with a 64 bit numerator and a 32 bit denominator, so
+the real 90kHz STC value is stc->stc / stc->base .
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``EINVAL``
+
+ - Invalid stc number.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _DMX_REMOVE_PID:
+
+==============
+DMX_REMOVE_PID
+==============
+
+Name
+----
+
+DMX_REMOVE_PID
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(fd, int request = DMX_REMOVE_PID, __u16 *)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals DMX_REMOVE_PID for this command.
+
+ - .. row 3
+
+ - __u16 *
+
+ - PID of the PES filter to be removed.
+
+
+Description
+-----------
+
+This ioctl call allows to remove a PID when multiple PIDs are set on a
+transport stream filter, e. g. a filter previously set up with output
+equal to DMX_OUT_TSDEMUX_TAP, created via either
+DMX_SET_PES_FILTER or DMX_ADD_PID.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _DMX_SET_BUFFER_SIZE:
+
+===================
+DMX_SET_BUFFER_SIZE
+===================
+
+Name
+----
+
+DMX_SET_BUFFER_SIZE
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl( int fd, int request = DMX_SET_BUFFER_SIZE, unsigned long size)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals DMX_SET_BUFFER_SIZE for this command.
+
+ - .. row 3
+
+ - unsigned long size
+
+ - Size of circular buffer.
+
+
+Description
+-----------
+
+This ioctl call is used to set the size of the circular buffer used for
+filtered data. The default size is two maximum sized sections, i.e. if
+this function is not called a buffer size of 2 \* 4096 bytes will be
+used.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _DMX_SET_FILTER:
+
+==============
+DMX_SET_FILTER
+==============
+
+Name
+----
+
+DMX_SET_FILTER
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl( int fd, int request = DMX_SET_FILTER, struct dmx_sct_filter_params *params)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals DMX_SET_FILTER for this command.
+
+ - .. row 3
+
+ - struct dmx_sct_filter_params \*params
+
+ - Pointer to structure containing filter parameters.
+
+
+Description
+-----------
+
+This ioctl call sets up a filter according to the filter and mask
+parameters provided. A timeout may be defined stating number of seconds
+to wait for a section to be loaded. A value of 0 means that no timeout
+should be applied. Finally there is a flag field where it is possible to
+state whether a section should be CRC-checked, whether the filter should
+be a ”one-shot” filter, i.e. if the filtering operation should be
+stopped after the first section is received, and whether the filtering
+operation should be started immediately (without waiting for a
+DMX_START ioctl call). If a filter was previously set-up, this filter
+will be canceled, and the receive buffer will be flushed.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _DMX_SET_PES_FILTER:
+
+==================
+DMX_SET_PES_FILTER
+==================
+
+Name
+----
+
+DMX_SET_PES_FILTER
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl( int fd, int request = DMX_SET_PES_FILTER, struct dmx_pes_filter_params *params)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals DMX_SET_PES_FILTER for this command.
+
+ - .. row 3
+
+ - struct dmx_pes_filter_params \*params
+
+ - Pointer to structure containing filter parameters.
+
+
+Description
+-----------
+
+This ioctl call sets up a PES filter according to the parameters
+provided. By a PES filter is meant a filter that is based just on the
+packet identifier (PID), i.e. no PES header or payload filtering
+capability is supported.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``EBUSY``
+
+ - This error code indicates that there are conflicting requests.
+ There are active filters filtering data from another input source.
+ Make sure that these filters are stopped before starting this
+ filter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _DMX_SET_SOURCE:
+
+==============
+DMX_SET_SOURCE
+==============
+
+Name
+----
+
+DMX_SET_SOURCE
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(fd, int request = DMX_SET_SOURCE, dmx_source_t *)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals DMX_SET_SOURCE for this command.
+
+ - .. row 3
+
+ - dmx_source_t *
+
+ - Undocumented.
+
+
+Description
+-----------
+
+This ioctl is undocumented. Documentation is welcome.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _DMX_START:
+
+=========
+DMX_START
+=========
+
+Name
+----
+
+DMX_START
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl( int fd, int request = DMX_START)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals DMX_START for this command.
+
+
+Description
+-----------
+
+This ioctl call is used to start the actual filtering operation defined
+via the ioctl calls DMX_SET_FILTER or DMX_SET_PES_FILTER.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``EINVAL``
+
+ - Invalid argument, i.e. no filtering parameters provided via the
+ DMX_SET_FILTER or DMX_SET_PES_FILTER functions.
+
+ - .. row 2
+
+ - ``EBUSY``
+
+ - This error code indicates that there are conflicting requests.
+ There are active filters filtering data from another input source.
+ Make sure that these filters are stopped before starting this
+ filter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _DMX_STOP:
+
+========
+DMX_STOP
+========
+
+Name
+----
+
+DMX_STOP
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl( int fd, int request = DMX_STOP)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals DMX_STOP for this command.
+
+
+Description
+-----------
+
+This ioctl call is used to stop the actual filtering operation defined
+via the ioctl calls DMX_SET_FILTER or DMX_SET_PES_FILTER and
+started via the DMX_START command.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _dmx_fcalls:
+
+********************
+Demux Function Calls
+********************
+
+.. toctree::
+ :maxdepth: 1
+
+ dmx-fopen
+ dmx-fclose
+ dmx-fread
+ dmx-fwrite
+ dmx-start
+ dmx-stop
+ dmx-set-filter
+ dmx-set-pes-filter
+ dmx-set-buffer-size
+ dmx-get-event
+ dmx-get-stc
+ dmx-get-pes-pids
+ dmx-get-caps
+ dmx-set-source
+ dmx-add-pid
+ dmx-remove-pid
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _dmx_h:
+
+*********************
+DVB Demux Header File
+*********************
+
+.. kernel-include:: $BUILDDIR/dmx.h.rst
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _dmx_types:
+
+****************
+Demux Data Types
+****************
+
+
+.. _dmx-output-t:
+
+Output for the demux
+====================
+
+
+.. _dmx-output:
+
+.. flat-table:: enum dmx_output
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - .. _DMX-OUT-DECODER:
+
+ DMX_OUT_DECODER
+
+ - Streaming directly to decoder.
+
+ - .. row 3
+
+ - .. _DMX-OUT-TAP:
+
+ DMX_OUT_TAP
+
+ - Output going to a memory buffer (to be retrieved via the read
+ command). Delivers the stream output to the demux device on which
+ the ioctl is called.
+
+ - .. row 4
+
+ - .. _DMX-OUT-TS-TAP:
+
+ DMX_OUT_TS_TAP
+
+ - Output multiplexed into a new TS (to be retrieved by reading from
+ the logical DVR device). Routes output to the logical DVR device
+ ``/dev/dvb/adapter?/dvr?``, which delivers a TS multiplexed from
+ all filters for which ``DMX_OUT_TS_TAP`` was specified.
+
+ - .. row 5
+
+ - .. _DMX-OUT-TSDEMUX-TAP:
+
+ DMX_OUT_TSDEMUX_TAP
+
+ - Like :ref:`DMX_OUT_TS_TAP <DMX-OUT-TS-TAP>` but retrieved
+ from the DMX device.
+
+
+
+.. _dmx-input-t:
+
+dmx_input_t
+===========
+
+
+.. code-block:: c
+
+ typedef enum
+ {
+ DMX_IN_FRONTEND, /* Input from a front-end device. */
+ DMX_IN_DVR /* Input from the logical DVR device. */
+ } dmx_input_t;
+
+
+.. _dmx-pes-type-t:
+
+dmx_pes_type_t
+==============
+
+
+.. code-block:: c
+
+ typedef enum
+ {
+ DMX_PES_AUDIO0,
+ DMX_PES_VIDEO0,
+ DMX_PES_TELETEXT0,
+ DMX_PES_SUBTITLE0,
+ DMX_PES_PCR0,
+
+ DMX_PES_AUDIO1,
+ DMX_PES_VIDEO1,
+ DMX_PES_TELETEXT1,
+ DMX_PES_SUBTITLE1,
+ DMX_PES_PCR1,
+
+ DMX_PES_AUDIO2,
+ DMX_PES_VIDEO2,
+ DMX_PES_TELETEXT2,
+ DMX_PES_SUBTITLE2,
+ DMX_PES_PCR2,
+
+ DMX_PES_AUDIO3,
+ DMX_PES_VIDEO3,
+ DMX_PES_TELETEXT3,
+ DMX_PES_SUBTITLE3,
+ DMX_PES_PCR3,
+
+ DMX_PES_OTHER
+ } dmx_pes_type_t;
+
+
+.. _dmx-filter:
+
+struct dmx_filter
+=================
+
+
+.. code-block:: c
+
+ typedef struct dmx_filter
+ {
+ __u8 filter[DMX_FILTER_SIZE];
+ __u8 mask[DMX_FILTER_SIZE];
+ __u8 mode[DMX_FILTER_SIZE];
+ } dmx_filter_t;
+
+
+.. _dmx-sct-filter-params:
+
+struct dmx_sct_filter_params
+============================
+
+
+.. code-block:: c
+
+ struct dmx_sct_filter_params
+ {
+ __u16 pid;
+ dmx_filter_t filter;
+ __u32 timeout;
+ __u32 flags;
+ #define DMX_CHECK_CRC 1
+ #define DMX_ONESHOT 2
+ #define DMX_IMMEDIATE_START 4
+ #define DMX_KERNEL_CLIENT 0x8000
+ };
+
+
+.. _dmx-pes-filter-params:
+
+struct dmx_pes_filter_params
+============================
+
+
+.. code-block:: c
+
+ struct dmx_pes_filter_params
+ {
+ __u16 pid;
+ dmx_input_t input;
+ dmx_output_t output;
+ dmx_pes_type_t pes_type;
+ __u32 flags;
+ };
+
+
+.. _dmx-event:
+
+struct dmx_event
+================
+
+
+.. code-block:: c
+
+ struct dmx_event
+ {
+ dmx_event_t event;
+ time_t timeStamp;
+ union
+ {
+ dmx_scrambling_status_t scrambling;
+ } u;
+ };
+
+
+.. _dmx-stc:
+
+struct dmx_stc
+==============
+
+
+.. code-block:: c
+
+ struct dmx_stc {
+ unsigned int num; /* input : which STC? 0..N */
+ unsigned int base; /* output: divisor for stc to get 90 kHz clock */
+ __u64 stc; /* output: stc in 'base'*90 kHz units */
+ };
+
+
+.. _dmx-caps:
+
+struct dmx_caps
+===============
+
+
+.. code-block:: c
+
+ typedef struct dmx_caps {
+ __u32 caps;
+ int num_decoders;
+ } dmx_caps_t;
+
+
+.. _dmx-source-t:
+
+enum dmx_source_t
+=================
+
+
+.. code-block:: c
+
+ typedef enum {
+ DMX_SOURCE_FRONT0 = 0,
+ DMX_SOURCE_FRONT1,
+ DMX_SOURCE_FRONT2,
+ DMX_SOURCE_FRONT3,
+ DMX_SOURCE_DVR0 = 16,
+ DMX_SOURCE_DVR1,
+ DMX_SOURCE_DVR2,
+ DMX_SOURCE_DVR3
+ } dmx_source_t;
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _dtv-fe-stats:
+
+*******************
+struct dtv_fe_stats
+*******************
+
+
+.. code-block:: c
+
+ #define MAX_DTV_STATS 4
+
+ struct dtv_fe_stats {
+ __u8 len;
+ struct dtv_stats stat[MAX_DTV_STATS];
+ } __packed;
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _dtv-properties:
+
+*********************
+struct dtv_properties
+*********************
+
+
+.. code-block:: c
+
+ struct dtv_properties {
+ __u32 num;
+ struct dtv_property *props;
+ };
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _dtv-property:
+
+*******************
+struct dtv_property
+*******************
+
+
+.. code-block:: c
+
+ /* Reserved fields should be set to 0 */
+
+ struct dtv_property {
+ __u32 cmd;
+ __u32 reserved[3];
+ union {
+ __u32 data;
+ struct dtv_fe_stats st;
+ struct {
+ __u8 data[32];
+ __u32 len;
+ __u32 reserved1[3];
+ void *reserved2;
+ } buffer;
+ } u;
+ int result;
+ } __attribute__ ((packed));
+
+ /* num of properties cannot exceed DTV_IOCTL_MAX_MSGS per ioctl */
+ #define DTV_IOCTL_MAX_MSGS 64
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _dtv-stats:
+
+****************
+struct dtv_stats
+****************
+
+
+.. code-block:: c
+
+ struct dtv_stats {
+ __u8 scale; /* enum fecap_scale_params type */
+ union {
+ __u64 uvalue; /* for counters and relative scales */
+ __s64 svalue; /* for 1/1000 dB measures */
+ };
+ } __packed;
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _dvb-fe-read-status:
+
+***************************************
+Querying frontend status and statistics
+***************************************
+
+Once :ref:`FE_SET_PROPERTY <FE_GET_PROPERTY>` is called, the
+frontend will run a kernel thread that will periodically check for the
+tuner lock status and provide statistics about the quality of the
+signal.
+
+The information about the frontend tuner locking status can be queried
+using :ref:`FE_READ_STATUS`.
+
+Signal statistics are provided via
+:ref:`FE_GET_PROPERTY`. Please note that several
+statistics require the demodulator to be fully locked (e. g. with
+FE_HAS_LOCK bit set). See
+:ref:`Frontend statistics indicators <frontend-stat-properties>` for
+more details.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _dvb-frontend-event:
+
+***************
+frontend events
+***************
+
+
+.. code-block:: c
+
+ struct dvb_frontend_event {
+ fe_status_t status;
+ struct dvb_frontend_parameters parameters;
+ };
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _dvb-frontend-parameters:
+
+*******************
+frontend parameters
+*******************
+
+The kind of parameters passed to the frontend device for tuning depend
+on the kind of hardware you are using.
+
+The struct ``dvb_frontend_parameters`` uses an union with specific
+per-system parameters. However, as newer delivery systems required more
+data, the structure size weren't enough to fit, and just extending its
+size would break the existing applications. So, those parameters were
+replaced by the usage of
+:ref:`FE_GET_PROPERTY/FE_SET_PROPERTY <FE_GET_PROPERTY>`
+ioctl's. The new API is flexible enough to add new parameters to
+existing delivery systems, and to add newer delivery systems.
+
+So, newer applications should use
+:ref:`FE_GET_PROPERTY/FE_SET_PROPERTY <FE_GET_PROPERTY>`
+instead, in order to be able to support the newer System Delivery like
+DVB-S2, DVB-T2, DVB-C2, ISDB, etc.
+
+All kinds of parameters are combined as an union in the
+FrontendParameters structure:
+
+
+.. code-block:: c
+
+ struct dvb_frontend_parameters {
+ uint32_t frequency; /* (absolute) frequency in Hz for QAM/OFDM */
+ /* intermediate frequency in kHz for QPSK */
+ fe_spectral_inversion_t inversion;
+ union {
+ struct dvb_qpsk_parameters qpsk;
+ struct dvb_qam_parameters qam;
+ struct dvb_ofdm_parameters ofdm;
+ struct dvb_vsb_parameters vsb;
+ } u;
+ };
+
+In the case of QPSK frontends the ``frequency`` field specifies the
+intermediate frequency, i.e. the offset which is effectively added to
+the local oscillator frequency (LOF) of the LNB. The intermediate
+frequency has to be specified in units of kHz. For QAM and OFDM
+frontends the ``frequency`` specifies the absolute frequency and is
+given in Hz.
+
+
+.. _dvb-qpsk-parameters:
+
+QPSK parameters
+===============
+
+For satellite QPSK frontends you have to use the ``dvb_qpsk_parameters``
+structure:
+
+
+.. code-block:: c
+
+ struct dvb_qpsk_parameters {
+ uint32_t symbol_rate; /* symbol rate in Symbols per second */
+ fe_code_rate_t fec_inner; /* forward error correction (see above) */
+ };
+
+
+.. _dvb-qam-parameters:
+
+QAM parameters
+==============
+
+for cable QAM frontend you use the ``dvb_qam_parameters`` structure:
+
+
+.. code-block:: c
+
+ struct dvb_qam_parameters {
+ uint32_t symbol_rate; /* symbol rate in Symbols per second */
+ fe_code_rate_t fec_inner; /* forward error correction (see above) */
+ fe_modulation_t modulation; /* modulation type (see above) */
+ };
+
+
+.. _dvb-vsb-parameters:
+
+VSB parameters
+==============
+
+ATSC frontends are supported by the ``dvb_vsb_parameters`` structure:
+
+
+.. code-block:: c
+
+ struct dvb_vsb_parameters {
+ fe_modulation_t modulation; /* modulation type (see above) */
+ };
+
+
+.. _dvb-ofdm-parameters:
+
+OFDM parameters
+===============
+
+DVB-T frontends are supported by the ``dvb_ofdm_parameters`` structure:
+
+
+.. code-block:: c
+
+ struct dvb_ofdm_parameters {
+ fe_bandwidth_t bandwidth;
+ fe_code_rate_t code_rate_HP; /* high priority stream code rate */
+ fe_code_rate_t code_rate_LP; /* low priority stream code rate */
+ fe_modulation_t constellation; /* modulation type (see above) */
+ fe_transmit_mode_t transmission_mode;
+ fe_guard_interval_t guard_interval;
+ fe_hierarchy_t hierarchy_information;
+ };
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. include:: <isonum.txt>
+
+.. _dvbapi:
+
+##############
+Digital TV API
+##############
+
+**NOTE:** This API is also known as **DVB API**, although it is generic
+enough to support all digital TV standards.
+
+**Version 5.10**
+
+.. toctree::
+ :maxdepth: 1
+ :numbered:
+
+ intro
+ frontend
+ demux
+ ca
+ net
+ legacy_dvb_apis
+ examples
+ audio_h
+ ca_h
+ dmx_h
+ frontend_h
+ net_h
+ video_h
+
+
+**********************
+Revision and Copyright
+**********************
+
+Authors:
+
+- J. K. Metzler, Ralph <rjkm@metzlerbros.de>
+
+ - Original author of the DVB API documentation.
+
+- O. C. Metzler, Marcus <rjkm@metzlerbros.de>
+
+ - Original author of the DVB API documentation.
+
+- Carvalho Chehab, Mauro <m.chehab@kernel.org>
+
+ - Ported document to Docbook XML, addition of DVBv5 API, documentation gaps fix.
+
+**Copyright** |copy| 2002-2003 : Convergence GmbH
+
+**Copyright** |copy| 2009-2016 : Mauro Carvalho Chehab
+
+****************
+Revision History
+****************
+
+:revision: 2.1.0 / 2015-05-29 (*mcc*)
+
+DocBook improvements and cleanups, in order to document the system calls
+on a more standard way and provide more description about the current
+DVB API.
+
+:revision: 2.0.4 / 2011-05-06 (*mcc*)
+
+Add more information about DVB APIv5, better describing the frontend
+GET/SET props ioctl's.
+
+
+:revision: 2.0.3 / 2010-07-03 (*mcc*)
+
+Add some frontend capabilities flags, present on kernel, but missing at
+the specs.
+
+
+:revision: 2.0.2 / 2009-10-25 (*mcc*)
+
+documents FE_SET_FRONTEND_TUNE_MODE and
+FE_DISHETWORK_SEND_LEGACY_CMD ioctls.
+
+
+:revision: 2.0.1 / 2009-09-16 (*mcc*)
+
+Added ISDB-T test originally written by Patrick Boettcher
+
+
+:revision: 2.0.0 / 2009-09-06 (*mcc*)
+
+Conversion from LaTex to DocBook XML. The contents is the same as the
+original LaTex version.
+
+
+:revision: 1.0.0 / 2003-07-24 (*rjkm*)
+
+Initial revision on LaTEX.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+**************
+Property types
+**************
+
+On :ref:`FE_GET_PROPERTY and FE_SET_PROPERTY <FE_GET_PROPERTY>`,
+the actual action is determined by the dtv_property cmd/data pairs.
+With one single ioctl, is possible to get/set up to 64 properties. The
+actual meaning of each property is described on the next sections.
+
+The available frontend property types are shown on the next section.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _frontend-properties:
+
+DVB Frontend properties
+=======================
+
+Tuning into a Digital TV physical channel and starting decoding it
+requires changing a set of parameters, in order to control the tuner,
+the demodulator, the Linear Low-noise Amplifier (LNA) and to set the
+antenna subsystem via Satellite Equipment Control (SEC), on satellite
+systems. The actual parameters are specific to each particular digital
+TV standards, and may change as the digital TV specs evolves.
+
+In the past, the strategy used was to have a union with the parameters
+needed to tune for DVB-S, DVB-C, DVB-T and ATSC delivery systems grouped
+there. The problem is that, as the second generation standards appeared,
+those structs were not big enough to contain the additional parameters.
+Also, the union didn't have any space left to be expanded without
+breaking userspace. So, the decision was to deprecate the legacy
+union/struct based approach, in favor of a properties set approach.
+
+NOTE: on Linux DVB API version 3, setting a frontend were done via
+:ref:`struct dvb_frontend_parameters <dvb-frontend-parameters>`.
+This got replaced on version 5 (also called "S2API", as this API were
+added originally_enabled to provide support for DVB-S2), because the
+old API has a very limited support to new standards and new hardware.
+This section describes the new and recommended way to set the frontend,
+with suppports all digital TV delivery systems.
+
+Example: with the properties based approach, in order to set the tuner
+to a DVB-C channel at 651 kHz, modulated with 256-QAM, FEC 3/4 and
+symbol rate of 5.217 Mbauds, those properties should be sent to
+:ref:`FE_SET_PROPERTY <FE_GET_PROPERTY>` ioctl:
+
+- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>` =
+ SYS_DVBC_ANNEX_A
+
+- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>` = 651000000
+
+- :ref:`DTV_MODULATION <DTV-MODULATION>` = QAM_256
+
+- :ref:`DTV_INVERSION <DTV-INVERSION>` = INVERSION_AUTO
+
+- :ref:`DTV_SYMBOL_RATE <DTV-SYMBOL-RATE>` = 5217000
+
+- :ref:`DTV_INNER_FEC <DTV-INNER-FEC>` = FEC_3_4
+
+- :ref:`DTV_TUNE <DTV-TUNE>`
+
+The code that would do the above is:
+
+
+.. code-block:: c
+
+ #include <stdio.h>
+ #include <fcntl.h>
+ #include <sys/ioctl.h>
+ #include <linux/dvb/frontend.h>
+
+ static struct dtv_property props[] = {
+ { .cmd = DTV_DELIVERY_SYSTEM, .u.data = SYS_DVBC_ANNEX_A },
+ { .cmd = DTV_FREQUENCY, .u.data = 651000000 },
+ { .cmd = DTV_MODULATION, .u.data = QAM_256 },
+ { .cmd = DTV_INVERSION, .u.data = INVERSION_AUTO },
+ { .cmd = DTV_SYMBOL_RATE, .u.data = 5217000 },
+ { .cmd = DTV_INNER_FEC, .u.data = FEC_3_4 },
+ { .cmd = DTV_TUNE }
+ };
+
+ static struct dtv_properties dtv_prop = {
+ .num = 6, .props = props
+ };
+
+ int main(void)
+ {
+ int fd = open("/dev/dvb/adapter0/frontend0", O_RDWR);
+
+ if (!fd) {
+ perror ("open");
+ return -1;
+ }
+ if (ioctl(fd, FE_SET_PROPERTY, &dtv_prop) == -1) {
+ perror("ioctl");
+ return -1;
+ }
+ printf("Frontend set\\n");
+ return 0;
+ }
+
+NOTE: While it is possible to directly call the Kernel code like the
+above example, it is strongly recommended to use
+`libdvbv5 <https://linuxtv.org/docs/libdvbv5/index.html>`__, as it
+provides abstraction to work with the supported digital TV standards and
+provides methods for usual operations like program scanning and to
+read/write channel descriptor files.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ dtv-stats
+ dtv-fe-stats
+ dtv-property
+ dtv-properties
+ dvbproperty-006
+ fe_property_parameters
+ frontend-stat-properties
+ frontend-property-terrestrial-systems
+ frontend-property-cable-systems
+ frontend-property-satellite-systems
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _dvb_examples:
+
+********
+Examples
+********
+
+In this section we would like to present some examples for using the DVB
+API.
+
+NOTE: This section is out of date, and the code below won't even
+compile. Please refer to the
+`libdvbv5 <https://linuxtv.org/docs/libdvbv5/index.html>`__ for
+updated/recommended examples.
+
+
+.. _tuning:
+
+Tuning
+======
+
+We will start with a generic tuning subroutine that uses the frontend
+and SEC, as well as the demux devices. The example is given for QPSK
+tuners, but can easily be adjusted for QAM.
+
+
+.. code-block:: c
+
+ #include <sys/ioctl.h>
+ #include <stdio.h>
+ #include <stdint.h>
+ #include <sys/types.h>
+ #include <sys/stat.h>
+ #include <fcntl.h>
+ #include <time.h>
+ #include <unistd.h>
+
+ #include <linux/dvb/dmx.h>
+ #include <linux/dvb/frontend.h>
+ #include <linux/dvb/sec.h>
+ #include <sys/poll.h>
+
+ #define DMX "/dev/dvb/adapter0/demux1"
+ #define FRONT "/dev/dvb/adapter0/frontend1"
+ #define SEC "/dev/dvb/adapter0/sec1"
+
+ /* routine for checking if we have a signal and other status information*/
+ int FEReadStatus(int fd, fe_status_t *stat)
+ {
+ int ans;
+
+ if ( (ans = ioctl(fd,FE_READ_STATUS,stat) < 0)){
+ perror("FE READ STATUS: ");
+ return -1;
+ }
+
+ if (*stat & FE_HAS_POWER)
+ printf("FE HAS POWER\\n");
+
+ if (*stat & FE_HAS_SIGNAL)
+ printf("FE HAS SIGNAL\\n");
+
+ if (*stat & FE_SPECTRUM_INV)
+ printf("SPEKTRUM INV\\n");
+
+ return 0;
+ }
+
+
+ /* tune qpsk */
+ /* freq: frequency of transponder */
+ /* vpid, apid, tpid: PIDs of video, audio and teletext TS packets */
+ /* diseqc: DiSEqC address of the used LNB */
+ /* pol: Polarisation */
+ /* srate: Symbol Rate */
+ /* fec. FEC */
+ /* lnb_lof1: local frequency of lower LNB band */
+ /* lnb_lof2: local frequency of upper LNB band */
+ /* lnb_slof: switch frequency of LNB */
+
+ int set_qpsk_channel(int freq, int vpid, int apid, int tpid,
+ int diseqc, int pol, int srate, int fec, int lnb_lof1,
+ int lnb_lof2, int lnb_slof)
+ {
+ struct secCommand scmd;
+ struct secCmdSequence scmds;
+ struct dmx_pes_filter_params pesFilterParams;
+ FrontendParameters frp;
+ struct pollfd pfd[1];
+ FrontendEvent event;
+ int demux1, demux2, demux3, front;
+
+ frequency = (uint32_t) freq;
+ symbolrate = (uint32_t) srate;
+
+ if((front = open(FRONT,O_RDWR)) < 0){
+ perror("FRONTEND DEVICE: ");
+ return -1;
+ }
+
+ if((sec = open(SEC,O_RDWR)) < 0){
+ perror("SEC DEVICE: ");
+ return -1;
+ }
+
+ if (demux1 < 0){
+ if ((demux1=open(DMX, O_RDWR|O_NONBLOCK))
+ < 0){
+ perror("DEMUX DEVICE: ");
+ return -1;
+ }
+ }
+
+ if (demux2 < 0){
+ if ((demux2=open(DMX, O_RDWR|O_NONBLOCK))
+ < 0){
+ perror("DEMUX DEVICE: ");
+ return -1;
+ }
+ }
+
+ if (demux3 < 0){
+ if ((demux3=open(DMX, O_RDWR|O_NONBLOCK))
+ < 0){
+ perror("DEMUX DEVICE: ");
+ return -1;
+ }
+ }
+
+ if (freq < lnb_slof) {
+ frp.Frequency = (freq - lnb_lof1);
+ scmds.continuousTone = SEC_TONE_OFF;
+ } else {
+ frp.Frequency = (freq - lnb_lof2);
+ scmds.continuousTone = SEC_TONE_ON;
+ }
+ frp.Inversion = INVERSION_AUTO;
+ if (pol) scmds.voltage = SEC_VOLTAGE_18;
+ else scmds.voltage = SEC_VOLTAGE_13;
+
+ scmd.type=0;
+ scmd.u.diseqc.addr=0x10;
+ scmd.u.diseqc.cmd=0x38;
+ scmd.u.diseqc.numParams=1;
+ scmd.u.diseqc.params[0] = 0xF0 | ((diseqc * 4) & 0x0F) |
+ (scmds.continuousTone == SEC_TONE_ON ? 1 : 0) |
+ (scmds.voltage==SEC_VOLTAGE_18 ? 2 : 0);
+
+ scmds.miniCommand=SEC_MINI_NONE;
+ scmds.numCommands=1;
+ scmds.commands=&scmd;
+ if (ioctl(sec, SEC_SEND_SEQUENCE, &scmds) < 0){
+ perror("SEC SEND: ");
+ return -1;
+ }
+
+ if (ioctl(sec, SEC_SEND_SEQUENCE, &scmds) < 0){
+ perror("SEC SEND: ");
+ return -1;
+ }
+
+ frp.u.qpsk.SymbolRate = srate;
+ frp.u.qpsk.FEC_inner = fec;
+
+ if (ioctl(front, FE_SET_FRONTEND, &frp) < 0){
+ perror("QPSK TUNE: ");
+ return -1;
+ }
+
+ pfd[0].fd = front;
+ pfd[0].events = POLLIN;
+
+ if (poll(pfd,1,3000)){
+ if (pfd[0].revents & POLLIN){
+ printf("Getting QPSK event\\n");
+ if ( ioctl(front, FE_GET_EVENT, &event)
+
+ == -EOVERFLOW){
+ perror("qpsk get event");
+ return -1;
+ }
+ printf("Received ");
+ switch(event.type){
+ case FE_UNEXPECTED_EV:
+ printf("unexpected event\\n");
+ return -1;
+ case FE_FAILURE_EV:
+ printf("failure event\\n");
+ return -1;
+
+ case FE_COMPLETION_EV:
+ printf("completion event\\n");
+ }
+ }
+ }
+
+
+ pesFilterParams.pid = vpid;
+ pesFilterParams.input = DMX_IN_FRONTEND;
+ pesFilterParams.output = DMX_OUT_DECODER;
+ pesFilterParams.pes_type = DMX_PES_VIDEO;
+ pesFilterParams.flags = DMX_IMMEDIATE_START;
+ if (ioctl(demux1, DMX_SET_PES_FILTER, &pesFilterParams) < 0){
+ perror("set_vpid");
+ return -1;
+ }
+
+ pesFilterParams.pid = apid;
+ pesFilterParams.input = DMX_IN_FRONTEND;
+ pesFilterParams.output = DMX_OUT_DECODER;
+ pesFilterParams.pes_type = DMX_PES_AUDIO;
+ pesFilterParams.flags = DMX_IMMEDIATE_START;
+ if (ioctl(demux2, DMX_SET_PES_FILTER, &pesFilterParams) < 0){
+ perror("set_apid");
+ return -1;
+ }
+
+ pesFilterParams.pid = tpid;
+ pesFilterParams.input = DMX_IN_FRONTEND;
+ pesFilterParams.output = DMX_OUT_DECODER;
+ pesFilterParams.pes_type = DMX_PES_TELETEXT;
+ pesFilterParams.flags = DMX_IMMEDIATE_START;
+ if (ioctl(demux3, DMX_SET_PES_FILTER, &pesFilterParams) < 0){
+ perror("set_tpid");
+ return -1;
+ }
+
+ return has_signal(fds);
+ }
+
+The program assumes that you are using a universal LNB and a standard
+DiSEqC switch with up to 4 addresses. Of course, you could build in some
+more checking if tuning was successful and maybe try to repeat the
+tuning process. Depending on the external hardware, i.e. LNB and DiSEqC
+switch, and weather conditions this may be necessary.
+
+
+.. _the_dvr_device:
+
+The DVR device
+==============
+
+The following program code shows how to use the DVR device for
+recording.
+
+
+.. code-block:: c
+
+ #include <sys/ioctl.h>
+ #include <stdio.h>
+ #include <stdint.h>
+ #include <sys/types.h>
+ #include <sys/stat.h>
+ #include <fcntl.h>
+ #include <time.h>
+ #include <unistd.h>
+
+ #include <linux/dvb/dmx.h>
+ #include <linux/dvb/video.h>
+ #include <sys/poll.h>
+ #define DVR "/dev/dvb/adapter0/dvr1"
+ #define AUDIO "/dev/dvb/adapter0/audio1"
+ #define VIDEO "/dev/dvb/adapter0/video1"
+
+ #define BUFFY (188*20)
+ #define MAX_LENGTH (1024*1024*5) /* record 5MB */
+
+
+ /* switch the demuxes to recording, assuming the transponder is tuned */
+
+ /* demux1, demux2: file descriptor of video and audio filters */
+ /* vpid, apid: PIDs of video and audio channels */
+
+ int switch_to_record(int demux1, int demux2, uint16_t vpid, uint16_t apid)
+ {
+ struct dmx_pes_filter_params pesFilterParams;
+
+ if (demux1 < 0){
+ if ((demux1=open(DMX, O_RDWR|O_NONBLOCK))
+ < 0){
+ perror("DEMUX DEVICE: ");
+ return -1;
+ }
+ }
+
+ if (demux2 < 0){
+ if ((demux2=open(DMX, O_RDWR|O_NONBLOCK))
+ < 0){
+ perror("DEMUX DEVICE: ");
+ return -1;
+ }
+ }
+
+ pesFilterParams.pid = vpid;
+ pesFilterParams.input = DMX_IN_FRONTEND;
+ pesFilterParams.output = DMX_OUT_TS_TAP;
+ pesFilterParams.pes_type = DMX_PES_VIDEO;
+ pesFilterParams.flags = DMX_IMMEDIATE_START;
+ if (ioctl(demux1, DMX_SET_PES_FILTER, &pesFilterParams) < 0){
+ perror("DEMUX DEVICE");
+ return -1;
+ }
+ pesFilterParams.pid = apid;
+ pesFilterParams.input = DMX_IN_FRONTEND;
+ pesFilterParams.output = DMX_OUT_TS_TAP;
+ pesFilterParams.pes_type = DMX_PES_AUDIO;
+ pesFilterParams.flags = DMX_IMMEDIATE_START;
+ if (ioctl(demux2, DMX_SET_PES_FILTER, &pesFilterParams) < 0){
+ perror("DEMUX DEVICE");
+ return -1;
+ }
+ return 0;
+ }
+
+ /* start recording MAX_LENGTH , assuming the transponder is tuned */
+
+ /* demux1, demux2: file descriptor of video and audio filters */
+ /* vpid, apid: PIDs of video and audio channels */
+ int record_dvr(int demux1, int demux2, uint16_t vpid, uint16_t apid)
+ {
+ int i;
+ int len;
+ int written;
+ uint8_t buf[BUFFY];
+ uint64_t length;
+ struct pollfd pfd[1];
+ int dvr, dvr_out;
+
+ /* open dvr device */
+ if ((dvr = open(DVR, O_RDONLY|O_NONBLOCK)) < 0){
+ perror("DVR DEVICE");
+ return -1;
+ }
+
+ /* switch video and audio demuxes to dvr */
+ printf ("Switching dvr on\\n");
+ i = switch_to_record(demux1, demux2, vpid, apid);
+ printf("finished: ");
+
+ printf("Recording %2.0f MB of test file in TS format\\n",
+ MAX_LENGTH/(1024.0*1024.0));
+ length = 0;
+
+ /* open output file */
+ if ((dvr_out = open(DVR_FILE,O_WRONLY|O_CREAT
+ |O_TRUNC, S_IRUSR|S_IWUSR
+ |S_IRGRP|S_IWGRP|S_IROTH|
+ S_IWOTH)) < 0){
+ perror("Can't open file for dvr test");
+ return -1;
+ }
+
+ pfd[0].fd = dvr;
+ pfd[0].events = POLLIN;
+
+ /* poll for dvr data and write to file */
+ while (length < MAX_LENGTH ) {
+ if (poll(pfd,1,1)){
+ if (pfd[0].revents & POLLIN){
+ len = read(dvr, buf, BUFFY);
+ if (len < 0){
+ perror("recording");
+ return -1;
+ }
+ if (len > 0){
+ written = 0;
+ while (written < len)
+ written +=
+ write (dvr_out,
+ buf, len);
+ length += len;
+ printf("written %2.0f MB\\r",
+ length/1024./1024.);
+ }
+ }
+ }
+ }
+ return 0;
+ }
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _fe-bandwidth-t:
+
+******************
+Frontend bandwidth
+******************
+
+
+.. _fe-bandwidth:
+
+.. flat-table:: enum fe_bandwidth
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - .. _BANDWIDTH-AUTO:
+
+ ``BANDWIDTH_AUTO``
+
+ - Autodetect bandwidth (if supported)
+
+ - .. row 3
+
+ - .. _BANDWIDTH-1-712-MHZ:
+
+ ``BANDWIDTH_1_712_MHZ``
+
+ - 1.712 MHz
+
+ - .. row 4
+
+ - .. _BANDWIDTH-5-MHZ:
+
+ ``BANDWIDTH_5_MHZ``
+
+ - 5 MHz
+
+ - .. row 5
+
+ - .. _BANDWIDTH-6-MHZ:
+
+ ``BANDWIDTH_6_MHZ``
+
+ - 6 MHz
+
+ - .. row 6
+
+ - .. _BANDWIDTH-7-MHZ:
+
+ ``BANDWIDTH_7_MHZ``
+
+ - 7 MHz
+
+ - .. row 7
+
+ - .. _BANDWIDTH-8-MHZ:
+
+ ``BANDWIDTH_8_MHZ``
+
+ - 8 MHz
+
+ - .. row 8
+
+ - .. _BANDWIDTH-10-MHZ:
+
+ ``BANDWIDTH_10_MHZ``
+
+ - 10 MHz
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _FE_DISEQC_RECV_SLAVE_REPLY:
+
+********************************
+ioctl FE_DISEQC_RECV_SLAVE_REPLY
+********************************
+
+Name
+====
+
+FE_DISEQC_RECV_SLAVE_REPLY - Receives reply from a DiSEqC 2.0 command
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct dvb_diseqc_slave_reply *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <frontend_f_open>`.
+
+``request``
+ FE_DISEQC_RECV_SLAVE_REPLY
+
+``argp``
+ pointer to struct
+ :ref:`dvb_diseqc_slave_reply <dvb-diseqc-slave-reply>`
+
+
+Description
+===========
+
+Receives reply from a DiSEqC 2.0 command.
+
+.. _dvb-diseqc-slave-reply:
+
+struct dvb_diseqc_slave_reply
+-----------------------------
+
+.. flat-table:: struct dvb_diseqc_slave_reply
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - uint8_t
+
+ - msg[4]
+
+ - DiSEqC message (framing, data[3])
+
+ - .. row 2
+
+ - uint8_t
+
+ - msg_len
+
+ - Length of the DiSEqC message. Valid values are 0 to 4, where 0
+ means no msg
+
+ - .. row 3
+
+ - int
+
+ - timeout
+
+ - Return from ioctl after timeout ms with errorcode when no message
+ was received
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _FE_DISEQC_RESET_OVERLOAD:
+
+******************************
+ioctl FE_DISEQC_RESET_OVERLOAD
+******************************
+
+Name
+====
+
+FE_DISEQC_RESET_OVERLOAD - Restores the power to the antenna subsystem, if it was powered off due - to power overload.
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, NULL )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <frontend_f_open>`.
+
+``request``
+ FE_DISEQC_RESET_OVERLOAD
+
+
+Description
+===========
+
+If the bus has been automatically powered off due to power overload,
+this ioctl call restores the power to the bus. The call requires
+read/write access to the device. This call has no effect if the device
+is manually powered off. Not all DVB adapters support this ioctl.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _FE_DISEQC_SEND_BURST:
+
+**************************
+ioctl FE_DISEQC_SEND_BURST
+**************************
+
+Name
+====
+
+FE_DISEQC_SEND_BURST - Sends a 22KHz tone burst for 2x1 mini DiSEqC satellite selection.
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, enum fe_sec_mini_cmd *tone )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <frontend_f_open>`.
+
+``request``
+ FE_DISEQC_SEND_BURST
+
+``tone``
+ pointer to enum :ref:`fe_sec_mini_cmd <fe-sec-mini-cmd>`
+
+
+Description
+===========
+
+This ioctl is used to set the generation of a 22kHz tone burst for mini
+DiSEqC satellite selection for 2x1 switches. This call requires
+read/write permissions.
+
+It provides support for what's specified at
+`Digital Satellite Equipment Control (DiSEqC) - Simple "ToneBurst" Detection Circuit specification. <http://www.eutelsat.com/files/contributed/satellites/pdf/Diseqc/associated%20docs/simple_tone_burst_detec.pdf>`__
+
+.. _fe-sec-mini-cmd-t:
+
+enum fe_sec_mini_cmd
+====================
+
+.. _fe-sec-mini-cmd:
+
+.. flat-table:: enum fe_sec_mini_cmd
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - .. _SEC-MINI-A:
+
+ ``SEC_MINI_A``
+
+ - Sends a mini-DiSEqC 22kHz '0' Tone Burst to select satellite-A
+
+ - .. row 3
+
+ - .. _SEC-MINI-B:
+
+ ``SEC_MINI_B``
+
+ - Sends a mini-DiSEqC 22kHz '1' Data Burst to select satellite-B
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _FE_DISEQC_SEND_MASTER_CMD:
+
+*******************************
+ioctl FE_DISEQC_SEND_MASTER_CMD
+*******************************
+
+Name
+====
+
+FE_DISEQC_SEND_MASTER_CMD - Sends a DiSEqC command
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct dvb_diseqc_master_cmd *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <frontend_f_open>`.
+
+``request``
+ FE_DISEQC_SEND_MASTER_CMD
+
+``argp``
+ pointer to struct
+ :ref:`dvb_diseqc_master_cmd <dvb-diseqc-master-cmd>`
+
+
+Description
+===========
+
+Sends a DiSEqC command to the antenna subsystem.
+
+.. _dvb-diseqc-master-cmd:
+
+struct dvb_diseqc_master_cmd
+============================
+
+.. flat-table:: struct dvb_diseqc_master_cmd
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - uint8_t
+
+ - msg[6]
+
+ - DiSEqC message (framing, address, command, data[3])
+
+ - .. row 2
+
+ - uint8_t
+
+ - msg_len
+
+ - Length of the DiSEqC message. Valid values are 3 to 6
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _FE_DISHNETWORK_SEND_LEGACY_CMD:
+
+******************************
+FE_DISHNETWORK_SEND_LEGACY_CMD
+******************************
+
+Name
+====
+
+FE_DISHNETWORK_SEND_LEGACY_CMD
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl(int fd, int request = FE_DISHNETWORK_SEND_LEGACY_CMD, unsigned long cmd)
+
+
+Arguments
+=========
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - unsigned long cmd
+
+ - sends the specified raw cmd to the dish via DISEqC.
+
+
+Description
+===========
+
+WARNING: This is a very obscure legacy command, used only at stv0299
+driver. Should not be used on newer drivers.
+
+It provides a non-standard method for selecting Diseqc voltage on the
+frontend, for Dish Network legacy switches.
+
+As support for this ioctl were added in 2004, this means that such
+dishes were already legacy in 2004.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _FE_ENABLE_HIGH_LNB_VOLTAGE:
+
+********************************
+ioctl FE_ENABLE_HIGH_LNB_VOLTAGE
+********************************
+
+Name
+====
+
+FE_ENABLE_HIGH_LNB_VOLTAGE - Select output DC level between normal LNBf voltages or higher LNBf - voltages.
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, unsigned int high )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <frontend_f_open>`.
+
+``request``
+ FE_ENABLE_HIGH_LNB_VOLTAGE
+
+``high``
+ Valid flags:
+
+ - 0 - normal 13V and 18V.
+
+ - >0 - enables slightly higher voltages instead of 13/18V, in order
+ to compensate for long antenna cables.
+
+
+Description
+===========
+
+Select output DC level between normal LNBf voltages or higher LNBf
+voltages between 0 (normal) or a value grater than 0 for higher
+voltages.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _FE_GET_EVENT:
+
+************
+FE_GET_EVENT
+************
+
+Name
+====
+
+FE_GET_EVENT
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl(int fd, int request = QPSK_GET_EVENT, struct dvb_frontend_event *ev)
+
+
+Arguments
+=========
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals :ref:`FE_GET_EVENT` for this command.
+
+ - .. row 3
+
+ - struct dvb_frontend_event \*ev
+
+ - Points to the location where the event,
+
+ - .. row 4
+
+ -
+ - if any, is to be stored.
+
+
+Description
+===========
+
+This ioctl call returns a frontend event if available. If an event is
+not available, the behavior depends on whether the device is in blocking
+or non-blocking mode. In the latter case, the call fails immediately
+with errno set to ``EWOULDBLOCK``. In the former case, the call blocks until
+an event becomes available.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``EWOULDBLOCK``
+
+ - There is no event pending, and the device is in non-blocking mode.
+
+ - .. row 2
+
+ - ``EOVERFLOW``
+
+ - Overflow in event queue - one or more events were lost.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _FE_GET_FRONTEND:
+
+***************
+FE_GET_FRONTEND
+***************
+
+Name
+====
+
+FE_GET_FRONTEND
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl(int fd, int request = FE_GET_FRONTEND, struct dvb_frontend_parameters *p)
+
+
+Arguments
+=========
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals :ref:`FE_SET_FRONTEND` for this
+ command.
+
+ - .. row 3
+
+ - struct dvb_frontend_parameters \*p
+
+ - Points to parameters for tuning operation.
+
+
+Description
+===========
+
+This ioctl call queries the currently effective frontend parameters. For
+this command, read-only access to the device is sufficient.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``EINVAL``
+
+ - Maximum supported symbol rate reached.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _FE_GET_INFO:
+
+*****************
+ioctl FE_GET_INFO
+*****************
+
+Name
+====
+
+FE_GET_INFO - Query DVB frontend capabilities and returns information about the - front-end. This call only requires read-only access to the device
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct dvb_frontend_info *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <frontend_f_open>`.
+
+``request``
+ FE_GET_INFO
+
+``argp``
+ pointer to struct struct
+ :ref:`dvb_frontend_info <dvb-frontend-info>`
+
+
+Description
+===========
+
+All DVB frontend devices support the ``FE_GET_INFO`` ioctl. It is used
+to identify kernel devices compatible with this specification and to
+obtain information about driver and hardware capabilities. The ioctl
+takes a pointer to dvb_frontend_info which is filled by the driver.
+When the driver is not compatible with this specification the ioctl
+returns an error.
+
+.. _dvb-frontend-info:
+
+struct dvb_frontend_info
+========================
+
+.. flat-table:: struct dvb_frontend_info
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - char
+
+ - name[128]
+
+ - Name of the frontend
+
+ - .. row 2
+
+ - fe_type_t
+
+ - type
+
+ - **DEPRECATED**. DVBv3 type. Should not be used on modern programs,
+ as a frontend may have more than one type. So, the DVBv5 API
+ should be used instead to enumerate and select the frontend type.
+
+ - .. row 3
+
+ - uint32_t
+
+ - frequency_min
+
+ - Minimal frequency supported by the frontend
+
+ - .. row 4
+
+ - uint32_t
+
+ - frequency_max
+
+ - Maximal frequency supported by the frontend
+
+ - .. row 5
+
+ - uint32_t
+
+ - frequency_stepsize
+
+ - Frequency step - all frequencies are multiple of this value
+
+ - .. row 6
+
+ - uint32_t
+
+ - frequency_tolerance
+
+ - Tolerance of the frequency
+
+ - .. row 7
+
+ - uint32_t
+
+ - symbol_rate_min
+
+ - Minimal symbol rate (for Cable/Satellite systems), in bauds
+
+ - .. row 8
+
+ - uint32_t
+
+ - symbol_rate_max
+
+ - Maximal symbol rate (for Cable/Satellite systems), in bauds
+
+ - .. row 9
+
+ - uint32_t
+
+ - symbol_rate_tolerance
+
+ - Maximal symbol rate tolerance, in ppm
+
+ - .. row 10
+
+ - uint32_t
+
+ - notifier_delay
+
+ - **DEPRECATED**. Not used by any driver.
+
+ - .. row 11
+
+ - enum :ref:`fe_caps <fe-caps>`
+
+ - caps
+
+ - Capabilities supported by the frontend
+
+
+NOTE: The frequencies are specified in Hz for Terrestrial and Cable
+systems. They're specified in kHz for Satellite systems
+
+
+.. _fe-caps-t:
+
+frontend capabilities
+=====================
+
+Capabilities describe what a frontend can do. Some capabilities are
+supported only on some specific frontend types.
+
+
+.. _fe-caps:
+
+.. flat-table:: enum fe_caps
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - .. _FE-IS-STUPID:
+
+ ``FE_IS_STUPID``
+
+ - There's something wrong at the frontend, and it can't report its
+ capabilities
+
+ - .. row 3
+
+ - .. _FE-CAN-INVERSION-AUTO:
+
+ ``FE_CAN_INVERSION_AUTO``
+
+ - The frontend is capable of auto-detecting inversion
+
+ - .. row 4
+
+ - .. _FE-CAN-FEC-1-2:
+
+ ``FE_CAN_FEC_1_2``
+
+ - The frontend supports FEC 1/2
+
+ - .. row 5
+
+ - .. _FE-CAN-FEC-2-3:
+
+ ``FE_CAN_FEC_2_3``
+
+ - The frontend supports FEC 2/3
+
+ - .. row 6
+
+ - .. _FE-CAN-FEC-3-4:
+
+ ``FE_CAN_FEC_3_4``
+
+ - The frontend supports FEC 3/4
+
+ - .. row 7
+
+ - .. _FE-CAN-FEC-4-5:
+
+ ``FE_CAN_FEC_4_5``
+
+ - The frontend supports FEC 4/5
+
+ - .. row 8
+
+ - .. _FE-CAN-FEC-5-6:
+
+ ``FE_CAN_FEC_5_6``
+
+ - The frontend supports FEC 5/6
+
+ - .. row 9
+
+ - .. _FE-CAN-FEC-6-7:
+
+ ``FE_CAN_FEC_6_7``
+
+ - The frontend supports FEC 6/7
+
+ - .. row 10
+
+ - .. _FE-CAN-FEC-7-8:
+
+ ``FE_CAN_FEC_7_8``
+
+ - The frontend supports FEC 7/8
+
+ - .. row 11
+
+ - .. _FE-CAN-FEC-8-9:
+
+ ``FE_CAN_FEC_8_9``
+
+ - The frontend supports FEC 8/9
+
+ - .. row 12
+
+ - .. _FE-CAN-FEC-AUTO:
+
+ ``FE_CAN_FEC_AUTO``
+
+ - The frontend can autodetect FEC.
+
+ - .. row 13
+
+ - .. _FE-CAN-QPSK:
+
+ ``FE_CAN_QPSK``
+
+ - The frontend supports QPSK modulation
+
+ - .. row 14
+
+ - .. _FE-CAN-QAM-16:
+
+ ``FE_CAN_QAM_16``
+
+ - The frontend supports 16-QAM modulation
+
+ - .. row 15
+
+ - .. _FE-CAN-QAM-32:
+
+ ``FE_CAN_QAM_32``
+
+ - The frontend supports 32-QAM modulation
+
+ - .. row 16
+
+ - .. _FE-CAN-QAM-64:
+
+ ``FE_CAN_QAM_64``
+
+ - The frontend supports 64-QAM modulation
+
+ - .. row 17
+
+ - .. _FE-CAN-QAM-128:
+
+ ``FE_CAN_QAM_128``
+
+ - The frontend supports 128-QAM modulation
+
+ - .. row 18
+
+ - .. _FE-CAN-QAM-256:
+
+ ``FE_CAN_QAM_256``
+
+ - The frontend supports 256-QAM modulation
+
+ - .. row 19
+
+ - .. _FE-CAN-QAM-AUTO:
+
+ ``FE_CAN_QAM_AUTO``
+
+ - The frontend can autodetect modulation
+
+ - .. row 20
+
+ - .. _FE-CAN-TRANSMISSION-MODE-AUTO:
+
+ ``FE_CAN_TRANSMISSION_MODE_AUTO``
+
+ - The frontend can autodetect the transmission mode
+
+ - .. row 21
+
+ - .. _FE-CAN-BANDWIDTH-AUTO:
+
+ ``FE_CAN_BANDWIDTH_AUTO``
+
+ - The frontend can autodetect the bandwidth
+
+ - .. row 22
+
+ - .. _FE-CAN-GUARD-INTERVAL-AUTO:
+
+ ``FE_CAN_GUARD_INTERVAL_AUTO``
+
+ - The frontend can autodetect the guard interval
+
+ - .. row 23
+
+ - .. _FE-CAN-HIERARCHY-AUTO:
+
+ ``FE_CAN_HIERARCHY_AUTO``
+
+ - The frontend can autodetect hierarch
+
+ - .. row 24
+
+ - .. _FE-CAN-8VSB:
+
+ ``FE_CAN_8VSB``
+
+ - The frontend supports 8-VSB modulation
+
+ - .. row 25
+
+ - .. _FE-CAN-16VSB:
+
+ ``FE_CAN_16VSB``
+
+ - The frontend supports 16-VSB modulation
+
+ - .. row 26
+
+ - .. _FE-HAS-EXTENDED-CAPS:
+
+ ``FE_HAS_EXTENDED_CAPS``
+
+ - Currently, unused
+
+ - .. row 27
+
+ - .. _FE-CAN-MULTISTREAM:
+
+ ``FE_CAN_MULTISTREAM``
+
+ - The frontend supports multistream filtering
+
+ - .. row 28
+
+ - .. _FE-CAN-TURBO-FEC:
+
+ ``FE_CAN_TURBO_FEC``
+
+ - The frontend supports turbo FEC modulation
+
+ - .. row 29
+
+ - .. _FE-CAN-2G-MODULATION:
+
+ ``FE_CAN_2G_MODULATION``
+
+ - The frontend supports "2nd generation modulation" (DVB-S2/T2)>
+
+ - .. row 30
+
+ - .. _FE-NEEDS-BENDING:
+
+ ``FE_NEEDS_BENDING``
+
+ - Not supported anymore, don't use it
+
+ - .. row 31
+
+ - .. _FE-CAN-RECOVER:
+
+ ``FE_CAN_RECOVER``
+
+ - The frontend can recover from a cable unplug automatically
+
+ - .. row 32
+
+ - .. _FE-CAN-MUTE-TS:
+
+ ``FE_CAN_MUTE_TS``
+
+ - The frontend can stop spurious TS data output
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _FE_GET_PROPERTY:
+
+**************************************
+ioctl FE_SET_PROPERTY, FE_GET_PROPERTY
+**************************************
+
+Name
+====
+
+FE_SET_PROPERTY - FE_GET_PROPERTY - FE_SET_PROPERTY sets one or more frontend properties. - FE_GET_PROPERTY returns one or more frontend properties.
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct dtv_properties *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <frontend_f_open>`.
+
+``request``
+ FE_SET_PROPERTY, FE_GET_PROPERTY
+
+``argp``
+ pointer to struct :ref:`dtv_properties <dtv-properties>`
+
+
+Description
+===========
+
+All DVB frontend devices support the ``FE_SET_PROPERTY`` and
+``FE_GET_PROPERTY`` ioctls. The supported properties and statistics
+depends on the delivery system and on the device:
+
+- ``FE_SET_PROPERTY:``
+
+ - This ioctl is used to set one or more frontend properties.
+
+ - This is the basic command to request the frontend to tune into
+ some frequency and to start decoding the digital TV signal.
+
+ - This call requires read/write access to the device.
+
+ - At return, the values are updated to reflect the actual parameters
+ used.
+
+- ``FE_GET_PROPERTY:``
+
+ - This ioctl is used to get properties and statistics from the
+ frontend.
+
+ - No properties are changed, and statistics aren't reset.
+
+ - This call only requires read-only access to the device.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _FE_READ_BER:
+
+***********
+FE_READ_BER
+***********
+
+Name
+====
+
+FE_READ_BER
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl(int fd, int request = FE_READ_BER, uint32_t *ber)
+
+
+Arguments
+=========
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals :ref:`FE_READ_BER` for this command.
+
+ - .. row 3
+
+ - uint32_t \*ber
+
+ - The bit error rate is stored into \*ber.
+
+
+Description
+===========
+
+This ioctl call returns the bit error rate for the signal currently
+received/demodulated by the front-end. For this command, read-only
+access to the device is sufficient.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _FE_READ_SIGNAL_STRENGTH:
+
+***********************
+FE_READ_SIGNAL_STRENGTH
+***********************
+
+Name
+====
+
+FE_READ_SIGNAL_STRENGTH
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request = FE_READ_SIGNAL_STRENGTH, uint16_t *strength)
+
+
+Arguments
+=========
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals
+ :ref:`FE_READ_SIGNAL_STRENGTH`
+ for this command.
+
+ - .. row 3
+
+ - uint16_t \*strength
+
+ - The signal strength value is stored into \*strength.
+
+
+Description
+===========
+
+This ioctl call returns the signal strength value for the signal
+currently received by the front-end. For this command, read-only access
+to the device is sufficient.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _FE_READ_SNR:
+
+***********
+FE_READ_SNR
+***********
+
+Name
+====
+
+FE_READ_SNR
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl(int fd, int request = FE_READ_SNR, int16_t *snr)
+
+
+Arguments
+=========
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals :ref:`FE_READ_SNR` for this command.
+
+ - .. row 3
+
+ - uint16_t \*snr
+
+ - The signal-to-noise ratio is stored into \*snr.
+
+
+Description
+===========
+
+This ioctl call returns the signal-to-noise ratio for the signal
+currently received by the front-end. For this command, read-only access
+to the device is sufficient.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _FE_READ_STATUS:
+
+********************
+ioctl FE_READ_STATUS
+********************
+
+Name
+====
+
+FE_READ_STATUS - Returns status information about the front-end. This call only requires - read-only access to the device
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, unsigned int *status )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <frontend_f_open>`.
+
+``request``
+ FE_READ_STATUS
+
+``status``
+ pointer to a bitmask integer filled with the values defined by enum
+ :ref:`fe_status <fe-status>`.
+
+
+Description
+===========
+
+All DVB frontend devices support the ``FE_READ_STATUS`` ioctl. It is
+used to check about the locking status of the frontend after being
+tuned. The ioctl takes a pointer to an integer where the status will be
+written.
+
+NOTE: the size of status is actually sizeof(enum fe_status), with
+varies according with the architecture. This needs to be fixed in the
+future.
+
+
+.. _fe-status-t:
+
+int fe_status
+=============
+
+The fe_status parameter is used to indicate the current state and/or
+state changes of the frontend hardware. It is produced using the enum
+:ref:`fe_status <fe-status>` values on a bitmask
+
+
+.. _fe-status:
+
+.. flat-table:: enum fe_status
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - .. _FE-HAS-SIGNAL:
+
+ ``FE_HAS_SIGNAL``
+
+ - The frontend has found something above the noise level
+
+ - .. row 3
+
+ - .. _FE-HAS-CARRIER:
+
+ ``FE_HAS_CARRIER``
+
+ - The frontend has found a DVB signal
+
+ - .. row 4
+
+ - .. _FE-HAS-VITERBI:
+
+ ``FE_HAS_VITERBI``
+
+ - The frontend FEC inner coding (Viterbi, LDPC or other inner code)
+ is stable
+
+ - .. row 5
+
+ - .. _FE-HAS-SYNC:
+
+ ``FE_HAS_SYNC``
+
+ - Synchronization bytes was found
+
+ - .. row 6
+
+ - .. _FE-HAS-LOCK:
+
+ ``FE_HAS_LOCK``
+
+ - The DVB were locked and everything is working
+
+ - .. row 7
+
+ - .. _FE-TIMEDOUT:
+
+ ``FE_TIMEDOUT``
+
+ - no lock within the last about 2 seconds
+
+ - .. row 8
+
+ - .. _FE-REINIT:
+
+ ``FE_REINIT``
+
+ - The frontend was reinitialized, application is recommended to
+ reset DiSEqC, tone and parameters
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _FE_READ_UNCORRECTED_BLOCKS:
+
+**************************
+FE_READ_UNCORRECTED_BLOCKS
+**************************
+
+Name
+====
+
+FE_READ_UNCORRECTED_BLOCKS
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request =FE_READ_UNCORRECTED_BLOCKS, uint32_t *ublocks)
+
+
+Arguments
+=========
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals
+ :ref:`FE_READ_UNCORRECTED_BLOCKS`
+ for this command.
+
+ - .. row 3
+
+ - uint32_t \*ublocks
+
+ - The total number of uncorrected blocks seen by the driver so far.
+
+
+Description
+===========
+
+This ioctl call returns the number of uncorrected blocks detected by the
+device driver during its lifetime. For meaningful measurements, the
+increment in block count during a specific time interval should be
+calculated. For this command, read-only access to the device is
+sufficient.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _FE_SET_FRONTEND_TUNE_MODE:
+
+*******************************
+ioctl FE_SET_FRONTEND_TUNE_MODE
+*******************************
+
+Name
+====
+
+FE_SET_FRONTEND_TUNE_MODE - Allow setting tuner mode flags to the frontend.
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, unsigned int flags )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <frontend_f_open>`.
+
+``request``
+ FE_SET_FRONTEND_TUNE_MODE
+
+``flags``
+ Valid flags:
+
+ - 0 - normal tune mode
+
+ - FE_TUNE_MODE_ONESHOT - When set, this flag will disable any
+ zigzagging or other "normal" tuning behaviour. Additionally,
+ there will be no automatic monitoring of the lock status, and
+ hence no frontend events will be generated. If a frontend device
+ is closed, this flag will be automatically turned off when the
+ device is reopened read-write.
+
+
+Description
+===========
+
+Allow setting tuner mode flags to the frontend, between 0 (normal) or
+FE_TUNE_MODE_ONESHOT mode
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _FE_SET_FRONTEND:
+
+***************
+FE_SET_FRONTEND
+***************
+
+Name
+====
+
+FE_SET_FRONTEND
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl(int fd, int request = FE_SET_FRONTEND, struct dvb_frontend_parameters *p)
+
+
+Arguments
+=========
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals :ref:`FE_SET_FRONTEND` for this
+ command.
+
+ - .. row 3
+
+ - struct dvb_frontend_parameters \*p
+
+ - Points to parameters for tuning operation.
+
+
+Description
+===========
+
+This ioctl call starts a tuning operation using specified parameters.
+The result of this call will be successful if the parameters were valid
+and the tuning could be initiated. The result of the tuning operation in
+itself, however, will arrive asynchronously as an event (see
+documentation for :ref:`FE_GET_EVENT` and
+FrontendEvent.) If a new :ref:`FE_SET_FRONTEND`
+operation is initiated before the previous one was completed, the
+previous operation will be aborted in favor of the new one. This command
+requires read/write access to the device.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``EINVAL``
+
+ - Maximum supported symbol rate reached.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _FE_SET_TONE:
+
+*****************
+ioctl FE_SET_TONE
+*****************
+
+Name
+====
+
+FE_SET_TONE - Sets/resets the generation of the continuous 22kHz tone.
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, enum fe_sec_tone_mode *tone )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <frontend_f_open>`.
+
+``request``
+ FE_SET_TONE
+
+``tone``
+ pointer to enum :ref:`fe_sec_tone_mode <fe-sec-tone-mode>`
+
+
+Description
+===========
+
+This ioctl is used to set the generation of the continuous 22kHz tone.
+This call requires read/write permissions.
+
+Usually, satellite antenna subsystems require that the digital TV device
+to send a 22kHz tone in order to select between high/low band on some
+dual-band LNBf. It is also used to send signals to DiSEqC equipment, but
+this is done using the DiSEqC ioctls.
+
+NOTE: if more than one device is connected to the same antenna, setting
+a tone may interfere on other devices, as they may lose the capability
+of selecting the band. So, it is recommended that applications would
+change to SEC_TONE_OFF when the device is not used.
+
+.. _fe-sec-tone-mode-t:
+
+enum fe_sec_tone_mode
+=====================
+
+.. _fe-sec-tone-mode:
+
+.. flat-table:: enum fe_sec_tone_mode
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - .. _SEC-TONE-ON:
+
+ ``SEC_TONE_ON``
+
+ - Sends a 22kHz tone burst to the antenna
+
+ - .. row 3
+
+ - .. _SEC-TONE-OFF:
+
+ ``SEC_TONE_OFF``
+
+ - Don't send a 22kHz tone to the antenna (except if the
+ FE_DISEQC_* ioctls are called)
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _FE_SET_VOLTAGE:
+
+********************
+ioctl FE_SET_VOLTAGE
+********************
+
+Name
+====
+
+FE_SET_VOLTAGE - Allow setting the DC level sent to the antenna subsystem.
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, enum fe_sec_voltage *voltage )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <frontend_f_open>`.
+
+``request``
+ FE_SET_VOLTAGE
+
+``voltage``
+ pointer to enum :ref:`fe_sec_voltage <fe-sec-voltage>`
+
+ Valid values are described at enum
+ :ref:`fe_sec_voltage <fe-sec-voltage>`.
+
+
+Description
+===========
+
+This ioctl allows to set the DC voltage level sent through the antenna
+cable to 13V, 18V or off.
+
+Usually, a satellite antenna subsystems require that the digital TV
+device to send a DC voltage to feed power to the LNBf. Depending on the
+LNBf type, the polarization or the intermediate frequency (IF) of the
+LNBf can controlled by the voltage level. Other devices (for example,
+the ones that implement DISEqC and multipoint LNBf's don't need to
+control the voltage level, provided that either 13V or 18V is sent to
+power up the LNBf.
+
+NOTE: if more than one device is connected to the same antenna, setting
+a voltage level may interfere on other devices, as they may lose the
+capability of setting polarization or IF. So, on those cases, setting
+the voltage to SEC_VOLTAGE_OFF while the device is not is used is
+recommended.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _fe-type-t:
+
+*************
+Frontend type
+*************
+
+For historical reasons, frontend types are named by the type of
+modulation used in transmission. The fontend types are given by
+fe_type_t type, defined as:
+
+
+.. _fe-type:
+
+.. flat-table:: Frontend types
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - fe_type
+
+ - Description
+
+ - :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>` equivalent
+ type
+
+ - .. row 2
+
+ - .. _FE-QPSK:
+
+ ``FE_QPSK``
+
+ - For DVB-S standard
+
+ - ``SYS_DVBS``
+
+ - .. row 3
+
+ - .. _FE-QAM:
+
+ ``FE_QAM``
+
+ - For DVB-C annex A standard
+
+ - ``SYS_DVBC_ANNEX_A``
+
+ - .. row 4
+
+ - .. _FE-OFDM:
+
+ ``FE_OFDM``
+
+ - For DVB-T standard
+
+ - ``SYS_DVBT``
+
+ - .. row 5
+
+ - .. _FE-ATSC:
+
+ ``FE_ATSC``
+
+ - For ATSC standard (terrestrial) or for DVB-C Annex B (cable) used
+ in US.
+
+ - ``SYS_ATSC`` (terrestrial) or ``SYS_DVBC_ANNEX_B`` (cable)
+
+
+Newer formats like DVB-S2, ISDB-T, ISDB-S and DVB-T2 are not described
+at the above, as they're supported via the new
+:ref:`FE_GET_PROPERTY/FE_GET_SET_PROPERTY <FE_GET_PROPERTY>`
+ioctl's, using the :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`
+parameter.
+
+In the old days, struct :ref:`dvb_frontend_info <dvb-frontend-info>`
+used to contain ``fe_type_t`` field to indicate the delivery systems,
+filled with either FE_QPSK, FE_QAM, FE_OFDM or FE_ATSC. While this
+is still filled to keep backward compatibility, the usage of this field
+is deprecated, as it can report just one delivery system, but some
+devices support multiple delivery systems. Please use
+:ref:`DTV_ENUM_DELSYS <DTV-ENUM-DELSYS>` instead.
+
+On devices that support multiple delivery systems, struct
+:ref:`dvb_frontend_info <dvb-frontend-info>`::``fe_type_t`` is
+filled with the currently standard, as selected by the last call to
+:ref:`FE_SET_PROPERTY <FE_GET_PROPERTY>` using the
+:ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>` property.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _fe_property_parameters:
+
+******************************
+Digital TV property parameters
+******************************
+
+
+.. _DTV-UNDEFINED:
+
+DTV_UNDEFINED
+=============
+
+Used internally. A GET/SET operation for it won't change or return
+anything.
+
+
+.. _DTV-TUNE:
+
+DTV_TUNE
+========
+
+Interpret the cache of data, build either a traditional frontend
+tunerequest so we can pass validation in the ``FE_SET_FRONTEND`` ioctl.
+
+
+.. _DTV-CLEAR:
+
+DTV_CLEAR
+=========
+
+Reset a cache of data specific to the frontend here. This does not
+effect hardware.
+
+
+.. _DTV-FREQUENCY:
+
+DTV_FREQUENCY
+=============
+
+Central frequency of the channel.
+
+Notes:
+
+1)For satellite delivery systems, it is measured in kHz. For the other
+ones, it is measured in Hz.
+
+2)For ISDB-T, the channels are usually transmitted with an offset of
+143kHz. E.g. a valid frequency could be 474143 kHz. The stepping is
+bound to the bandwidth of the channel which is 6MHz.
+
+3)As in ISDB-Tsb the channel consists of only one or three segments the
+frequency step is 429kHz, 3*429 respectively. As for ISDB-T the central
+frequency of the channel is expected.
+
+
+.. _DTV-MODULATION:
+
+DTV_MODULATION
+==============
+
+Specifies the frontend modulation type for delivery systems that
+supports more than one modulation type. The modulation can be one of the
+types defined by enum :ref:`fe_modulation <fe-modulation>`.
+
+
+.. _fe-modulation-t:
+
+Modulation property
+-------------------
+
+Most of the digital TV standards currently offers more than one possible
+modulation (sometimes called as "constellation" on some standards). This
+enum contains the values used by the Kernel. Please note that not all
+modulations are supported by a given standard.
+
+
+.. _fe-modulation:
+
+.. flat-table:: enum fe_modulation
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - .. _QPSK:
+
+ ``QPSK``
+
+ - QPSK modulation
+
+ - .. row 3
+
+ - .. _QAM-16:
+
+ ``QAM_16``
+
+ - 16-QAM modulation
+
+ - .. row 4
+
+ - .. _QAM-32:
+
+ ``QAM_32``
+
+ - 32-QAM modulation
+
+ - .. row 5
+
+ - .. _QAM-64:
+
+ ``QAM_64``
+
+ - 64-QAM modulation
+
+ - .. row 6
+
+ - .. _QAM-128:
+
+ ``QAM_128``
+
+ - 128-QAM modulation
+
+ - .. row 7
+
+ - .. _QAM-256:
+
+ ``QAM_256``
+
+ - 256-QAM modulation
+
+ - .. row 8
+
+ - .. _QAM-AUTO:
+
+ ``QAM_AUTO``
+
+ - Autodetect QAM modulation
+
+ - .. row 9
+
+ - .. _VSB-8:
+
+ ``VSB_8``
+
+ - 8-VSB modulation
+
+ - .. row 10
+
+ - .. _VSB-16:
+
+ ``VSB_16``
+
+ - 16-VSB modulation
+
+ - .. row 11
+
+ - .. _PSK-8:
+
+ ``PSK_8``
+
+ - 8-PSK modulation
+
+ - .. row 12
+
+ - .. _APSK-16:
+
+ ``APSK_16``
+
+ - 16-APSK modulation
+
+ - .. row 13
+
+ - .. _APSK-32:
+
+ ``APSK_32``
+
+ - 32-APSK modulation
+
+ - .. row 14
+
+ - .. _DQPSK:
+
+ ``DQPSK``
+
+ - DQPSK modulation
+
+ - .. row 15
+
+ - .. _QAM-4-NR:
+
+ ``QAM_4_NR``
+
+ - 4-QAM-NR modulation
+
+
+
+.. _DTV-BANDWIDTH-HZ:
+
+DTV_BANDWIDTH_HZ
+================
+
+Bandwidth for the channel, in HZ.
+
+Possible values: ``1712000``, ``5000000``, ``6000000``, ``7000000``,
+``8000000``, ``10000000``.
+
+Notes:
+
+1) For ISDB-T it should be always 6000000Hz (6MHz)
+
+2) For ISDB-Tsb it can vary depending on the number of connected
+segments
+
+3) Bandwidth doesn't apply for DVB-C transmissions, as the bandwidth for
+DVB-C depends on the symbol rate
+
+4) Bandwidth in ISDB-T is fixed (6MHz) or can be easily derived from
+other parameters (DTV_ISDBT_SB_SEGMENT_IDX,
+DTV_ISDBT_SB_SEGMENT_COUNT).
+
+5) DVB-T supports 6, 7 and 8MHz.
+
+6) In addition, DVB-T2 supports 1.172, 5 and 10MHz.
+
+
+.. _DTV-INVERSION:
+
+DTV_INVERSION
+=============
+
+Specifies if the frontend should do spectral inversion or not.
+
+
+.. _fe-spectral-inversion-t:
+
+enum fe_modulation: Frontend spectral inversion
+-----------------------------------------------
+
+This parameter indicates if spectral inversion should be presumed or
+not. In the automatic setting (``INVERSION_AUTO``) the hardware will try
+to figure out the correct setting by itself. If the hardware doesn't
+support, the DVB core will try to lock at the carrier first with
+inversion off. If it fails, it will try to enable inversion.
+
+
+.. _fe-spectral-inversion:
+
+.. flat-table:: enum fe_modulation
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - .. _INVERSION-OFF:
+
+ ``INVERSION_OFF``
+
+ - Don't do spectral band inversion.
+
+ - .. row 3
+
+ - .. _INVERSION-ON:
+
+ ``INVERSION_ON``
+
+ - Do spectral band inversion.
+
+ - .. row 4
+
+ - .. _INVERSION-AUTO:
+
+ ``INVERSION_AUTO``
+
+ - Autodetect spectral band inversion.
+
+
+
+.. _DTV-DISEQC-MASTER:
+
+DTV_DISEQC_MASTER
+=================
+
+Currently not implemented.
+
+
+.. _DTV-SYMBOL-RATE:
+
+DTV_SYMBOL_RATE
+===============
+
+Digital TV symbol rate, in bauds (symbols/second). Used on cable
+standards.
+
+
+.. _DTV-INNER-FEC:
+
+DTV_INNER_FEC
+=============
+
+Used cable/satellite transmissions. The acceptable values are:
+
+
+.. _fe-code-rate-t:
+
+enum fe_code_rate: type of the Forward Error Correction.
+--------------------------------------------------------
+
+
+.. _fe-code-rate:
+
+.. flat-table:: enum fe_code_rate
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - .. _FEC-NONE:
+
+ ``FEC_NONE``
+
+ - No Forward Error Correction Code
+
+ - .. row 3
+
+ - .. _FEC-AUTO:
+
+ ``FEC_AUTO``
+
+ - Autodetect Error Correction Code
+
+ - .. row 4
+
+ - .. _FEC-1-2:
+
+ ``FEC_1_2``
+
+ - Forward Error Correction Code 1/2
+
+ - .. row 5
+
+ - .. _FEC-2-3:
+
+ ``FEC_2_3``
+
+ - Forward Error Correction Code 2/3
+
+ - .. row 6
+
+ - .. _FEC-3-4:
+
+ ``FEC_3_4``
+
+ - Forward Error Correction Code 3/4
+
+ - .. row 7
+
+ - .. _FEC-4-5:
+
+ ``FEC_4_5``
+
+ - Forward Error Correction Code 4/5
+
+ - .. row 8
+
+ - .. _FEC-5-6:
+
+ ``FEC_5_6``
+
+ - Forward Error Correction Code 5/6
+
+ - .. row 9
+
+ - .. _FEC-6-7:
+
+ ``FEC_6_7``
+
+ - Forward Error Correction Code 6/7
+
+ - .. row 10
+
+ - .. _FEC-7-8:
+
+ ``FEC_7_8``
+
+ - Forward Error Correction Code 7/8
+
+ - .. row 11
+
+ - .. _FEC-8-9:
+
+ ``FEC_8_9``
+
+ - Forward Error Correction Code 8/9
+
+ - .. row 12
+
+ - .. _FEC-9-10:
+
+ ``FEC_9_10``
+
+ - Forward Error Correction Code 9/10
+
+ - .. row 13
+
+ - .. _FEC-2-5:
+
+ ``FEC_2_5``
+
+ - Forward Error Correction Code 2/5
+
+ - .. row 14
+
+ - .. _FEC-3-5:
+
+ ``FEC_3_5``
+
+ - Forward Error Correction Code 3/5
+
+
+
+.. _DTV-VOLTAGE:
+
+DTV_VOLTAGE
+===========
+
+The voltage is usually used with non-DiSEqC capable LNBs to switch the
+polarzation (horizontal/vertical). When using DiSEqC epuipment this
+voltage has to be switched consistently to the DiSEqC commands as
+described in the DiSEqC spec.
+
+
+.. _fe-sec-voltage:
+
+.. flat-table:: enum fe_sec_voltage
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - .. _SEC-VOLTAGE-13:
+
+ ``SEC_VOLTAGE_13``
+
+ - Set DC voltage level to 13V
+
+ - .. row 3
+
+ - .. _SEC-VOLTAGE-18:
+
+ ``SEC_VOLTAGE_18``
+
+ - Set DC voltage level to 18V
+
+ - .. row 4
+
+ - .. _SEC-VOLTAGE-OFF:
+
+ ``SEC_VOLTAGE_OFF``
+
+ - Don't send any voltage to the antenna
+
+
+
+.. _DTV-TONE:
+
+DTV_TONE
+========
+
+Currently not used.
+
+
+.. _DTV-PILOT:
+
+DTV_PILOT
+=========
+
+Sets DVB-S2 pilot
+
+
+.. _fe-pilot-t:
+
+fe_pilot type
+-------------
+
+
+.. _fe-pilot:
+
+.. flat-table:: enum fe_pilot
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - .. _PILOT-ON:
+
+ ``PILOT_ON``
+
+ - Pilot tones enabled
+
+ - .. row 3
+
+ - .. _PILOT-OFF:
+
+ ``PILOT_OFF``
+
+ - Pilot tones disabled
+
+ - .. row 4
+
+ - .. _PILOT-AUTO:
+
+ ``PILOT_AUTO``
+
+ - Autodetect pilot tones
+
+
+
+.. _DTV-ROLLOFF:
+
+DTV_ROLLOFF
+===========
+
+Sets DVB-S2 rolloff
+
+
+.. _fe-rolloff-t:
+
+fe_rolloff type
+---------------
+
+
+.. _fe-rolloff:
+
+.. flat-table:: enum fe_rolloff
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - .. _ROLLOFF-35:
+
+ ``ROLLOFF_35``
+
+ - Roloff factor: α=35%
+
+ - .. row 3
+
+ - .. _ROLLOFF-20:
+
+ ``ROLLOFF_20``
+
+ - Roloff factor: α=20%
+
+ - .. row 4
+
+ - .. _ROLLOFF-25:
+
+ ``ROLLOFF_25``
+
+ - Roloff factor: α=25%
+
+ - .. row 5
+
+ - .. _ROLLOFF-AUTO:
+
+ ``ROLLOFF_AUTO``
+
+ - Auto-detect the roloff factor.
+
+
+
+.. _DTV-DISEQC-SLAVE-REPLY:
+
+DTV_DISEQC_SLAVE_REPLY
+======================
+
+Currently not implemented.
+
+
+.. _DTV-FE-CAPABILITY-COUNT:
+
+DTV_FE_CAPABILITY_COUNT
+=======================
+
+Currently not implemented.
+
+
+.. _DTV-FE-CAPABILITY:
+
+DTV_FE_CAPABILITY
+=================
+
+Currently not implemented.
+
+
+.. _DTV-DELIVERY-SYSTEM:
+
+DTV_DELIVERY_SYSTEM
+===================
+
+Specifies the type of Delivery system
+
+
+.. _fe-delivery-system-t:
+
+fe_delivery_system type
+-----------------------
+
+Possible values:
+
+
+.. _fe-delivery-system:
+
+.. flat-table:: enum fe_delivery_system
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - .. _SYS-UNDEFINED:
+
+ ``SYS_UNDEFINED``
+
+ - Undefined standard. Generally, indicates an error
+
+ - .. row 3
+
+ - .. _SYS-DVBC-ANNEX-A:
+
+ ``SYS_DVBC_ANNEX_A``
+
+ - Cable TV: DVB-C following ITU-T J.83 Annex A spec
+
+ - .. row 4
+
+ - .. _SYS-DVBC-ANNEX-B:
+
+ ``SYS_DVBC_ANNEX_B``
+
+ - Cable TV: DVB-C following ITU-T J.83 Annex B spec (ClearQAM)
+
+ - .. row 5
+
+ - .. _SYS-DVBC-ANNEX-C:
+
+ ``SYS_DVBC_ANNEX_C``
+
+ - Cable TV: DVB-C following ITU-T J.83 Annex C spec
+
+ - .. row 6
+
+ - .. _SYS-ISDBC:
+
+ ``SYS_ISDBC``
+
+ - Cable TV: ISDB-C (no drivers yet)
+
+ - .. row 7
+
+ - .. _SYS-DVBT:
+
+ ``SYS_DVBT``
+
+ - Terrestral TV: DVB-T
+
+ - .. row 8
+
+ - .. _SYS-DVBT2:
+
+ ``SYS_DVBT2``
+
+ - Terrestral TV: DVB-T2
+
+ - .. row 9
+
+ - .. _SYS-ISDBT:
+
+ ``SYS_ISDBT``
+
+ - Terrestral TV: ISDB-T
+
+ - .. row 10
+
+ - .. _SYS-ATSC:
+
+ ``SYS_ATSC``
+
+ - Terrestral TV: ATSC
+
+ - .. row 11
+
+ - .. _SYS-ATSCMH:
+
+ ``SYS_ATSCMH``
+
+ - Terrestral TV (mobile): ATSC-M/H
+
+ - .. row 12
+
+ - .. _SYS-DTMB:
+
+ ``SYS_DTMB``
+
+ - Terrestrial TV: DTMB
+
+ - .. row 13
+
+ - .. _SYS-DVBS:
+
+ ``SYS_DVBS``
+
+ - Satellite TV: DVB-S
+
+ - .. row 14
+
+ - .. _SYS-DVBS2:
+
+ ``SYS_DVBS2``
+
+ - Satellite TV: DVB-S2
+
+ - .. row 15
+
+ - .. _SYS-TURBO:
+
+ ``SYS_TURBO``
+
+ - Satellite TV: DVB-S Turbo
+
+ - .. row 16
+
+ - .. _SYS-ISDBS:
+
+ ``SYS_ISDBS``
+
+ - Satellite TV: ISDB-S
+
+ - .. row 17
+
+ - .. _SYS-DAB:
+
+ ``SYS_DAB``
+
+ - Digital audio: DAB (not fully supported)
+
+ - .. row 18
+
+ - .. _SYS-DSS:
+
+ ``SYS_DSS``
+
+ - Satellite TV:"DSS (not fully supported)
+
+ - .. row 19
+
+ - .. _SYS-CMMB:
+
+ ``SYS_CMMB``
+
+ - Terrestral TV (mobile):CMMB (not fully supported)
+
+ - .. row 20
+
+ - .. _SYS-DVBH:
+
+ ``SYS_DVBH``
+
+ - Terrestral TV (mobile): DVB-H (standard deprecated)
+
+
+
+.. _DTV-ISDBT-PARTIAL-RECEPTION:
+
+DTV_ISDBT_PARTIAL_RECEPTION
+===========================
+
+If ``DTV_ISDBT_SOUND_BROADCASTING`` is '0' this bit-field represents
+whether the channel is in partial reception mode or not.
+
+If '1' ``DTV_ISDBT_LAYERA_*`` values are assigned to the center segment
+and ``DTV_ISDBT_LAYERA_SEGMENT_COUNT`` has to be '1'.
+
+If in addition ``DTV_ISDBT_SOUND_BROADCASTING`` is '1'
+``DTV_ISDBT_PARTIAL_RECEPTION`` represents whether this ISDB-Tsb channel
+is consisting of one segment and layer or three segments and two layers.
+
+Possible values: 0, 1, -1 (AUTO)
+
+
+.. _DTV-ISDBT-SOUND-BROADCASTING:
+
+DTV_ISDBT_SOUND_BROADCASTING
+============================
+
+This field represents whether the other DTV_ISDBT_*-parameters are
+referring to an ISDB-T and an ISDB-Tsb channel. (See also
+``DTV_ISDBT_PARTIAL_RECEPTION``).
+
+Possible values: 0, 1, -1 (AUTO)
+
+
+.. _DTV-ISDBT-SB-SUBCHANNEL-ID:
+
+DTV_ISDBT_SB_SUBCHANNEL_ID
+==========================
+
+This field only applies if ``DTV_ISDBT_SOUND_BROADCASTING`` is '1'.
+
+(Note of the author: This might not be the correct description of the
+``SUBCHANNEL-ID`` in all details, but it is my understanding of the
+technical background needed to program a device)
+
+An ISDB-Tsb channel (1 or 3 segments) can be broadcasted alone or in a
+set of connected ISDB-Tsb channels. In this set of channels every
+channel can be received independently. The number of connected ISDB-Tsb
+segment can vary, e.g. depending on the frequency spectrum bandwidth
+available.
+
+Example: Assume 8 ISDB-Tsb connected segments are broadcasted. The
+broadcaster has several possibilities to put those channels in the air:
+Assuming a normal 13-segment ISDB-T spectrum he can align the 8 segments
+from position 1-8 to 5-13 or anything in between.
+
+The underlying layer of segments are subchannels: each segment is
+consisting of several subchannels with a predefined IDs. A sub-channel
+is used to help the demodulator to synchronize on the channel.
+
+An ISDB-T channel is always centered over all sub-channels. As for the
+example above, in ISDB-Tsb it is no longer as simple as that.
+
+``The DTV_ISDBT_SB_SUBCHANNEL_ID`` parameter is used to give the
+sub-channel ID of the segment to be demodulated.
+
+Possible values: 0 .. 41, -1 (AUTO)
+
+
+.. _DTV-ISDBT-SB-SEGMENT-IDX:
+
+DTV_ISDBT_SB_SEGMENT_IDX
+========================
+
+This field only applies if ``DTV_ISDBT_SOUND_BROADCASTING`` is '1'.
+
+``DTV_ISDBT_SB_SEGMENT_IDX`` gives the index of the segment to be
+demodulated for an ISDB-Tsb channel where several of them are
+transmitted in the connected manner.
+
+Possible values: 0 .. ``DTV_ISDBT_SB_SEGMENT_COUNT`` - 1
+
+Note: This value cannot be determined by an automatic channel search.
+
+
+.. _DTV-ISDBT-SB-SEGMENT-COUNT:
+
+DTV_ISDBT_SB_SEGMENT_COUNT
+==========================
+
+This field only applies if ``DTV_ISDBT_SOUND_BROADCASTING`` is '1'.
+
+``DTV_ISDBT_SB_SEGMENT_COUNT`` gives the total count of connected
+ISDB-Tsb channels.
+
+Possible values: 1 .. 13
+
+Note: This value cannot be determined by an automatic channel search.
+
+
+.. _isdb-hierq-layers:
+
+DTV-ISDBT-LAYER[A-C] parameters
+===============================
+
+ISDB-T channels can be coded hierarchically. As opposed to DVB-T in
+ISDB-T hierarchical layers can be decoded simultaneously. For that
+reason a ISDB-T demodulator has 3 Viterbi and 3 Reed-Solomon decoders.
+
+ISDB-T has 3 hierarchical layers which each can use a part of the
+available segments. The total number of segments over all layers has to
+13 in ISDB-T.
+
+There are 3 parameter sets, for Layers A, B and C.
+
+
+.. _DTV-ISDBT-LAYER-ENABLED:
+
+DTV_ISDBT_LAYER_ENABLED
+-----------------------
+
+Hierarchical reception in ISDB-T is achieved by enabling or disabling
+layers in the decoding process. Setting all bits of
+``DTV_ISDBT_LAYER_ENABLED`` to '1' forces all layers (if applicable) to
+be demodulated. This is the default.
+
+If the channel is in the partial reception mode
+(``DTV_ISDBT_PARTIAL_RECEPTION`` = 1) the central segment can be decoded
+independently of the other 12 segments. In that mode layer A has to have
+a ``SEGMENT_COUNT`` of 1.
+
+In ISDB-Tsb only layer A is used, it can be 1 or 3 in ISDB-Tsb according
+to ``DTV_ISDBT_PARTIAL_RECEPTION``. ``SEGMENT_COUNT`` must be filled
+accordingly.
+
+Only the values of the first 3 bits are used. Other bits will be silently ignored:
+
+``DTV_ISDBT_LAYER_ENABLED`` bit 0: layer A enabled
+
+``DTV_ISDBT_LAYER_ENABLED`` bit 1: layer B enabled
+
+``DTV_ISDBT_LAYER_ENABLED`` bit 2: layer C enabled
+
+``DTV_ISDBT_LAYER_ENABLED`` bits 3-31: unused
+
+
+.. _DTV-ISDBT-LAYER-FEC:
+
+DTV_ISDBT_LAYER[A-C]_FEC
+------------------------
+
+Possible values: ``FEC_AUTO``, ``FEC_1_2``, ``FEC_2_3``, ``FEC_3_4``,
+``FEC_5_6``, ``FEC_7_8``
+
+
+.. _DTV-ISDBT-LAYER-MODULATION:
+
+DTV_ISDBT_LAYER[A-C]_MODULATION
+-------------------------------
+
+Possible values: ``QAM_AUTO``, QP\ ``SK, QAM_16``, ``QAM_64``, ``DQPSK``
+
+Note: If layer C is ``DQPSK`` layer B has to be ``DQPSK``. If layer B is
+``DQPSK`` and ``DTV_ISDBT_PARTIAL_RECEPTION``\ =0 layer has to be
+``DQPSK``.
+
+
+.. _DTV-ISDBT-LAYER-SEGMENT-COUNT:
+
+DTV_ISDBT_LAYER[A-C]_SEGMENT_COUNT
+----------------------------------
+
+Possible values: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, -1 (AUTO)
+
+Note: Truth table for ``DTV_ISDBT_SOUND_BROADCASTING`` and
+``DTV_ISDBT_PARTIAL_RECEPTION`` and ``LAYER[A-C]_SEGMENT_COUNT``
+
+
+.. _isdbt-layer_seg-cnt-table:
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - PR
+
+ - SB
+
+ - Layer A width
+
+ - Layer B width
+
+ - Layer C width
+
+ - total width
+
+ - .. row 2
+
+ - 0
+
+ - 0
+
+ - 1 .. 13
+
+ - 1 .. 13
+
+ - 1 .. 13
+
+ - 13
+
+ - .. row 3
+
+ - 1
+
+ - 0
+
+ - 1
+
+ - 1 .. 13
+
+ - 1 .. 13
+
+ - 13
+
+ - .. row 4
+
+ - 0
+
+ - 1
+
+ - 1
+
+ - 0
+
+ - 0
+
+ - 1
+
+ - .. row 5
+
+ - 1
+
+ - 1
+
+ - 1
+
+ - 2
+
+ - 0
+
+ - 13
+
+
+
+.. _DTV-ISDBT-LAYER-TIME-INTERLEAVING:
+
+DTV_ISDBT_LAYER[A-C]_TIME_INTERLEAVING
+--------------------------------------
+
+Valid values: 0, 1, 2, 4, -1 (AUTO)
+
+when DTV_ISDBT_SOUND_BROADCASTING is active, value 8 is also valid.
+
+Note: The real time interleaving length depends on the mode (fft-size).
+The values here are referring to what can be found in the
+TMCC-structure, as shown in the table below.
+
+
+.. _isdbt-layer-interleaving-table:
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``DTV_ISDBT_LAYER[A-C]_TIME_INTERLEAVING``
+
+ - Mode 1 (2K FFT)
+
+ - Mode 2 (4K FFT)
+
+ - Mode 3 (8K FFT)
+
+ - .. row 2
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - .. row 3
+
+ - 1
+
+ - 4
+
+ - 2
+
+ - 1
+
+ - .. row 4
+
+ - 2
+
+ - 8
+
+ - 4
+
+ - 2
+
+ - .. row 5
+
+ - 4
+
+ - 16
+
+ - 8
+
+ - 4
+
+
+
+.. _DTV-ATSCMH-FIC-VER:
+
+DTV_ATSCMH_FIC_VER
+------------------
+
+Version number of the FIC (Fast Information Channel) signaling data.
+
+FIC is used for relaying information to allow rapid service acquisition
+by the receiver.
+
+Possible values: 0, 1, 2, 3, ..., 30, 31
+
+
+.. _DTV-ATSCMH-PARADE-ID:
+
+DTV_ATSCMH_PARADE_ID
+--------------------
+
+Parade identification number
+
+A parade is a collection of up to eight MH groups, conveying one or two
+ensembles.
+
+Possible values: 0, 1, 2, 3, ..., 126, 127
+
+
+.. _DTV-ATSCMH-NOG:
+
+DTV_ATSCMH_NOG
+--------------
+
+Number of MH groups per MH subframe for a designated parade.
+
+Possible values: 1, 2, 3, 4, 5, 6, 7, 8
+
+
+.. _DTV-ATSCMH-TNOG:
+
+DTV_ATSCMH_TNOG
+---------------
+
+Total number of MH groups including all MH groups belonging to all MH
+parades in one MH subframe.
+
+Possible values: 0, 1, 2, 3, ..., 30, 31
+
+
+.. _DTV-ATSCMH-SGN:
+
+DTV_ATSCMH_SGN
+--------------
+
+Start group number.
+
+Possible values: 0, 1, 2, 3, ..., 14, 15
+
+
+.. _DTV-ATSCMH-PRC:
+
+DTV_ATSCMH_PRC
+--------------
+
+Parade repetition cycle.
+
+Possible values: 1, 2, 3, 4, 5, 6, 7, 8
+
+
+.. _DTV-ATSCMH-RS-FRAME-MODE:
+
+DTV_ATSCMH_RS_FRAME_MODE
+------------------------
+
+Reed Solomon (RS) frame mode.
+
+Possible values are:
+
+
+.. _atscmh-rs-frame-mode:
+
+.. flat-table:: enum atscmh_rs_frame_mode
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - .. _ATSCMH-RSFRAME-PRI-ONLY:
+
+ ``ATSCMH_RSFRAME_PRI_ONLY``
+
+ - Single Frame: There is only a primary RS Frame for all Group
+ Regions.
+
+ - .. row 3
+
+ - .. _ATSCMH-RSFRAME-PRI-SEC:
+
+ ``ATSCMH_RSFRAME_PRI_SEC``
+
+ - Dual Frame: There are two separate RS Frames: Primary RS Frame for
+ Group Region A and B and Secondary RS Frame for Group Region C and
+ D.
+
+
+
+.. _DTV-ATSCMH-RS-FRAME-ENSEMBLE:
+
+DTV_ATSCMH_RS_FRAME_ENSEMBLE
+----------------------------
+
+Reed Solomon(RS) frame ensemble.
+
+Possible values are:
+
+
+.. _atscmh-rs-frame-ensemble:
+
+.. flat-table:: enum atscmh_rs_frame_ensemble
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - .. _ATSCMH-RSFRAME-ENS-PRI:
+
+ ``ATSCMH_RSFRAME_ENS_PRI``
+
+ - Primary Ensemble.
+
+ - .. row 3
+
+ - .. _ATSCMH-RSFRAME-ENS-SEC:
+
+ ``AATSCMH_RSFRAME_PRI_SEC``
+
+ - Secondary Ensemble.
+
+ - .. row 4
+
+ - .. _ATSCMH-RSFRAME-RES:
+
+ ``AATSCMH_RSFRAME_RES``
+
+ - Reserved. Shouldn't be used.
+
+
+
+.. _DTV-ATSCMH-RS-CODE-MODE-PRI:
+
+DTV_ATSCMH_RS_CODE_MODE_PRI
+---------------------------
+
+Reed Solomon (RS) code mode (primary).
+
+Possible values are:
+
+
+.. _atscmh-rs-code-mode:
+
+.. flat-table:: enum atscmh_rs_code_mode
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - .. _ATSCMH-RSCODE-211-187:
+
+ ``ATSCMH_RSCODE_211_187``
+
+ - Reed Solomon code (211,187).
+
+ - .. row 3
+
+ - .. _ATSCMH-RSCODE-223-187:
+
+ ``ATSCMH_RSCODE_223_187``
+
+ - Reed Solomon code (223,187).
+
+ - .. row 4
+
+ - .. _ATSCMH-RSCODE-235-187:
+
+ ``ATSCMH_RSCODE_235_187``
+
+ - Reed Solomon code (235,187).
+
+ - .. row 5
+
+ - .. _ATSCMH-RSCODE-RES:
+
+ ``ATSCMH_RSCODE_RES``
+
+ - Reserved. Shouldn't be used.
+
+
+
+.. _DTV-ATSCMH-RS-CODE-MODE-SEC:
+
+DTV_ATSCMH_RS_CODE_MODE_SEC
+---------------------------
+
+Reed Solomon (RS) code mode (secondary).
+
+Possible values are the same as documented on enum
+:ref:`atscmh_rs_code_mode <atscmh-rs-code-mode>`:
+
+
+.. _DTV-ATSCMH-SCCC-BLOCK-MODE:
+
+DTV_ATSCMH_SCCC_BLOCK_MODE
+--------------------------
+
+Series Concatenated Convolutional Code Block Mode.
+
+Possible values are:
+
+
+.. _atscmh-sccc-block-mode:
+
+.. flat-table:: enum atscmh_scc_block_mode
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - .. _ATSCMH-SCCC-BLK-SEP:
+
+ ``ATSCMH_SCCC_BLK_SEP``
+
+ - Separate SCCC: the SCCC outer code mode shall be set independently
+ for each Group Region (A, B, C, D)
+
+ - .. row 3
+
+ - .. _ATSCMH-SCCC-BLK-COMB:
+
+ ``ATSCMH_SCCC_BLK_COMB``
+
+ - Combined SCCC: all four Regions shall have the same SCCC outer
+ code mode.
+
+ - .. row 4
+
+ - .. _ATSCMH-SCCC-BLK-RES:
+
+ ``ATSCMH_SCCC_BLK_RES``
+
+ - Reserved. Shouldn't be used.
+
+
+
+.. _DTV-ATSCMH-SCCC-CODE-MODE-A:
+
+DTV_ATSCMH_SCCC_CODE_MODE_A
+---------------------------
+
+Series Concatenated Convolutional Code Rate.
+
+Possible values are:
+
+
+.. _atscmh-sccc-code-mode:
+
+.. flat-table:: enum atscmh_sccc_code_mode
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - .. _ATSCMH-SCCC-CODE-HLF:
+
+ ``ATSCMH_SCCC_CODE_HLF``
+
+ - The outer code rate of a SCCC Block is 1/2 rate.
+
+ - .. row 3
+
+ - .. _ATSCMH-SCCC-CODE-QTR:
+
+ ``ATSCMH_SCCC_CODE_QTR``
+
+ - The outer code rate of a SCCC Block is 1/4 rate.
+
+ - .. row 4
+
+ - .. _ATSCMH-SCCC-CODE-RES:
+
+ ``ATSCMH_SCCC_CODE_RES``
+
+ - to be documented.
+
+
+
+.. _DTV-ATSCMH-SCCC-CODE-MODE-B:
+
+DTV_ATSCMH_SCCC_CODE_MODE_B
+---------------------------
+
+Series Concatenated Convolutional Code Rate.
+
+Possible values are the same as documented on enum
+:ref:`atscmh_sccc_code_mode <atscmh-sccc-code-mode>`.
+
+
+.. _DTV-ATSCMH-SCCC-CODE-MODE-C:
+
+DTV_ATSCMH_SCCC_CODE_MODE_C
+---------------------------
+
+Series Concatenated Convolutional Code Rate.
+
+Possible values are the same as documented on enum
+:ref:`atscmh_sccc_code_mode <atscmh-sccc-code-mode>`.
+
+
+.. _DTV-ATSCMH-SCCC-CODE-MODE-D:
+
+DTV_ATSCMH_SCCC_CODE_MODE_D
+---------------------------
+
+Series Concatenated Convolutional Code Rate.
+
+Possible values are the same as documented on enum
+:ref:`atscmh_sccc_code_mode <atscmh-sccc-code-mode>`.
+
+
+.. _DTV-API-VERSION:
+
+DTV_API_VERSION
+===============
+
+Returns the major/minor version of the DVB API
+
+
+.. _DTV-CODE-RATE-HP:
+
+DTV_CODE_RATE_HP
+================
+
+Used on terrestrial transmissions. The acceptable values are the ones
+described at :ref:`fe_transmit_mode_t <fe-transmit-mode-t>`.
+
+
+.. _DTV-CODE-RATE-LP:
+
+DTV_CODE_RATE_LP
+================
+
+Used on terrestrial transmissions. The acceptable values are the ones
+described at :ref:`fe_transmit_mode_t <fe-transmit-mode-t>`.
+
+
+.. _DTV-GUARD-INTERVAL:
+
+DTV_GUARD_INTERVAL
+==================
+
+Possible values are:
+
+
+.. _fe-guard-interval-t:
+
+Modulation guard interval
+-------------------------
+
+
+.. _fe-guard-interval:
+
+.. flat-table:: enum fe_guard_interval
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - .. _GUARD-INTERVAL-AUTO:
+
+ ``GUARD_INTERVAL_AUTO``
+
+ - Autodetect the guard interval
+
+ - .. row 3
+
+ - .. _GUARD-INTERVAL-1-128:
+
+ ``GUARD_INTERVAL_1_128``
+
+ - Guard interval 1/128
+
+ - .. row 4
+
+ - .. _GUARD-INTERVAL-1-32:
+
+ ``GUARD_INTERVAL_1_32``
+
+ - Guard interval 1/32
+
+ - .. row 5
+
+ - .. _GUARD-INTERVAL-1-16:
+
+ ``GUARD_INTERVAL_1_16``
+
+ - Guard interval 1/16
+
+ - .. row 6
+
+ - .. _GUARD-INTERVAL-1-8:
+
+ ``GUARD_INTERVAL_1_8``
+
+ - Guard interval 1/8
+
+ - .. row 7
+
+ - .. _GUARD-INTERVAL-1-4:
+
+ ``GUARD_INTERVAL_1_4``
+
+ - Guard interval 1/4
+
+ - .. row 8
+
+ - .. _GUARD-INTERVAL-19-128:
+
+ ``GUARD_INTERVAL_19_128``
+
+ - Guard interval 19/128
+
+ - .. row 9
+
+ - .. _GUARD-INTERVAL-19-256:
+
+ ``GUARD_INTERVAL_19_256``
+
+ - Guard interval 19/256
+
+ - .. row 10
+
+ - .. _GUARD-INTERVAL-PN420:
+
+ ``GUARD_INTERVAL_PN420``
+
+ - PN length 420 (1/4)
+
+ - .. row 11
+
+ - .. _GUARD-INTERVAL-PN595:
+
+ ``GUARD_INTERVAL_PN595``
+
+ - PN length 595 (1/6)
+
+ - .. row 12
+
+ - .. _GUARD-INTERVAL-PN945:
+
+ ``GUARD_INTERVAL_PN945``
+
+ - PN length 945 (1/9)
+
+
+Notes:
+
+1) If ``DTV_GUARD_INTERVAL`` is set the ``GUARD_INTERVAL_AUTO`` the
+hardware will try to find the correct guard interval (if capable) and
+will use TMCC to fill in the missing parameters.
+
+2) Intervals 1/128, 19/128 and 19/256 are used only for DVB-T2 at
+present
+
+3) DTMB specifies PN420, PN595 and PN945.
+
+
+.. _DTV-TRANSMISSION-MODE:
+
+DTV_TRANSMISSION_MODE
+=====================
+
+Specifies the number of carriers used by the standard. This is used only
+on OFTM-based standards, e. g. DVB-T/T2, ISDB-T, DTMB
+
+
+.. _fe-transmit-mode-t:
+
+enum fe_transmit_mode: Number of carriers per channel
+-----------------------------------------------------
+
+
+.. _fe-transmit-mode:
+
+.. flat-table:: enum fe_transmit_mode
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - .. _TRANSMISSION-MODE-AUTO:
+
+ ``TRANSMISSION_MODE_AUTO``
+
+ - Autodetect transmission mode. The hardware will try to find the
+ correct FFT-size (if capable) to fill in the missing parameters.
+
+ - .. row 3
+
+ - .. _TRANSMISSION-MODE-1K:
+
+ ``TRANSMISSION_MODE_1K``
+
+ - Transmission mode 1K
+
+ - .. row 4
+
+ - .. _TRANSMISSION-MODE-2K:
+
+ ``TRANSMISSION_MODE_2K``
+
+ - Transmission mode 2K
+
+ - .. row 5
+
+ - .. _TRANSMISSION-MODE-8K:
+
+ ``TRANSMISSION_MODE_8K``
+
+ - Transmission mode 8K
+
+ - .. row 6
+
+ - .. _TRANSMISSION-MODE-4K:
+
+ ``TRANSMISSION_MODE_4K``
+
+ - Transmission mode 4K
+
+ - .. row 7
+
+ - .. _TRANSMISSION-MODE-16K:
+
+ ``TRANSMISSION_MODE_16K``
+
+ - Transmission mode 16K
+
+ - .. row 8
+
+ - .. _TRANSMISSION-MODE-32K:
+
+ ``TRANSMISSION_MODE_32K``
+
+ - Transmission mode 32K
+
+ - .. row 9
+
+ - .. _TRANSMISSION-MODE-C1:
+
+ ``TRANSMISSION_MODE_C1``
+
+ - Single Carrier (C=1) transmission mode (DTMB)
+
+ - .. row 10
+
+ - .. _TRANSMISSION-MODE-C3780:
+
+ ``TRANSMISSION_MODE_C3780``
+
+ - Multi Carrier (C=3780) transmission mode (DTMB)
+
+
+Notes:
+
+1) ISDB-T supports three carrier/symbol-size: 8K, 4K, 2K. It is called
+'mode' in the standard: Mode 1 is 2K, mode 2 is 4K, mode 3 is 8K
+
+2) If ``DTV_TRANSMISSION_MODE`` is set the ``TRANSMISSION_MODE_AUTO``
+the hardware will try to find the correct FFT-size (if capable) and will
+use TMCC to fill in the missing parameters.
+
+3) DVB-T specifies 2K and 8K as valid sizes.
+
+4) DVB-T2 specifies 1K, 2K, 4K, 8K, 16K and 32K.
+
+5) DTMB specifies C1 and C3780.
+
+
+.. _DTV-HIERARCHY:
+
+DTV_HIERARCHY
+=============
+
+Frontend hierarchy
+
+
+.. _fe-hierarchy-t:
+
+Frontend hierarchy
+------------------
+
+
+.. _fe-hierarchy:
+
+.. flat-table:: enum fe_hierarchy
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - .. _HIERARCHY-NONE:
+
+ ``HIERARCHY_NONE``
+
+ - No hierarchy
+
+ - .. row 3
+
+ - .. _HIERARCHY-AUTO:
+
+ ``HIERARCHY_AUTO``
+
+ - Autodetect hierarchy (if supported)
+
+ - .. row 4
+
+ - .. _HIERARCHY-1:
+
+ ``HIERARCHY_1``
+
+ - Hierarchy 1
+
+ - .. row 5
+
+ - .. _HIERARCHY-2:
+
+ ``HIERARCHY_2``
+
+ - Hierarchy 2
+
+ - .. row 6
+
+ - .. _HIERARCHY-4:
+
+ ``HIERARCHY_4``
+
+ - Hierarchy 4
+
+
+
+.. _DTV-STREAM-ID:
+
+DTV_STREAM_ID
+=============
+
+DVB-S2, DVB-T2 and ISDB-S support the transmission of several streams on
+a single transport stream. This property enables the DVB driver to
+handle substream filtering, when supported by the hardware. By default,
+substream filtering is disabled.
+
+For DVB-S2 and DVB-T2, the valid substream id range is from 0 to 255.
+
+For ISDB, the valid substream id range is from 1 to 65535.
+
+To disable it, you should use the special macro NO_STREAM_ID_FILTER.
+
+Note: any value outside the id range also disables filtering.
+
+
+.. _DTV-DVBT2-PLP-ID-LEGACY:
+
+DTV_DVBT2_PLP_ID_LEGACY
+=======================
+
+Obsolete, replaced with DTV_STREAM_ID.
+
+
+.. _DTV-ENUM-DELSYS:
+
+DTV_ENUM_DELSYS
+===============
+
+A Multi standard frontend needs to advertise the delivery systems
+provided. Applications need to enumerate the provided delivery systems,
+before using any other operation with the frontend. Prior to it's
+introduction, FE_GET_INFO was used to determine a frontend type. A
+frontend which provides more than a single delivery system,
+FE_GET_INFO doesn't help much. Applications which intends to use a
+multistandard frontend must enumerate the delivery systems associated
+with it, rather than trying to use FE_GET_INFO. In the case of a
+legacy frontend, the result is just the same as with FE_GET_INFO, but
+in a more structured format
+
+
+.. _DTV-INTERLEAVING:
+
+DTV_INTERLEAVING
+================
+
+Time interleaving to be used. Currently, used only on DTMB.
+
+
+.. _fe-interleaving:
+
+.. flat-table:: enum fe_interleaving
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - .. _INTERLEAVING-NONE:
+
+ ``INTERLEAVING_NONE``
+
+ - No interleaving.
+
+ - .. row 3
+
+ - .. _INTERLEAVING-AUTO:
+
+ ``INTERLEAVING_AUTO``
+
+ - Auto-detect interleaving.
+
+ - .. row 4
+
+ - .. _INTERLEAVING-240:
+
+ ``INTERLEAVING_240``
+
+ - Interleaving of 240 symbols.
+
+ - .. row 5
+
+ - .. _INTERLEAVING-720:
+
+ ``INTERLEAVING_720``
+
+ - Interleaving of 720 symbols.
+
+
+
+.. _DTV-LNA:
+
+DTV_LNA
+=======
+
+Low-noise amplifier.
+
+Hardware might offer controllable LNA which can be set manually using
+that parameter. Usually LNA could be found only from terrestrial devices
+if at all.
+
+Possible values: 0, 1, LNA_AUTO
+
+0, LNA off
+
+1, LNA on
+
+use the special macro LNA_AUTO to set LNA auto
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _frontend-property-cable-systems:
+
+*****************************************
+Properties used on cable delivery systems
+*****************************************
+
+
+.. _dvbc-params:
+
+DVB-C delivery system
+=====================
+
+The DVB-C Annex-A is the widely used cable standard. Transmission uses
+QAM modulation.
+
+The DVB-C Annex-C is optimized for 6MHz, and is used in Japan. It
+supports a subset of the Annex A modulation types, and a roll-off of
+0.13, instead of 0.15
+
+The following parameters are valid for DVB-C Annex A/C:
+
+- :ref:`DTV_API_VERSION <DTV-API-VERSION>`
+
+- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`
+
+- :ref:`DTV_TUNE <DTV-TUNE>`
+
+- :ref:`DTV_CLEAR <DTV-CLEAR>`
+
+- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`
+
+- :ref:`DTV_MODULATION <DTV-MODULATION>`
+
+- :ref:`DTV_INVERSION <DTV-INVERSION>`
+
+- :ref:`DTV_SYMBOL_RATE <DTV-SYMBOL-RATE>`
+
+- :ref:`DTV_INNER_FEC <DTV-INNER-FEC>`
+
+- :ref:`DTV_LNA <DTV-LNA>`
+
+In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
+are also valid.
+
+
+.. _dvbc-annex-b-params:
+
+DVB-C Annex B delivery system
+=============================
+
+The DVB-C Annex-B is only used on a few Countries like the United
+States.
+
+The following parameters are valid for DVB-C Annex B:
+
+- :ref:`DTV_API_VERSION <DTV-API-VERSION>`
+
+- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`
+
+- :ref:`DTV_TUNE <DTV-TUNE>`
+
+- :ref:`DTV_CLEAR <DTV-CLEAR>`
+
+- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`
+
+- :ref:`DTV_MODULATION <DTV-MODULATION>`
+
+- :ref:`DTV_INVERSION <DTV-INVERSION>`
+
+- :ref:`DTV_LNA <DTV-LNA>`
+
+In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
+are also valid.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _frontend-property-satellite-systems:
+
+*********************************************
+Properties used on satellite delivery systems
+*********************************************
+
+
+.. _dvbs-params:
+
+DVB-S delivery system
+=====================
+
+The following parameters are valid for DVB-S:
+
+- :ref:`DTV_API_VERSION <DTV-API-VERSION>`
+
+- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`
+
+- :ref:`DTV_TUNE <DTV-TUNE>`
+
+- :ref:`DTV_CLEAR <DTV-CLEAR>`
+
+- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`
+
+- :ref:`DTV_INVERSION <DTV-INVERSION>`
+
+- :ref:`DTV_SYMBOL_RATE <DTV-SYMBOL-RATE>`
+
+- :ref:`DTV_INNER_FEC <DTV-INNER-FEC>`
+
+- :ref:`DTV_VOLTAGE <DTV-VOLTAGE>`
+
+- :ref:`DTV_TONE <DTV-TONE>`
+
+In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
+are also valid.
+
+Future implementations might add those two missing parameters:
+
+- :ref:`DTV_DISEQC_MASTER <DTV-DISEQC-MASTER>`
+
+- :ref:`DTV_DISEQC_SLAVE_REPLY <DTV-DISEQC-SLAVE-REPLY>`
+
+
+.. _dvbs2-params:
+
+DVB-S2 delivery system
+======================
+
+In addition to all parameters valid for DVB-S, DVB-S2 supports the
+following parameters:
+
+- :ref:`DTV_MODULATION <DTV-MODULATION>`
+
+- :ref:`DTV_PILOT <DTV-PILOT>`
+
+- :ref:`DTV_ROLLOFF <DTV-ROLLOFF>`
+
+- :ref:`DTV_STREAM_ID <DTV-STREAM-ID>`
+
+In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
+are also valid.
+
+
+.. _turbo-params:
+
+Turbo code delivery system
+==========================
+
+In addition to all parameters valid for DVB-S, turbo code supports the
+following parameters:
+
+- :ref:`DTV_MODULATION <DTV-MODULATION>`
+
+
+.. _isdbs-params:
+
+ISDB-S delivery system
+======================
+
+The following parameters are valid for ISDB-S:
+
+- :ref:`DTV_API_VERSION <DTV-API-VERSION>`
+
+- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`
+
+- :ref:`DTV_TUNE <DTV-TUNE>`
+
+- :ref:`DTV_CLEAR <DTV-CLEAR>`
+
+- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`
+
+- :ref:`DTV_INVERSION <DTV-INVERSION>`
+
+- :ref:`DTV_SYMBOL_RATE <DTV-SYMBOL-RATE>`
+
+- :ref:`DTV_INNER_FEC <DTV-INNER-FEC>`
+
+- :ref:`DTV_VOLTAGE <DTV-VOLTAGE>`
+
+- :ref:`DTV_STREAM_ID <DTV-STREAM-ID>`
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _frontend-property-terrestrial-systems:
+
+***********************************************
+Properties used on terrestrial delivery systems
+***********************************************
+
+
+.. _dvbt-params:
+
+DVB-T delivery system
+=====================
+
+The following parameters are valid for DVB-T:
+
+- :ref:`DTV_API_VERSION <DTV-API-VERSION>`
+
+- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`
+
+- :ref:`DTV_TUNE <DTV-TUNE>`
+
+- :ref:`DTV_CLEAR <DTV-CLEAR>`
+
+- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`
+
+- :ref:`DTV_MODULATION <DTV-MODULATION>`
+
+- :ref:`DTV_BANDWIDTH_HZ <DTV-BANDWIDTH-HZ>`
+
+- :ref:`DTV_INVERSION <DTV-INVERSION>`
+
+- :ref:`DTV_CODE_RATE_HP <DTV-CODE-RATE-HP>`
+
+- :ref:`DTV_CODE_RATE_LP <DTV-CODE-RATE-LP>`
+
+- :ref:`DTV_GUARD_INTERVAL <DTV-GUARD-INTERVAL>`
+
+- :ref:`DTV_TRANSMISSION_MODE <DTV-TRANSMISSION-MODE>`
+
+- :ref:`DTV_HIERARCHY <DTV-HIERARCHY>`
+
+- :ref:`DTV_LNA <DTV-LNA>`
+
+In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
+are also valid.
+
+
+.. _dvbt2-params:
+
+DVB-T2 delivery system
+======================
+
+DVB-T2 support is currently in the early stages of development, so
+expect that this section maygrow and become more detailed with time.
+
+The following parameters are valid for DVB-T2:
+
+- :ref:`DTV_API_VERSION <DTV-API-VERSION>`
+
+- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`
+
+- :ref:`DTV_TUNE <DTV-TUNE>`
+
+- :ref:`DTV_CLEAR <DTV-CLEAR>`
+
+- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`
+
+- :ref:`DTV_MODULATION <DTV-MODULATION>`
+
+- :ref:`DTV_BANDWIDTH_HZ <DTV-BANDWIDTH-HZ>`
+
+- :ref:`DTV_INVERSION <DTV-INVERSION>`
+
+- :ref:`DTV_CODE_RATE_HP <DTV-CODE-RATE-HP>`
+
+- :ref:`DTV_CODE_RATE_LP <DTV-CODE-RATE-LP>`
+
+- :ref:`DTV_GUARD_INTERVAL <DTV-GUARD-INTERVAL>`
+
+- :ref:`DTV_TRANSMISSION_MODE <DTV-TRANSMISSION-MODE>`
+
+- :ref:`DTV_HIERARCHY <DTV-HIERARCHY>`
+
+- :ref:`DTV_STREAM_ID <DTV-STREAM-ID>`
+
+- :ref:`DTV_LNA <DTV-LNA>`
+
+In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
+are also valid.
+
+
+.. _isdbt:
+
+ISDB-T delivery system
+======================
+
+This ISDB-T/ISDB-Tsb API extension should reflect all information needed
+to tune any ISDB-T/ISDB-Tsb hardware. Of course it is possible that some
+very sophisticated devices won't need certain parameters to tune.
+
+The information given here should help application writers to know how
+to handle ISDB-T and ISDB-Tsb hardware using the Linux DVB-API.
+
+The details given here about ISDB-T and ISDB-Tsb are just enough to
+basically show the dependencies between the needed parameter values, but
+surely some information is left out. For more detailed information see
+the following documents:
+
+ARIB STD-B31 - "Transmission System for Digital Terrestrial Television
+Broadcasting" and
+
+ARIB TR-B14 - "Operational Guidelines for Digital Terrestrial Television
+Broadcasting".
+
+In order to understand the ISDB specific parameters, one has to have
+some knowledge the channel structure in ISDB-T and ISDB-Tsb. I.e. it has
+to be known to the reader that an ISDB-T channel consists of 13
+segments, that it can have up to 3 layer sharing those segments, and
+things like that.
+
+The following parameters are valid for ISDB-T:
+
+- :ref:`DTV_API_VERSION <DTV-API-VERSION>`
+
+- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`
+
+- :ref:`DTV_TUNE <DTV-TUNE>`
+
+- :ref:`DTV_CLEAR <DTV-CLEAR>`
+
+- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`
+
+- :ref:`DTV_BANDWIDTH_HZ <DTV-BANDWIDTH-HZ>`
+
+- :ref:`DTV_INVERSION <DTV-INVERSION>`
+
+- :ref:`DTV_GUARD_INTERVAL <DTV-GUARD-INTERVAL>`
+
+- :ref:`DTV_TRANSMISSION_MODE <DTV-TRANSMISSION-MODE>`
+
+- :ref:`DTV_ISDBT_LAYER_ENABLED <DTV-ISDBT-LAYER-ENABLED>`
+
+- :ref:`DTV_ISDBT_PARTIAL_RECEPTION <DTV-ISDBT-PARTIAL-RECEPTION>`
+
+- :ref:`DTV_ISDBT_SOUND_BROADCASTING <DTV-ISDBT-SOUND-BROADCASTING>`
+
+- :ref:`DTV_ISDBT_SB_SUBCHANNEL_ID <DTV-ISDBT-SB-SUBCHANNEL-ID>`
+
+- :ref:`DTV_ISDBT_SB_SEGMENT_IDX <DTV-ISDBT-SB-SEGMENT-IDX>`
+
+- :ref:`DTV_ISDBT_SB_SEGMENT_COUNT <DTV-ISDBT-SB-SEGMENT-COUNT>`
+
+- :ref:`DTV_ISDBT_LAYERA_FEC <DTV-ISDBT-LAYER-FEC>`
+
+- :ref:`DTV_ISDBT_LAYERA_MODULATION <DTV-ISDBT-LAYER-MODULATION>`
+
+- :ref:`DTV_ISDBT_LAYERA_SEGMENT_COUNT <DTV-ISDBT-LAYER-SEGMENT-COUNT>`
+
+- :ref:`DTV_ISDBT_LAYERA_TIME_INTERLEAVING <DTV-ISDBT-LAYER-TIME-INTERLEAVING>`
+
+- :ref:`DTV_ISDBT_LAYERB_FEC <DTV-ISDBT-LAYER-FEC>`
+
+- :ref:`DTV_ISDBT_LAYERB_MODULATION <DTV-ISDBT-LAYER-MODULATION>`
+
+- :ref:`DTV_ISDBT_LAYERB_SEGMENT_COUNT <DTV-ISDBT-LAYER-SEGMENT-COUNT>`
+
+- :ref:`DTV_ISDBT_LAYERB_TIME_INTERLEAVING <DTV-ISDBT-LAYER-TIME-INTERLEAVING>`
+
+- :ref:`DTV_ISDBT_LAYERC_FEC <DTV-ISDBT-LAYER-FEC>`
+
+- :ref:`DTV_ISDBT_LAYERC_MODULATION <DTV-ISDBT-LAYER-MODULATION>`
+
+- :ref:`DTV_ISDBT_LAYERC_SEGMENT_COUNT <DTV-ISDBT-LAYER-SEGMENT-COUNT>`
+
+- :ref:`DTV_ISDBT_LAYERC_TIME_INTERLEAVING <DTV-ISDBT-LAYER-TIME-INTERLEAVING>`
+
+In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
+are also valid.
+
+
+.. _atsc-params:
+
+ATSC delivery system
+====================
+
+The following parameters are valid for ATSC:
+
+- :ref:`DTV_API_VERSION <DTV-API-VERSION>`
+
+- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`
+
+- :ref:`DTV_TUNE <DTV-TUNE>`
+
+- :ref:`DTV_CLEAR <DTV-CLEAR>`
+
+- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`
+
+- :ref:`DTV_MODULATION <DTV-MODULATION>`
+
+- :ref:`DTV_BANDWIDTH_HZ <DTV-BANDWIDTH-HZ>`
+
+In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
+are also valid.
+
+
+.. _atscmh-params:
+
+ATSC-MH delivery system
+=======================
+
+The following parameters are valid for ATSC-MH:
+
+- :ref:`DTV_API_VERSION <DTV-API-VERSION>`
+
+- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`
+
+- :ref:`DTV_TUNE <DTV-TUNE>`
+
+- :ref:`DTV_CLEAR <DTV-CLEAR>`
+
+- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`
+
+- :ref:`DTV_BANDWIDTH_HZ <DTV-BANDWIDTH-HZ>`
+
+- :ref:`DTV_ATSCMH_FIC_VER <DTV-ATSCMH-FIC-VER>`
+
+- :ref:`DTV_ATSCMH_PARADE_ID <DTV-ATSCMH-PARADE-ID>`
+
+- :ref:`DTV_ATSCMH_NOG <DTV-ATSCMH-NOG>`
+
+- :ref:`DTV_ATSCMH_TNOG <DTV-ATSCMH-TNOG>`
+
+- :ref:`DTV_ATSCMH_SGN <DTV-ATSCMH-SGN>`
+
+- :ref:`DTV_ATSCMH_PRC <DTV-ATSCMH-PRC>`
+
+- :ref:`DTV_ATSCMH_RS_FRAME_MODE <DTV-ATSCMH-RS-FRAME-MODE>`
+
+- :ref:`DTV_ATSCMH_RS_FRAME_ENSEMBLE <DTV-ATSCMH-RS-FRAME-ENSEMBLE>`
+
+- :ref:`DTV_ATSCMH_RS_CODE_MODE_PRI <DTV-ATSCMH-RS-CODE-MODE-PRI>`
+
+- :ref:`DTV_ATSCMH_RS_CODE_MODE_SEC <DTV-ATSCMH-RS-CODE-MODE-SEC>`
+
+- :ref:`DTV_ATSCMH_SCCC_BLOCK_MODE <DTV-ATSCMH-SCCC-BLOCK-MODE>`
+
+- :ref:`DTV_ATSCMH_SCCC_CODE_MODE_A <DTV-ATSCMH-SCCC-CODE-MODE-A>`
+
+- :ref:`DTV_ATSCMH_SCCC_CODE_MODE_B <DTV-ATSCMH-SCCC-CODE-MODE-B>`
+
+- :ref:`DTV_ATSCMH_SCCC_CODE_MODE_C <DTV-ATSCMH-SCCC-CODE-MODE-C>`
+
+- :ref:`DTV_ATSCMH_SCCC_CODE_MODE_D <DTV-ATSCMH-SCCC-CODE-MODE-D>`
+
+In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
+are also valid.
+
+
+.. _dtmb-params:
+
+DTMB delivery system
+====================
+
+The following parameters are valid for DTMB:
+
+- :ref:`DTV_API_VERSION <DTV-API-VERSION>`
+
+- :ref:`DTV_DELIVERY_SYSTEM <DTV-DELIVERY-SYSTEM>`
+
+- :ref:`DTV_TUNE <DTV-TUNE>`
+
+- :ref:`DTV_CLEAR <DTV-CLEAR>`
+
+- :ref:`DTV_FREQUENCY <DTV-FREQUENCY>`
+
+- :ref:`DTV_MODULATION <DTV-MODULATION>`
+
+- :ref:`DTV_BANDWIDTH_HZ <DTV-BANDWIDTH-HZ>`
+
+- :ref:`DTV_INVERSION <DTV-INVERSION>`
+
+- :ref:`DTV_INNER_FEC <DTV-INNER-FEC>`
+
+- :ref:`DTV_GUARD_INTERVAL <DTV-GUARD-INTERVAL>`
+
+- :ref:`DTV_TRANSMISSION_MODE <DTV-TRANSMISSION-MODE>`
+
+- :ref:`DTV_INTERLEAVING <DTV-INTERLEAVING>`
+
+- :ref:`DTV_LNA <DTV-LNA>`
+
+In addition, the :ref:`DTV QoS statistics <frontend-stat-properties>`
+are also valid.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _frontend-stat-properties:
+
+******************************
+Frontend statistics indicators
+******************************
+
+The values are returned via ``dtv_property.stat``. If the property is
+supported, ``dtv_property.stat.len`` is bigger than zero.
+
+For most delivery systems, ``dtv_property.stat.len`` will be 1 if the
+stats is supported, and the properties will return a single value for
+each parameter.
+
+It should be noted, however, that new OFDM delivery systems like ISDB
+can use different modulation types for each group of carriers. On such
+standards, up to 3 groups of statistics can be provided, and
+``dtv_property.stat.len`` is updated to reflect the "global" metrics,
+plus one metric per each carrier group (called "layer" on ISDB).
+
+So, in order to be consistent with other delivery systems, the first
+value at :ref:`dtv_property.stat.dtv_stats <dtv-stats>` array refers
+to the global metric. The other elements of the array represent each
+layer, starting from layer A(index 1), layer B (index 2) and so on.
+
+The number of filled elements are stored at ``dtv_property.stat.len``.
+
+Each element of the ``dtv_property.stat.dtv_stats`` array consists on
+two elements:
+
+- ``svalue`` or ``uvalue``, where ``svalue`` is for signed values of
+ the measure (dB measures) and ``uvalue`` is for unsigned values
+ (counters, relative scale)
+
+- ``scale`` - Scale for the value. It can be:
+
+ - ``FE_SCALE_NOT_AVAILABLE`` - The parameter is supported by the
+ frontend, but it was not possible to collect it (could be a
+ transitory or permanent condition)
+
+ - ``FE_SCALE_DECIBEL`` - parameter is a signed value, measured in
+ 1/1000 dB
+
+ - ``FE_SCALE_RELATIVE`` - parameter is a unsigned value, where 0
+ means 0% and 65535 means 100%.
+
+ - ``FE_SCALE_COUNTER`` - parameter is a unsigned value that counts
+ the occurrence of an event, like bit error, block error, or lapsed
+ time.
+
+
+.. _DTV-STAT-SIGNAL-STRENGTH:
+
+DTV_STAT_SIGNAL_STRENGTH
+========================
+
+Indicates the signal strength level at the analog part of the tuner or
+of the demod.
+
+Possible scales for this metric are:
+
+- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
+ measurement was not complete yet.
+
+- ``FE_SCALE_DECIBEL`` - signal strength is in 0.001 dBm units, power
+ measured in miliwatts. This value is generally negative.
+
+- ``FE_SCALE_RELATIVE`` - The frontend provides a 0% to 100%
+ measurement for power (actually, 0 to 65535).
+
+
+.. _DTV-STAT-CNR:
+
+DTV_STAT_CNR
+============
+
+Indicates the Signal to Noise ratio for the main carrier.
+
+Possible scales for this metric are:
+
+- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
+ measurement was not complete yet.
+
+- ``FE_SCALE_DECIBEL`` - Signal/Noise ratio is in 0.001 dB units.
+
+- ``FE_SCALE_RELATIVE`` - The frontend provides a 0% to 100%
+ measurement for Signal/Noise (actually, 0 to 65535).
+
+
+.. _DTV-STAT-PRE-ERROR-BIT-COUNT:
+
+DTV_STAT_PRE_ERROR_BIT_COUNT
+============================
+
+Measures the number of bit errors before the forward error correction
+(FEC) on the inner coding block (before Viterbi, LDPC or other inner
+code).
+
+This measure is taken during the same interval as
+``DTV_STAT_PRE_TOTAL_BIT_COUNT``.
+
+In order to get the BER (Bit Error Rate) measurement, it should be
+divided by
+:ref:`DTV_STAT_PRE_TOTAL_BIT_COUNT <DTV-STAT-PRE-TOTAL-BIT-COUNT>`.
+
+This measurement is monotonically increased, as the frontend gets more
+bit count measurements. The frontend may reset it when a
+channel/transponder is tuned.
+
+Possible scales for this metric are:
+
+- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
+ measurement was not complete yet.
+
+- ``FE_SCALE_COUNTER`` - Number of error bits counted before the inner
+ coding.
+
+
+.. _DTV-STAT-PRE-TOTAL-BIT-COUNT:
+
+DTV_STAT_PRE_TOTAL_BIT_COUNT
+============================
+
+Measures the amount of bits received before the inner code block, during
+the same period as
+:ref:`DTV_STAT_PRE_ERROR_BIT_COUNT <DTV-STAT-PRE-ERROR-BIT-COUNT>`
+measurement was taken.
+
+It should be noted that this measurement can be smaller than the total
+amount of bits on the transport stream, as the frontend may need to
+manually restart the measurement, losing some data between each
+measurement interval.
+
+This measurement is monotonically increased, as the frontend gets more
+bit count measurements. The frontend may reset it when a
+channel/transponder is tuned.
+
+Possible scales for this metric are:
+
+- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
+ measurement was not complete yet.
+
+- ``FE_SCALE_COUNTER`` - Number of bits counted while measuring
+ :ref:`DTV_STAT_PRE_ERROR_BIT_COUNT <DTV-STAT-PRE-ERROR-BIT-COUNT>`.
+
+
+.. _DTV-STAT-POST-ERROR-BIT-COUNT:
+
+DTV_STAT_POST_ERROR_BIT_COUNT
+=============================
+
+Measures the number of bit errors after the forward error correction
+(FEC) done by inner code block (after Viterbi, LDPC or other inner
+code).
+
+This measure is taken during the same interval as
+``DTV_STAT_POST_TOTAL_BIT_COUNT``.
+
+In order to get the BER (Bit Error Rate) measurement, it should be
+divided by
+:ref:`DTV_STAT_POST_TOTAL_BIT_COUNT <DTV-STAT-POST-TOTAL-BIT-COUNT>`.
+
+This measurement is monotonically increased, as the frontend gets more
+bit count measurements. The frontend may reset it when a
+channel/transponder is tuned.
+
+Possible scales for this metric are:
+
+- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
+ measurement was not complete yet.
+
+- ``FE_SCALE_COUNTER`` - Number of error bits counted after the inner
+ coding.
+
+
+.. _DTV-STAT-POST-TOTAL-BIT-COUNT:
+
+DTV_STAT_POST_TOTAL_BIT_COUNT
+=============================
+
+Measures the amount of bits received after the inner coding, during the
+same period as
+:ref:`DTV_STAT_POST_ERROR_BIT_COUNT <DTV-STAT-POST-ERROR-BIT-COUNT>`
+measurement was taken.
+
+It should be noted that this measurement can be smaller than the total
+amount of bits on the transport stream, as the frontend may need to
+manually restart the measurement, losing some data between each
+measurement interval.
+
+This measurement is monotonically increased, as the frontend gets more
+bit count measurements. The frontend may reset it when a
+channel/transponder is tuned.
+
+Possible scales for this metric are:
+
+- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
+ measurement was not complete yet.
+
+- ``FE_SCALE_COUNTER`` - Number of bits counted while measuring
+ :ref:`DTV_STAT_POST_ERROR_BIT_COUNT <DTV-STAT-POST-ERROR-BIT-COUNT>`.
+
+
+.. _DTV-STAT-ERROR-BLOCK-COUNT:
+
+DTV_STAT_ERROR_BLOCK_COUNT
+==========================
+
+Measures the number of block errors after the outer forward error
+correction coding (after Reed-Solomon or other outer code).
+
+This measurement is monotonically increased, as the frontend gets more
+bit count measurements. The frontend may reset it when a
+channel/transponder is tuned.
+
+Possible scales for this metric are:
+
+- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
+ measurement was not complete yet.
+
+- ``FE_SCALE_COUNTER`` - Number of error blocks counted after the outer
+ coding.
+
+
+.. _DTV-STAT-TOTAL-BLOCK-COUNT:
+
+DTV-STAT_TOTAL_BLOCK_COUNT
+==========================
+
+Measures the total number of blocks received during the same period as
+:ref:`DTV_STAT_ERROR_BLOCK_COUNT <DTV-STAT-ERROR-BLOCK-COUNT>`
+measurement was taken.
+
+It can be used to calculate the PER indicator, by dividing
+:ref:`DTV_STAT_ERROR_BLOCK_COUNT <DTV-STAT-ERROR-BLOCK-COUNT>` by
+:ref:`DTV-STAT-TOTAL-BLOCK-COUNT`.
+
+Possible scales for this metric are:
+
+- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the
+ measurement was not complete yet.
+
+- ``FE_SCALE_COUNTER`` - Number of blocks counted while measuring
+ :ref:`DTV_STAT_ERROR_BLOCK_COUNT <DTV-STAT-ERROR-BLOCK-COUNT>`.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _dvb_frontend:
+
+################
+DVB Frontend API
+################
+The DVB frontend API was designed to support three types of delivery
+systems:
+
+- Terrestrial systems: DVB-T, DVB-T2, ATSC, ATSC M/H, ISDB-T, DVB-H,
+ DTMB, CMMB
+
+- Cable systems: DVB-C Annex A/C, ClearQAM (DVB-C Annex B), ISDB-C
+
+- Satellite systems: DVB-S, DVB-S2, DVB Turbo, ISDB-S, DSS
+
+The DVB frontend controls several sub-devices including:
+
+- Tuner
+
+- Digital TV demodulator
+
+- Low noise amplifier (LNA)
+
+- Satellite Equipment Control (SEC) hardware (only for Satellite).
+
+The frontend can be accessed through ``/dev/dvb/adapter?/frontend?``.
+Data types and ioctl definitions can be accessed by including
+``linux/dvb/frontend.h`` in your application.
+
+NOTE: Transmission via the internet (DVB-IP) is not yet handled by this
+API but a future extension is possible.
+
+On Satellite systems, the API support for the Satellite Equipment
+Control (SEC) allows to power control and to send/receive signals to
+control the antenna subsystem, selecting the polarization and choosing
+the Intermediate Frequency IF) of the Low Noise Block Converter Feed
+Horn (LNBf). It supports the DiSEqC and V-SEC protocols. The DiSEqC
+(digital SEC) specification is available at
+`Eutelsat <http://www.eutelsat.com/satellites/4_5_5.html>`__.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ query-dvb-frontend-info
+ dvb-fe-read-status
+ dvbproperty
+ frontend_fcalls
+ frontend_legacy_dvbv3_api
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _frontend_f_close:
+
+********************
+DVB frontend close()
+********************
+
+Name
+====
+
+fe-close - Close a frontend device
+
+
+Synopsis
+========
+
+.. code-block:: c
+
+ #include <unistd.h>
+
+
+.. cpp:function:: int close( int fd )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+
+Description
+===========
+
+This system call closes a previously opened front-end device. After
+closing a front-end device, its corresponding hardware might be powered
+down automatically.
+
+
+Return Value
+============
+
+The function returns 0 on success, -1 on failure and the ``errno`` is
+set appropriately. Possible error codes:
+
+EBADF
+ ``fd`` is not a valid open file descriptor.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _frontend_f_open:
+
+*******************
+DVB frontend open()
+*******************
+
+Name
+====
+
+fe-open - Open a frontend device
+
+
+Synopsis
+========
+
+.. code-block:: c
+
+ #include <fcntl.h>
+
+
+.. cpp:function:: int open( const char *device_name, int flags )
+
+
+Arguments
+=========
+
+``device_name``
+ Device to be opened.
+
+``flags``
+ Open flags. Access can either be ``O_RDWR`` or ``O_RDONLY``.
+
+ Multiple opens are allowed with ``O_RDONLY``. In this mode, only
+ query and read ioctls are allowed.
+
+ Only one open is allowed in ``O_RDWR``. In this mode, all ioctls are
+ allowed.
+
+ When the ``O_NONBLOCK`` flag is given, the system calls may return
+ ``EAGAIN`` error code when no data is available or when the device
+ driver is temporarily busy.
+
+ Other flags have no effect.
+
+
+Description
+===========
+
+This system call opens a named frontend device
+(``/dev/dvb/adapter?/frontend?``) for subsequent use. Usually the first
+thing to do after a successful open is to find out the frontend type
+with :ref:`FE_GET_INFO`.
+
+The device can be opened in read-only mode, which only allows monitoring
+of device status and statistics, or read/write mode, which allows any
+kind of use (e.g. performing tuning operations.)
+
+In a system with multiple front-ends, it is usually the case that
+multiple devices cannot be open in read/write mode simultaneously. As
+long as a front-end device is opened in read/write mode, other open()
+calls in read/write mode will either fail or block, depending on whether
+non-blocking or blocking mode was specified. A front-end device opened
+in blocking mode can later be put into non-blocking mode (and vice
+versa) using the F_SETFL command of the fcntl system call. This is a
+standard system call, documented in the Linux manual page for fcntl.
+When an open() call has succeeded, the device will be ready for use in
+the specified mode. This implies that the corresponding hardware is
+powered up, and that other front-ends may have been powered down to make
+that possible.
+
+
+Return Value
+============
+
+On success :ref:`open() <frontend_f_open>` returns the new file descriptor.
+On error, -1 is returned, and the ``errno`` variable is set appropriately.
+
+Possible error codes are:
+
+EACCES
+ The caller has no permission to access the device.
+
+EBUSY
+ The the device driver is already in use.
+
+ENXIO
+ No device corresponding to this device special file exists.
+
+ENOMEM
+ Not enough kernel memory was available to complete the request.
+
+EMFILE
+ The process already has the maximum number of files open.
+
+ENFILE
+ The limit on the total number of files open on the system has been
+ reached.
+
+ENODEV
+ The device got removed.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _frontend_fcalls:
+
+#######################
+Frontend Function Calls
+#######################
+
+.. toctree::
+ :maxdepth: 1
+
+ frontend_f_open
+ frontend_f_close
+ fe-get-info
+ fe-read-status
+ fe-get-property
+ fe-diseqc-reset-overload
+ fe-diseqc-send-master-cmd
+ fe-diseqc-recv-slave-reply
+ fe-diseqc-send-burst
+ fe-set-tone
+ fe-set-voltage
+ fe-enable-high-lnb-voltage
+ fe-set-frontend-tune-mode
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _frontend_h:
+
+************************
+DVB Frontend Header File
+************************
+
+.. kernel-include:: $BUILDDIR/frontend.h.rst
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _frontend_legacy_types:
+
+Frontend Legacy Data Types
+==========================
+
+
+.. toctree::
+ :maxdepth: 1
+
+ fe-type-t
+ fe-bandwidth-t
+ dvb-frontend-parameters
+ dvb-frontend-event
+
+
+.. _frontend_legacy_fcalls:
+
+Frontend Legacy Function Calls
+==============================
+
+Those functions are defined at DVB version 3. The support is kept in the
+kernel due to compatibility issues only. Their usage is strongly not
+recommended
+
+
+.. toctree::
+ :maxdepth: 1
+
+ fe-read-ber
+ fe-read-snr
+ fe-read-signal-strength
+ fe-read-uncorrected-blocks
+ fe-set-frontend
+ fe-get-frontend
+ fe-get-event
+ fe-dishnetwork-send-legacy-cmd
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _frontend_legacy_dvbv3_api:
+
+****************************************
+DVB Frontend legacy API (a. k. a. DVBv3)
+****************************************
+
+The usage of this API is deprecated, as it doesn't support all digital
+TV standards, doesn't provide good statistics measurements and provides
+incomplete information. This is kept only to support legacy
+applications.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ frontend_legacy_api
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _dvb_introdution:
+
+************
+Introduction
+************
+
+
+.. _requisites:
+
+What you need to know
+=====================
+
+The reader of this document is required to have some knowledge in the
+area of digital video broadcasting (DVB) and should be familiar with
+part I of the MPEG2 specification ISO/IEC 13818 (aka ITU-T H.222), i.e
+you should know what a program/transport stream (PS/TS) is and what is
+meant by a packetized elementary stream (PES) or an I-frame.
+
+Various DVB standards documents are available from http://www.dvb.org
+and/or http://www.etsi.org.
+
+It is also necessary to know how to access unix/linux devices and how to
+use ioctl calls. This also includes the knowledge of C or C++.
+
+
+.. _history:
+
+History
+=======
+
+The first API for DVB cards we used at Convergence in late 1999 was an
+extension of the Video4Linux API which was primarily developed for frame
+grabber cards. As such it was not really well suited to be used for DVB
+cards and their new features like recording MPEG streams and filtering
+several section and PES data streams at the same time.
+
+In early 2000, we were approached by Nokia with a proposal for a new
+standard Linux DVB API. As a commitment to the development of terminals
+based on open standards, Nokia and Convergence made it available to all
+Linux developers and published it on https://linuxtv.org in September
+2000. Convergence is the maintainer of the Linux DVB API. Together with
+the LinuxTV community (i.e. you, the reader of this document), the Linux
+DVB API will be constantly reviewed and improved. With the Linux driver
+for the Siemens/Hauppauge DVB PCI card Convergence provides a first
+implementation of the Linux DVB API.
+
+
+.. _overview:
+
+Overview
+========
+
+
+.. _stb_components:
+
+.. figure:: intro_files/dvbstb.*
+ :alt: dvbstb.pdf / dvbstb.png
+ :align: center
+
+ Components of a DVB card/STB
+
+A DVB PCI card or DVB set-top-box (STB) usually consists of the
+following main hardware components:
+
+- Frontend consisting of tuner and DVB demodulator
+
+ Here the raw signal reaches the DVB hardware from a satellite dish or
+ antenna or directly from cable. The frontend down-converts and
+ demodulates this signal into an MPEG transport stream (TS). In case
+ of a satellite frontend, this includes a facility for satellite
+ equipment control (SEC), which allows control of LNB polarization,
+ multi feed switches or dish rotors.
+
+- Conditional Access (CA) hardware like CI adapters and smartcard slots
+
+ The complete TS is passed through the CA hardware. Programs to which
+ the user has access (controlled by the smart card) are decoded in
+ real time and re-inserted into the TS.
+
+- Demultiplexer which filters the incoming DVB stream
+
+ The demultiplexer splits the TS into its components like audio and
+ video streams. Besides usually several of such audio and video
+ streams it also contains data streams with information about the
+ programs offered in this or other streams of the same provider.
+
+- MPEG2 audio and video decoder
+
+ The main targets of the demultiplexer are the MPEG2 audio and video
+ decoders. After decoding they pass on the uncompressed audio and
+ video to the computer screen or (through a PAL/NTSC encoder) to a TV
+ set.
+
+:ref:`stb_components` shows a crude schematic of the control and data
+flow between those components.
+
+On a DVB PCI card not all of these have to be present since some
+functionality can be provided by the main CPU of the PC (e.g. MPEG
+picture and sound decoding) or is not needed (e.g. for data-only uses
+like “internet over satellite”). Also not every card or STB provides
+conditional access hardware.
+
+
+.. _dvb_devices:
+
+Linux DVB Devices
+=================
+
+The Linux DVB API lets you control these hardware components through
+currently six Unix-style character devices for video, audio, frontend,
+demux, CA and IP-over-DVB networking. The video and audio devices
+control the MPEG2 decoder hardware, the frontend device the tuner and
+the DVB demodulator. The demux device gives you control over the PES and
+section filters of the hardware. If the hardware does not support
+filtering these filters can be implemented in software. Finally, the CA
+device controls all the conditional access capabilities of the hardware.
+It can depend on the individual security requirements of the platform,
+if and how many of the CA functions are made available to the
+application through this device.
+
+All devices can be found in the ``/dev`` tree under ``/dev/dvb``. The
+individual devices are called:
+
+- ``/dev/dvb/adapterN/audioM``,
+
+- ``/dev/dvb/adapterN/videoM``,
+
+- ``/dev/dvb/adapterN/frontendM``,
+
+- ``/dev/dvb/adapterN/netM``,
+
+- ``/dev/dvb/adapterN/demuxM``,
+
+- ``/dev/dvb/adapterN/dvrM``,
+
+- ``/dev/dvb/adapterN/caM``,
+
+where N enumerates the DVB PCI cards in a system starting from 0, and M
+enumerates the devices of each type within each adapter, starting
+from 0, too. We will omit the “ ``/dev/dvb/adapterN/``\ ” in the further
+discussion of these devices.
+
+More details about the data structures and function calls of all the
+devices are described in the following chapters.
+
+
+.. _include_files:
+
+API include files
+=================
+
+For each of the DVB devices a corresponding include file exists. The DVB
+API include files should be included in application sources with a
+partial path like:
+
+
+.. code-block:: c
+
+ #include <linux/dvb/ca.h>
+
+ #include <linux/dvb/dmx.h>
+
+ #include <linux/dvb/frontend.h>
+
+ #include <linux/dvb/net.h>
+
+
+To enable applications to support different API version, an additional
+include file ``linux/dvb/version.h`` exists, which defines the constant
+``DVB_API_VERSION``. This document describes ``DVB_API_VERSION 5.10``.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _legacy_dvb_apis:
+
+*******************
+DVB Deprecated APIs
+*******************
+
+The APIs described here are kept only for historical reasons. There's
+just one driver for a very legacy hardware that uses this API. No modern
+drivers should use it. Instead, audio and video should be using the V4L2
+and ALSA APIs, and the pipelines should be set using the Media
+Controller API
+
+
+.. toctree::
+ :maxdepth: 1
+
+ video
+ audio
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _NET_ADD_IF:
+
+****************
+ioctl NET_ADD_IF
+****************
+
+Name
+====
+
+NET_ADD_IF - Creates a new network interface for a given Packet ID.
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct dvb_net_if *net_if )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <frontend_f_open>`.
+
+``request``
+ FE_SET_TONE
+
+``net_if``
+ pointer to struct :ref:`dvb_net_if <dvb-net-if>`
+
+
+Description
+===========
+
+The NET_ADD_IF ioctl system call selects the Packet ID (PID) that
+contains a TCP/IP traffic, the type of encapsulation to be used (MPE or
+ULE) and the interface number for the new interface to be created. When
+the system call successfully returns, a new virtual network interface is
+created.
+
+The struct :ref:`dvb_net_if <dvb-net-if>`::ifnum field will be
+filled with the number of the created interface.
+
+
+.. _dvb-net-if-t:
+
+struct dvb_net_if description
+=============================
+
+.. _dvb-net-if:
+
+.. flat-table:: struct dvb_net_if
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ID
+
+ - Description
+
+ - .. row 2
+
+ - pid
+
+ - Packet ID (PID) of the MPEG-TS that contains data
+
+ - .. row 3
+
+ - ifnum
+
+ - number of the DVB interface.
+
+ - .. row 4
+
+ - feedtype
+
+ - Encapsulation type of the feed. It can be:
+ ``DVB_NET_FEEDTYPE_MPE`` for MPE encoding or
+ ``DVB_NET_FEEDTYPE_ULE`` for ULE encoding.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _NET_GET_IF:
+
+****************
+ioctl NET_GET_IF
+****************
+
+Name
+====
+
+NET_GET_IF - Read the configuration data of an interface created via - :ref:`NET_ADD_IF <net>`.
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct dvb_net_if *net_if )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <frontend_f_open>`.
+
+``request``
+ FE_SET_TONE
+
+``net_if``
+ pointer to struct :ref:`dvb_net_if <dvb-net-if>`
+
+
+Description
+===========
+
+The NET_GET_IF ioctl uses the interface number given by the struct
+:ref:`dvb_net_if <dvb-net-if>`::ifnum field and fills the content of
+struct :ref:`dvb_net_if <dvb-net-if>` with the packet ID and
+encapsulation type used on such interface. If the interface was not
+created yet with :ref:`NET_ADD_IF <net>`, it will return -1 and fill
+the ``errno`` with ``EINVAL`` error code.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _NET_REMOVE_IF:
+
+*******************
+ioctl NET_REMOVE_IF
+*******************
+
+Name
+====
+
+NET_REMOVE_IF - Removes a network interface.
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, int ifnum )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <frontend_f_open>`.
+
+``request``
+ FE_SET_TONE
+
+``net_if``
+ number of the interface to be removed
+
+
+Description
+===========
+
+The NET_REMOVE_IF ioctl deletes an interface previously created via
+:ref:`NET_ADD_IF <net>`.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _net:
+
+###############
+DVB Network API
+###############
+The DVB net device controls the mapping of data packages that are part
+of a transport stream to be mapped into a virtual network interface,
+visible through the standard Linux network protocol stack.
+
+Currently, two encapsulations are supported:
+
+- `Multi Protocol Encapsulation (MPE) <http://en.wikipedia.org/wiki/Multiprotocol_Encapsulation>`__
+
+- `Ultra Lightweight Encapsulation (ULE) <http://en.wikipedia.org/wiki/Unidirectional_Lightweight_Encapsulation>`__
+
+In order to create the Linux virtual network interfaces, an application
+needs to tell to the Kernel what are the PIDs and the encapsulation
+types that are present on the transport stream. This is done through
+``/dev/dvb/adapter?/net?`` device node. The data will be available via
+virtual ``dvb?_?`` network interfaces, and will be controlled/routed via
+the standard ip tools (like ip, route, netstat, ifconfig, etc).
+
+Data types and and ioctl definitions are defined via ``linux/dvb/net.h``
+header.
+
+
+.. _net_fcalls:
+
+######################
+DVB net Function Calls
+######################
+
+.. toctree::
+ :maxdepth: 1
+
+ net-add-if
+ net-remove-if
+ net-get-if
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _net_h:
+
+***********************
+DVB Network Header File
+***********************
+
+.. kernel-include:: $BUILDDIR/net.h.rst
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _query-dvb-frontend-info:
+
+*****************************
+Querying frontend information
+*****************************
+
+Usually, the first thing to do when the frontend is opened is to check
+the frontend capabilities. This is done using
+:ref:`FE_GET_INFO`. This ioctl will enumerate the
+DVB API version and other characteristics about the frontend, and can be
+opened either in read only or read/write mode.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDEO_CLEAR_BUFFER:
+
+==================
+VIDEO_CLEAR_BUFFER
+==================
+
+Name
+----
+
+VIDEO_CLEAR_BUFFER
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(fd, int request = VIDEO_CLEAR_BUFFER)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals VIDEO_CLEAR_BUFFER for this command.
+
+
+Description
+-----------
+
+This ioctl call clears all video buffers in the driver and in the
+decoder hardware.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDEO_COMMAND:
+
+=============
+VIDEO_COMMAND
+=============
+
+Name
+----
+
+VIDEO_COMMAND
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(int fd, int request = VIDEO_COMMAND, struct video_command *cmd)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals VIDEO_COMMAND for this command.
+
+ - .. row 3
+
+ - struct video_command \*cmd
+
+ - Commands the decoder.
+
+
+Description
+-----------
+
+This ioctl is obsolete. Do not use in new drivers. For V4L2 decoders
+this ioctl has been replaced by the
+:ref:`VIDIOC_DECODER_CMD` ioctl.
+
+This ioctl commands the decoder. The ``video_command`` struct is a
+subset of the ``v4l2_decoder_cmd`` struct, so refer to the
+:ref:`VIDIOC_DECODER_CMD` documentation for
+more information.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDEO_CONTINUE:
+
+==============
+VIDEO_CONTINUE
+==============
+
+Name
+----
+
+VIDEO_CONTINUE
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(fd, int request = VIDEO_CONTINUE)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals VIDEO_CONTINUE for this command.
+
+
+Description
+-----------
+
+This ioctl is for DVB devices only. To control a V4L2 decoder use the
+V4L2 :ref:`VIDIOC_DECODER_CMD` instead.
+
+This ioctl call restarts decoding and playing processes of the video
+stream which was played before a call to VIDEO_FREEZE was made.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDEO_FAST_FORWARD:
+
+==================
+VIDEO_FAST_FORWARD
+==================
+
+Name
+----
+
+VIDEO_FAST_FORWARD
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(fd, int request = VIDEO_FAST_FORWARD, int nFrames)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals VIDEO_FAST_FORWARD for this command.
+
+ - .. row 3
+
+ - int nFrames
+
+ - The number of frames to skip.
+
+
+Description
+-----------
+
+This ioctl call asks the Video Device to skip decoding of N number of
+I-frames. This call can only be used if VIDEO_SOURCE_MEMORY is
+selected.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``EPERM``
+
+ - Mode VIDEO_SOURCE_MEMORY not selected.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _video_fclose:
+
+=================
+dvb video close()
+=================
+
+Name
+----
+
+dvb video close()
+
+
+Synopsis
+--------
+
+.. cpp:function:: int close(int fd)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+
+Description
+-----------
+
+This system call closes a previously opened video device.
+
+
+Return Value
+------------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``EBADF``
+
+ - fd is not a valid open file descriptor.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _video_fopen:
+
+================
+dvb video open()
+================
+
+Name
+----
+
+dvb video open()
+
+
+Synopsis
+--------
+
+.. cpp:function:: int open(const char *deviceName, int flags)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - const char \*deviceName
+
+ - Name of specific video device.
+
+ - .. row 2
+
+ - int flags
+
+ - A bit-wise OR of the following flags:
+
+ - .. row 3
+
+ -
+ - O_RDONLY read-only access
+
+ - .. row 4
+
+ -
+ - O_RDWR read/write access
+
+ - .. row 5
+
+ -
+ - O_NONBLOCK open in non-blocking mode
+
+ - .. row 6
+
+ -
+ - (blocking mode is the default)
+
+
+Description
+-----------
+
+This system call opens a named video device (e.g.
+/dev/dvb/adapter0/video0) for subsequent use.
+
+When an open() call has succeeded, the device will be ready for use. The
+significance of blocking or non-blocking mode is described in the
+documentation for functions where there is a difference. It does not
+affect the semantics of the open() call itself. A device opened in
+blocking mode can later be put into non-blocking mode (and vice versa)
+using the F_SETFL command of the fcntl system call. This is a standard
+system call, documented in the Linux manual page for fcntl. Only one
+user can open the Video Device in O_RDWR mode. All other attempts to
+open the device in this mode will fail, and an error-code will be
+returned. If the Video Device is opened in O_RDONLY mode, the only
+ioctl call that can be used is VIDEO_GET_STATUS. All other call will
+return an error code.
+
+
+Return Value
+------------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``ENODEV``
+
+ - Device driver not loaded/available.
+
+ - .. row 2
+
+ - ``EINTERNAL``
+
+ - Internal error.
+
+ - .. row 3
+
+ - ``EBUSY``
+
+ - Device or resource busy.
+
+ - .. row 4
+
+ - ``EINVAL``
+
+ - Invalid argument.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDEO_FREEZE:
+
+============
+VIDEO_FREEZE
+============
+
+Name
+----
+
+VIDEO_FREEZE
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(fd, int request = VIDEO_FREEZE)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals VIDEO_FREEZE for this command.
+
+
+Description
+-----------
+
+This ioctl is for DVB devices only. To control a V4L2 decoder use the
+V4L2 :ref:`VIDIOC_DECODER_CMD` instead.
+
+This ioctl call suspends the live video stream being played. Decoding
+and playing are frozen. It is then possible to restart the decoding and
+playing process of the video stream using the VIDEO_CONTINUE command.
+If VIDEO_SOURCE_MEMORY is selected in the ioctl call
+VIDEO_SELECT_SOURCE, the DVB subsystem will not decode any more data
+until the ioctl call VIDEO_CONTINUE or VIDEO_PLAY is performed.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _video_fwrite:
+
+=================
+dvb video write()
+=================
+
+Name
+----
+
+dvb video write()
+
+
+Synopsis
+--------
+
+.. cpp:function:: size_t write(int fd, const void *buf, size_t count)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - void \*buf
+
+ - Pointer to the buffer containing the PES data.
+
+ - .. row 3
+
+ - size_t count
+
+ - Size of buf.
+
+
+Description
+-----------
+
+This system call can only be used if VIDEO_SOURCE_MEMORY is selected
+in the ioctl call VIDEO_SELECT_SOURCE. The data provided shall be in
+PES format, unless the capability allows other formats. If O_NONBLOCK
+is not specified the function will block until buffer space is
+available. The amount of data to be transferred is implied by count.
+
+
+Return Value
+------------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``EPERM``
+
+ - Mode VIDEO_SOURCE_MEMORY not selected.
+
+ - .. row 2
+
+ - ``ENOMEM``
+
+ - Attempted to write more data than the internal buffer can hold.
+
+ - .. row 3
+
+ - ``EBADF``
+
+ - fd is not a valid open file descriptor.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDEO_GET_CAPABILITIES:
+
+======================
+VIDEO_GET_CAPABILITIES
+======================
+
+Name
+----
+
+VIDEO_GET_CAPABILITIES
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(fd, int request = VIDEO_GET_CAPABILITIES, unsigned int *cap)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals VIDEO_GET_CAPABILITIES for this command.
+
+ - .. row 3
+
+ - unsigned int \*cap
+
+ - Pointer to a location where to store the capability information.
+
+
+Description
+-----------
+
+This ioctl call asks the video device about its decoding capabilities.
+On success it returns and integer which has bits set according to the
+defines in section ??.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDEO_GET_EVENT:
+
+===============
+VIDEO_GET_EVENT
+===============
+
+Name
+----
+
+VIDEO_GET_EVENT
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(fd, int request = VIDEO_GET_EVENT, struct video_event *ev)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals VIDEO_GET_EVENT for this command.
+
+ - .. row 3
+
+ - struct video_event \*ev
+
+ - Points to the location where the event, if any, is to be stored.
+
+
+Description
+-----------
+
+This ioctl is for DVB devices only. To get events from a V4L2 decoder
+use the V4L2 :ref:`VIDIOC_DQEVENT` ioctl instead.
+
+This ioctl call returns an event of type video_event if available. If
+an event is not available, the behavior depends on whether the device is
+in blocking or non-blocking mode. In the latter case, the call fails
+immediately with errno set to ``EWOULDBLOCK``. In the former case, the call
+blocks until an event becomes available. The standard Linux poll()
+and/or select() system calls can be used with the device file descriptor
+to watch for new events. For select(), the file descriptor should be
+included in the exceptfds argument, and for poll(), POLLPRI should be
+specified as the wake-up condition. Read-only permissions are sufficient
+for this ioctl call.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``EWOULDBLOCK``
+
+ - There is no event pending, and the device is in non-blocking mode.
+
+ - .. row 2
+
+ - ``EOVERFLOW``
+
+ - Overflow in event queue - one or more events were lost.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDEO_GET_FRAME_COUNT:
+
+=====================
+VIDEO_GET_FRAME_COUNT
+=====================
+
+Name
+----
+
+VIDEO_GET_FRAME_COUNT
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(int fd, int request = VIDEO_GET_FRAME_COUNT, __u64 *pts)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals VIDEO_GET_FRAME_COUNT for this command.
+
+ - .. row 3
+
+ - __u64 \*pts
+
+ - Returns the number of frames displayed since the decoder was
+ started.
+
+
+Description
+-----------
+
+This ioctl is obsolete. Do not use in new drivers. For V4L2 decoders
+this ioctl has been replaced by the ``V4L2_CID_MPEG_VIDEO_DEC_FRAME``
+control.
+
+This ioctl call asks the Video Device to return the number of displayed
+frames since the decoder was started.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDEO_GET_FRAME_RATE:
+
+====================
+VIDEO_GET_FRAME_RATE
+====================
+
+Name
+----
+
+VIDEO_GET_FRAME_RATE
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(int fd, int request = VIDEO_GET_FRAME_RATE, unsigned int *rate)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals VIDEO_GET_FRAME_RATE for this command.
+
+ - .. row 3
+
+ - unsigned int \*rate
+
+ - Returns the framerate in number of frames per 1000 seconds.
+
+
+Description
+-----------
+
+This ioctl call asks the Video Device to return the current framerate.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDEO_GET_NAVI:
+
+==============
+VIDEO_GET_NAVI
+==============
+
+Name
+----
+
+VIDEO_GET_NAVI
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(fd, int request = VIDEO_GET_NAVI , video_navi_pack_t *navipack)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals VIDEO_GET_NAVI for this command.
+
+ - .. row 3
+
+ - video_navi_pack_t \*navipack
+
+ - PCI or DSI pack (private stream 2) according to section ??.
+
+
+Description
+-----------
+
+This ioctl returns navigational information from the DVD stream. This is
+especially needed if an encoded stream has to be decoded by the
+hardware.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``EFAULT``
+
+ - driver is not able to return navigational information
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDEO_GET_PTS:
+
+=============
+VIDEO_GET_PTS
+=============
+
+Name
+----
+
+VIDEO_GET_PTS
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(int fd, int request = VIDEO_GET_PTS, __u64 *pts)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals VIDEO_GET_PTS for this command.
+
+ - .. row 3
+
+ - __u64 \*pts
+
+ - Returns the 33-bit timestamp as defined in ITU T-REC-H.222.0 /
+ ISO/IEC 13818-1.
+
+ The PTS should belong to the currently played frame if possible,
+ but may also be a value close to it like the PTS of the last
+ decoded frame or the last PTS extracted by the PES parser.
+
+
+Description
+-----------
+
+This ioctl is obsolete. Do not use in new drivers. For V4L2 decoders
+this ioctl has been replaced by the ``V4L2_CID_MPEG_VIDEO_DEC_PTS``
+control.
+
+This ioctl call asks the Video Device to return the current PTS
+timestamp.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDEO_GET_SIZE:
+
+==============
+VIDEO_GET_SIZE
+==============
+
+Name
+----
+
+VIDEO_GET_SIZE
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(int fd, int request = VIDEO_GET_SIZE, video_size_t *size)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals VIDEO_GET_SIZE for this command.
+
+ - .. row 3
+
+ - video_size_t \*size
+
+ - Returns the size and aspect ratio.
+
+
+Description
+-----------
+
+This ioctl returns the size and aspect ratio.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDEO_GET_STATUS:
+
+================
+VIDEO_GET_STATUS
+================
+
+Name
+----
+
+VIDEO_GET_STATUS
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(fd, int request = VIDEO_GET_STATUS, struct video_status *status)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals VIDEO_GET_STATUS for this command.
+
+ - .. row 3
+
+ - struct video_status \*status
+
+ - Returns the current status of the Video Device.
+
+
+Description
+-----------
+
+This ioctl call asks the Video Device to return the current status of
+the device.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDEO_PLAY:
+
+==========
+VIDEO_PLAY
+==========
+
+Name
+----
+
+VIDEO_PLAY
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(fd, int request = VIDEO_PLAY)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals VIDEO_PLAY for this command.
+
+
+Description
+-----------
+
+This ioctl is for DVB devices only. To control a V4L2 decoder use the
+V4L2 :ref:`VIDIOC_DECODER_CMD` instead.
+
+This ioctl call asks the Video Device to start playing a video stream
+from the selected source.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDEO_SELECT_SOURCE:
+
+===================
+VIDEO_SELECT_SOURCE
+===================
+
+Name
+----
+
+VIDEO_SELECT_SOURCE
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(fd, int request = VIDEO_SELECT_SOURCE, video_stream_source_t source)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals VIDEO_SELECT_SOURCE for this command.
+
+ - .. row 3
+
+ - video_stream_source_t source
+
+ - Indicates which source shall be used for the Video stream.
+
+
+Description
+-----------
+
+This ioctl is for DVB devices only. This ioctl was also supported by the
+V4L2 ivtv driver, but that has been replaced by the ivtv-specific
+``IVTV_IOC_PASSTHROUGH_MODE`` ioctl.
+
+This ioctl call informs the video device which source shall be used for
+the input data. The possible sources are demux or memory. If memory is
+selected, the data is fed to the video device through the write command.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDEO_SET_ATTRIBUTES:
+
+====================
+VIDEO_SET_ATTRIBUTES
+====================
+
+Name
+----
+
+VIDEO_SET_ATTRIBUTES
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(fd, int request = VIDEO_SET_ATTRIBUTE ,video_attributes_t vattr)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals VIDEO_SET_ATTRIBUTE for this command.
+
+ - .. row 3
+
+ - video_attributes_t vattr
+
+ - video attributes according to section ??.
+
+
+Description
+-----------
+
+This ioctl is intended for DVD playback and allows you to set certain
+information about the stream. Some hardware may not need this
+information, but the call also tells the hardware to prepare for DVD
+playback.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``EINVAL``
+
+ - input is not a valid attribute setting.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDEO_SET_BLANK:
+
+===============
+VIDEO_SET_BLANK
+===============
+
+Name
+----
+
+VIDEO_SET_BLANK
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(fd, int request = VIDEO_SET_BLANK, boolean mode)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals VIDEO_SET_BLANK for this command.
+
+ - .. row 3
+
+ - boolean mode
+
+ - TRUE: Blank screen when stop.
+
+ - .. row 4
+
+ -
+ - FALSE: Show last decoded frame.
+
+
+Description
+-----------
+
+This ioctl call asks the Video Device to blank out the picture.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDEO_SET_DISPLAY_FORMAT:
+
+========================
+VIDEO_SET_DISPLAY_FORMAT
+========================
+
+Name
+----
+
+VIDEO_SET_DISPLAY_FORMAT
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(fd, int request = VIDEO_SET_DISPLAY_FORMAT, video_display_format_t format)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals VIDEO_SET_DISPLAY_FORMAT for this command.
+
+ - .. row 3
+
+ - video_display_format_t format
+
+ - Selects the video format to be used.
+
+
+Description
+-----------
+
+This ioctl call asks the Video Device to select the video format to be
+applied by the MPEG chip on the video.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDEO_SET_FORMAT:
+
+================
+VIDEO_SET_FORMAT
+================
+
+Name
+----
+
+VIDEO_SET_FORMAT
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(fd, int request = VIDEO_SET_FORMAT, video_format_t format)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals VIDEO_SET_FORMAT for this command.
+
+ - .. row 3
+
+ - video_format_t format
+
+ - video format of TV as defined in section ??.
+
+
+Description
+-----------
+
+This ioctl sets the screen format (aspect ratio) of the connected output
+device (TV) so that the output of the decoder can be adjusted
+accordingly.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``EINVAL``
+
+ - format is not a valid video format.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDEO_SET_HIGHLIGHT:
+
+===================
+VIDEO_SET_HIGHLIGHT
+===================
+
+Name
+----
+
+VIDEO_SET_HIGHLIGHT
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(fd, int request = VIDEO_SET_HIGHLIGHT ,video_highlight_t *vhilite)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals VIDEO_SET_HIGHLIGHT for this command.
+
+ - .. row 3
+
+ - video_highlight_t \*vhilite
+
+ - SPU Highlight information according to section ??.
+
+
+Description
+-----------
+
+This ioctl sets the SPU highlight information for the menu access of a
+DVD.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDEO_SET_ID:
+
+============
+VIDEO_SET_ID
+============
+
+Name
+----
+
+VIDEO_SET_ID
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(int fd, int request = VIDEO_SET_ID, int id)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals VIDEO_SET_ID for this command.
+
+ - .. row 3
+
+ - int id
+
+ - video sub-stream id
+
+
+Description
+-----------
+
+This ioctl selects which sub-stream is to be decoded if a program or
+system stream is sent to the video device.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``EINVAL``
+
+ - Invalid sub-stream id.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDEO_SET_SPU_PALETTE:
+
+=====================
+VIDEO_SET_SPU_PALETTE
+=====================
+
+Name
+----
+
+VIDEO_SET_SPU_PALETTE
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(fd, int request = VIDEO_SET_SPU_PALETTE, video_spu_palette_t *palette )
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals VIDEO_SET_SPU_PALETTE for this command.
+
+ - .. row 3
+
+ - video_spu_palette_t \*palette
+
+ - SPU palette according to section ??.
+
+
+Description
+-----------
+
+This ioctl sets the SPU color palette.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``EINVAL``
+
+ - input is not a valid palette or driver doesn’t handle SPU.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDEO_SET_SPU:
+
+=============
+VIDEO_SET_SPU
+=============
+
+Name
+----
+
+VIDEO_SET_SPU
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(fd, int request = VIDEO_SET_SPU , video_spu_t *spu)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals VIDEO_SET_SPU for this command.
+
+ - .. row 3
+
+ - video_spu_t \*spu
+
+ - SPU decoding (de)activation and subid setting according to section
+ ??.
+
+
+Description
+-----------
+
+This ioctl activates or deactivates SPU decoding in a DVD input stream.
+It can only be used, if the driver is able to handle a DVD stream.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``EINVAL``
+
+ - input is not a valid spu setting or driver cannot handle SPU.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDEO_SET_STREAMTYPE:
+
+====================
+VIDEO_SET_STREAMTYPE
+====================
+
+Name
+----
+
+VIDEO_SET_STREAMTYPE
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(fd, int request = VIDEO_SET_STREAMTYPE, int type)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals VIDEO_SET_STREAMTYPE for this command.
+
+ - .. row 3
+
+ - int type
+
+ - stream type
+
+
+Description
+-----------
+
+This ioctl tells the driver which kind of stream to expect being written
+to it. If this call is not used the default of video PES is used. Some
+drivers might not support this call and always expect PES.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDEO_SET_SYSTEM:
+
+================
+VIDEO_SET_SYSTEM
+================
+
+Name
+----
+
+VIDEO_SET_SYSTEM
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(fd, int request = VIDEO_SET_SYSTEM , video_system_t system)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals VIDEO_SET_FORMAT for this command.
+
+ - .. row 3
+
+ - video_system_t system
+
+ - video system of TV output.
+
+
+Description
+-----------
+
+This ioctl sets the television output format. The format (see section
+??) may vary from the color format of the displayed MPEG stream. If the
+hardware is not able to display the requested format the call will
+return an error.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``EINVAL``
+
+ - system is not a valid or supported video system.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDEO_SLOWMOTION:
+
+================
+VIDEO_SLOWMOTION
+================
+
+Name
+----
+
+VIDEO_SLOWMOTION
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(fd, int request = VIDEO_SLOWMOTION, int nFrames)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals VIDEO_SLOWMOTION for this command.
+
+ - .. row 3
+
+ - int nFrames
+
+ - The number of times to repeat each frame.
+
+
+Description
+-----------
+
+This ioctl call asks the video device to repeat decoding frames N number
+of times. This call can only be used if VIDEO_SOURCE_MEMORY is
+selected.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``EPERM``
+
+ - Mode VIDEO_SOURCE_MEMORY not selected.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDEO_STILLPICTURE:
+
+==================
+VIDEO_STILLPICTURE
+==================
+
+Name
+----
+
+VIDEO_STILLPICTURE
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(fd, int request = VIDEO_STILLPICTURE, struct video_still_picture *sp)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals VIDEO_STILLPICTURE for this command.
+
+ - .. row 3
+
+ - struct video_still_picture \*sp
+
+ - Pointer to a location where an I-frame and size is stored.
+
+
+Description
+-----------
+
+This ioctl call asks the Video Device to display a still picture
+(I-frame). The input data shall contain an I-frame. If the pointer is
+NULL, then the current displayed still picture is blanked.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDEO_STOP:
+
+==========
+VIDEO_STOP
+==========
+
+Name
+----
+
+VIDEO_STOP
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(fd, int request = VIDEO_STOP, boolean mode)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals VIDEO_STOP for this command.
+
+ - .. row 3
+
+ - Boolean mode
+
+ - Indicates how the screen shall be handled.
+
+ - .. row 4
+
+ -
+ - TRUE: Blank screen when stop.
+
+ - .. row 5
+
+ -
+ - FALSE: Show last decoded frame.
+
+
+Description
+-----------
+
+This ioctl is for DVB devices only. To control a V4L2 decoder use the
+V4L2 :ref:`VIDIOC_DECODER_CMD` instead.
+
+This ioctl call asks the Video Device to stop playing the current
+stream. Depending on the input parameter, the screen can be blanked out
+or displaying the last decoded frame.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDEO_TRY_COMMAND:
+
+=================
+VIDEO_TRY_COMMAND
+=================
+
+Name
+----
+
+VIDEO_TRY_COMMAND
+
+
+Synopsis
+--------
+
+.. cpp:function:: int ioctl(int fd, int request = VIDEO_TRY_COMMAND, struct video_command *cmd)
+
+
+Arguments
+---------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - int fd
+
+ - File descriptor returned by a previous call to open().
+
+ - .. row 2
+
+ - int request
+
+ - Equals VIDEO_TRY_COMMAND for this command.
+
+ - .. row 3
+
+ - struct video_command \*cmd
+
+ - Try a decoder command.
+
+
+Description
+-----------
+
+This ioctl is obsolete. Do not use in new drivers. For V4L2 decoders
+this ioctl has been replaced by the
+:ref:`VIDIOC_TRY_DECODER_CMD <VIDIOC_DECODER_CMD>` ioctl.
+
+This ioctl tries a decoder command. The ``video_command`` struct is a
+subset of the ``v4l2_decoder_cmd`` struct, so refer to the
+:ref:`VIDIOC_TRY_DECODER_CMD <VIDIOC_DECODER_CMD>` documentation
+for more information.
+
+
+Return Value
+------------
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _dvb_video:
+
+################
+DVB Video Device
+################
+The DVB video device controls the MPEG2 video decoder of the DVB
+hardware. It can be accessed through **/dev/dvb/adapter0/video0**. Data
+types and and ioctl definitions can be accessed by including
+**linux/dvb/video.h** in your application.
+
+Note that the DVB video device only controls decoding of the MPEG video
+stream, not its presentation on the TV or computer screen. On PCs this
+is typically handled by an associated video4linux device, e.g.
+**/dev/video**, which allows scaling and defining output windows.
+
+Some DVB cards don’t have their own MPEG decoder, which results in the
+omission of the audio and video device as well as the video4linux
+device.
+
+The ioctls that deal with SPUs (sub picture units) and navigation
+packets are only supported on some MPEG decoders made for DVD playback.
+
+These ioctls were also used by V4L2 to control MPEG decoders implemented
+in V4L2. The use of these ioctls for that purpose has been made obsolete
+and proper V4L2 ioctls or controls have been created to replace that
+functionality.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ video_types
+ video_function_calls
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _video_function_calls:
+
+********************
+Video Function Calls
+********************
+
+.. toctree::
+ :maxdepth: 1
+
+ video-fopen
+ video-fclose
+ video-fwrite
+ video-stop
+ video-play
+ video-freeze
+ video-continue
+ video-select-source
+ video-set-blank
+ video-get-status
+ video-get-frame-count
+ video-get-pts
+ video-get-frame-rate
+ video-get-event
+ video-command
+ video-try-command
+ video-get-size
+ video-set-display-format
+ video-stillpicture
+ video-fast-forward
+ video-slowmotion
+ video-get-capabilities
+ video-set-id
+ video-clear-buffer
+ video-set-streamtype
+ video-set-format
+ video-set-system
+ video-set-highlight
+ video-set-spu
+ video-set-spu-palette
+ video-get-navi
+ video-set-attributes
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _video_h:
+
+*********************
+DVB Video Header File
+*********************
+
+.. kernel-include:: $BUILDDIR/video.h.rst
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _video_types:
+
+****************
+Video Data Types
+****************
+
+
+.. _video-format-t:
+
+video_format_t
+==============
+
+The ``video_format_t`` data type defined by
+
+
+.. code-block:: c
+
+ typedef enum {
+ VIDEO_FORMAT_4_3, /* Select 4:3 format */
+ VIDEO_FORMAT_16_9, /* Select 16:9 format. */
+ VIDEO_FORMAT_221_1 /* 2.21:1 */
+ } video_format_t;
+
+is used in the VIDEO_SET_FORMAT function (??) to tell the driver which
+aspect ratio the output hardware (e.g. TV) has. It is also used in the
+data structures video_status (??) returned by VIDEO_GET_STATUS (??)
+and video_event (??) returned by VIDEO_GET_EVENT (??) which report
+about the display format of the current video stream.
+
+
+.. _video-displayformat-t:
+
+video_displayformat_t
+=====================
+
+In case the display format of the video stream and of the display
+hardware differ the application has to specify how to handle the
+cropping of the picture. This can be done using the
+VIDEO_SET_DISPLAY_FORMAT call (??) which accepts
+
+
+.. code-block:: c
+
+ typedef enum {
+ VIDEO_PAN_SCAN, /* use pan and scan format */
+ VIDEO_LETTER_BOX, /* use letterbox format */
+ VIDEO_CENTER_CUT_OUT /* use center cut out format */
+ } video_displayformat_t;
+
+as argument.
+
+
+.. _video-stream-source-t:
+
+video_stream_source_t
+=====================
+
+The video stream source is set through the VIDEO_SELECT_SOURCE call
+and can take the following values, depending on whether we are replaying
+from an internal (demuxer) or external (user write) source.
+
+
+.. code-block:: c
+
+ typedef enum {
+ VIDEO_SOURCE_DEMUX, /* Select the demux as the main source */
+ VIDEO_SOURCE_MEMORY /* If this source is selected, the stream
+ comes from the user through the write
+ system call */
+ } video_stream_source_t;
+
+VIDEO_SOURCE_DEMUX selects the demultiplexer (fed either by the
+frontend or the DVR device) as the source of the video stream. If
+VIDEO_SOURCE_MEMORY is selected the stream comes from the application
+through the **write()** system call.
+
+
+.. _video-play-state-t:
+
+video_play_state_t
+==================
+
+The following values can be returned by the VIDEO_GET_STATUS call
+representing the state of video playback.
+
+
+.. code-block:: c
+
+ typedef enum {
+ VIDEO_STOPPED, /* Video is stopped */
+ VIDEO_PLAYING, /* Video is currently playing */
+ VIDEO_FREEZED /* Video is freezed */
+ } video_play_state_t;
+
+
+.. _video-command:
+
+struct video_command
+====================
+
+The structure must be zeroed before use by the application This ensures
+it can be extended safely in the future.
+
+
+.. code-block:: c
+
+ struct video_command {
+ __u32 cmd;
+ __u32 flags;
+ union {
+ struct {
+ __u64 pts;
+ } stop;
+
+ struct {
+ /* 0 or 1000 specifies normal speed,
+ 1 specifies forward single stepping,
+ -1 specifies backward single stepping,
+ >>1: playback at speed/1000 of the normal speed,
+ <-1: reverse playback at (-speed/1000) of the normal speed. */
+ __s32 speed;
+ __u32 format;
+ } play;
+
+ struct {
+ __u32 data[16];
+ } raw;
+ };
+ };
+
+
+.. _video-size-t:
+
+video_size_t
+============
+
+
+.. code-block:: c
+
+ typedef struct {
+ int w;
+ int h;
+ video_format_t aspect_ratio;
+ } video_size_t;
+
+
+.. _video-event:
+
+struct video_event
+==================
+
+The following is the structure of a video event as it is returned by the
+VIDEO_GET_EVENT call.
+
+
+.. code-block:: c
+
+ struct video_event {
+ __s32 type;
+ #define VIDEO_EVENT_SIZE_CHANGED 1
+ #define VIDEO_EVENT_FRAME_RATE_CHANGED 2
+ #define VIDEO_EVENT_DECODER_STOPPED 3
+ #define VIDEO_EVENT_VSYNC 4
+ __kernel_time_t timestamp;
+ union {
+ video_size_t size;
+ unsigned int frame_rate; /* in frames per 1000sec */
+ unsigned char vsync_field; /* unknown/odd/even/progressive */
+ } u;
+ };
+
+
+.. _video-status:
+
+struct video_status
+===================
+
+The VIDEO_GET_STATUS call returns the following structure informing
+about various states of the playback operation.
+
+
+.. code-block:: c
+
+ struct video_status {
+ int video_blank; /* blank video on freeze? */
+ video_play_state_t play_state; /* current state of playback */
+ video_stream_source_t stream_source; /* current source (demux/memory) */
+ video_format_t video_format; /* current aspect ratio of stream */
+ video_displayformat_t display_format;/* selected cropping mode */
+ };
+
+If video_blank is set video will be blanked out if the channel is
+changed or if playback is stopped. Otherwise, the last picture will be
+displayed. play_state indicates if the video is currently frozen,
+stopped, or being played back. The stream_source corresponds to the
+seleted source for the video stream. It can come either from the
+demultiplexer or from memory. The video_format indicates the aspect
+ratio (one of 4:3 or 16:9) of the currently played video stream.
+Finally, display_format corresponds to the selected cropping mode in
+case the source video format is not the same as the format of the output
+device.
+
+
+.. _video-still-picture:
+
+struct video_still_picture
+==========================
+
+An I-frame displayed via the VIDEO_STILLPICTURE call is passed on
+within the following structure.
+
+
+.. code-block:: c
+
+ /* pointer to and size of a single iframe in memory */
+ struct video_still_picture {
+ char *iFrame; /* pointer to a single iframe in memory */
+ int32_t size;
+ };
+
+
+.. _video_caps:
+
+video capabilities
+==================
+
+A call to VIDEO_GET_CAPABILITIES returns an unsigned integer with the
+following bits set according to the hardwares capabilities.
+
+
+.. code-block:: c
+
+ /* bit definitions for capabilities: */
+ /* can the hardware decode MPEG1 and/or MPEG2? */
+ #define VIDEO_CAP_MPEG1 1
+ #define VIDEO_CAP_MPEG2 2
+ /* can you send a system and/or program stream to video device?
+ (you still have to open the video and the audio device but only
+ send the stream to the video device) */
+ #define VIDEO_CAP_SYS 4
+ #define VIDEO_CAP_PROG 8
+ /* can the driver also handle SPU, NAVI and CSS encoded data?
+ (CSS API is not present yet) */
+ #define VIDEO_CAP_SPU 16
+ #define VIDEO_CAP_NAVI 32
+ #define VIDEO_CAP_CSS 64
+
+
+.. _video-system:
+
+video_system_t
+==============
+
+A call to VIDEO_SET_SYSTEM sets the desired video system for TV
+output. The following system types can be set:
+
+
+.. code-block:: c
+
+ typedef enum {
+ VIDEO_SYSTEM_PAL,
+ VIDEO_SYSTEM_NTSC,
+ VIDEO_SYSTEM_PALN,
+ VIDEO_SYSTEM_PALNc,
+ VIDEO_SYSTEM_PALM,
+ VIDEO_SYSTEM_NTSC60,
+ VIDEO_SYSTEM_PAL60,
+ VIDEO_SYSTEM_PALM60
+ } video_system_t;
+
+
+.. _video-highlight:
+
+struct video_highlight
+======================
+
+Calling the ioctl VIDEO_SET_HIGHLIGHTS posts the SPU highlight
+information. The call expects the following format for that information:
+
+
+.. code-block:: c
+
+ typedef
+ struct video_highlight {
+ boolean active; /* 1=show highlight, 0=hide highlight */
+ uint8_t contrast1; /* 7- 4 Pattern pixel contrast */
+ /* 3- 0 Background pixel contrast */
+ uint8_t contrast2; /* 7- 4 Emphasis pixel-2 contrast */
+ /* 3- 0 Emphasis pixel-1 contrast */
+ uint8_t color1; /* 7- 4 Pattern pixel color */
+ /* 3- 0 Background pixel color */
+ uint8_t color2; /* 7- 4 Emphasis pixel-2 color */
+ /* 3- 0 Emphasis pixel-1 color */
+ uint32_t ypos; /* 23-22 auto action mode */
+ /* 21-12 start y */
+ /* 9- 0 end y */
+ uint32_t xpos; /* 23-22 button color number */
+ /* 21-12 start x */
+ /* 9- 0 end x */
+ } video_highlight_t;
+
+
+.. _video-spu:
+
+struct video_spu
+================
+
+Calling VIDEO_SET_SPU deactivates or activates SPU decoding, according
+to the following format:
+
+
+.. code-block:: c
+
+ typedef
+ struct video_spu {
+ boolean active;
+ int stream_id;
+ } video_spu_t;
+
+
+.. _video-spu-palette:
+
+struct video_spu_palette
+========================
+
+The following structure is used to set the SPU palette by calling
+VIDEO_SPU_PALETTE:
+
+
+.. code-block:: c
+
+ typedef
+ struct video_spu_palette {
+ int length;
+ uint8_t *palette;
+ } video_spu_palette_t;
+
+
+.. _video-navi-pack:
+
+struct video_navi_pack
+======================
+
+In order to get the navigational data the following structure has to be
+passed to the ioctl VIDEO_GET_NAVI:
+
+
+.. code-block:: c
+
+ typedef
+ struct video_navi_pack {
+ int length; /* 0 ... 1024 */
+ uint8_t data[1024];
+ } video_navi_pack_t;
+
+
+.. _video-attributes-t:
+
+video_attributes_t
+==================
+
+The following attributes can be set by a call to VIDEO_SET_ATTRIBUTES:
+
+
+.. code-block:: c
+
+ typedef uint16_t video_attributes_t;
+ /* bits: descr. */
+ /* 15-14 Video compression mode (0=MPEG-1, 1=MPEG-2) */
+ /* 13-12 TV system (0=525/60, 1=625/50) */
+ /* 11-10 Aspect ratio (0=4:3, 3=16:9) */
+ /* 9- 8 permitted display mode on 4:3 monitor (0=both, 1=only pan-sca */
+ /* 7 line 21-1 data present in GOP (1=yes, 0=no) */
+ /* 6 line 21-2 data present in GOP (1=yes, 0=no) */
+ /* 5- 3 source resolution (0=720x480/576, 1=704x480/576, 2=352x480/57 */
+ /* 2 source letterboxed (1=yes, 0=no) */
+ /* 0 film/camera mode (0=camera, 1=film (625/50 only)) */
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _fdl:
+
+******************************
+GNU Free Documentation License
+******************************
+
+
+.. _fdl-preamble:
+
+0. PREAMBLE
+===========
+
+The purpose of this License is to make a manual, textbook, or other
+written document “free” in the sense of freedom: to assure everyone the
+effective freedom to copy and redistribute it, with or without modifying
+it, either commercially or noncommercially. Secondarily, this License
+preserves for the author and publisher a way to get credit for their
+work, while not being considered responsible for modifications made by
+others.
+
+This License is a kind of “copyleft”, which means that derivative works
+of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft license
+designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free program
+should come with manuals providing the same freedoms that the software
+does. But this License is not limited to software manuals; it can be
+used for any textual work, regardless of subject matter or whether it is
+published as a printed book. We recommend this License principally for
+works whose purpose is instruction or reference.
+
+
+.. _fdl-section1:
+
+1. APPLICABILITY AND DEFINITIONS
+================================
+
+
+.. _fdl-document:
+
+This License applies to any manual or other work that contains a notice
+placed by the copyright holder saying it can be distributed under the
+terms of this License. The “Document”, below, refers to any such manual
+or work. Any member of the public is a licensee, and is addressed as
+“you”.
+
+
+.. _fdl-modified:
+
+A “Modified Version” of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+
+.. _fdl-secondary:
+
+A “Secondary Section” is a named appendix or a front-matter section of
+the :ref:`Document <fdl-document>` that deals exclusively with the
+relationship of the publishers or authors of the Document to the
+Document's overall subject (or to related matters) and contains nothing
+that could fall directly within that overall subject. (For example, if
+the Document is in part a textbook of mathematics, a Secondary Section
+may not explain any mathematics.) The relationship could be a matter of
+historical connection with the subject or with related matters, or of
+legal, commercial, philosophical, ethical or political position
+regarding them.
+
+
+.. _fdl-invariant:
+
+The “Invariant Sections” are certain
+:ref:`Secondary Sections <fdl-secondary>` whose titles are designated,
+as being those of Invariant Sections, in the notice that says that the
+:ref:`Document <fdl-document>` is released under this License.
+
+
+.. _fdl-cover-texts:
+
+The “Cover Texts” are certain short passages of text that are listed, as
+Front-Cover Texts or Back-Cover Texts, in the notice that says that the
+:ref:`Document <fdl-document>` is released under this License.
+
+
+.. _fdl-transparent:
+
+A “Transparent” copy of the :ref:`Document <fdl-document>` means a
+machine-readable copy, represented in a format whose specification is
+available to the general public, whose contents can be viewed and edited
+directly and straightforwardly with generic text editors or (for images
+composed of pixels) generic paint programs or (for drawings) some widely
+available drawing editor, and that is suitable for input to text
+formatters or for automatic translation to a variety of formats suitable
+for input to text formatters. A copy made in an otherwise Transparent
+file format whose markup has been designed to thwart or discourage
+subsequent modification by readers is not Transparent. A copy that is
+not “Transparent” is called “Opaque”.
+
+Examples of suitable formats for Transparent copies include plain ASCII
+without markup, Texinfo input format, LaTeX input format, SGML or XML
+using a publicly available DTD, and standard-conforming simple HTML
+designed for human modification. Opaque formats include PostScript, PDF,
+proprietary formats that can be read and edited only by proprietary word
+processors, SGML or XML for which the DTD and/or processing tools are
+not generally available, and the machine-generated HTML produced by some
+word processors for output purposes only.
+
+
+.. _fdl-title-page:
+
+The “Title Page” means, for a printed book, the title page itself, plus
+such following pages as are needed to hold, legibly, the material this
+License requires to appear in the title page. For works in formats which
+do not have any title page as such, “Title Page” means the text near the
+most prominent appearance of the work's title, preceding the beginning
+of the body of the text.
+
+
+.. _fdl-section2:
+
+2. VERBATIM COPYING
+===================
+
+You may copy and distribute the :ref:`Document <fdl-document>` in any
+medium, either commercially or noncommercially, provided that this
+License, the copyright notices, and the license notice saying this
+License applies to the Document are reproduced in all copies, and that
+you add no other conditions whatsoever to those of this License. You may
+not use technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in
+:ref:`section 3 <fdl-section3>`.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
+
+.. _fdl-section3:
+
+3. COPYING IN QUANTITY
+======================
+
+If you publish printed copies of the :ref:`Document <fdl-document>`
+numbering more than 100, and the Document's license notice requires
+:ref:`Cover Texts <fdl-cover-texts>`, you must enclose the copies in
+covers that carry, clearly and legibly, all these Cover Texts:
+Front-Cover Texts on the front cover, and Back-Cover Texts on the back
+cover. Both covers must also clearly and legibly identify you as the
+publisher of these copies. The front cover must present the full title
+with all words of the title equally prominent and visible. You may add
+other material on the covers in addition. Copying with changes limited
+to the covers, as long as they preserve the title of the
+:ref:`Document <fdl-document>` and satisfy these conditions, can be
+treated as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute :ref:`Opaque <fdl-transparent>` copies of
+the :ref:`Document <fdl-document>` numbering more than 100, you must
+either include a machine-readable :ref:`Transparent <fdl-transparent>`
+copy along with each Opaque copy, or state in or with each Opaque copy a
+publicly-accessible computer-network location containing a complete
+Transparent copy of the Document, free of added material, which the
+general network-using public has access to download anonymously at no
+charge using public-standard network protocols. If you use the latter
+option, you must take reasonably prudent steps, when you begin
+distribution of Opaque copies in quantity, to ensure that this
+Transparent copy will remain thus accessible at the stated location
+until at least one year after the last time you distribute an Opaque
+copy (directly or through your agents or retailers) of that edition to
+the public.
+
+It is requested, but not required, that you contact the authors of the
+:ref:`Document <fdl-document>` well before redistributing any large
+number of copies, to give them a chance to provide you with an updated
+version of the Document.
+
+
+.. _fdl-section4:
+
+4. MODIFICATIONS
+================
+
+You may copy and distribute a :ref:`Modified Version <fdl-modified>`
+of the :ref:`Document <fdl-document>` under the conditions of sections
+:ref:`2 <fdl-section2>` and :ref:`3 <fdl-section3>` above, provided
+that you release the Modified Version under precisely this License, with
+the Modified Version filling the role of the Document, thus licensing
+distribution and modification of the Modified Version to whoever
+possesses a copy of it. In addition, you must do these things in the
+Modified Version:
+
+- **A.**
+ Use in the :ref:`Title Page <fdl-title-page>` (and on the covers,
+ if any) a title distinct from that of the
+ :ref:`Document <fdl-document>`, and from those of previous versions
+ (which should, if there were any, be listed in the History section of
+ the Document). You may use the same title as a previous version if
+ the original publisher of that version gives permission.
+
+- **B.**
+ List on the :ref:`Title Page <fdl-title-page>`, as authors, one or
+ more persons or entities responsible for authorship of the
+ modifications in the :ref:`Modified Version <fdl-modified>`,
+ together with at least five of the principal authors of the
+ :ref:`Document <fdl-document>` (all of its principal authors, if it
+ has less than five).
+
+- **C.**
+ State on the :ref:`Title Page <fdl-title-page>` the name of the
+ publisher of the :ref:`Modified Version <fdl-modified>`, as the
+ publisher.
+
+- **D.**
+ Preserve all the copyright notices of the
+ :ref:`Document <fdl-document>`.
+
+- **E.**
+ Add an appropriate copyright notice for your modifications adjacent
+ to the other copyright notices.
+
+- **F.**
+ Include, immediately after the copyright notices, a license notice
+ giving the public permission to use the
+ :ref:`Modified Version <fdl-modified>` under the terms of this
+ License, in the form shown in the Addendum below.
+
+- **G.**
+ Preserve in that license notice the full lists of
+ :ref:`Invariant Sections <fdl-invariant>` and required
+ :ref:`Cover Texts <fdl-cover-texts>` given in the
+ :ref:`Document's <fdl-document>` license notice.
+
+- **H.**
+ Include an unaltered copy of this License.
+
+- **I.**
+ Preserve the section entitled “History”, and its title, and add to it
+ an item stating at least the title, year, new authors, and publisher
+ of the :ref:`Modified Version <fdl-modified>` as given on the
+ :ref:`Title Page <fdl-title-page>`. If there is no section entitled
+ “History” in the :ref:`Document <fdl-document>`, create one stating
+ the title, year, authors, and publisher of the Document as given on
+ its Title Page, then add an item describing the Modified Version as
+ stated in the previous sentence.
+
+- **J.**
+ Preserve the network location, if any, given in the
+ :ref:`Document <fdl-document>` for public access to a
+ :ref:`Transparent <fdl-transparent>` copy of the Document, and
+ likewise the network locations given in the Document for previous
+ versions it was based on. These may be placed in the “History”
+ section. You may omit a network location for a work that was
+ published at least four years before the Document itself, or if the
+ original publisher of the version it refers to gives permission.
+
+- **K.**
+ In any section entitled “Acknowledgements” or “Dedications”, preserve
+ the section's title, and preserve in the section all the substance
+ and tone of each of the contributor acknowledgements and/or
+ dedications given therein.
+
+- **L.**
+ Preserve all the :ref:`Invariant Sections <fdl-invariant>` of the
+ :ref:`Document <fdl-document>`, unaltered in their text and in
+ their titles. Section numbers or the equivalent are not considered
+ part of the section titles.
+
+- **M.**
+ Delete any section entitled “Endorsements”. Such a section may not be
+ included in the :ref:`Modified Version <fdl-modified>`.
+
+- **N.**
+ Do not retitle any existing section as “Endorsements” or to conflict
+ in title with any :ref:`Invariant Section <fdl-invariant>`.
+
+If the :ref:`Modified Version <fdl-modified>` includes new
+front-matter sections or appendices that qualify as
+:ref:`Secondary Sections <fdl-secondary>` and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the list
+of :ref:`Invariant Sections <fdl-invariant>` in the Modified Version's
+license notice. These titles must be distinct from any other section
+titles.
+
+You may add a section entitled “Endorsements”, provided it contains
+nothing but endorsements of your
+:ref:`Modified Version <fdl-modified>` by various parties--for
+example, statements of peer review or that the text has been approved by
+an organization as the authoritative definition of a standard.
+
+You may add a passage of up to five words as a
+:ref:`Front-Cover Text <fdl-cover-texts>`, and a passage of up to 25
+words as a :ref:`Back-Cover Text <fdl-cover-texts>`, to the end of the
+list of :ref:`Cover Texts <fdl-cover-texts>` in the
+:ref:`Modified Version <fdl-modified>`. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or through
+arrangements made by) any one entity. If the
+:ref:`Document <fdl-document>` already includes a cover text for the
+same cover, previously added by you or by arrangement made by the same
+entity you are acting on behalf of, you may not add another; but you may
+replace the old one, on explicit permission from the previous publisher
+that added the old one.
+
+The author(s) and publisher(s) of the :ref:`Document <fdl-document>`
+do not by this License give permission to use their names for publicity
+for or to assert or imply endorsement of any
+:ref:`Modified Version <fdl-modified>`.
+
+
+.. _fdl-section5:
+
+5. COMBINING DOCUMENTS
+======================
+
+You may combine the :ref:`Document <fdl-document>` with other
+documents released under this License, under the terms defined in
+:ref:`section 4 <fdl-section4>` above for modified versions, provided
+that you include in the combination all of the
+:ref:`Invariant Sections <fdl-invariant>` of all of the original
+documents, unmodified, and list them all as Invariant Sections of your
+combined work in its license notice.
+
+The combined work need only contain one copy of this License, and
+multiple identical :ref:`Invariant Sections <fdl-invariant>` may be
+replaced with a single copy. If there are multiple Invariant Sections
+with the same name but different contents, make the title of each such
+section unique by adding at the end of it, in parentheses, the name of
+the original author or publisher of that section if known, or else a
+unique number. Make the same adjustment to the section titles in the
+list of Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections entitled “History” in
+the various original documents, forming one section entitled “History”;
+likewise combine any sections entitled “Acknowledgements”, and any
+sections entitled “Dedications”. You must delete all sections entitled
+“Endorsements.”
+
+
+.. _fdl-section6:
+
+6. COLLECTIONS OF DOCUMENTS
+===========================
+
+You may make a collection consisting of the
+:ref:`Document <fdl-document>` and other documents released under this
+License, and replace the individual copies of this License in the
+various documents with a single copy that is included in the collection,
+provided that you follow the rules of this License for verbatim copying
+of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and dispbibute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
+
+.. _fdl-section7:
+
+7. AGGREGATION WITH INDEPENDENT WORKS
+=====================================
+
+A compilation of the :ref:`Document <fdl-document>` or its derivatives
+with other separate and independent documents or works, in or on a
+volume of a storage or distribution medium, does not as a whole count as
+a :ref:`Modified Version <fdl-modified>` of the Document, provided no
+compilation copyright is claimed for the compilation. Such a compilation
+is called an “aggregate”, and this License does not apply to the other
+self-contained works thus compiled with the Document , on account of
+their being thus compiled, if they are not themselves derivative works
+of the Document. If the :ref:`Cover Text <fdl-cover-texts>`
+requirement of :ref:`section 3 <fdl-section3>` is applicable to these
+copies of the Document, then if the Document is less than one quarter of
+the entire aggregate, the Document's Cover Texts may be placed on covers
+that surround only the Document within the aggregate. Otherwise they
+must appear on covers around the whole aggregate.
+
+
+.. _fdl-section8:
+
+8. TRANSLATION
+==============
+
+Translation is considered a kind of modification, so you may distribute
+translations of the :ref:`Document <fdl-document>` under the terms of
+:ref:`section 4 <fdl-section4>`. Replacing
+:ref:`Invariant Sections <fdl-invariant>` with translations requires
+special permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License provided that you also include the original
+English version of this License. In case of a disagreement between the
+translation and the original English version of this License, the
+original English version will prevail.
+
+
+.. _fdl-section9:
+
+9. TERMINATION
+==============
+
+You may not copy, modify, sublicense, or distribute the
+:ref:`Document <fdl-document>` except as expressly provided for under
+this License. Any other attempt to copy, modify, sublicense or
+distribute the Document is void, and will automatically terminate your
+rights under this License. However, parties who have received copies, or
+rights, from you under this License will not have their licenses
+terminated so long as such parties remain in full compliance.
+
+
+.. _fdl-section10:
+
+10. FUTURE REVISIONS OF THIS LICENSE
+====================================
+
+The `Free Software Foundation <http://www.gnu.org/fsf/fsf.html>`__
+may publish new, revised versions of the GNU Free Documentation License
+from time to time. Such new versions will be similar in spirit to the
+present version, but may differ in detail to address new problems or
+concerns. See
+`http://www.gnu.org/copyleft/ <http://www.gnu.org/copyleft>`__.
+
+Each version of the License is given a distinguishing version number. If
+the :ref:`Document <fdl-document>` specifies that a particular
+numbered version of this License “or any later version” applies to it,
+you have the option of following the terms and conditions either of that
+specified version or of any later version that has been published (not
+as a draft) by the Free Software Foundation. If the Document does not
+specify a version number of this License, you may choose any version
+ever published (not as a draft) by the Free Software Foundation.
+
+
+.. _fdl-using:
+
+Addendum
+========
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and license
+notices just after the title page:
+
+ Copyright © YEAR YOUR NAME.
+
+ 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 the :ref:`Invariant Sections <fdl-invariant>`
+ being LIST THEIR TITLES, with the
+ :ref:`Front-Cover Texts <fdl-cover-texts>` being LIST, and with
+ the :ref:`Back-Cover Texts <fdl-cover-texts>` being LIST. A copy
+ of the license is included in the section entitled “GNU Free
+ Documentation License”.
+
+If you have no :ref:`Invariant Sections <fdl-invariant>`, write “with
+no Invariant Sections” instead of saying which ones are invariant. If
+you have no :ref:`Front-Cover Texts <fdl-cover-texts>`, write “no
+Front-Cover Texts” instead of “Front-Cover Texts being LIST”; likewise
+for :ref:`Back-Cover Texts <fdl-cover-texts>`.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of free
+software license, such as the
+`GNU General Public License <http://www.gnu.org/copyleft/gpl.html>`__,
+to permit their use in free software.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _gen_errors:
+
+*******************
+Generic Error Codes
+*******************
+
+
+.. _gen-errors:
+
+.. flat-table:: Generic error codes
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 16
+
+
+ - .. row 1
+
+ - ``EAGAIN`` (aka ``EWOULDBLOCK``)
+
+ - The ioctl can't be handled because the device is in state where it
+ can't perform it. This could happen for example in case where
+ device is sleeping and ioctl is performed to query statistics. It
+ is also returned when the ioctl would need to wait for an event,
+ but the device was opened in non-blocking mode.
+
+ - .. row 2
+
+ - ``EBADF``
+
+ - The file descriptor is not a valid.
+
+ - .. row 3
+
+ - ``EBUSY``
+
+ - The ioctl can't be handled because the device is busy. This is
+ typically return while device is streaming, and an ioctl tried to
+ change something that would affect the stream, or would require
+ the usage of a hardware resource that was already allocated. The
+ ioctl must not be retried without performing another action to fix
+ the problem first (typically: stop the stream before retrying).
+
+ - .. row 4
+
+ - ``EFAULT``
+
+ - There was a failure while copying data from/to userspace, probably
+ caused by an invalid pointer reference.
+
+ - .. row 5
+
+ - ``EINVAL``
+
+ - One or more of the ioctl parameters are invalid or out of the
+ allowed range. This is a widely used error code. See the
+ individual ioctl requests for specific causes.
+
+ - .. row 6
+
+ - ``ENODEV``
+
+ - Device not found or was removed.
+
+ - .. row 7
+
+ - ``ENOMEM``
+
+ - There's not enough memory to handle the desired operation.
+
+ - .. row 8
+
+ - ``ENOTTY``
+
+ - The ioctl is not supported by the driver, actually meaning that
+ the required functionality is not available, or the file
+ descriptor is not for a media device.
+
+ - .. row 9
+
+ - ``ENOSPC``
+
+ - On USB devices, the stream ioctl's can return this error, meaning
+ that this request would overcommit the usb bandwidth reserved for
+ periodic transfers (up to 80% of the USB bandwidth).
+
+ - .. row 10
+
+ - ``EPERM``
+
+ - Permission denied. Can be returned if the device needs write
+ permission, or some special capabilities is needed (e. g. root)
+
+
+Note 1: ioctls may return other error codes. Since errors may have side
+effects such as a driver reset, applications should abort on unexpected
+errors.
+
+Note 2: Request-specific error codes are listed in the individual
+requests descriptions.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _media-controller-intro:
+
+Introduction
+============
+
+Media devices increasingly handle multiple related functions. Many USB
+cameras include microphones, video capture hardware can also output
+video, or SoC camera interfaces also perform memory-to-memory operations
+similar to video codecs.
+
+Independent functions, even when implemented in the same hardware, can
+be modelled as separate devices. A USB camera with a microphone will be
+presented to userspace applications as V4L2 and ALSA capture devices.
+The devices' relationships (when using a webcam, end-users shouldn't
+have to manually select the associated USB microphone), while not made
+available directly to applications by the drivers, can usually be
+retrieved from sysfs.
+
+With more and more advanced SoC devices being introduced, the current
+approach will not scale. Device topologies are getting increasingly
+complex and can't always be represented by a tree structure. Hardware
+blocks are shared between different functions, creating dependencies
+between seemingly unrelated devices.
+
+Kernel abstraction APIs such as V4L2 and ALSA provide means for
+applications to access hardware parameters. As newer hardware expose an
+increasingly high number of those parameters, drivers need to guess what
+applications really require based on limited information, thereby
+implementing policies that belong to userspace.
+
+The media controller API aims at solving those problems.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _media-controller-model:
+
+Media device model
+==================
+
+Discovering a device internal topology, and configuring it at runtime,
+is one of the goals of the media controller API. To achieve this,
+hardware devices and Linux Kernel interfaces are modelled as graph
+objects on an oriented graph. The object types that constitute the graph
+are:
+
+- An **entity** is a basic media hardware or software building block.
+ It can correspond to a large variety of logical blocks such as
+ physical hardware devices (CMOS sensor for instance), logical
+ hardware devices (a building block in a System-on-Chip image
+ processing pipeline), DMA channels or physical connectors.
+
+- An **interface** is a graph representation of a Linux Kernel
+ userspace API interface, like a device node or a sysfs file that
+ controls one or more entities in the graph.
+
+- A **pad** is a data connection endpoint through which an entity can
+ interact with other entities. Data (not restricted to video) produced
+ by an entity flows from the entity's output to one or more entity
+ inputs. Pads should not be confused with physical pins at chip
+ boundaries.
+
+- A **data link** is a point-to-point oriented connection between two
+ pads, either on the same entity or on different entities. Data flows
+ from a source pad to a sink pad.
+
+- An **interface link** is a point-to-point bidirectional control
+ connection between a Linux Kernel interface and an entity.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. include:: <isonum.txt>
+
+.. _media_common:
+
+####################
+Media Controller API
+####################
+
+.. _media_controller:
+
+****************
+Media Controller
+****************
+
+
+.. toctree::
+ :maxdepth: 1
+ :numbered:
+
+ media-controller-intro
+ media-controller-model
+ media-types
+
+
+.. _media-user-func:
+
+******************
+Function Reference
+******************
+
+
+.. toctree::
+ :maxdepth: 1
+
+ media-func-open
+ media-func-close
+ media-func-ioctl
+ media-ioc-device-info
+ media-ioc-g-topology
+ media-ioc-enum-entities
+ media-ioc-enum-links
+ media-ioc-setup-link
+
+
+**********************
+Revision and Copyright
+**********************
+
+Authors:
+
+- Pinchart, Laurent <laurent.pinchart@ideasonboard.com>
+
+ - Initial version.
+
+- Carvalho Chehab, Mauro <mchehab@kernel.org>
+
+ - MEDIA_IOC_G_TOPOLOGY documentation and documentation improvements.
+
+**Copyright** |copy| 2010 : Laurent Pinchart
+
+**Copyright** |copy| 2015-2016 : Mauro Carvalho Chehab
+
+****************
+Revision History
+****************
+
+:revision: 1.1.0 / 2015-12-12 (*mcc*)
+
+:revision: 1.0.0 / 2010-11-10 (*lp*)
+
+Initial revision
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _media-func-close:
+
+*************
+media close()
+*************
+
+Name
+====
+
+media-close - Close a media device
+
+
+Synopsis
+========
+
+.. code-block:: c
+
+ #include <unistd.h>
+
+
+.. cpp:function:: int close( int fd )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+
+Description
+===========
+
+Closes the media device. Resources associated with the file descriptor
+are freed. The device configuration remain unchanged.
+
+
+Return Value
+============
+
+:ref:`close() <media-func-close>` returns 0 on success. On error, -1 is returned, and
+``errno`` is set appropriately. Possible error codes are:
+
+EBADF
+ ``fd`` is not a valid open file descriptor.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _media-func-ioctl:
+
+*************
+media ioctl()
+*************
+
+Name
+====
+
+media-ioctl - Control a media device
+
+
+Synopsis
+========
+
+.. code-block:: c
+
+ #include <sys/ioctl.h>
+
+
+.. cpp:function:: int ioctl( int fd, int request, void *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ Media ioctl request code as defined in the media.h header file, for
+ example MEDIA_IOC_SETUP_LINK.
+
+``argp``
+ Pointer to a request-specific structure.
+
+
+Description
+===========
+
+The :ref:`ioctl() <media-func-ioctl>` function manipulates media device
+parameters. The argument ``fd`` must be an open file descriptor.
+
+The ioctl ``request`` code specifies the media function to be called. It
+has encoded in it whether the argument is an input, output or read/write
+parameter, and the size of the argument ``argp`` in bytes.
+
+Macros and structures definitions specifying media ioctl requests and
+their parameters are located in the media.h header file. All media ioctl
+requests, their respective function and parameters are specified in
+:ref:`media-user-func`.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+Request-specific error codes are listed in the individual requests
+descriptions.
+
+When an ioctl that takes an output or read/write parameter fails, the
+parameter remains unmodified.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _media-func-open:
+
+************
+media open()
+************
+
+Name
+====
+
+media-open - Open a media device
+
+
+Synopsis
+========
+
+.. code-block:: c
+
+ #include <fcntl.h>
+
+
+.. cpp:function:: int open( const char *device_name, int flags )
+
+
+Arguments
+=========
+
+``device_name``
+ Device to be opened.
+
+``flags``
+ Open flags. Access mode must be either ``O_RDONLY`` or ``O_RDWR``.
+ Other flags have no effect.
+
+
+Description
+===========
+
+To open a media device applications call :ref:`open() <media-func-open>` with the
+desired device name. The function has no side effects; the device
+configuration remain unchanged.
+
+When the device is opened in read-only mode, attempts to modify its
+configuration will result in an error, and ``errno`` will be set to
+EBADF.
+
+
+Return Value
+============
+
+:ref:`open() <func-open>` returns the new file descriptor on success. On error,
+-1 is returned, and ``errno`` is set appropriately. Possible error codes
+are:
+
+EACCES
+ The requested access to the file is not allowed.
+
+EMFILE
+ The process already has the maximum number of files open.
+
+ENFILE
+ The system limit on the total number of open files has been reached.
+
+ENOMEM
+ Insufficient kernel memory was available.
+
+ENXIO
+ No device corresponding to this device special file exists.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _media-ioc-device-info:
+
+***************************
+ioctl MEDIA_IOC_DEVICE_INFO
+***************************
+
+Name
+====
+
+MEDIA_IOC_DEVICE_INFO - Query device information
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct media_device_info *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <media-func-open>`.
+
+``request``
+ MEDIA_IOC_DEVICE_INFO
+
+``argp``
+
+
+Description
+===========
+
+All media devices must support the ``MEDIA_IOC_DEVICE_INFO`` ioctl. To
+query device information, applications call the ioctl with a pointer to
+a struct :ref:`media_device_info <media-device-info>`. The driver
+fills the structure and returns the information to the application. The
+ioctl never fails.
+
+
+.. _media-device-info:
+
+.. flat-table:: struct media_device_info
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - char
+
+ - ``driver``\ [16]
+
+ - Name of the driver implementing the media API as a NUL-terminated
+ ASCII string. The driver version is stored in the
+ ``driver_version`` field.
+
+ Driver specific applications can use this information to verify
+ the driver identity. It is also useful to work around known bugs,
+ or to identify drivers in error reports.
+
+ - .. row 2
+
+ - char
+
+ - ``model``\ [32]
+
+ - Device model name as a NUL-terminated UTF-8 string. The device
+ version is stored in the ``device_version`` field and is not be
+ appended to the model name.
+
+ - .. row 3
+
+ - char
+
+ - ``serial``\ [40]
+
+ - Serial number as a NUL-terminated ASCII string.
+
+ - .. row 4
+
+ - char
+
+ - ``bus_info``\ [32]
+
+ - Location of the device in the system as a NUL-terminated ASCII
+ string. This includes the bus type name (PCI, USB, ...) and a
+ bus-specific identifier.
+
+ - .. row 5
+
+ - __u32
+
+ - ``media_version``
+
+ - Media API version, formatted with the ``KERNEL_VERSION()`` macro.
+
+ - .. row 6
+
+ - __u32
+
+ - ``hw_revision``
+
+ - Hardware device revision in a driver-specific format.
+
+ - .. row 7
+
+ - __u32
+
+ - ``driver_version``
+
+ - Media device driver version, formatted with the
+ ``KERNEL_VERSION()`` macro. Together with the ``driver`` field
+ this identifies a particular driver.
+
+ - .. row 8
+
+ - __u32
+
+ - ``reserved``\ [31]
+
+ - Reserved for future extensions. Drivers and applications must set
+ this array to zero.
+
+
+The ``serial`` and ``bus_info`` fields can be used to distinguish
+between multiple instances of otherwise identical hardware. The serial
+number takes precedence when provided and can be assumed to be unique.
+If the serial number is an empty string, the ``bus_info`` field can be
+used instead. The ``bus_info`` field is guaranteed to be unique, but can
+vary across reboots or device unplug/replug.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _media-ioc-enum-entities:
+
+*****************************
+ioctl MEDIA_IOC_ENUM_ENTITIES
+*****************************
+
+Name
+====
+
+MEDIA_IOC_ENUM_ENTITIES - Enumerate entities and their properties
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct media_entity_desc *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <media-func-open>`.
+
+``request``
+ MEDIA_IOC_ENUM_ENTITIES
+
+``argp``
+
+
+Description
+===========
+
+To query the attributes of an entity, applications set the id field of a
+struct :ref:`media_entity_desc <media-entity-desc>` structure and
+call the MEDIA_IOC_ENUM_ENTITIES ioctl with a pointer to this
+structure. The driver fills the rest of the structure or returns an
+EINVAL error code when the id is invalid.
+
+Entities can be enumerated by or'ing the id with the
+``MEDIA_ENT_ID_FLAG_NEXT`` flag. The driver will return information
+about the entity with the smallest id strictly larger than the requested
+one ('next entity'), or the ``EINVAL`` error code if there is none.
+
+Entity IDs can be non-contiguous. Applications must *not* try to
+enumerate entities by calling MEDIA_IOC_ENUM_ENTITIES with increasing
+id's until they get an error.
+
+
+.. _media-entity-desc:
+
+.. flat-table:: struct media_entity_desc
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 1 1 8
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``id``
+
+ -
+ -
+ - Entity id, set by the application. When the id is or'ed with
+ ``MEDIA_ENT_ID_FLAG_NEXT``, the driver clears the flag and returns
+ the first entity with a larger id.
+
+ - .. row 2
+
+ - char
+
+ - ``name``\ [32]
+
+ -
+ -
+ - Entity name as an UTF-8 NULL-terminated string.
+
+ - .. row 3
+
+ - __u32
+
+ - ``type``
+
+ -
+ -
+ - Entity type, see :ref:`media-entity-type` for details.
+
+ - .. row 4
+
+ - __u32
+
+ - ``revision``
+
+ -
+ -
+ - Entity revision. Always zero (obsolete)
+
+ - .. row 5
+
+ - __u32
+
+ - ``flags``
+
+ -
+ -
+ - Entity flags, see :ref:`media-entity-flag` for details.
+
+ - .. row 6
+
+ - __u32
+
+ - ``group_id``
+
+ -
+ -
+ - Entity group ID. Always zero (obsolete)
+
+ - .. row 7
+
+ - __u16
+
+ - ``pads``
+
+ -
+ -
+ - Number of pads
+
+ - .. row 8
+
+ - __u16
+
+ - ``links``
+
+ -
+ -
+ - Total number of outbound links. Inbound links are not counted in
+ this field.
+
+ - .. row 9
+
+ - union
+
+ - .. row 10
+
+ -
+ - struct
+
+ - ``dev``
+
+ -
+ - Valid for (sub-)devices that create a single device node.
+
+ - .. row 11
+
+ -
+ -
+ - __u32
+
+ - ``major``
+
+ - Device node major number.
+
+ - .. row 12
+
+ -
+ -
+ - __u32
+
+ - ``minor``
+
+ - Device node minor number.
+
+ - .. row 13
+
+ -
+ - __u8
+
+ - ``raw``\ [184]
+
+ -
+ -
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The struct :ref:`media_entity_desc <media-entity-desc>` ``id``
+ references a non-existing entity.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _media-ioc-enum-links:
+
+**************************
+ioctl MEDIA_IOC_ENUM_LINKS
+**************************
+
+Name
+====
+
+MEDIA_IOC_ENUM_LINKS - Enumerate all pads and links for a given entity
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct media_links_enum *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <media-func-open>`.
+
+``request``
+ MEDIA_IOC_ENUM_LINKS
+
+``argp``
+
+
+Description
+===========
+
+To enumerate pads and/or links for a given entity, applications set the
+entity field of a struct :ref:`media_links_enum <media-links-enum>`
+structure and initialize the struct
+:ref:`media_pad_desc <media-pad-desc>` and struct
+:ref:`media_link_desc <media-link-desc>` structure arrays pointed by
+the ``pads`` and ``links`` fields. They then call the
+MEDIA_IOC_ENUM_LINKS ioctl with a pointer to this structure.
+
+If the ``pads`` field is not NULL, the driver fills the ``pads`` array
+with information about the entity's pads. The array must have enough
+room to store all the entity's pads. The number of pads can be retrieved
+with the :ref:`MEDIA_IOC_ENUM_ENTITIES <media-ioc-enum-entities>`
+ioctl.
+
+If the ``links`` field is not NULL, the driver fills the ``links`` array
+with information about the entity's outbound links. The array must have
+enough room to store all the entity's outbound links. The number of
+outbound links can be retrieved with the
+:ref:`MEDIA_IOC_ENUM_ENTITIES <media-ioc-enum-entities>` ioctl.
+
+Only forward links that originate at one of the entity's source pads are
+returned during the enumeration process.
+
+
+.. _media-links-enum:
+
+.. flat-table:: struct media_links_enum
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``entity``
+
+ - Entity id, set by the application.
+
+ - .. row 2
+
+ - struct :ref:`media_pad_desc <media-pad-desc>`
+
+ - \*\ ``pads``
+
+ - Pointer to a pads array allocated by the application. Ignored if
+ NULL.
+
+ - .. row 3
+
+ - struct :ref:`media_link_desc <media-link-desc>`
+
+ - \*\ ``links``
+
+ - Pointer to a links array allocated by the application. Ignored if
+ NULL.
+
+
+
+.. _media-pad-desc:
+
+.. flat-table:: struct media_pad_desc
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``entity``
+
+ - ID of the entity this pad belongs to.
+
+ - .. row 2
+
+ - __u16
+
+ - ``index``
+
+ - 0-based pad index.
+
+ - .. row 3
+
+ - __u32
+
+ - ``flags``
+
+ - Pad flags, see :ref:`media-pad-flag` for more details.
+
+
+
+.. _media-link-desc:
+
+.. flat-table:: struct media_link_desc
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - struct :ref:`media_pad_desc <media-pad-desc>`
+
+ - ``source``
+
+ - Pad at the origin of this link.
+
+ - .. row 2
+
+ - struct :ref:`media_pad_desc <media-pad-desc>`
+
+ - ``sink``
+
+ - Pad at the target of this link.
+
+ - .. row 3
+
+ - __u32
+
+ - ``flags``
+
+ - Link flags, see :ref:`media-link-flag` for more details.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The struct :ref:`media_links_enum <media-links-enum>` ``id``
+ references a non-existing entity.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _media-g-topology:
+
+**************************
+ioctl MEDIA_IOC_G_TOPOLOGY
+**************************
+
+Name
+====
+
+MEDIA_IOC_G_TOPOLOGY - Enumerate the graph topology and graph element properties
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct media_v2_topology *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <media-func-open>`.
+
+``request``
+ MEDIA_IOC_G_TOPOLOGY
+
+``argp``
+
+
+Description
+===========
+
+The typical usage of this ioctl is to call it twice. On the first call,
+the structure defined at struct
+:ref:`media_v2_topology <media-v2-topology>` should be zeroed. At
+return, if no errors happen, this ioctl will return the
+``topology_version`` and the total number of entities, interfaces, pads
+and links.
+
+Before the second call, the userspace should allocate arrays to store
+the graph elements that are desired, putting the pointers to them at the
+ptr_entities, ptr_interfaces, ptr_links and/or ptr_pads, keeping the
+other values untouched.
+
+If the ``topology_version`` remains the same, the ioctl should fill the
+desired arrays with the media graph elements.
+
+
+.. _media-v2-topology:
+
+.. flat-table:: struct media_v2_topology
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 2 8
+
+
+ - .. row 1
+
+ - __u64
+
+ - ``topology_version``
+
+ - Version of the media graph topology. When the graph is created,
+ this field starts with zero. Every time a graph element is added
+ or removed, this field is incremented.
+
+ - .. row 2
+
+ - __u64
+
+ - ``num_entities``
+
+ - Number of entities in the graph
+
+ - .. row 3
+
+ - __u64
+
+ - ``ptr_entities``
+
+ - A pointer to a memory area where the entities array will be
+ stored, converted to a 64-bits integer. It can be zero. if zero,
+ the ioctl won't store the entities. It will just update
+ ``num_entities``
+
+ - .. row 4
+
+ - __u64
+
+ - ``num_interfaces``
+
+ - Number of interfaces in the graph
+
+ - .. row 5
+
+ - __u64
+
+ - ``ptr_interfaces``
+
+ - A pointer to a memory area where the interfaces array will be
+ stored, converted to a 64-bits integer. It can be zero. if zero,
+ the ioctl won't store the interfaces. It will just update
+ ``num_interfaces``
+
+ - .. row 6
+
+ - __u64
+
+ - ``num_pads``
+
+ - Total number of pads in the graph
+
+ - .. row 7
+
+ - __u64
+
+ - ``ptr_pads``
+
+ - A pointer to a memory area where the pads array will be stored,
+ converted to a 64-bits integer. It can be zero. if zero, the ioctl
+ won't store the pads. It will just update ``num_pads``
+
+ - .. row 8
+
+ - __u64
+
+ - ``num_links``
+
+ - Total number of data and interface links in the graph
+
+ - .. row 9
+
+ - __u64
+
+ - ``ptr_links``
+
+ - A pointer to a memory area where the links array will be stored,
+ converted to a 64-bits integer. It can be zero. if zero, the ioctl
+ won't store the links. It will just update ``num_links``
+
+
+
+.. _media-v2-entity:
+
+.. flat-table:: struct media_v2_entity
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 2 8
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``id``
+
+ - Unique ID for the entity.
+
+ - .. row 2
+
+ - char
+
+ - ``name``\ [64]
+
+ - Entity name as an UTF-8 NULL-terminated string.
+
+ - .. row 3
+
+ - __u32
+
+ - ``function``
+
+ - Entity main function, see :ref:`media-entity-type` for details.
+
+ - .. row 4
+
+ - __u32
+
+ - ``reserved``\ [12]
+
+ - Reserved for future extensions. Drivers and applications must set
+ this array to zero.
+
+
+
+.. _media-v2-interface:
+
+.. flat-table:: struct media_v2_interface
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 2 8
+
+ - .. row 1
+
+ - __u32
+
+ - ``id``
+
+ - Unique ID for the interface.
+
+ - .. row 2
+
+ - __u32
+
+ - ``intf_type``
+
+ - Interface type, see :ref:`media-intf-type` for details.
+
+ - .. row 3
+
+ - __u32
+
+ - ``flags``
+
+ - Interface flags. Currently unused.
+
+ - .. row 4
+
+ - __u32
+
+ - ``reserved``\ [9]
+
+ - Reserved for future extensions. Drivers and applications must set
+ this array to zero.
+
+ - .. row 5
+
+ - struct media_v2_intf_devnode
+
+ - ``devnode``
+
+ - Used only for device node interfaces. See
+ :ref:`media-v2-intf-devnode` for details..
+
+
+
+.. _media-v2-intf-devnode:
+
+.. flat-table:: struct media_v2_interface
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 2 8
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``major``
+
+ - Device node major number.
+
+ - .. row 2
+
+ - __u32
+
+ - ``minor``
+
+ - Device node minor number.
+
+
+
+.. _media-v2-pad:
+
+.. flat-table:: struct media_v2_pad
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 2 8
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``id``
+
+ - Unique ID for the pad.
+
+ - .. row 2
+
+ - __u32
+
+ - ``entity_id``
+
+ - Unique ID for the entity where this pad belongs.
+
+ - .. row 3
+
+ - __u32
+
+ - ``flags``
+
+ - Pad flags, see :ref:`media-pad-flag` for more details.
+
+ - .. row 4
+
+ - __u32
+
+ - ``reserved``\ [9]
+
+ - Reserved for future extensions. Drivers and applications must set
+ this array to zero.
+
+
+
+.. _media-v2-link:
+
+.. flat-table:: struct media_v2_pad
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 2 8
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``id``
+
+ - Unique ID for the pad.
+
+ - .. row 2
+
+ - __u32
+
+ - ``source_id``
+
+ - On pad to pad links: unique ID for the source pad.
+
+ On interface to entity links: unique ID for the interface.
+
+ - .. row 3
+
+ - __u32
+
+ - ``sink_id``
+
+ - On pad to pad links: unique ID for the sink pad.
+
+ On interface to entity links: unique ID for the entity.
+
+ - .. row 4
+
+ - __u32
+
+ - ``flags``
+
+ - Link flags, see :ref:`media-link-flag` for more details.
+
+ - .. row 5
+
+ - __u32
+
+ - ``reserved``\ [5]
+
+ - Reserved for future extensions. Drivers and applications must set
+ this array to zero.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+ENOSPC
+ This is returned when either one or more of the num_entities,
+ num_interfaces, num_links or num_pads are non-zero and are
+ smaller than the actual number of elements inside the graph. This
+ may happen if the ``topology_version`` changed when compared to the
+ last time this ioctl was called. Userspace should usually free the
+ area for the pointers, zero the struct elements and call this ioctl
+ again.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _media-ioc-setup-link:
+
+**************************
+ioctl MEDIA_IOC_SETUP_LINK
+**************************
+
+Name
+====
+
+MEDIA_IOC_SETUP_LINK - Modify the properties of a link
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct media_link_desc *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <media-func-open>`.
+
+``request``
+ MEDIA_IOC_SETUP_LINK
+
+``argp``
+
+
+Description
+===========
+
+To change link properties applications fill a struct
+:ref:`media_link_desc <media-link-desc>` with link identification
+information (source and sink pad) and the new requested link flags. They
+then call the MEDIA_IOC_SETUP_LINK ioctl with a pointer to that
+structure.
+
+The only configurable property is the ``ENABLED`` link flag to
+enable/disable a link. Links marked with the ``IMMUTABLE`` link flag can
+not be enabled or disabled.
+
+Link configuration has no side effect on other links. If an enabled link
+at the sink pad prevents the link from being enabled, the driver returns
+with an ``EBUSY`` error code.
+
+Only links marked with the ``DYNAMIC`` link flag can be enabled/disabled
+while streaming media data. Attempting to enable or disable a streaming
+non-dynamic link will return an ``EBUSY`` error code.
+
+If the specified link can't be found the driver returns with an ``EINVAL``
+error code.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The struct :ref:`media_link_desc <media-link-desc>` references a
+ non-existing link, or the link is immutable and an attempt to modify
+ its configuration was made.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _media-controller-types:
+
+Types and flags used to represent the media graph elements
+==========================================================
+
+
+.. _media-entity-type:
+
+.. flat-table:: Media entity types
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``MEDIA_ENT_F_UNKNOWN`` and ``MEDIA_ENT_F_V4L2_SUBDEV_UNKNOWN``
+
+ - Unknown entity. That generally indicates that a driver didn't
+ initialize properly the entity, with is a Kernel bug
+
+ - .. row 2
+
+ - ``MEDIA_ENT_F_IO_V4L``
+
+ - Data streaming input and/or output entity.
+
+ - .. row 3
+
+ - ``MEDIA_ENT_F_IO_VBI``
+
+ - V4L VBI streaming input or output entity
+
+ - .. row 4
+
+ - ``MEDIA_ENT_F_IO_SWRADIO``
+
+ - V4L Software Digital Radio (SDR) streaming input or output entity
+
+ - .. row 5
+
+ - ``MEDIA_ENT_F_IO_DTV``
+
+ - DVB Digital TV streaming input or output entity
+
+ - .. row 6
+
+ - ``MEDIA_ENT_F_DTV_DEMOD``
+
+ - Digital TV demodulator entity.
+
+ - .. row 7
+
+ - ``MEDIA_ENT_F_TS_DEMUX``
+
+ - MPEG Transport stream demux entity. Could be implemented on
+ hardware or in Kernelspace by the Linux DVB subsystem.
+
+ - .. row 8
+
+ - ``MEDIA_ENT_F_DTV_CA``
+
+ - Digital TV Conditional Access module (CAM) entity
+
+ - .. row 9
+
+ - ``MEDIA_ENT_F_DTV_NET_DECAP``
+
+ - Digital TV network ULE/MLE desencapsulation entity. Could be
+ implemented on hardware or in Kernelspace
+
+ - .. row 10
+
+ - ``MEDIA_ENT_F_CONN_RF``
+
+ - Connector for a Radio Frequency (RF) signal.
+
+ - .. row 11
+
+ - ``MEDIA_ENT_F_CONN_SVIDEO``
+
+ - Connector for a S-Video signal.
+
+ - .. row 12
+
+ - ``MEDIA_ENT_F_CONN_COMPOSITE``
+
+ - Connector for a RGB composite signal.
+
+ - .. row 13
+
+ - ``MEDIA_ENT_F_CAM_SENSOR``
+
+ - Camera video sensor entity.
+
+ - .. row 14
+
+ - ``MEDIA_ENT_F_FLASH``
+
+ - Flash controller entity.
+
+ - .. row 15
+
+ - ``MEDIA_ENT_F_LENS``
+
+ - Lens controller entity.
+
+ - .. row 16
+
+ - ``MEDIA_ENT_F_ATV_DECODER``
+
+ - Analog video decoder, the basic function of the video decoder is
+ to accept analogue video from a wide variety of sources such as
+ broadcast, DVD players, cameras and video cassette recorders, in
+ either NTSC, PAL, SECAM or HD format, separating the stream into
+ its component parts, luminance and chrominance, and output it in
+ some digital video standard, with appropriate timing signals.
+
+ - .. row 17
+
+ - ``MEDIA_ENT_F_TUNER``
+
+ - Digital TV, analog TV, radio and/or software radio tuner, with
+ consists on a PLL tuning stage that converts radio frequency (RF)
+ signal into an Intermediate Frequency (IF). Modern tuners have
+ internally IF-PLL decoders for audio and video, but older models
+ have those stages implemented on separate entities.
+
+ - .. row 18
+
+ - ``MEDIA_ENT_F_IF_VID_DECODER``
+
+ - IF-PLL video decoder. It receives the IF from a PLL and decodes
+ the analog TV video signal. This is commonly found on some very
+ old analog tuners, like Philips MK3 designs. They all contain a
+ tda9887 (or some software compatible similar chip, like tda9885).
+ Those devices use a different I2C address than the tuner PLL.
+
+ - .. row 19
+
+ - ``MEDIA_ENT_F_IF_AUD_DECODER``
+
+ - IF-PLL sound decoder. It receives the IF from a PLL and decodes
+ the analog TV audio signal. This is commonly found on some very
+ old analog hardware, like Micronas msp3400, Philips tda9840,
+ tda985x, etc. Those devices use a different I2C address than the
+ tuner PLL and should be controlled together with the IF-PLL video
+ decoder.
+
+ - .. row 20
+
+ - ``MEDIA_ENT_F_AUDIO_CAPTURE``
+
+ - Audio Capture Function Entity.
+
+ - .. row 21
+
+ - ``MEDIA_ENT_F_AUDIO_PLAYBACK``
+
+ - Audio Playback Function Entity.
+
+ - .. row 22
+
+ - ``MEDIA_ENT_F_AUDIO_MIXER``
+
+ - Audio Mixer Function Entity.
+
+
+
+.. _media-entity-flag:
+
+.. flat-table:: Media entity flags
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``MEDIA_ENT_FL_DEFAULT``
+
+ - Default entity for its type. Used to discover the default audio,
+ VBI and video devices, the default camera sensor, ...
+
+ - .. row 2
+
+ - ``MEDIA_ENT_FL_CONNECTOR``
+
+ - The entity represents a data conector
+
+
+
+.. _media-intf-type:
+
+.. flat-table:: Media interface types
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``MEDIA_INTF_T_DVB_FE``
+
+ - Device node interface for the Digital TV frontend
+
+ - typically, /dev/dvb/adapter?/frontend?
+
+ - .. row 2
+
+ - ``MEDIA_INTF_T_DVB_DEMUX``
+
+ - Device node interface for the Digital TV demux
+
+ - typically, /dev/dvb/adapter?/demux?
+
+ - .. row 3
+
+ - ``MEDIA_INTF_T_DVB_DVR``
+
+ - Device node interface for the Digital TV DVR
+
+ - typically, /dev/dvb/adapter?/dvr?
+
+ - .. row 4
+
+ - ``MEDIA_INTF_T_DVB_CA``
+
+ - Device node interface for the Digital TV Conditional Access
+
+ - typically, /dev/dvb/adapter?/ca?
+
+ - .. row 5
+
+ - ``MEDIA_INTF_T_DVB_FE``
+
+ - Device node interface for the Digital TV network control
+
+ - typically, /dev/dvb/adapter?/net?
+
+ - .. row 6
+
+ - ``MEDIA_INTF_T_V4L_VIDEO``
+
+ - Device node interface for video (V4L)
+
+ - typically, /dev/video?
+
+ - .. row 7
+
+ - ``MEDIA_INTF_T_V4L_VBI``
+
+ - Device node interface for VBI (V4L)
+
+ - typically, /dev/vbi?
+
+ - .. row 8
+
+ - ``MEDIA_INTF_T_V4L_RADIO``
+
+ - Device node interface for radio (V4L)
+
+ - typically, /dev/vbi?
+
+ - .. row 9
+
+ - ``MEDIA_INTF_T_V4L_SUBDEV``
+
+ - Device node interface for a V4L subdevice
+
+ - typically, /dev/v4l-subdev?
+
+ - .. row 10
+
+ - ``MEDIA_INTF_T_V4L_SWRADIO``
+
+ - Device node interface for Software Defined Radio (V4L)
+
+ - typically, /dev/swradio?
+
+ - .. row 11
+
+ - ``MEDIA_INTF_T_ALSA_PCM_CAPTURE``
+
+ - Device node interface for ALSA PCM Capture
+
+ - typically, /dev/snd/pcmC?D?c
+
+ - .. row 12
+
+ - ``MEDIA_INTF_T_ALSA_PCM_PLAYBACK``
+
+ - Device node interface for ALSA PCM Playback
+
+ - typically, /dev/snd/pcmC?D?p
+
+ - .. row 13
+
+ - ``MEDIA_INTF_T_ALSA_CONTROL``
+
+ - Device node interface for ALSA Control
+
+ - typically, /dev/snd/controlC?
+
+ - .. row 14
+
+ - ``MEDIA_INTF_T_ALSA_COMPRESS``
+
+ - Device node interface for ALSA Compress
+
+ - typically, /dev/snd/compr?
+
+ - .. row 15
+
+ - ``MEDIA_INTF_T_ALSA_RAWMIDI``
+
+ - Device node interface for ALSA Raw MIDI
+
+ - typically, /dev/snd/midi?
+
+ - .. row 16
+
+ - ``MEDIA_INTF_T_ALSA_HWDEP``
+
+ - Device node interface for ALSA Hardware Dependent
+
+ - typically, /dev/snd/hwC?D?
+
+ - .. row 17
+
+ - ``MEDIA_INTF_T_ALSA_SEQUENCER``
+
+ - Device node interface for ALSA Sequencer
+
+ - typically, /dev/snd/seq
+
+ - .. row 18
+
+ - ``MEDIA_INTF_T_ALSA_TIMER``
+
+ - Device node interface for ALSA Timer
+
+ - typically, /dev/snd/timer
+
+
+
+.. _media-pad-flag:
+
+.. flat-table:: Media pad flags
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``MEDIA_PAD_FL_SINK``
+
+ - Input pad, relative to the entity. Input pads sink data and are
+ targets of links.
+
+ - .. row 2
+
+ - ``MEDIA_PAD_FL_SOURCE``
+
+ - Output pad, relative to the entity. Output pads source data and
+ are origins of links.
+
+ - .. row 3
+
+ - ``MEDIA_PAD_FL_MUST_CONNECT``
+
+ - If this flag is set and the pad is linked to any other pad, then
+ at least one of those links must be enabled for the entity to be
+ able to stream. There could be temporary reasons (e.g. device
+ configuration dependent) for the pad to need enabled links even
+ when this flag isn't set; the absence of the flag doesn't imply
+ there is none.
+
+
+One and only one of ``MEDIA_PAD_FL_SINK`` and ``MEDIA_PAD_FL_SOURCE``
+must be set for every pad.
+
+
+.. _media-link-flag:
+
+.. flat-table:: Media link flags
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``MEDIA_LNK_FL_ENABLED``
+
+ - The link is enabled and can be used to transfer media data. When
+ two or more links target a sink pad, only one of them can be
+ enabled at a time.
+
+ - .. row 2
+
+ - ``MEDIA_LNK_FL_IMMUTABLE``
+
+ - The link enabled state can't be modified at runtime. An immutable
+ link is always enabled.
+
+ - .. row 3
+
+ - ``MEDIA_LNK_FL_DYNAMIC``
+
+ - The link enabled state can be modified during streaming. This flag
+ is set by drivers and is read-only for applications.
+
+ - .. row 4
+
+ - ``MEDIA_LNK_FL_LINK_TYPE``
+
+ - This is a bitmask that defines the type of the link. Currently,
+ two types of links are supported:
+
+ ``MEDIA_LNK_FL_DATA_LINK`` if the link is between two pads
+
+ ``MEDIA_LNK_FL_INTERFACE_LINK`` if the link is between an
+ interface and an entity
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _Remote_controllers_Intro:
+
+************
+Introduction
+************
+
+Currently, most analog and digital devices have a Infrared input for
+remote controllers. Each manufacturer has their own type of control. It
+is not rare for the same manufacturer to ship different types of
+controls, depending on the device.
+
+A Remote Controller interface is mapped as a normal evdev/input
+interface, just like a keyboard or a mouse. So, it uses all ioctls
+already defined for any other input devices.
+
+However, remove controllers are more flexible than a normal input
+device, as the IR receiver (and/or transmitter) can be used in
+conjunction with a wide variety of different IR remotes.
+
+In order to allow flexibility, the Remote Controller subsystem allows
+controlling the RC-specific attributes via
+:ref:`the sysfs class nodes <remote_controllers_sysfs_nodes>`.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _Remote_controllers_table_change:
+
+*******************************************
+Changing default Remote Controller mappings
+*******************************************
+
+The event interface provides two ioctls to be used against the
+/dev/input/event device, to allow changing the default keymapping.
+
+This program demonstrates how to replace the keymap tables.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ keytable.c
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _Remote_controllers_tables:
+
+************************
+Remote controller tables
+************************
+
+Unfortunately, for several years, there was no effort to create uniform
+IR keycodes for different devices. This caused the same IR keyname to be
+mapped completely differently on different IR devices. This resulted
+that the same IR keyname to be mapped completely different on different
+IR's. Due to that, V4L2 API now specifies a standard for mapping Media
+keys on IR.
+
+This standard should be used by both V4L/DVB drivers and userspace
+applications
+
+The modules register the remote as keyboard within the linux input
+layer. This means that the IR key strokes will look like normal keyboard
+key strokes (if CONFIG_INPUT_KEYBOARD is enabled). Using the event
+devices (CONFIG_INPUT_EVDEV) it is possible for applications to access
+the remote via /dev/input/event devices.
+
+
+.. _rc_standard_keymap:
+
+.. flat-table:: IR default keymapping
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - Key code
+
+ - Meaning
+
+ - Key examples on IR
+
+ - .. row 2
+
+ - **Numeric keys**
+
+ - .. row 3
+
+ - ``KEY_0``
+
+ - Keyboard digit 0
+
+ - 0
+
+ - .. row 4
+
+ - ``KEY_1``
+
+ - Keyboard digit 1
+
+ - 1
+
+ - .. row 5
+
+ - ``KEY_2``
+
+ - Keyboard digit 2
+
+ - 2
+
+ - .. row 6
+
+ - ``KEY_3``
+
+ - Keyboard digit 3
+
+ - 3
+
+ - .. row 7
+
+ - ``KEY_4``
+
+ - Keyboard digit 4
+
+ - 4
+
+ - .. row 8
+
+ - ``KEY_5``
+
+ - Keyboard digit 5
+
+ - 5
+
+ - .. row 9
+
+ - ``KEY_6``
+
+ - Keyboard digit 6
+
+ - 6
+
+ - .. row 10
+
+ - ``KEY_7``
+
+ - Keyboard digit 7
+
+ - 7
+
+ - .. row 11
+
+ - ``KEY_8``
+
+ - Keyboard digit 8
+
+ - 8
+
+ - .. row 12
+
+ - ``KEY_9``
+
+ - Keyboard digit 9
+
+ - 9
+
+ - .. row 13
+
+ - **Movie play control**
+
+ - .. row 14
+
+ - ``KEY_FORWARD``
+
+ - Instantly advance in time
+
+ - >> / FORWARD
+
+ - .. row 15
+
+ - ``KEY_BACK``
+
+ - Instantly go back in time
+
+ - <<< / BACK
+
+ - .. row 16
+
+ - ``KEY_FASTFORWARD``
+
+ - Play movie faster
+
+ - >>> / FORWARD
+
+ - .. row 17
+
+ - ``KEY_REWIND``
+
+ - Play movie back
+
+ - REWIND / BACKWARD
+
+ - .. row 18
+
+ - ``KEY_NEXT``
+
+ - Select next chapter / sub-chapter / interval
+
+ - NEXT / SKIP
+
+ - .. row 19
+
+ - ``KEY_PREVIOUS``
+
+ - Select previous chapter / sub-chapter / interval
+
+ - << / PREV / PREVIOUS
+
+ - .. row 20
+
+ - ``KEY_AGAIN``
+
+ - Repeat the video or a video interval
+
+ - REPEAT / LOOP / RECALL
+
+ - .. row 21
+
+ - ``KEY_PAUSE``
+
+ - Pause sroweam
+
+ - PAUSE / FREEZE
+
+ - .. row 22
+
+ - ``KEY_PLAY``
+
+ - Play movie at the normal timeshift
+
+ - NORMAL TIMESHIFT / LIVE / >
+
+ - .. row 23
+
+ - ``KEY_PLAYPAUSE``
+
+ - Alternate between play and pause
+
+ - PLAY / PAUSE
+
+ - .. row 24
+
+ - ``KEY_STOP``
+
+ - Stop sroweam
+
+ - STOP
+
+ - .. row 25
+
+ - ``KEY_RECORD``
+
+ - Start/stop recording sroweam
+
+ - CAPTURE / REC / RECORD/PAUSE
+
+ - .. row 26
+
+ - ``KEY_CAMERA``
+
+ - Take a picture of the image
+
+ - CAMERA ICON / CAPTURE / SNAPSHOT
+
+ - .. row 27
+
+ - ``KEY_SHUFFLE``
+
+ - Enable shuffle mode
+
+ - SHUFFLE
+
+ - .. row 28
+
+ - ``KEY_TIME``
+
+ - Activate time shift mode
+
+ - TIME SHIFT
+
+ - .. row 29
+
+ - ``KEY_TITLE``
+
+ - Allow changing the chapter
+
+ - CHAPTER
+
+ - .. row 30
+
+ - ``KEY_SUBTITLE``
+
+ - Allow changing the subtitle
+
+ - SUBTITLE
+
+ - .. row 31
+
+ - **Image control**
+
+ - .. row 32
+
+ - ``KEY_BRIGHTNESSDOWN``
+
+ - Decrease Brightness
+
+ - BRIGHTNESS DECREASE
+
+ - .. row 33
+
+ - ``KEY_BRIGHTNESSUP``
+
+ - Increase Brightness
+
+ - BRIGHTNESS INCREASE
+
+ - .. row 34
+
+ - ``KEY_ANGLE``
+
+ - Switch video camera angle (on videos with more than one angle
+ stored)
+
+ - ANGLE / SWAP
+
+ - .. row 35
+
+ - ``KEY_EPG``
+
+ - Open the Elecrowonic Play Guide (EPG)
+
+ - EPG / GUIDE
+
+ - .. row 36
+
+ - ``KEY_TEXT``
+
+ - Activate/change closed caption mode
+
+ - CLOSED CAPTION/TELETEXT / DVD TEXT / TELETEXT / TTX
+
+ - .. row 37
+
+ - **Audio control**
+
+ - .. row 38
+
+ - ``KEY_AUDIO``
+
+ - Change audio source
+
+ - AUDIO SOURCE / AUDIO / MUSIC
+
+ - .. row 39
+
+ - ``KEY_MUTE``
+
+ - Mute/unmute audio
+
+ - MUTE / DEMUTE / UNMUTE
+
+ - .. row 40
+
+ - ``KEY_VOLUMEDOWN``
+
+ - Decrease volume
+
+ - VOLUME- / VOLUME DOWN
+
+ - .. row 41
+
+ - ``KEY_VOLUMEUP``
+
+ - Increase volume
+
+ - VOLUME+ / VOLUME UP
+
+ - .. row 42
+
+ - ``KEY_MODE``
+
+ - Change sound mode
+
+ - MONO/STEREO
+
+ - .. row 43
+
+ - ``KEY_LANGUAGE``
+
+ - Select Language
+
+ - 1ST / 2ND LANGUAGE / DVD LANG / MTS/SAP / MTS SEL
+
+ - .. row 44
+
+ - **Channel control**
+
+ - .. row 45
+
+ - ``KEY_CHANNEL``
+
+ - Go to the next favorite channel
+
+ - ALT / CHANNEL / CH SURFING / SURF / FAV
+
+ - .. row 46
+
+ - ``KEY_CHANNELDOWN``
+
+ - Decrease channel sequencially
+
+ - CHANNEL - / CHANNEL DOWN / DOWN
+
+ - .. row 47
+
+ - ``KEY_CHANNELUP``
+
+ - Increase channel sequencially
+
+ - CHANNEL + / CHANNEL UP / UP
+
+ - .. row 48
+
+ - ``KEY_DIGITS``
+
+ - Use more than one digit for channel
+
+ - PLUS / 100/ 1xx / xxx / -/-- / Single Double Triple Digit
+
+ - .. row 49
+
+ - ``KEY_SEARCH``
+
+ - Start channel autoscan
+
+ - SCAN / AUTOSCAN
+
+ - .. row 50
+
+ - **Colored keys**
+
+ - .. row 51
+
+ - ``KEY_BLUE``
+
+ - IR Blue key
+
+ - BLUE
+
+ - .. row 52
+
+ - ``KEY_GREEN``
+
+ - IR Green Key
+
+ - GREEN
+
+ - .. row 53
+
+ - ``KEY_RED``
+
+ - IR Red key
+
+ - RED
+
+ - .. row 54
+
+ - ``KEY_YELLOW``
+
+ - IR Yellow key
+
+ - YELLOW
+
+ - .. row 55
+
+ - **Media selection**
+
+ - .. row 56
+
+ - ``KEY_CD``
+
+ - Change input source to Compact Disc
+
+ - CD
+
+ - .. row 57
+
+ - ``KEY_DVD``
+
+ - Change input to DVD
+
+ - DVD / DVD MENU
+
+ - .. row 58
+
+ - ``KEY_EJECTCLOSECD``
+
+ - Open/close the CD/DVD player
+
+ - -> ) / CLOSE / OPEN
+
+ - .. row 59
+
+ - ``KEY_MEDIA``
+
+ - Turn on/off Media application
+
+ - PC/TV / TURN ON/OFF APP
+
+ - .. row 60
+
+ - ``KEY_PC``
+
+ - Selects from TV to PC
+
+ - PC
+
+ - .. row 61
+
+ - ``KEY_RADIO``
+
+ - Put into AM/FM radio mode
+
+ - RADIO / TV/FM / TV/RADIO / FM / FM/RADIO
+
+ - .. row 62
+
+ - ``KEY_TV``
+
+ - Select tv mode
+
+ - TV / LIVE TV
+
+ - .. row 63
+
+ - ``KEY_TV2``
+
+ - Select Cable mode
+
+ - AIR/CBL
+
+ - .. row 64
+
+ - ``KEY_VCR``
+
+ - Select VCR mode
+
+ - VCR MODE / DTR
+
+ - .. row 65
+
+ - ``KEY_VIDEO``
+
+ - Alternate between input modes
+
+ - SOURCE / SELECT / DISPLAY / SWITCH INPUTS / VIDEO
+
+ - .. row 66
+
+ - **Power control**
+
+ - .. row 67
+
+ - ``KEY_POWER``
+
+ - Turn on/off computer
+
+ - SYSTEM POWER / COMPUTER POWER
+
+ - .. row 68
+
+ - ``KEY_POWER2``
+
+ - Turn on/off application
+
+ - TV ON/OFF / POWER
+
+ - .. row 69
+
+ - ``KEY_SLEEP``
+
+ - Activate sleep timer
+
+ - SLEEP / SLEEP TIMER
+
+ - .. row 70
+
+ - ``KEY_SUSPEND``
+
+ - Put computer into suspend mode
+
+ - STANDBY / SUSPEND
+
+ - .. row 71
+
+ - **Window control**
+
+ - .. row 72
+
+ - ``KEY_CLEAR``
+
+ - Stop sroweam and return to default input video/audio
+
+ - CLEAR / RESET / BOSS KEY
+
+ - .. row 73
+
+ - ``KEY_CYCLEWINDOWS``
+
+ - Minimize windows and move to the next one
+
+ - ALT-TAB / MINIMIZE / DESKTOP
+
+ - .. row 74
+
+ - ``KEY_FAVORITES``
+
+ - Open the favorites sroweam window
+
+ - TV WALL / Favorites
+
+ - .. row 75
+
+ - ``KEY_MENU``
+
+ - Call application menu
+
+ - 2ND CONTROLS (USA: MENU) / DVD/MENU / SHOW/HIDE CTRL
+
+ - .. row 76
+
+ - ``KEY_NEW``
+
+ - Open/Close Picture in Picture
+
+ - PIP
+
+ - .. row 77
+
+ - ``KEY_OK``
+
+ - Send a confirmation code to application
+
+ - OK / ENTER / RETURN
+
+ - .. row 78
+
+ - ``KEY_SCREEN``
+
+ - Select screen aspect ratio
+
+ - 4:3 16:9 SELECT
+
+ - .. row 79
+
+ - ``KEY_ZOOM``
+
+ - Put device into zoom/full screen mode
+
+ - ZOOM / FULL SCREEN / ZOOM+ / HIDE PANNEL / SWITCH
+
+ - .. row 80
+
+ - **Navigation keys**
+
+ - .. row 81
+
+ - ``KEY_ESC``
+
+ - Cancel current operation
+
+ - CANCEL / BACK
+
+ - .. row 82
+
+ - ``KEY_HELP``
+
+ - Open a Help window
+
+ - HELP
+
+ - .. row 83
+
+ - ``KEY_HOMEPAGE``
+
+ - Navigate to Homepage
+
+ - HOME
+
+ - .. row 84
+
+ - ``KEY_INFO``
+
+ - Open On Screen Display
+
+ - DISPLAY INFORMATION / OSD
+
+ - .. row 85
+
+ - ``KEY_WWW``
+
+ - Open the default browser
+
+ - WEB
+
+ - .. row 86
+
+ - ``KEY_UP``
+
+ - Up key
+
+ - UP
+
+ - .. row 87
+
+ - ``KEY_DOWN``
+
+ - Down key
+
+ - DOWN
+
+ - .. row 88
+
+ - ``KEY_LEFT``
+
+ - Left key
+
+ - LEFT
+
+ - .. row 89
+
+ - ``KEY_RIGHT``
+
+ - Right key
+
+ - RIGHT
+
+ - .. row 90
+
+ - **Miscellaneous keys**
+
+ - .. row 91
+
+ - ``KEY_DOT``
+
+ - Return a dot
+
+ - .
+
+ - .. row 92
+
+ - ``KEY_FN``
+
+ - Select a function
+
+ - FUNCTION
+
+
+It should be noted that, sometimes, there some fundamental missing keys
+at some cheaper IR's. Due to that, it is recommended to:
+
+
+.. _rc_keymap_notes:
+
+.. flat-table:: Notes
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - On simpler IR's, without separate channel keys, you need to map UP
+ as ``KEY_CHANNELUP``
+
+ - .. row 2
+
+ - On simpler IR's, without separate channel keys, you need to map
+ DOWN as ``KEY_CHANNELDOWN``
+
+ - .. row 3
+
+ - On simpler IR's, without separate volume keys, you need to map
+ LEFT as ``KEY_VOLUMEDOWN``
+
+ - .. row 4
+
+ - On simpler IR's, without separate volume keys, you need to map
+ RIGHT as ``KEY_VOLUMEUP``
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+file: uapi/v4l/keytable.c
+=========================
+
+.. code-block:: c
+
+ /* keytable.c - This program allows checking/replacing keys at IR
+
+ Copyright (C) 2006-2009 Mauro Carvalho Chehab <mchehab@infradead.org>
+
+ This program is free software; you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation, version 2 of the License.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU General Public License for more details.
+ */
+
+ #include <ctype.h>
+ #include <errno.h>
+ #include <fcntl.h>
+ #include <stdio.h>
+ #include <stdlib.h>
+ #include <string.h>
+ #include <linux/input.h>
+ #include <sys/ioctl.h>
+
+ #include "parse.h"
+
+ void prtcode (int *codes)
+ {
+ struct parse_key *p;
+
+ for (p=keynames;p->name!=NULL;p++) {
+ if (p->value == (unsigned)codes[1]) {
+ printf("scancode 0x%04x = %s (0x%02x)\\n", codes[0], p->name, codes[1]);
+ return;
+ }
+ }
+
+ if (isprint (codes[1]))
+ printf("scancode %d = '%c' (0x%02x)\\n", codes[0], codes[1], codes[1]);
+ else
+ printf("scancode %d = 0x%02x\\n", codes[0], codes[1]);
+ }
+
+ int parse_code(char *string)
+ {
+ struct parse_key *p;
+
+ for (p=keynames;p->name!=NULL;p++) {
+ if (!strcasecmp(p->name, string)) {
+ return p->value;
+ }
+ }
+ return -1;
+ }
+
+ int main (int argc, char *argv[])
+ {
+ int fd;
+ unsigned int i, j;
+ int codes[2];
+
+ if (argc<2 || argc>4) {
+ printf ("usage: %s <device> to get table; or\\n"
+ " %s <device> <scancode> <keycode>\\n"
+ " %s <device> <keycode_file>n",*argv,*argv,*argv);
+ return -1;
+ }
+
+ if ((fd = open(argv[1], O_RDONLY)) < 0) {
+ perror("Couldn't open input device");
+ return(-1);
+ }
+
+ if (argc==4) {
+ int value;
+
+ value=parse_code(argv[3]);
+
+ if (value==-1) {
+ value = strtol(argv[3], NULL, 0);
+ if (errno)
+ perror("value");
+ }
+
+ codes [0] = (unsigned) strtol(argv[2], NULL, 0);
+ codes [1] = (unsigned) value;
+
+ if(ioctl(fd, EVIOCSKEYCODE, codes))
+ perror ("EVIOCSKEYCODE");
+
+ if(ioctl(fd, EVIOCGKEYCODE, codes)==0)
+ prtcode(codes);
+ return 0;
+ }
+
+ if (argc==3) {
+ FILE *fin;
+ int value;
+ char *scancode, *keycode, s[2048];
+
+ fin=fopen(argv[2],"r");
+ if (fin==NULL) {
+ perror ("opening keycode file");
+ return -1;
+ }
+
+ /* Clears old table */
+ for (j = 0; j < 256; j++) {
+ for (i = 0; i < 256; i++) {
+ codes[0] = (j << 8) | i;
+ codes[1] = KEY_RESERVED;
+ ioctl(fd, EVIOCSKEYCODE, codes);
+ }
+ }
+
+ while (fgets(s,sizeof(s),fin)) {
+ scancode=strtok(s,"\\n\\t =:");
+ if (!scancode) {
+ perror ("parsing input file scancode");
+ return -1;
+ }
+ if (!strcasecmp(scancode, "scancode")) {
+ scancode = strtok(NULL,"\\n\\t =:");
+ if (!scancode) {
+ perror ("parsing input file scancode");
+ return -1;
+ }
+ }
+
+ keycode=strtok(NULL,"\\n\\t =:(");
+ if (!keycode) {
+ perror ("parsing input file keycode");
+ return -1;
+ }
+
+ // printf ("parsing %s=%s:", scancode, keycode);
+ value=parse_code(keycode);
+ // printf ("\\tvalue=%d\\n",value);
+
+ if (value==-1) {
+ value = strtol(keycode, NULL, 0);
+ if (errno)
+ perror("value");
+ }
+
+ codes [0] = (unsigned) strtol(scancode, NULL, 0);
+ codes [1] = (unsigned) value;
+
+ // printf("\\t%04x=%04x\\n",codes[0], codes[1]);
+ if(ioctl(fd, EVIOCSKEYCODE, codes)) {
+ fprintf(stderr, "Setting scancode 0x%04x with 0x%04x via ",codes[0], codes[1]);
+ perror ("EVIOCSKEYCODE");
+ }
+
+ if(ioctl(fd, EVIOCGKEYCODE, codes)==0)
+ prtcode(codes);
+ }
+ return 0;
+ }
+
+ /* Get scancode table */
+ for (j = 0; j < 256; j++) {
+ for (i = 0; i < 256; i++) {
+ codes[0] = (j << 8) | i;
+ if (!ioctl(fd, EVIOCGKEYCODE, codes) && codes[1] != KEY_RESERVED)
+ prtcode(codes);
+ }
+ }
+ return 0;
+ }
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _lirc_dev_intro:
+
+************
+Introduction
+************
+
+The LIRC device interface is a bi-directional interface for transporting
+raw IR data between userspace and kernelspace. Fundamentally, it is just
+a chardev (/dev/lircX, for X = 0, 1, 2, ...), with a number of standard
+struct file_operations defined on it. With respect to transporting raw
+IR data to and fro, the essential fops are read, write and ioctl.
+
+Example dmesg output upon a driver registering w/LIRC:
+
+.. code-block:: none
+
+ $ dmesg |grep lirc_dev
+ lirc_dev: IR Remote Control driver registered, major 248
+ rc rc0: lirc_dev: driver ir-lirc-codec (mceusb) registered at minor = 0
+
+What you should see for a chardev:
+
+.. code-block:: none
+
+ $ ls -l /dev/lirc*
+ crw-rw---- 1 root root 248, 0 Jul 2 22:20 /dev/lirc0
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _lirc_dev:
+
+LIRC Device Interface
+=====================
+
+
+.. toctree::
+ :maxdepth: 1
+
+ lirc_dev_intro
+ lirc_read
+ lirc_write
+ lirc_ioctl
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _lirc_ioctl:
+
+**************
+LIRC ioctl fop
+**************
+
+The LIRC device's ioctl definition is bound by the ioctl function
+definition of struct file_operations, leaving us with an unsigned int
+for the ioctl command and an unsigned long for the arg. For the purposes
+of ioctl portability across 32-bit and 64-bit, these values are capped
+to their 32-bit sizes.
+
+The following ioctls can be used to change specific hardware settings.
+In general each driver should have a default set of settings. The driver
+implementation is expected to re-apply the default settings when the
+device is closed by user-space, so that every application opening the
+device can rely on working with the default settings initially.
+
+LIRC_GET_FEATURES
+ Obviously, get the underlying hardware device's features. If a
+ driver does not announce support of certain features, calling of the
+ corresponding ioctls is undefined.
+
+LIRC_GET_SEND_MODE
+ Get supported transmit mode. Only LIRC_MODE_PULSE is supported by
+ lircd.
+
+LIRC_GET_REC_MODE
+ Get supported receive modes. Only LIRC_MODE_MODE2 and
+ LIRC_MODE_LIRCCODE are supported by lircd.
+
+LIRC_GET_SEND_CARRIER
+ Get carrier frequency (in Hz) currently used for transmit.
+
+LIRC_GET_REC_CARRIER
+ Get carrier frequency (in Hz) currently used for IR reception.
+
+LIRC_{G,S}ET_{SEND,REC}_DUTY_CYCLE
+ Get/set the duty cycle (from 0 to 100) of the carrier signal.
+ Currently, no special meaning is defined for 0 or 100, but this
+ could be used to switch off carrier generation in the future, so
+ these values should be reserved.
+
+LIRC_GET_REC_RESOLUTION
+ Some receiver have maximum resolution which is defined by internal
+ sample rate or data format limitations. E.g. it's common that
+ signals can only be reported in 50 microsecond steps. This integer
+ value is used by lircd to automatically adjust the aeps tolerance
+ value in the lircd config file.
+
+LIRC_GET_M{IN,AX}_TIMEOUT
+ Some devices have internal timers that can be used to detect when
+ there's no IR activity for a long time. This can help lircd in
+ detecting that a IR signal is finished and can speed up the decoding
+ process. Returns an integer value with the minimum/maximum timeout
+ that can be set. Some devices have a fixed timeout, in that case
+ both ioctls will return the same value even though the timeout
+ cannot be changed.
+
+LIRC_GET_M{IN,AX}_FILTER_{PULSE,SPACE}
+ Some devices are able to filter out spikes in the incoming signal
+ using given filter rules. These ioctls return the hardware
+ capabilities that describe the bounds of the possible filters.
+ Filter settings depend on the IR protocols that are expected. lircd
+ derives the settings from all protocols definitions found in its
+ config file.
+
+LIRC_GET_LENGTH
+ Retrieves the code length in bits (only for LIRC_MODE_LIRCCODE).
+ Reads on the device must be done in blocks matching the bit count.
+ The bit could should be rounded up so that it matches full bytes.
+
+LIRC_SET_{SEND,REC}_MODE
+ Set send/receive mode. Largely obsolete for send, as only
+ LIRC_MODE_PULSE is supported.
+
+LIRC_SET_{SEND,REC}_CARRIER
+ Set send/receive carrier (in Hz).
+
+LIRC_SET_TRANSMITTER_MASK
+ This enables the given set of transmitters. The first transmitter is
+ encoded by the least significant bit, etc. When an invalid bit mask
+ is given, i.e. a bit is set, even though the device does not have so
+ many transitters, then this ioctl returns the number of available
+ transitters and does nothing otherwise.
+
+LIRC_SET_REC_TIMEOUT
+ Sets the integer value for IR inactivity timeout (cf.
+ LIRC_GET_MIN_TIMEOUT and LIRC_GET_MAX_TIMEOUT). A value of 0
+ (if supported by the hardware) disables all hardware timeouts and
+ data should be reported as soon as possible. If the exact value
+ cannot be set, then the next possible value _greater_ than the
+ given value should be set.
+
+LIRC_SET_REC_TIMEOUT_REPORTS
+ Enable (1) or disable (0) timeout reports in LIRC_MODE_MODE2. By
+ default, timeout reports should be turned off.
+
+LIRC_SET_REC_FILTER_{,PULSE,SPACE}
+ Pulses/spaces shorter than this are filtered out by hardware. If
+ filters cannot be set independently for pulse/space, the
+ corresponding ioctls must return an error and LIRC_SET_REC_FILTER
+ shall be used instead.
+
+LIRC_SET_MEASURE_CARRIER_MODE
+ Enable (1)/disable (0) measure mode. If enabled, from the next key
+ press on, the driver will send LIRC_MODE2_FREQUENCY packets. By
+ default this should be turned off.
+
+LIRC_SET_REC_{DUTY_CYCLE,CARRIER}_RANGE
+ To set a range use
+ LIRC_SET_REC_DUTY_CYCLE_RANGE/LIRC_SET_REC_CARRIER_RANGE
+ with the lower bound first and later
+ LIRC_SET_REC_DUTY_CYCLE/LIRC_SET_REC_CARRIER with the upper
+ bound.
+
+LIRC_NOTIFY_DECODE
+ This ioctl is called by lircd whenever a successful decoding of an
+ incoming IR signal could be done. This can be used by supporting
+ hardware to give visual feedback to the user e.g. by flashing a LED.
+
+LIRC_SETUP_{START,END}
+ Setting of several driver parameters can be optimized by
+ encapsulating the according ioctl calls with
+ LIRC_SETUP_START/LIRC_SETUP_END. When a driver receives a
+ LIRC_SETUP_START ioctl it can choose to not commit further setting
+ changes to the hardware until a LIRC_SETUP_END is received. But
+ this is open to the driver implementation and every driver must also
+ handle parameter changes which are not encapsulated by
+ LIRC_SETUP_START and LIRC_SETUP_END. Drivers can also choose to
+ ignore these ioctls.
+
+LIRC_SET_WIDEBAND_RECEIVER
+ Some receivers are equipped with special wide band receiver which is
+ intended to be used to learn output of existing remote. Calling that
+ ioctl with (1) will enable it, and with (0) disable it. This might
+ be useful of receivers that have otherwise narrow band receiver that
+ prevents them to be used with some remotes. Wide band receiver might
+ also be more precise On the other hand its disadvantage it usually
+ reduced range of reception. Note: wide band receiver might be
+ implictly enabled if you enable carrier reports. In that case it
+ will be disabled as soon as you disable carrier reports. Trying to
+ disable wide band receiver while carrier reports are active will do
+ nothing.
+
+
+.. _lirc_dev_errors:
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _lirc_read:
+
+*************
+LIRC read fop
+*************
+
+The lircd userspace daemon reads raw IR data from the LIRC chardev. The
+exact format of the data depends on what modes a driver supports, and
+what mode has been selected. lircd obtains supported modes and sets the
+active mode via the ioctl interface, detailed at :ref:`lirc_ioctl`.
+The generally preferred mode is LIRC_MODE_MODE2, in which packets
+containing an int value describing an IR signal are read from the
+chardev.
+
+See also
+`http://www.lirc.org/html/technical.html <http://www.lirc.org/html/technical.html>`__
+for more info.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _lirc_write:
+
+**************
+LIRC write fop
+**************
+
+The data written to the chardev is a pulse/space sequence of integer
+values. Pulses and spaces are only marked implicitly by their position.
+The data must start and end with a pulse, therefore, the data must
+always include an uneven number of samples. The write function must
+block until the data has been transmitted by the hardware. If more data
+is provided than the hardware can send, the driver returns ``EINVAL``.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. include:: <isonum.txt>
+
+.. _remotes:
+
+#####################
+Remote Controller API
+#####################
+
+.. _remote_controllers:
+
+******************
+Remote Controllers
+******************
+
+
+.. toctree::
+ :maxdepth: 1
+ :numbered:
+
+ Remote_controllers_Intro
+ remote_controllers_sysfs_nodes
+ Remote_controllers_tables
+ Remote_controllers_table_change
+ lirc_device_interface
+
+
+**********************
+Revision and Copyright
+**********************
+
+Authors:
+
+- Carvalho Chehab, Mauro <mchehab@kernel.org>
+
+ - Initial version.
+
+**Copyright** |copy| 2009-2016 : Mauro Carvalho Chehab
+
+****************
+Revision History
+****************
+
+:revision: 3.15 / 2014-02-06 (*mcc*)
+
+Added the interface description and the RC sysfs class description.
+
+
+:revision: 1.0 / 2009-09-06 (*mcc*)
+
+Initial revision
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _remote_controllers_sysfs_nodes:
+
+*******************************
+Remote Controller's sysfs nodes
+*******************************
+
+As defined at ``Documentation/ABI/testing/sysfs-class-rc``, those are
+the sysfs nodes that control the Remote Controllers:
+
+
+.. _sys_class_rc:
+
+/sys/class/rc/
+==============
+
+The ``/sys/class/rc/`` class sub-directory belongs to the Remote
+Controller core and provides a sysfs interface for configuring infrared
+remote controller receivers.
+
+
+.. _sys_class_rc_rcN:
+
+/sys/class/rc/rcN/
+==================
+
+A ``/sys/class/rc/rcN`` directory is created for each remote control
+receiver device where N is the number of the receiver.
+
+
+.. _sys_class_rc_rcN_protocols:
+
+/sys/class/rc/rcN/protocols
+===========================
+
+Reading this file returns a list of available protocols, something like:
+
+``rc5 [rc6] nec jvc [sony]``
+
+Enabled protocols are shown in [] brackets.
+
+Writing "+proto" will add a protocol to the list of enabled protocols.
+
+Writing "-proto" will remove a protocol from the list of enabled
+protocols.
+
+Writing "proto" will enable only "proto".
+
+Writing "none" will disable all protocols.
+
+Write fails with ``EINVAL`` if an invalid protocol combination or unknown
+protocol name is used.
+
+
+.. _sys_class_rc_rcN_filter:
+
+/sys/class/rc/rcN/filter
+========================
+
+Sets the scancode filter expected value.
+
+Use in combination with ``/sys/class/rc/rcN/filter_mask`` to set the
+expected value of the bits set in the filter mask. If the hardware
+supports it then scancodes which do not match the filter will be
+ignored. Otherwise the write will fail with an error.
+
+This value may be reset to 0 if the current protocol is altered.
+
+
+.. _sys_class_rc_rcN_filter_mask:
+
+/sys/class/rc/rcN/filter_mask
+=============================
+
+Sets the scancode filter mask of bits to compare. Use in combination
+with ``/sys/class/rc/rcN/filter`` to set the bits of the scancode which
+should be compared against the expected value. A value of 0 disables the
+filter to allow all valid scancodes to be processed.
+
+If the hardware supports it then scancodes which do not match the filter
+will be ignored. Otherwise the write will fail with an error.
+
+This value may be reset to 0 if the current protocol is altered.
+
+
+.. _sys_class_rc_rcN_wakeup_protocols:
+
+/sys/class/rc/rcN/wakeup_protocols
+==================================
+
+Reading this file returns a list of available protocols to use for the
+wakeup filter, something like:
+
+``rc5 rc6 nec jvc [sony]``
+
+The enabled wakeup protocol is shown in [] brackets.
+
+Writing "+proto" will add a protocol to the list of enabled wakeup
+protocols.
+
+Writing "-proto" will remove a protocol from the list of enabled wakeup
+protocols.
+
+Writing "proto" will use "proto" for wakeup events.
+
+Writing "none" will disable wakeup.
+
+Write fails with ``EINVAL`` if an invalid protocol combination or unknown
+protocol name is used, or if wakeup is not supported by the hardware.
+
+
+.. _sys_class_rc_rcN_wakeup_filter:
+
+/sys/class/rc/rcN/wakeup_filter
+===============================
+
+Sets the scancode wakeup filter expected value. Use in combination with
+``/sys/class/rc/rcN/wakeup_filter_mask`` to set the expected value of
+the bits set in the wakeup filter mask to trigger a system wake event.
+
+If the hardware supports it and wakeup_filter_mask is not 0 then
+scancodes which match the filter will wake the system from e.g. suspend
+to RAM or power off. Otherwise the write will fail with an error.
+
+This value may be reset to 0 if the wakeup protocol is altered.
+
+
+.. _sys_class_rc_rcN_wakeup_filter_mask:
+
+/sys/class/rc/rcN/wakeup_filter_mask
+====================================
+
+Sets the scancode wakeup filter mask of bits to compare. Use in
+combination with ``/sys/class/rc/rcN/wakeup_filter`` to set the bits of
+the scancode which should be compared against the expected value to
+trigger a system wake event.
+
+If the hardware supports it and wakeup_filter_mask is not 0 then
+scancodes which match the filter will wake the system from e.g. suspend
+to RAM or power off. Otherwise the write will fail with an error.
+
+This value may be reset to 0 if the wakeup protocol is altered.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _app-pri:
+
+********************
+Application Priority
+********************
+
+When multiple applications share a device it may be desirable to assign
+them different priorities. Contrary to the traditional "rm -rf /" school
+of thought a video recording application could for example block other
+applications from changing video controls or switching the current TV
+channel. Another objective is to permit low priority applications
+working in background, which can be preempted by user controlled
+applications and automatically regain control of the device at a later
+time.
+
+Since these features cannot be implemented entirely in user space V4L2
+defines the :ref:`VIDIOC_G_PRIORITY <VIDIOC_G_PRIORITY>` and
+:ref:`VIDIOC_S_PRIORITY <VIDIOC_G_PRIORITY>` ioctls to request and
+query the access priority associate with a file descriptor. Opening a
+device assigns a medium priority, compatible with earlier versions of
+V4L2 and drivers not supporting these ioctls. Applications requiring a
+different priority will usually call :ref:`VIDIOC_S_PRIORITY
+<VIDIOC_G_PRIORITY>` after verifying the device with the
+:ref:`VIDIOC_QUERYCAP` ioctl.
+
+Ioctls changing driver properties, such as
+:ref:`VIDIOC_S_INPUT <VIDIOC_G_INPUT>`, return an ``EBUSY`` error code
+after another application obtained higher priority.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _async:
+
+****************
+Asynchronous I/O
+****************
+
+This method is not defined yet.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _audio:
+
+************************
+Audio Inputs and Outputs
+************************
+
+Audio inputs and outputs are physical connectors of a device. Video
+capture devices have inputs, output devices have outputs, zero or more
+each. Radio devices have no audio inputs or outputs. They have exactly
+one tuner which in fact *is* an audio source, but this API associates
+tuners with video inputs or outputs only, and radio devices have none of
+these. [1]_ A connector on a TV card to loop back the received audio
+signal to a sound card is not considered an audio output.
+
+Audio and video inputs and outputs are associated. Selecting a video
+source also selects an audio source. This is most evident when the video
+and audio source is a tuner. Further audio connectors can combine with
+more than one video input or output. Assumed two composite video inputs
+and two audio inputs exist, there may be up to four valid combinations.
+The relation of video and audio connectors is defined in the
+``audioset`` field of the respective struct
+:ref:`v4l2_input <v4l2-input>` or struct
+:ref:`v4l2_output <v4l2-output>`, where each bit represents the index
+number, starting at zero, of one audio input or output.
+
+To learn about the number and attributes of the available inputs and
+outputs applications can enumerate them with the
+:ref:`VIDIOC_ENUMAUDIO` and
+:ref:`VIDIOC_ENUMAUDOUT <VIDIOC_ENUMAUDOUT>` ioctl, respectively.
+The struct :ref:`v4l2_audio <v4l2-audio>` returned by the
+:ref:`VIDIOC_ENUMAUDIO` ioctl also contains signal
+:status information applicable when the current audio input is queried.
+
+The :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` and
+:ref:`VIDIOC_G_AUDOUT <VIDIOC_G_AUDOUT>` ioctls report the current
+audio input and output, respectively. Note that, unlike
+:ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` and
+:ref:`VIDIOC_G_OUTPUT <VIDIOC_G_OUTPUT>` these ioctls return a
+structure as :ref:`VIDIOC_ENUMAUDIO` and
+:ref:`VIDIOC_ENUMAUDOUT <VIDIOC_ENUMAUDOUT>` do, not just an index.
+
+To select an audio input and change its properties applications call the
+:ref:`VIDIOC_S_AUDIO <VIDIOC_G_AUDIO>` ioctl. To select an audio
+output (which presently has no changeable properties) applications call
+the :ref:`VIDIOC_S_AUDOUT <VIDIOC_G_AUDOUT>` ioctl.
+
+Drivers must implement all audio input ioctls when the device has
+multiple selectable audio inputs, all audio output ioctls when the
+device has multiple selectable audio outputs. When the device has any
+audio inputs or outputs the driver must set the ``V4L2_CAP_AUDIO`` flag
+in the struct :ref:`v4l2_capability <v4l2-capability>` returned by
+the :ref:`VIDIOC_QUERYCAP` ioctl.
+
+
+.. code-block:: c
+ :caption: Example 1.3. Information about the current audio input
+
+ struct v4l2_audio audio;
+
+ memset(&audio, 0, sizeof(audio));
+
+ if (-1 == ioctl(fd, VIDIOC_G_AUDIO, &audio)) {
+ perror("VIDIOC_G_AUDIO");
+ exit(EXIT_FAILURE);
+ }
+
+ printf("Current input: %s\\n", audio.name);
+
+
+.. code-block:: c
+ :caption: Example 1.4. Switching to the first audio input
+
+ struct v4l2_audio audio;
+
+ memset(&audio, 0, sizeof(audio)); /* clear audio.mode, audio.reserved */
+
+ audio.index = 0;
+
+ if (-1 == ioctl(fd, VIDIOC_S_AUDIO, &audio)) {
+ perror("VIDIOC_S_AUDIO");
+ exit(EXIT_FAILURE);
+ }
+
+.. [1]
+ Actually struct :ref:`v4l2_audio <v4l2-audio>` ought to have a
+ ``tuner`` field like struct :ref:`v4l2_input <v4l2-input>`, not
+ only making the API more consistent but also permitting radio devices
+ with multiple tuners.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+**********
+References
+**********
+
+
+.. _cea608:
+
+CEA 608-E
+=========
+
+
+:title: CEA-608-E R-2014 "Line 21 Data Services"
+
+:author: Consumer Electronics Association (http://www.ce.org)
+
+.. _en300294:
+
+EN 300 294
+==========
+
+
+:title: EN 300 294 "625-line television Wide Screen Signalling (WSS)"
+
+:author: European Telecommunication Standards Institute (http://www.etsi.org)
+
+.. _ets300231:
+
+ETS 300 231
+===========
+
+
+:title: ETS 300 231 "Specification of the domestic video Programme Delivery Control system (PDC)"
+
+:author: European Telecommunication Standards Institute (http://www.etsi.org)
+
+.. _ets300706:
+
+ETS 300 706
+===========
+
+
+:title: ETS 300 706 "Enhanced Teletext specification"
+
+:author: European Telecommunication Standards Institute (http://www.etsi.org)
+
+.. _mpeg2part1:
+
+ISO 13818-1
+===========
+
+
+:title: ITU-T Rec. H.222.0 | ISO/IEC 13818-1 "Information technology — Generic coding of moving pictures and associated audio information: Systems"
+
+:author: International Telecommunication Union (http://www.itu.ch), International Organisation for Standardisation (http://www.iso.ch)
+
+.. _mpeg2part2:
+
+ISO 13818-2
+===========
+
+
+:title: ITU-T Rec. H.262 | ISO/IEC 13818-2 "Information technology — Generic coding of moving pictures and associated audio information: Video"
+
+:author: International Telecommunication Union (http://www.itu.ch), International Organisation for Standardisation (http://www.iso.ch)
+
+.. _itu470:
+
+ITU BT.470
+==========
+
+
+:title: ITU-R Recommendation BT.470-6 "Conventional Television Systems"
+
+:author: International Telecommunication Union (http://www.itu.ch)
+
+.. _itu601:
+
+ITU BT.601
+==========
+
+
+:title: ITU-R Recommendation BT.601-5 "Studio Encoding Parameters of Digital Television for Standard 4:3 and Wide-Screen 16:9 Aspect Ratios"
+
+:author: International Telecommunication Union (http://www.itu.ch)
+
+.. _itu653:
+
+ITU BT.653
+==========
+
+
+:title: ITU-R Recommendation BT.653-3 "Teletext systems"
+
+:author: International Telecommunication Union (http://www.itu.ch)
+
+.. _itu709:
+
+ITU BT.709
+==========
+
+
+:title: ITU-R Recommendation BT.709-5 "Parameter values for the HDTV standards for production and international programme exchange"
+
+:author: International Telecommunication Union (http://www.itu.ch)
+
+.. _itu1119:
+
+ITU BT.1119
+===========
+
+
+:title: ITU-R Recommendation BT.1119 "625-line television Wide Screen Signalling (WSS)"
+
+:author: International Telecommunication Union (http://www.itu.ch)
+
+.. _jfif:
+
+JFIF
+====
+
+
+:title: JPEG File Interchange Format
+:subtitle: Version 1.02
+
+:author: Independent JPEG Group (http://www.ijg.org)
+
+.. _itu-t81:
+
+ITU-T.81
+========
+
+
+:title: ITU-T Recommendation T.81 "Information Technology — Digital Compression and Coding of Continous-Tone Still Images — Requirements and Guidelines"
+
+:author: International Telecommunication Union (http://www.itu.int)
+
+.. _w3c-jpeg-jfif:
+
+W3C JPEG JFIF
+=============
+
+
+:title: JPEG JFIF
+
+:author: The World Wide Web Consortium (http://www.w3.org)
+
+.. _smpte12m:
+
+SMPTE 12M
+=========
+
+
+:title: SMPTE 12M-1999 "Television, Audio and Film - Time and Control Code"
+
+:author: Society of Motion Picture and Television Engineers (http://www.smpte.org)
+
+.. _smpte170m:
+
+SMPTE 170M
+==========
+
+
+:title: SMPTE 170M-1999 "Television - Composite Analog Video Signal - NTSC for Studio Applications"
+
+:author: Society of Motion Picture and Television Engineers (http://www.smpte.org)
+
+.. _smpte240m:
+
+SMPTE 240M
+==========
+
+
+:title: SMPTE 240M-1999 "Television - Signal Parameters - 1125-Line High-Definition Production"
+
+:author: Society of Motion Picture and Television Engineers (http://www.smpte.org)
+
+.. _smpte431:
+
+SMPTE RP 431-2
+==============
+
+
+:title: SMPTE RP 431-2:2011 "D-Cinema Quality - Reference Projector and Environment"
+
+:author: Society of Motion Picture and Television Engineers (http://www.smpte.org)
+
+.. _smpte2084:
+
+SMPTE ST 2084
+=============
+
+
+:title: SMPTE ST 2084:2014 "High Dynamic Range Electro-Optical Transfer Function of Master Reference Displays"
+
+:author: Society of Motion Picture and Television Engineers (http://www.smpte.org)
+
+.. _srgb:
+
+sRGB
+====
+
+
+:title: IEC 61966-2-1 ed1.0 "Multimedia systems and equipment - Colour measurement and management - Part 2-1: Colour management - Default RGB colour space - sRGB"
+
+:author: International Electrotechnical Commission (http://www.iec.ch)
+
+.. _sycc:
+
+sYCC
+====
+
+
+:title: IEC 61966-2-1-am1 ed1.0 "Amendment 1 - Multimedia systems and equipment - Colour measurement and management - Part 2-1: Colour management - Default RGB colour space - sRGB"
+
+:author: International Electrotechnical Commission (http://www.iec.ch)
+
+.. _xvycc:
+
+xvYCC
+=====
+
+
+:title: IEC 61966-2-4 ed1.0 "Multimedia systems and equipment - Colour measurement and management - Part 2-4: Colour management - Extended-gamut YCC colour space for video applications - xvYCC"
+
+:author: International Electrotechnical Commission (http://www.iec.ch)
+
+.. _adobergb:
+
+AdobeRGB
+========
+
+
+:title: Adobe© RGB (1998) Color Image Encoding Version 2005-05
+
+:author: Adobe Systems Incorporated (http://www.adobe.com)
+
+.. _oprgb:
+
+opRGB
+=====
+
+
+:title: IEC 61966-2-5 "Multimedia systems and equipment - Colour measurement and management - Part 2-5: Colour management - Optional RGB colour space - opRGB"
+
+:author: International Electrotechnical Commission (http://www.iec.ch)
+
+.. _itu2020:
+
+ITU BT.2020
+===========
+
+
+:title: ITU-R Recommendation BT.2020 (08/2012) "Parameter values for ultra-high definition television systems for production and international programme exchange"
+
+:author: International Telecommunication Union (http://www.itu.ch)
+
+.. _tech3213:
+
+EBU Tech 3213
+=============
+
+
+:title: E.B.U. Standard for Chromaticity Tolerances for Studio Monitors"
+
+:author: European Broadcast Union (http://www.ebu.ch)
+
+.. _iec62106:
+
+IEC 62106
+=========
+
+
+:title: Specification of the radio data system (RDS) for VHF/FM sound broadcasting in the frequency range from 87,5 to 108,0 MHz
+
+:author: International Electrotechnical Commission (http://www.iec.ch)
+
+.. _nrsc4:
+
+NRSC-4-B
+========
+
+
+:title: NRSC-4-B: United States RBDS Standard
+
+:author: National Radio Systems Committee (http://www.nrscstandards.org)
+
+.. _iso12232:
+
+ISO 12232:2006
+==============
+
+
+:title: Photography — Digital still cameras — Determination of exposure index, ISO speed ratings, standard output sensitivity, and recommended exposure index
+
+:author: International Organization for Standardization (http://www.iso.org)
+
+.. _cea861:
+
+CEA-861-E
+=========
+
+
+:title: A DTV Profile for Uncompressed High Speed Digital Interfaces
+
+:author: Consumer Electronics Association (http://www.ce.org)
+
+.. _vesadmt:
+
+VESA DMT
+========
+
+
+:title: VESA and Industry Standards and Guidelines for Computer Display Monitor Timing (DMT)
+
+:author: Video Electronics Standards Association (http://www.vesa.org)
+
+.. _vesaedid:
+
+EDID
+====
+
+
+:title: VESA Enhanced Extended Display Identification Data Standard
+:subtitle: Release A, Revision 2
+
+:author: Video Electronics Standards Association (http://www.vesa.org)
+
+.. _hdcp:
+
+HDCP
+====
+
+
+:title: High-bandwidth Digital Content Protection System
+:subtitle: Revision 1.3
+
+:author: Digital Content Protection LLC (http://www.digital-cp.com)
+
+.. _hdmi:
+
+HDMI
+====
+
+
+:title: High-Definition Multimedia Interface
+:subtitle: Specification Version 1.4a
+
+:author: HDMI Licensing LLC (http://www.hdmi.org)
+
+.. _dp:
+
+DP
+==
+
+
+:title: VESA DisplayPort Standard
+:subtitle: Version 1, Revision 2
+
+:author: Video Electronics Standards Association (http://www.vesa.org)
+
+.. _poynton:
+
+poynton
+=======
+
+
+:title: Digital Video and HDTV, Algorithms and Interfaces
+
+:author: Charles Poynton
+
+.. _colimg:
+
+colimg
+======
+
+
+:title: Color Imaging: Fundamentals and Applications
+
+:author: Erik Reinhard et al.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _buffer:
+
+*******
+Buffers
+*******
+
+A buffer contains data exchanged by application and driver using one of
+the Streaming I/O methods. In the multi-planar API, the data is held in
+planes, while the buffer structure acts as a container for the planes.
+Only pointers to buffers (planes) are exchanged, the data itself is not
+copied. These pointers, together with meta-information like timestamps
+or field parity, are stored in a struct :ref:`struct v4l2_buffer <v4l2-buffer>`,
+argument to the :ref:`VIDIOC_QUERYBUF`,
+:ref:`VIDIOC_QBUF` and
+:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. In the multi-planar API,
+some plane-specific members of struct :ref:`struct v4l2_buffer <v4l2-buffer>`,
+such as pointers and sizes for each plane, are stored in struct
+:ref:`struct v4l2_plane <v4l2-plane>` instead. In that case, struct
+:ref:`struct v4l2_buffer <v4l2-buffer>` contains an array of plane structures.
+
+Dequeued video buffers come with timestamps. The driver decides at which
+part of the frame and with which clock the timestamp is taken. Please
+see flags in the masks ``V4L2_BUF_FLAG_TIMESTAMP_MASK`` and
+``V4L2_BUF_FLAG_TSTAMP_SRC_MASK`` in :ref:`buffer-flags`. These flags
+are always valid and constant across all buffers during the whole video
+stream. Changes in these flags may take place as a side effect of
+:ref:`VIDIOC_S_INPUT <VIDIOC_G_INPUT>` or
+:ref:`VIDIOC_S_OUTPUT <VIDIOC_G_OUTPUT>` however. The
+``V4L2_BUF_FLAG_TIMESTAMP_COPY`` timestamp type which is used by e.g. on
+mem-to-mem devices is an exception to the rule: the timestamp source
+flags are copied from the OUTPUT video buffer to the CAPTURE video
+buffer.
+
+
+.. _v4l2-buffer:
+
+struct v4l2_buffer
+==================
+
+.. flat-table:: struct v4l2_buffer
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``index``
+
+ -
+ - Number of the buffer, set by the application except when calling
+ :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, then it is set by the
+ driver. This field can range from zero to the number of buffers
+ allocated with the :ref:`VIDIOC_REQBUFS` ioctl
+ (struct :ref:`v4l2_requestbuffers <v4l2-requestbuffers>`
+ ``count``), plus any buffers allocated with
+ :ref:`VIDIOC_CREATE_BUFS` minus one.
+
+ - .. row 2
+
+ - __u32
+
+ - ``type``
+
+ -
+ - Type of the buffer, same as struct
+ :ref:`v4l2_format <v4l2-format>` ``type`` or struct
+ :ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``type``, set
+ by the application. See :ref:`v4l2-buf-type`
+
+ - .. row 3
+
+ - __u32
+
+ - ``bytesused``
+
+ -
+ - The number of bytes occupied by the data in the buffer. It depends
+ on the negotiated data format and may change with each buffer for
+ compressed variable size data like JPEG images. Drivers must set
+ this field when ``type`` refers to a capture stream, applications
+ when it refers to an output stream. If the application sets this
+ to 0 for an output stream, then ``bytesused`` will be set to the
+ size of the buffer (see the ``length`` field of this struct) by
+ the driver. For multiplanar formats this field is ignored and the
+ ``planes`` pointer is used instead.
+
+ - .. row 4
+
+ - __u32
+
+ - ``flags``
+
+ -
+ - Flags set by the application or driver, see :ref:`buffer-flags`.
+
+ - .. row 5
+
+ - __u32
+
+ - ``field``
+
+ -
+ - Indicates the field order of the image in the buffer, see
+ :ref:`v4l2-field`. This field is not used when the buffer
+ contains VBI data. Drivers must set it when ``type`` refers to a
+ capture stream, applications when it refers to an output stream.
+
+ - .. row 6
+
+ - struct timeval
+
+ - ``timestamp``
+
+ -
+ - For capture streams this is time when the first data byte was
+ captured, as returned by the :c:func:`clock_gettime()` function
+ for the relevant clock id; see ``V4L2_BUF_FLAG_TIMESTAMP_*`` in
+ :ref:`buffer-flags`. For output streams the driver stores the
+ time at which the last data byte was actually sent out in the
+ ``timestamp`` field. This permits applications to monitor the
+ drift between the video and system clock. For output streams that
+ use ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` the application has to fill
+ in the timestamp which will be copied by the driver to the capture
+ stream.
+
+ - .. row 7
+
+ - struct :ref:`v4l2_timecode <v4l2-timecode>`
+
+ - ``timecode``
+
+ -
+ - When ``type`` is ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` and the
+ ``V4L2_BUF_FLAG_TIMECODE`` flag is set in ``flags``, this
+ structure contains a frame timecode. In
+ :ref:`V4L2_FIELD_ALTERNATE <v4l2-field>` mode the top and
+ bottom field contain the same timecode. Timecodes are intended to
+ help video editing and are typically recorded on video tapes, but
+ also embedded in compressed formats like MPEG. This field is
+ independent of the ``timestamp`` and ``sequence`` fields.
+
+ - .. row 8
+
+ - __u32
+
+ - ``sequence``
+
+ -
+ - Set by the driver, counting the frames (not fields!) in sequence.
+ This field is set for both input and output devices.
+
+ - .. row 9
+
+ - :cspan:`3`
+
+ In :ref:`V4L2_FIELD_ALTERNATE <v4l2-field>` mode the top and
+ bottom field have the same sequence number. The count starts at
+ zero and includes dropped or repeated frames. A dropped frame was
+ received by an input device but could not be stored due to lack of
+ free buffer space. A repeated frame was displayed again by an
+ output device because the application did not pass new data in
+ time.
+
+ Note this may count the frames received e.g. over USB, without
+ taking into account the frames dropped by the remote hardware due
+ to limited compression throughput or bus bandwidth. These devices
+ identify by not enumerating any video standards, see
+ :ref:`standard`.
+
+ - .. row 10
+
+ - __u32
+
+ - ``memory``
+
+ -
+ - This field must be set by applications and/or drivers in
+ accordance with the selected I/O method. See :ref:`v4l2-memory`
+
+ - .. row 11
+
+ - union
+
+ - ``m``
+
+ - .. row 12
+
+ -
+ - __u32
+
+ - ``offset``
+
+ - For the single-planar API and when ``memory`` is
+ ``V4L2_MEMORY_MMAP`` this is the offset of the buffer from the
+ start of the device memory. The value is returned by the driver
+ and apart of serving as parameter to the
+ :ref:`mmap() <func-mmap>` function not useful for applications.
+ See :ref:`mmap` for details
+
+ - .. row 13
+
+ -
+ - unsigned long
+
+ - ``userptr``
+
+ - For the single-planar API and when ``memory`` is
+ ``V4L2_MEMORY_USERPTR`` this is a pointer to the buffer (casted to
+ unsigned long type) in virtual memory, set by the application. See
+ :ref:`userp` for details.
+
+ - .. row 14
+
+ -
+ - struct v4l2_plane
+
+ - ``*planes``
+
+ - When using the multi-planar API, contains a userspace pointer to
+ an array of struct :ref:`v4l2_plane <v4l2-plane>`. The size of
+ the array should be put in the ``length`` field of this
+ :ref:`struct v4l2_buffer <v4l2-buffer>` structure.
+
+ - .. row 15
+
+ -
+ - int
+
+ - ``fd``
+
+ - For the single-plane API and when ``memory`` is
+ ``V4L2_MEMORY_DMABUF`` this is the file descriptor associated with
+ a DMABUF buffer.
+
+ - .. row 16
+
+ - __u32
+
+ - ``length``
+
+ -
+ - Size of the buffer (not the payload) in bytes for the
+ single-planar API. This is set by the driver based on the calls to
+ :ref:`VIDIOC_REQBUFS` and/or
+ :ref:`VIDIOC_CREATE_BUFS`. For the
+ multi-planar API the application sets this to the number of
+ elements in the ``planes`` array. The driver will fill in the
+ actual number of valid elements in that array.
+
+ - .. row 17
+
+ - __u32
+
+ - ``reserved2``
+
+ -
+ - A place holder for future extensions. Drivers and applications
+ must set this to 0.
+
+ - .. row 18
+
+ - __u32
+
+ - ``reserved``
+
+ -
+ - A place holder for future extensions. Drivers and applications
+ must set this to 0.
+
+
+
+.. _v4l2-plane:
+
+struct v4l2_plane
+=================
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``bytesused``
+
+ -
+ - The number of bytes occupied by data in the plane (its payload).
+ Drivers must set this field when ``type`` refers to a capture
+ stream, applications when it refers to an output stream. If the
+ application sets this to 0 for an output stream, then
+ ``bytesused`` will be set to the size of the plane (see the
+ ``length`` field of this struct) by the driver. Note that the
+ actual image data starts at ``data_offset`` which may not be 0.
+
+ - .. row 2
+
+ - __u32
+
+ - ``length``
+
+ -
+ - Size in bytes of the plane (not its payload). This is set by the
+ driver based on the calls to
+ :ref:`VIDIOC_REQBUFS` and/or
+ :ref:`VIDIOC_CREATE_BUFS`.
+
+ - .. row 3
+
+ - union
+
+ - ``m``
+
+ -
+ -
+
+ - .. row 4
+
+ -
+ - __u32
+
+ - ``mem_offset``
+
+ - When the memory type in the containing struct
+ :ref:`v4l2_buffer <v4l2-buffer>` is ``V4L2_MEMORY_MMAP``, this
+ is the value that should be passed to :ref:`mmap() <func-mmap>`,
+ similar to the ``offset`` field in struct
+ :ref:`v4l2_buffer <v4l2-buffer>`.
+
+ - .. row 5
+
+ -
+ - unsigned long
+
+ - ``userptr``
+
+ - When the memory type in the containing struct
+ :ref:`v4l2_buffer <v4l2-buffer>` is ``V4L2_MEMORY_USERPTR``,
+ this is a userspace pointer to the memory allocated for this plane
+ by an application.
+
+ - .. row 6
+
+ -
+ - int
+
+ - ``fd``
+
+ - When the memory type in the containing struct
+ :ref:`v4l2_buffer <v4l2-buffer>` is ``V4L2_MEMORY_DMABUF``,
+ this is a file descriptor associated with a DMABUF buffer, similar
+ to the ``fd`` field in struct :ref:`v4l2_buffer <v4l2-buffer>`.
+
+ - .. row 7
+
+ - __u32
+
+ - ``data_offset``
+
+ -
+ - Offset in bytes to video data in the plane. Drivers must set this
+ field when ``type`` refers to a capture stream, applications when
+ it refers to an output stream. Note that data_offset is included
+ in ``bytesused``. So the size of the image in the plane is
+ ``bytesused``-``data_offset`` at offset ``data_offset`` from the
+ start of the plane.
+
+ - .. row 8
+
+ - __u32
+
+ - ``reserved[11]``
+
+ -
+ - Reserved for future use. Should be zeroed by drivers and
+ applications.
+
+
+
+.. _v4l2-buf-type:
+
+enum v4l2_buf_type
+==================
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_BUF_TYPE_VIDEO_CAPTURE``
+
+ - 1
+
+ - Buffer of a single-planar video capture stream, see
+ :ref:`capture`.
+
+ - .. row 2
+
+ - ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``
+
+ - 9
+
+ - Buffer of a multi-planar video capture stream, see
+ :ref:`capture`.
+
+ - .. row 3
+
+ - ``V4L2_BUF_TYPE_VIDEO_OUTPUT``
+
+ - 2
+
+ - Buffer of a single-planar video output stream, see
+ :ref:`output`.
+
+ - .. row 4
+
+ - ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``
+
+ - 10
+
+ - Buffer of a multi-planar video output stream, see :ref:`output`.
+
+ - .. row 5
+
+ - ``V4L2_BUF_TYPE_VIDEO_OVERLAY``
+
+ - 3
+
+ - Buffer for video overlay, see :ref:`overlay`.
+
+ - .. row 6
+
+ - ``V4L2_BUF_TYPE_VBI_CAPTURE``
+
+ - 4
+
+ - Buffer of a raw VBI capture stream, see :ref:`raw-vbi`.
+
+ - .. row 7
+
+ - ``V4L2_BUF_TYPE_VBI_OUTPUT``
+
+ - 5
+
+ - Buffer of a raw VBI output stream, see :ref:`raw-vbi`.
+
+ - .. row 8
+
+ - ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE``
+
+ - 6
+
+ - Buffer of a sliced VBI capture stream, see :ref:`sliced`.
+
+ - .. row 9
+
+ - ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT``
+
+ - 7
+
+ - Buffer of a sliced VBI output stream, see :ref:`sliced`.
+
+ - .. row 10
+
+ - ``V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY``
+
+ - 8
+
+ - Buffer for video output overlay (OSD), see :ref:`osd`.
+
+ - .. row 11
+
+ - ``V4L2_BUF_TYPE_SDR_CAPTURE``
+
+ - 11
+
+ - Buffer for Software Defined Radio (SDR) capture stream, see
+ :ref:`sdr`.
+
+ - .. row 12
+
+ - ``V4L2_BUF_TYPE_SDR_OUTPUT``
+
+ - 12
+
+ - Buffer for Software Defined Radio (SDR) output stream, see
+ :ref:`sdr`.
+
+
+
+.. _buffer-flags:
+
+Buffer Flags
+============
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_BUF_FLAG_MAPPED``
+
+ - 0x00000001
+
+ - The buffer resides in device memory and has been mapped into the
+ application's address space, see :ref:`mmap` for details.
+ Drivers set or clear this flag when the
+ :ref:`VIDIOC_QUERYBUF`,
+ :ref:`VIDIOC_QBUF` or
+ :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called. Set by the
+ driver.
+
+ - .. row 2
+
+ - ``V4L2_BUF_FLAG_QUEUED``
+
+ - 0x00000002
+
+ - Internally drivers maintain two buffer queues, an incoming and
+ outgoing queue. When this flag is set, the buffer is currently on
+ the incoming queue. It automatically moves to the outgoing queue
+ after the buffer has been filled (capture devices) or displayed
+ (output devices). Drivers set or clear this flag when the
+ ``VIDIOC_QUERYBUF`` ioctl is called. After (successful) calling
+ the ``VIDIOC_QBUF``\ ioctl it is always set and after
+ ``VIDIOC_DQBUF`` always cleared.
+
+ - .. row 3
+
+ - ``V4L2_BUF_FLAG_DONE``
+
+ - 0x00000004
+
+ - When this flag is set, the buffer is currently on the outgoing
+ queue, ready to be dequeued from the driver. Drivers set or clear
+ this flag when the ``VIDIOC_QUERYBUF`` ioctl is called. After
+ calling the ``VIDIOC_QBUF`` or ``VIDIOC_DQBUF`` it is always
+ cleared. Of course a buffer cannot be on both queues at the same
+ time, the ``V4L2_BUF_FLAG_QUEUED`` and ``V4L2_BUF_FLAG_DONE`` flag
+ are mutually exclusive. They can be both cleared however, then the
+ buffer is in "dequeued" state, in the application domain so to
+ say.
+
+ - .. row 4
+
+ - ``V4L2_BUF_FLAG_ERROR``
+
+ - 0x00000040
+
+ - When this flag is set, the buffer has been dequeued successfully,
+ although the data might have been corrupted. This is recoverable,
+ streaming may continue as normal and the buffer may be reused
+ normally. Drivers set this flag when the ``VIDIOC_DQBUF`` ioctl is
+ called.
+
+ - .. row 5
+
+ - ``V4L2_BUF_FLAG_KEYFRAME``
+
+ - 0x00000008
+
+ - Drivers set or clear this flag when calling the ``VIDIOC_DQBUF``
+ ioctl. It may be set by video capture devices when the buffer
+ contains a compressed image which is a key frame (or field), i. e.
+ can be decompressed on its own. Also known as an I-frame.
+ Applications can set this bit when ``type`` refers to an output
+ stream.
+
+ - .. row 6
+
+ - ``V4L2_BUF_FLAG_PFRAME``
+
+ - 0x00000010
+
+ - Similar to ``V4L2_BUF_FLAG_KEYFRAME`` this flags predicted frames
+ or fields which contain only differences to a previous key frame.
+ Applications can set this bit when ``type`` refers to an output
+ stream.
+
+ - .. row 7
+
+ - ``V4L2_BUF_FLAG_BFRAME``
+
+ - 0x00000020
+
+ - Similar to ``V4L2_BUF_FLAG_KEYFRAME`` this flags a bi-directional
+ predicted frame or field which contains only the differences
+ between the current frame and both the preceding and following key
+ frames to specify its content. Applications can set this bit when
+ ``type`` refers to an output stream.
+
+ - .. row 8
+
+ - ``V4L2_BUF_FLAG_TIMECODE``
+
+ - 0x00000100
+
+ - The ``timecode`` field is valid. Drivers set or clear this flag
+ when the ``VIDIOC_DQBUF`` ioctl is called. Applications can set
+ this bit and the corresponding ``timecode`` structure when
+ ``type`` refers to an output stream.
+
+ - .. row 9
+
+ - ``V4L2_BUF_FLAG_PREPARED``
+
+ - 0x00000400
+
+ - The buffer has been prepared for I/O and can be queued by the
+ application. Drivers set or clear this flag when the
+ :ref:`VIDIOC_QUERYBUF`,
+ :ref:`VIDIOC_PREPARE_BUF <VIDIOC_QBUF>`,
+ :ref:`VIDIOC_QBUF` or
+ :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called.
+
+ - .. row 10
+
+ - ``V4L2_BUF_FLAG_NO_CACHE_INVALIDATE``
+
+ - 0x00000800
+
+ - Caches do not have to be invalidated for this buffer. Typically
+ applications shall use this flag if the data captured in the
+ buffer is not going to be touched by the CPU, instead the buffer
+ will, probably, be passed on to a DMA-capable hardware unit for
+ further processing or output.
+
+ - .. row 11
+
+ - ``V4L2_BUF_FLAG_NO_CACHE_CLEAN``
+
+ - 0x00001000
+
+ - Caches do not have to be cleaned for this buffer. Typically
+ applications shall use this flag for output buffers if the data in
+ this buffer has not been created by the CPU but by some
+ DMA-capable unit, in which case caches have not been used.
+
+ - .. row 12
+
+ - ``V4L2_BUF_FLAG_LAST``
+
+ - 0x00100000
+
+ - Last buffer produced by the hardware. mem2mem codec drivers set
+ this flag on the capture queue for the last buffer when the
+ :ref:`VIDIOC_QUERYBUF` or
+ :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called. Due to
+ hardware limitations, the last buffer may be empty. In this case
+ the driver will set the ``bytesused`` field to 0, regardless of
+ the format. Any Any subsequent call to the
+ :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will not block anymore,
+ but return an ``EPIPE`` error code.
+
+ - .. row 13
+
+ - ``V4L2_BUF_FLAG_TIMESTAMP_MASK``
+
+ - 0x0000e000
+
+ - Mask for timestamp types below. To test the timestamp type, mask
+ out bits not belonging to timestamp type by performing a logical
+ and operation with buffer flags and timestamp mask.
+
+ - .. row 14
+
+ - ``V4L2_BUF_FLAG_TIMESTAMP_UNKNOWN``
+
+ - 0x00000000
+
+ - Unknown timestamp type. This type is used by drivers before Linux
+ 3.9 and may be either monotonic (see below) or realtime (wall
+ clock). Monotonic clock has been favoured in embedded systems
+ whereas most of the drivers use the realtime clock. Either kinds
+ of timestamps are available in user space via
+ :c:func:`clock_gettime(2)` using clock IDs ``CLOCK_MONOTONIC``
+ and ``CLOCK_REALTIME``, respectively.
+
+ - .. row 15
+
+ - ``V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC``
+
+ - 0x00002000
+
+ - The buffer timestamp has been taken from the ``CLOCK_MONOTONIC``
+ clock. To access the same clock outside V4L2, use
+ :c:func:`clock_gettime(2)`.
+
+ - .. row 16
+
+ - ``V4L2_BUF_FLAG_TIMESTAMP_COPY``
+
+ - 0x00004000
+
+ - The CAPTURE buffer timestamp has been taken from the corresponding
+ OUTPUT buffer. This flag applies only to mem2mem devices.
+
+ - .. row 17
+
+ - ``V4L2_BUF_FLAG_TSTAMP_SRC_MASK``
+
+ - 0x00070000
+
+ - Mask for timestamp sources below. The timestamp source defines the
+ point of time the timestamp is taken in relation to the frame.
+ Logical 'and' operation between the ``flags`` field and
+ ``V4L2_BUF_FLAG_TSTAMP_SRC_MASK`` produces the value of the
+ timestamp source. Applications must set the timestamp source when
+ ``type`` refers to an output stream and
+ ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` is set.
+
+ - .. row 18
+
+ - ``V4L2_BUF_FLAG_TSTAMP_SRC_EOF``
+
+ - 0x00000000
+
+ - End Of Frame. The buffer timestamp has been taken when the last
+ pixel of the frame has been received or the last pixel of the
+ frame has been transmitted. In practice, software generated
+ timestamps will typically be read from the clock a small amount of
+ time after the last pixel has been received or transmitten,
+ depending on the system and other activity in it.
+
+ - .. row 19
+
+ - ``V4L2_BUF_FLAG_TSTAMP_SRC_SOE``
+
+ - 0x00010000
+
+ - Start Of Exposure. The buffer timestamp has been taken when the
+ exposure of the frame has begun. This is only valid for the
+ ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` buffer type.
+
+
+
+.. _v4l2-memory:
+
+enum v4l2_memory
+================
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_MEMORY_MMAP``
+
+ - 1
+
+ - The buffer is used for :ref:`memory mapping <mmap>` I/O.
+
+ - .. row 2
+
+ - ``V4L2_MEMORY_USERPTR``
+
+ - 2
+
+ - The buffer is used for :ref:`user pointer <userp>` I/O.
+
+ - .. row 3
+
+ - ``V4L2_MEMORY_OVERLAY``
+
+ - 3
+
+ - [to do]
+
+ - .. row 4
+
+ - ``V4L2_MEMORY_DMABUF``
+
+ - 4
+
+ - The buffer is used for :ref:`DMA shared buffer <dmabuf>` I/O.
+
+
+
+Timecodes
+=========
+
+The :ref:`struct v4l2_timecode <v4l2-timecode>` structure is designed to hold a
+:ref:`smpte12m` or similar timecode. (struct
+:c:type:`struct timeval` timestamps are stored in struct
+:ref:`v4l2_buffer <v4l2-buffer>` field ``timestamp``.)
+
+
+.. _v4l2-timecode:
+
+struct v4l2_timecode
+--------------------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``type``
+
+ - Frame rate the timecodes are based on, see :ref:`timecode-type`.
+
+ - .. row 2
+
+ - __u32
+
+ - ``flags``
+
+ - Timecode flags, see :ref:`timecode-flags`.
+
+ - .. row 3
+
+ - __u8
+
+ - ``frames``
+
+ - Frame count, 0 ... 23/24/29/49/59, depending on the type of
+ timecode.
+
+ - .. row 4
+
+ - __u8
+
+ - ``seconds``
+
+ - Seconds count, 0 ... 59. This is a binary, not BCD number.
+
+ - .. row 5
+
+ - __u8
+
+ - ``minutes``
+
+ - Minutes count, 0 ... 59. This is a binary, not BCD number.
+
+ - .. row 6
+
+ - __u8
+
+ - ``hours``
+
+ - Hours count, 0 ... 29. This is a binary, not BCD number.
+
+ - .. row 7
+
+ - __u8
+
+ - ``userbits``\ [4]
+
+ - The "user group" bits from the timecode.
+
+
+
+.. _timecode-type:
+
+Timecode Types
+--------------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_TC_TYPE_24FPS``
+
+ - 1
+
+ - 24 frames per second, i. e. film.
+
+ - .. row 2
+
+ - ``V4L2_TC_TYPE_25FPS``
+
+ - 2
+
+ - 25 frames per second, i. e. PAL or SECAM video.
+
+ - .. row 3
+
+ - ``V4L2_TC_TYPE_30FPS``
+
+ - 3
+
+ - 30 frames per second, i. e. NTSC video.
+
+ - .. row 4
+
+ - ``V4L2_TC_TYPE_50FPS``
+
+ - 4
+
+ -
+
+ - .. row 5
+
+ - ``V4L2_TC_TYPE_60FPS``
+
+ - 5
+
+ -
+
+
+
+.. _timecode-flags:
+
+Timecode Flags
+--------------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_TC_FLAG_DROPFRAME``
+
+ - 0x0001
+
+ - Indicates "drop frame" semantics for counting frames in 29.97 fps
+ material. When set, frame numbers 0 and 1 at the start of each
+ minute, except minutes 0, 10, 20, 30, 40, 50 are omitted from the
+ count.
+
+ - .. row 2
+
+ - ``V4L2_TC_FLAG_COLORFRAME``
+
+ - 0x0002
+
+ - The "color frame" flag.
+
+ - .. row 3
+
+ - ``V4L2_TC_USERBITS_field``
+
+ - 0x000C
+
+ - Field mask for the "binary group flags".
+
+ - .. row 4
+
+ - ``V4L2_TC_USERBITS_USERDEFINED``
+
+ - 0x0000
+
+ - Unspecified format.
+
+ - .. row 5
+
+ - ``V4L2_TC_USERBITS_8BITCHARS``
+
+ - 0x0008
+
+ - 8-bit ISO characters.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _capture-example:
+
+*********************
+Video Capture Example
+*********************
+
+
+.. toctree::
+ :maxdepth: 1
+
+ capture.c
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+file: media/v4l/capture.c
+=========================
+
+.. code-block:: c
+
+ /*
+ * V4L2 video capture example
+ *
+ * This program can be used and distributed without restrictions.
+ *
+ * This program is provided with the V4L2 API
+ * see https://linuxtv.org/docs.php for more information
+ */
+
+ #include <stdio.h>
+ #include <stdlib.h>
+ #include <string.h>
+ #include <assert.h>
+
+ #include <getopt.h> /* getopt_long() */
+
+ #include <fcntl.h> /* low-level i/o */
+ #include <unistd.h>
+ #include <errno.h>
+ #include <sys/stat.h>
+ #include <sys/types.h>
+ #include <sys/time.h>
+ #include <sys/mman.h>
+ #include <sys/ioctl.h>
+
+ #include <linux/videodev2.h>
+
+ #define CLEAR(x) memset(&(x), 0, sizeof(x))
+
+ enum io_method {
+ IO_METHOD_READ,
+ IO_METHOD_MMAP,
+ IO_METHOD_USERPTR,
+ };
+
+ struct buffer {
+ void *start;
+ size_t length;
+ };
+
+ static char *dev_name;
+ static enum io_method io = IO_METHOD_MMAP;
+ static int fd = -1;
+ struct buffer *buffers;
+ static unsigned int n_buffers;
+ static int out_buf;
+ static int force_format;
+ static int frame_count = 70;
+
+ static void errno_exit(const char *s)
+ {
+ fprintf(stderr, "%s error %d, %s\\n", s, errno, strerror(errno));
+ exit(EXIT_FAILURE);
+ }
+
+ static int xioctl(int fh, int request, void *arg)
+ {
+ int r;
+
+ do {
+ r = ioctl(fh, request, arg);
+ } while (-1 == r && EINTR == errno);
+
+ return r;
+ }
+
+ static void process_image(const void *p, int size)
+ {
+ if (out_buf)
+ fwrite(p, size, 1, stdout);
+
+ fflush(stderr);
+ fprintf(stderr, ".");
+ fflush(stdout);
+ }
+
+ static int read_frame(void)
+ {
+ struct v4l2_buffer buf;
+ unsigned int i;
+
+ switch (io) {
+ case IO_METHOD_READ:
+ if (-1 == read(fd, buffers[0].start, buffers[0].length)) {
+ switch (errno) {
+ case EAGAIN:
+ return 0;
+
+ case EIO:
+ /* Could ignore EIO, see spec. */
+
+ /* fall through */
+
+ default:
+ errno_exit("read");
+ }
+ }
+
+ process_image(buffers[0].start, buffers[0].length);
+ break;
+
+ case IO_METHOD_MMAP:
+ CLEAR(buf);
+
+ buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ buf.memory = V4L2_MEMORY_MMAP;
+
+ if (-1 == xioctl(fd, VIDIOC_DQBUF, &buf)) {
+ switch (errno) {
+ case EAGAIN:
+ return 0;
+
+ case EIO:
+ /* Could ignore EIO, see spec. */
+
+ /* fall through */
+
+ default:
+ errno_exit("VIDIOC_DQBUF");
+ }
+ }
+
+ assert(buf.index < n_buffers);
+
+ process_image(buffers[buf.index].start, buf.bytesused);
+
+ if (-1 == xioctl(fd, VIDIOC_QBUF, &buf))
+ errno_exit("VIDIOC_QBUF");
+ break;
+
+ case IO_METHOD_USERPTR:
+ CLEAR(buf);
+
+ buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ buf.memory = V4L2_MEMORY_USERPTR;
+
+ if (-1 == xioctl(fd, VIDIOC_DQBUF, &buf)) {
+ switch (errno) {
+ case EAGAIN:
+ return 0;
+
+ case EIO:
+ /* Could ignore EIO, see spec. */
+
+ /* fall through */
+
+ default:
+ errno_exit("VIDIOC_DQBUF");
+ }
+ }
+
+ for (i = 0; i < n_buffers; ++i)
+ if (buf.m.userptr == (unsigned long)buffers[i].start
+ && buf.length == buffers[i].length)
+ break;
+
+ assert(i < n_buffers);
+
+ process_image((void *)buf.m.userptr, buf.bytesused);
+
+ if (-1 == xioctl(fd, VIDIOC_QBUF, &buf))
+ errno_exit("VIDIOC_QBUF");
+ break;
+ }
+
+ return 1;
+ }
+
+ static void mainloop(void)
+ {
+ unsigned int count;
+
+ count = frame_count;
+
+ while (count-- > 0) {
+ for (;;) {
+ fd_set fds;
+ struct timeval tv;
+ int r;
+
+ FD_ZERO(&fds);
+ FD_SET(fd, &fds);
+
+ /* Timeout. */
+ tv.tv_sec = 2;
+ tv.tv_usec = 0;
+
+ r = select(fd + 1, &fds, NULL, NULL, &tv);
+
+ if (-1 == r) {
+ if (EINTR == errno)
+ continue;
+ errno_exit("select");
+ }
+
+ if (0 == r) {
+ fprintf(stderr, "select timeout\\n");
+ exit(EXIT_FAILURE);
+ }
+
+ if (read_frame())
+ break;
+ /* EAGAIN - continue select loop. */
+ }
+ }
+ }
+
+ static void stop_capturing(void)
+ {
+ enum v4l2_buf_type type;
+
+ switch (io) {
+ case IO_METHOD_READ:
+ /* Nothing to do. */
+ break;
+
+ case IO_METHOD_MMAP:
+ case IO_METHOD_USERPTR:
+ type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ if (-1 == xioctl(fd, VIDIOC_STREAMOFF, &type))
+ errno_exit("VIDIOC_STREAMOFF");
+ break;
+ }
+ }
+
+ static void start_capturing(void)
+ {
+ unsigned int i;
+ enum v4l2_buf_type type;
+
+ switch (io) {
+ case IO_METHOD_READ:
+ /* Nothing to do. */
+ break;
+
+ case IO_METHOD_MMAP:
+ for (i = 0; i < n_buffers; ++i) {
+ struct v4l2_buffer buf;
+
+ CLEAR(buf);
+ buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ buf.memory = V4L2_MEMORY_MMAP;
+ buf.index = i;
+
+ if (-1 == xioctl(fd, VIDIOC_QBUF, &buf))
+ errno_exit("VIDIOC_QBUF");
+ }
+ type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ if (-1 == xioctl(fd, VIDIOC_STREAMON, &type))
+ errno_exit("VIDIOC_STREAMON");
+ break;
+
+ case IO_METHOD_USERPTR:
+ for (i = 0; i < n_buffers; ++i) {
+ struct v4l2_buffer buf;
+
+ CLEAR(buf);
+ buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ buf.memory = V4L2_MEMORY_USERPTR;
+ buf.index = i;
+ buf.m.userptr = (unsigned long)buffers[i].start;
+ buf.length = buffers[i].length;
+
+ if (-1 == xioctl(fd, VIDIOC_QBUF, &buf))
+ errno_exit("VIDIOC_QBUF");
+ }
+ type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ if (-1 == xioctl(fd, VIDIOC_STREAMON, &type))
+ errno_exit("VIDIOC_STREAMON");
+ break;
+ }
+ }
+
+ static void uninit_device(void)
+ {
+ unsigned int i;
+
+ switch (io) {
+ case IO_METHOD_READ:
+ free(buffers[0].start);
+ break;
+
+ case IO_METHOD_MMAP:
+ for (i = 0; i < n_buffers; ++i)
+ if (-1 == munmap(buffers[i].start, buffers[i].length))
+ errno_exit("munmap");
+ break;
+
+ case IO_METHOD_USERPTR:
+ for (i = 0; i < n_buffers; ++i)
+ free(buffers[i].start);
+ break;
+ }
+
+ free(buffers);
+ }
+
+ static void init_read(unsigned int buffer_size)
+ {
+ buffers = calloc(1, sizeof(*buffers));
+
+ if (!buffers) {
+ fprintf(stderr, "Out of memory\\n");
+ exit(EXIT_FAILURE);
+ }
+
+ buffers[0].length = buffer_size;
+ buffers[0].start = malloc(buffer_size);
+
+ if (!buffers[0].start) {
+ fprintf(stderr, "Out of memory\\n");
+ exit(EXIT_FAILURE);
+ }
+ }
+
+ static void init_mmap(void)
+ {
+ struct v4l2_requestbuffers req;
+
+ CLEAR(req);
+
+ req.count = 4;
+ req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ req.memory = V4L2_MEMORY_MMAP;
+
+ if (-1 == xioctl(fd, VIDIOC_REQBUFS, &req)) {
+ if (EINVAL == errno) {
+ fprintf(stderr, "%s does not support "
+ "memory mappingn", dev_name);
+ exit(EXIT_FAILURE);
+ } else {
+ errno_exit("VIDIOC_REQBUFS");
+ }
+ }
+
+ if (req.count < 2) {
+ fprintf(stderr, "Insufficient buffer memory on %s\\n",
+ dev_name);
+ exit(EXIT_FAILURE);
+ }
+
+ buffers = calloc(req.count, sizeof(*buffers));
+
+ if (!buffers) {
+ fprintf(stderr, "Out of memory\\n");
+ exit(EXIT_FAILURE);
+ }
+
+ for (n_buffers = 0; n_buffers < req.count; ++n_buffers) {
+ struct v4l2_buffer buf;
+
+ CLEAR(buf);
+
+ buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ buf.memory = V4L2_MEMORY_MMAP;
+ buf.index = n_buffers;
+
+ if (-1 == xioctl(fd, VIDIOC_QUERYBUF, &buf))
+ errno_exit("VIDIOC_QUERYBUF");
+
+ buffers[n_buffers].length = buf.length;
+ buffers[n_buffers].start =
+ mmap(NULL /* start anywhere */,
+ buf.length,
+ PROT_READ | PROT_WRITE /* required */,
+ MAP_SHARED /* recommended */,
+ fd, buf.m.offset);
+
+ if (MAP_FAILED == buffers[n_buffers].start)
+ errno_exit("mmap");
+ }
+ }
+
+ static void init_userp(unsigned int buffer_size)
+ {
+ struct v4l2_requestbuffers req;
+
+ CLEAR(req);
+
+ req.count = 4;
+ req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ req.memory = V4L2_MEMORY_USERPTR;
+
+ if (-1 == xioctl(fd, VIDIOC_REQBUFS, &req)) {
+ if (EINVAL == errno) {
+ fprintf(stderr, "%s does not support "
+ "user pointer i/on", dev_name);
+ exit(EXIT_FAILURE);
+ } else {
+ errno_exit("VIDIOC_REQBUFS");
+ }
+ }
+
+ buffers = calloc(4, sizeof(*buffers));
+
+ if (!buffers) {
+ fprintf(stderr, "Out of memory\\n");
+ exit(EXIT_FAILURE);
+ }
+
+ for (n_buffers = 0; n_buffers < 4; ++n_buffers) {
+ buffers[n_buffers].length = buffer_size;
+ buffers[n_buffers].start = malloc(buffer_size);
+
+ if (!buffers[n_buffers].start) {
+ fprintf(stderr, "Out of memory\\n");
+ exit(EXIT_FAILURE);
+ }
+ }
+ }
+
+ static void init_device(void)
+ {
+ struct v4l2_capability cap;
+ struct v4l2_cropcap cropcap;
+ struct v4l2_crop crop;
+ struct v4l2_format fmt;
+ unsigned int min;
+
+ if (-1 == xioctl(fd, VIDIOC_QUERYCAP, &cap)) {
+ if (EINVAL == errno) {
+ fprintf(stderr, "%s is no V4L2 device\\n",
+ dev_name);
+ exit(EXIT_FAILURE);
+ } else {
+ errno_exit("VIDIOC_QUERYCAP");
+ }
+ }
+
+ if (!(cap.capabilities & V4L2_CAP_VIDEO_CAPTURE)) {
+ fprintf(stderr, "%s is no video capture device\\n",
+ dev_name);
+ exit(EXIT_FAILURE);
+ }
+
+ switch (io) {
+ case IO_METHOD_READ:
+ if (!(cap.capabilities & V4L2_CAP_READWRITE)) {
+ fprintf(stderr, "%s does not support read i/o\\n",
+ dev_name);
+ exit(EXIT_FAILURE);
+ }
+ break;
+
+ case IO_METHOD_MMAP:
+ case IO_METHOD_USERPTR:
+ if (!(cap.capabilities & V4L2_CAP_STREAMING)) {
+ fprintf(stderr, "%s does not support streaming i/o\\n",
+ dev_name);
+ exit(EXIT_FAILURE);
+ }
+ break;
+ }
+
+
+ /* Select video input, video standard and tune here. */
+
+
+ CLEAR(cropcap);
+
+ cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+
+ if (0 == xioctl(fd, VIDIOC_CROPCAP, &cropcap)) {
+ crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ crop.c = cropcap.defrect; /* reset to default */
+
+ if (-1 == xioctl(fd, VIDIOC_S_CROP, &crop)) {
+ switch (errno) {
+ case EINVAL:
+ /* Cropping not supported. */
+ break;
+ default:
+ /* Errors ignored. */
+ break;
+ }
+ }
+ } else {
+ /* Errors ignored. */
+ }
+
+
+ CLEAR(fmt);
+
+ fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ if (force_format) {
+ fmt.fmt.pix.width = 640;
+ fmt.fmt.pix.height = 480;
+ fmt.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV;
+ fmt.fmt.pix.field = V4L2_FIELD_INTERLACED;
+
+ if (-1 == xioctl(fd, VIDIOC_S_FMT, &fmt))
+ errno_exit("VIDIOC_S_FMT");
+
+ /* Note VIDIOC_S_FMT may change width and height. */
+ } else {
+ /* Preserve original settings as set by v4l2-ctl for example */
+ if (-1 == xioctl(fd, VIDIOC_G_FMT, &fmt))
+ errno_exit("VIDIOC_G_FMT");
+ }
+
+ /* Buggy driver paranoia. */
+ min = fmt.fmt.pix.width * 2;
+ if (fmt.fmt.pix.bytesperline < min)
+ fmt.fmt.pix.bytesperline = min;
+ min = fmt.fmt.pix.bytesperline * fmt.fmt.pix.height;
+ if (fmt.fmt.pix.sizeimage < min)
+ fmt.fmt.pix.sizeimage = min;
+
+ switch (io) {
+ case IO_METHOD_READ:
+ init_read(fmt.fmt.pix.sizeimage);
+ break;
+
+ case IO_METHOD_MMAP:
+ init_mmap();
+ break;
+
+ case IO_METHOD_USERPTR:
+ init_userp(fmt.fmt.pix.sizeimage);
+ break;
+ }
+ }
+
+ static void close_device(void)
+ {
+ if (-1 == close(fd))
+ errno_exit("close");
+
+ fd = -1;
+ }
+
+ static void open_device(void)
+ {
+ struct stat st;
+
+ if (-1 == stat(dev_name, &st)) {
+ fprintf(stderr, "Cannot identify '%s': %d, %s\\n",
+ dev_name, errno, strerror(errno));
+ exit(EXIT_FAILURE);
+ }
+
+ if (!S_ISCHR(st.st_mode)) {
+ fprintf(stderr, "%s is no devicen", dev_name);
+ exit(EXIT_FAILURE);
+ }
+
+ fd = open(dev_name, O_RDWR /* required */ | O_NONBLOCK, 0);
+
+ if (-1 == fd) {
+ fprintf(stderr, "Cannot open '%s': %d, %s\\n",
+ dev_name, errno, strerror(errno));
+ exit(EXIT_FAILURE);
+ }
+ }
+
+ static void usage(FILE *fp, int argc, char **argv)
+ {
+ fprintf(fp,
+ "Usage: %s [options]\\n\\n"
+ "Version 1.3\\n"
+ "Options:\\n"
+ "-d | --device name Video device name [%s]n"
+ "-h | --help Print this messagen"
+ "-m | --mmap Use memory mapped buffers [default]n"
+ "-r | --read Use read() callsn"
+ "-u | --userp Use application allocated buffersn"
+ "-o | --output Outputs stream to stdoutn"
+ "-f | --format Force format to 640x480 YUYVn"
+ "-c | --count Number of frames to grab [%i]n"
+ "",
+ argv[0], dev_name, frame_count);
+ }
+
+ static const char short_options[] = "d:hmruofc:";
+
+ static const struct option
+ long_options[] = {
+ { "device", required_argument, NULL, 'd' },
+ { "help", no_argument, NULL, 'h' },
+ { "mmap", no_argument, NULL, 'm' },
+ { "read", no_argument, NULL, 'r' },
+ { "userp", no_argument, NULL, 'u' },
+ { "output", no_argument, NULL, 'o' },
+ { "format", no_argument, NULL, 'f' },
+ { "count", required_argument, NULL, 'c' },
+ { 0, 0, 0, 0 }
+ };
+
+ int main(int argc, char **argv)
+ {
+ dev_name = "/dev/video0";
+
+ for (;;) {
+ int idx;
+ int c;
+
+ c = getopt_long(argc, argv,
+ short_options, long_options, &idx);
+
+ if (-1 == c)
+ break;
+
+ switch (c) {
+ case 0: /* getopt_long() flag */
+ break;
+
+ case 'd':
+ dev_name = optarg;
+ break;
+
+ case 'h':
+ usage(stdout, argc, argv);
+ exit(EXIT_SUCCESS);
+
+ case 'm':
+ io = IO_METHOD_MMAP;
+ break;
+
+ case 'r':
+ io = IO_METHOD_READ;
+ break;
+
+ case 'u':
+ io = IO_METHOD_USERPTR;
+ break;
+
+ case 'o':
+ out_buf++;
+ break;
+
+ case 'f':
+ force_format++;
+ break;
+
+ case 'c':
+ errno = 0;
+ frame_count = strtol(optarg, NULL, 0);
+ if (errno)
+ errno_exit(optarg);
+ break;
+
+ default:
+ usage(stderr, argc, argv);
+ exit(EXIT_FAILURE);
+ }
+ }
+
+ open_device();
+ init_device();
+ start_capturing();
+ mainloop();
+ stop_capturing();
+ uninit_device();
+ close_device();
+ fprintf(stderr, "\\n");
+ return 0;
+ }
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _colorspaces:
+
+***********
+Colorspaces
+***********
+
+'Color' is a very complex concept and depends on physics, chemistry and
+biology. Just because you have three numbers that describe the 'red',
+'green' and 'blue' components of the color of a pixel does not mean that
+you can accurately display that color. A colorspace defines what it
+actually *means* to have an RGB value of e.g. (255, 0, 0). That is,
+which color should be reproduced on the screen in a perfectly calibrated
+environment.
+
+In order to do that we first need to have a good definition of color,
+i.e. some way to uniquely and unambiguously define a color so that
+someone else can reproduce it. Human color vision is trichromatic since
+the human eye has color receptors that are sensitive to three different
+wavelengths of light. Hence the need to use three numbers to describe
+color. Be glad you are not a mantis shrimp as those are sensitive to 12
+different wavelengths, so instead of RGB we would be using the
+ABCDEFGHIJKL colorspace...
+
+Color exists only in the eye and brain and is the result of how strongly
+color receptors are stimulated. This is based on the Spectral Power
+Distribution (SPD) which is a graph showing the intensity (radiant
+power) of the light at wavelengths covering the visible spectrum as it
+enters the eye. The science of colorimetry is about the relationship
+between the SPD and color as perceived by the human brain.
+
+Since the human eye has only three color receptors it is perfectly
+possible that different SPDs will result in the same stimulation of
+those receptors and are perceived as the same color, even though the SPD
+of the light is different.
+
+In the 1920s experiments were devised to determine the relationship
+between SPDs and the perceived color and that resulted in the CIE 1931
+standard that defines spectral weighting functions that model the
+perception of color. Specifically that standard defines functions that
+can take an SPD and calculate the stimulus for each color receptor.
+After some further mathematical transforms these stimuli are known as
+the *CIE XYZ tristimulus* values and these X, Y and Z values describe a
+color as perceived by a human unambiguously. These X, Y and Z values are
+all in the range [0…1].
+
+The Y value in the CIE XYZ colorspace corresponds to luminance. Often
+the CIE XYZ colorspace is transformed to the normalized CIE xyY
+colorspace:
+
+x = X / (X + Y + Z)
+
+y = Y / (X + Y + Z)
+
+The x and y values are the chromaticity coordinates and can be used to
+define a color without the luminance component Y. It is very confusing
+to have such similar names for these colorspaces. Just be aware that if
+colors are specified with lower case 'x' and 'y', then the CIE xyY
+colorspace is used. Upper case 'X' and 'Y' refer to the CIE XYZ
+colorspace. Also, y has nothing to do with luminance. Together x and y
+specify a color, and Y the luminance. That is really all you need to
+remember from a practical point of view. At the end of this section you
+will find reading resources that go into much more detail if you are
+interested.
+
+A monitor or TV will reproduce colors by emitting light at three
+different wavelengths, the combination of which will stimulate the color
+receptors in the eye and thus cause the perception of color.
+Historically these wavelengths were defined by the red, green and blue
+phosphors used in the displays. These *color primaries* are part of what
+defines a colorspace.
+
+Different display devices will have different primaries and some
+primaries are more suitable for some display technologies than others.
+This has resulted in a variety of colorspaces that are used for
+different display technologies or uses. To define a colorspace you need
+to define the three color primaries (these are typically defined as x, y
+chromaticity coordinates from the CIE xyY colorspace) but also the white
+reference: that is the color obtained when all three primaries are at
+maximum power. This determines the relative power or energy of the
+primaries. This is usually chosen to be close to daylight which has been
+defined as the CIE D65 Illuminant.
+
+To recapitulate: the CIE XYZ colorspace uniquely identifies colors.
+Other colorspaces are defined by three chromaticity coordinates defined
+in the CIE xyY colorspace. Based on those a 3x3 matrix can be
+constructed that transforms CIE XYZ colors to colors in the new
+colorspace.
+
+Both the CIE XYZ and the RGB colorspace that are derived from the
+specific chromaticity primaries are linear colorspaces. But neither the
+eye, nor display technology is linear. Doubling the values of all
+components in the linear colorspace will not be perceived as twice the
+intensity of the color. So each colorspace also defines a transfer
+function that takes a linear color component value and transforms it to
+the non-linear component value, which is a closer match to the
+non-linear performance of both the eye and displays. Linear component
+values are denoted RGB, non-linear are denoted as R'G'B'. In general
+colors used in graphics are all R'G'B', except in openGL which uses
+linear RGB. Special care should be taken when dealing with openGL to
+provide linear RGB colors or to use the built-in openGL support to apply
+the inverse transfer function.
+
+The final piece that defines a colorspace is a function that transforms
+non-linear R'G'B' to non-linear Y'CbCr. This function is determined by
+the so-called luma coefficients. There may be multiple possible Y'CbCr
+encodings allowed for the same colorspace. Many encodings of color
+prefer to use luma (Y') and chroma (CbCr) instead of R'G'B'. Since the
+human eye is more sensitive to differences in luminance than in color
+this encoding allows one to reduce the amount of color information
+compared to the luma data. Note that the luma (Y') is unrelated to the Y
+in the CIE XYZ colorspace. Also note that Y'CbCr is often called YCbCr
+or YUV even though these are strictly speaking wrong.
+
+Sometimes people confuse Y'CbCr as being a colorspace. This is not
+correct, it is just an encoding of an R'G'B' color into luma and chroma
+values. The underlying colorspace that is associated with the R'G'B'
+color is also associated with the Y'CbCr color.
+
+The final step is how the RGB, R'G'B' or Y'CbCr values are quantized.
+The CIE XYZ colorspace where X, Y and Z are in the range [0…1] describes
+all colors that humans can perceive, but the transform to another
+colorspace will produce colors that are outside the [0…1] range. Once
+clamped to the [0…1] range those colors can no longer be reproduced in
+that colorspace. This clamping is what reduces the extent or gamut of
+the colorspace. How the range of [0…1] is translated to integer values
+in the range of [0…255] (or higher, depending on the color depth) is
+called the quantization. This is *not* part of the colorspace
+definition. In practice RGB or R'G'B' values are full range, i.e. they
+use the full [0…255] range. Y'CbCr values on the other hand are limited
+range with Y' using [16…235] and Cb and Cr using [16…240].
+
+Unfortunately, in some cases limited range RGB is also used where the
+components use the range [16…235]. And full range Y'CbCr also exists
+using the [0…255] range.
+
+In order to correctly interpret a color you need to know the
+quantization range, whether it is R'G'B' or Y'CbCr, the used Y'CbCr
+encoding and the colorspace. From that information you can calculate the
+corresponding CIE XYZ color and map that again to whatever colorspace
+your display device uses.
+
+The colorspace definition itself consists of the three chromaticity
+primaries, the white reference chromaticity, a transfer function and the
+luma coefficients needed to transform R'G'B' to Y'CbCr. While some
+colorspace standards correctly define all four, quite often the
+colorspace standard only defines some, and you have to rely on other
+standards for the missing pieces. The fact that colorspaces are often a
+mix of different standards also led to very confusing naming conventions
+where the name of a standard was used to name a colorspace when in fact
+that standard was part of various other colorspaces as well.
+
+If you want to read more about colors and colorspaces, then the
+following resources are useful: :ref:`poynton` is a good practical
+book for video engineers, :ref:`colimg` has a much broader scope and
+describes many more aspects of color (physics, chemistry, biology,
+etc.). The
+`http://www.brucelindbloom.com <http://www.brucelindbloom.com>`__
+website is an excellent resource, especially with respect to the
+mathematics behind colorspace conversions. The wikipedia
+`CIE 1931 colorspace <http://en.wikipedia.org/wiki/CIE_1931_color_space#CIE_xy_chromaticity_diagram_and_the_CIE_xyY_color_space>`__
+article is also very useful.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _common-defs:
+
+******************************************************
+Common definitions for V4L2 and V4L2 subdev interfaces
+******************************************************
+
+
+.. toctree::
+ :maxdepth: 1
+
+ selections-common
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _common:
+
+###################
+Common API Elements
+###################
+Programming a V4L2 device consists of these steps:
+
+- Opening the device
+
+- Changing device properties, selecting a video and audio input, video
+ standard, picture brightness a. o.
+
+- Negotiating a data format
+
+- Negotiating an input/output method
+
+- The actual input/output loop
+
+- Closing the device
+
+In practice most steps are optional and can be executed out of order. It
+depends on the V4L2 device type, you can read about the details in
+:ref:`devices`. In this chapter we will discuss the basic concepts
+applicable to all devices.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ open
+ querycap
+ app-pri
+ video
+ audio
+ tuner
+ standard
+ dv-timings
+ control
+ extended-controls
+ format
+ planar-apis
+ crop
+ selection-api
+ streaming-par
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _compat:
+
+*******
+Changes
+*******
+
+The following chapters document the evolution of the V4L2 API, errata or
+extensions. They are also intended to help application and driver
+writers to port or update their code.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ diff-v4l
+ hist-v4l2
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _control:
+
+*************
+User Controls
+*************
+
+Devices typically have a number of user-settable controls such as
+brightness, saturation and so on, which would be presented to the user
+on a graphical user interface. But, different devices will have
+different controls available, and furthermore, the range of possible
+values, and the default value will vary from device to device. The
+control ioctls provide the information and a mechanism to create a nice
+user interface for these controls that will work correctly with any
+device.
+
+All controls are accessed using an ID value. V4L2 defines several IDs
+for specific purposes. Drivers can also implement their own custom
+controls using ``V4L2_CID_PRIVATE_BASE`` [1]_ and higher values. The
+pre-defined control IDs have the prefix ``V4L2_CID_``, and are listed in
+:ref:`control-id`. The ID is used when querying the attributes of a
+control, and when getting or setting the current value.
+
+Generally applications should present controls to the user without
+assumptions about their purpose. Each control comes with a name string
+the user is supposed to understand. When the purpose is non-intuitive
+the driver writer should provide a user manual, a user interface plug-in
+or a driver specific panel application. Predefined IDs were introduced
+to change a few controls programmatically, for example to mute a device
+during a channel switch.
+
+Drivers may enumerate different controls after switching the current
+video input or output, tuner or modulator, or audio input or output.
+Different in the sense of other bounds, another default and current
+value, step size or other menu items. A control with a certain *custom*
+ID can also change name and type.
+
+If a control is not applicable to the current configuration of the
+device (for example, it doesn't apply to the current video input)
+drivers set the ``V4L2_CTRL_FLAG_INACTIVE`` flag.
+
+Control values are stored globally, they do not change when switching
+except to stay within the reported bounds. They also do not change e. g.
+when the device is opened or closed, when the tuner radio frequency is
+changed or generally never without application request.
+
+V4L2 specifies an event mechanism to notify applications when controls
+change value (see
+:ref:`VIDIOC_SUBSCRIBE_EVENT`, event
+``V4L2_EVENT_CTRL``), panel applications might want to make use of that
+in order to always reflect the correct control value.
+
+All controls use machine endianness.
+
+
+.. _control-id:
+
+Control IDs
+===========
+
+``V4L2_CID_BASE``
+ First predefined ID, equal to ``V4L2_CID_BRIGHTNESS``.
+
+``V4L2_CID_USER_BASE``
+ Synonym of ``V4L2_CID_BASE``.
+
+``V4L2_CID_BRIGHTNESS`` ``(integer)``
+ Picture brightness, or more precisely, the black level.
+
+``V4L2_CID_CONTRAST`` ``(integer)``
+ Picture contrast or luma gain.
+
+``V4L2_CID_SATURATION`` ``(integer)``
+ Picture color saturation or chroma gain.
+
+``V4L2_CID_HUE`` ``(integer)``
+ Hue or color balance.
+
+``V4L2_CID_AUDIO_VOLUME`` ``(integer)``
+ Overall audio volume. Note some drivers also provide an OSS or ALSA
+ mixer interface.
+
+``V4L2_CID_AUDIO_BALANCE`` ``(integer)``
+ Audio stereo balance. Minimum corresponds to all the way left,
+ maximum to right.
+
+``V4L2_CID_AUDIO_BASS`` ``(integer)``
+ Audio bass adjustment.
+
+``V4L2_CID_AUDIO_TREBLE`` ``(integer)``
+ Audio treble adjustment.
+
+``V4L2_CID_AUDIO_MUTE`` ``(boolean)``
+ Mute audio, i. e. set the volume to zero, however without affecting
+ ``V4L2_CID_AUDIO_VOLUME``. Like ALSA drivers, V4L2 drivers must mute
+ at load time to avoid excessive noise. Actually the entire device
+ should be reset to a low power consumption state.
+
+``V4L2_CID_AUDIO_LOUDNESS`` ``(boolean)``
+ Loudness mode (bass boost).
+
+``V4L2_CID_BLACK_LEVEL`` ``(integer)``
+ Another name for brightness (not a synonym of
+ ``V4L2_CID_BRIGHTNESS``). This control is deprecated and should not
+ be used in new drivers and applications.
+
+``V4L2_CID_AUTO_WHITE_BALANCE`` ``(boolean)``
+ Automatic white balance (cameras).
+
+``V4L2_CID_DO_WHITE_BALANCE`` ``(button)``
+ This is an action control. When set (the value is ignored), the
+ device will do a white balance and then hold the current setting.
+ Contrast this with the boolean ``V4L2_CID_AUTO_WHITE_BALANCE``,
+ which, when activated, keeps adjusting the white balance.
+
+``V4L2_CID_RED_BALANCE`` ``(integer)``
+ Red chroma balance.
+
+``V4L2_CID_BLUE_BALANCE`` ``(integer)``
+ Blue chroma balance.
+
+``V4L2_CID_GAMMA`` ``(integer)``
+ Gamma adjust.
+
+``V4L2_CID_WHITENESS`` ``(integer)``
+ Whiteness for grey-scale devices. This is a synonym for
+ ``V4L2_CID_GAMMA``. This control is deprecated and should not be
+ used in new drivers and applications.
+
+``V4L2_CID_EXPOSURE`` ``(integer)``
+ Exposure (cameras). [Unit?]
+
+``V4L2_CID_AUTOGAIN`` ``(boolean)``
+ Automatic gain/exposure control.
+
+``V4L2_CID_GAIN`` ``(integer)``
+ Gain control.
+
+``V4L2_CID_HFLIP`` ``(boolean)``
+ Mirror the picture horizontally.
+
+``V4L2_CID_VFLIP`` ``(boolean)``
+ Mirror the picture vertically.
+
+.. _v4l2-power-line-frequency:
+
+``V4L2_CID_POWER_LINE_FREQUENCY`` ``(enum)``
+ Enables a power line frequency filter to avoid flicker. Possible
+ values for ``enum v4l2_power_line_frequency`` are:
+ ``V4L2_CID_POWER_LINE_FREQUENCY_DISABLED`` (0),
+ ``V4L2_CID_POWER_LINE_FREQUENCY_50HZ`` (1),
+ ``V4L2_CID_POWER_LINE_FREQUENCY_60HZ`` (2) and
+ ``V4L2_CID_POWER_LINE_FREQUENCY_AUTO`` (3).
+
+``V4L2_CID_HUE_AUTO`` ``(boolean)``
+ Enables automatic hue control by the device. The effect of setting
+ ``V4L2_CID_HUE`` while automatic hue control is enabled is
+ undefined, drivers should ignore such request.
+
+``V4L2_CID_WHITE_BALANCE_TEMPERATURE`` ``(integer)``
+ This control specifies the white balance settings as a color
+ temperature in Kelvin. A driver should have a minimum of 2800
+ (incandescent) to 6500 (daylight). For more information about color
+ temperature see
+ `Wikipedia <http://en.wikipedia.org/wiki/Color_temperature>`__.
+
+``V4L2_CID_SHARPNESS`` ``(integer)``
+ Adjusts the sharpness filters in a camera. The minimum value
+ disables the filters, higher values give a sharper picture.
+
+``V4L2_CID_BACKLIGHT_COMPENSATION`` ``(integer)``
+ Adjusts the backlight compensation in a camera. The minimum value
+ disables backlight compensation.
+
+``V4L2_CID_CHROMA_AGC`` ``(boolean)``
+ Chroma automatic gain control.
+
+``V4L2_CID_CHROMA_GAIN`` ``(integer)``
+ Adjusts the Chroma gain control (for use when chroma AGC is
+ disabled).
+
+``V4L2_CID_COLOR_KILLER`` ``(boolean)``
+ Enable the color killer (i. e. force a black & white image in case
+ of a weak video signal).
+
+.. _v4l2-colorfx:
+
+``V4L2_CID_COLORFX`` ``(enum)``
+ Selects a color effect. The following values are defined:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_COLORFX_NONE``
+
+ - Color effect is disabled.
+
+ - .. row 2
+
+ - ``V4L2_COLORFX_ANTIQUE``
+
+ - An aging (old photo) effect.
+
+ - .. row 3
+
+ - ``V4L2_COLORFX_ART_FREEZE``
+
+ - Frost color effect.
+
+ - .. row 4
+
+ - ``V4L2_COLORFX_AQUA``
+
+ - Water color, cool tone.
+
+ - .. row 5
+
+ - ``V4L2_COLORFX_BW``
+
+ - Black and white.
+
+ - .. row 6
+
+ - ``V4L2_COLORFX_EMBOSS``
+
+ - Emboss, the highlights and shadows replace light/dark boundaries
+ and low contrast areas are set to a gray background.
+
+ - .. row 7
+
+ - ``V4L2_COLORFX_GRASS_GREEN``
+
+ - Grass green.
+
+ - .. row 8
+
+ - ``V4L2_COLORFX_NEGATIVE``
+
+ - Negative.
+
+ - .. row 9
+
+ - ``V4L2_COLORFX_SEPIA``
+
+ - Sepia tone.
+
+ - .. row 10
+
+ - ``V4L2_COLORFX_SKETCH``
+
+ - Sketch.
+
+ - .. row 11
+
+ - ``V4L2_COLORFX_SKIN_WHITEN``
+
+ - Skin whiten.
+
+ - .. row 12
+
+ - ``V4L2_COLORFX_SKY_BLUE``
+
+ - Sky blue.
+
+ - .. row 13
+
+ - ``V4L2_COLORFX_SOLARIZATION``
+
+ - Solarization, the image is partially reversed in tone, only color
+ values above or below a certain threshold are inverted.
+
+ - .. row 14
+
+ - ``V4L2_COLORFX_SILHOUETTE``
+
+ - Silhouette (outline).
+
+ - .. row 15
+
+ - ``V4L2_COLORFX_VIVID``
+
+ - Vivid colors.
+
+ - .. row 16
+
+ - ``V4L2_COLORFX_SET_CBCR``
+
+ - The Cb and Cr chroma components are replaced by fixed coefficients
+ determined by ``V4L2_CID_COLORFX_CBCR`` control.
+
+
+
+``V4L2_CID_COLORFX_CBCR`` ``(integer)``
+ Determines the Cb and Cr coefficients for ``V4L2_COLORFX_SET_CBCR``
+ color effect. Bits [7:0] of the supplied 32 bit value are
+ interpreted as Cr component, bits [15:8] as Cb component and bits
+ [31:16] must be zero.
+
+``V4L2_CID_AUTOBRIGHTNESS`` ``(boolean)``
+ Enable Automatic Brightness.
+
+``V4L2_CID_ROTATE`` ``(integer)``
+ Rotates the image by specified angle. Common angles are 90, 270 and
+ 180. Rotating the image to 90 and 270 will reverse the height and
+ width of the display window. It is necessary to set the new height
+ and width of the picture using the
+ :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl according to the
+ rotation angle selected.
+
+``V4L2_CID_BG_COLOR`` ``(integer)``
+ Sets the background color on the current output device. Background
+ color needs to be specified in the RGB24 format. The supplied 32 bit
+ value is interpreted as bits 0-7 Red color information, bits 8-15
+ Green color information, bits 16-23 Blue color information and bits
+ 24-31 must be zero.
+
+``V4L2_CID_ILLUMINATORS_1 V4L2_CID_ILLUMINATORS_2`` ``(boolean)``
+ Switch on or off the illuminator 1 or 2 of the device (usually a
+ microscope).
+
+``V4L2_CID_MIN_BUFFERS_FOR_CAPTURE`` ``(integer)``
+ This is a read-only control that can be read by the application and
+ used as a hint to determine the number of CAPTURE buffers to pass to
+ REQBUFS. The value is the minimum number of CAPTURE buffers that is
+ necessary for hardware to work.
+
+``V4L2_CID_MIN_BUFFERS_FOR_OUTPUT`` ``(integer)``
+ This is a read-only control that can be read by the application and
+ used as a hint to determine the number of OUTPUT buffers to pass to
+ REQBUFS. The value is the minimum number of OUTPUT buffers that is
+ necessary for hardware to work.
+
+.. _v4l2-alpha-component:
+
+``V4L2_CID_ALPHA_COMPONENT`` ``(integer)``
+ Sets the alpha color component. When a capture device (or capture
+ queue of a mem-to-mem device) produces a frame format that includes
+ an alpha component (e.g.
+ :ref:`packed RGB image formats <rgb-formats>`) and the alpha value
+ is not defined by the device or the mem-to-mem input data this
+ control lets you select the alpha component value of all pixels.
+ When an output device (or output queue of a mem-to-mem device)
+ consumes a frame format that doesn't include an alpha component and
+ the device supports alpha channel processing this control lets you
+ set the alpha component value of all pixels for further processing
+ in the device.
+
+``V4L2_CID_LASTP1``
+ End of the predefined control IDs (currently
+ ``V4L2_CID_ALPHA_COMPONENT`` + 1).
+
+``V4L2_CID_PRIVATE_BASE``
+ ID of the first custom (driver specific) control. Applications
+ depending on particular custom controls should check the driver name
+ and version, see :ref:`querycap`.
+
+Applications can enumerate the available controls with the
+:ref:`VIDIOC_QUERYCTRL` and
+:ref:`VIDIOC_QUERYMENU <VIDIOC_QUERYCTRL>` ioctls, get and set a
+control value with the :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and
+:ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls. Drivers must implement
+``VIDIOC_QUERYCTRL``, ``VIDIOC_G_CTRL`` and ``VIDIOC_S_CTRL`` when the
+device has one or more controls, ``VIDIOC_QUERYMENU`` when it has one or
+more menu type controls.
+
+
+.. _enum_all_controls:
+
+.. code-block:: c
+ :caption: Example 1.8. Enumerating all user controls
+
+
+ struct v4l2_queryctrl queryctrl;
+ struct v4l2_querymenu querymenu;
+
+ static void enumerate_menu(void)
+ {
+ printf(" Menu items:\\n");
+
+ memset(&querymenu, 0, sizeof(querymenu));
+ querymenu.id = queryctrl.id;
+
+ for (querymenu.index = queryctrl.minimum;
+ querymenu.index <= queryctrl.maximum;
+ querymenu.index++) {
+ if (0 == ioctl(fd, VIDIOC_QUERYMENU, &querymenu)) {
+ printf(" %s\\n", querymenu.name);
+ }
+ }
+ }
+
+ memset(&queryctrl, 0, sizeof(queryctrl));
+
+ for (queryctrl.id = V4L2_CID_BASE;
+ queryctrl.id < V4L2_CID_LASTP1;
+ queryctrl.id++) {
+ if (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
+ if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)
+ continue;
+
+ printf("Control %s\\n", queryctrl.name);
+
+ if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
+ enumerate_menu();
+ } else {
+ if (errno == EINVAL)
+ continue;
+
+ perror("VIDIOC_QUERYCTRL");
+ exit(EXIT_FAILURE);
+ }
+ }
+
+ for (queryctrl.id = V4L2_CID_PRIVATE_BASE;;
+ queryctrl.id++) {
+ if (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
+ if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)
+ continue;
+
+ printf("Control %s\\n", queryctrl.name);
+
+ if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
+ enumerate_menu();
+ } else {
+ if (errno == EINVAL)
+ break;
+
+ perror("VIDIOC_QUERYCTRL");
+ exit(EXIT_FAILURE);
+ }
+ }
+
+
+.. code-block:: c
+ :caption: Example 1.9. Enumerating all user controls (alternative)
+
+ memset(&queryctrl, 0, sizeof(queryctrl));
+
+ queryctrl.id = V4L2_CTRL_CLASS_USER | V4L2_CTRL_FLAG_NEXT_CTRL;
+ while (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
+ if (V4L2_CTRL_ID2CLASS(queryctrl.id) != V4L2_CTRL_CLASS_USER)
+ break;
+ if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)
+ continue;
+
+ printf("Control %s\\n", queryctrl.name);
+
+ if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
+ enumerate_menu();
+
+ queryctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
+ }
+ if (errno != EINVAL) {
+ perror("VIDIOC_QUERYCTRL");
+ exit(EXIT_FAILURE);
+ }
+
+
+.. code-block:: c
+ :caption: Example 1.10. Changing controls
+
+ struct v4l2_queryctrl queryctrl;
+ struct v4l2_control control;
+
+ memset(&queryctrl, 0, sizeof(queryctrl));
+ queryctrl.id = V4L2_CID_BRIGHTNESS;
+
+ if (-1 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
+ if (errno != EINVAL) {
+ perror("VIDIOC_QUERYCTRL");
+ exit(EXIT_FAILURE);
+ } else {
+ printf("V4L2_CID_BRIGHTNESS is not supportedn");
+ }
+ } else if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) {
+ printf("V4L2_CID_BRIGHTNESS is not supportedn");
+ } else {
+ memset(&control, 0, sizeof (control));
+ control.id = V4L2_CID_BRIGHTNESS;
+ control.value = queryctrl.default_value;
+
+ if (-1 == ioctl(fd, VIDIOC_S_CTRL, &control)) {
+ perror("VIDIOC_S_CTRL");
+ exit(EXIT_FAILURE);
+ }
+ }
+
+ memset(&control, 0, sizeof(control));
+ control.id = V4L2_CID_CONTRAST;
+
+ if (0 == ioctl(fd, VIDIOC_G_CTRL, &control)) {
+ control.value += 1;
+
+ /* The driver may clamp the value or return ERANGE, ignored here */
+
+ if (-1 == ioctl(fd, VIDIOC_S_CTRL, &control)
+ && errno != ERANGE) {
+ perror("VIDIOC_S_CTRL");
+ exit(EXIT_FAILURE);
+ }
+ /* Ignore if V4L2_CID_CONTRAST is unsupported */
+ } else if (errno != EINVAL) {
+ perror("VIDIOC_G_CTRL");
+ exit(EXIT_FAILURE);
+ }
+
+ control.id = V4L2_CID_AUDIO_MUTE;
+ control.value = 1; /* silence */
+
+ /* Errors ignored */
+ ioctl(fd, VIDIOC_S_CTRL, &control);
+
+.. [1]
+ The use of ``V4L2_CID_PRIVATE_BASE`` is problematic because different
+ drivers may use the same ``V4L2_CID_PRIVATE_BASE`` ID for different
+ controls. This makes it hard to programatically set such controls
+ since the meaning of the control with that ID is driver dependent. In
+ order to resolve this drivers use unique IDs and the
+ ``V4L2_CID_PRIVATE_BASE`` IDs are mapped to those unique IDs by the
+ kernel. Consider these ``V4L2_CID_PRIVATE_BASE`` IDs as aliases to
+ the real IDs.
+
+ Many applications today still use the ``V4L2_CID_PRIVATE_BASE`` IDs
+ instead of using :ref:`VIDIOC_QUERYCTRL` with
+ the ``V4L2_CTRL_FLAG_NEXT_CTRL`` flag to enumerate all IDs, so
+ support for ``V4L2_CID_PRIVATE_BASE`` is still around.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _crop:
+
+*************************************
+Image Cropping, Insertion and Scaling
+*************************************
+
+Some video capture devices can sample a subsection of the picture and
+shrink or enlarge it to an image of arbitrary size. We call these
+abilities cropping and scaling. Some video output devices can scale an
+image up or down and insert it at an arbitrary scan line and horizontal
+offset into a video signal.
+
+Applications can use the following API to select an area in the video
+signal, query the default area and the hardware limits.
+
+**NOTE**: Despite their name, the :ref:`VIDIOC_CROPCAP <VIDIOC_CROPCAP>`,
+:ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and :ref:`VIDIOC_S_CROP
+<VIDIOC_G_CROP>` ioctls apply to input as well as output devices.
+
+Scaling requires a source and a target. On a video capture or overlay
+device the source is the video signal, and the cropping ioctls determine
+the area actually sampled. The target are images read by the application
+or overlaid onto the graphics screen. Their size (and position for an
+overlay) is negotiated with the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`
+and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls.
+
+On a video output device the source are the images passed in by the
+application, and their size is again negotiated with the
+:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
+ioctls, or may be encoded in a compressed video stream. The target is
+the video signal, and the cropping ioctls determine the area where the
+images are inserted.
+
+Source and target rectangles are defined even if the device does not
+support scaling or the :ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and
+:ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` ioctls. Their size (and position
+where applicable) will be fixed in this case.
+
+**NOTE:** All capture and output devices must support the
+:ref:`VIDIOC_CROPCAP <VIDIOC_CROPCAP>` ioctl such that applications can
+determine if scaling takes place.
+
+
+Cropping Structures
+===================
+
+
+.. _crop-scale:
+
+.. figure:: crop_files/crop.*
+ :alt: crop.pdf / crop.gif
+ :align: center
+
+ Image Cropping, Insertion and Scaling
+
+ The cropping, insertion and scaling process
+
+
+
+For capture devices the coordinates of the top left corner, width and
+height of the area which can be sampled is given by the ``bounds``
+substructure of the struct :ref:`v4l2_cropcap <v4l2-cropcap>` returned
+by the :ref:`VIDIOC_CROPCAP <VIDIOC_CROPCAP>` ioctl. To support a wide
+range of hardware this specification does not define an origin or units.
+However by convention drivers should horizontally count unscaled samples
+relative to 0H (the leading edge of the horizontal sync pulse, see
+:ref:`vbi-hsync`). Vertically ITU-R line numbers of the first field
+(see ITU R-525 line numbering for :ref:`525 lines <vbi-525>` and for
+:ref:`625 lines <vbi-625>`), multiplied by two if the driver
+can capture both fields.
+
+The top left corner, width and height of the source rectangle, that is
+the area actually sampled, is given by struct
+:ref:`v4l2_crop <v4l2-crop>` using the same coordinate system as
+struct :ref:`v4l2_cropcap <v4l2-cropcap>`. Applications can use the
+:ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>`
+ioctls to get and set this rectangle. It must lie completely within the
+capture boundaries and the driver may further adjust the requested size
+and/or position according to hardware limitations.
+
+Each capture device has a default source rectangle, given by the
+``defrect`` substructure of struct
+:ref:`v4l2_cropcap <v4l2-cropcap>`. The center of this rectangle
+shall align with the center of the active picture area of the video
+signal, and cover what the driver writer considers the complete picture.
+Drivers shall reset the source rectangle to the default when the driver
+is first loaded, but not later.
+
+For output devices these structures and ioctls are used accordingly,
+defining the *target* rectangle where the images will be inserted into
+the video signal.
+
+
+Scaling Adjustments
+===================
+
+Video hardware can have various cropping, insertion and scaling
+limitations. It may only scale up or down, support only discrete scaling
+factors, or have different scaling abilities in horizontal and vertical
+direction. Also it may not support scaling at all. At the same time the
+struct :ref:`v4l2_crop <v4l2-crop>` rectangle may have to be aligned,
+and both the source and target rectangles may have arbitrary upper and
+lower size limits. In particular the maximum ``width`` and ``height`` in
+struct :ref:`v4l2_crop <v4l2-crop>` may be smaller than the struct
+:ref:`v4l2_cropcap <v4l2-cropcap>`. ``bounds`` area. Therefore, as
+usual, drivers are expected to adjust the requested parameters and
+return the actual values selected.
+
+Applications can change the source or the target rectangle first, as
+they may prefer a particular image size or a certain area in the video
+signal. If the driver has to adjust both to satisfy hardware
+limitations, the last requested rectangle shall take priority, and the
+driver should preferably adjust the opposite one. The
+:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl however shall not change
+the driver state and therefore only adjust the requested rectangle.
+
+Suppose scaling on a video capture device is restricted to a factor 1:1
+or 2:1 in either direction and the target image size must be a multiple
+of 16 × 16 pixels. The source cropping rectangle is set to defaults,
+which are also the upper limit in this example, of 640 × 400 pixels at
+offset 0, 0. An application requests an image size of 300 × 225 pixels,
+assuming video will be scaled down from the "full picture" accordingly.
+The driver sets the image size to the closest possible values 304 × 224,
+then chooses the cropping rectangle closest to the requested size, that
+is 608 × 224 (224 × 2:1 would exceed the limit 400). The offset 0, 0 is
+still valid, thus unmodified. Given the default cropping rectangle
+reported by :ref:`VIDIOC_CROPCAP <VIDIOC_CROPCAP>` the application can
+easily propose another offset to center the cropping rectangle.
+
+Now the application may insist on covering an area using a picture
+aspect ratio closer to the original request, so it asks for a cropping
+rectangle of 608 × 456 pixels. The present scaling factors limit
+cropping to 640 × 384, so the driver returns the cropping size 608 × 384
+and adjusts the image size to closest possible 304 × 192.
+
+
+Examples
+========
+
+Source and target rectangles shall remain unchanged across closing and
+reopening a device, such that piping data into or out of a device will
+work without special preparations. More advanced applications should
+ensure the parameters are suitable before starting I/O.
+
+**NOTE:** on the next two examples, a video capture device is assumed;
+change ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` for other types of device.
+
+.. code-block:: c
+ :caption: Example 1.11. Resetting the cropping parameters
+
+ struct v4l2_cropcap cropcap;
+ struct v4l2_crop crop;
+
+ memset (&cropcap, 0, sizeof (cropcap));
+ cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+
+ if (-1 == ioctl (fd, VIDIOC_CROPCAP, &cropcap)) {
+ perror ("VIDIOC_CROPCAP");
+ exit (EXIT_FAILURE);
+ }
+
+ memset (&crop, 0, sizeof (crop));
+ crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ crop.c = cropcap.defrect;
+
+ /* Ignore if cropping is not supported (EINVAL). */
+
+ if (-1 == ioctl (fd, VIDIOC_S_CROP, &crop)
+ && errno != EINVAL) {
+ perror ("VIDIOC_S_CROP");
+ exit (EXIT_FAILURE);
+ }
+
+.. code-block:: c
+ :caption: Example 1.12. Simple downscaling
+
+ struct v4l2_cropcap cropcap;
+ struct v4l2_format format;
+
+ reset_cropping_parameters ();
+
+ /* Scale down to 1/4 size of full picture. */
+
+ memset (&format, 0, sizeof (format)); /* defaults */
+
+ format.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+
+ format.fmt.pix.width = cropcap.defrect.width >> 1;
+ format.fmt.pix.height = cropcap.defrect.height >> 1;
+ format.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV;
+
+ if (-1 == ioctl (fd, VIDIOC_S_FMT, &format)) {
+ perror ("VIDIOC_S_FORMAT");
+ exit (EXIT_FAILURE);
+ }
+
+ /* We could check the actual image size now, the actual scaling factor
+ or if the driver can scale at all. */
+
+**NOTE:** This example assumes an output device.
+
+.. code-block:: c
+ :caption: Example 1.13. Selecting an output area
+
+ struct v4l2_cropcap cropcap;
+ struct v4l2_crop crop;
+
+ memset (&cropcap, 0, sizeof (cropcap));
+ cropcap.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;
+
+ if (-1 == ioctl (fd, VIDIOC_CROPCAP;, &cropcap)) {
+ perror ("VIDIOC_CROPCAP");
+ exit (EXIT_FAILURE);
+ }
+
+ memset (&crop, 0, sizeof (crop));
+
+ crop.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;
+ crop.c = cropcap.defrect;
+
+ /* Scale the width and height to 50 % of their original size
+ and center the output. */
+
+ crop.c.width /= 2;
+ crop.c.height /= 2;
+ crop.c.left += crop.c.width / 2;
+ crop.c.top += crop.c.height / 2;
+
+ /* Ignore if cropping is not supported (EINVAL). */
+
+ if (-1 == ioctl (fd, VIDIOC_S_CROP, &crop)
+ && errno != EINVAL) {
+ perror ("VIDIOC_S_CROP");
+ exit (EXIT_FAILURE);
+ }
+
+**NOTE:** This example assumes a video capture device.
+
+.. code-block:: c
+ :caption: Example 1.14. Current scaling factor and pixel aspect
+
+ struct v4l2_cropcap cropcap;
+ struct v4l2_crop crop;
+ struct v4l2_format format;
+ double hscale, vscale;
+ double aspect;
+ int dwidth, dheight;
+
+ memset (&cropcap, 0, sizeof (cropcap));
+ cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+
+ if (-1 == ioctl (fd, VIDIOC_CROPCAP, &cropcap)) {
+ perror ("VIDIOC_CROPCAP");
+ exit (EXIT_FAILURE);
+ }
+
+ memset (&crop, 0, sizeof (crop));
+ crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+
+ if (-1 == ioctl (fd, VIDIOC_G_CROP, &crop)) {
+ if (errno != EINVAL) {
+ perror ("VIDIOC_G_CROP");
+ exit (EXIT_FAILURE);
+ }
+
+ /* Cropping not supported. */
+ crop.c = cropcap.defrect;
+ }
+
+ memset (&format, 0, sizeof (format));
+ format.fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+
+ if (-1 == ioctl (fd, VIDIOC_G_FMT, &format)) {
+ perror ("VIDIOC_G_FMT");
+ exit (EXIT_FAILURE);
+ }
+
+ /* The scaling applied by the driver. */
+
+ hscale = format.fmt.pix.width / (double) crop.c.width;
+ vscale = format.fmt.pix.height / (double) crop.c.height;
+
+ aspect = cropcap.pixelaspect.numerator /
+ (double) cropcap.pixelaspect.denominator;
+ aspect = aspect * hscale / vscale;
+
+ /* Devices following ITU-R BT.601 do not capture
+ square pixels. For playback on a computer monitor
+ we should scale the images to this size. */
+
+ dwidth = format.fmt.pix.width / aspect;
+ dheight = format.fmt.pix.height;
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _depth-formats:
+
+*************
+Depth Formats
+*************
+
+Depth data provides distance to points, mapped onto the image plane
+
+
+.. toctree::
+ :maxdepth: 1
+
+ pixfmt-z16
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _capture:
+
+***********************
+Video Capture Interface
+***********************
+
+Video capture devices sample an analog video signal and store the
+digitized images in memory. Today nearly all devices can capture at full
+25 or 30 frames/second. With this interface applications can control the
+capture process and move images from the driver into user space.
+
+Conventionally V4L2 video capture devices are accessed through character
+device special files named ``/dev/video`` and ``/dev/video0`` to
+``/dev/video63`` with major number 81 and minor numbers 0 to 63.
+``/dev/video`` is typically a symbolic link to the preferred video
+device. Note the same device files are used for video output devices.
+
+
+Querying Capabilities
+=====================
+
+Devices supporting the video capture interface set the
+``V4L2_CAP_VIDEO_CAPTURE`` or ``V4L2_CAP_VIDEO_CAPTURE_MPLANE`` flag in
+the ``capabilities`` field of struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP` ioctl. As secondary device
+functions they may also support the :ref:`video overlay <overlay>`
+(``V4L2_CAP_VIDEO_OVERLAY``) and the :ref:`raw VBI capture <raw-vbi>`
+(``V4L2_CAP_VBI_CAPTURE``) interface. At least one of the read/write or
+streaming I/O methods must be supported. Tuners and audio inputs are
+optional.
+
+
+Supplemental Functions
+======================
+
+Video capture devices shall support :ref:`audio input <audio>`,
+:ref:`tuner`, :ref:`controls <control>`,
+:ref:`cropping and scaling <crop>` and
+:ref:`streaming parameter <streaming-par>` ioctls as needed. The
+:ref:`video input <video>` and :ref:`video standard <standard>`
+ioctls must be supported by all video capture devices.
+
+
+Image Format Negotiation
+========================
+
+The result of a capture operation is determined by cropping and image
+format parameters. The former select an area of the video picture to
+capture, the latter how images are stored in memory, i. e. in RGB or YUV
+format, the number of bits per pixel or width and height. Together they
+also define how images are scaled in the process.
+
+As usual these parameters are *not* reset at :ref:`open() <func-open>`
+time to permit Unix tool chains, programming a device and then reading
+from it as if it was a plain file. Well written V4L2 applications ensure
+they really get what they want, including cropping and scaling.
+
+Cropping initialization at minimum requires to reset the parameters to
+defaults. An example is given in :ref:`crop`.
+
+To query the current image format applications set the ``type`` field of
+a struct :ref:`v4l2_format <v4l2-format>` to
+``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or
+``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and call the
+:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl with a pointer to this
+structure. Drivers fill the struct
+:ref:`v4l2_pix_format <v4l2-pix-format>` ``pix`` or the struct
+:ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` ``pix_mp``
+member of the ``fmt`` union.
+
+To request different parameters applications set the ``type`` field of a
+struct :ref:`v4l2_format <v4l2-format>` as above and initialize all
+fields of the struct :ref:`v4l2_pix_format <v4l2-pix-format>`
+``vbi`` member of the ``fmt`` union, or better just modify the results
+of :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, and call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
+ioctl with a pointer to this structure. Drivers may adjust the
+parameters and finally return the actual parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`
+does.
+
+Like :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` the :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl
+can be used to learn about hardware limitations without disabling I/O or
+possibly time consuming hardware preparations.
+
+The contents of struct :ref:`v4l2_pix_format <v4l2-pix-format>` and
+struct :ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` are
+discussed in :ref:`pixfmt`. See also the specification of the
+:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctls for
+details. Video capture devices must implement both the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`
+and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ignores all
+requests and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does.
+:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional.
+
+
+Reading Images
+==============
+
+A video capture device may support the ::ref:`read() function <func-read>`
+and/or streaming (:ref:`memory mapping <func-mmap>` or
+:ref:`user pointer <userp>`) I/O. See :ref:`io` for details.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _codec:
+
+***************
+Codec Interface
+***************
+
+A V4L2 codec can compress, decompress, transform, or otherwise convert
+video data from one format into another format, in memory. Typically
+such devices are memory-to-memory devices (i.e. devices with the
+``V4L2_CAP_VIDEO_M2M`` or ``V4L2_CAP_VIDEO_M2M_MPLANE`` capability set).
+
+A memory-to-memory video node acts just like a normal video node, but it
+supports both output (sending frames from memory to the codec hardware)
+and capture (receiving the processed frames from the codec hardware into
+memory) stream I/O. An application will have to setup the stream I/O for
+both sides and finally call :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`
+for both capture and output to start the codec.
+
+Video compression codecs use the MPEG controls to setup their codec
+parameters (note that the MPEG controls actually support many more
+codecs than just MPEG). See :ref:`mpeg-controls`.
+
+Memory-to-memory devices can often be used as a shared resource: you can
+open the video node multiple times, each application setting up their
+own codec properties that are local to the file handle, and each can use
+it independently from the others. The driver will arbitrate access to
+the codec and reprogram it whenever another file handler gets access.
+This is different from the usual video node behavior where the video
+properties are global to the device (i.e. changing something through one
+file handle is visible through another file handle).
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _effect:
+
+************************
+Effect Devices Interface
+************************
+
+ **Note**
+
+ This interface has been be suspended from the V4L2 API implemented
+ in Linux 2.6 until we have more experience with effect device
+ interfaces.
+
+A V4L2 video effect device can do image effects, filtering, or combine
+two or more images or image streams. For example video transitions or
+wipes. Applications send data to be processed and receive the result
+data either with :ref:`read() <func-read>` and
+:ref:`write() <func-write>` functions, or through the streaming I/O
+mechanism.
+
+[to do]
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _event:
+
+***************
+Event Interface
+***************
+
+The V4L2 event interface provides a means for a user to get immediately
+notified on certain conditions taking place on a device. This might
+include start of frame or loss of signal events, for example. Changes in
+the value or state of a V4L2 control can also be reported through
+events.
+
+To receive events, the events the user is interested in first must be
+subscribed using the
+:ref:`VIDIOC_SUBSCRIBE_EVENT` ioctl. Once
+an event is subscribed, the events of subscribed types are dequeueable
+using the :ref:`VIDIOC_DQEVENT` ioctl. Events may be
+unsubscribed using VIDIOC_UNSUBSCRIBE_EVENT ioctl. The special event
+type V4L2_EVENT_ALL may be used to unsubscribe all the events the
+driver supports.
+
+The event subscriptions and event queues are specific to file handles.
+Subscribing an event on one file handle does not affect other file
+handles.
+
+The information on dequeueable events is obtained by using select or
+poll system calls on video devices. The V4L2 events use POLLPRI events
+on poll system call and exceptions on select system call.
+
+Starting with kernel 3.1 certain guarantees can be given with regards to
+events:
+
+1. Each subscribed event has its own internal dedicated event queue.
+ This means that flooding of one event type will not interfere with
+ other event types.
+
+2. If the internal event queue for a particular subscribed event becomes
+ full, then the oldest event in that queue will be dropped.
+
+3. Where applicable, certain event types can ensure that the payload of
+ the oldest event that is about to be dropped will be merged with the
+ payload of the next oldest event. Thus ensuring that no information
+ is lost, but only an intermediate step leading up to that
+ information. See the documentation for the event you want to
+ subscribe to whether this is applicable for that event or not.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _osd:
+
+******************************
+Video Output Overlay Interface
+******************************
+
+**Also known as On-Screen Display (OSD)**
+
+Some video output devices can overlay a framebuffer image onto the
+outgoing video signal. Applications can set up such an overlay using
+this interface, which borrows structures and ioctls of the
+:ref:`Video Overlay <overlay>` interface.
+
+The OSD function is accessible through the same character special file
+as the :ref:`Video Output <capture>` function. Note the default
+function of such a ``/dev/video`` device is video capturing or output.
+The OSD function is only available after calling the
+:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
+
+
+Querying Capabilities
+=====================
+
+Devices supporting the *Video Output Overlay* interface set the
+``V4L2_CAP_VIDEO_OUTPUT_OVERLAY`` flag in the ``capabilities`` field of
+struct :ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP` ioctl.
+
+
+Framebuffer
+===========
+
+Contrary to the *Video Overlay* interface the framebuffer is normally
+implemented on the TV card and not the graphics card. On Linux it is
+accessible as a framebuffer device (``/dev/fbN``). Given a V4L2 device,
+applications can find the corresponding framebuffer device by calling
+the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` ioctl. It returns, amongst
+other information, the physical address of the framebuffer in the
+``base`` field of struct :ref:`v4l2_framebuffer <v4l2-framebuffer>`.
+The framebuffer device ioctl ``FBIOGET_FSCREENINFO`` returns the same
+address in the ``smem_start`` field of struct
+:c:type:`struct fb_fix_screeninfo`. The ``FBIOGET_FSCREENINFO``
+ioctl and struct :c:type:`struct fb_fix_screeninfo` are defined in
+the ``linux/fb.h`` header file.
+
+The width and height of the framebuffer depends on the current video
+standard. A V4L2 driver may reject attempts to change the video standard
+(or any other ioctl which would imply a framebuffer size change) with an
+``EBUSY`` error code until all applications closed the framebuffer device.
+
+
+.. code-block:: c
+ :caption: Example 4.1. Finding a framebuffer device for OSD
+
+ #include <linux/fb.h>
+
+ struct v4l2_framebuffer fbuf;
+ unsigned int i;
+ int fb_fd;
+
+ if (-1 == ioctl(fd, VIDIOC_G_FBUF, &fbuf)) {
+ perror("VIDIOC_G_FBUF");
+ exit(EXIT_FAILURE);
+ }
+
+ for (i = 0; i < 30; i++) {
+ char dev_name[16];
+ struct fb_fix_screeninfo si;
+
+ snprintf(dev_name, sizeof(dev_name), "/dev/fb%u", i);
+
+ fb_fd = open(dev_name, O_RDWR);
+ if (-1 == fb_fd) {
+ switch (errno) {
+ case ENOENT: /* no such file */
+ case ENXIO: /* no driver */
+ continue;
+
+ default:
+ perror("open");
+ exit(EXIT_FAILURE);
+ }
+ }
+
+ if (0 == ioctl(fb_fd, FBIOGET_FSCREENINFO, &si)) {
+ if (si.smem_start == (unsigned long)fbuf.base)
+ break;
+ } else {
+ /* Apparently not a framebuffer device. */
+ }
+
+ close(fb_fd);
+ fb_fd = -1;
+ }
+
+ /* fb_fd is the file descriptor of the framebuffer device
+ for the video output overlay, or -1 if no device was found. */
+
+
+Overlay Window and Scaling
+==========================
+
+The overlay is controlled by source and target rectangles. The source
+rectangle selects a subsection of the framebuffer image to be overlaid,
+the target rectangle an area in the outgoing video signal where the
+image will appear. Drivers may or may not support scaling, and arbitrary
+sizes and positions of these rectangles. Further drivers may support any
+(or none) of the clipping/blending methods defined for the
+:ref:`Video Overlay <overlay>` interface.
+
+A struct :ref:`v4l2_window <v4l2-window>` defines the size of the
+source rectangle, its position in the framebuffer and the
+clipping/blending method to be used for the overlay. To get the current
+parameters applications set the ``type`` field of a struct
+:ref:`v4l2_format <v4l2-format>` to
+``V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY`` and call the
+:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl. The driver fills the
+:ref:`struct v4l2_window <v4l2-window>` substructure named ``win``. It is not
+possible to retrieve a previously programmed clipping list or bitmap.
+
+To program the source rectangle applications set the ``type`` field of a
+struct :ref:`v4l2_format <v4l2-format>` to
+``V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY``, initialize the ``win``
+substructure and call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
+The driver adjusts the parameters against hardware limits and returns
+the actual parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. Like :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`,
+the :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl can be used to learn
+about driver capabilities without actually changing driver state. Unlike
+:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` this also works after the overlay has been enabled.
+
+A struct :ref:`v4l2_crop <v4l2-crop>` defines the size and position
+of the target rectangle. The scaling factor of the overlay is implied by
+the width and height given in struct :ref:`v4l2_window <v4l2-window>`
+and struct :ref:`v4l2_crop <v4l2-crop>`. The cropping API applies to
+*Video Output* and *Video Output Overlay* devices in the same way as to
+*Video Capture* and *Video Overlay* devices, merely reversing the
+direction of the data flow. For more information see :ref:`crop`.
+
+
+Enabling Overlay
+================
+
+There is no V4L2 ioctl to enable or disable the overlay, however the
+framebuffer interface of the driver may support the ``FBIOBLANK`` ioctl.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _output:
+
+**********************
+Video Output Interface
+**********************
+
+Video output devices encode stills or image sequences as analog video
+signal. With this interface applications can control the encoding
+process and move images from user space to the driver.
+
+Conventionally V4L2 video output devices are accessed through character
+device special files named ``/dev/video`` and ``/dev/video0`` to
+``/dev/video63`` with major number 81 and minor numbers 0 to 63.
+``/dev/video`` is typically a symbolic link to the preferred video
+device. Note the same device files are used for video capture devices.
+
+
+Querying Capabilities
+=====================
+
+Devices supporting the video output interface set the
+``V4L2_CAP_VIDEO_OUTPUT`` or ``V4L2_CAP_VIDEO_OUTPUT_MPLANE`` flag in
+the ``capabilities`` field of struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP` ioctl. As secondary device
+functions they may also support the :ref:`raw VBI output <raw-vbi>`
+(``V4L2_CAP_VBI_OUTPUT``) interface. At least one of the read/write or
+streaming I/O methods must be supported. Modulators and audio outputs
+are optional.
+
+
+Supplemental Functions
+======================
+
+Video output devices shall support :ref:`audio output <audio>`,
+:ref:`modulator <tuner>`, :ref:`controls <control>`,
+:ref:`cropping and scaling <crop>` and
+:ref:`streaming parameter <streaming-par>` ioctls as needed. The
+:ref:`video output <video>` and :ref:`video standard <standard>`
+ioctls must be supported by all video output devices.
+
+
+Image Format Negotiation
+========================
+
+The output is determined by cropping and image format parameters. The
+former select an area of the video picture where the image will appear,
+the latter how images are stored in memory, i. e. in RGB or YUV format,
+the number of bits per pixel or width and height. Together they also
+define how images are scaled in the process.
+
+As usual these parameters are *not* reset at :ref:`open() <func-open>`
+time to permit Unix tool chains, programming a device and then writing
+to it as if it was a plain file. Well written V4L2 applications ensure
+they really get what they want, including cropping and scaling.
+
+Cropping initialization at minimum requires to reset the parameters to
+defaults. An example is given in :ref:`crop`.
+
+To query the current image format applications set the ``type`` field of
+a struct :ref:`v4l2_format <v4l2-format>` to
+``V4L2_BUF_TYPE_VIDEO_OUTPUT`` or ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``
+and call the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl with a pointer
+to this structure. Drivers fill the struct
+:ref:`v4l2_pix_format <v4l2-pix-format>` ``pix`` or the struct
+:ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` ``pix_mp``
+member of the ``fmt`` union.
+
+To request different parameters applications set the ``type`` field of a
+struct :ref:`v4l2_format <v4l2-format>` as above and initialize all
+fields of the struct :ref:`v4l2_pix_format <v4l2-pix-format>`
+``vbi`` member of the ``fmt`` union, or better just modify the results
+of :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, and call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
+ioctl with a pointer to this structure. Drivers may adjust the
+parameters and finally return the actual parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`
+does.
+
+Like :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` the :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl
+can be used to learn about hardware limitations without disabling I/O or
+possibly time consuming hardware preparations.
+
+The contents of struct :ref:`v4l2_pix_format <v4l2-pix-format>` and
+struct :ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` are
+discussed in :ref:`pixfmt`. See also the specification of the
+:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctls for
+details. Video output devices must implement both the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`
+and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ignores all
+requests and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does.
+:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional.
+
+
+Writing Images
+==============
+
+A video output device may support the :ref:`write() function <rw>`
+and/or streaming (:ref:`memory mapping <mmap>` or
+:ref:`user pointer <userp>`) I/O. See :ref:`io` for details.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _overlay:
+
+***********************
+Video Overlay Interface
+***********************
+
+**Also known as Framebuffer Overlay or Previewing.**
+
+Video overlay devices have the ability to genlock (TV-)video into the
+(VGA-)video signal of a graphics card, or to store captured images
+directly in video memory of a graphics card, typically with clipping.
+This can be considerable more efficient than capturing images and
+displaying them by other means. In the old days when only nuclear power
+plants needed cooling towers this used to be the only way to put live
+video into a window.
+
+Video overlay devices are accessed through the same character special
+files as :ref:`video capture <capture>` devices. Note the default
+function of a ``/dev/video`` device is video capturing. The overlay
+function is only available after calling the
+:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
+
+The driver may support simultaneous overlay and capturing using the
+read/write and streaming I/O methods. If so, operation at the nominal
+frame rate of the video standard is not guaranteed. Frames may be
+directed away from overlay to capture, or one field may be used for
+overlay and the other for capture if the capture parameters permit this.
+
+Applications should use different file descriptors for capturing and
+overlay. This must be supported by all drivers capable of simultaneous
+capturing and overlay. Optionally these drivers may also permit
+capturing and overlay with a single file descriptor for compatibility
+with V4L and earlier versions of V4L2. [1]_
+
+
+Querying Capabilities
+=====================
+
+Devices supporting the video overlay interface set the
+``V4L2_CAP_VIDEO_OVERLAY`` flag in the ``capabilities`` field of struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP` ioctl. The overlay I/O
+method specified below must be supported. Tuners and audio inputs are
+optional.
+
+
+Supplemental Functions
+======================
+
+Video overlay devices shall support :ref:`audio input <audio>`,
+:ref:`tuner`, :ref:`controls <control>`,
+:ref:`cropping and scaling <crop>` and
+:ref:`streaming parameter <streaming-par>` ioctls as needed. The
+:ref:`video input <video>` and :ref:`video standard <standard>`
+ioctls must be supported by all video overlay devices.
+
+
+Setup
+=====
+
+Before overlay can commence applications must program the driver with
+frame buffer parameters, namely the address and size of the frame buffer
+and the image format, for example RGB 5:6:5. The
+:ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` and
+:ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctls are available to get and
+set these parameters, respectively. The :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctl is
+privileged because it allows to set up DMA into physical memory,
+bypassing the memory protection mechanisms of the kernel. Only the
+superuser can change the frame buffer address and size. Users are not
+supposed to run TV applications as root or with SUID bit set. A small
+helper application with suitable privileges should query the graphics
+system and program the V4L2 driver at the appropriate time.
+
+Some devices add the video overlay to the output signal of the graphics
+card. In this case the frame buffer is not modified by the video device,
+and the frame buffer address and pixel format are not needed by the
+driver. The :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctl is not privileged. An application
+can check for this type of device by calling the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`
+ioctl.
+
+A driver may support any (or none) of five clipping/blending methods:
+
+1. Chroma-keying displays the overlaid image only where pixels in the
+ primary graphics surface assume a certain color.
+
+2. A bitmap can be specified where each bit corresponds to a pixel in
+ the overlaid image. When the bit is set, the corresponding video
+ pixel is displayed, otherwise a pixel of the graphics surface.
+
+3. A list of clipping rectangles can be specified. In these regions *no*
+ video is displayed, so the graphics surface can be seen here.
+
+4. The framebuffer has an alpha channel that can be used to clip or
+ blend the framebuffer with the video.
+
+5. A global alpha value can be specified to blend the framebuffer
+ contents with video images.
+
+When simultaneous capturing and overlay is supported and the hardware
+prohibits different image and frame buffer formats, the format requested
+first takes precedence. The attempt to capture
+(:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`) or overlay
+(:ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`) may fail with an ``EBUSY`` error
+code or return accordingly modified parameters..
+
+
+Overlay Window
+==============
+
+The overlaid image is determined by cropping and overlay window
+parameters. The former select an area of the video picture to capture,
+the latter how images are overlaid and clipped. Cropping initialization
+at minimum requires to reset the parameters to defaults. An example is
+given in :ref:`crop`.
+
+The overlay window is described by a struct
+:ref:`v4l2_window <v4l2-window>`. It defines the size of the image,
+its position over the graphics surface and the clipping to be applied.
+To get the current parameters applications set the ``type`` field of a
+struct :ref:`v4l2_format <v4l2-format>` to
+``V4L2_BUF_TYPE_VIDEO_OVERLAY`` and call the
+:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl. The driver fills the
+:ref:`struct v4l2_window <v4l2-window>` substructure named ``win``. It is not
+possible to retrieve a previously programmed clipping list or bitmap.
+
+To program the overlay window applications set the ``type`` field of a
+struct :ref:`v4l2_format <v4l2-format>` to
+``V4L2_BUF_TYPE_VIDEO_OVERLAY``, initialize the ``win`` substructure and
+call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. The driver
+adjusts the parameters against hardware limits and returns the actual
+parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. Like :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`, the
+:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl can be used to learn
+about driver capabilities without actually changing driver state. Unlike
+:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` this also works after the overlay has been enabled.
+
+The scaling factor of the overlaid image is implied by the width and
+height given in struct :ref:`v4l2_window <v4l2-window>` and the size
+of the cropping rectangle. For more information see :ref:`crop`.
+
+When simultaneous capturing and overlay is supported and the hardware
+prohibits different image and window sizes, the size requested first
+takes precedence. The attempt to capture or overlay as well
+(:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`) may fail with an ``EBUSY`` error
+code or return accordingly modified parameters.
+
+
+.. _v4l2-window:
+
+struct v4l2_window
+------------------
+
+``struct v4l2_rect w``
+ Size and position of the window relative to the top, left corner of
+ the frame buffer defined with
+ :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`. The window can extend the
+ frame buffer width and height, the ``x`` and ``y`` coordinates can
+ be negative, and it can lie completely outside the frame buffer. The
+ driver clips the window accordingly, or if that is not possible,
+ modifies its size and/or position.
+
+``enum v4l2_field field``
+ Applications set this field to determine which video field shall be
+ overlaid, typically one of ``V4L2_FIELD_ANY`` (0),
+ ``V4L2_FIELD_TOP``, ``V4L2_FIELD_BOTTOM`` or
+ ``V4L2_FIELD_INTERLACED``. Drivers may have to choose a different
+ field order and return the actual setting here.
+
+``__u32 chromakey``
+ When chroma-keying has been negotiated with
+ :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` applications set this field
+ to the desired pixel value for the chroma key. The format is the
+ same as the pixel format of the framebuffer (struct
+ :ref:`v4l2_framebuffer <v4l2-framebuffer>` ``fmt.pixelformat``
+ field), with bytes in host order. E. g. for
+ :ref:`V4L2_PIX_FMT_BGR24 <V4L2-PIX-FMT-BGR32>` the value should
+ be 0xRRGGBB on a little endian, 0xBBGGRR on a big endian host.
+
+``struct v4l2_clip * clips``
+ When chroma-keying has *not* been negotiated and
+ :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` indicated this capability,
+ applications can set this field to point to an array of clipping
+ rectangles.
+
+ Like the window coordinates w, clipping rectangles are defined
+ relative to the top, left corner of the frame buffer. However
+ clipping rectangles must not extend the frame buffer width and
+ height, and they must not overlap. If possible applications
+ should merge adjacent rectangles. Whether this must create
+ x-y or y-x bands, or the order of rectangles, is not defined. When
+ clip lists are not supported the driver ignores this field. Its
+ contents after calling :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
+ are undefined.
+
+``__u32 clipcount``
+ When the application set the ``clips`` field, this field must
+ contain the number of clipping rectangles in the list. When clip
+ lists are not supported the driver ignores this field, its contents
+ after calling :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` are undefined. When clip lists are
+ supported but no clipping is desired this field must be set to zero.
+
+``void * bitmap``
+ When chroma-keying has *not* been negotiated and
+ :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` indicated this capability,
+ applications can set this field to point to a clipping bit mask.
+
+It must be of the same size as the window, ``w.width`` and ``w.height``.
+Each bit corresponds to a pixel in the overlaid image, which is
+displayed only when the bit is *set*. Pixel coordinates translate to
+bits like:
+
+
+.. code-block:: c
+
+ ((__u8 *) bitmap)[w.width * y + x / 8] & (1 << (x & 7))
+
+where ``0`` ≤ x < ``w.width`` and ``0`` ≤ y <``w.height``. [2]_
+
+When a clipping bit mask is not supported the driver ignores this field,
+its contents after calling :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` are
+undefined. When a bit mask is supported but no clipping is desired this
+field must be set to ``NULL``.
+
+Applications need not create a clip list or bit mask. When they pass
+both, or despite negotiating chroma-keying, the results are undefined.
+Regardless of the chosen method, the clipping abilities of the hardware
+may be limited in quantity or quality. The results when these limits are
+exceeded are undefined. [3]_
+
+``__u8 global_alpha``
+ The global alpha value used to blend the framebuffer with video
+ images, if global alpha blending has been negotiated
+ (``V4L2_FBUF_FLAG_GLOBAL_ALPHA``, see
+ :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`,
+ :ref:`framebuffer-flags`).
+
+ **Note**: this field was added in Linux 2.6.23, extending the structure.
+ However the :ref:`VIDIOC_[G|S|TRY]_FMT <VIDIOC_G_FMT>`
+ ioctls, which take a pointer to a :ref:`v4l2_format <v4l2-format>`
+ parent structure with padding bytes at the end, are not affected.
+
+
+.. _v4l2-clip:
+
+struct v4l2_clip [4]_
+---------------------
+
+``struct v4l2_rect c``
+ Coordinates of the clipping rectangle, relative to the top, left
+ corner of the frame buffer. Only window pixels *outside* all
+ clipping rectangles are displayed.
+
+``struct v4l2_clip * next``
+ Pointer to the next clipping rectangle, ``NULL`` when this is the last
+ rectangle. Drivers ignore this field, it cannot be used to pass a
+ linked list of clipping rectangles.
+
+
+.. _v4l2-rect:
+
+struct v4l2_rect
+----------------
+
+``__s32 left``
+ Horizontal offset of the top, left corner of the rectangle, in
+ pixels.
+
+``__s32 top``
+ Vertical offset of the top, left corner of the rectangle, in pixels.
+ Offsets increase to the right and down.
+
+``__u32 width``
+ Width of the rectangle, in pixels.
+
+``__u32 height``
+ Height of the rectangle, in pixels.
+
+
+Enabling Overlay
+================
+
+To start or stop the frame buffer overlay applications call the
+:ref:`VIDIOC_OVERLAY` ioctl.
+
+.. [1]
+ A common application of two file descriptors is the XFree86
+ :ref:`Xv/V4L <xvideo>` interface driver and a V4L2 application.
+ While the X server controls video overlay, the application can take
+ advantage of memory mapping and DMA.
+
+ In the opinion of the designers of this API, no driver writer taking
+ the efforts to support simultaneous capturing and overlay will
+ restrict this ability by requiring a single file descriptor, as in
+ V4L and earlier versions of V4L2. Making this optional means
+ applications depending on two file descriptors need backup routines
+ to be compatible with all drivers, which is considerable more work
+ than using two fds in applications which do not. Also two fd's fit
+ the general concept of one file descriptor for each logical stream.
+ Hence as a complexity trade-off drivers *must* support two file
+ descriptors and *may* support single fd operation.
+
+.. [2]
+ Should we require ``w.width`` to be a multiple of eight?
+
+.. [3]
+ When the image is written into frame buffer memory it will be
+ undesirable if the driver clips out less pixels than expected,
+ because the application and graphics system are not aware these
+ regions need to be refreshed. The driver should clip out more pixels
+ or not write the image at all.
+
+.. [4]
+ The X Window system defines "regions" which are vectors of ``struct
+ BoxRec { short x1, y1, x2, y2; }`` with ``width = x2 - x1`` and
+ ``height = y2 - y1``, so one cannot pass X11 clip lists directly.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _radio:
+
+***************
+Radio Interface
+***************
+
+This interface is intended for AM and FM (analog) radio receivers and
+transmitters.
+
+Conventionally V4L2 radio devices are accessed through character device
+special files named ``/dev/radio`` and ``/dev/radio0`` to
+``/dev/radio63`` with major number 81 and minor numbers 64 to 127.
+
+
+Querying Capabilities
+=====================
+
+Devices supporting the radio interface set the ``V4L2_CAP_RADIO`` and
+``V4L2_CAP_TUNER`` or ``V4L2_CAP_MODULATOR`` flag in the
+``capabilities`` field of struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP` ioctl. Other combinations of
+capability flags are reserved for future extensions.
+
+
+Supplemental Functions
+======================
+
+Radio devices can support :ref:`controls <control>`, and must support
+the :ref:`tuner or modulator <tuner>` ioctls.
+
+They do not support the video input or output, audio input or output,
+video standard, cropping and scaling, compression and streaming
+parameter, or overlay ioctls. All other ioctls and I/O methods are
+reserved for future extensions.
+
+
+Programming
+===========
+
+Radio devices may have a couple audio controls (as discussed in
+:ref:`control`) such as a volume control, possibly custom controls.
+Further all radio devices have one tuner or modulator (these are
+discussed in :ref:`tuner`) with index number zero to select the radio
+frequency and to determine if a monaural or FM stereo program is
+received/emitted. Drivers switch automatically between AM and FM
+depending on the selected frequency. The
+:ref:`VIDIOC_G_TUNER <VIDIOC_G_TUNER>` or
+:ref:`VIDIOC_G_MODULATOR <VIDIOC_G_MODULATOR>` ioctl reports the
+supported frequency range.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _raw-vbi:
+
+**********************
+Raw VBI Data Interface
+**********************
+
+VBI is an abbreviation of Vertical Blanking Interval, a gap in the
+sequence of lines of an analog video signal. During VBI no picture
+information is transmitted, allowing some time while the electron beam
+of a cathode ray tube TV returns to the top of the screen. Using an
+oscilloscope you will find here the vertical synchronization pulses and
+short data packages ASK modulated [1]_ onto the video signal. These are
+transmissions of services such as Teletext or Closed Caption.
+
+Subject of this interface type is raw VBI data, as sampled off a video
+signal, or to be added to a signal for output. The data format is
+similar to uncompressed video images, a number of lines times a number
+of samples per line, we call this a VBI image.
+
+Conventionally V4L2 VBI devices are accessed through character device
+special files named ``/dev/vbi`` and ``/dev/vbi0`` to ``/dev/vbi31``
+with major number 81 and minor numbers 224 to 255. ``/dev/vbi`` is
+typically a symbolic link to the preferred VBI device. This convention
+applies to both input and output devices.
+
+To address the problems of finding related video and VBI devices VBI
+capturing and output is also available as device function under
+``/dev/video``. To capture or output raw VBI data with these devices
+applications must call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
+Accessed as ``/dev/vbi``, raw VBI capturing or output is the default
+device function.
+
+
+Querying Capabilities
+=====================
+
+Devices supporting the raw VBI capturing or output API set the
+``V4L2_CAP_VBI_CAPTURE`` or ``V4L2_CAP_VBI_OUTPUT`` flags, respectively,
+in the ``capabilities`` field of struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP` ioctl. At least one of the
+read/write, streaming or asynchronous I/O methods must be supported. VBI
+devices may or may not have a tuner or modulator.
+
+
+Supplemental Functions
+======================
+
+VBI devices shall support :ref:`video input or output <video>`,
+:ref:`tuner or modulator <tuner>`, and :ref:`controls <control>`
+ioctls as needed. The :ref:`video standard <standard>` ioctls provide
+information vital to program a VBI device, therefore must be supported.
+
+
+Raw VBI Format Negotiation
+==========================
+
+Raw VBI sampling abilities can vary, in particular the sampling
+frequency. To properly interpret the data V4L2 specifies an ioctl to
+query the sampling parameters. Moreover, to allow for some flexibility
+applications can also suggest different parameters.
+
+As usual these parameters are *not* reset at :ref:`open() <func-open>`
+time to permit Unix tool chains, programming a device and then reading
+from it as if it was a plain file. Well written V4L2 applications should
+always ensure they really get what they want, requesting reasonable
+parameters and then checking if the actual parameters are suitable.
+
+To query the current raw VBI capture parameters applications set the
+``type`` field of a struct :ref:`v4l2_format <v4l2-format>` to
+``V4L2_BUF_TYPE_VBI_CAPTURE`` or ``V4L2_BUF_TYPE_VBI_OUTPUT``, and call
+the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl with a pointer to this
+structure. Drivers fill the struct
+:ref:`v4l2_vbi_format <v4l2-vbi-format>` ``vbi`` member of the
+``fmt`` union.
+
+To request different parameters applications set the ``type`` field of a
+struct :ref:`v4l2_format <v4l2-format>` as above and initialize all
+fields of the struct :ref:`v4l2_vbi_format <v4l2-vbi-format>`
+``vbi`` member of the ``fmt`` union, or better just modify the results
+of :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, and call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
+ioctl with a pointer to this structure. Drivers return an ``EINVAL`` error
+code only when the given parameters are ambiguous, otherwise they modify
+the parameters according to the hardware capabilities and return the
+actual parameters. When the driver allocates resources at this point, it
+may return an ``EBUSY`` error code to indicate the returned parameters are
+valid but the required resources are currently not available. That may
+happen for instance when the video and VBI areas to capture would
+overlap, or when the driver supports multiple opens and another process
+already requested VBI capturing or output. Anyway, applications must
+expect other resource allocation points which may return ``EBUSY``, at the
+:ref:`VIDIOC_STREAMON` ioctl and the first :ref:`read() <func-read>`
+, :ref:`write() <func-write>` and :ref:`select() <func-select>` calls.
+
+VBI devices must implement both the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
+:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ignores all requests
+and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does.
+:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional.
+
+
+.. _v4l2-vbi-format:
+
+.. flat-table:: struct v4l2_vbi_format
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``sampling_rate``
+
+ - Samples per second, i. e. unit 1 Hz.
+
+ - .. row 2
+
+ - __u32
+
+ - ``offset``
+
+ - Horizontal offset of the VBI image, relative to the leading edge
+ of the line synchronization pulse and counted in samples: The
+ first sample in the VBI image will be located ``offset`` /
+ ``sampling_rate`` seconds following the leading edge. See also
+ :ref:`vbi-hsync`.
+
+ - .. row 3
+
+ - __u32
+
+ - ``samples_per_line``
+
+ -
+
+ - .. row 4
+
+ - __u32
+
+ - ``sample_format``
+
+ - Defines the sample format as in :ref:`pixfmt`, a
+ four-character-code. [2]_ Usually this is ``V4L2_PIX_FMT_GREY``,
+ i. e. each sample consists of 8 bits with lower values oriented
+ towards the black level. Do not assume any other correlation of
+ values with the signal level. For example, the MSB does not
+ necessarily indicate if the signal is 'high' or 'low' because 128
+ may not be the mean value of the signal. Drivers shall not convert
+ the sample format by software.
+
+ - .. row 5
+
+ - __u32
+
+ - ``start``\ [2]_
+
+ - This is the scanning system line number associated with the first
+ line of the VBI image, of the first and the second field
+ respectively. See :ref:`vbi-525` and :ref:`vbi-625` for valid
+ values. The ``V4L2_VBI_ITU_525_F1_START``,
+ ``V4L2_VBI_ITU_525_F2_START``, ``V4L2_VBI_ITU_625_F1_START`` and
+ ``V4L2_VBI_ITU_625_F2_START`` defines give the start line numbers
+ for each field for each 525 or 625 line format as a convenience.
+ Don't forget that ITU line numbering starts at 1, not 0. VBI input
+ drivers can return start values 0 if the hardware cannot reliable
+ identify scanning lines, VBI acquisition may not require this
+ information.
+
+ - .. row 6
+
+ - __u32
+
+ - ``count``\ [2]_
+
+ - The number of lines in the first and second field image,
+ respectively.
+
+ - .. row 7
+
+ - :cspan:`2`
+
+ Drivers should be as flexibility as possible. For example, it may
+ be possible to extend or move the VBI capture window down to the
+ picture area, implementing a 'full field mode' to capture data
+ service transmissions embedded in the picture.
+
+ An application can set the first or second ``count`` value to zero
+ if no data is required from the respective field; ``count``\ [1]
+ if the scanning system is progressive, i. e. not interlaced. The
+ corresponding start value shall be ignored by the application and
+ driver. Anyway, drivers may not support single field capturing and
+ return both count values non-zero.
+
+ Both ``count`` values set to zero, or line numbers outside the
+ bounds depicted in :ref:`vbi-525` and :ref:`vbi-625`, or a
+ field image covering lines of two fields, are invalid and shall
+ not be returned by the driver.
+
+ To initialize the ``start`` and ``count`` fields, applications
+ must first determine the current video standard selection. The
+ :ref:`v4l2_std_id <v4l2-std-id>` or the ``framelines`` field
+ of struct :ref:`v4l2_standard <v4l2-standard>` can be evaluated
+ for this purpose.
+
+ - .. row 8
+
+ - __u32
+
+ - ``flags``
+
+ - See :ref:`vbifmt-flags` below. Currently only drivers set flags,
+ applications must set this field to zero.
+
+ - .. row 9
+
+ - __u32
+
+ - ``reserved``\ [2]_
+
+ - This array is reserved for future extensions. Drivers and
+ applications must set it to zero.
+
+
+
+.. _vbifmt-flags:
+
+.. flat-table:: Raw VBI Format Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_VBI_UNSYNC``
+
+ - 0x0001
+
+ - This flag indicates hardware which does not properly distinguish
+ between fields. Normally the VBI image stores the first field
+ (lower scanning line numbers) first in memory. This may be a top
+ or bottom field depending on the video standard. When this flag is
+ set the first or second field may be stored first, however the
+ fields are still in correct temporal order with the older field
+ first in memory. [3]_
+
+ - .. row 2
+
+ - ``V4L2_VBI_INTERLACED``
+
+ - 0x0002
+
+ - By default the two field images will be passed sequentially; all
+ lines of the first field followed by all lines of the second field
+ (compare :ref:`field-order` ``V4L2_FIELD_SEQ_TB`` and
+ ``V4L2_FIELD_SEQ_BT``, whether the top or bottom field is first in
+ memory depends on the video standard). When this flag is set, the
+ two fields are interlaced (cf. ``V4L2_FIELD_INTERLACED``). The
+ first line of the first field followed by the first line of the
+ second field, then the two second lines, and so on. Such a layout
+ may be necessary when the hardware has been programmed to capture
+ or output interlaced video images and is unable to separate the
+ fields for VBI capturing at the same time. For simplicity setting
+ this flag implies that both ``count`` values are equal and
+ non-zero.
+
+
+
+.. _vbi-hsync:
+
+.. figure:: dev-raw-vbi_files/vbi_hsync.*
+ :alt: vbi_hsync.pdf / vbi_hsync.gif
+ :align: center
+
+ **Figure 4.1. Line synchronization**
+
+
+.. _vbi-525:
+
+.. figure:: dev-raw-vbi_files/vbi_525.*
+ :alt: vbi_525.pdf / vbi_525.gif
+ :align: center
+
+ **Figure 4.2. ITU-R 525 line numbering (M/NTSC and M/PAL)**
+
+
+
+.. _vbi-625:
+
+.. figure:: dev-raw-vbi_files/vbi_625.*
+ :alt: vbi_625.pdf / vbi_625.gif
+ :align: center
+
+ **Figure 4.3. ITU-R 625 line numbering**
+
+
+
+Remember the VBI image format depends on the selected video standard,
+therefore the application must choose a new standard or query the
+current standard first. Attempts to read or write data ahead of format
+negotiation, or after switching the video standard which may invalidate
+the negotiated VBI parameters, should be refused by the driver. A format
+change during active I/O is not permitted.
+
+
+Reading and writing VBI images
+==============================
+
+To assure synchronization with the field number and easier
+implementation, the smallest unit of data passed at a time is one frame,
+consisting of two fields of VBI images immediately following in memory.
+
+The total size of a frame computes as follows:
+
+
+.. code-block:: c
+
+ (count[0] + count[1]) * samples_per_line * sample size in bytes
+
+The sample size is most likely always one byte, applications must check
+the ``sample_format`` field though, to function properly with other
+drivers.
+
+A VBI device may support :ref:`read/write <rw>` and/or streaming
+(:ref:`memory mapping <mmap>` or :ref:`user pointer <userp>`) I/O.
+The latter bears the possibility of synchronizing video and VBI data by
+using buffer timestamps.
+
+Remember the :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` ioctl and the
+first :ref:`read() <func-read>`, :ref:`write() <func-write>` and
+:ref:`select() <func-select>` call can be resource allocation
+points returning an ``EBUSY`` error code if the required hardware resources
+are temporarily unavailable, for example the device is already in use by
+another process.
+
+.. [1]
+ ASK: Amplitude-Shift Keying. A high signal level represents a '1'
+ bit, a low level a '0' bit.
+
+.. [2]
+ A few devices may be unable to sample VBI data at all but can extend
+ the video capture window to the VBI region.
+
+.. [3]
+ Most VBI services transmit on both fields, but some have different
+ semantics depending on the field number. These cannot be reliable
+ decoded or encoded when ``V4L2_VBI_UNSYNC`` is set.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _rds:
+
+*************
+RDS Interface
+*************
+
+The Radio Data System transmits supplementary information in binary
+format, for example the station name or travel information, on an
+inaudible audio subcarrier of a radio program. This interface is aimed
+at devices capable of receiving and/or transmitting RDS information.
+
+For more information see the core RDS standard :ref:`iec62106` and the
+RBDS standard :ref:`nrsc4`.
+
+Note that the RBDS standard as is used in the USA is almost identical to
+the RDS standard. Any RDS decoder/encoder can also handle RBDS. Only
+some of the fields have slightly different meanings. See the RBDS
+standard for more information.
+
+The RBDS standard also specifies support for MMBS (Modified Mobile
+Search). This is a proprietary format which seems to be discontinued.
+The RDS interface does not support this format. Should support for MMBS
+(or the so-called 'E blocks' in general) be needed, then please contact
+the linux-media mailing list:
+`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__.
+
+
+Querying Capabilities
+=====================
+
+Devices supporting the RDS capturing API set the
+``V4L2_CAP_RDS_CAPTURE`` flag in the ``capabilities`` field of struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP` ioctl. Any tuner that
+supports RDS will set the ``V4L2_TUNER_CAP_RDS`` flag in the
+``capability`` field of struct :ref:`v4l2_tuner <v4l2-tuner>`. If the
+driver only passes RDS blocks without interpreting the data the
+``V4L2_TUNER_CAP_RDS_BLOCK_IO`` flag has to be set, see
+:ref:`Reading RDS data <reading-rds-data>`. For future use the flag
+``V4L2_TUNER_CAP_RDS_CONTROLS`` has also been defined. However, a driver
+for a radio tuner with this capability does not yet exist, so if you are
+planning to write such a driver you should discuss this on the
+linux-media mailing list:
+`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__.
+
+Whether an RDS signal is present can be detected by looking at the
+``rxsubchans`` field of struct :ref:`v4l2_tuner <v4l2-tuner>`: the
+``V4L2_TUNER_SUB_RDS`` will be set if RDS data was detected.
+
+Devices supporting the RDS output API set the ``V4L2_CAP_RDS_OUTPUT``
+flag in the ``capabilities`` field of struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP` ioctl. Any modulator that
+supports RDS will set the ``V4L2_TUNER_CAP_RDS`` flag in the
+``capability`` field of struct
+:ref:`v4l2_modulator <v4l2-modulator>`. In order to enable the RDS
+transmission one must set the ``V4L2_TUNER_SUB_RDS`` bit in the
+``txsubchans`` field of struct
+:ref:`v4l2_modulator <v4l2-modulator>`. If the driver only passes RDS
+blocks without interpreting the data the ``V4L2_TUNER_CAP_RDS_BLOCK_IO``
+flag has to be set. If the tuner is capable of handling RDS entities
+like program identification codes and radio text, the flag
+``V4L2_TUNER_CAP_RDS_CONTROLS`` should be set, see
+:ref:`Writing RDS data <writing-rds-data>` and
+:ref:`FM Transmitter Control Reference <fm-tx-controls>`.
+
+
+.. _reading-rds-data:
+
+Reading RDS data
+================
+
+RDS data can be read from the radio device with the
+:ref:`read() <func-read>` function. The data is packed in groups of
+three bytes.
+
+
+.. _writing-rds-data:
+
+Writing RDS data
+================
+
+RDS data can be written to the radio device with the
+:ref:`write() <func-write>` function. The data is packed in groups of
+three bytes, as follows:
+
+
+RDS datastructures
+==================
+
+
+.. _v4l2-rds-data:
+
+.. flat-table:: struct v4l2_rds_data
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 5
+
+
+ - .. row 1
+
+ - __u8
+
+ - ``lsb``
+
+ - Least Significant Byte of RDS Block
+
+ - .. row 2
+
+ - __u8
+
+ - ``msb``
+
+ - Most Significant Byte of RDS Block
+
+ - .. row 3
+
+ - __u8
+
+ - ``block``
+
+ - Block description
+
+
+
+.. _v4l2-rds-block:
+
+.. flat-table:: Block description
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 5
+
+
+ - .. row 1
+
+ - Bits 0-2
+
+ - Block (aka offset) of the received data.
+
+ - .. row 2
+
+ - Bits 3-5
+
+ - Deprecated. Currently identical to bits 0-2. Do not use these
+ bits.
+
+ - .. row 3
+
+ - Bit 6
+
+ - Corrected bit. Indicates that an error was corrected for this data
+ block.
+
+ - .. row 4
+
+ - Bit 7
+
+ - Error bit. Indicates that an uncorrectable error occurred during
+ reception of this block.
+
+
+
+.. _v4l2-rds-block-codes:
+
+.. flat-table:: Block defines
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 1 5
+
+
+ - .. row 1
+
+ - V4L2_RDS_BLOCK_MSK
+
+ -
+ - 7
+
+ - Mask for bits 0-2 to get the block ID.
+
+ - .. row 2
+
+ - V4L2_RDS_BLOCK_A
+
+ -
+ - 0
+
+ - Block A.
+
+ - .. row 3
+
+ - V4L2_RDS_BLOCK_B
+
+ -
+ - 1
+
+ - Block B.
+
+ - .. row 4
+
+ - V4L2_RDS_BLOCK_C
+
+ -
+ - 2
+
+ - Block C.
+
+ - .. row 5
+
+ - V4L2_RDS_BLOCK_D
+
+ -
+ - 3
+
+ - Block D.
+
+ - .. row 6
+
+ - V4L2_RDS_BLOCK_C_ALT
+
+ -
+ - 4
+
+ - Block C'.
+
+ - .. row 7
+
+ - V4L2_RDS_BLOCK_INVALID
+
+ - read-only
+
+ - 7
+
+ - An invalid block.
+
+ - .. row 8
+
+ - V4L2_RDS_BLOCK_CORRECTED
+
+ - read-only
+
+ - 0x40
+
+ - A bit error was detected but corrected.
+
+ - .. row 9
+
+ - V4L2_RDS_BLOCK_ERROR
+
+ - read-only
+
+ - 0x80
+
+ - An uncorrectable error occurred.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _sdr:
+
+**************************************
+Software Defined Radio Interface (SDR)
+**************************************
+
+SDR is an abbreviation of Software Defined Radio, the radio device which
+uses application software for modulation or demodulation. This interface
+is intended for controlling and data streaming of such devices.
+
+SDR devices are accessed through character device special files named
+``/dev/swradio0`` to ``/dev/swradio255`` with major number 81 and
+dynamically allocated minor numbers 0 to 255.
+
+
+Querying Capabilities
+=====================
+
+Devices supporting the SDR receiver interface set the
+``V4L2_CAP_SDR_CAPTURE`` and ``V4L2_CAP_TUNER`` flag in the
+``capabilities`` field of struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP` ioctl. That flag means the
+device has an Analog to Digital Converter (ADC), which is a mandatory
+element for the SDR receiver.
+
+Devices supporting the SDR transmitter interface set the
+``V4L2_CAP_SDR_OUTPUT`` and ``V4L2_CAP_MODULATOR`` flag in the
+``capabilities`` field of struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP` ioctl. That flag means the
+device has an Digital to Analog Converter (DAC), which is a mandatory
+element for the SDR transmitter.
+
+At least one of the read/write, streaming or asynchronous I/O methods
+must be supported.
+
+
+Supplemental Functions
+======================
+
+SDR devices can support :ref:`controls <control>`, and must support
+the :ref:`tuner` ioctls. Tuner ioctls are used for setting the
+ADC/DAC sampling rate (sampling frequency) and the possible radio
+frequency (RF).
+
+The ``V4L2_TUNER_SDR`` tuner type is used for setting SDR device ADC/DAC
+frequency, and the ``V4L2_TUNER_RF`` tuner type is used for setting
+radio frequency. The tuner index of the RF tuner (if any) must always
+follow the SDR tuner index. Normally the SDR tuner is #0 and the RF
+tuner is #1.
+
+The :ref:`VIDIOC_S_HW_FREQ_SEEK` ioctl is
+not supported.
+
+
+Data Format Negotiation
+=======================
+
+The SDR device uses the :ref:`format` ioctls to select the
+capture and output format. Both the sampling resolution and the data
+streaming format are bound to that selectable format. In addition to the
+basic :ref:`format` ioctls, the
+:ref:`VIDIOC_ENUM_FMT` ioctl must be supported as
+well.
+
+To use the :ref:`format` ioctls applications set the ``type``
+field of a struct :ref:`v4l2_format <v4l2-format>` to
+``V4L2_BUF_TYPE_SDR_CAPTURE`` or ``V4L2_BUF_TYPE_SDR_OUTPUT`` and use
+the struct :ref:`v4l2_sdr_format <v4l2-sdr-format>` ``sdr`` member
+of the ``fmt`` union as needed per the desired operation. Currently
+there is two fields, ``pixelformat`` and ``buffersize``, of struct
+struct :ref:`v4l2_sdr_format <v4l2-sdr-format>` which are used.
+Content of the ``pixelformat`` is V4L2 FourCC code of the data format.
+The ``buffersize`` field is maximum buffer size in bytes required for
+data transfer, set by the driver in order to inform application.
+
+
+.. _v4l2-sdr-format:
+
+.. flat-table:: struct v4l2_sdr_format
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``pixelformat``
+
+ - The data format or type of compression, set by the application.
+ This is a little endian
+ :ref:`four character code <v4l2-fourcc>`. V4L2 defines SDR
+ formats in :ref:`sdr-formats`.
+
+ - .. row 2
+
+ - __u32
+
+ - ``buffersize``
+
+ - Maximum size in bytes required for data. Value is set by the
+ driver.
+
+ - .. row 3
+
+ - __u8
+
+ - ``reserved[24]``
+
+ - This array is reserved for future extensions. Drivers and
+ applications must set it to zero.
+
+
+An SDR device may support :ref:`read/write <rw>` and/or streaming
+(:ref:`memory mapping <mmap>` or :ref:`user pointer <userp>`) I/O.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _sliced:
+
+*************************
+Sliced VBI Data Interface
+*************************
+
+VBI stands for Vertical Blanking Interval, a gap in the sequence of
+lines of an analog video signal. During VBI no picture information is
+transmitted, allowing some time while the electron beam of a cathode ray
+tube TV returns to the top of the screen.
+
+Sliced VBI devices use hardware to demodulate data transmitted in the
+VBI. V4L2 drivers shall *not* do this by software, see also the
+:ref:`raw VBI interface <raw-vbi>`. The data is passed as short
+packets of fixed size, covering one scan line each. The number of
+packets per video frame is variable.
+
+Sliced VBI capture and output devices are accessed through the same
+character special files as raw VBI devices. When a driver supports both
+interfaces, the default function of a ``/dev/vbi`` device is *raw* VBI
+capturing or output, and the sliced VBI function is only available after
+calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl as defined
+below. Likewise a ``/dev/video`` device may support the sliced VBI API,
+however the default function here is video capturing or output.
+Different file descriptors must be used to pass raw and sliced VBI data
+simultaneously, if this is supported by the driver.
+
+
+Querying Capabilities
+=====================
+
+Devices supporting the sliced VBI capturing or output API set the
+``V4L2_CAP_SLICED_VBI_CAPTURE`` or ``V4L2_CAP_SLICED_VBI_OUTPUT`` flag
+respectively, in the ``capabilities`` field of struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP` ioctl. At least one of the
+read/write, streaming or asynchronous :ref:`I/O methods <io>` must be
+supported. Sliced VBI devices may have a tuner or modulator.
+
+
+Supplemental Functions
+======================
+
+Sliced VBI devices shall support :ref:`video input or output <video>`
+and :ref:`tuner or modulator <tuner>` ioctls if they have these
+capabilities, and they may support :ref:`control` ioctls.
+The :ref:`video standard <standard>` ioctls provide information vital
+to program a sliced VBI device, therefore must be supported.
+
+
+.. _sliced-vbi-format-negotitation:
+
+Sliced VBI Format Negotiation
+=============================
+
+To find out which data services are supported by the hardware
+applications can call the
+:ref:`VIDIOC_G_SLICED_VBI_CAP <VIDIOC_G_SLICED_VBI_CAP>` ioctl.
+All drivers implementing the sliced VBI interface must support this
+ioctl. The results may differ from those of the
+:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl when the number of VBI
+lines the hardware can capture or output per frame, or the number of
+services it can identify on a given line are limited. For example on PAL
+line 16 the hardware may be able to look for a VPS or Teletext signal,
+but not both at the same time.
+
+To determine the currently selected services applications set the
+``type`` field of struct :ref:`v4l2_format <v4l2-format>` to
+``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE`` or
+``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT``, and the
+:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl fills the ``fmt.sliced``
+member, a struct
+:ref:`v4l2_sliced_vbi_format <v4l2-sliced-vbi-format>`.
+
+Applications can request different parameters by initializing or
+modifying the ``fmt.sliced`` member and calling the
+:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with a pointer to the
+:ref:`struct v4l2_format <v4l2-format>` structure.
+
+The sliced VBI API is more complicated than the raw VBI API because the
+hardware must be told which VBI service to expect on each scan line. Not
+all services may be supported by the hardware on all lines (this is
+especially true for VBI output where Teletext is often unsupported and
+other services can only be inserted in one specific line). In many
+cases, however, it is sufficient to just set the ``service_set`` field
+to the required services and let the driver fill the ``service_lines``
+array according to hardware capabilities. Only if more precise control
+is needed should the programmer set the ``service_lines`` array
+explicitly.
+
+The :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl modifies the parameters
+according to hardware capabilities. When the driver allocates resources
+at this point, it may return an ``EBUSY`` error code if the required
+resources are temporarily unavailable. Other resource allocation points
+which may return ``EBUSY`` can be the
+:ref:`VIDIOC_STREAMON` ioctl and the first
+:ref:`read() <func-read>`, :ref:`write() <func-write>` and
+:ref:`select() <func-select>` call.
+
+
+.. _v4l2-sliced-vbi-format:
+
+struct v4l2_sliced_vbi_format
+-----------------------------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 3 2 2 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``service_set``
+
+ - :cspan:`2`
+
+ If ``service_set`` is non-zero when passed with
+ :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` or
+ :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>`, the ``service_lines``
+ array will be filled by the driver according to the services
+ specified in this field. For example, if ``service_set`` is
+ initialized with ``V4L2_SLICED_TELETEXT_B | V4L2_SLICED_WSS_625``,
+ a driver for the cx25840 video decoder sets lines 7-22 of both
+ fields [1]_ to ``V4L2_SLICED_TELETEXT_B`` and line 23 of the first
+ field to ``V4L2_SLICED_WSS_625``. If ``service_set`` is set to
+ zero, then the values of ``service_lines`` will be used instead.
+
+ On return the driver sets this field to the union of all elements
+ of the returned ``service_lines`` array. It may contain less
+ services than requested, perhaps just one, if the hardware cannot
+ handle more services simultaneously. It may be empty (zero) if
+ none of the requested services are supported by the hardware.
+
+ - .. row 2
+
+ - __u16
+
+ - ``service_lines``\ [2][24]
+
+ - :cspan:`2`
+
+ Applications initialize this array with sets of data services the
+ driver shall look for or insert on the respective scan line.
+ Subject to hardware capabilities drivers return the requested set,
+ a subset, which may be just a single service, or an empty set.
+ When the hardware cannot handle multiple services on the same line
+ the driver shall choose one. No assumptions can be made on which
+ service the driver chooses.
+
+ Data services are defined in :ref:`vbi-services2`. Array indices
+ map to ITU-R line numbers (see also :ref:`vbi-525` and
+ :ref:`vbi-625`) as follows:
+
+ - .. row 3
+
+ -
+ -
+ - Element
+
+ - 525 line systems
+
+ - 625 line systems
+
+ - .. row 4
+
+ -
+ -
+ - ``service_lines``\ [0][1]
+
+ - 1
+
+ - 1
+
+ - .. row 5
+
+ -
+ -
+ - ``service_lines``\ [0][23]
+
+ - 23
+
+ - 23
+
+ - .. row 6
+
+ -
+ -
+ - ``service_lines``\ [1][1]
+
+ - 264
+
+ - 314
+
+ - .. row 7
+
+ -
+ -
+ - ``service_lines``\ [1][23]
+
+ - 286
+
+ - 336
+
+ - .. row 8
+
+ -
+ -
+ - :cspan:`2` Drivers must set ``service_lines`` [0][0] and
+ ``service_lines``\ [1][0] to zero. The
+ ``V4L2_VBI_ITU_525_F1_START``, ``V4L2_VBI_ITU_525_F2_START``,
+ ``V4L2_VBI_ITU_625_F1_START`` and ``V4L2_VBI_ITU_625_F2_START``
+ defines give the start line numbers for each field for each 525 or
+ 625 line format as a convenience. Don't forget that ITU line
+ numbering starts at 1, not 0.
+
+ - .. row 9
+
+ - __u32
+
+ - ``io_size``
+
+ - :cspan:`2` Maximum number of bytes passed by one
+ :ref:`read() <func-read>` or :ref:`write() <func-write>` call,
+ and the buffer size in bytes for the
+ :ref:`VIDIOC_QBUF` and
+ :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. Drivers set this field
+ to the size of struct
+ :ref:`v4l2_sliced_vbi_data <v4l2-sliced-vbi-data>` times the
+ number of non-zero elements in the returned ``service_lines``
+ array (that is the number of lines potentially carrying data).
+
+ - .. row 10
+
+ - __u32
+
+ - ``reserved``\ [2]
+
+ - :cspan:`2` This array is reserved for future extensions.
+ Applications and drivers must set it to zero.
+
+
+
+.. _vbi-services2:
+
+Sliced VBI services
+-------------------
+
+.. flat-table::
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 2 1 1 2 2
+
+
+ - .. row 1
+
+ - Symbol
+
+ - Value
+
+ - Reference
+
+ - Lines, usually
+
+ - Payload
+
+ - .. row 2
+
+ - ``V4L2_SLICED_TELETEXT_B`` (Teletext System B)
+
+ - 0x0001
+
+ - :ref:`ets300706`, :ref:`itu653`
+
+ - PAL/SECAM line 7-22, 320-335 (second field 7-22)
+
+ - Last 42 of the 45 byte Teletext packet, that is without clock
+ run-in and framing code, lsb first transmitted.
+
+ - .. row 3
+
+ - ``V4L2_SLICED_VPS``
+
+ - 0x0400
+
+ - :ref:`ets300231`
+
+ - PAL line 16
+
+ - Byte number 3 to 15 according to Figure 9 of ETS 300 231, lsb
+ first transmitted.
+
+ - .. row 4
+
+ - ``V4L2_SLICED_CAPTION_525``
+
+ - 0x1000
+
+ - :ref:`cea608`
+
+ - NTSC line 21, 284 (second field 21)
+
+ - Two bytes in transmission order, including parity bit, lsb first
+ transmitted.
+
+ - .. row 5
+
+ - ``V4L2_SLICED_WSS_625``
+
+ - 0x4000
+
+ - :ref:`itu1119`, :ref:`en300294`
+
+ - PAL/SECAM line 23
+
+ -
+
+ ::
+
+ Byte 0 1
+ msb lsb msb lsb
+ Bit 7 6 5 4 3 2 1 0 x x 13 12 11 10 9
+
+ - .. row 6
+
+ - ``V4L2_SLICED_VBI_525``
+
+ - 0x1000
+
+ - :cspan:`2` Set of services applicable to 525 line systems.
+
+ - .. row 7
+
+ - ``V4L2_SLICED_VBI_625``
+
+ - 0x4401
+
+ - :cspan:`2` Set of services applicable to 625 line systems.
+
+
+Drivers may return an ``EINVAL`` error code when applications attempt to
+read or write data without prior format negotiation, after switching the
+video standard (which may invalidate the negotiated VBI parameters) and
+after switching the video input (which may change the video standard as
+a side effect). The :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl may
+return an ``EBUSY`` error code when applications attempt to change the
+format while i/o is in progress (between a
+:ref:`VIDIOC_STREAMON` and
+:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` call, and after the first
+:ref:`read() <func-read>` or :ref:`write() <func-write>` call).
+
+
+Reading and writing sliced VBI data
+===================================
+
+A single :ref:`read() <func-read>` or :ref:`write() <func-write>`
+call must pass all data belonging to one video frame. That is an array
+of :ref:`struct v4l2_sliced_vbi_data <v4l2-sliced-vbi-data>` structures with one or
+more elements and a total size not exceeding ``io_size`` bytes. Likewise
+in streaming I/O mode one buffer of ``io_size`` bytes must contain data
+of one video frame. The ``id`` of unused
+:ref:`struct v4l2_sliced_vbi_data <v4l2-sliced-vbi-data>` elements must be zero.
+
+
+.. _v4l2-sliced-vbi-data:
+
+struct v4l2_sliced_vbi_data
+---------------------------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``id``
+
+ - A flag from :ref:`vbi-services` identifying the type of data in
+ this packet. Only a single bit must be set. When the ``id`` of a
+ captured packet is zero, the packet is empty and the contents of
+ other fields are undefined. Applications shall ignore empty
+ packets. When the ``id`` of a packet for output is zero the
+ contents of the ``data`` field are undefined and the driver must
+ no longer insert data on the requested ``field`` and ``line``.
+
+ - .. row 2
+
+ - __u32
+
+ - ``field``
+
+ - The video field number this data has been captured from, or shall
+ be inserted at. ``0`` for the first field, ``1`` for the second
+ field.
+
+ - .. row 3
+
+ - __u32
+
+ - ``line``
+
+ - The field (as opposed to frame) line number this data has been
+ captured from, or shall be inserted at. See :ref:`vbi-525` and
+ :ref:`vbi-625` for valid values. Sliced VBI capture devices can
+ set the line number of all packets to ``0`` if the hardware cannot
+ reliably identify scan lines. The field number must always be
+ valid.
+
+ - .. row 4
+
+ - __u32
+
+ - ``reserved``
+
+ - This field is reserved for future extensions. Applications and
+ drivers must set it to zero.
+
+ - .. row 5
+
+ - __u8
+
+ - ``data``\ [48]
+
+ - The packet payload. See :ref:`vbi-services` for the contents and
+ number of bytes passed for each data type. The contents of padding
+ bytes at the end of this array are undefined, drivers and
+ applications shall ignore them.
+
+
+Packets are always passed in ascending line number order, without
+duplicate line numbers. The :ref:`write() <func-write>` function and
+the :ref:`VIDIOC_QBUF` ioctl must return an ``EINVAL``
+error code when applications violate this rule. They must also return an
+EINVAL error code when applications pass an incorrect field or line
+number, or a combination of ``field``, ``line`` and ``id`` which has not
+been negotiated with the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` or
+:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. When the line numbers are
+unknown the driver must pass the packets in transmitted order. The
+driver can insert empty packets with ``id`` set to zero anywhere in the
+packet array.
+
+To assure synchronization and to distinguish from frame dropping, when a
+captured frame does not carry any of the requested data services drivers
+must pass one or more empty packets. When an application fails to pass
+VBI data in time for output, the driver must output the last VPS and WSS
+packet again, and disable the output of Closed Caption and Teletext
+data, or output data which is ignored by Closed Caption and Teletext
+decoders.
+
+A sliced VBI device may support :ref:`read/write <rw>` and/or
+streaming (:ref:`memory mapping <mmap>` and/or
+:ref:`user pointer <userp>`) I/O. The latter bears the possibility of
+synchronizing video and VBI data by using buffer timestamps.
+
+
+Sliced VBI Data in MPEG Streams
+===============================
+
+If a device can produce an MPEG output stream, it may be capable of
+providing
+:ref:`negotiated sliced VBI services <sliced-vbi-format-negotitation>`
+as data embedded in the MPEG stream. Users or applications control this
+sliced VBI data insertion with the
+:ref:`V4L2_CID_MPEG_STREAM_VBI_FMT <v4l2-mpeg-stream-vbi-fmt>`
+control.
+
+If the driver does not provide the
+:ref:`V4L2_CID_MPEG_STREAM_VBI_FMT <v4l2-mpeg-stream-vbi-fmt>`
+control, or only allows that control to be set to
+:ref:`V4L2_MPEG_STREAM_VBI_FMT_NONE <v4l2-mpeg-stream-vbi-fmt>`,
+then the device cannot embed sliced VBI data in the MPEG stream.
+
+The
+:ref:`V4L2_CID_MPEG_STREAM_VBI_FMT <v4l2-mpeg-stream-vbi-fmt>`
+control does not implicitly set the device driver to capture nor cease
+capturing sliced VBI data. The control only indicates to embed sliced
+VBI data in the MPEG stream, if an application has negotiated sliced VBI
+service be captured.
+
+It may also be the case that a device can embed sliced VBI data in only
+certain types of MPEG streams: for example in an MPEG-2 PS but not an
+MPEG-2 TS. In this situation, if sliced VBI data insertion is requested,
+the sliced VBI data will be embedded in MPEG stream types when
+supported, and silently omitted from MPEG stream types where sliced VBI
+data insertion is not supported by the device.
+
+The following subsections specify the format of the embedded sliced VBI
+data.
+
+
+MPEG Stream Embedded, Sliced VBI Data Format: NONE
+--------------------------------------------------
+
+The
+:ref:`V4L2_MPEG_STREAM_VBI_FMT_NONE <v4l2-mpeg-stream-vbi-fmt>`
+embedded sliced VBI format shall be interpreted by drivers as a control
+to cease embedding sliced VBI data in MPEG streams. Neither the device
+nor driver shall insert "empty" embedded sliced VBI data packets in the
+MPEG stream when this format is set. No MPEG stream data structures are
+specified for this format.
+
+
+MPEG Stream Embedded, Sliced VBI Data Format: IVTV
+--------------------------------------------------
+
+The
+:ref:`V4L2_MPEG_STREAM_VBI_FMT_IVTV <v4l2-mpeg-stream-vbi-fmt>`
+embedded sliced VBI format, when supported, indicates to the driver to
+embed up to 36 lines of sliced VBI data per frame in an MPEG-2 *Private
+Stream 1 PES* packet encapsulated in an MPEG-2 *Program Pack* in the
+MPEG stream.
+
+*Historical context*: This format specification originates from a
+custom, embedded, sliced VBI data format used by the ``ivtv`` driver.
+This format has already been informally specified in the kernel sources
+in the file ``Documentation/video4linux/cx2341x/README.vbi`` . The
+maximum size of the payload and other aspects of this format are driven
+by the CX23415 MPEG decoder's capabilities and limitations with respect
+to extracting, decoding, and displaying sliced VBI data embedded within
+an MPEG stream.
+
+This format's use is *not* exclusive to the ``ivtv`` driver *nor*
+exclusive to CX2341x devices, as the sliced VBI data packet insertion
+into the MPEG stream is implemented in driver software. At least the
+``cx18`` driver provides sliced VBI data insertion into an MPEG-2 PS in
+this format as well.
+
+The following definitions specify the payload of the MPEG-2 *Private
+Stream 1 PES* packets that contain sliced VBI data when
+:ref:`V4L2_MPEG_STREAM_VBI_FMT_IVTV <v4l2-mpeg-stream-vbi-fmt>`
+is set. (The MPEG-2 *Private Stream 1 PES* packet header and
+encapsulating MPEG-2 *Program Pack* header are not detailed here. Please
+refer to the MPEG-2 specifications for details on those packet headers.)
+
+The payload of the MPEG-2 *Private Stream 1 PES* packets that contain
+sliced VBI data is specified by struct
+:ref:`v4l2_mpeg_vbi_fmt_ivtv <v4l2-mpeg-vbi-fmt-ivtv>`. The
+payload is variable length, depending on the actual number of lines of
+sliced VBI data present in a video frame. The payload may be padded at
+the end with unspecified fill bytes to align the end of the payload to a
+4-byte boundary. The payload shall never exceed 1552 bytes (2 fields
+with 18 lines/field with 43 bytes of data/line and a 4 byte magic
+number).
+
+
+.. _v4l2-mpeg-vbi-fmt-ivtv:
+
+struct v4l2_mpeg_vbi_fmt_ivtv
+-----------------------------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 1 2
+
+
+ - .. row 1
+
+ - __u8
+
+ - ``magic``\ [4]
+
+ -
+ - A "magic" constant from :ref:`v4l2-mpeg-vbi-fmt-ivtv-magic` that
+ indicates this is a valid sliced VBI data payload and also
+ indicates which member of the anonymous union, ``itv0`` or
+ ``ITV0``, to use for the payload data.
+
+ - .. row 2
+
+ - union
+
+ - (anonymous)
+
+ - .. row 3
+
+ -
+ - struct :ref:`v4l2_mpeg_vbi_itv0 <v4l2-mpeg-vbi-itv0>`
+
+ - ``itv0``
+
+ - The primary form of the sliced VBI data payload that contains
+ anywhere from 1 to 35 lines of sliced VBI data. Line masks are
+ provided in this form of the payload indicating which VBI lines
+ are provided.
+
+ - .. row 4
+
+ -
+ - struct :ref:`v4l2_mpeg_vbi_ITV0 <v4l2-mpeg-vbi-itv0-1>`
+
+ - ``ITV0``
+
+ - An alternate form of the sliced VBI data payload used when 36
+ lines of sliced VBI data are present. No line masks are provided
+ in this form of the payload; all valid line mask bits are
+ implcitly set.
+
+
+
+.. _v4l2-mpeg-vbi-fmt-ivtv-magic:
+
+Magic Constants for struct v4l2_mpeg_vbi_fmt_ivtv magic field
+-------------------------------------------------------------
+
+.. flat-table::
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - Defined Symbol
+
+ - Value
+
+ - Description
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VBI_IVTV_MAGIC0``
+
+ - "itv0"
+
+ - Indicates the ``itv0`` member of the union in struct
+ :ref:`v4l2_mpeg_vbi_fmt_ivtv <v4l2-mpeg-vbi-fmt-ivtv>` is
+ valid.
+
+ - .. row 3
+
+ - ``V4L2_MPEG_VBI_IVTV_MAGIC1``
+
+ - "ITV0"
+
+ - Indicates the ``ITV0`` member of the union in struct
+ :ref:`v4l2_mpeg_vbi_fmt_ivtv <v4l2-mpeg-vbi-fmt-ivtv>` is
+ valid and that 36 lines of sliced VBI data are present.
+
+
+
+.. _v4l2-mpeg-vbi-itv0:
+
+struct v4l2_mpeg_vbi_itv0
+-------------------------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __le32
+
+ - ``linemask``\ [2]
+
+ - Bitmasks indicating the VBI service lines present. These
+ ``linemask`` values are stored in little endian byte order in the
+ MPEG stream. Some reference ``linemask`` bit positions with their
+ corresponding VBI line number and video field are given below.
+ b\ :sub:`0` indicates the least significant bit of a ``linemask``
+ value:
+
+
+
+ ::
+
+ linemask[0] b0: line 6 first field
+ linemask[0] b17: line 23 first field
+ linemask[0] b18: line 6 second field
+ linemask[0] b31: line 19 second field
+ linemask[1] b0: line 20 second field
+ linemask[1] b3: line 23 second field
+ linemask[1] b4-b31: unused and set to 0
+
+ - .. row 2
+
+ - struct
+ :ref:`v4l2_mpeg_vbi_itv0_line <v4l2-mpeg-vbi-itv0-line>`
+
+ - ``line``\ [35]
+
+ - This is a variable length array that holds from 1 to 35 lines of
+ sliced VBI data. The sliced VBI data lines present correspond to
+ the bits set in the ``linemask`` array, starting from b\ :sub:`0`
+ of ``linemask``\ [0] up through b\ :sub:`31` of ``linemask``\ [0],
+ and from b\ :sub:`0` of ``linemask``\ [1] up through b\ :sub:`3` of
+ ``linemask``\ [1]. ``line``\ [0] corresponds to the first bit
+ found set in the ``linemask`` array, ``line``\ [1] corresponds to
+ the second bit found set in the ``linemask`` array, etc. If no
+ ``linemask`` array bits are set, then ``line``\ [0] may contain
+ one line of unspecified data that should be ignored by
+ applications.
+
+
+
+.. _v4l2-mpeg-vbi-itv0-1:
+
+struct v4l2_mpeg_vbi_ITV0
+-------------------------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - struct
+ :ref:`v4l2_mpeg_vbi_itv0_line <v4l2-mpeg-vbi-itv0-line>`
+
+ - ``line``\ [36]
+
+ - A fixed length array of 36 lines of sliced VBI data. ``line``\ [0]
+ through ``line``\ [17] correspond to lines 6 through 23 of the
+ first field. ``line``\ [18] through ``line``\ [35] corresponds to
+ lines 6 through 23 of the second field.
+
+
+
+.. _v4l2-mpeg-vbi-itv0-line:
+
+struct v4l2_mpeg_vbi_itv0_line
+------------------------------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u8
+
+ - ``id``
+
+ - A line identifier value from
+ :ref:`ITV0-Line-Identifier-Constants` that indicates the type of
+ sliced VBI data stored on this line.
+
+ - .. row 2
+
+ - __u8
+
+ - ``data``\ [42]
+
+ - The sliced VBI data for the line.
+
+
+
+.. _ITV0-Line-Identifier-Constants:
+
+Line Identifiers for struct v4l2_mpeg_vbi_itv0_line id field
+------------------------------------------------------------
+
+.. flat-table::
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - Defined Symbol
+
+ - Value
+
+ - Description
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VBI_IVTV_TELETEXT_B``
+
+ - 1
+
+ - Refer to :ref:`Sliced VBI services <vbi-services2>` for a
+ description of the line payload.
+
+ - .. row 3
+
+ - ``V4L2_MPEG_VBI_IVTV_CAPTION_525``
+
+ - 4
+
+ - Refer to :ref:`Sliced VBI services <vbi-services2>` for a
+ description of the line payload.
+
+ - .. row 4
+
+ - ``V4L2_MPEG_VBI_IVTV_WSS_625``
+
+ - 5
+
+ - Refer to :ref:`Sliced VBI services <vbi-services2>` for a
+ description of the line payload.
+
+ - .. row 5
+
+ - ``V4L2_MPEG_VBI_IVTV_VPS``
+
+ - 7
+
+ - Refer to :ref:`Sliced VBI services <vbi-services2>` for a
+ description of the line payload.
+
+
+
+.. [1]
+ According to :ref:`ETS 300 706 <ets300706>` lines 6-22 of the first
+ field and lines 5-22 of the second field may carry Teletext data.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _subdev:
+
+********************
+Sub-device Interface
+********************
+
+The complex nature of V4L2 devices, where hardware is often made of
+several integrated circuits that need to interact with each other in a
+controlled way, leads to complex V4L2 drivers. The drivers usually
+reflect the hardware model in software, and model the different hardware
+components as software blocks called sub-devices.
+
+V4L2 sub-devices are usually kernel-only objects. If the V4L2 driver
+implements the media device API, they will automatically inherit from
+media entities. Applications will be able to enumerate the sub-devices
+and discover the hardware topology using the media entities, pads and
+links enumeration API.
+
+In addition to make sub-devices discoverable, drivers can also choose to
+make them directly configurable by applications. When both the
+sub-device driver and the V4L2 device driver support this, sub-devices
+will feature a character device node on which ioctls can be called to
+
+- query, read and write sub-devices controls
+
+- subscribe and unsubscribe to events and retrieve them
+
+- negotiate image formats on individual pads
+
+Sub-device character device nodes, conventionally named
+``/dev/v4l-subdev*``, use major number 81.
+
+
+Controls
+========
+
+Most V4L2 controls are implemented by sub-device hardware. Drivers
+usually merge all controls and expose them through video device nodes.
+Applications can control all sub-devices through a single interface.
+
+Complex devices sometimes implement the same control in different pieces
+of hardware. This situation is common in embedded platforms, where both
+sensors and image processing hardware implement identical functions,
+such as contrast adjustment, white balance or faulty pixels correction.
+As the V4L2 controls API doesn't support several identical controls in a
+single device, all but one of the identical controls are hidden.
+
+Applications can access those hidden controls through the sub-device
+node with the V4L2 control API described in :ref:`control`. The ioctls
+behave identically as when issued on V4L2 device nodes, with the
+exception that they deal only with controls implemented in the
+sub-device.
+
+Depending on the driver, those controls might also be exposed through
+one (or several) V4L2 device nodes.
+
+
+Events
+======
+
+V4L2 sub-devices can notify applications of events as described in
+:ref:`event`. The API behaves identically as when used on V4L2 device
+nodes, with the exception that it only deals with events generated by
+the sub-device. Depending on the driver, those events might also be
+reported on one (or several) V4L2 device nodes.
+
+
+.. _pad-level-formats:
+
+Pad-level Formats
+=================
+
+ **Warning**
+
+ Pad-level formats are only applicable to very complex device that
+ need to expose low-level format configuration to user space. Generic
+ V4L2 applications do *not* need to use the API described in this
+ section.
+
+ **Note**
+
+ For the purpose of this section, the term *format* means the
+ combination of media bus data format, frame width and frame height.
+
+Image formats are typically negotiated on video capture and output
+devices using the format and
+:ref:`selection <VIDIOC_SUBDEV_G_SELECTION>` ioctls. The driver is
+responsible for configuring every block in the video pipeline according
+to the requested format at the pipeline input and/or output.
+
+For complex devices, such as often found in embedded systems, identical
+image sizes at the output of a pipeline can be achieved using different
+hardware configurations. One such example is shown on
+:ref:`pipeline-scaling`, where image scaling can be performed on both
+the video sensor and the host image processing hardware.
+
+
+.. _pipeline-scaling:
+
+.. figure:: dev-subdev_files/pipeline.*
+ :alt: pipeline.pdf / pipeline.png
+ :align: center
+
+ Image Format Negotiation on Pipelines
+
+ High quality and high speed pipeline configuration
+
+
+
+The sensor scaler is usually of less quality than the host scaler, but
+scaling on the sensor is required to achieve higher frame rates.
+Depending on the use case (quality vs. speed), the pipeline must be
+configured differently. Applications need to configure the formats at
+every point in the pipeline explicitly.
+
+Drivers that implement the :ref:`media API <media-controller-intro>`
+can expose pad-level image format configuration to applications. When
+they do, applications can use the
+:ref:`VIDIOC_SUBDEV_G_FMT <VIDIOC_SUBDEV_G_FMT>` and
+:ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` ioctls. to
+negotiate formats on a per-pad basis.
+
+Applications are responsible for configuring coherent parameters on the
+whole pipeline and making sure that connected pads have compatible
+formats. The pipeline is checked for formats mismatch at
+:ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` time, and an ``EPIPE`` error
+code is then returned if the configuration is invalid.
+
+Pad-level image format configuration support can be tested by calling
+the :ref:`VIDIOC_SUBDEV_G_FMT` ioctl on pad
+0. If the driver returns an ``EINVAL`` error code pad-level format
+configuration is not supported by the sub-device.
+
+
+Format Negotiation
+------------------
+
+Acceptable formats on pads can (and usually do) depend on a number of
+external parameters, such as formats on other pads, active links, or
+even controls. Finding a combination of formats on all pads in a video
+pipeline, acceptable to both application and driver, can't rely on
+formats enumeration only. A format negotiation mechanism is required.
+
+Central to the format negotiation mechanism are the get/set format
+operations. When called with the ``which`` argument set to
+:ref:`V4L2_SUBDEV_FORMAT_TRY <VIDIOC_SUBDEV_G_FMT>`, the
+:ref:`VIDIOC_SUBDEV_G_FMT <VIDIOC_SUBDEV_G_FMT>` and
+:ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` ioctls operate on
+a set of formats parameters that are not connected to the hardware
+configuration. Modifying those 'try' formats leaves the device state
+untouched (this applies to both the software state stored in the driver
+and the hardware state stored in the device itself).
+
+While not kept as part of the device state, try formats are stored in
+the sub-device file handles. A
+:ref:`VIDIOC_SUBDEV_G_FMT <VIDIOC_SUBDEV_G_FMT>` call will return
+the last try format set *on the same sub-device file handle*. Several
+applications querying the same sub-device at the same time will thus not
+interact with each other.
+
+To find out whether a particular format is supported by the device,
+applications use the
+:ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` ioctl. Drivers
+verify and, if needed, change the requested ``format`` based on device
+requirements and return the possibly modified value. Applications can
+then choose to try a different format or accept the returned value and
+continue.
+
+Formats returned by the driver during a negotiation iteration are
+guaranteed to be supported by the device. In particular, drivers
+guarantee that a returned format will not be further changed if passed
+to an :ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` call as-is
+(as long as external parameters, such as formats on other pads or links'
+configuration are not changed).
+
+Drivers automatically propagate formats inside sub-devices. When a try
+or active format is set on a pad, corresponding formats on other pads of
+the same sub-device can be modified by the driver. Drivers are free to
+modify formats as required by the device. However, they should comply
+with the following rules when possible:
+
+- Formats should be propagated from sink pads to source pads. Modifying
+ a format on a source pad should not modify the format on any sink
+ pad.
+
+- Sub-devices that scale frames using variable scaling factors should
+ reset the scale factors to default values when sink pads formats are
+ modified. If the 1:1 scaling ratio is supported, this means that
+ source pads formats should be reset to the sink pads formats.
+
+Formats are not propagated across links, as that would involve
+propagating them from one sub-device file handle to another.
+Applications must then take care to configure both ends of every link
+explicitly with compatible formats. Identical formats on the two ends of
+a link are guaranteed to be compatible. Drivers are free to accept
+different formats matching device requirements as being compatible.
+
+:ref:`sample-pipeline-config` shows a sample configuration sequence
+for the pipeline described in :ref:`pipeline-scaling` (table columns
+list entity names and pad numbers).
+
+
+.. _sample-pipeline-config:
+
+.. flat-table:: Sample Pipeline Configuration
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - Sensor/0 format
+
+ - Frontend/0 format
+
+ - Frontend/1 format
+
+ - Scaler/0 format
+
+ - Scaler/0 compose selection rectangle
+
+ - Scaler/1 format
+
+ - .. row 2
+
+ - Initial state
+
+ - 2048x1536/SGRBG8_1X8
+
+ - (default)
+
+ - (default)
+
+ - (default)
+
+ - (default)
+
+ - (default)
+
+ - .. row 3
+
+ - Configure frontend sink format
+
+ - 2048x1536/SGRBG8_1X8
+
+ - *2048x1536/SGRBG8_1X8*
+
+ - *2046x1534/SGRBG8_1X8*
+
+ - (default)
+
+ - (default)
+
+ - (default)
+
+ - .. row 4
+
+ - Configure scaler sink format
+
+ - 2048x1536/SGRBG8_1X8
+
+ - 2048x1536/SGRBG8_1X8
+
+ - 2046x1534/SGRBG8_1X8
+
+ - *2046x1534/SGRBG8_1X8*
+
+ - *0,0/2046x1534*
+
+ - *2046x1534/SGRBG8_1X8*
+
+ - .. row 5
+
+ - Configure scaler sink compose selection
+
+ - 2048x1536/SGRBG8_1X8
+
+ - 2048x1536/SGRBG8_1X8
+
+ - 2046x1534/SGRBG8_1X8
+
+ - 2046x1534/SGRBG8_1X8
+
+ - *0,0/1280x960*
+
+ - *1280x960/SGRBG8_1X8*
+
+
+
+1. Initial state. The sensor source pad format is set to its native 3MP
+ size and V4L2_MBUS_FMT_SGRBG8_1X8 media bus code. Formats on the
+ host frontend and scaler sink and source pads have the default
+ values, as well as the compose rectangle on the scaler's sink pad.
+
+2. The application configures the frontend sink pad format's size to
+ 2048x1536 and its media bus code to V4L2_MBUS_FMT_SGRBG_1X8. The
+ driver propagates the format to the frontend source pad.
+
+3. The application configures the scaler sink pad format's size to
+ 2046x1534 and the media bus code to V4L2_MBUS_FMT_SGRBG_1X8 to
+ match the frontend source size and media bus code. The media bus code
+ on the sink pad is set to V4L2_MBUS_FMT_SGRBG_1X8. The driver
+ propagates the size to the compose selection rectangle on the
+ scaler's sink pad, and the format to the scaler source pad.
+
+4. The application configures the size of the compose selection
+ rectangle of the scaler's sink pad 1280x960. The driver propagates
+ the size to the scaler's source pad format.
+
+When satisfied with the try results, applications can set the active
+formats by setting the ``which`` argument to
+``V4L2_SUBDEV_FORMAT_ACTIVE``. Active formats are changed exactly as try
+formats by drivers. To avoid modifying the hardware state during format
+negotiation, applications should negotiate try formats first and then
+modify the active settings using the try formats returned during the
+last negotiation iteration. This guarantees that the active format will
+be applied as-is by the driver without being modified.
+
+
+.. _v4l2-subdev-selections:
+
+Selections: cropping, scaling and composition
+---------------------------------------------
+
+Many sub-devices support cropping frames on their input or output pads
+(or possible even on both). Cropping is used to select the area of
+interest in an image, typically on an image sensor or a video decoder.
+It can also be used as part of digital zoom implementations to select
+the area of the image that will be scaled up.
+
+Crop settings are defined by a crop rectangle and represented in a
+struct :ref:`v4l2_rect <v4l2-rect>` by the coordinates of the top
+left corner and the rectangle size. Both the coordinates and sizes are
+expressed in pixels.
+
+As for pad formats, drivers store try and active rectangles for the
+selection targets :ref:`v4l2-selections-common`.
+
+On sink pads, cropping is applied relative to the current pad format.
+The pad format represents the image size as received by the sub-device
+from the previous block in the pipeline, and the crop rectangle
+represents the sub-image that will be transmitted further inside the
+sub-device for processing.
+
+The scaling operation changes the size of the image by scaling it to new
+dimensions. The scaling ratio isn't specified explicitly, but is implied
+from the original and scaled image sizes. Both sizes are represented by
+struct :ref:`v4l2_rect <v4l2-rect>`.
+
+Scaling support is optional. When supported by a subdev, the crop
+rectangle on the subdev's sink pad is scaled to the size configured
+using the
+:ref:`VIDIOC_SUBDEV_S_SELECTION <VIDIOC_SUBDEV_G_SELECTION>` IOCTL
+using ``V4L2_SEL_TGT_COMPOSE`` selection target on the same pad. If the
+subdev supports scaling but not composing, the top and left values are
+not used and must always be set to zero.
+
+On source pads, cropping is similar to sink pads, with the exception
+that the source size from which the cropping is performed, is the
+COMPOSE rectangle on the sink pad. In both sink and source pads, the
+crop rectangle must be entirely contained inside the source image size
+for the crop operation.
+
+The drivers should always use the closest possible rectangle the user
+requests on all selection targets, unless specifically told otherwise.
+``V4L2_SEL_FLAG_GE`` and ``V4L2_SEL_FLAG_LE`` flags may be used to round
+the image size either up or down. :ref:`v4l2-selection-flags`
+
+
+Types of selection targets
+--------------------------
+
+
+Actual targets
+^^^^^^^^^^^^^^
+
+Actual targets (without a postfix) reflect the actual hardware
+configuration at any point of time. There is a BOUNDS target
+corresponding to every actual target.
+
+
+BOUNDS targets
+^^^^^^^^^^^^^^
+
+BOUNDS targets is the smallest rectangle that contains all valid actual
+rectangles. It may not be possible to set the actual rectangle as large
+as the BOUNDS rectangle, however. This may be because e.g. a sensor's
+pixel array is not rectangular but cross-shaped or round. The maximum
+size may also be smaller than the BOUNDS rectangle.
+
+
+Order of configuration and format propagation
+---------------------------------------------
+
+Inside subdevs, the order of image processing steps will always be from
+the sink pad towards the source pad. This is also reflected in the order
+in which the configuration must be performed by the user: the changes
+made will be propagated to any subsequent stages. If this behaviour is
+not desired, the user must set ``V4L2_SEL_FLAG_KEEP_CONFIG`` flag. This
+flag causes no propagation of the changes are allowed in any
+circumstances. This may also cause the accessed rectangle to be adjusted
+by the driver, depending on the properties of the underlying hardware.
+
+The coordinates to a step always refer to the actual size of the
+previous step. The exception to this rule is the source compose
+rectangle, which refers to the sink compose bounds rectangle --- if it
+is supported by the hardware.
+
+1. Sink pad format. The user configures the sink pad format. This format
+ defines the parameters of the image the entity receives through the
+ pad for further processing.
+
+2. Sink pad actual crop selection. The sink pad crop defines the crop
+ performed to the sink pad format.
+
+3. Sink pad actual compose selection. The size of the sink pad compose
+ rectangle defines the scaling ratio compared to the size of the sink
+ pad crop rectangle. The location of the compose rectangle specifies
+ the location of the actual sink compose rectangle in the sink compose
+ bounds rectangle.
+
+4. Source pad actual crop selection. Crop on the source pad defines crop
+ performed to the image in the sink compose bounds rectangle.
+
+5. Source pad format. The source pad format defines the output pixel
+ format of the subdev, as well as the other parameters with the
+ exception of the image width and height. Width and height are defined
+ by the size of the source pad actual crop selection.
+
+Accessing any of the above rectangles not supported by the subdev will
+return ``EINVAL``. Any rectangle referring to a previous unsupported
+rectangle coordinates will instead refer to the previous supported
+rectangle. For example, if sink crop is not supported, the compose
+selection will refer to the sink pad format dimensions instead.
+
+
+.. _subdev-image-processing-crop:
+
+.. figure:: dev-subdev_files/subdev-image-processing-crop.*
+ :alt: subdev-image-processing-crop.svg
+ :align: center
+
+ **Figure 4.5. Image processing in subdevs: simple crop example**
+
+In the above example, the subdev supports cropping on its sink pad. To
+configure it, the user sets the media bus format on the subdev's sink
+pad. Now the actual crop rectangle can be set on the sink pad --- the
+location and size of this rectangle reflect the location and size of a
+rectangle to be cropped from the sink format. The size of the sink crop
+rectangle will also be the size of the format of the subdev's source
+pad.
+
+
+.. _subdev-image-processing-scaling-multi-source:
+
+.. figure:: dev-subdev_files/subdev-image-processing-scaling-multi-source.*
+ :alt: subdev-image-processing-scaling-multi-source.svg
+ :align: center
+
+ **Figure 4.6. Image processing in subdevs: scaling with multiple sources**
+
+In this example, the subdev is capable of first cropping, then scaling
+and finally cropping for two source pads individually from the resulting
+scaled image. The location of the scaled image in the cropped image is
+ignored in sink compose target. Both of the locations of the source crop
+rectangles refer to the sink scaling rectangle, independently cropping
+an area at location specified by the source crop rectangle from it.
+
+
+.. _subdev-image-processing-full:
+
+.. figure:: dev-subdev_files/subdev-image-processing-full.*
+ :alt: subdev-image-processing-full.svg
+ :align: center
+
+ **Figure 4.7. Image processing in subdevs: scaling and composition with multiple sinks and sources**
+
+The subdev driver supports two sink pads and two source pads. The images
+from both of the sink pads are individually cropped, then scaled and
+further composed on the composition bounds rectangle. From that, two
+independent streams are cropped and sent out of the subdev from the
+source pads.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ subdev-formats
--- /dev/null
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/PR-SVG-20010719/DTD/svg10.dtd">
+<svg width="43cm" height="10cm" viewBox="-194 128 844 196" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x="-8" y="130" width="469.774" height="193"/>
+ <g>
+ <rect style="fill: #ffffff" x="4.5" y="189" width="159" height="104"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a52a2a" x="4.5" y="189" width="159" height="104"/>
+ </g>
+ <g>
+ <rect style="fill: #ffffff" x="63.5" y="211" width="94" height="77"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" x="63.5" y="211" width="94" height="77"/>
+ </g>
+ <text style="fill: #0000ff;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="74.5" y="227.75">
+ <tspan x="74.5" y="227.75">sink</tspan>
+ <tspan x="74.5" y="243.75">crop</tspan>
+ <tspan x="74.5" y="259.75">selection</tspan>
+ </text>
+ <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="29.5" y="158">
+ <tspan x="29.5" y="158"></tspan>
+ </text>
+ <text style="fill: #a52a2a;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="8.53836" y="157.914">
+ <tspan x="8.53836" y="157.914">sink media</tspan>
+ <tspan x="8.53836" y="173.914">bus format</tspan>
+ </text>
+ <text style="fill: #8b6914;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="349.774" y="155">
+ <tspan x="349.774" y="155">source media</tspan>
+ <tspan x="349.774" y="171">bus format</tspan>
+ </text>
+ <g>
+ <rect style="fill: #ffffff" x="350.488" y="190.834" width="93.2863" height="75.166"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #8b6914" x="350.488" y="190.834" width="93.2863" height="75.166"/>
+ </g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="350.488" y1="266" x2="63.5" y2="288"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="350.488" y1="190.834" x2="63.5" y2="211"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="443.774" y1="266" x2="157.5" y2="288"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="443.774" y1="190.834" x2="157.5" y2="211"/>
+ <g>
+ <ellipse style="fill: #ffffff" cx="473.1" cy="219.984" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="473.1" cy="219.984" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="473.1" cy="219.984" rx="8.5" ry="8.5"/>
+ </g>
+ <g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="481.6" y1="219.984" x2="637.934" y2="220.012"/>
+ <polygon style="fill: #000000" points="645.434,220.014 635.433,225.012 637.934,220.012 635.435,215.012 "/>
+ <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="645.434,220.014 635.433,225.012 637.934,220.012 635.435,215.012 "/>
+ </g>
+ <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="506.908" y="209.8">
+ <tspan x="506.908" y="209.8">pad 1 (source)</tspan>
+ </text>
+ <g>
+ <ellipse style="fill: #ffffff" cx="-20.3982" cy="241.512" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-20.3982" cy="241.512" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-20.3982" cy="241.512" rx="8.5" ry="8.5"/>
+ </g>
+ <g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="-192.398" y1="241.8" x2="-38.6343" y2="241.529"/>
+ <polygon style="fill: #000000" points="-31.1343,241.516 -41.1254,246.534 -38.6343,241.529 -41.1431,236.534 "/>
+ <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="-31.1343,241.516 -41.1254,246.534 -38.6343,241.529 -41.1431,236.534 "/>
+ </g>
+ <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="-147.858" y="229.8">
+ <tspan x="-147.858" y="229.8">pad 0 (sink)</tspan>
+ </text>
+</svg>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/PR-SVG-20010719/DTD/svg10.dtd">
+<svg width="59cm" height="18cm" viewBox="-186 71 1178 346" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <g>
+ <rect style="fill: #ffffff" x="318.9" y="129" width="208.1" height="249"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #ff765a" x="318.9" y="129" width="208.1" height="249"/>
+ </g>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x="-2" y="73" width="806" height="343"/>
+ <g>
+ <ellipse style="fill: #ffffff" cx="-12.5" cy="166.712" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-12.5" cy="166.712" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-12.5" cy="166.712" rx="8.5" ry="8.5"/>
+ </g>
+ <g>
+ <ellipse style="fill: #ffffff" cx="815.232" cy="205.184" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="815.232" cy="205.184" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="815.232" cy="205.184" rx="8.5" ry="8.5"/>
+ </g>
+ <g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="-184.5" y1="167" x2="-30.7361" y2="166.729"/>
+ <polygon style="fill: #000000" points="-23.2361,166.716 -33.2272,171.734 -30.7361,166.729 -33.2449,161.734 "/>
+ <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="-23.2361,166.716 -33.2272,171.734 -30.7361,166.729 -33.2449,161.734 "/>
+ </g>
+ <g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="823.732" y1="205.184" x2="980.066" y2="205.212"/>
+ <polygon style="fill: #000000" points="987.566,205.214 977.565,210.212 980.066,205.212 977.567,200.212 "/>
+ <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="987.566,205.214 977.565,210.212 980.066,205.212 977.567,200.212 "/>
+ </g>
+ <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="-139.96" y="155">
+ <tspan x="-139.96" y="155">pad 0 (sink)</tspan>
+ </text>
+ <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="849.04" y="195">
+ <tspan x="849.04" y="195">pad 2 (source)</tspan>
+ </text>
+ <g>
+ <rect style="fill: #ffffff" x="5.5" y="120" width="159" height="104"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a52a2a" x="5.5" y="120" width="159" height="104"/>
+ </g>
+ <g>
+ <rect style="fill: #ffffff" x="62.5" y="136" width="94" height="77"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" x="62.5" y="136" width="94" height="77"/>
+ </g>
+ <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="30.5" y="89">
+ <tspan x="30.5" y="89"></tspan>
+ </text>
+ <text style="fill: #a52a2a;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="9.53836" y="88.9138">
+ <tspan x="9.53836" y="88.9138">sink media</tspan>
+ <tspan x="9.53836" y="104.914">bus format</tspan>
+ </text>
+ <g>
+ <rect style="fill: #ffffff" x="333.644" y="185.65" width="165.2" height="172.478"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #00ff00" x="333.644" y="185.65" width="165.2" height="172.478"/>
+ </g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="333.644" y1="358.128" x2="62.5" y2="213"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="333.644" y1="185.65" x2="62.5" y2="136"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="498.844" y1="358.128" x2="156.5" y2="213"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="498.844" y1="185.65" x2="156.5" y2="136"/>
+ <text style="fill: #00ff00;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="334.704" y="149.442">
+ <tspan x="334.704" y="149.442">sink compose</tspan>
+ <tspan x="334.704" y="165.442">selection (scaling)</tspan>
+ </text>
+ <g>
+ <rect style="fill: #ffffff" x="409.322" y="194.565" width="100.186" height="71.4523"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x="409.322" y="194.565" width="100.186" height="71.4523"/>
+ </g>
+ <text style="fill: #8b6914;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="689.5" y="105.128">
+ <tspan x="689.5" y="105.128">source media</tspan>
+ <tspan x="689.5" y="121.128">bus format</tspan>
+ </text>
+ <g>
+ <rect style="fill: #ffffff" x="688.488" y="173.834" width="100.186" height="71.4523"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #8b6914" x="688.488" y="173.834" width="100.186" height="71.4523"/>
+ </g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="688.488" y1="245.286" x2="409.322" y2="266.018"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="688.488" y1="173.834" x2="409.322" y2="194.565"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="788.674" y1="245.286" x2="509.508" y2="266.018"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="788.674" y1="173.834" x2="509.508" y2="194.565"/>
+ <text style="fill: #ff765a;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="325" y="103">
+ <tspan x="325" y="103">sink compose</tspan>
+ <tspan x="325" y="119">bounds selection</tspan>
+ </text>
+ <g>
+ <ellipse style="fill: #ffffff" cx="-12.0982" cy="341.512" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-12.0982" cy="341.512" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-12.0982" cy="341.512" rx="8.5" ry="8.5"/>
+ </g>
+ <g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="-184.098" y1="341.8" x2="-30.3343" y2="341.529"/>
+ <polygon style="fill: #000000" points="-22.8343,341.516 -32.8254,346.534 -30.3343,341.529 -32.8431,336.534 "/>
+ <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="-22.8343,341.516 -32.8254,346.534 -30.3343,341.529 -32.8431,336.534 "/>
+ </g>
+ <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="-139" y="329">
+ <tspan x="-139" y="329">pad 1 (sink)</tspan>
+ </text>
+ <g>
+ <rect style="fill: #ffffff" x="7.80824" y="292.8" width="112.092" height="82.2"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a52a2a" x="7.80824" y="292.8" width="112.092" height="82.2"/>
+ </g>
+ <g>
+ <rect style="fill: #ffffff" x="52.9" y="314.8" width="58.1" height="50.2"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" x="52.9" y="314.8" width="58.1" height="50.2"/>
+ </g>
+ <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="31.9" y="259.8">
+ <tspan x="31.9" y="259.8"></tspan>
+ </text>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="358.9" y1="251.9" x2="52.9" y2="314.8"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="358.9" y1="316" x2="52.9" y2="365"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="434" y1="316" x2="111" y2="365"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="434" y1="251.9" x2="111" y2="314.8"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #00ff00" x="358.9" y="251.9" width="75.1" height="64.1"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x="443.262" y="284.466" width="64.738" height="48.534"/>
+ <g>
+ <rect style="fill: #ffffff" x="693.428" y="324.734" width="63.572" height="49.266"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #8b6914" x="693.428" y="324.734" width="63.572" height="49.266"/>
+ </g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="693.428" y1="374" x2="443.262" y2="333"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="693.428" y1="324.734" x2="443.262" y2="284.466"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="757" y1="374" x2="508" y2="333"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="757" y1="324.734" x2="508" y2="284.466"/>
+ <g>
+ <ellipse style="fill: #ffffff" cx="815.44" cy="343.984" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="815.44" cy="343.984" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="815.44" cy="343.984" rx="8.5" ry="8.5"/>
+ </g>
+ <g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="823.94" y1="343.984" x2="980.274" y2="344.012"/>
+ <polygon style="fill: #000000" points="987.774,344.014 977.773,349.012 980.274,344.012 977.775,339.012 "/>
+ <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="987.774,344.014 977.773,349.012 980.274,344.012 977.775,339.012 "/>
+ </g>
+ <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="849.248" y="333.8">
+ <tspan x="849.248" y="333.8">pad 3 (source)</tspan>
+ </text>
+ <text style="fill: #0000ff;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="197" y="91">
+ <tspan x="197" y="91">sink</tspan>
+ <tspan x="197" y="107">crop</tspan>
+ <tspan x="197" y="123">selection</tspan>
+ </text>
+ <text style="fill: #a020f0;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="553" y="95">
+ <tspan x="553" y="95">source</tspan>
+ <tspan x="553" y="111">crop</tspan>
+ <tspan x="553" y="127">selection</tspan>
+ </text>
+ <g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" x1="211" y1="132" x2="166.21" y2="135.287"/>
+ <polygon style="fill: #0000ff" points="158.73,135.836 168.337,130.118 166.21,135.287 169.069,140.091 "/>
+ <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" points="158.73,135.836 168.337,130.118 166.21,135.287 169.069,140.091 "/>
+ </g>
+ <g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" x1="209" y1="131" x2="115.581" y2="306.209"/>
+ <polygon style="fill: #0000ff" points="112.052,312.827 112.345,301.65 115.581,306.209 121.169,306.355 "/>
+ <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" points="112.052,312.827 112.345,301.65 115.581,306.209 121.169,306.355 "/>
+ </g>
+ <g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x1="550.492" y1="133.214" x2="514.916" y2="186.469"/>
+ <polygon style="fill: #a020f0" points="510.75,192.706 512.147,181.613 514.916,186.469 520.463,187.168 "/>
+ <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" points="510.75,192.706 512.147,181.613 514.916,186.469 520.463,187.168 "/>
+ </g>
+ <g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x1="550.072" y1="133.787" x2="510.618" y2="275.089"/>
+ <polygon style="fill: #a020f0" points="508.601,282.312 506.475,271.336 510.618,275.089 516.106,274.025 "/>
+ <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" points="508.601,282.312 506.475,271.336 510.618,275.089 516.106,274.025 "/>
+ </g>
+</svg>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/PR-SVG-20010719/DTD/svg10.dtd">
+<svg width="59cm" height="17cm" viewBox="-194 128 1179 330" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x="-8" y="130" width="806" height="327"/>
+ <g>
+ <rect style="fill: #ffffff" x="4.5" y="189" width="159" height="104"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a52a2a" x="4.5" y="189" width="159" height="104"/>
+ </g>
+ <g>
+ <rect style="fill: #ffffff" x="49.5" y="204" width="94" height="77"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" x="49.5" y="204" width="94" height="77"/>
+ </g>
+ <text style="fill: #0000ff;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="60" y="224">
+ <tspan x="60" y="224">sink</tspan>
+ <tspan x="60" y="240">crop</tspan>
+ <tspan x="60" y="256">selection</tspan>
+ </text>
+ <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="29.5" y="158">
+ <tspan x="29.5" y="158"></tspan>
+ </text>
+ <text style="fill: #a52a2a;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="8.53836" y="157.914">
+ <tspan x="8.53836" y="157.914">sink media</tspan>
+ <tspan x="8.53836" y="173.914">bus format</tspan>
+ </text>
+ <g>
+ <rect style="fill: #ffffff" x="333.644" y="185.65" width="165.2" height="172.478"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #00ff00" x="333.644" y="185.65" width="165.2" height="172.478"/>
+ </g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="333.644" y1="358.128" x2="49.5" y2="281"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="333.644" y1="185.65" x2="49.5" y2="204"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="498.844" y1="358.128" x2="143.5" y2="281"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="498.844" y1="185.65" x2="143.5" y2="204"/>
+ <text style="fill: #00ff00;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="334.704" y="149.442">
+ <tspan x="334.704" y="149.442">sink compose</tspan>
+ <tspan x="334.704" y="165.442">selection (scaling)</tspan>
+ </text>
+ <g>
+ <rect style="fill: #ffffff" x="382.322" y="199.565" width="100.186" height="71.4523"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x="382.322" y="199.565" width="100.186" height="71.4523"/>
+ </g>
+ <text style="fill: #a020f0;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="543.322" y="149.442">
+ <tspan x="543.322" y="149.442">source</tspan>
+ <tspan x="543.322" y="165.442">crop</tspan>
+ <tspan x="543.322" y="181.442">selection</tspan>
+ </text>
+ <text style="fill: #8b6914;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="691.5" y="157.128">
+ <tspan x="691.5" y="157.128">source media</tspan>
+ <tspan x="691.5" y="173.128">bus format</tspan>
+ </text>
+ <g>
+ <rect style="fill: #ffffff" x="690.488" y="225.834" width="100.186" height="71.4523"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #8b6914" x="690.488" y="225.834" width="100.186" height="71.4523"/>
+ </g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="690.488" y1="297.286" x2="382.322" y2="271.018"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="690.488" y1="225.834" x2="382.322" y2="199.565"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="790.674" y1="297.286" x2="482.508" y2="271.018"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="790.674" y1="225.834" x2="482.508" y2="199.565"/>
+ <g>
+ <ellipse style="fill: #ffffff" cx="808.1" cy="249.984" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="808.1" cy="249.984" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="808.1" cy="249.984" rx="8.5" ry="8.5"/>
+ </g>
+ <g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="816.6" y1="249.984" x2="972.934" y2="250.012"/>
+ <polygon style="fill: #000000" points="980.434,250.014 970.433,255.012 972.934,250.012 970.435,245.012 "/>
+ <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="980.434,250.014 970.433,255.012 972.934,250.012 970.435,245.012 "/>
+ </g>
+ <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="841.908" y="239.8">
+ <tspan x="841.908" y="239.8">pad 1 (source)</tspan>
+ </text>
+ <g>
+ <ellipse style="fill: #ffffff" cx="-20.3982" cy="241.512" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-20.3982" cy="241.512" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-20.3982" cy="241.512" rx="8.5" ry="8.5"/>
+ </g>
+ <g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="-192.398" y1="241.8" x2="-38.6343" y2="241.529"/>
+ <polygon style="fill: #000000" points="-31.1343,241.516 -41.1254,246.534 -38.6343,241.529 -41.1431,236.534 "/>
+ <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="-31.1343,241.516 -41.1254,246.534 -38.6343,241.529 -41.1431,236.534 "/>
+ </g>
+ <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="-147.858" y="229.8">
+ <tspan x="-147.858" y="229.8">pad 0 (sink)</tspan>
+ </text>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x="389.822" y="276.666" width="100.186" height="71.4523"/>
+ <g>
+ <rect style="fill: #ffffff" x="689.988" y="345.934" width="100.186" height="71.4523"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #8b6914" x="689.988" y="345.934" width="100.186" height="71.4523"/>
+ </g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="689.988" y1="417.386" x2="389.822" y2="348.118"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="689.988" y1="345.934" x2="389.822" y2="276.666"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="790.174" y1="417.386" x2="490.008" y2="348.118"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="790.174" y1="345.934" x2="490.008" y2="276.666"/>
+ <g>
+ <ellipse style="fill: #ffffff" cx="805.6" cy="384.084" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="805.6" cy="384.084" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="805.6" cy="384.084" rx="8.5" ry="8.5"/>
+ </g>
+ <g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="814.1" y1="384.084" x2="970.434" y2="384.112"/>
+ <polygon style="fill: #000000" points="977.934,384.114 967.933,389.112 970.434,384.112 967.935,379.112 "/>
+ <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="977.934,384.114 967.933,389.112 970.434,384.112 967.935,379.112 "/>
+ </g>
+ <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="839.408" y="373.9">
+ <tspan x="839.408" y="373.9">pad 2 (source)</tspan>
+ </text>
+ <g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x1="546" y1="191" x2="492.157" y2="198.263"/>
+ <polygon style="fill: #a020f0" points="484.724,199.266 493.966,192.974 492.157,198.263 495.303,202.884 "/>
+ <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" points="484.724,199.266 493.966,192.974 492.157,198.263 495.303,202.884 "/>
+ </g>
+ <g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x1="546.908" y1="190.725" x2="495.383" y2="268.548"/>
+ <polygon style="fill: #a020f0" points="491.242,274.802 492.594,263.703 495.383,268.548 500.932,269.224 "/>
+ <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" points="491.242,274.802 492.594,263.703 495.383,268.548 500.932,269.224 "/>
+ </g>
+</svg>
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _ttx:
+
+******************
+Teletext Interface
+******************
+
+This interface was aimed at devices receiving and demodulating Teletext
+data [:ref:`ets300706`, :ref:`itu653`], evaluating the Teletext
+packages and storing formatted pages in cache memory. Such devices are
+usually implemented as microcontrollers with serial interface
+(I:sup:`2`\ C) and could be found on old TV cards, dedicated Teletext
+decoding cards and home-brew devices connected to the PC parallel port.
+
+The Teletext API was designed by Martin Buck. It was defined in the
+kernel header file ``linux/videotext.h``, the specification is available
+from
+`ftp://ftp.gwdg.de/pub/linux/misc/videotext/ <ftp://ftp.gwdg.de/pub/linux/misc/videotext/>`__.
+(Videotext is the name of the German public television Teletext
+service.)
+
+Eventually the Teletext API was integrated into the V4L API with
+character device file names ``/dev/vtx0`` to ``/dev/vtx31``, device
+major number 81, minor numbers 192 to 223.
+
+However, teletext decoders were quickly replaced by more generic VBI
+demodulators and those dedicated teletext decoders no longer exist. For
+many years the vtx devices were still around, even though nobody used
+them. So the decision was made to finally remove support for the
+Teletext API in kernel 2.6.37.
+
+Modern devices all use the :ref:`raw <raw-vbi>` or
+:ref:`sliced` VBI API.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _devices:
+
+**********
+Interfaces
+**********
+
+
+.. toctree::
+ :maxdepth: 1
+
+ dev-capture
+ dev-overlay
+ dev-output
+ dev-osd
+ dev-codec
+ dev-effect
+ dev-raw-vbi
+ dev-sliced-vbi
+ dev-teletext
+ dev-radio
+ dev-rds
+ dev-sdr
+ dev-event
+ dev-subdev
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _diff-v4l:
+
+********************************
+Differences between V4L and V4L2
+********************************
+
+The Video For Linux API was first introduced in Linux 2.1 to unify and
+replace various TV and radio device related interfaces, developed
+independently by driver writers in prior years. Starting with Linux 2.5
+the much improved V4L2 API replaces the V4L API. The support for the old
+V4L calls were removed from Kernel, but the library :ref:`libv4l`
+supports the conversion of a V4L API system call into a V4L2 one.
+
+
+Opening and Closing Devices
+===========================
+
+For compatibility reasons the character device file names recommended
+for V4L2 video capture, overlay, radio and raw vbi capture devices did
+not change from those used by V4L. They are listed in :ref:`devices`
+and below in :ref:`v4l-dev`.
+
+The teletext devices (minor range 192-223) have been removed in V4L2 and
+no longer exist. There is no hardware available anymore for handling
+pure teletext. Instead raw or sliced VBI is used.
+
+The V4L ``videodev`` module automatically assigns minor numbers to
+drivers in load order, depending on the registered device type. We
+recommend that V4L2 drivers by default register devices with the same
+numbers, but the system administrator can assign arbitrary minor numbers
+using driver module options. The major device number remains 81.
+
+
+.. _v4l-dev:
+
+.. flat-table:: V4L Device Types, Names and Numbers
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Device Type
+
+ - File Name
+
+ - Minor Numbers
+
+ - .. row 2
+
+ - Video capture and overlay
+
+ - ``/dev/video`` and ``/dev/bttv0``\ [1]_, ``/dev/video0`` to
+ ``/dev/video63``
+
+ - 0-63
+
+ - .. row 3
+
+ - Radio receiver
+
+ - ``/dev/radio``\ [2]_, ``/dev/radio0`` to ``/dev/radio63``
+
+ - 64-127
+
+ - .. row 4
+
+ - Raw VBI capture
+
+ - ``/dev/vbi``, ``/dev/vbi0`` to ``/dev/vbi31``
+
+ - 224-255
+
+
+V4L prohibits (or used to prohibit) multiple opens of a device file.
+V4L2 drivers *may* support multiple opens, see :ref:`open` for details
+and consequences.
+
+V4L drivers respond to V4L2 ioctls with an ``EINVAL`` error code.
+
+
+Querying Capabilities
+=====================
+
+The V4L ``VIDIOCGCAP`` ioctl is equivalent to V4L2's
+:ref:`VIDIOC_QUERYCAP`.
+
+The ``name`` field in struct :c:type:`struct video_capability` became
+``card`` in struct :ref:`v4l2_capability <v4l2-capability>`, ``type``
+was replaced by ``capabilities``. Note V4L2 does not distinguish between
+device types like this, better think of basic video input, video output
+and radio devices supporting a set of related functions like video
+capturing, video overlay and VBI capturing. See :ref:`open` for an
+introduction.
+
+
+
+.. flat-table::
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - struct :c:type:`struct video_capability` ``type``
+
+ - struct :ref:`v4l2_capability <v4l2-capability>`
+ ``capabilities`` flags
+
+ - Purpose
+
+ - .. row 2
+
+ - ``VID_TYPE_CAPTURE``
+
+ - ``V4L2_CAP_VIDEO_CAPTURE``
+
+ - The :ref:`video capture <capture>` interface is supported.
+
+ - .. row 3
+
+ - ``VID_TYPE_TUNER``
+
+ - ``V4L2_CAP_TUNER``
+
+ - The device has a :ref:`tuner or modulator <tuner>`.
+
+ - .. row 4
+
+ - ``VID_TYPE_TELETEXT``
+
+ - ``V4L2_CAP_VBI_CAPTURE``
+
+ - The :ref:`raw VBI capture <raw-vbi>` interface is supported.
+
+ - .. row 5
+
+ - ``VID_TYPE_OVERLAY``
+
+ - ``V4L2_CAP_VIDEO_OVERLAY``
+
+ - The :ref:`video overlay <overlay>` interface is supported.
+
+ - .. row 6
+
+ - ``VID_TYPE_CHROMAKEY``
+
+ - ``V4L2_FBUF_CAP_CHROMAKEY`` in field ``capability`` of struct
+ :ref:`v4l2_framebuffer <v4l2-framebuffer>`
+
+ - Whether chromakey overlay is supported. For more information on
+ overlay see :ref:`overlay`.
+
+ - .. row 7
+
+ - ``VID_TYPE_CLIPPING``
+
+ - ``V4L2_FBUF_CAP_LIST_CLIPPING`` and
+ ``V4L2_FBUF_CAP_BITMAP_CLIPPING`` in field ``capability`` of
+ struct :ref:`v4l2_framebuffer <v4l2-framebuffer>`
+
+ - Whether clipping the overlaid image is supported, see
+ :ref:`overlay`.
+
+ - .. row 8
+
+ - ``VID_TYPE_FRAMERAM``
+
+ - ``V4L2_FBUF_CAP_EXTERNOVERLAY`` *not set* in field ``capability``
+ of struct :ref:`v4l2_framebuffer <v4l2-framebuffer>`
+
+ - Whether overlay overwrites frame buffer memory, see
+ :ref:`overlay`.
+
+ - .. row 9
+
+ - ``VID_TYPE_SCALES``
+
+ - ``-``
+
+ - This flag indicates if the hardware can scale images. The V4L2 API
+ implies the scale factor by setting the cropping dimensions and
+ image size with the :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` and
+ :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, respectively. The
+ driver returns the closest sizes possible. For more information on
+ cropping and scaling see :ref:`crop`.
+
+ - .. row 10
+
+ - ``VID_TYPE_MONOCHROME``
+
+ - ``-``
+
+ - Applications can enumerate the supported image formats with the
+ :ref:`VIDIOC_ENUM_FMT` ioctl to determine if
+ the device supports grey scale capturing only. For more
+ information on image formats see :ref:`pixfmt`.
+
+ - .. row 11
+
+ - ``VID_TYPE_SUBCAPTURE``
+
+ - ``-``
+
+ - Applications can call the :ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>`
+ ioctl to determine if the device supports capturing a subsection
+ of the full picture ("cropping" in V4L2). If not, the ioctl
+ returns the ``EINVAL`` error code. For more information on cropping
+ and scaling see :ref:`crop`.
+
+ - .. row 12
+
+ - ``VID_TYPE_MPEG_DECODER``
+
+ - ``-``
+
+ - Applications can enumerate the supported image formats with the
+ :ref:`VIDIOC_ENUM_FMT` ioctl to determine if
+ the device supports MPEG streams.
+
+ - .. row 13
+
+ - ``VID_TYPE_MPEG_ENCODER``
+
+ - ``-``
+
+ - See above.
+
+ - .. row 14
+
+ - ``VID_TYPE_MJPEG_DECODER``
+
+ - ``-``
+
+ - See above.
+
+ - .. row 15
+
+ - ``VID_TYPE_MJPEG_ENCODER``
+
+ - ``-``
+
+ - See above.
+
+
+The ``audios`` field was replaced by ``capabilities`` flag
+``V4L2_CAP_AUDIO``, indicating *if* the device has any audio inputs or
+outputs. To determine their number applications can enumerate audio
+inputs with the :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` ioctl. The
+audio ioctls are described in :ref:`audio`.
+
+The ``maxwidth``, ``maxheight``, ``minwidth`` and ``minheight`` fields
+were removed. Calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` or
+:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl with the desired
+dimensions returns the closest size possible, taking into account the
+current video standard, cropping and scaling limitations.
+
+
+Video Sources
+=============
+
+V4L provides the ``VIDIOCGCHAN`` and ``VIDIOCSCHAN`` ioctl using struct
+:c:type:`struct video_channel` to enumerate the video inputs of a V4L
+device. The equivalent V4L2 ioctls are
+:ref:`VIDIOC_ENUMINPUT`,
+:ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` and
+:ref:`VIDIOC_S_INPUT <VIDIOC_G_INPUT>` using struct
+:ref:`v4l2_input <v4l2-input>` as discussed in :ref:`video`.
+
+The ``channel`` field counting inputs was renamed to ``index``, the
+video input types were renamed as follows:
+
+
+
+.. flat-table::
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - struct :c:type:`struct video_channel` ``type``
+
+ - struct :ref:`v4l2_input <v4l2-input>` ``type``
+
+ - .. row 2
+
+ - ``VIDEO_TYPE_TV``
+
+ - ``V4L2_INPUT_TYPE_TUNER``
+
+ - .. row 3
+
+ - ``VIDEO_TYPE_CAMERA``
+
+ - ``V4L2_INPUT_TYPE_CAMERA``
+
+
+Unlike the ``tuners`` field expressing the number of tuners of this
+input, V4L2 assumes each video input is connected to at most one tuner.
+However a tuner can have more than one input, i. e. RF connectors, and a
+device can have multiple tuners. The index number of the tuner
+associated with the input, if any, is stored in field ``tuner`` of
+struct :ref:`v4l2_input <v4l2-input>`. Enumeration of tuners is
+discussed in :ref:`tuner`.
+
+The redundant ``VIDEO_VC_TUNER`` flag was dropped. Video inputs
+associated with a tuner are of type ``V4L2_INPUT_TYPE_TUNER``. The
+``VIDEO_VC_AUDIO`` flag was replaced by the ``audioset`` field. V4L2
+considers devices with up to 32 audio inputs. Each set bit in the
+``audioset`` field represents one audio input this video input combines
+with. For information about audio inputs and how to switch between them
+see :ref:`audio`.
+
+The ``norm`` field describing the supported video standards was replaced
+by ``std``. The V4L specification mentions a flag ``VIDEO_VC_NORM``
+indicating whether the standard can be changed. This flag was a later
+addition together with the ``norm`` field and has been removed in the
+meantime. V4L2 has a similar, albeit more comprehensive approach to
+video standards, see :ref:`standard` for more information.
+
+
+Tuning
+======
+
+The V4L ``VIDIOCGTUNER`` and ``VIDIOCSTUNER`` ioctl and struct
+:c:type:`struct video_tuner` can be used to enumerate the tuners of a
+V4L TV or radio device. The equivalent V4L2 ioctls are
+:ref:`VIDIOC_G_TUNER <VIDIOC_G_TUNER>` and
+:ref:`VIDIOC_S_TUNER <VIDIOC_G_TUNER>` using struct
+:ref:`v4l2_tuner <v4l2-tuner>`. Tuners are covered in :ref:`tuner`.
+
+The ``tuner`` field counting tuners was renamed to ``index``. The fields
+``name``, ``rangelow`` and ``rangehigh`` remained unchanged.
+
+The ``VIDEO_TUNER_PAL``, ``VIDEO_TUNER_NTSC`` and ``VIDEO_TUNER_SECAM``
+flags indicating the supported video standards were dropped. This
+information is now contained in the associated struct
+:ref:`v4l2_input <v4l2-input>`. No replacement exists for the
+``VIDEO_TUNER_NORM`` flag indicating whether the video standard can be
+switched. The ``mode`` field to select a different video standard was
+replaced by a whole new set of ioctls and structures described in
+:ref:`standard`. Due to its ubiquity it should be mentioned the BTTV
+driver supports several standards in addition to the regular
+``VIDEO_MODE_PAL`` (0), ``VIDEO_MODE_NTSC``, ``VIDEO_MODE_SECAM`` and
+``VIDEO_MODE_AUTO`` (3). Namely N/PAL Argentina, M/PAL, N/PAL, and NTSC
+Japan with numbers 3-6 (sic).
+
+The ``VIDEO_TUNER_STEREO_ON`` flag indicating stereo reception became
+``V4L2_TUNER_SUB_STEREO`` in field ``rxsubchans``. This field also
+permits the detection of monaural and bilingual audio, see the
+definition of struct :ref:`v4l2_tuner <v4l2-tuner>` for details.
+Presently no replacement exists for the ``VIDEO_TUNER_RDS_ON`` and
+``VIDEO_TUNER_MBS_ON`` flags.
+
+The ``VIDEO_TUNER_LOW`` flag was renamed to ``V4L2_TUNER_CAP_LOW`` in
+the struct :ref:`v4l2_tuner <v4l2-tuner>` ``capability`` field.
+
+The ``VIDIOCGFREQ`` and ``VIDIOCSFREQ`` ioctl to change the tuner
+frequency where renamed to
+:ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` and
+:ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>`. They take a pointer
+to a struct :ref:`v4l2_frequency <v4l2-frequency>` instead of an
+unsigned long integer.
+
+
+.. _v4l-image-properties:
+
+Image Properties
+================
+
+V4L2 has no equivalent of the ``VIDIOCGPICT`` and ``VIDIOCSPICT`` ioctl
+and struct :c:type:`struct video_picture`. The following fields where
+replaced by V4L2 controls accessible with the
+:ref:`VIDIOC_QUERYCTRL`,
+:ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and
+:ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls:
+
+
+
+.. flat-table::
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - struct :c:type:`struct video_picture`
+
+ - V4L2 Control ID
+
+ - .. row 2
+
+ - ``brightness``
+
+ - ``V4L2_CID_BRIGHTNESS``
+
+ - .. row 3
+
+ - ``hue``
+
+ - ``V4L2_CID_HUE``
+
+ - .. row 4
+
+ - ``colour``
+
+ - ``V4L2_CID_SATURATION``
+
+ - .. row 5
+
+ - ``contrast``
+
+ - ``V4L2_CID_CONTRAST``
+
+ - .. row 6
+
+ - ``whiteness``
+
+ - ``V4L2_CID_WHITENESS``
+
+
+The V4L picture controls are assumed to range from 0 to 65535 with no
+particular reset value. The V4L2 API permits arbitrary limits and
+defaults which can be queried with the
+:ref:`VIDIOC_QUERYCTRL` ioctl. For general
+information about controls see :ref:`control`.
+
+The ``depth`` (average number of bits per pixel) of a video image is
+implied by the selected image format. V4L2 does not explicitly provide
+such information assuming applications recognizing the format are aware
+of the image depth and others need not know. The ``palette`` field moved
+into the struct :ref:`v4l2_pix_format <v4l2-pix-format>`:
+
+
+
+.. flat-table::
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - struct :c:type:`struct video_picture` ``palette``
+
+ - struct :ref:`v4l2_pix_format <v4l2-pix-format>` ``pixfmt``
+
+ - .. row 2
+
+ - ``VIDEO_PALETTE_GREY``
+
+ - :ref:`V4L2_PIX_FMT_GREY <V4L2-PIX-FMT-GREY>`
+
+ - .. row 3
+
+ - ``VIDEO_PALETTE_HI240``
+
+ - :ref:`V4L2_PIX_FMT_HI240 <pixfmt-reserved>` [3]_
+
+ - .. row 4
+
+ - ``VIDEO_PALETTE_RGB565``
+
+ - :ref:`V4L2_PIX_FMT_RGB565 <pixfmt-rgb>`
+
+ - .. row 5
+
+ - ``VIDEO_PALETTE_RGB555``
+
+ - :ref:`V4L2_PIX_FMT_RGB555 <pixfmt-rgb>`
+
+ - .. row 6
+
+ - ``VIDEO_PALETTE_RGB24``
+
+ - :ref:`V4L2_PIX_FMT_BGR24 <pixfmt-rgb>`
+
+ - .. row 7
+
+ - ``VIDEO_PALETTE_RGB32``
+
+ - :ref:`V4L2_PIX_FMT_BGR32 <pixfmt-rgb>` [4]_
+
+ - .. row 8
+
+ - ``VIDEO_PALETTE_YUV422``
+
+ - :ref:`V4L2_PIX_FMT_YUYV <V4L2-PIX-FMT-YUYV>`
+
+ - .. row 9
+
+ - ``VIDEO_PALETTE_YUYV``\ [5]_
+
+ - :ref:`V4L2_PIX_FMT_YUYV <V4L2-PIX-FMT-YUYV>`
+
+ - .. row 10
+
+ - ``VIDEO_PALETTE_UYVY``
+
+ - :ref:`V4L2_PIX_FMT_UYVY <V4L2-PIX-FMT-UYVY>`
+
+ - .. row 11
+
+ - ``VIDEO_PALETTE_YUV420``
+
+ - None
+
+ - .. row 12
+
+ - ``VIDEO_PALETTE_YUV411``
+
+ - :ref:`V4L2_PIX_FMT_Y41P <V4L2-PIX-FMT-Y41P>` [6]_
+
+ - .. row 13
+
+ - ``VIDEO_PALETTE_RAW``
+
+ - None [7]_
+
+ - .. row 14
+
+ - ``VIDEO_PALETTE_YUV422P``
+
+ - :ref:`V4L2_PIX_FMT_YUV422P <V4L2-PIX-FMT-YUV422P>`
+
+ - .. row 15
+
+ - ``VIDEO_PALETTE_YUV411P``
+
+ - :ref:`V4L2_PIX_FMT_YUV411P <V4L2-PIX-FMT-YUV411P>` [8]_
+
+ - .. row 16
+
+ - ``VIDEO_PALETTE_YUV420P``
+
+ - :ref:`V4L2_PIX_FMT_YVU420 <V4L2-PIX-FMT-YVU420>`
+
+ - .. row 17
+
+ - ``VIDEO_PALETTE_YUV410P``
+
+ - :ref:`V4L2_PIX_FMT_YVU410 <V4L2-PIX-FMT-YVU410>`
+
+
+V4L2 image formats are defined in :ref:`pixfmt`. The image format can
+be selected with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
+
+
+Audio
+=====
+
+The ``VIDIOCGAUDIO`` and ``VIDIOCSAUDIO`` ioctl and struct
+:c:type:`struct video_audio` are used to enumerate the audio inputs
+of a V4L device. The equivalent V4L2 ioctls are
+:ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` and
+:ref:`VIDIOC_S_AUDIO <VIDIOC_G_AUDIO>` using struct
+:ref:`v4l2_audio <v4l2-audio>` as discussed in :ref:`audio`.
+
+The ``audio`` "channel number" field counting audio inputs was renamed
+to ``index``.
+
+On ``VIDIOCSAUDIO`` the ``mode`` field selects *one* of the
+``VIDEO_SOUND_MONO``, ``VIDEO_SOUND_STEREO``, ``VIDEO_SOUND_LANG1`` or
+``VIDEO_SOUND_LANG2`` audio demodulation modes. When the current audio
+standard is BTSC ``VIDEO_SOUND_LANG2`` refers to SAP and
+``VIDEO_SOUND_LANG1`` is meaningless. Also undocumented in the V4L
+specification, there is no way to query the selected mode. On
+``VIDIOCGAUDIO`` the driver returns the *actually received* audio
+programmes in this field. In the V4L2 API this information is stored in
+the struct :ref:`v4l2_tuner <v4l2-tuner>` ``rxsubchans`` and
+``audmode`` fields, respectively. See :ref:`tuner` for more
+information on tuners. Related to audio modes struct
+:ref:`v4l2_audio <v4l2-audio>` also reports if this is a mono or
+stereo input, regardless if the source is a tuner.
+
+The following fields where replaced by V4L2 controls accessible with the
+:ref:`VIDIOC_QUERYCTRL`,
+:ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and
+:ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls:
+
+
+
+.. flat-table::
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - struct :c:type:`struct video_audio`
+
+ - V4L2 Control ID
+
+ - .. row 2
+
+ - ``volume``
+
+ - ``V4L2_CID_AUDIO_VOLUME``
+
+ - .. row 3
+
+ - ``bass``
+
+ - ``V4L2_CID_AUDIO_BASS``
+
+ - .. row 4
+
+ - ``treble``
+
+ - ``V4L2_CID_AUDIO_TREBLE``
+
+ - .. row 5
+
+ - ``balance``
+
+ - ``V4L2_CID_AUDIO_BALANCE``
+
+
+To determine which of these controls are supported by a driver V4L
+provides the ``flags`` ``VIDEO_AUDIO_VOLUME``, ``VIDEO_AUDIO_BASS``,
+``VIDEO_AUDIO_TREBLE`` and ``VIDEO_AUDIO_BALANCE``. In the V4L2 API the
+:ref:`VIDIOC_QUERYCTRL` ioctl reports if the
+respective control is supported. Accordingly the ``VIDEO_AUDIO_MUTABLE``
+and ``VIDEO_AUDIO_MUTE`` flags where replaced by the boolean
+``V4L2_CID_AUDIO_MUTE`` control.
+
+All V4L2 controls have a ``step`` attribute replacing the struct
+:c:type:`struct video_audio` ``step`` field. The V4L audio controls
+are assumed to range from 0 to 65535 with no particular reset value. The
+V4L2 API permits arbitrary limits and defaults which can be queried with
+the :ref:`VIDIOC_QUERYCTRL` ioctl. For general
+information about controls see :ref:`control`.
+
+
+Frame Buffer Overlay
+====================
+
+The V4L2 ioctls equivalent to ``VIDIOCGFBUF`` and ``VIDIOCSFBUF`` are
+:ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` and
+:ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`. The ``base`` field of struct
+:c:type:`struct video_buffer` remained unchanged, except V4L2 defines
+a flag to indicate non-destructive overlays instead of a ``NULL``
+pointer. All other fields moved into the struct
+:ref:`v4l2_pix_format <v4l2-pix-format>` ``fmt`` substructure of
+struct :ref:`v4l2_framebuffer <v4l2-framebuffer>`. The ``depth``
+field was replaced by ``pixelformat``. See :ref:`pixfmt-rgb` for a
+list of RGB formats and their respective color depths.
+
+Instead of the special ioctls ``VIDIOCGWIN`` and ``VIDIOCSWIN`` V4L2
+uses the general-purpose data format negotiation ioctls
+:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
+:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. They take a pointer to a struct
+:ref:`v4l2_format <v4l2-format>` as argument. Here the ``win`` member
+of the ``fmt`` union is used, a struct
+:ref:`v4l2_window <v4l2-window>`.
+
+The ``x``, ``y``, ``width`` and ``height`` fields of struct
+:c:type:`struct video_window` moved into struct
+:ref:`v4l2_rect <v4l2-rect>` substructure ``w`` of struct
+:c:type:`struct v4l2_window`. The ``chromakey``, ``clips``, and
+``clipcount`` fields remained unchanged. Struct
+:c:type:`struct video_clip` was renamed to struct
+:ref:`v4l2_clip <v4l2-clip>`, also containing a struct
+:c:type:`struct v4l2_rect`, but the semantics are still the same.
+
+The ``VIDEO_WINDOW_INTERLACE`` flag was dropped. Instead applications
+must set the ``field`` field to ``V4L2_FIELD_ANY`` or
+``V4L2_FIELD_INTERLACED``. The ``VIDEO_WINDOW_CHROMAKEY`` flag moved
+into struct :ref:`v4l2_framebuffer <v4l2-framebuffer>`, under the new
+name ``V4L2_FBUF_FLAG_CHROMAKEY``.
+
+In V4L, storing a bitmap pointer in ``clips`` and setting ``clipcount``
+to ``VIDEO_CLIP_BITMAP`` (-1) requests bitmap clipping, using a fixed
+size bitmap of 1024 × 625 bits. Struct :c:type:`struct v4l2_window`
+has a separate ``bitmap`` pointer field for this purpose and the bitmap
+size is determined by ``w.width`` and ``w.height``.
+
+The ``VIDIOCCAPTURE`` ioctl to enable or disable overlay was renamed to
+:ref:`VIDIOC_OVERLAY`.
+
+
+Cropping
+========
+
+To capture only a subsection of the full picture V4L defines the
+``VIDIOCGCAPTURE`` and ``VIDIOCSCAPTURE`` ioctls using struct
+:c:type:`struct video_capture`. The equivalent V4L2 ioctls are
+:ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and
+:ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` using struct
+:ref:`v4l2_crop <v4l2-crop>`, and the related
+:ref:`VIDIOC_CROPCAP` ioctl. This is a rather
+complex matter, see :ref:`crop` for details.
+
+The ``x``, ``y``, ``width`` and ``height`` fields moved into struct
+:ref:`v4l2_rect <v4l2-rect>` substructure ``c`` of struct
+:c:type:`struct v4l2_crop`. The ``decimation`` field was dropped. In
+the V4L2 API the scaling factor is implied by the size of the cropping
+rectangle and the size of the captured or overlaid image.
+
+The ``VIDEO_CAPTURE_ODD`` and ``VIDEO_CAPTURE_EVEN`` flags to capture
+only the odd or even field, respectively, were replaced by
+``V4L2_FIELD_TOP`` and ``V4L2_FIELD_BOTTOM`` in the field named
+``field`` of struct :ref:`v4l2_pix_format <v4l2-pix-format>` and
+struct :ref:`v4l2_window <v4l2-window>`. These structures are used to
+select a capture or overlay format with the
+:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
+
+
+Reading Images, Memory Mapping
+==============================
+
+
+Capturing using the read method
+-------------------------------
+
+There is no essential difference between reading images from a V4L or
+V4L2 device using the :ref:`read() <func-read>` function, however V4L2
+drivers are not required to support this I/O method. Applications can
+determine if the function is available with the
+:ref:`VIDIOC_QUERYCAP` ioctl. All V4L2 devices
+exchanging data with applications must support the
+:ref:`select() <func-select>` and :ref:`poll() <func-poll>`
+functions.
+
+To select an image format and size, V4L provides the ``VIDIOCSPICT`` and
+``VIDIOCSWIN`` ioctls. V4L2 uses the general-purpose data format
+negotiation ioctls :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
+:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. They take a pointer to a struct
+:ref:`v4l2_format <v4l2-format>` as argument, here the struct
+:ref:`v4l2_pix_format <v4l2-pix-format>` named ``pix`` of its
+``fmt`` union is used.
+
+For more information about the V4L2 read interface see :ref:`rw`.
+
+
+Capturing using memory mapping
+------------------------------
+
+Applications can read from V4L devices by mapping buffers in device
+memory, or more often just buffers allocated in DMA-able system memory,
+into their address space. This avoids the data copying overhead of the
+read method. V4L2 supports memory mapping as well, with a few
+differences.
+
+
+
+.. flat-table::
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - V4L
+
+ - V4L2
+
+ - .. row 2
+
+ -
+ - The image format must be selected before buffers are allocated,
+ with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. When no
+ format is selected the driver may use the last, possibly by
+ another application requested format.
+
+ - .. row 3
+
+ - Applications cannot change the number of buffers. The it is built
+ into the driver, unless it has a module option to change the
+ number when the driver module is loaded.
+
+ - The :ref:`VIDIOC_REQBUFS` ioctl allocates the
+ desired number of buffers, this is a required step in the
+ initialization sequence.
+
+ - .. row 4
+
+ - Drivers map all buffers as one contiguous range of memory. The
+ ``VIDIOCGMBUF`` ioctl is available to query the number of buffers,
+ the offset of each buffer from the start of the virtual file, and
+ the overall amount of memory used, which can be used as arguments
+ for the :ref:`mmap() <func-mmap>` function.
+
+ - Buffers are individually mapped. The offset and size of each
+ buffer can be determined with the
+ :ref:`VIDIOC_QUERYBUF` ioctl.
+
+ - .. row 5
+
+ - The ``VIDIOCMCAPTURE`` ioctl prepares a buffer for capturing. It
+ also determines the image format for this buffer. The ioctl
+ returns immediately, eventually with an ``EAGAIN`` error code if no
+ video signal had been detected. When the driver supports more than
+ one buffer applications can call the ioctl multiple times and thus
+ have multiple outstanding capture requests.
+
+ The ``VIDIOCSYNC`` ioctl suspends execution until a particular
+ buffer has been filled.
+
+ - Drivers maintain an incoming and outgoing queue.
+ :ref:`VIDIOC_QBUF` enqueues any empty buffer into
+ the incoming queue. Filled buffers are dequeued from the outgoing
+ queue with the :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. To wait
+ until filled buffers become available this function,
+ :ref:`select() <func-select>` or :ref:`poll() <func-poll>` can
+ be used. The :ref:`VIDIOC_STREAMON` ioctl
+ must be called once after enqueuing one or more buffers to start
+ capturing. Its counterpart
+ :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` stops capturing and
+ dequeues all buffers from both queues. Applications can query the
+ signal status, if known, with the
+ :ref:`VIDIOC_ENUMINPUT` ioctl.
+
+
+For a more in-depth discussion of memory mapping and examples, see
+:ref:`mmap`.
+
+
+Reading Raw VBI Data
+====================
+
+Originally the V4L API did not specify a raw VBI capture interface, only
+the device file ``/dev/vbi`` was reserved for this purpose. The only
+driver supporting this interface was the BTTV driver, de-facto defining
+the V4L VBI interface. Reading from the device yields a raw VBI image
+with the following parameters:
+
+
+
+.. flat-table::
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - struct :ref:`v4l2_vbi_format <v4l2-vbi-format>`
+
+ - V4L, BTTV driver
+
+ - .. row 2
+
+ - sampling_rate
+
+ - 28636363 Hz NTSC (or any other 525-line standard); 35468950 Hz PAL
+ and SECAM (625-line standards)
+
+ - .. row 3
+
+ - offset
+
+ - ?
+
+ - .. row 4
+
+ - samples_per_line
+
+ - 2048
+
+ - .. row 5
+
+ - sample_format
+
+ - V4L2_PIX_FMT_GREY. The last four bytes (a machine endianness
+ integer) contain a frame counter.
+
+ - .. row 6
+
+ - start[]
+
+ - 10, 273 NTSC; 22, 335 PAL and SECAM
+
+ - .. row 7
+
+ - count[]
+
+ - 16, 16 [9]_
+
+ - .. row 8
+
+ - flags
+
+ - 0
+
+
+Undocumented in the V4L specification, in Linux 2.3 the
+``VIDIOCGVBIFMT`` and ``VIDIOCSVBIFMT`` ioctls using struct
+:c:type:`struct vbi_format` were added to determine the VBI image
+parameters. These ioctls are only partially compatible with the V4L2 VBI
+interface specified in :ref:`raw-vbi`.
+
+An ``offset`` field does not exist, ``sample_format`` is supposed to be
+``VIDEO_PALETTE_RAW``, equivalent to ``V4L2_PIX_FMT_GREY``. The
+remaining fields are probably equivalent to struct
+:ref:`v4l2_vbi_format <v4l2-vbi-format>`.
+
+Apparently only the Zoran (ZR 36120) driver implements these ioctls. The
+semantics differ from those specified for V4L2 in two ways. The
+parameters are reset on :ref:`open() <func-open>` and
+``VIDIOCSVBIFMT`` always returns an ``EINVAL`` error code if the parameters
+are invalid.
+
+
+Miscellaneous
+=============
+
+V4L2 has no equivalent of the ``VIDIOCGUNIT`` ioctl. Applications can
+find the VBI device associated with a video capture device (or vice
+versa) by reopening the device and requesting VBI data. For details see
+:ref:`open`.
+
+No replacement exists for ``VIDIOCKEY``, and the V4L functions for
+microcode programming. A new interface for MPEG compression and playback
+devices is documented in :ref:`extended-controls`.
+
+.. [1]
+ According to Documentation/devices.txt these should be symbolic links
+ to ``/dev/video0``. Note the original bttv interface is not
+ compatible with V4L or V4L2.
+
+.. [2]
+ According to ``Documentation/devices.txt`` a symbolic link to
+ ``/dev/radio0``.
+
+.. [3]
+ This is a custom format used by the BTTV driver, not one of the V4L2
+ standard formats.
+
+.. [4]
+ Presumably all V4L RGB formats are little-endian, although some
+ drivers might interpret them according to machine endianness. V4L2
+ defines little-endian, big-endian and red/blue swapped variants. For
+ details see :ref:`pixfmt-rgb`.
+
+.. [5]
+ ``VIDEO_PALETTE_YUV422`` and ``VIDEO_PALETTE_YUYV`` are the same
+ formats. Some V4L drivers respond to one, some to the other.
+
+.. [6]
+ Not to be confused with ``V4L2_PIX_FMT_YUV411P``, which is a planar
+ format.
+
+.. [7]
+ V4L explains this as: "RAW capture (BT848)"
+
+.. [8]
+ Not to be confused with ``V4L2_PIX_FMT_Y41P``, which is a packed
+ format.
+
+.. [9]
+ Old driver versions used different values, eventually the custom
+ ``BTTV_VBISIZE`` ioctl was added to query the correct values.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _dmabuf:
+
+************************************
+Streaming I/O (DMA buffer importing)
+************************************
+
+The DMABUF framework provides a generic method for sharing buffers
+between multiple devices. Device drivers that support DMABUF can export
+a DMA buffer to userspace as a file descriptor (known as the exporter
+role), import a DMA buffer from userspace using a file descriptor
+previously exported for a different or the same device (known as the
+importer role), or both. This section describes the DMABUF importer role
+API in V4L2.
+
+Refer to :ref:`DMABUF exporting <VIDIOC_EXPBUF>` for details about
+exporting V4L2 buffers as DMABUF file descriptors.
+
+Input and output devices support the streaming I/O method when the
+``V4L2_CAP_STREAMING`` flag in the ``capabilities`` field of struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP <VIDIOC_QUERYCAP>` ioctl is set. Whether
+importing DMA buffers through DMABUF file descriptors is supported is
+determined by calling the :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`
+ioctl with the memory type set to ``V4L2_MEMORY_DMABUF``.
+
+This I/O method is dedicated to sharing DMA buffers between different
+devices, which may be V4L devices or other video-related devices (e.g.
+DRM). Buffers (planes) are allocated by a driver on behalf of an
+application. Next, these buffers are exported to the application as file
+descriptors using an API which is specific for an allocator driver. Only
+such file descriptor are exchanged. The descriptors and meta-information
+are passed in struct :ref:`v4l2_buffer <v4l2-buffer>` (or in struct
+:ref:`v4l2_plane <v4l2-plane>` in the multi-planar API case). The
+driver must be switched into DMABUF I/O mode by calling the
+:ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>` with the desired buffer type.
+
+
+.. code-block:: c
+ :caption: Example 3.4. Initiating streaming I/O with DMABUF file descriptors
+
+ struct v4l2_requestbuffers reqbuf;
+
+ memset(&reqbuf, 0, sizeof (reqbuf));
+ reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ reqbuf.memory = V4L2_MEMORY_DMABUF;
+ reqbuf.count = 1;
+
+ if (ioctl(fd, VIDIOC_REQBUFS, &reqbuf) == -1) {
+ if (errno == EINVAL)
+ printf("Video capturing or DMABUF streaming is not supported\\n");
+ else
+ perror("VIDIOC_REQBUFS");
+
+ exit(EXIT_FAILURE);
+ }
+
+The buffer (plane) file descriptor is passed on the fly with the
+:ref:`VIDIOC_QBUF <VIDIOC_QBUF>` ioctl. In case of multiplanar
+buffers, every plane can be associated with a different DMABUF
+descriptor. Although buffers are commonly cycled, applications can pass
+a different DMABUF descriptor at each :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` call.
+
+
+.. code-block:: c
+ :caption: Example 3.5. Queueing DMABUF using single plane API
+
+ int buffer_queue(int v4lfd, int index, int dmafd)
+ {
+ struct v4l2_buffer buf;
+
+ memset(&buf, 0, sizeof buf);
+ buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ buf.memory = V4L2_MEMORY_DMABUF;
+ buf.index = index;
+ buf.m.fd = dmafd;
+
+ if (ioctl(v4lfd, VIDIOC_QBUF, &buf) == -1) {
+ perror("VIDIOC_QBUF");
+ return -1;
+ }
+
+ return 0;
+ }
+
+
+.. code-block:: c
+ :caption: Example 3.6. Queueing DMABUF using multi plane API
+
+ int buffer_queue_mp(int v4lfd, int index, int dmafd[], int n_planes)
+ {
+ struct v4l2_buffer buf;
+ struct v4l2_plane planes[VIDEO_MAX_PLANES];
+ int i;
+
+ memset(&buf, 0, sizeof buf);
+ buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE;
+ buf.memory = V4L2_MEMORY_DMABUF;
+ buf.index = index;
+ buf.m.planes = planes;
+ buf.length = n_planes;
+
+ memset(&planes, 0, sizeof planes);
+
+ for (i = 0; i < n_planes; ++i)
+ buf.m.planes[i].m.fd = dmafd[i];
+
+ if (ioctl(v4lfd, VIDIOC_QBUF, &buf) == -1) {
+ perror("VIDIOC_QBUF");
+ return -1;
+ }
+
+ return 0;
+ }
+
+Captured or displayed buffers are dequeued with the
+:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. The driver can unlock the
+buffer at any time between the completion of the DMA and this ioctl. The
+memory is also unlocked when
+:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` is called,
+:ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, or when the device is closed.
+
+For capturing applications it is customary to enqueue a number of empty
+buffers, to start capturing and enter the read loop. Here the
+application waits until a filled buffer can be dequeued, and re-enqueues
+the buffer when the data is no longer needed. Output applications fill
+and enqueue buffers, when enough buffers are stacked up output is
+started. In the write loop, when the application runs out of free
+buffers it must wait until an empty buffer can be dequeued and reused.
+Two methods exist to suspend execution of the application until one or
+more buffers can be dequeued. By default :ref:`VIDIOC_DQBUF
+<VIDIOC_QBUF>` blocks when no buffer is in the outgoing queue. When the
+``O_NONBLOCK`` flag was given to the :ref:`open() <func-open>` function,
+:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` returns immediately with an ``EAGAIN``
+error code when no buffer is available. The
+:ref:`select() <func-select>` and :ref:`poll() <func-poll>`
+functions are always available.
+
+To start and stop capturing or displaying applications call the
+:ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and
+:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls. Note that
+:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` removes all buffers from
+both queues and unlocks all buffers as a side effect. Since there is no
+notion of doing anything "now" on a multitasking system, if an
+application needs to synchronize with another event it should examine
+the struct :ref:`v4l2_buffer <v4l2-buffer>` ``timestamp`` of captured or
+outputted buffers.
+
+Drivers implementing DMABUF importing I/O must support the
+:ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`,
+:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_STREAMON
+<VIDIOC_STREAMON>` and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls,
+and the :ref:`select() <func-select>` and :ref:`poll() <func-poll>`
+functions.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _driver:
+
+***********************
+V4L2 Driver Programming
+***********************
+
+to do
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _dv-timings:
+
+**************************
+Digital Video (DV) Timings
+**************************
+
+The video standards discussed so far have been dealing with Analog TV
+and the corresponding video timings. Today there are many more different
+hardware interfaces such as High Definition TV interfaces (HDMI), VGA,
+DVI connectors etc., that carry video signals and there is a need to
+extend the API to select the video timings for these interfaces. Since
+it is not possible to extend the :ref:`v4l2_std_id <v4l2-std-id>`
+due to the limited bits available, a new set of ioctls was added to
+set/get video timings at the input and output.
+
+These ioctls deal with the detailed digital video timings that define
+each video format. This includes parameters such as the active video
+width and height, signal polarities, frontporches, backporches, sync
+widths etc. The ``linux/v4l2-dv-timings.h`` header can be used to get
+the timings of the formats in the :ref:`cea861` and :ref:`vesadmt`
+standards.
+
+To enumerate and query the attributes of the DV timings supported by a
+device applications use the
+:ref:`VIDIOC_ENUM_DV_TIMINGS` and
+:ref:`VIDIOC_DV_TIMINGS_CAP` ioctls. To set
+DV timings for the device applications use the
+:ref:`VIDIOC_S_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>` ioctl and to get
+current DV timings they use the
+:ref:`VIDIOC_G_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>` ioctl. To detect
+the DV timings as seen by the video receiver applications use the
+:ref:`VIDIOC_QUERY_DV_TIMINGS` ioctl.
+
+Applications can make use of the :ref:`input-capabilities` and
+:ref:`output-capabilities` flags to determine whether the digital
+video ioctls can be used with the given input or output.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _extended-controls:
+
+*****************
+Extended Controls
+*****************
+
+
+Introduction
+============
+
+The control mechanism as originally designed was meant to be used for
+user settings (brightness, saturation, etc). However, it turned out to
+be a very useful model for implementing more complicated driver APIs
+where each driver implements only a subset of a larger API.
+
+The MPEG encoding API was the driving force behind designing and
+implementing this extended control mechanism: the MPEG standard is quite
+large and the currently supported hardware MPEG encoders each only
+implement a subset of this standard. Further more, many parameters
+relating to how the video is encoded into an MPEG stream are specific to
+the MPEG encoding chip since the MPEG standard only defines the format
+of the resulting MPEG stream, not how the video is actually encoded into
+that format.
+
+Unfortunately, the original control API lacked some features needed for
+these new uses and so it was extended into the (not terribly originally
+named) extended control API.
+
+Even though the MPEG encoding API was the first effort to use the
+Extended Control API, nowadays there are also other classes of Extended
+Controls, such as Camera Controls and FM Transmitter Controls. The
+Extended Controls API as well as all Extended Controls classes are
+described in the following text.
+
+
+The Extended Control API
+========================
+
+Three new ioctls are available:
+:ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`,
+:ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` and
+:ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`. These ioctls act
+on arrays of controls (as opposed to the
+:ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and
+:ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls that act on a single
+control). This is needed since it is often required to atomically change
+several controls at once.
+
+Each of the new ioctls expects a pointer to a struct
+:ref:`v4l2_ext_controls <v4l2-ext-controls>`. This structure
+contains a pointer to the control array, a count of the number of
+controls in that array and a control class. Control classes are used to
+group similar controls into a single class. For example, control class
+``V4L2_CTRL_CLASS_USER`` contains all user controls (i. e. all controls
+that can also be set using the old :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>`
+ioctl). Control class ``V4L2_CTRL_CLASS_MPEG`` contains all controls
+relating to MPEG encoding, etc.
+
+All controls in the control array must belong to the specified control
+class. An error is returned if this is not the case.
+
+It is also possible to use an empty control array (``count`` == 0) to check
+whether the specified control class is supported.
+
+The control array is a struct
+:ref:`v4l2_ext_control <v4l2-ext-control>` array. The
+:ref:`struct v4l2_ext_control <v4l2-ext-control>` structure is very similar to
+struct :ref:`v4l2_control <v4l2-control>`, except for the fact that
+it also allows for 64-bit values and pointers to be passed.
+
+Since the struct :ref:`v4l2_ext_control <v4l2-ext-control>` supports
+pointers it is now also possible to have controls with compound types
+such as N-dimensional arrays and/or structures. You need to specify the
+``V4L2_CTRL_FLAG_NEXT_COMPOUND`` when enumerating controls to actually
+be able to see such compound controls. In other words, these controls
+with compound types should only be used programmatically.
+
+Since such compound controls need to expose more information about
+themselves than is possible with
+:ref:`VIDIOC_QUERYCTRL` the
+:ref:`VIDIOC_QUERY_EXT_CTRL <VIDIOC_QUERYCTRL>` ioctl was added. In
+particular, this ioctl gives the dimensions of the N-dimensional array
+if this control consists of more than one element.
+
+It is important to realize that due to the flexibility of controls it is
+necessary to check whether the control you want to set actually is
+supported in the driver and what the valid range of values is. So use
+the :ref:`VIDIOC_QUERYCTRL` (or
+:ref:`VIDIOC_QUERY_EXT_CTRL <VIDIOC_QUERYCTRL>`) and
+:ref:`VIDIOC_QUERYMENU <VIDIOC_QUERYCTRL>` ioctls to check this. Also
+note that it is possible that some of the menu indices in a control of
+type ``V4L2_CTRL_TYPE_MENU`` may not be supported (``VIDIOC_QUERYMENU``
+will return an error). A good example is the list of supported MPEG
+audio bitrates. Some drivers only support one or two bitrates, others
+support a wider range.
+
+All controls use machine endianness.
+
+
+Enumerating Extended Controls
+=============================
+
+The recommended way to enumerate over the extended controls is by using
+:ref:`VIDIOC_QUERYCTRL` in combination with the
+``V4L2_CTRL_FLAG_NEXT_CTRL`` flag:
+
+
+.. code-block:: c
+
+ struct v4l2_queryctrl qctrl;
+
+ qctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL;
+ while (0 == ioctl (fd, VIDIOC_QUERYCTRL, &qctrl)) {
+ /* ... */
+ qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
+ }
+
+The initial control ID is set to 0 ORed with the
+``V4L2_CTRL_FLAG_NEXT_CTRL`` flag. The ``VIDIOC_QUERYCTRL`` ioctl will
+return the first control with a higher ID than the specified one. When
+no such controls are found an error is returned.
+
+If you want to get all controls within a specific control class, then
+you can set the initial ``qctrl.id`` value to the control class and add
+an extra check to break out of the loop when a control of another
+control class is found:
+
+
+.. code-block:: c
+
+ qctrl.id = V4L2_CTRL_CLASS_MPEG | V4L2_CTRL_FLAG_NEXT_CTRL;
+ while (0 == ioctl(fd, VIDIOC_QUERYCTRL, &qctrl)) {
+ if (V4L2_CTRL_ID2CLASS(qctrl.id) != V4L2_CTRL_CLASS_MPEG)
+ break;
+ /* ... */
+ qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
+ }
+
+The 32-bit ``qctrl.id`` value is subdivided into three bit ranges: the
+top 4 bits are reserved for flags (e. g. ``V4L2_CTRL_FLAG_NEXT_CTRL``)
+and are not actually part of the ID. The remaining 28 bits form the
+control ID, of which the most significant 12 bits define the control
+class and the least significant 16 bits identify the control within the
+control class. It is guaranteed that these last 16 bits are always
+non-zero for controls. The range of 0x1000 and up are reserved for
+driver-specific controls. The macro ``V4L2_CTRL_ID2CLASS(id)`` returns
+the control class ID based on a control ID.
+
+If the driver does not support extended controls, then
+``VIDIOC_QUERYCTRL`` will fail when used in combination with
+``V4L2_CTRL_FLAG_NEXT_CTRL``. In that case the old method of enumerating
+control should be used (see :ref:`enum_all_controls`). But if it is
+supported, then it is guaranteed to enumerate over all controls,
+including driver-private controls.
+
+
+Creating Control Panels
+=======================
+
+It is possible to create control panels for a graphical user interface
+where the user can select the various controls. Basically you will have
+to iterate over all controls using the method described above. Each
+control class starts with a control of type
+``V4L2_CTRL_TYPE_CTRL_CLASS``. ``VIDIOC_QUERYCTRL`` will return the name
+of this control class which can be used as the title of a tab page
+within a control panel.
+
+The flags field of struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` also
+contains hints on the behavior of the control. See the
+:ref:`VIDIOC_QUERYCTRL` documentation for more
+details.
+
+
+.. _mpeg-controls:
+
+Codec Control Reference
+=======================
+
+Below all controls within the Codec control class are described. First
+the generic controls, then controls specific for certain hardware.
+
+Note: These controls are applicable to all codecs and not just MPEG. The
+defines are prefixed with V4L2_CID_MPEG/V4L2_MPEG as the controls
+were originally made for MPEG codecs and later extended to cover all
+encoding formats.
+
+
+Generic Codec Controls
+----------------------
+
+
+.. _mpeg-control-id:
+
+Codec Control IDs
+^^^^^^^^^^^^^^^^^
+
+``V4L2_CID_MPEG_CLASS (class)``
+ The Codec class descriptor. Calling
+ :ref:`VIDIOC_QUERYCTRL` for this control will
+ return a description of this control class. This description can be
+ used as the caption of a Tab page in a GUI, for example.
+
+.. _v4l2-mpeg-stream-type:
+
+``V4L2_CID_MPEG_STREAM_TYPE (enum v4l2_mpeg_stream_type)``
+ The MPEG-1, -2 or -4 output stream type. One cannot assume anything
+ here. Each hardware MPEG encoder tends to support different subsets
+ of the available MPEG stream types. This control is specific to
+ multiplexed MPEG streams. The currently defined stream types are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_STREAM_TYPE_MPEG2_PS``
+
+ - MPEG-2 program stream
+
+ - .. row 2
+
+ - ``V4L2_MPEG_STREAM_TYPE_MPEG2_TS``
+
+ - MPEG-2 transport stream
+
+ - .. row 3
+
+ - ``V4L2_MPEG_STREAM_TYPE_MPEG1_SS``
+
+ - MPEG-1 system stream
+
+ - .. row 4
+
+ - ``V4L2_MPEG_STREAM_TYPE_MPEG2_DVD``
+
+ - MPEG-2 DVD-compatible stream
+
+ - .. row 5
+
+ - ``V4L2_MPEG_STREAM_TYPE_MPEG1_VCD``
+
+ - MPEG-1 VCD-compatible stream
+
+ - .. row 6
+
+ - ``V4L2_MPEG_STREAM_TYPE_MPEG2_SVCD``
+
+ - MPEG-2 SVCD-compatible stream
+
+
+
+``V4L2_CID_MPEG_STREAM_PID_PMT (integer)``
+ Program Map Table Packet ID for the MPEG transport stream (default
+ 16)
+
+``V4L2_CID_MPEG_STREAM_PID_AUDIO (integer)``
+ Audio Packet ID for the MPEG transport stream (default 256)
+
+``V4L2_CID_MPEG_STREAM_PID_VIDEO (integer)``
+ Video Packet ID for the MPEG transport stream (default 260)
+
+``V4L2_CID_MPEG_STREAM_PID_PCR (integer)``
+ Packet ID for the MPEG transport stream carrying PCR fields (default
+ 259)
+
+``V4L2_CID_MPEG_STREAM_PES_ID_AUDIO (integer)``
+ Audio ID for MPEG PES
+
+``V4L2_CID_MPEG_STREAM_PES_ID_VIDEO (integer)``
+ Video ID for MPEG PES
+
+.. _v4l2-mpeg-stream-vbi-fmt:
+
+``V4L2_CID_MPEG_STREAM_VBI_FMT (enum v4l2_mpeg_stream_vbi_fmt)``
+ Some cards can embed VBI data (e. g. Closed Caption, Teletext) into
+ the MPEG stream. This control selects whether VBI data should be
+ embedded, and if so, what embedding method should be used. The list
+ of possible VBI formats depends on the driver. The currently defined
+ VBI format types are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_STREAM_VBI_FMT_NONE``
+
+ - No VBI in the MPEG stream
+
+ - .. row 2
+
+ - ``V4L2_MPEG_STREAM_VBI_FMT_IVTV``
+
+ - VBI in private packets, IVTV format (documented in the kernel
+ sources in the file
+ ``Documentation/video4linux/cx2341x/README.vbi``)
+
+
+
+.. _v4l2-mpeg-audio-sampling-freq:
+
+``V4L2_CID_MPEG_AUDIO_SAMPLING_FREQ (enum v4l2_mpeg_audio_sampling_freq)``
+ MPEG Audio sampling frequency. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_AUDIO_SAMPLING_FREQ_44100``
+
+ - 44.1 kHz
+
+ - .. row 2
+
+ - ``V4L2_MPEG_AUDIO_SAMPLING_FREQ_48000``
+
+ - 48 kHz
+
+ - .. row 3
+
+ - ``V4L2_MPEG_AUDIO_SAMPLING_FREQ_32000``
+
+ - 32 kHz
+
+
+
+.. _v4l2-mpeg-audio-encoding:
+
+``V4L2_CID_MPEG_AUDIO_ENCODING (enum v4l2_mpeg_audio_encoding)``
+ MPEG Audio encoding. This control is specific to multiplexed MPEG
+ streams. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_AUDIO_ENCODING_LAYER_1``
+
+ - MPEG-1/2 Layer I encoding
+
+ - .. row 2
+
+ - ``V4L2_MPEG_AUDIO_ENCODING_LAYER_2``
+
+ - MPEG-1/2 Layer II encoding
+
+ - .. row 3
+
+ - ``V4L2_MPEG_AUDIO_ENCODING_LAYER_3``
+
+ - MPEG-1/2 Layer III encoding
+
+ - .. row 4
+
+ - ``V4L2_MPEG_AUDIO_ENCODING_AAC``
+
+ - MPEG-2/4 AAC (Advanced Audio Coding)
+
+ - .. row 5
+
+ - ``V4L2_MPEG_AUDIO_ENCODING_AC3``
+
+ - AC-3 aka ATSC A/52 encoding
+
+
+
+.. _v4l2-mpeg-audio-l1-bitrate:
+
+``V4L2_CID_MPEG_AUDIO_L1_BITRATE (enum v4l2_mpeg_audio_l1_bitrate)``
+ MPEG-1/2 Layer I bitrate. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_AUDIO_L1_BITRATE_32K``
+
+ - 32 kbit/s
+
+ - .. row 2
+
+ - ``V4L2_MPEG_AUDIO_L1_BITRATE_64K``
+
+ - 64 kbit/s
+
+ - .. row 3
+
+ - ``V4L2_MPEG_AUDIO_L1_BITRATE_96K``
+
+ - 96 kbit/s
+
+ - .. row 4
+
+ - ``V4L2_MPEG_AUDIO_L1_BITRATE_128K``
+
+ - 128 kbit/s
+
+ - .. row 5
+
+ - ``V4L2_MPEG_AUDIO_L1_BITRATE_160K``
+
+ - 160 kbit/s
+
+ - .. row 6
+
+ - ``V4L2_MPEG_AUDIO_L1_BITRATE_192K``
+
+ - 192 kbit/s
+
+ - .. row 7
+
+ - ``V4L2_MPEG_AUDIO_L1_BITRATE_224K``
+
+ - 224 kbit/s
+
+ - .. row 8
+
+ - ``V4L2_MPEG_AUDIO_L1_BITRATE_256K``
+
+ - 256 kbit/s
+
+ - .. row 9
+
+ - ``V4L2_MPEG_AUDIO_L1_BITRATE_288K``
+
+ - 288 kbit/s
+
+ - .. row 10
+
+ - ``V4L2_MPEG_AUDIO_L1_BITRATE_320K``
+
+ - 320 kbit/s
+
+ - .. row 11
+
+ - ``V4L2_MPEG_AUDIO_L1_BITRATE_352K``
+
+ - 352 kbit/s
+
+ - .. row 12
+
+ - ``V4L2_MPEG_AUDIO_L1_BITRATE_384K``
+
+ - 384 kbit/s
+
+ - .. row 13
+
+ - ``V4L2_MPEG_AUDIO_L1_BITRATE_416K``
+
+ - 416 kbit/s
+
+ - .. row 14
+
+ - ``V4L2_MPEG_AUDIO_L1_BITRATE_448K``
+
+ - 448 kbit/s
+
+
+
+.. _v4l2-mpeg-audio-l2-bitrate:
+
+``V4L2_CID_MPEG_AUDIO_L2_BITRATE (enum v4l2_mpeg_audio_l2_bitrate)``
+ MPEG-1/2 Layer II bitrate. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_AUDIO_L2_BITRATE_32K``
+
+ - 32 kbit/s
+
+ - .. row 2
+
+ - ``V4L2_MPEG_AUDIO_L2_BITRATE_48K``
+
+ - 48 kbit/s
+
+ - .. row 3
+
+ - ``V4L2_MPEG_AUDIO_L2_BITRATE_56K``
+
+ - 56 kbit/s
+
+ - .. row 4
+
+ - ``V4L2_MPEG_AUDIO_L2_BITRATE_64K``
+
+ - 64 kbit/s
+
+ - .. row 5
+
+ - ``V4L2_MPEG_AUDIO_L2_BITRATE_80K``
+
+ - 80 kbit/s
+
+ - .. row 6
+
+ - ``V4L2_MPEG_AUDIO_L2_BITRATE_96K``
+
+ - 96 kbit/s
+
+ - .. row 7
+
+ - ``V4L2_MPEG_AUDIO_L2_BITRATE_112K``
+
+ - 112 kbit/s
+
+ - .. row 8
+
+ - ``V4L2_MPEG_AUDIO_L2_BITRATE_128K``
+
+ - 128 kbit/s
+
+ - .. row 9
+
+ - ``V4L2_MPEG_AUDIO_L2_BITRATE_160K``
+
+ - 160 kbit/s
+
+ - .. row 10
+
+ - ``V4L2_MPEG_AUDIO_L2_BITRATE_192K``
+
+ - 192 kbit/s
+
+ - .. row 11
+
+ - ``V4L2_MPEG_AUDIO_L2_BITRATE_224K``
+
+ - 224 kbit/s
+
+ - .. row 12
+
+ - ``V4L2_MPEG_AUDIO_L2_BITRATE_256K``
+
+ - 256 kbit/s
+
+ - .. row 13
+
+ - ``V4L2_MPEG_AUDIO_L2_BITRATE_320K``
+
+ - 320 kbit/s
+
+ - .. row 14
+
+ - ``V4L2_MPEG_AUDIO_L2_BITRATE_384K``
+
+ - 384 kbit/s
+
+
+
+.. _v4l2-mpeg-audio-l3-bitrate:
+
+``V4L2_CID_MPEG_AUDIO_L3_BITRATE (enum v4l2_mpeg_audio_l3_bitrate)``
+ MPEG-1/2 Layer III bitrate. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_AUDIO_L3_BITRATE_32K``
+
+ - 32 kbit/s
+
+ - .. row 2
+
+ - ``V4L2_MPEG_AUDIO_L3_BITRATE_40K``
+
+ - 40 kbit/s
+
+ - .. row 3
+
+ - ``V4L2_MPEG_AUDIO_L3_BITRATE_48K``
+
+ - 48 kbit/s
+
+ - .. row 4
+
+ - ``V4L2_MPEG_AUDIO_L3_BITRATE_56K``
+
+ - 56 kbit/s
+
+ - .. row 5
+
+ - ``V4L2_MPEG_AUDIO_L3_BITRATE_64K``
+
+ - 64 kbit/s
+
+ - .. row 6
+
+ - ``V4L2_MPEG_AUDIO_L3_BITRATE_80K``
+
+ - 80 kbit/s
+
+ - .. row 7
+
+ - ``V4L2_MPEG_AUDIO_L3_BITRATE_96K``
+
+ - 96 kbit/s
+
+ - .. row 8
+
+ - ``V4L2_MPEG_AUDIO_L3_BITRATE_112K``
+
+ - 112 kbit/s
+
+ - .. row 9
+
+ - ``V4L2_MPEG_AUDIO_L3_BITRATE_128K``
+
+ - 128 kbit/s
+
+ - .. row 10
+
+ - ``V4L2_MPEG_AUDIO_L3_BITRATE_160K``
+
+ - 160 kbit/s
+
+ - .. row 11
+
+ - ``V4L2_MPEG_AUDIO_L3_BITRATE_192K``
+
+ - 192 kbit/s
+
+ - .. row 12
+
+ - ``V4L2_MPEG_AUDIO_L3_BITRATE_224K``
+
+ - 224 kbit/s
+
+ - .. row 13
+
+ - ``V4L2_MPEG_AUDIO_L3_BITRATE_256K``
+
+ - 256 kbit/s
+
+ - .. row 14
+
+ - ``V4L2_MPEG_AUDIO_L3_BITRATE_320K``
+
+ - 320 kbit/s
+
+
+
+``V4L2_CID_MPEG_AUDIO_AAC_BITRATE (integer)``
+ AAC bitrate in bits per second.
+
+.. _v4l2-mpeg-audio-ac3-bitrate:
+
+``V4L2_CID_MPEG_AUDIO_AC3_BITRATE (enum v4l2_mpeg_audio_ac3_bitrate)``
+ AC-3 bitrate. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_32K``
+
+ - 32 kbit/s
+
+ - .. row 2
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_40K``
+
+ - 40 kbit/s
+
+ - .. row 3
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_48K``
+
+ - 48 kbit/s
+
+ - .. row 4
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_56K``
+
+ - 56 kbit/s
+
+ - .. row 5
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_64K``
+
+ - 64 kbit/s
+
+ - .. row 6
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_80K``
+
+ - 80 kbit/s
+
+ - .. row 7
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_96K``
+
+ - 96 kbit/s
+
+ - .. row 8
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_112K``
+
+ - 112 kbit/s
+
+ - .. row 9
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_128K``
+
+ - 128 kbit/s
+
+ - .. row 10
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_160K``
+
+ - 160 kbit/s
+
+ - .. row 11
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_192K``
+
+ - 192 kbit/s
+
+ - .. row 12
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_224K``
+
+ - 224 kbit/s
+
+ - .. row 13
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_256K``
+
+ - 256 kbit/s
+
+ - .. row 14
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_320K``
+
+ - 320 kbit/s
+
+ - .. row 15
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_384K``
+
+ - 384 kbit/s
+
+ - .. row 16
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_448K``
+
+ - 448 kbit/s
+
+ - .. row 17
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_512K``
+
+ - 512 kbit/s
+
+ - .. row 18
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_576K``
+
+ - 576 kbit/s
+
+ - .. row 19
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_640K``
+
+ - 640 kbit/s
+
+
+
+.. _v4l2-mpeg-audio-mode:
+
+``V4L2_CID_MPEG_AUDIO_MODE (enum v4l2_mpeg_audio_mode)``
+ MPEG Audio mode. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_AUDIO_MODE_STEREO``
+
+ - Stereo
+
+ - .. row 2
+
+ - ``V4L2_MPEG_AUDIO_MODE_JOINT_STEREO``
+
+ - Joint Stereo
+
+ - .. row 3
+
+ - ``V4L2_MPEG_AUDIO_MODE_DUAL``
+
+ - Bilingual
+
+ - .. row 4
+
+ - ``V4L2_MPEG_AUDIO_MODE_MONO``
+
+ - Mono
+
+
+
+.. _v4l2-mpeg-audio-mode-extension:
+
+``V4L2_CID_MPEG_AUDIO_MODE_EXTENSION (enum v4l2_mpeg_audio_mode_extension)``
+ Joint Stereo audio mode extension. In Layer I and II they indicate
+ which subbands are in intensity stereo. All other subbands are coded
+ in stereo. Layer III is not (yet) supported. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_4``
+
+ - Subbands 4-31 in intensity stereo
+
+ - .. row 2
+
+ - ``V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_8``
+
+ - Subbands 8-31 in intensity stereo
+
+ - .. row 3
+
+ - ``V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_12``
+
+ - Subbands 12-31 in intensity stereo
+
+ - .. row 4
+
+ - ``V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_16``
+
+ - Subbands 16-31 in intensity stereo
+
+
+
+.. _v4l2-mpeg-audio-emphasis:
+
+``V4L2_CID_MPEG_AUDIO_EMPHASIS (enum v4l2_mpeg_audio_emphasis)``
+ Audio Emphasis. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_AUDIO_EMPHASIS_NONE``
+
+ - None
+
+ - .. row 2
+
+ - ``V4L2_MPEG_AUDIO_EMPHASIS_50_DIV_15_uS``
+
+ - 50/15 microsecond emphasis
+
+ - .. row 3
+
+ - ``V4L2_MPEG_AUDIO_EMPHASIS_CCITT_J17``
+
+ - CCITT J.17
+
+
+
+.. _v4l2-mpeg-audio-crc:
+
+``V4L2_CID_MPEG_AUDIO_CRC (enum v4l2_mpeg_audio_crc)``
+ CRC method. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_AUDIO_CRC_NONE``
+
+ - None
+
+ - .. row 2
+
+ - ``V4L2_MPEG_AUDIO_CRC_CRC16``
+
+ - 16 bit parity check
+
+
+
+``V4L2_CID_MPEG_AUDIO_MUTE (boolean)``
+ Mutes the audio when capturing. This is not done by muting audio
+ hardware, which can still produce a slight hiss, but in the encoder
+ itself, guaranteeing a fixed and reproducible audio bitstream. 0 =
+ unmuted, 1 = muted.
+
+.. _v4l2-mpeg-audio-dec-playback:
+
+``V4L2_CID_MPEG_AUDIO_DEC_PLAYBACK (enum v4l2_mpeg_audio_dec_playback)``
+ Determines how monolingual audio should be played back. Possible
+ values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_AUTO``
+
+ - Automatically determines the best playback mode.
+
+ - .. row 2
+
+ - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_STEREO``
+
+ - Stereo playback.
+
+ - .. row 3
+
+ - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_LEFT``
+
+ - Left channel playback.
+
+ - .. row 4
+
+ - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_RIGHT``
+
+ - Right channel playback.
+
+ - .. row 5
+
+ - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_MONO``
+
+ - Mono playback.
+
+ - .. row 6
+
+ - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_SWAPPED_STEREO``
+
+ - Stereo playback with swapped left and right channels.
+
+
+
+.. _v4l2-mpeg-audio-dec-multilingual-playback:
+
+``V4L2_CID_MPEG_AUDIO_DEC_MULTILINGUAL_PLAYBACK (enum v4l2_mpeg_audio_dec_playback)``
+ Determines how multilingual audio should be played back.
+
+.. _v4l2-mpeg-video-encoding:
+
+``V4L2_CID_MPEG_VIDEO_ENCODING (enum v4l2_mpeg_video_encoding)``
+ MPEG Video encoding method. This control is specific to multiplexed
+ MPEG streams. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_ENCODING_MPEG_1``
+
+ - MPEG-1 Video encoding
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_ENCODING_MPEG_2``
+
+ - MPEG-2 Video encoding
+
+ - .. row 3
+
+ - ``V4L2_MPEG_VIDEO_ENCODING_MPEG_4_AVC``
+
+ - MPEG-4 AVC (H.264) Video encoding
+
+
+
+.. _v4l2-mpeg-video-aspect:
+
+``V4L2_CID_MPEG_VIDEO_ASPECT (enum v4l2_mpeg_video_aspect)``
+ Video aspect. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_ASPECT_1x1``
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_ASPECT_4x3``
+
+ - .. row 3
+
+ - ``V4L2_MPEG_VIDEO_ASPECT_16x9``
+
+ - .. row 4
+
+ - ``V4L2_MPEG_VIDEO_ASPECT_221x100``
+
+
+
+``V4L2_CID_MPEG_VIDEO_B_FRAMES (integer)``
+ Number of B-Frames (default 2)
+
+``V4L2_CID_MPEG_VIDEO_GOP_SIZE (integer)``
+ GOP size (default 12)
+
+``V4L2_CID_MPEG_VIDEO_GOP_CLOSURE (boolean)``
+ GOP closure (default 1)
+
+``V4L2_CID_MPEG_VIDEO_PULLDOWN (boolean)``
+ Enable 3:2 pulldown (default 0)
+
+.. _v4l2-mpeg-video-bitrate-mode:
+
+``V4L2_CID_MPEG_VIDEO_BITRATE_MODE (enum v4l2_mpeg_video_bitrate_mode)``
+ Video bitrate mode. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_BITRATE_MODE_VBR``
+
+ - Variable bitrate
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_BITRATE_MODE_CBR``
+
+ - Constant bitrate
+
+
+
+``V4L2_CID_MPEG_VIDEO_BITRATE (integer)``
+ Video bitrate in bits per second.
+
+``V4L2_CID_MPEG_VIDEO_BITRATE_PEAK (integer)``
+ Peak video bitrate in bits per second. Must be larger or equal to
+ the average video bitrate. It is ignored if the video bitrate mode
+ is set to constant bitrate.
+
+``V4L2_CID_MPEG_VIDEO_TEMPORAL_DECIMATION (integer)``
+ For every captured frame, skip this many subsequent frames (default
+ 0).
+
+``V4L2_CID_MPEG_VIDEO_MUTE (boolean)``
+ "Mutes" the video to a fixed color when capturing. This is useful
+ for testing, to produce a fixed video bitstream. 0 = unmuted, 1 =
+ muted.
+
+``V4L2_CID_MPEG_VIDEO_MUTE_YUV (integer)``
+ Sets the "mute" color of the video. The supplied 32-bit integer is
+ interpreted as follows (bit 0 = least significant bit):
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Bit 0:7
+
+ - V chrominance information
+
+ - .. row 2
+
+ - Bit 8:15
+
+ - U chrominance information
+
+ - .. row 3
+
+ - Bit 16:23
+
+ - Y luminance information
+
+ - .. row 4
+
+ - Bit 24:31
+
+ - Must be zero.
+
+
+
+.. _v4l2-mpeg-video-dec-pts:
+
+``V4L2_CID_MPEG_VIDEO_DEC_PTS (integer64)``
+ This read-only control returns the 33-bit video Presentation Time
+ Stamp as defined in ITU T-REC-H.222.0 and ISO/IEC 13818-1 of the
+ currently displayed frame. This is the same PTS as is used in
+ :ref:`VIDIOC_DECODER_CMD`.
+
+.. _v4l2-mpeg-video-dec-frame:
+
+``V4L2_CID_MPEG_VIDEO_DEC_FRAME (integer64)``
+ This read-only control returns the frame counter of the frame that
+ is currently displayed (decoded). This value is reset to 0 whenever
+ the decoder is started.
+
+``V4L2_CID_MPEG_VIDEO_DECODER_SLICE_INTERFACE (boolean)``
+ If enabled the decoder expects to receive a single slice per buffer,
+ otherwise the decoder expects a single frame in per buffer.
+ Applicable to the decoder, all codecs.
+
+``V4L2_CID_MPEG_VIDEO_H264_VUI_SAR_ENABLE (boolean)``
+ Enable writing sample aspect ratio in the Video Usability
+ Information. Applicable to the H264 encoder.
+
+.. _v4l2-mpeg-video-h264-vui-sar-idc:
+
+``V4L2_CID_MPEG_VIDEO_H264_VUI_SAR_IDC (enum v4l2_mpeg_video_h264_vui_sar_idc)``
+ VUI sample aspect ratio indicator for H.264 encoding. The value is
+ defined in the table E-1 in the standard. Applicable to the H264
+ encoder.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_UNSPECIFIED``
+
+ - Unspecified
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_1x1``
+
+ - 1x1
+
+ - .. row 3
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_12x11``
+
+ - 12x11
+
+ - .. row 4
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_10x11``
+
+ - 10x11
+
+ - .. row 5
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_16x11``
+
+ - 16x11
+
+ - .. row 6
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_40x33``
+
+ - 40x33
+
+ - .. row 7
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_24x11``
+
+ - 24x11
+
+ - .. row 8
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_20x11``
+
+ - 20x11
+
+ - .. row 9
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_32x11``
+
+ - 32x11
+
+ - .. row 10
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_80x33``
+
+ - 80x33
+
+ - .. row 11
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_18x11``
+
+ - 18x11
+
+ - .. row 12
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_15x11``
+
+ - 15x11
+
+ - .. row 13
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_64x33``
+
+ - 64x33
+
+ - .. row 14
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_160x99``
+
+ - 160x99
+
+ - .. row 15
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_4x3``
+
+ - 4x3
+
+ - .. row 16
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_3x2``
+
+ - 3x2
+
+ - .. row 17
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_2x1``
+
+ - 2x1
+
+ - .. row 18
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_EXTENDED``
+
+ - Extended SAR
+
+
+
+``V4L2_CID_MPEG_VIDEO_H264_VUI_EXT_SAR_WIDTH (integer)``
+ Extended sample aspect ratio width for H.264 VUI encoding.
+ Applicable to the H264 encoder.
+
+``V4L2_CID_MPEG_VIDEO_H264_VUI_EXT_SAR_HEIGHT (integer)``
+ Extended sample aspect ratio height for H.264 VUI encoding.
+ Applicable to the H264 encoder.
+
+.. _v4l2-mpeg-video-h264-level:
+
+``V4L2_CID_MPEG_VIDEO_H264_LEVEL (enum v4l2_mpeg_video_h264_level)``
+ The level information for the H264 video elementary stream.
+ Applicable to the H264 encoder. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_1_0``
+
+ - Level 1.0
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_1B``
+
+ - Level 1B
+
+ - .. row 3
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_1_1``
+
+ - Level 1.1
+
+ - .. row 4
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_1_2``
+
+ - Level 1.2
+
+ - .. row 5
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_1_3``
+
+ - Level 1.3
+
+ - .. row 6
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_2_0``
+
+ - Level 2.0
+
+ - .. row 7
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_2_1``
+
+ - Level 2.1
+
+ - .. row 8
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_2_2``
+
+ - Level 2.2
+
+ - .. row 9
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_3_0``
+
+ - Level 3.0
+
+ - .. row 10
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_3_1``
+
+ - Level 3.1
+
+ - .. row 11
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_3_2``
+
+ - Level 3.2
+
+ - .. row 12
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_4_0``
+
+ - Level 4.0
+
+ - .. row 13
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_4_1``
+
+ - Level 4.1
+
+ - .. row 14
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_4_2``
+
+ - Level 4.2
+
+ - .. row 15
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_5_0``
+
+ - Level 5.0
+
+ - .. row 16
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_5_1``
+
+ - Level 5.1
+
+
+
+.. _v4l2-mpeg-video-mpeg4-level:
+
+``V4L2_CID_MPEG_VIDEO_MPEG4_LEVEL (enum v4l2_mpeg_video_mpeg4_level)``
+ The level information for the MPEG4 elementary stream. Applicable to
+ the MPEG4 encoder. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_LEVEL_0``
+
+ - Level 0
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_LEVEL_0B``
+
+ - Level 0b
+
+ - .. row 3
+
+ - ``V4L2_MPEG_VIDEO_LEVEL_1``
+
+ - Level 1
+
+ - .. row 4
+
+ - ``V4L2_MPEG_VIDEO_LEVEL_2``
+
+ - Level 2
+
+ - .. row 5
+
+ - ``V4L2_MPEG_VIDEO_LEVEL_3``
+
+ - Level 3
+
+ - .. row 6
+
+ - ``V4L2_MPEG_VIDEO_LEVEL_3B``
+
+ - Level 3b
+
+ - .. row 7
+
+ - ``V4L2_MPEG_VIDEO_LEVEL_4``
+
+ - Level 4
+
+ - .. row 8
+
+ - ``V4L2_MPEG_VIDEO_LEVEL_5``
+
+ - Level 5
+
+
+
+.. _v4l2-mpeg-video-h264-profile:
+
+``V4L2_CID_MPEG_VIDEO_H264_PROFILE (enum v4l2_mpeg_video_h264_profile)``
+ The profile information for H264. Applicable to the H264 encoder.
+ Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_BASELINE``
+
+ - Baseline profile
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_CONSTRAINED_BASELINE``
+
+ - Constrained Baseline profile
+
+ - .. row 3
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_MAIN``
+
+ - Main profile
+
+ - .. row 4
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_EXTENDED``
+
+ - Extended profile
+
+ - .. row 5
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH``
+
+ - High profile
+
+ - .. row 6
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_10``
+
+ - High 10 profile
+
+ - .. row 7
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_422``
+
+ - High 422 profile
+
+ - .. row 8
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_444_PREDICTIVE``
+
+ - High 444 Predictive profile
+
+ - .. row 9
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_10_INTRA``
+
+ - High 10 Intra profile
+
+ - .. row 10
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_422_INTRA``
+
+ - High 422 Intra profile
+
+ - .. row 11
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_444_INTRA``
+
+ - High 444 Intra profile
+
+ - .. row 12
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_CAVLC_444_INTRA``
+
+ - CAVLC 444 Intra profile
+
+ - .. row 13
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_SCALABLE_BASELINE``
+
+ - Scalable Baseline profile
+
+ - .. row 14
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_SCALABLE_HIGH``
+
+ - Scalable High profile
+
+ - .. row 15
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_SCALABLE_HIGH_INTRA``
+
+ - Scalable High Intra profile
+
+ - .. row 16
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_STEREO_HIGH``
+
+ - Stereo High profile
+
+ - .. row 17
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_MULTIVIEW_HIGH``
+
+ - Multiview High profile
+
+
+
+.. _v4l2-mpeg-video-mpeg4-profile:
+
+``V4L2_CID_MPEG_VIDEO_MPEG4_PROFILE (enum v4l2_mpeg_video_mpeg4_profile)``
+ The profile information for MPEG4. Applicable to the MPEG4 encoder.
+ Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_PROFILE_SIMPLE``
+
+ - Simple profile
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_PROFILE_ADVANCED_SIMPLE``
+
+ - Advanced Simple profile
+
+ - .. row 3
+
+ - ``V4L2_MPEG_VIDEO_PROFILE_CORE``
+
+ - Core profile
+
+ - .. row 4
+
+ - ``V4L2_MPEG_VIDEO_PROFILE_SIMPLE_SCALABLE``
+
+ - Simple Scalable profile
+
+ - .. row 5
+
+ - ``V4L2_MPEG_VIDEO_PROFILE_ADVANCED_CODING_EFFICIENCY``
+
+ -
+
+
+
+``V4L2_CID_MPEG_VIDEO_MAX_REF_PIC (integer)``
+ The maximum number of reference pictures used for encoding.
+ Applicable to the encoder.
+
+.. _v4l2-mpeg-video-multi-slice-mode:
+
+``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE (enum v4l2_mpeg_video_multi_slice_mode)``
+ Determines how the encoder should handle division of frame into
+ slices. Applicable to the encoder. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_SINGLE``
+
+ - Single slice per frame.
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_MB``
+
+ - Multiple slices with set maximum number of macroblocks per slice.
+
+ - .. row 3
+
+ - ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_BYTES``
+
+ - Multiple slice with set maximum size in bytes per slice.
+
+
+
+``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MAX_MB (integer)``
+ The maximum number of macroblocks in a slice. Used when
+ ``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE`` is set to
+ ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_MB``. Applicable to the
+ encoder.
+
+``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MAX_BYTES (integer)``
+ The maximum size of a slice in bytes. Used when
+ ``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE`` is set to
+ ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_BYTES``. Applicable to the
+ encoder.
+
+.. _v4l2-mpeg-video-h264-loop-filter-mode:
+
+``V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_MODE (enum v4l2_mpeg_video_h264_loop_filter_mode)``
+ Loop filter mode for H264 encoder. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_H264_LOOP_FILTER_MODE_ENABLED``
+
+ - Loop filter is enabled.
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_H264_LOOP_FILTER_MODE_DISABLED``
+
+ - Loop filter is disabled.
+
+ - .. row 3
+
+ - ``V4L2_MPEG_VIDEO_H264_LOOP_FILTER_MODE_DISABLED_AT_SLICE_BOUNDARY``
+
+ - Loop filter is disabled at the slice boundary.
+
+
+
+``V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_ALPHA (integer)``
+ Loop filter alpha coefficient, defined in the H264 standard.
+ Applicable to the H264 encoder.
+
+``V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_BETA (integer)``
+ Loop filter beta coefficient, defined in the H264 standard.
+ Applicable to the H264 encoder.
+
+.. _v4l2-mpeg-video-h264-entropy-mode:
+
+``V4L2_CID_MPEG_VIDEO_H264_ENTROPY_MODE (enum v4l2_mpeg_video_h264_entropy_mode)``
+ Entropy coding mode for H264 - CABAC/CAVALC. Applicable to the H264
+ encoder. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_H264_ENTROPY_MODE_CAVLC``
+
+ - Use CAVLC entropy coding.
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_H264_ENTROPY_MODE_CABAC``
+
+ - Use CABAC entropy coding.
+
+
+
+``V4L2_CID_MPEG_VIDEO_H264_8X8_TRANSFORM (boolean)``
+ Enable 8X8 transform for H264. Applicable to the H264 encoder.
+
+``V4L2_CID_MPEG_VIDEO_CYCLIC_INTRA_REFRESH_MB (integer)``
+ Cyclic intra macroblock refresh. This is the number of continuous
+ macroblocks refreshed every frame. Each frame a successive set of
+ macroblocks is refreshed until the cycle completes and starts from
+ the top of the frame. Applicable to H264, H263 and MPEG4 encoder.
+
+``V4L2_CID_MPEG_VIDEO_FRAME_RC_ENABLE (boolean)``
+ Frame level rate control enable. If this control is disabled then
+ the quantization parameter for each frame type is constant and set
+ with appropriate controls (e.g.
+ ``V4L2_CID_MPEG_VIDEO_H263_I_FRAME_QP``). If frame rate control is
+ enabled then quantization parameter is adjusted to meet the chosen
+ bitrate. Minimum and maximum value for the quantization parameter
+ can be set with appropriate controls (e.g.
+ ``V4L2_CID_MPEG_VIDEO_H263_MIN_QP``). Applicable to encoders.
+
+``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE (boolean)``
+ Macroblock level rate control enable. Applicable to the MPEG4 and
+ H264 encoders.
+
+``V4L2_CID_MPEG_VIDEO_MPEG4_QPEL (boolean)``
+ Quarter pixel motion estimation for MPEG4. Applicable to the MPEG4
+ encoder.
+
+``V4L2_CID_MPEG_VIDEO_H263_I_FRAME_QP (integer)``
+ Quantization parameter for an I frame for H263. Valid range: from 1
+ to 31.
+
+``V4L2_CID_MPEG_VIDEO_H263_MIN_QP (integer)``
+ Minimum quantization parameter for H263. Valid range: from 1 to 31.
+
+``V4L2_CID_MPEG_VIDEO_H263_MAX_QP (integer)``
+ Maximum quantization parameter for H263. Valid range: from 1 to 31.
+
+``V4L2_CID_MPEG_VIDEO_H263_P_FRAME_QP (integer)``
+ Quantization parameter for an P frame for H263. Valid range: from 1
+ to 31.
+
+``V4L2_CID_MPEG_VIDEO_H263_B_FRAME_QP (integer)``
+ Quantization parameter for an B frame for H263. Valid range: from 1
+ to 31.
+
+``V4L2_CID_MPEG_VIDEO_H264_I_FRAME_QP (integer)``
+ Quantization parameter for an I frame for H264. Valid range: from 0
+ to 51.
+
+``V4L2_CID_MPEG_VIDEO_H264_MIN_QP (integer)``
+ Minimum quantization parameter for H264. Valid range: from 0 to 51.
+
+``V4L2_CID_MPEG_VIDEO_H264_MAX_QP (integer)``
+ Maximum quantization parameter for H264. Valid range: from 0 to 51.
+
+``V4L2_CID_MPEG_VIDEO_H264_P_FRAME_QP (integer)``
+ Quantization parameter for an P frame for H264. Valid range: from 0
+ to 51.
+
+``V4L2_CID_MPEG_VIDEO_H264_B_FRAME_QP (integer)``
+ Quantization parameter for an B frame for H264. Valid range: from 0
+ to 51.
+
+``V4L2_CID_MPEG_VIDEO_MPEG4_I_FRAME_QP (integer)``
+ Quantization parameter for an I frame for MPEG4. Valid range: from 1
+ to 31.
+
+``V4L2_CID_MPEG_VIDEO_MPEG4_MIN_QP (integer)``
+ Minimum quantization parameter for MPEG4. Valid range: from 1 to 31.
+
+``V4L2_CID_MPEG_VIDEO_MPEG4_MAX_QP (integer)``
+ Maximum quantization parameter for MPEG4. Valid range: from 1 to 31.
+
+``V4L2_CID_MPEG_VIDEO_MPEG4_P_FRAME_QP (integer)``
+ Quantization parameter for an P frame for MPEG4. Valid range: from 1
+ to 31.
+
+``V4L2_CID_MPEG_VIDEO_MPEG4_B_FRAME_QP (integer)``
+ Quantization parameter for an B frame for MPEG4. Valid range: from 1
+ to 31.
+
+``V4L2_CID_MPEG_VIDEO_VBV_SIZE (integer)``
+ The Video Buffer Verifier size in kilobytes, it is used as a
+ limitation of frame skip. The VBV is defined in the standard as a
+ mean to verify that the produced stream will be successfully
+ decoded. The standard describes it as "Part of a hypothetical
+ decoder that is conceptually connected to the output of the encoder.
+ Its purpose is to provide a constraint on the variability of the
+ data rate that an encoder or editing process may produce.".
+ Applicable to the MPEG1, MPEG2, MPEG4 encoders.
+
+.. _v4l2-mpeg-video-vbv-delay:
+
+``V4L2_CID_MPEG_VIDEO_VBV_DELAY (integer)``
+ Sets the initial delay in milliseconds for VBV buffer control.
+
+.. _v4l2-mpeg-video-hor-search-range:
+
+``V4L2_CID_MPEG_VIDEO_MV_H_SEARCH_RANGE (integer)``
+ Horizontal search range defines maximum horizontal search area in
+ pixels to search and match for the present Macroblock (MB) in the
+ reference picture. This V4L2 control macro is used to set horizontal
+ search range for motion estimation module in video encoder.
+
+.. _v4l2-mpeg-video-vert-search-range:
+
+``V4L2_CID_MPEG_VIDEO_MV_V_SEARCH_RANGE (integer)``
+ Vertical search range defines maximum vertical search area in pixels
+ to search and match for the present Macroblock (MB) in the reference
+ picture. This V4L2 control macro is used to set vertical search
+ range for motion estimation module in video encoder.
+
+.. _v4l2-mpeg-video-force-key-frame:
+
+``V4L2_CID_MPEG_VIDEO_FORCE_KEY_FRAME (button)``
+ Force a key frame for the next queued buffer. Applicable to
+ encoders. This is a general, codec-agnostic keyframe control.
+
+``V4L2_CID_MPEG_VIDEO_H264_CPB_SIZE (integer)``
+ The Coded Picture Buffer size in kilobytes, it is used as a
+ limitation of frame skip. The CPB is defined in the H264 standard as
+ a mean to verify that the produced stream will be successfully
+ decoded. Applicable to the H264 encoder.
+
+``V4L2_CID_MPEG_VIDEO_H264_I_PERIOD (integer)``
+ Period between I-frames in the open GOP for H264. In case of an open
+ GOP this is the period between two I-frames. The period between IDR
+ (Instantaneous Decoding Refresh) frames is taken from the GOP_SIZE
+ control. An IDR frame, which stands for Instantaneous Decoding
+ Refresh is an I-frame after which no prior frames are referenced.
+ This means that a stream can be restarted from an IDR frame without
+ the need to store or decode any previous frames. Applicable to the
+ H264 encoder.
+
+.. _v4l2-mpeg-video-header-mode:
+
+``V4L2_CID_MPEG_VIDEO_HEADER_MODE (enum v4l2_mpeg_video_header_mode)``
+ Determines whether the header is returned as the first buffer or is
+ it returned together with the first frame. Applicable to encoders.
+ Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_HEADER_MODE_SEPARATE``
+
+ - The stream header is returned separately in the first buffer.
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_HEADER_MODE_JOINED_WITH_1ST_FRAME``
+
+ - The stream header is returned together with the first encoded
+ frame.
+
+
+
+``V4L2_CID_MPEG_VIDEO_REPEAT_SEQ_HEADER (boolean)``
+ Repeat the video sequence headers. Repeating these headers makes
+ random access to the video stream easier. Applicable to the MPEG1, 2
+ and 4 encoder.
+
+``V4L2_CID_MPEG_VIDEO_DECODER_MPEG4_DEBLOCK_FILTER (boolean)``
+ Enabled the deblocking post processing filter for MPEG4 decoder.
+ Applicable to the MPEG4 decoder.
+
+``V4L2_CID_MPEG_VIDEO_MPEG4_VOP_TIME_RES (integer)``
+ vop_time_increment_resolution value for MPEG4. Applicable to the
+ MPEG4 encoder.
+
+``V4L2_CID_MPEG_VIDEO_MPEG4_VOP_TIME_INC (integer)``
+ vop_time_increment value for MPEG4. Applicable to the MPEG4
+ encoder.
+
+``V4L2_CID_MPEG_VIDEO_H264_SEI_FRAME_PACKING (boolean)``
+ Enable generation of frame packing supplemental enhancement
+ information in the encoded bitstream. The frame packing SEI message
+ contains the arrangement of L and R planes for 3D viewing.
+ Applicable to the H264 encoder.
+
+``V4L2_CID_MPEG_VIDEO_H264_SEI_FP_CURRENT_FRAME_0 (boolean)``
+ Sets current frame as frame0 in frame packing SEI. Applicable to the
+ H264 encoder.
+
+.. _v4l2-mpeg-video-h264-sei-fp-arrangement-type:
+
+``V4L2_CID_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE (enum v4l2_mpeg_video_h264_sei_fp_arrangement_type)``
+ Frame packing arrangement type for H264 SEI. Applicable to the H264
+ encoder. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_CHEKERBOARD``
+
+ - Pixels are alternatively from L and R.
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_COLUMN``
+
+ - L and R are interlaced by column.
+
+ - .. row 3
+
+ - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_ROW``
+
+ - L and R are interlaced by row.
+
+ - .. row 4
+
+ - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_SIDE_BY_SIDE``
+
+ - L is on the left, R on the right.
+
+ - .. row 5
+
+ - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_TOP_BOTTOM``
+
+ - L is on top, R on bottom.
+
+ - .. row 6
+
+ - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_TEMPORAL``
+
+ - One view per frame.
+
+
+
+``V4L2_CID_MPEG_VIDEO_H264_FMO (boolean)``
+ Enables flexible macroblock ordering in the encoded bitstream. It is
+ a technique used for restructuring the ordering of macroblocks in
+ pictures. Applicable to the H264 encoder.
+
+.. _v4l2-mpeg-video-h264-fmo-map-type:
+
+``V4L2_CID_MPEG_VIDEO_H264_FMO_MAP_TYPE (enum v4l2_mpeg_video_h264_fmo_map_type)``
+ When using FMO, the map type divides the image in different scan
+ patterns of macroblocks. Applicable to the H264 encoder. Possible
+ values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_INTERLEAVED_SLICES``
+
+ - Slices are interleaved one after other with macroblocks in run
+ length order.
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_SCATTERED_SLICES``
+
+ - Scatters the macroblocks based on a mathematical function known to
+ both encoder and decoder.
+
+ - .. row 3
+
+ - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_FOREGROUND_WITH_LEFT_OVER``
+
+ - Macroblocks arranged in rectangular areas or regions of interest.
+
+ - .. row 4
+
+ - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_BOX_OUT``
+
+ - Slice groups grow in a cyclic way from centre to outwards.
+
+ - .. row 5
+
+ - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_RASTER_SCAN``
+
+ - Slice groups grow in raster scan pattern from left to right.
+
+ - .. row 6
+
+ - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_WIPE_SCAN``
+
+ - Slice groups grow in wipe scan pattern from top to bottom.
+
+ - .. row 7
+
+ - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_EXPLICIT``
+
+ - User defined map type.
+
+
+
+``V4L2_CID_MPEG_VIDEO_H264_FMO_SLICE_GROUP (integer)``
+ Number of slice groups in FMO. Applicable to the H264 encoder.
+
+.. _v4l2-mpeg-video-h264-fmo-change-direction:
+
+``V4L2_CID_MPEG_VIDEO_H264_FMO_CHANGE_DIRECTION (enum v4l2_mpeg_video_h264_fmo_change_dir)``
+ Specifies a direction of the slice group change for raster and wipe
+ maps. Applicable to the H264 encoder. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_H264_FMO_CHANGE_DIR_RIGHT``
+
+ - Raster scan or wipe right.
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_H264_FMO_CHANGE_DIR_LEFT``
+
+ - Reverse raster scan or wipe left.
+
+
+
+``V4L2_CID_MPEG_VIDEO_H264_FMO_CHANGE_RATE (integer)``
+ Specifies the size of the first slice group for raster and wipe map.
+ Applicable to the H264 encoder.
+
+``V4L2_CID_MPEG_VIDEO_H264_FMO_RUN_LENGTH (integer)``
+ Specifies the number of consecutive macroblocks for the interleaved
+ map. Applicable to the H264 encoder.
+
+``V4L2_CID_MPEG_VIDEO_H264_ASO (boolean)``
+ Enables arbitrary slice ordering in encoded bitstream. Applicable to
+ the H264 encoder.
+
+``V4L2_CID_MPEG_VIDEO_H264_ASO_SLICE_ORDER (integer)``
+ Specifies the slice order in ASO. Applicable to the H264 encoder.
+ The supplied 32-bit integer is interpreted as follows (bit 0 = least
+ significant bit):
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Bit 0:15
+
+ - Slice ID
+
+ - .. row 2
+
+ - Bit 16:32
+
+ - Slice position or order
+
+
+
+``V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING (boolean)``
+ Enables H264 hierarchical coding. Applicable to the H264 encoder.
+
+.. _v4l2-mpeg-video-h264-hierarchical-coding-type:
+
+``V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING_TYPE (enum v4l2_mpeg_video_h264_hierarchical_coding_type)``
+ Specifies the hierarchical coding type. Applicable to the H264
+ encoder. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_H264_HIERARCHICAL_CODING_B``
+
+ - Hierarchical B coding.
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_H264_HIERARCHICAL_CODING_P``
+
+ - Hierarchical P coding.
+
+
+
+``V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING_LAYER (integer)``
+ Specifies the number of hierarchical coding layers. Applicable to
+ the H264 encoder.
+
+``V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING_LAYER_QP (integer)``
+ Specifies a user defined QP for each layer. Applicable to the H264
+ encoder. The supplied 32-bit integer is interpreted as follows (bit
+ 0 = least significant bit):
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Bit 0:15
+
+ - QP value
+
+ - .. row 2
+
+ - Bit 16:32
+
+ - Layer number
+
+
+
+
+MFC 5.1 MPEG Controls
+---------------------
+
+The following MPEG class controls deal with MPEG decoding and encoding
+settings that are specific to the Multi Format Codec 5.1 device present
+in the S5P family of SoCs by Samsung.
+
+
+.. _mfc51-control-id:
+
+MFC 5.1 Control IDs
+^^^^^^^^^^^^^^^^^^^
+
+``V4L2_CID_MPEG_MFC51_VIDEO_DECODER_H264_DISPLAY_DELAY_ENABLE (boolean)``
+ If the display delay is enabled then the decoder is forced to return
+ a CAPTURE buffer (decoded frame) after processing a certain number
+ of OUTPUT buffers. The delay can be set through
+ ``V4L2_CID_MPEG_MFC51_VIDEO_DECODER_H264_DISPLAY_DELAY``. This
+ feature can be used for example for generating thumbnails of videos.
+ Applicable to the H264 decoder.
+
+``V4L2_CID_MPEG_MFC51_VIDEO_DECODER_H264_DISPLAY_DELAY (integer)``
+ Display delay value for H264 decoder. The decoder is forced to
+ return a decoded frame after the set 'display delay' number of
+ frames. If this number is low it may result in frames returned out
+ of dispaly order, in addition the hardware may still be using the
+ returned buffer as a reference picture for subsequent frames.
+
+``V4L2_CID_MPEG_MFC51_VIDEO_H264_NUM_REF_PIC_FOR_P (integer)``
+ The number of reference pictures used for encoding a P picture.
+ Applicable to the H264 encoder.
+
+``V4L2_CID_MPEG_MFC51_VIDEO_PADDING (boolean)``
+ Padding enable in the encoder - use a color instead of repeating
+ border pixels. Applicable to encoders.
+
+``V4L2_CID_MPEG_MFC51_VIDEO_PADDING_YUV (integer)``
+ Padding color in the encoder. Applicable to encoders. The supplied
+ 32-bit integer is interpreted as follows (bit 0 = least significant
+ bit):
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Bit 0:7
+
+ - V chrominance information
+
+ - .. row 2
+
+ - Bit 8:15
+
+ - U chrominance information
+
+ - .. row 3
+
+ - Bit 16:23
+
+ - Y luminance information
+
+ - .. row 4
+
+ - Bit 24:31
+
+ - Must be zero.
+
+
+
+``V4L2_CID_MPEG_MFC51_VIDEO_RC_REACTION_COEFF (integer)``
+ Reaction coefficient for MFC rate control. Applicable to encoders.
+
+ Note 1: Valid only when the frame level RC is enabled.
+
+ Note 2: For tight CBR, this field must be small (ex. 2 ~ 10). For
+ VBR, this field must be large (ex. 100 ~ 1000).
+
+ Note 3: It is not recommended to use the greater number than
+ FRAME_RATE * (10^9 / BIT_RATE).
+
+``V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_DARK (boolean)``
+ Adaptive rate control for dark region. Valid only when H.264 and
+ macroblock level RC is enabled
+ (``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE``). Applicable to the H264
+ encoder.
+
+``V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_SMOOTH (boolean)``
+ Adaptive rate control for smooth region. Valid only when H.264 and
+ macroblock level RC is enabled
+ (``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE``). Applicable to the H264
+ encoder.
+
+``V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_STATIC (boolean)``
+ Adaptive rate control for static region. Valid only when H.264 and
+ macroblock level RC is enabled
+ (``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE``). Applicable to the H264
+ encoder.
+
+``V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_ACTIVITY (boolean)``
+ Adaptive rate control for activity region. Valid only when H.264 and
+ macroblock level RC is enabled
+ (``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE``). Applicable to the H264
+ encoder.
+
+.. _v4l2-mpeg-mfc51-video-frame-skip-mode:
+
+``V4L2_CID_MPEG_MFC51_VIDEO_FRAME_SKIP_MODE (enum v4l2_mpeg_mfc51_video_frame_skip_mode)``
+ Indicates in what conditions the encoder should skip frames. If
+ encoding a frame would cause the encoded stream to be larger then a
+ chosen data limit then the frame will be skipped. Possible values
+ are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_MFC51_FRAME_SKIP_MODE_DISABLED``
+
+ - Frame skip mode is disabled.
+
+ - .. row 2
+
+ - ``V4L2_MPEG_MFC51_FRAME_SKIP_MODE_LEVEL_LIMIT``
+
+ - Frame skip mode enabled and buffer limit is set by the chosen
+ level and is defined by the standard.
+
+ - .. row 3
+
+ - ``V4L2_MPEG_MFC51_FRAME_SKIP_MODE_BUF_LIMIT``
+
+ - Frame skip mode enabled and buffer limit is set by the VBV
+ (MPEG1/2/4) or CPB (H264) buffer size control.
+
+
+
+``V4L2_CID_MPEG_MFC51_VIDEO_RC_FIXED_TARGET_BIT (integer)``
+ Enable rate-control with fixed target bit. If this setting is
+ enabled, then the rate control logic of the encoder will calculate
+ the average bitrate for a GOP and keep it below or equal the set
+ bitrate target. Otherwise the rate control logic calculates the
+ overall average bitrate for the stream and keeps it below or equal
+ to the set bitrate. In the first case the average bitrate for the
+ whole stream will be smaller then the set bitrate. This is caused
+ because the average is calculated for smaller number of frames, on
+ the other hand enabling this setting will ensure that the stream
+ will meet tight bandwidth constraints. Applicable to encoders.
+
+.. _v4l2-mpeg-mfc51-video-force-frame-type:
+
+``V4L2_CID_MPEG_MFC51_VIDEO_FORCE_FRAME_TYPE (enum v4l2_mpeg_mfc51_video_force_frame_type)``
+ Force a frame type for the next queued buffer. Applicable to
+ encoders. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_DISABLED``
+
+ - Forcing a specific frame type disabled.
+
+ - .. row 2
+
+ - ``V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_I_FRAME``
+
+ - Force an I-frame.
+
+ - .. row 3
+
+ - ``V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_NOT_CODED``
+
+ - Force a non-coded frame.
+
+
+
+
+CX2341x MPEG Controls
+---------------------
+
+The following MPEG class controls deal with MPEG encoding settings that
+are specific to the Conexant CX23415 and CX23416 MPEG encoding chips.
+
+
+.. _cx2341x-control-id:
+
+CX2341x Control IDs
+^^^^^^^^^^^^^^^^^^^
+
+.. _v4l2-mpeg-cx2341x-video-spatial-filter-mode:
+
+``V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE (enum v4l2_mpeg_cx2341x_video_spatial_filter_mode)``
+ Sets the Spatial Filter mode (default ``MANUAL``). Possible values
+ are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_MANUAL``
+
+ - Choose the filter manually
+
+ - .. row 2
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_AUTO``
+
+ - Choose the filter automatically
+
+
+
+``V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER (integer (0-15))``
+ The setting for the Spatial Filter. 0 = off, 15 = maximum. (Default
+ is 0.)
+
+.. _luma-spatial-filter-type:
+
+``V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE (enum v4l2_mpeg_cx2341x_video_luma_spatial_filter_type)``
+ Select the algorithm to use for the Luma Spatial Filter (default
+ ``1D_HOR``). Possible values:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_OFF``
+
+ - No filter
+
+ - .. row 2
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_HOR``
+
+ - One-dimensional horizontal
+
+ - .. row 3
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_VERT``
+
+ - One-dimensional vertical
+
+ - .. row 4
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_HV_SEPARABLE``
+
+ - Two-dimensional separable
+
+ - .. row 5
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_SYM_NON_SEPARABLE``
+
+ - Two-dimensional symmetrical non-separable
+
+
+
+.. _chroma-spatial-filter-type:
+
+``V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE (enum v4l2_mpeg_cx2341x_video_chroma_spatial_filter_type)``
+ Select the algorithm for the Chroma Spatial Filter (default
+ ``1D_HOR``). Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_OFF``
+
+ - No filter
+
+ - .. row 2
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_1D_HOR``
+
+ - One-dimensional horizontal
+
+
+
+.. _v4l2-mpeg-cx2341x-video-temporal-filter-mode:
+
+``V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE (enum v4l2_mpeg_cx2341x_video_temporal_filter_mode)``
+ Sets the Temporal Filter mode (default ``MANUAL``). Possible values
+ are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_MANUAL``
+
+ - Choose the filter manually
+
+ - .. row 2
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_AUTO``
+
+ - Choose the filter automatically
+
+
+
+``V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER (integer (0-31))``
+ The setting for the Temporal Filter. 0 = off, 31 = maximum. (Default
+ is 8 for full-scale capturing and 0 for scaled capturing.)
+
+.. _v4l2-mpeg-cx2341x-video-median-filter-type:
+
+``V4L2_CID_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE (enum v4l2_mpeg_cx2341x_video_median_filter_type)``
+ Median Filter Type (default ``OFF``). Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_OFF``
+
+ - No filter
+
+ - .. row 2
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR``
+
+ - Horizontal filter
+
+ - .. row 3
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_VERT``
+
+ - Vertical filter
+
+ - .. row 4
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR_VERT``
+
+ - Horizontal and vertical filter
+
+ - .. row 5
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_DIAG``
+
+ - Diagonal filter
+
+
+
+``V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_BOTTOM (integer (0-255))``
+ Threshold above which the luminance median filter is enabled
+ (default 0)
+
+``V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_TOP (integer (0-255))``
+ Threshold below which the luminance median filter is enabled
+ (default 255)
+
+``V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_BOTTOM (integer (0-255))``
+ Threshold above which the chroma median filter is enabled (default
+ 0)
+
+``V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_TOP (integer (0-255))``
+ Threshold below which the chroma median filter is enabled (default
+ 255)
+
+``V4L2_CID_MPEG_CX2341X_STREAM_INSERT_NAV_PACKETS (boolean)``
+ The CX2341X MPEG encoder can insert one empty MPEG-2 PES packet into
+ the stream between every four video frames. The packet size is 2048
+ bytes, including the packet_start_code_prefix and stream_id
+ fields. The stream_id is 0xBF (private stream 2). The payload
+ consists of 0x00 bytes, to be filled in by the application. 0 = do
+ not insert, 1 = insert packets.
+
+
+VPX Control Reference
+---------------------
+
+The VPX controls include controls for encoding parameters of VPx video
+codec.
+
+
+.. _vpx-control-id:
+
+VPX Control IDs
+^^^^^^^^^^^^^^^
+
+.. _v4l2-vpx-num-partitions:
+
+``V4L2_CID_MPEG_VIDEO_VPX_NUM_PARTITIONS (enum v4l2_vp8_num_partitions)``
+ The number of token partitions to use in VP8 encoder. Possible
+ values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_CID_MPEG_VIDEO_VPX_1_PARTITION``
+
+ - 1 coefficient partition
+
+ - .. row 2
+
+ - ``V4L2_CID_MPEG_VIDEO_VPX_2_PARTITIONS``
+
+ - 2 coefficient partitions
+
+ - .. row 3
+
+ - ``V4L2_CID_MPEG_VIDEO_VPX_4_PARTITIONS``
+
+ - 4 coefficient partitions
+
+ - .. row 4
+
+ - ``V4L2_CID_MPEG_VIDEO_VPX_8_PARTITIONS``
+
+ - 8 coefficient partitions
+
+
+
+``V4L2_CID_MPEG_VIDEO_VPX_IMD_DISABLE_4X4 (boolean)``
+ Setting this prevents intra 4x4 mode in the intra mode decision.
+
+.. _v4l2-vpx-num-ref-frames:
+
+``V4L2_CID_MPEG_VIDEO_VPX_NUM_REF_FRAMES (enum v4l2_vp8_num_ref_frames)``
+ The number of reference pictures for encoding P frames. Possible
+ values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_CID_MPEG_VIDEO_VPX_1_REF_FRAME``
+
+ - Last encoded frame will be searched
+
+ - .. row 2
+
+ - ``V4L2_CID_MPEG_VIDEO_VPX_2_REF_FRAME``
+
+ - Two frames will be searched among the last encoded frame, the
+ golden frame and the alternate reference (altref) frame. The
+ encoder implementation will decide which two are chosen.
+
+ - .. row 3
+
+ - ``V4L2_CID_MPEG_VIDEO_VPX_3_REF_FRAME``
+
+ - The last encoded frame, the golden frame and the altref frame will
+ be searched.
+
+
+
+``V4L2_CID_MPEG_VIDEO_VPX_FILTER_LEVEL (integer)``
+ Indicates the loop filter level. The adjustment of the loop filter
+ level is done via a delta value against a baseline loop filter
+ value.
+
+``V4L2_CID_MPEG_VIDEO_VPX_FILTER_SHARPNESS (integer)``
+ This parameter affects the loop filter. Anything above zero weakens
+ the deblocking effect on the loop filter.
+
+``V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_REF_PERIOD (integer)``
+ Sets the refresh period for the golden frame. The period is defined
+ in number of frames. For a value of 'n', every nth frame starting
+ from the first key frame will be taken as a golden frame. For eg.
+ for encoding sequence of 0, 1, 2, 3, 4, 5, 6, 7 where the golden
+ frame refresh period is set as 4, the frames 0, 4, 8 etc will be
+ taken as the golden frames as frame 0 is always a key frame.
+
+.. _v4l2-vpx-golden-frame-sel:
+
+``V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_SEL (enum v4l2_vp8_golden_frame_sel)``
+ Selects the golden frame for encoding. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_USE_PREV``
+
+ - Use the (n-2)th frame as a golden frame, current frame index being
+ 'n'.
+
+ - .. row 2
+
+ - ``V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_USE_REF_PERIOD``
+
+ - Use the previous specific frame indicated by
+ V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_REF_PERIOD as a
+ golden frame.
+
+
+
+``V4L2_CID_MPEG_VIDEO_VPX_MIN_QP (integer)``
+ Minimum quantization parameter for VP8.
+
+``V4L2_CID_MPEG_VIDEO_VPX_MAX_QP (integer)``
+ Maximum quantization parameter for VP8.
+
+``V4L2_CID_MPEG_VIDEO_VPX_I_FRAME_QP (integer)``
+ Quantization parameter for an I frame for VP8.
+
+``V4L2_CID_MPEG_VIDEO_VPX_P_FRAME_QP (integer)``
+ Quantization parameter for a P frame for VP8.
+
+``V4L2_CID_MPEG_VIDEO_VPX_PROFILE (integer)``
+ Select the desired profile for VPx encoder. Acceptable values are 0,
+ 1, 2 and 3 corresponding to encoder profiles 0, 1, 2 and 3.
+
+
+.. _camera-controls:
+
+Camera Control Reference
+========================
+
+The Camera class includes controls for mechanical (or equivalent
+digital) features of a device such as controllable lenses or sensors.
+
+
+.. _camera-control-id:
+
+Camera Control IDs
+------------------
+
+``V4L2_CID_CAMERA_CLASS (class)``
+ The Camera class descriptor. Calling
+ :ref:`VIDIOC_QUERYCTRL` for this control will
+ return a description of this control class.
+
+.. _v4l2-exposure-auto-type:
+
+``V4L2_CID_EXPOSURE_AUTO (enum v4l2_exposure_auto_type)``
+ Enables automatic adjustments of the exposure time and/or iris
+ aperture. The effect of manual changes of the exposure time or iris
+ aperture while these features are enabled is undefined, drivers
+ should ignore such requests. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_EXPOSURE_AUTO``
+
+ - Automatic exposure time, automatic iris aperture.
+
+ - .. row 2
+
+ - ``V4L2_EXPOSURE_MANUAL``
+
+ - Manual exposure time, manual iris.
+
+ - .. row 3
+
+ - ``V4L2_EXPOSURE_SHUTTER_PRIORITY``
+
+ - Manual exposure time, auto iris.
+
+ - .. row 4
+
+ - ``V4L2_EXPOSURE_APERTURE_PRIORITY``
+
+ - Auto exposure time, manual iris.
+
+
+
+``V4L2_CID_EXPOSURE_ABSOLUTE (integer)``
+ Determines the exposure time of the camera sensor. The exposure time
+ is limited by the frame interval. Drivers should interpret the
+ values as 100 µs units, where the value 1 stands for 1/10000th of a
+ second, 10000 for 1 second and 100000 for 10 seconds.
+
+``V4L2_CID_EXPOSURE_AUTO_PRIORITY (boolean)``
+ When ``V4L2_CID_EXPOSURE_AUTO`` is set to ``AUTO`` or
+ ``APERTURE_PRIORITY``, this control determines if the device may
+ dynamically vary the frame rate. By default this feature is disabled
+ (0) and the frame rate must remain constant.
+
+``V4L2_CID_EXPOSURE_BIAS (integer menu)``
+ Determines the automatic exposure compensation, it is effective only
+ when ``V4L2_CID_EXPOSURE_AUTO`` control is set to ``AUTO``,
+ ``SHUTTER_PRIORITY`` or ``APERTURE_PRIORITY``. It is expressed in
+ terms of EV, drivers should interpret the values as 0.001 EV units,
+ where the value 1000 stands for +1 EV.
+
+ Increasing the exposure compensation value is equivalent to
+ decreasing the exposure value (EV) and will increase the amount of
+ light at the image sensor. The camera performs the exposure
+ compensation by adjusting absolute exposure time and/or aperture.
+
+.. _v4l2-exposure-metering:
+
+``V4L2_CID_EXPOSURE_METERING (enum v4l2_exposure_metering)``
+ Determines how the camera measures the amount of light available for
+ the frame exposure. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_EXPOSURE_METERING_AVERAGE``
+
+ - Use the light information coming from the entire frame and average
+ giving no weighting to any particular portion of the metered area.
+
+ - .. row 2
+
+ - ``V4L2_EXPOSURE_METERING_CENTER_WEIGHTED``
+
+ - Average the light information coming from the entire frame giving
+ priority to the center of the metered area.
+
+ - .. row 3
+
+ - ``V4L2_EXPOSURE_METERING_SPOT``
+
+ - Measure only very small area at the center of the frame.
+
+ - .. row 4
+
+ - ``V4L2_EXPOSURE_METERING_MATRIX``
+
+ - A multi-zone metering. The light intensity is measured in several
+ points of the frame and the results are combined. The algorithm of
+ the zones selection and their significance in calculating the
+ final value is device dependent.
+
+
+
+``V4L2_CID_PAN_RELATIVE (integer)``
+ This control turns the camera horizontally by the specified amount.
+ The unit is undefined. A positive value moves the camera to the
+ right (clockwise when viewed from above), a negative value to the
+ left. A value of zero does not cause motion. This is a write-only
+ control.
+
+``V4L2_CID_TILT_RELATIVE (integer)``
+ This control turns the camera vertically by the specified amount.
+ The unit is undefined. A positive value moves the camera up, a
+ negative value down. A value of zero does not cause motion. This is
+ a write-only control.
+
+``V4L2_CID_PAN_RESET (button)``
+ When this control is set, the camera moves horizontally to the
+ default position.
+
+``V4L2_CID_TILT_RESET (button)``
+ When this control is set, the camera moves vertically to the default
+ position.
+
+``V4L2_CID_PAN_ABSOLUTE (integer)``
+ This control turns the camera horizontally to the specified
+ position. Positive values move the camera to the right (clockwise
+ when viewed from above), negative values to the left. Drivers should
+ interpret the values as arc seconds, with valid values between -180
+ * 3600 and +180 * 3600 inclusive.
+
+``V4L2_CID_TILT_ABSOLUTE (integer)``
+ This control turns the camera vertically to the specified position.
+ Positive values move the camera up, negative values down. Drivers
+ should interpret the values as arc seconds, with valid values
+ between -180 * 3600 and +180 * 3600 inclusive.
+
+``V4L2_CID_FOCUS_ABSOLUTE (integer)``
+ This control sets the focal point of the camera to the specified
+ position. The unit is undefined. Positive values set the focus
+ closer to the camera, negative values towards infinity.
+
+``V4L2_CID_FOCUS_RELATIVE (integer)``
+ This control moves the focal point of the camera by the specified
+ amount. The unit is undefined. Positive values move the focus closer
+ to the camera, negative values towards infinity. This is a
+ write-only control.
+
+``V4L2_CID_FOCUS_AUTO (boolean)``
+ Enables continuous automatic focus adjustments. The effect of manual
+ focus adjustments while this feature is enabled is undefined,
+ drivers should ignore such requests.
+
+``V4L2_CID_AUTO_FOCUS_START (button)``
+ Starts single auto focus process. The effect of setting this control
+ when ``V4L2_CID_FOCUS_AUTO`` is set to ``TRUE`` (1) is undefined,
+ drivers should ignore such requests.
+
+``V4L2_CID_AUTO_FOCUS_STOP (button)``
+ Aborts automatic focusing started with ``V4L2_CID_AUTO_FOCUS_START``
+ control. It is effective only when the continuous autofocus is
+ disabled, that is when ``V4L2_CID_FOCUS_AUTO`` control is set to
+ ``FALSE`` (0).
+
+.. _v4l2-auto-focus-status:
+
+``V4L2_CID_AUTO_FOCUS_STATUS (bitmask)``
+ The automatic focus status. This is a read-only control.
+
+ Setting ``V4L2_LOCK_FOCUS`` lock bit of the ``V4L2_CID_3A_LOCK``
+ control may stop updates of the ``V4L2_CID_AUTO_FOCUS_STATUS``
+ control value.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_AUTO_FOCUS_STATUS_IDLE``
+
+ - Automatic focus is not active.
+
+ - .. row 2
+
+ - ``V4L2_AUTO_FOCUS_STATUS_BUSY``
+
+ - Automatic focusing is in progress.
+
+ - .. row 3
+
+ - ``V4L2_AUTO_FOCUS_STATUS_REACHED``
+
+ - Focus has been reached.
+
+ - .. row 4
+
+ - ``V4L2_AUTO_FOCUS_STATUS_FAILED``
+
+ - Automatic focus has failed, the driver will not transition from
+ this state until another action is performed by an application.
+
+
+
+.. _v4l2-auto-focus-range:
+
+``V4L2_CID_AUTO_FOCUS_RANGE (enum v4l2_auto_focus_range)``
+ Determines auto focus distance range for which lens may be adjusted.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_AUTO_FOCUS_RANGE_AUTO``
+
+ - The camera automatically selects the focus range.
+
+ - .. row 2
+
+ - ``V4L2_AUTO_FOCUS_RANGE_NORMAL``
+
+ - Normal distance range, limited for best automatic focus
+ performance.
+
+ - .. row 3
+
+ - ``V4L2_AUTO_FOCUS_RANGE_MACRO``
+
+ - Macro (close-up) auto focus. The camera will use its minimum
+ possible distance for auto focus.
+
+ - .. row 4
+
+ - ``V4L2_AUTO_FOCUS_RANGE_INFINITY``
+
+ - The lens is set to focus on an object at infinite distance.
+
+
+
+``V4L2_CID_ZOOM_ABSOLUTE (integer)``
+ Specify the objective lens focal length as an absolute value. The
+ zoom unit is driver-specific and its value should be a positive
+ integer.
+
+``V4L2_CID_ZOOM_RELATIVE (integer)``
+ Specify the objective lens focal length relatively to the current
+ value. Positive values move the zoom lens group towards the
+ telephoto direction, negative values towards the wide-angle
+ direction. The zoom unit is driver-specific. This is a write-only
+ control.
+
+``V4L2_CID_ZOOM_CONTINUOUS (integer)``
+ Move the objective lens group at the specified speed until it
+ reaches physical device limits or until an explicit request to stop
+ the movement. A positive value moves the zoom lens group towards the
+ telephoto direction. A value of zero stops the zoom lens group
+ movement. A negative value moves the zoom lens group towards the
+ wide-angle direction. The zoom speed unit is driver-specific.
+
+``V4L2_CID_IRIS_ABSOLUTE (integer)``
+ This control sets the camera's aperture to the specified value. The
+ unit is undefined. Larger values open the iris wider, smaller values
+ close it.
+
+``V4L2_CID_IRIS_RELATIVE (integer)``
+ This control modifies the camera's aperture by the specified amount.
+ The unit is undefined. Positive values open the iris one step
+ further, negative values close it one step further. This is a
+ write-only control.
+
+``V4L2_CID_PRIVACY (boolean)``
+ Prevent video from being acquired by the camera. When this control
+ is set to ``TRUE`` (1), no image can be captured by the camera.
+ Common means to enforce privacy are mechanical obturation of the
+ sensor and firmware image processing, but the device is not
+ restricted to these methods. Devices that implement the privacy
+ control must support read access and may support write access.
+
+``V4L2_CID_BAND_STOP_FILTER (integer)``
+ Switch the band-stop filter of a camera sensor on or off, or specify
+ its strength. Such band-stop filters can be used, for example, to
+ filter out the fluorescent light component.
+
+.. _v4l2-auto-n-preset-white-balance:
+
+``V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE (enum v4l2_auto_n_preset_white_balance)``
+ Sets white balance to automatic, manual or a preset. The presets
+ determine color temperature of the light as a hint to the camera for
+ white balance adjustments resulting in most accurate color
+ representation. The following white balance presets are listed in
+ order of increasing color temperature.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_WHITE_BALANCE_MANUAL``
+
+ - Manual white balance.
+
+ - .. row 2
+
+ - ``V4L2_WHITE_BALANCE_AUTO``
+
+ - Automatic white balance adjustments.
+
+ - .. row 3
+
+ - ``V4L2_WHITE_BALANCE_INCANDESCENT``
+
+ - White balance setting for incandescent (tungsten) lighting. It
+ generally cools down the colors and corresponds approximately to
+ 2500...3500 K color temperature range.
+
+ - .. row 4
+
+ - ``V4L2_WHITE_BALANCE_FLUORESCENT``
+
+ - White balance preset for fluorescent lighting. It corresponds
+ approximately to 4000...5000 K color temperature.
+
+ - .. row 5
+
+ - ``V4L2_WHITE_BALANCE_FLUORESCENT_H``
+
+ - With this setting the camera will compensate for fluorescent H
+ lighting.
+
+ - .. row 6
+
+ - ``V4L2_WHITE_BALANCE_HORIZON``
+
+ - White balance setting for horizon daylight. It corresponds
+ approximately to 5000 K color temperature.
+
+ - .. row 7
+
+ - ``V4L2_WHITE_BALANCE_DAYLIGHT``
+
+ - White balance preset for daylight (with clear sky). It corresponds
+ approximately to 5000...6500 K color temperature.
+
+ - .. row 8
+
+ - ``V4L2_WHITE_BALANCE_FLASH``
+
+ - With this setting the camera will compensate for the flash light.
+ It slightly warms up the colors and corresponds roughly to
+ 5000...5500 K color temperature.
+
+ - .. row 9
+
+ - ``V4L2_WHITE_BALANCE_CLOUDY``
+
+ - White balance preset for moderately overcast sky. This option
+ corresponds approximately to 6500...8000 K color temperature
+ range.
+
+ - .. row 10
+
+ - ``V4L2_WHITE_BALANCE_SHADE``
+
+ - White balance preset for shade or heavily overcast sky. It
+ corresponds approximately to 9000...10000 K color temperature.
+
+
+
+.. _v4l2-wide-dynamic-range:
+
+``V4L2_CID_WIDE_DYNAMIC_RANGE (boolean)``
+ Enables or disables the camera's wide dynamic range feature. This
+ feature allows to obtain clear images in situations where intensity
+ of the illumination varies significantly throughout the scene, i.e.
+ there are simultaneously very dark and very bright areas. It is most
+ commonly realized in cameras by combining two subsequent frames with
+ different exposure times. [1]_
+
+.. _v4l2-image-stabilization:
+
+``V4L2_CID_IMAGE_STABILIZATION (boolean)``
+ Enables or disables image stabilization.
+
+``V4L2_CID_ISO_SENSITIVITY (integer menu)``
+ Determines ISO equivalent of an image sensor indicating the sensor's
+ sensitivity to light. The numbers are expressed in arithmetic scale,
+ as per :ref:`iso12232` standard, where doubling the sensor
+ sensitivity is represented by doubling the numerical ISO value.
+ Applications should interpret the values as standard ISO values
+ multiplied by 1000, e.g. control value 800 stands for ISO 0.8.
+ Drivers will usually support only a subset of standard ISO values.
+ The effect of setting this control while the
+ ``V4L2_CID_ISO_SENSITIVITY_AUTO`` control is set to a value other
+ than ``V4L2_CID_ISO_SENSITIVITY_MANUAL`` is undefined, drivers
+ should ignore such requests.
+
+.. _v4l2-iso-sensitivity-auto-type:
+
+``V4L2_CID_ISO_SENSITIVITY_AUTO (enum v4l2_iso_sensitivity_type)``
+ Enables or disables automatic ISO sensitivity adjustments.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_CID_ISO_SENSITIVITY_MANUAL``
+
+ - Manual ISO sensitivity.
+
+ - .. row 2
+
+ - ``V4L2_CID_ISO_SENSITIVITY_AUTO``
+
+ - Automatic ISO sensitivity adjustments.
+
+
+
+.. _v4l2-scene-mode:
+
+``V4L2_CID_SCENE_MODE (enum v4l2_scene_mode)``
+ This control allows to select scene programs as the camera automatic
+ modes optimized for common shooting scenes. Within these modes the
+ camera determines best exposure, aperture, focusing, light metering,
+ white balance and equivalent sensitivity. The controls of those
+ parameters are influenced by the scene mode control. An exact
+ behavior in each mode is subject to the camera specification.
+
+ When the scene mode feature is not used, this control should be set
+ to ``V4L2_SCENE_MODE_NONE`` to make sure the other possibly related
+ controls are accessible. The following scene programs are defined:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_SCENE_MODE_NONE``
+
+ - The scene mode feature is disabled.
+
+ - .. row 2
+
+ - ``V4L2_SCENE_MODE_BACKLIGHT``
+
+ - Backlight. Compensates for dark shadows when light is coming from
+ behind a subject, also by automatically turning on the flash.
+
+ - .. row 3
+
+ - ``V4L2_SCENE_MODE_BEACH_SNOW``
+
+ - Beach and snow. This mode compensates for all-white or bright
+ scenes, which tend to look gray and low contrast, when camera's
+ automatic exposure is based on an average scene brightness. To
+ compensate, this mode automatically slightly overexposes the
+ frames. The white balance may also be adjusted to compensate for
+ the fact that reflected snow looks bluish rather than white.
+
+ - .. row 4
+
+ - ``V4L2_SCENE_MODE_CANDLELIGHT``
+
+ - Candle light. The camera generally raises the ISO sensitivity and
+ lowers the shutter speed. This mode compensates for relatively
+ close subject in the scene. The flash is disabled in order to
+ preserve the ambiance of the light.
+
+ - .. row 5
+
+ - ``V4L2_SCENE_MODE_DAWN_DUSK``
+
+ - Dawn and dusk. Preserves the colors seen in low natural light
+ before dusk and after down. The camera may turn off the flash, and
+ automatically focus at infinity. It will usually boost saturation
+ and lower the shutter speed.
+
+ - .. row 6
+
+ - ``V4L2_SCENE_MODE_FALL_COLORS``
+
+ - Fall colors. Increases saturation and adjusts white balance for
+ color enhancement. Pictures of autumn leaves get saturated reds
+ and yellows.
+
+ - .. row 7
+
+ - ``V4L2_SCENE_MODE_FIREWORKS``
+
+ - Fireworks. Long exposure times are used to capture the expanding
+ burst of light from a firework. The camera may invoke image
+ stabilization.
+
+ - .. row 8
+
+ - ``V4L2_SCENE_MODE_LANDSCAPE``
+
+ - Landscape. The camera may choose a small aperture to provide deep
+ depth of field and long exposure duration to help capture detail
+ in dim light conditions. The focus is fixed at infinity. Suitable
+ for distant and wide scenery.
+
+ - .. row 9
+
+ - ``V4L2_SCENE_MODE_NIGHT``
+
+ - Night, also known as Night Landscape. Designed for low light
+ conditions, it preserves detail in the dark areas without blowing
+ out bright objects. The camera generally sets itself to a
+ medium-to-high ISO sensitivity, with a relatively long exposure
+ time, and turns flash off. As such, there will be increased image
+ noise and the possibility of blurred image.
+
+ - .. row 10
+
+ - ``V4L2_SCENE_MODE_PARTY_INDOOR``
+
+ - Party and indoor. Designed to capture indoor scenes that are lit
+ by indoor background lighting as well as the flash. The camera
+ usually increases ISO sensitivity, and adjusts exposure for the
+ low light conditions.
+
+ - .. row 11
+
+ - ``V4L2_SCENE_MODE_PORTRAIT``
+
+ - Portrait. The camera adjusts the aperture so that the depth of
+ field is reduced, which helps to isolate the subject against a
+ smooth background. Most cameras recognize the presence of faces in
+ the scene and focus on them. The color hue is adjusted to enhance
+ skin tones. The intensity of the flash is often reduced.
+
+ - .. row 12
+
+ - ``V4L2_SCENE_MODE_SPORTS``
+
+ - Sports. Significantly increases ISO and uses a fast shutter speed
+ to freeze motion of rapidly-moving subjects. Increased image noise
+ may be seen in this mode.
+
+ - .. row 13
+
+ - ``V4L2_SCENE_MODE_SUNSET``
+
+ - Sunset. Preserves deep hues seen in sunsets and sunrises. It bumps
+ up the saturation.
+
+ - .. row 14
+
+ - ``V4L2_SCENE_MODE_TEXT``
+
+ - Text. It applies extra contrast and sharpness, it is typically a
+ black-and-white mode optimized for readability. Automatic focus
+ may be switched to close-up mode and this setting may also involve
+ some lens-distortion correction.
+
+
+
+``V4L2_CID_3A_LOCK (bitmask)``
+ This control locks or unlocks the automatic focus, exposure and
+ white balance. The automatic adjustments can be paused independently
+ by setting the corresponding lock bit to 1. The camera then retains
+ the settings until the lock bit is cleared. The following lock bits
+ are defined:
+
+ When a given algorithm is not enabled, drivers should ignore
+ requests to lock it and should return no error. An example might be
+ an application setting bit ``V4L2_LOCK_WHITE_BALANCE`` when the
+ ``V4L2_CID_AUTO_WHITE_BALANCE`` control is set to ``FALSE``. The
+ value of this control may be changed by exposure, white balance or
+ focus controls.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_LOCK_EXPOSURE``
+
+ - Automatic exposure adjustments lock.
+
+ - .. row 2
+
+ - ``V4L2_LOCK_WHITE_BALANCE``
+
+ - Automatic white balance adjustments lock.
+
+ - .. row 3
+
+ - ``V4L2_LOCK_FOCUS``
+
+ - Automatic focus lock.
+
+
+
+``V4L2_CID_PAN_SPEED (integer)``
+ This control turns the camera horizontally at the specific speed.
+ The unit is undefined. A positive value moves the camera to the
+ right (clockwise when viewed from above), a negative value to the
+ left. A value of zero stops the motion if one is in progress and has
+ no effect otherwise.
+
+``V4L2_CID_TILT_SPEED (integer)``
+ This control turns the camera vertically at the specified speed. The
+ unit is undefined. A positive value moves the camera up, a negative
+ value down. A value of zero stops the motion if one is in progress
+ and has no effect otherwise.
+
+
+.. _fm-tx-controls:
+
+FM Transmitter Control Reference
+================================
+
+The FM Transmitter (FM_TX) class includes controls for common features
+of FM transmissions capable devices. Currently this class includes
+parameters for audio compression, pilot tone generation, audio deviation
+limiter, RDS transmission and tuning power features.
+
+
+.. _fm-tx-control-id:
+
+FM_TX Control IDs
+-----------------
+
+``V4L2_CID_FM_TX_CLASS (class)``
+ The FM_TX class descriptor. Calling
+ :ref:`VIDIOC_QUERYCTRL` for this control will
+ return a description of this control class.
+
+``V4L2_CID_RDS_TX_DEVIATION (integer)``
+ Configures RDS signal frequency deviation level in Hz. The range and
+ step are driver-specific.
+
+``V4L2_CID_RDS_TX_PI (integer)``
+ Sets the RDS Programme Identification field for transmission.
+
+``V4L2_CID_RDS_TX_PTY (integer)``
+ Sets the RDS Programme Type field for transmission. This encodes up
+ to 31 pre-defined programme types.
+
+``V4L2_CID_RDS_TX_PS_NAME (string)``
+ Sets the Programme Service name (PS_NAME) for transmission. It is
+ intended for static display on a receiver. It is the primary aid to
+ listeners in programme service identification and selection. In
+ Annex E of :ref:`iec62106`, the RDS specification, there is a full
+ description of the correct character encoding for Programme Service
+ name strings. Also from RDS specification, PS is usually a single
+ eight character text. However, it is also possible to find receivers
+ which can scroll strings sized as 8 x N characters. So, this control
+ must be configured with steps of 8 characters. The result is it must
+ always contain a string with size multiple of 8.
+
+``V4L2_CID_RDS_TX_RADIO_TEXT (string)``
+ Sets the Radio Text info for transmission. It is a textual
+ description of what is being broadcasted. RDS Radio Text can be
+ applied when broadcaster wishes to transmit longer PS names,
+ programme-related information or any other text. In these cases,
+ RadioText should be used in addition to ``V4L2_CID_RDS_TX_PS_NAME``.
+ The encoding for Radio Text strings is also fully described in Annex
+ E of :ref:`iec62106`. The length of Radio Text strings depends on
+ which RDS Block is being used to transmit it, either 32 (2A block)
+ or 64 (2B block). However, it is also possible to find receivers
+ which can scroll strings sized as 32 x N or 64 x N characters. So,
+ this control must be configured with steps of 32 or 64 characters.
+ The result is it must always contain a string with size multiple of
+ 32 or 64.
+
+``V4L2_CID_RDS_TX_MONO_STEREO (boolean)``
+ Sets the Mono/Stereo bit of the Decoder Identification code. If set,
+ then the audio was recorded as stereo.
+
+``V4L2_CID_RDS_TX_ARTIFICIAL_HEAD (boolean)``
+ Sets the
+ `Artificial Head <http://en.wikipedia.org/wiki/Artificial_head>`__
+ bit of the Decoder Identification code. If set, then the audio was
+ recorded using an artificial head.
+
+``V4L2_CID_RDS_TX_COMPRESSED (boolean)``
+ Sets the Compressed bit of the Decoder Identification code. If set,
+ then the audio is compressed.
+
+``V4L2_CID_RDS_TX_DYNAMIC_PTY (boolean)``
+ Sets the Dynamic PTY bit of the Decoder Identification code. If set,
+ then the PTY code is dynamically switched.
+
+``V4L2_CID_RDS_TX_TRAFFIC_ANNOUNCEMENT (boolean)``
+ If set, then a traffic announcement is in progress.
+
+``V4L2_CID_RDS_TX_TRAFFIC_PROGRAM (boolean)``
+ If set, then the tuned programme carries traffic announcements.
+
+``V4L2_CID_RDS_TX_MUSIC_SPEECH (boolean)``
+ If set, then this channel broadcasts music. If cleared, then it
+ broadcasts speech. If the transmitter doesn't make this distinction,
+ then it should be set.
+
+``V4L2_CID_RDS_TX_ALT_FREQS_ENABLE (boolean)``
+ If set, then transmit alternate frequencies.
+
+``V4L2_CID_RDS_TX_ALT_FREQS (__u32 array)``
+ The alternate frequencies in kHz units. The RDS standard allows for
+ up to 25 frequencies to be defined. Drivers may support fewer
+ frequencies so check the array size.
+
+``V4L2_CID_AUDIO_LIMITER_ENABLED (boolean)``
+ Enables or disables the audio deviation limiter feature. The limiter
+ is useful when trying to maximize the audio volume, minimize
+ receiver-generated distortion and prevent overmodulation.
+
+``V4L2_CID_AUDIO_LIMITER_RELEASE_TIME (integer)``
+ Sets the audio deviation limiter feature release time. Unit is in
+ useconds. Step and range are driver-specific.
+
+``V4L2_CID_AUDIO_LIMITER_DEVIATION (integer)``
+ Configures audio frequency deviation level in Hz. The range and step
+ are driver-specific.
+
+``V4L2_CID_AUDIO_COMPRESSION_ENABLED (boolean)``
+ Enables or disables the audio compression feature. This feature
+ amplifies signals below the threshold by a fixed gain and compresses
+ audio signals above the threshold by the ratio of Threshold/(Gain +
+ Threshold).
+
+``V4L2_CID_AUDIO_COMPRESSION_GAIN (integer)``
+ Sets the gain for audio compression feature. It is a dB value. The
+ range and step are driver-specific.
+
+``V4L2_CID_AUDIO_COMPRESSION_THRESHOLD (integer)``
+ Sets the threshold level for audio compression freature. It is a dB
+ value. The range and step are driver-specific.
+
+``V4L2_CID_AUDIO_COMPRESSION_ATTACK_TIME (integer)``
+ Sets the attack time for audio compression feature. It is a useconds
+ value. The range and step are driver-specific.
+
+``V4L2_CID_AUDIO_COMPRESSION_RELEASE_TIME (integer)``
+ Sets the release time for audio compression feature. It is a
+ useconds value. The range and step are driver-specific.
+
+``V4L2_CID_PILOT_TONE_ENABLED (boolean)``
+ Enables or disables the pilot tone generation feature.
+
+``V4L2_CID_PILOT_TONE_DEVIATION (integer)``
+ Configures pilot tone frequency deviation level. Unit is in Hz. The
+ range and step are driver-specific.
+
+``V4L2_CID_PILOT_TONE_FREQUENCY (integer)``
+ Configures pilot tone frequency value. Unit is in Hz. The range and
+ step are driver-specific.
+
+``V4L2_CID_TUNE_PREEMPHASIS (enum v4l2_preemphasis)``
+ Configures the pre-emphasis value for broadcasting. A pre-emphasis
+ filter is applied to the broadcast to accentuate the high audio
+ frequencies. Depending on the region, a time constant of either 50
+ or 75 useconds is used. The enum v4l2_preemphasis defines possible
+ values for pre-emphasis. Here they are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_PREEMPHASIS_DISABLED``
+
+ - No pre-emphasis is applied.
+
+ - .. row 2
+
+ - ``V4L2_PREEMPHASIS_50_uS``
+
+ - A pre-emphasis of 50 uS is used.
+
+ - .. row 3
+
+ - ``V4L2_PREEMPHASIS_75_uS``
+
+ - A pre-emphasis of 75 uS is used.
+
+
+
+``V4L2_CID_TUNE_POWER_LEVEL (integer)``
+ Sets the output power level for signal transmission. Unit is in
+ dBuV. Range and step are driver-specific.
+
+``V4L2_CID_TUNE_ANTENNA_CAPACITOR (integer)``
+ This selects the value of antenna tuning capacitor manually or
+ automatically if set to zero. Unit, range and step are
+ driver-specific.
+
+For more details about RDS specification, refer to :ref:`iec62106`
+document, from CENELEC.
+
+
+.. _flash-controls:
+
+Flash Control Reference
+=======================
+
+The V4L2 flash controls are intended to provide generic access to flash
+controller devices. Flash controller devices are typically used in
+digital cameras.
+
+The interface can support both LED and xenon flash devices. As of
+writing this, there is no xenon flash driver using this interface.
+
+
+.. _flash-controls-use-cases:
+
+Supported use cases
+-------------------
+
+
+Unsynchronised LED flash (software strobe)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Unsynchronised LED flash is controlled directly by the host as the
+sensor. The flash must be enabled by the host before the exposure of the
+image starts and disabled once it ends. The host is fully responsible
+for the timing of the flash.
+
+Example of such device: Nokia N900.
+
+
+Synchronised LED flash (hardware strobe)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The synchronised LED flash is pre-programmed by the host (power and
+timeout) but controlled by the sensor through a strobe signal from the
+sensor to the flash.
+
+The sensor controls the flash duration and timing. This information
+typically must be made available to the sensor.
+
+
+LED flash as torch
+^^^^^^^^^^^^^^^^^^
+
+LED flash may be used as torch in conjunction with another use case
+involving camera or individually.
+
+
+.. _flash-control-id:
+
+Flash Control IDs
+"""""""""""""""""
+
+``V4L2_CID_FLASH_CLASS (class)``
+ The FLASH class descriptor.
+
+``V4L2_CID_FLASH_LED_MODE (menu)``
+ Defines the mode of the flash LED, the high-power white LED attached
+ to the flash controller. Setting this control may not be possible in
+ presence of some faults. See V4L2_CID_FLASH_FAULT.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_FLASH_LED_MODE_NONE``
+
+ - Off.
+
+ - .. row 2
+
+ - ``V4L2_FLASH_LED_MODE_FLASH``
+
+ - Flash mode.
+
+ - .. row 3
+
+ - ``V4L2_FLASH_LED_MODE_TORCH``
+
+ - Torch mode. See V4L2_CID_FLASH_TORCH_INTENSITY.
+
+
+
+``V4L2_CID_FLASH_STROBE_SOURCE (menu)``
+ Defines the source of the flash LED strobe.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_FLASH_STROBE_SOURCE_SOFTWARE``
+
+ - The flash strobe is triggered by using the
+ V4L2_CID_FLASH_STROBE control.
+
+ - .. row 2
+
+ - ``V4L2_FLASH_STROBE_SOURCE_EXTERNAL``
+
+ - The flash strobe is triggered by an external source. Typically
+ this is a sensor, which makes it possible to synchronises the
+ flash strobe start to exposure start.
+
+
+
+``V4L2_CID_FLASH_STROBE (button)``
+ Strobe flash. Valid when V4L2_CID_FLASH_LED_MODE is set to
+ V4L2_FLASH_LED_MODE_FLASH and V4L2_CID_FLASH_STROBE_SOURCE
+ is set to V4L2_FLASH_STROBE_SOURCE_SOFTWARE. Setting this
+ control may not be possible in presence of some faults. See
+ V4L2_CID_FLASH_FAULT.
+
+``V4L2_CID_FLASH_STROBE_STOP (button)``
+ Stop flash strobe immediately.
+
+``V4L2_CID_FLASH_STROBE_STATUS (boolean)``
+ Strobe status: whether the flash is strobing at the moment or not.
+ This is a read-only control.
+
+``V4L2_CID_FLASH_TIMEOUT (integer)``
+ Hardware timeout for flash. The flash strobe is stopped after this
+ period of time has passed from the start of the strobe.
+
+``V4L2_CID_FLASH_INTENSITY (integer)``
+ Intensity of the flash strobe when the flash LED is in flash mode
+ (V4L2_FLASH_LED_MODE_FLASH). The unit should be milliamps (mA)
+ if possible.
+
+``V4L2_CID_FLASH_TORCH_INTENSITY (integer)``
+ Intensity of the flash LED in torch mode
+ (V4L2_FLASH_LED_MODE_TORCH). The unit should be milliamps (mA)
+ if possible. Setting this control may not be possible in presence of
+ some faults. See V4L2_CID_FLASH_FAULT.
+
+``V4L2_CID_FLASH_INDICATOR_INTENSITY (integer)``
+ Intensity of the indicator LED. The indicator LED may be fully
+ independent of the flash LED. The unit should be microamps (uA) if
+ possible.
+
+``V4L2_CID_FLASH_FAULT (bitmask)``
+ Faults related to the flash. The faults tell about specific problems
+ in the flash chip itself or the LEDs attached to it. Faults may
+ prevent further use of some of the flash controls. In particular,
+ V4L2_CID_FLASH_LED_MODE is set to V4L2_FLASH_LED_MODE_NONE
+ if the fault affects the flash LED. Exactly which faults have such
+ an effect is chip dependent. Reading the faults resets the control
+ and returns the chip to a usable state if possible.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_FLASH_FAULT_OVER_VOLTAGE``
+
+ - Flash controller voltage to the flash LED has exceeded the limit
+ specific to the flash controller.
+
+ - .. row 2
+
+ - ``V4L2_FLASH_FAULT_TIMEOUT``
+
+ - The flash strobe was still on when the timeout set by the user ---
+ V4L2_CID_FLASH_TIMEOUT control --- has expired. Not all flash
+ controllers may set this in all such conditions.
+
+ - .. row 3
+
+ - ``V4L2_FLASH_FAULT_OVER_TEMPERATURE``
+
+ - The flash controller has overheated.
+
+ - .. row 4
+
+ - ``V4L2_FLASH_FAULT_SHORT_CIRCUIT``
+
+ - The short circuit protection of the flash controller has been
+ triggered.
+
+ - .. row 5
+
+ - ``V4L2_FLASH_FAULT_OVER_CURRENT``
+
+ - Current in the LED power supply has exceeded the limit specific to
+ the flash controller.
+
+ - .. row 6
+
+ - ``V4L2_FLASH_FAULT_INDICATOR``
+
+ - The flash controller has detected a short or open circuit
+ condition on the indicator LED.
+
+ - .. row 7
+
+ - ``V4L2_FLASH_FAULT_UNDER_VOLTAGE``
+
+ - Flash controller voltage to the flash LED has been below the
+ minimum limit specific to the flash controller.
+
+ - .. row 8
+
+ - ``V4L2_FLASH_FAULT_INPUT_VOLTAGE``
+
+ - The input voltage of the flash controller is below the limit under
+ which strobing the flash at full current will not be possible.The
+ condition persists until this flag is no longer set.
+
+ - .. row 9
+
+ - ``V4L2_FLASH_FAULT_LED_OVER_TEMPERATURE``
+
+ - The temperature of the LED has exceeded its allowed upper limit.
+
+
+
+``V4L2_CID_FLASH_CHARGE (boolean)``
+ Enable or disable charging of the xenon flash capacitor.
+
+``V4L2_CID_FLASH_READY (boolean)``
+ Is the flash ready to strobe? Xenon flashes require their capacitors
+ charged before strobing. LED flashes often require a cooldown period
+ after strobe during which another strobe will not be possible. This
+ is a read-only control.
+
+
+.. _jpeg-controls:
+
+JPEG Control Reference
+======================
+
+The JPEG class includes controls for common features of JPEG encoders
+and decoders. Currently it includes features for codecs implementing
+progressive baseline DCT compression process with Huffman entrophy
+coding.
+
+
+.. _jpeg-control-id:
+
+JPEG Control IDs
+----------------
+
+``V4L2_CID_JPEG_CLASS (class)``
+ The JPEG class descriptor. Calling
+ :ref:`VIDIOC_QUERYCTRL` for this control will
+ return a description of this control class.
+
+``V4L2_CID_JPEG_CHROMA_SUBSAMPLING (menu)``
+ The chroma subsampling factors describe how each component of an
+ input image is sampled, in respect to maximum sample rate in each
+ spatial dimension. See :ref:`itu-t81`, clause A.1.1. for more
+ details. The ``V4L2_CID_JPEG_CHROMA_SUBSAMPLING`` control determines
+ how Cb and Cr components are downsampled after coverting an input
+ image from RGB to Y'CbCr color space.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_JPEG_CHROMA_SUBSAMPLING_444``
+
+ - No chroma subsampling, each pixel has Y, Cr and Cb values.
+
+ - .. row 2
+
+ - ``V4L2_JPEG_CHROMA_SUBSAMPLING_422``
+
+ - Horizontally subsample Cr, Cb components by a factor of 2.
+
+ - .. row 3
+
+ - ``V4L2_JPEG_CHROMA_SUBSAMPLING_420``
+
+ - Subsample Cr, Cb components horizontally and vertically by 2.
+
+ - .. row 4
+
+ - ``V4L2_JPEG_CHROMA_SUBSAMPLING_411``
+
+ - Horizontally subsample Cr, Cb components by a factor of 4.
+
+ - .. row 5
+
+ - ``V4L2_JPEG_CHROMA_SUBSAMPLING_410``
+
+ - Subsample Cr, Cb components horizontally by 4 and vertically by 2.
+
+ - .. row 6
+
+ - ``V4L2_JPEG_CHROMA_SUBSAMPLING_GRAY``
+
+ - Use only luminance component.
+
+
+
+``V4L2_CID_JPEG_RESTART_INTERVAL (integer)``
+ The restart interval determines an interval of inserting RSTm
+ markers (m = 0..7). The purpose of these markers is to additionally
+ reinitialize the encoder process, in order to process blocks of an
+ image independently. For the lossy compression processes the restart
+ interval unit is MCU (Minimum Coded Unit) and its value is contained
+ in DRI (Define Restart Interval) marker. If
+ ``V4L2_CID_JPEG_RESTART_INTERVAL`` control is set to 0, DRI and RSTm
+ markers will not be inserted.
+
+.. _jpeg-quality-control:
+
+``V4L2_CID_JPEG_COMPRESSION_QUALITY (integer)``
+ ``V4L2_CID_JPEG_COMPRESSION_QUALITY`` control determines trade-off
+ between image quality and size. It provides simpler method for
+ applications to control image quality, without a need for direct
+ reconfiguration of luminance and chrominance quantization tables. In
+ cases where a driver uses quantization tables configured directly by
+ an application, using interfaces defined elsewhere,
+ ``V4L2_CID_JPEG_COMPRESSION_QUALITY`` control should be set by
+ driver to 0.
+
+ The value range of this control is driver-specific. Only positive,
+ non-zero values are meaningful. The recommended range is 1 - 100,
+ where larger values correspond to better image quality.
+
+.. _jpeg-active-marker-control:
+
+``V4L2_CID_JPEG_ACTIVE_MARKER (bitmask)``
+ Specify which JPEG markers are included in compressed stream. This
+ control is valid only for encoders.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_JPEG_ACTIVE_MARKER_APP0``
+
+ - Application data segment APP\ :sub:`0`.
+
+ - .. row 2
+
+ - ``V4L2_JPEG_ACTIVE_MARKER_APP1``
+
+ - Application data segment APP\ :sub:`1`.
+
+ - .. row 3
+
+ - ``V4L2_JPEG_ACTIVE_MARKER_COM``
+
+ - Comment segment.
+
+ - .. row 4
+
+ - ``V4L2_JPEG_ACTIVE_MARKER_DQT``
+
+ - Quantization tables segment.
+
+ - .. row 5
+
+ - ``V4L2_JPEG_ACTIVE_MARKER_DHT``
+
+ - Huffman tables segment.
+
+
+
+For more details about JPEG specification, refer to :ref:`itu-t81`,
+:ref:`jfif`, :ref:`w3c-jpeg-jfif`.
+
+
+.. _image-source-controls:
+
+Image Source Control Reference
+==============================
+
+The Image Source control class is intended for low-level control of
+image source devices such as image sensors. The devices feature an
+analogue to digital converter and a bus transmitter to transmit the
+image data out of the device.
+
+
+.. _image-source-control-id:
+
+Image Source Control IDs
+------------------------
+
+``V4L2_CID_IMAGE_SOURCE_CLASS (class)``
+ The IMAGE_SOURCE class descriptor.
+
+``V4L2_CID_VBLANK (integer)``
+ Vertical blanking. The idle period after every frame during which no
+ image data is produced. The unit of vertical blanking is a line.
+ Every line has length of the image width plus horizontal blanking at
+ the pixel rate defined by ``V4L2_CID_PIXEL_RATE`` control in the
+ same sub-device.
+
+``V4L2_CID_HBLANK (integer)``
+ Horizontal blanking. The idle period after every line of image data
+ during which no image data is produced. The unit of horizontal
+ blanking is pixels.
+
+``V4L2_CID_ANALOGUE_GAIN (integer)``
+ Analogue gain is gain affecting all colour components in the pixel
+ matrix. The gain operation is performed in the analogue domain
+ before A/D conversion.
+
+``V4L2_CID_TEST_PATTERN_RED (integer)``
+ Test pattern red colour component.
+
+``V4L2_CID_TEST_PATTERN_GREENR (integer)``
+ Test pattern green (next to red) colour component.
+
+``V4L2_CID_TEST_PATTERN_BLUE (integer)``
+ Test pattern blue colour component.
+
+``V4L2_CID_TEST_PATTERN_GREENB (integer)``
+ Test pattern green (next to blue) colour component.
+
+
+.. _image-process-controls:
+
+Image Process Control Reference
+===============================
+
+The Image Process control class is intended for low-level control of
+image processing functions. Unlike ``V4L2_CID_IMAGE_SOURCE_CLASS``, the
+controls in this class affect processing the image, and do not control
+capturing of it.
+
+
+.. _image-process-control-id:
+
+Image Process Control IDs
+-------------------------
+
+``V4L2_CID_IMAGE_PROC_CLASS (class)``
+ The IMAGE_PROC class descriptor.
+
+``V4L2_CID_LINK_FREQ (integer menu)``
+ Data bus frequency. Together with the media bus pixel code, bus type
+ (clock cycles per sample), the data bus frequency defines the pixel
+ rate (``V4L2_CID_PIXEL_RATE``) in the pixel array (or possibly
+ elsewhere, if the device is not an image sensor). The frame rate can
+ be calculated from the pixel clock, image width and height and
+ horizontal and vertical blanking. While the pixel rate control may
+ be defined elsewhere than in the subdev containing the pixel array,
+ the frame rate cannot be obtained from that information. This is
+ because only on the pixel array it can be assumed that the vertical
+ and horizontal blanking information is exact: no other blanking is
+ allowed in the pixel array. The selection of frame rate is performed
+ by selecting the desired horizontal and vertical blanking. The unit
+ of this control is Hz.
+
+``V4L2_CID_PIXEL_RATE (64-bit integer)``
+ Pixel rate in the source pads of the subdev. This control is
+ read-only and its unit is pixels / second.
+
+``V4L2_CID_TEST_PATTERN (menu)``
+ Some capture/display/sensor devices have the capability to generate
+ test pattern images. These hardware specific test patterns can be
+ used to test if a device is working properly.
+
+
+.. _dv-controls:
+
+Digital Video Control Reference
+===============================
+
+The Digital Video control class is intended to control receivers and
+transmitters for `VGA <http://en.wikipedia.org/wiki/Vga>`__,
+`DVI <http://en.wikipedia.org/wiki/Digital_Visual_Interface>`__
+(Digital Visual Interface), HDMI (:ref:`hdmi`) and DisplayPort
+(:ref:`dp`). These controls are generally expected to be private to
+the receiver or transmitter subdevice that implements them, so they are
+only exposed on the ``/dev/v4l-subdev*`` device node.
+
+Note that these devices can have multiple input or output pads which are
+hooked up to e.g. HDMI connectors. Even though the subdevice will
+receive or transmit video from/to only one of those pads, the other pads
+can still be active when it comes to EDID (Extended Display
+Identification Data, :ref:`vesaedid`) and HDCP (High-bandwidth Digital
+Content Protection System, :ref:`hdcp`) processing, allowing the
+device to do the fairly slow EDID/HDCP handling in advance. This allows
+for quick switching between connectors.
+
+These pads appear in several of the controls in this section as
+bitmasks, one bit for each pad. Bit 0 corresponds to pad 0, bit 1 to pad
+1, etc. The maximum value of the control is the set of valid pads.
+
+
+.. _dv-control-id:
+
+Digital Video Control IDs
+-------------------------
+
+``V4L2_CID_DV_CLASS (class)``
+ The Digital Video class descriptor.
+
+``V4L2_CID_DV_TX_HOTPLUG (bitmask)``
+ Many connectors have a hotplug pin which is high if EDID information
+ is available from the source. This control shows the state of the
+ hotplug pin as seen by the transmitter. Each bit corresponds to an
+ output pad on the transmitter. If an output pad does not have an
+ associated hotplug pin, then the bit for that pad will be 0. This
+ read-only control is applicable to DVI-D, HDMI and DisplayPort
+ connectors.
+
+``V4L2_CID_DV_TX_RXSENSE (bitmask)``
+ Rx Sense is the detection of pull-ups on the TMDS clock lines. This
+ normally means that the sink has left/entered standby (i.e. the
+ transmitter can sense that the receiver is ready to receive video).
+ Each bit corresponds to an output pad on the transmitter. If an
+ output pad does not have an associated Rx Sense, then the bit for
+ that pad will be 0. This read-only control is applicable to DVI-D
+ and HDMI devices.
+
+``V4L2_CID_DV_TX_EDID_PRESENT (bitmask)``
+ When the transmitter sees the hotplug signal from the receiver it
+ will attempt to read the EDID. If set, then the transmitter has read
+ at least the first block (= 128 bytes). Each bit corresponds to an
+ output pad on the transmitter. If an output pad does not support
+ EDIDs, then the bit for that pad will be 0. This read-only control
+ is applicable to VGA, DVI-A/D, HDMI and DisplayPort connectors.
+
+``V4L2_CID_DV_TX_MODE (enum v4l2_dv_tx_mode)``
+ HDMI transmitters can transmit in DVI-D mode (just video) or in HDMI
+ mode (video + audio + auxiliary data). This control selects which
+ mode to use: V4L2_DV_TX_MODE_DVI_D or V4L2_DV_TX_MODE_HDMI.
+ This control is applicable to HDMI connectors.
+
+``V4L2_CID_DV_TX_RGB_RANGE (enum v4l2_dv_rgb_range)``
+ Select the quantization range for RGB output. V4L2_DV_RANGE_AUTO
+ follows the RGB quantization range specified in the standard for the
+ video interface (ie. :ref:`cea861` for HDMI).
+ V4L2_DV_RANGE_LIMITED and V4L2_DV_RANGE_FULL override the
+ standard to be compatible with sinks that have not implemented the
+ standard correctly (unfortunately quite common for HDMI and DVI-D).
+ Full range allows all possible values to be used whereas limited
+ range sets the range to (16 << (N-8)) - (235 << (N-8)) where N is
+ the number of bits per component. This control is applicable to VGA,
+ DVI-A/D, HDMI and DisplayPort connectors.
+
+``V4L2_CID_DV_TX_IT_CONTENT_TYPE (enum v4l2_dv_it_content_type)``
+ Configures the IT Content Type of the transmitted video. This
+ information is sent over HDMI and DisplayPort connectors as part of
+ the AVI InfoFrame. The term 'IT Content' is used for content that
+ originates from a computer as opposed to content from a TV broadcast
+ or an analog source. The enum v4l2_dv_it_content_type defines
+ the possible content types:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_DV_IT_CONTENT_TYPE_GRAPHICS``
+
+ - Graphics content. Pixel data should be passed unfiltered and
+ without analog reconstruction.
+
+ - .. row 2
+
+ - ``V4L2_DV_IT_CONTENT_TYPE_PHOTO``
+
+ - Photo content. The content is derived from digital still pictures.
+ The content should be passed through with minimal scaling and
+ picture enhancements.
+
+ - .. row 3
+
+ - ``V4L2_DV_IT_CONTENT_TYPE_CINEMA``
+
+ - Cinema content.
+
+ - .. row 4
+
+ - ``V4L2_DV_IT_CONTENT_TYPE_GAME``
+
+ - Game content. Audio and video latency should be minimized.
+
+ - .. row 5
+
+ - ``V4L2_DV_IT_CONTENT_TYPE_NO_ITC``
+
+ - No IT Content information is available and the ITC bit in the AVI
+ InfoFrame is set to 0.
+
+
+
+``V4L2_CID_DV_RX_POWER_PRESENT (bitmask)``
+ Detects whether the receiver receives power from the source (e.g.
+ HDMI carries 5V on one of the pins). This is often used to power an
+ eeprom which contains EDID information, such that the source can
+ read the EDID even if the sink is in standby/power off. Each bit
+ corresponds to an input pad on the transmitter. If an input pad
+ cannot detect whether power is present, then the bit for that pad
+ will be 0. This read-only control is applicable to DVI-D, HDMI and
+ DisplayPort connectors.
+
+``V4L2_CID_DV_RX_RGB_RANGE (enum v4l2_dv_rgb_range)``
+ Select the quantization range for RGB input. V4L2_DV_RANGE_AUTO
+ follows the RGB quantization range specified in the standard for the
+ video interface (ie. :ref:`cea861` for HDMI).
+ V4L2_DV_RANGE_LIMITED and V4L2_DV_RANGE_FULL override the
+ standard to be compatible with sources that have not implemented the
+ standard correctly (unfortunately quite common for HDMI and DVI-D).
+ Full range allows all possible values to be used whereas limited
+ range sets the range to (16 << (N-8)) - (235 << (N-8)) where N is
+ the number of bits per component. This control is applicable to VGA,
+ DVI-A/D, HDMI and DisplayPort connectors.
+
+``V4L2_CID_DV_RX_IT_CONTENT_TYPE (enum v4l2_dv_it_content_type)``
+ Reads the IT Content Type of the received video. This information is
+ sent over HDMI and DisplayPort connectors as part of the AVI
+ InfoFrame. The term 'IT Content' is used for content that originates
+ from a computer as opposed to content from a TV broadcast or an
+ analog source. See ``V4L2_CID_DV_TX_IT_CONTENT_TYPE`` for the
+ available content types.
+
+
+.. _fm-rx-controls:
+
+FM Receiver Control Reference
+=============================
+
+The FM Receiver (FM_RX) class includes controls for common features of
+FM Reception capable devices.
+
+
+.. _fm-rx-control-id:
+
+FM_RX Control IDs
+-----------------
+
+``V4L2_CID_FM_RX_CLASS (class)``
+ The FM_RX class descriptor. Calling
+ :ref:`VIDIOC_QUERYCTRL` for this control will
+ return a description of this control class.
+
+``V4L2_CID_RDS_RECEPTION (boolean)``
+ Enables/disables RDS reception by the radio tuner
+
+``V4L2_CID_RDS_RX_PTY (integer)``
+ Gets RDS Programme Type field. This encodes up to 31 pre-defined
+ programme types.
+
+``V4L2_CID_RDS_RX_PS_NAME (string)``
+ Gets the Programme Service name (PS_NAME). It is intended for
+ static display on a receiver. It is the primary aid to listeners in
+ programme service identification and selection. In Annex E of
+ :ref:`iec62106`, the RDS specification, there is a full
+ description of the correct character encoding for Programme Service
+ name strings. Also from RDS specification, PS is usually a single
+ eight character text. However, it is also possible to find receivers
+ which can scroll strings sized as 8 x N characters. So, this control
+ must be configured with steps of 8 characters. The result is it must
+ always contain a string with size multiple of 8.
+
+``V4L2_CID_RDS_RX_RADIO_TEXT (string)``
+ Gets the Radio Text info. It is a textual description of what is
+ being broadcasted. RDS Radio Text can be applied when broadcaster
+ wishes to transmit longer PS names, programme-related information or
+ any other text. In these cases, RadioText can be used in addition to
+ ``V4L2_CID_RDS_RX_PS_NAME``. The encoding for Radio Text strings is
+ also fully described in Annex E of :ref:`iec62106`. The length of
+ Radio Text strings depends on which RDS Block is being used to
+ transmit it, either 32 (2A block) or 64 (2B block). However, it is
+ also possible to find receivers which can scroll strings sized as 32
+ x N or 64 x N characters. So, this control must be configured with
+ steps of 32 or 64 characters. The result is it must always contain a
+ string with size multiple of 32 or 64.
+
+``V4L2_CID_RDS_RX_TRAFFIC_ANNOUNCEMENT (boolean)``
+ If set, then a traffic announcement is in progress.
+
+``V4L2_CID_RDS_RX_TRAFFIC_PROGRAM (boolean)``
+ If set, then the tuned programme carries traffic announcements.
+
+``V4L2_CID_RDS_RX_MUSIC_SPEECH (boolean)``
+ If set, then this channel broadcasts music. If cleared, then it
+ broadcasts speech. If the transmitter doesn't make this distinction,
+ then it will be set.
+
+``V4L2_CID_TUNE_DEEMPHASIS (enum v4l2_deemphasis)``
+ Configures the de-emphasis value for reception. A de-emphasis filter
+ is applied to the broadcast to accentuate the high audio
+ frequencies. Depending on the region, a time constant of either 50
+ or 75 useconds is used. The enum v4l2_deemphasis defines possible
+ values for de-emphasis. Here they are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_DEEMPHASIS_DISABLED``
+
+ - No de-emphasis is applied.
+
+ - .. row 2
+
+ - ``V4L2_DEEMPHASIS_50_uS``
+
+ - A de-emphasis of 50 uS is used.
+
+ - .. row 3
+
+ - ``V4L2_DEEMPHASIS_75_uS``
+
+ - A de-emphasis of 75 uS is used.
+
+
+
+
+.. _detect-controls:
+
+Detect Control Reference
+========================
+
+The Detect class includes controls for common features of various motion
+or object detection capable devices.
+
+
+.. _detect-control-id:
+
+Detect Control IDs
+------------------
+
+``V4L2_CID_DETECT_CLASS (class)``
+ The Detect class descriptor. Calling
+ :ref:`VIDIOC_QUERYCTRL` for this control will
+ return a description of this control class.
+
+``V4L2_CID_DETECT_MD_MODE (menu)``
+ Sets the motion detection mode.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_DETECT_MD_MODE_DISABLED``
+
+ - Disable motion detection.
+
+ - .. row 2
+
+ - ``V4L2_DETECT_MD_MODE_GLOBAL``
+
+ - Use a single motion detection threshold.
+
+ - .. row 3
+
+ - ``V4L2_DETECT_MD_MODE_THRESHOLD_GRID``
+
+ - The image is divided into a grid, each cell with its own motion
+ detection threshold. These thresholds are set through the
+ ``V4L2_CID_DETECT_MD_THRESHOLD_GRID`` matrix control.
+
+ - .. row 4
+
+ - ``V4L2_DETECT_MD_MODE_REGION_GRID``
+
+ - The image is divided into a grid, each cell with its own region
+ value that specifies which per-region motion detection thresholds
+ should be used. Each region has its own thresholds. How these
+ per-region thresholds are set up is driver-specific. The region
+ values for the grid are set through the
+ ``V4L2_CID_DETECT_MD_REGION_GRID`` matrix control.
+
+
+
+``V4L2_CID_DETECT_MD_GLOBAL_THRESHOLD (integer)``
+ Sets the global motion detection threshold to be used with the
+ ``V4L2_DETECT_MD_MODE_GLOBAL`` motion detection mode.
+
+``V4L2_CID_DETECT_MD_THRESHOLD_GRID (__u16 matrix)``
+ Sets the motion detection thresholds for each cell in the grid. To
+ be used with the ``V4L2_DETECT_MD_MODE_THRESHOLD_GRID`` motion
+ detection mode. Matrix element (0, 0) represents the cell at the
+ top-left of the grid.
+
+``V4L2_CID_DETECT_MD_REGION_GRID (__u8 matrix)``
+ Sets the motion detection region value for each cell in the grid. To
+ be used with the ``V4L2_DETECT_MD_MODE_REGION_GRID`` motion
+ detection mode. Matrix element (0, 0) represents the cell at the
+ top-left of the grid.
+
+
+.. _rf-tuner-controls:
+
+RF Tuner Control Reference
+==========================
+
+The RF Tuner (RF_TUNER) class includes controls for common features of
+devices having RF tuner.
+
+In this context, RF tuner is radio receiver circuit between antenna and
+demodulator. It receives radio frequency (RF) from the antenna and
+converts that received signal to lower intermediate frequency (IF) or
+baseband frequency (BB). Tuners that could do baseband output are often
+called Zero-IF tuners. Older tuners were typically simple PLL tuners
+inside a metal box, whilst newer ones are highly integrated chips
+without a metal box "silicon tuners". These controls are mostly
+applicable for new feature rich silicon tuners, just because older
+tuners does not have much adjustable features.
+
+For more information about RF tuners see
+`Tuner (radio) <http://en.wikipedia.org/wiki/Tuner_%28radio%29>`__
+and `RF front end <http://en.wikipedia.org/wiki/RF_front_end>`__
+from Wikipedia.
+
+
+.. _rf-tuner-control-id:
+
+RF_TUNER Control IDs
+--------------------
+
+``V4L2_CID_RF_TUNER_CLASS (class)``
+ The RF_TUNER class descriptor. Calling
+ :ref:`VIDIOC_QUERYCTRL` for this control will
+ return a description of this control class.
+
+``V4L2_CID_RF_TUNER_BANDWIDTH_AUTO (boolean)``
+ Enables/disables tuner radio channel bandwidth configuration. In
+ automatic mode bandwidth configuration is performed by the driver.
+
+``V4L2_CID_RF_TUNER_BANDWIDTH (integer)``
+ Filter(s) on tuner signal path are used to filter signal according
+ to receiving party needs. Driver configures filters to fulfill
+ desired bandwidth requirement. Used when
+ V4L2_CID_RF_TUNER_BANDWIDTH_AUTO is not set. Unit is in Hz. The
+ range and step are driver-specific.
+
+``V4L2_CID_RF_TUNER_LNA_GAIN_AUTO (boolean)``
+ Enables/disables LNA automatic gain control (AGC)
+
+``V4L2_CID_RF_TUNER_MIXER_GAIN_AUTO (boolean)``
+ Enables/disables mixer automatic gain control (AGC)
+
+``V4L2_CID_RF_TUNER_IF_GAIN_AUTO (boolean)``
+ Enables/disables IF automatic gain control (AGC)
+
+``V4L2_CID_RF_TUNER_RF_GAIN (integer)``
+ The RF amplifier is the very first amplifier on the receiver signal
+ path, just right after the antenna input. The difference between the
+ LNA gain and the RF gain in this document is that the LNA gain is
+ integrated in the tuner chip while the RF gain is a separate chip.
+ There may be both RF and LNA gain controls in the same device. The
+ range and step are driver-specific.
+
+``V4L2_CID_RF_TUNER_LNA_GAIN (integer)``
+ LNA (low noise amplifier) gain is first gain stage on the RF tuner
+ signal path. It is located very close to tuner antenna input. Used
+ when ``V4L2_CID_RF_TUNER_LNA_GAIN_AUTO`` is not set. See
+ ``V4L2_CID_RF_TUNER_RF_GAIN`` to understand how RF gain and LNA gain
+ differs from the each others. The range and step are
+ driver-specific.
+
+``V4L2_CID_RF_TUNER_MIXER_GAIN (integer)``
+ Mixer gain is second gain stage on the RF tuner signal path. It is
+ located inside mixer block, where RF signal is down-converted by the
+ mixer. Used when ``V4L2_CID_RF_TUNER_MIXER_GAIN_AUTO`` is not set.
+ The range and step are driver-specific.
+
+``V4L2_CID_RF_TUNER_IF_GAIN (integer)``
+ IF gain is last gain stage on the RF tuner signal path. It is
+ located on output of RF tuner. It controls signal level of
+ intermediate frequency output or baseband output. Used when
+ ``V4L2_CID_RF_TUNER_IF_GAIN_AUTO`` is not set. The range and step
+ are driver-specific.
+
+``V4L2_CID_RF_TUNER_PLL_LOCK (boolean)``
+ Is synthesizer PLL locked? RF tuner is receiving given frequency
+ when that control is set. This is a read-only control.
+
+.. [1]
+ This control may be changed to a menu control in the future, if more
+ options are required.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _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.
+
+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
+:ref:`v4l2_pix_format <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).
+
+
+.. _v4l2-field:
+
+enum v4l2_field
+===============
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_FIELD_ANY``
+
+ - 0
+
+ - Applications request this field order when any one of the
+ ``V4L2_FIELD_NONE``, ``V4L2_FIELD_TOP``, ``V4L2_FIELD_BOTTOM``, or
+ ``V4L2_FIELD_INTERLACED`` formats 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
+ :ref:`v4l2_buffer <v4l2-buffer>` ``field`` can never be
+ ``V4L2_FIELD_ANY``.
+
+ - .. row 2
+
+ - ``V4L2_FIELD_NONE``
+
+ - 1
+
+ - Images are in progressive format, not interlaced. The driver may
+ also indicate this order when it cannot distinguish between
+ ``V4L2_FIELD_TOP`` and ``V4L2_FIELD_BOTTOM``.
+
+ - .. row 3
+
+ - ``V4L2_FIELD_TOP``
+
+ - 2
+
+ - Images consist of the top (aka odd) field only.
+
+ - .. row 4
+
+ - ``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.
+
+ - .. row 5
+
+ - ``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 first
+ transmitted) depends on the current video standard. M/NTSC
+ transmits the bottom field first, all other standards the top
+ field first.
+
+ - .. row 6
+
+ - ``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.
+
+ - .. row 7
+
+ - ``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.
+
+ - .. row 8
+
+ - ``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 :ref:`v4l2_buffer <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
+ :ref:`v4l2_buffer <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.
+
+ - .. row 9
+
+ - ``V4L2_FIELD_INTERLACED_TB``
+
+ - 8
+
+ - Images contain both fields, interleaved line by line, top field
+ first. The top field is transmitted first.
+
+ - .. row 10
+
+ - ``V4L2_FIELD_INTERLACED_BT``
+
+ - 9
+
+ - Images contain both fields, interleaved line by line, top field
+ first. The bottom field is transmitted first.
+
+
+
+.. _fieldseq-tb:
+
+Field Order, Top Field First Transmitted
+========================================
+
+.. figure:: field-order_files/fieldseq_tb.*
+ :alt: fieldseq_tb.pdf / fieldseq_tb.gif
+ :align: center
+
+
+.. _fieldseq-bt:
+
+Field Order, Bottom Field First Transmitted
+===========================================
+
+.. figure:: field-order_files/fieldseq_bt.*
+ :alt: fieldseq_bt.pdf / fieldseq_bt.gif
+ :align: center
+
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _format:
+
+************
+Data Formats
+************
+
+
+Data Format Negotiation
+=======================
+
+Different devices exchange different kinds of data with applications,
+for example video images, raw or sliced VBI data, RDS datagrams. Even
+within one kind many different formats are possible, in particular an
+abundance of image formats. Although drivers must provide a default and
+the selection persists across closing and reopening a device,
+applications should always negotiate a data format before engaging in
+data exchange. Negotiation means the application asks for a particular
+format and the driver selects and reports the best the hardware can do
+to satisfy the request. Of course applications can also just query the
+current selection.
+
+A single mechanism exists to negotiate all data formats using the
+aggregate struct :ref:`v4l2_format <v4l2-format>` and the
+:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
+:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls. Additionally the
+:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl can be used to examine
+what the hardware *could* do, without actually selecting a new data
+format. The data formats supported by the V4L2 API are covered in the
+respective device section in :ref:`devices`. For a closer look at
+image formats see :ref:`pixfmt`.
+
+The :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl is a major turning-point in the
+initialization sequence. Prior to this point multiple panel applications
+can access the same device concurrently to select the current input,
+change controls or modify other properties. The first :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
+assigns a logical stream (video data, VBI data etc.) exclusively to one
+file descriptor.
+
+Exclusive means no other application, more precisely no other file
+descriptor, can grab this stream or change device properties
+inconsistent with the negotiated parameters. A video standard change for
+example, when the new standard uses a different number of scan lines,
+can invalidate the selected image format. Therefore only the file
+descriptor owning the stream can make invalidating changes. Accordingly
+multiple file descriptors which grabbed different logical streams
+prevent each other from interfering with their settings. When for
+example video overlay is about to start or already in progress,
+simultaneous video capturing may be restricted to the same cropping and
+image size.
+
+When applications omit the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl its locking side
+effects are implied by the next step, the selection of an I/O method
+with the :ref:`VIDIOC_REQBUFS` ioctl or implicit
+with the first :ref:`read() <func-read>` or
+:ref:`write() <func-write>` call.
+
+Generally only one logical stream can be assigned to a file descriptor,
+the exception being drivers permitting simultaneous video capturing and
+overlay using the same file descriptor for compatibility with V4L and
+earlier versions of V4L2. Switching the logical stream or returning into
+"panel mode" is possible by closing and reopening the device. Drivers
+*may* support a switch using :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`.
+
+All drivers exchanging data with applications must support the
+:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. Implementation of the
+:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is highly recommended but optional.
+
+
+Image Format Enumeration
+========================
+
+Apart of the generic format negotiation functions a special ioctl to
+enumerate all image formats supported by video capture, overlay or
+output devices is available. [1]_
+
+The :ref:`VIDIOC_ENUM_FMT` ioctl must be supported
+by all drivers exchanging image data with applications.
+
+ **Important**
+
+ Drivers are not supposed to convert image formats in kernel space.
+ They must enumerate only formats directly supported by the hardware.
+ If necessary driver writers should publish an example conversion
+ routine or library for integration into applications.
+
+.. [1]
+ Enumerating formats an application has no a-priori knowledge of
+ (otherwise it could explicitly ask for them and need not enumerate)
+ seems useless, but there are applications serving as proxy between
+ drivers and the actual video applications for which this is useful.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _func-close:
+
+************
+V4L2 close()
+************
+
+Name
+====
+
+v4l2-close - Close a V4L2 device
+
+
+Synopsis
+========
+
+.. code-block:: c
+
+ #include <unistd.h>
+
+
+.. cpp:function:: int close( int fd )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+
+Description
+===========
+
+Closes the device. Any I/O in progress is terminated and resources
+associated with the file descriptor are freed. However data format
+parameters, current input or output, control values or other properties
+remain unchanged.
+
+
+Return Value
+============
+
+The function returns 0 on success, -1 on failure and the ``errno`` is
+set appropriately. Possible error codes:
+
+EBADF
+ ``fd`` is not a valid open file descriptor.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _func-ioctl:
+
+************
+V4L2 ioctl()
+************
+
+Name
+====
+
+v4l2-ioctl - Program a V4L2 device
+
+
+Synopsis
+========
+
+.. code-block:: c
+
+ #include <sys/ioctl.h>
+
+
+.. cpp:function:: int ioctl( int fd, int request, void *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ V4L2 ioctl request code as defined in the ``videodev2.h`` header
+ file, for example VIDIOC_QUERYCAP.
+
+``argp``
+ Pointer to a function parameter, usually a structure.
+
+
+Description
+===========
+
+The :ref:`ioctl() <func-ioctl>` function is used to program V4L2 devices. The
+argument ``fd`` must be an open file descriptor. An ioctl ``request``
+has encoded in it whether the argument is an input, output or read/write
+parameter, and the size of the argument ``argp`` in bytes. Macros and
+defines specifying V4L2 ioctl requests are located in the
+``videodev2.h`` header file. Applications should use their own copy, not
+include the version in the kernel sources on the system they compile on.
+All V4L2 ioctl requests, their respective function and parameters are
+specified in :ref:`user-func`.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+When an ioctl that takes an output or read/write parameter fails, the
+parameter remains unmodified.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _func-mmap:
+
+***********
+V4L2 mmap()
+***********
+
+Name
+====
+
+v4l2-mmap - Map device memory into application address space
+
+
+Synopsis
+========
+
+.. code-block:: c
+
+ #include <unistd.h>
+ #include <sys/mman.h>
+
+
+.. cpp:function:: void *mmap( void *start, size_t length, int prot, int flags, int fd, off_t offset )
+
+
+Arguments
+=========
+
+``start``
+ Map the buffer to this address in the application's address space.
+ When the ``MAP_FIXED`` flag is specified, ``start`` must be a
+ multiple of the pagesize and mmap will fail when the specified
+ address cannot be used. Use of this option is discouraged;
+ applications should just specify a ``NULL`` pointer here.
+
+``length``
+ Length of the memory area to map. This must be the same value as
+ returned by the driver in the struct
+ :ref:`v4l2_buffer <v4l2-buffer>` ``length`` field for the
+ single-planar API, and the same value as returned by the driver in
+ the struct :ref:`v4l2_plane <v4l2-plane>` ``length`` field for
+ the multi-planar API.
+
+``prot``
+ The ``prot`` argument describes the desired memory protection.
+ Regardless of the device type and the direction of data exchange it
+ should be set to ``PROT_READ`` | ``PROT_WRITE``, permitting read
+ and write access to image buffers. Drivers should support at least
+ this combination of flags. Note the Linux ``video-buf`` kernel
+ module, which is used by the bttv, saa7134, saa7146, cx88 and vivi
+ driver supports only ``PROT_READ`` | ``PROT_WRITE``. When the
+ driver does not support the desired protection the
+ :ref:`mmap() <func-mmap>` function fails.
+
+ Note device memory accesses (e. g. the memory on a graphics card
+ with video capturing hardware) may incur a performance penalty
+ compared to main memory accesses, or reads may be significantly
+ slower than writes or vice versa. Other I/O methods may be more
+ efficient in this case.
+
+``flags``
+ The ``flags`` parameter specifies the type of the mapped object,
+ mapping options and whether modifications made to the mapped copy of
+ the page are private to the process or are to be shared with other
+ references.
+
+ ``MAP_FIXED`` requests that the driver selects no other address than
+ the one specified. If the specified address cannot be used,
+ :ref:`mmap() <func-mmap>` will fail. If ``MAP_FIXED`` is specified,
+ ``start`` must be a multiple of the pagesize. Use of this option is
+ discouraged.
+
+ One of the ``MAP_SHARED`` or ``MAP_PRIVATE`` flags must be set.
+ ``MAP_SHARED`` allows applications to share the mapped memory with
+ other (e. g. child-) processes. Note the Linux ``video-buf`` module
+ which is used by the bttv, saa7134, saa7146, cx88 and vivi driver
+ supports only ``MAP_SHARED``. ``MAP_PRIVATE`` requests copy-on-write
+ semantics. V4L2 applications should not set the ``MAP_PRIVATE``,
+ ``MAP_DENYWRITE``, ``MAP_EXECUTABLE`` or ``MAP_ANON`` flag.
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``offset``
+ Offset of the buffer in device memory. This must be the same value
+ as returned by the driver in the struct
+ :ref:`v4l2_buffer <v4l2-buffer>` ``m`` union ``offset`` field for
+ the single-planar API, and the same value as returned by the driver
+ in the struct :ref:`v4l2_plane <v4l2-plane>` ``m`` union
+ ``mem_offset`` field for the multi-planar API.
+
+
+Description
+===========
+
+The :ref:`mmap() <func-mmap>` function asks to map ``length`` bytes starting at
+``offset`` in the memory of the device specified by ``fd`` into the
+application address space, preferably at address ``start``. This latter
+address is a hint only, and is usually specified as 0.
+
+Suitable length and offset parameters are queried with the
+:ref:`VIDIOC_QUERYBUF` ioctl. Buffers must be
+allocated with the :ref:`VIDIOC_REQBUFS` ioctl
+before they can be queried.
+
+To unmap buffers the :ref:`munmap() <func-munmap>` function is used.
+
+
+Return Value
+============
+
+On success :ref:`mmap() <func-mmap>` returns a pointer to the mapped buffer. On
+error ``MAP_FAILED`` (-1) is returned, and the ``errno`` variable is set
+appropriately. Possible error codes are:
+
+EBADF
+ ``fd`` is not a valid file descriptor.
+
+EACCES
+ ``fd`` is not open for reading and writing.
+
+EINVAL
+ The ``start`` or ``length`` or ``offset`` are not suitable. (E. g.
+ they are too large, or not aligned on a ``PAGESIZE`` boundary.)
+
+ The ``flags`` or ``prot`` value is not supported.
+
+ No buffers have been allocated with the
+ :ref:`VIDIOC_REQBUFS` ioctl.
+
+ENOMEM
+ Not enough physical or virtual memory was available to complete the
+ request.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _func-munmap:
+
+*************
+V4L2 munmap()
+*************
+
+Name
+====
+
+v4l2-munmap - Unmap device memory
+
+
+Synopsis
+========
+
+.. code-block:: c
+
+ #include <unistd.h>
+ #include <sys/mman.h>
+
+
+.. cpp:function:: int munmap( void *start, size_t length )
+
+
+Arguments
+=========
+
+``start``
+ Address of the mapped buffer as returned by the
+ :ref:`mmap() <func-mmap>` function.
+
+``length``
+ Length of the mapped buffer. This must be the same value as given to
+ :ref:`mmap() <func-mmap>` and returned by the driver in the struct
+ :ref:`v4l2_buffer <v4l2-buffer>` ``length`` field for the
+ single-planar API and in the struct
+ :ref:`v4l2_plane <v4l2-plane>` ``length`` field for the
+ multi-planar API.
+
+
+Description
+===========
+
+Unmaps a previously with the :ref:`mmap() <func-mmap>` function mapped
+buffer and frees it, if possible.
+
+
+Return Value
+============
+
+On success :ref:`munmap() <func-munmap>` returns 0, on failure -1 and the
+``errno`` variable is set appropriately:
+
+EINVAL
+ The ``start`` or ``length`` is incorrect, or no buffers have been
+ mapped yet.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _func-open:
+
+***********
+V4L2 open()
+***********
+
+Name
+====
+
+v4l2-open - Open a V4L2 device
+
+
+Synopsis
+========
+
+.. code-block:: c
+
+ #include <fcntl.h>
+
+
+.. cpp:function:: int open( const char *device_name, int flags )
+
+
+Arguments
+=========
+
+``device_name``
+ Device to be opened.
+
+``flags``
+ Open flags. Access mode must be ``O_RDWR``. This is just a
+ technicality, input devices still support only reading and output
+ devices only writing.
+
+ When the ``O_NONBLOCK`` flag is given, the :ref:`read() <func-read>`
+ function and the :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will
+ return the ``EAGAIN`` error code when no data is available or no
+ buffer is in the driver outgoing queue, otherwise these functions
+ block until data becomes available. All V4L2 drivers exchanging data
+ with applications must support the ``O_NONBLOCK`` flag.
+
+ Other flags have no effect.
+
+
+Description
+===========
+
+To open a V4L2 device applications call :ref:`open() <func-open>` with the
+desired device name. This function has no side effects; all data format
+parameters, current input or output, control values or other properties
+remain unchanged. At the first :ref:`open() <func-open>` call after loading the
+driver they will be reset to default values, drivers are never in an
+undefined state.
+
+
+Return Value
+============
+
+On success :ref:`open() <func-open>` returns the new file descriptor. On error
+-1 is returned, and the ``errno`` variable is set appropriately.
+Possible error codes are:
+
+EACCES
+ The caller has no permission to access the device.
+
+EBUSY
+ The driver does not support multiple opens and the device is already
+ in use.
+
+ENXIO
+ No device corresponding to this device special file exists.
+
+ENOMEM
+ Not enough kernel memory was available to complete the request.
+
+EMFILE
+ The process already has the maximum number of files open.
+
+ENFILE
+ The limit on the total number of files open on the system has been
+ reached.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _func-poll:
+
+***********
+V4L2 poll()
+***********
+
+Name
+====
+
+v4l2-poll - Wait for some event on a file descriptor
+
+
+Synopsis
+========
+
+.. code-block:: c
+
+ #include <sys/poll.h>
+
+
+.. cpp:function:: int poll( struct pollfd *ufds, unsigned int nfds, int timeout )
+
+
+Arguments
+=========
+
+
+
+Description
+===========
+
+With the :ref:`poll() <func-poll>` function applications can suspend execution
+until the driver has captured data or is ready to accept data for
+output.
+
+When streaming I/O has been negotiated this function waits until a
+buffer has been filled by the capture device and can be dequeued with
+the :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. For output devices this
+function waits until the device is ready to accept a new buffer to be
+queued up with the :ref:`VIDIOC_QBUF` ioctl for
+display. When buffers are already in the outgoing queue of the driver
+(capture) or the incoming queue isn't full (display) the function
+returns immediately.
+
+On success :ref:`poll() <func-poll>` returns the number of file descriptors
+that have been selected (that is, file descriptors for which the
+``revents`` field of the respective :c:func:`struct pollfd` structure
+is non-zero). Capture devices set the ``POLLIN`` and ``POLLRDNORM``
+flags in the ``revents`` field, output devices the ``POLLOUT`` and
+``POLLWRNORM`` flags. When the function timed out it returns a value of
+zero, on failure it returns -1 and the ``errno`` variable is set
+appropriately. When the application did not call
+:ref:`VIDIOC_STREAMON` the :ref:`poll() <func-poll>`
+function succeeds, but sets the ``POLLERR`` flag in the ``revents``
+field. When the application has called
+:ref:`VIDIOC_STREAMON` for a capture device but
+hasn't yet called :ref:`VIDIOC_QBUF`, the
+:ref:`poll() <func-poll>` function succeeds and sets the ``POLLERR`` flag in
+the ``revents`` field. For output devices this same situation will cause
+:ref:`poll() <func-poll>` to succeed as well, but it sets the ``POLLOUT`` and
+``POLLWRNORM`` flags in the ``revents`` field.
+
+If an event occurred (see :ref:`VIDIOC_DQEVENT`)
+then ``POLLPRI`` will be set in the ``revents`` field and
+:ref:`poll() <func-poll>` will return.
+
+When use of the :ref:`read() <func-read>` function has been negotiated and the
+driver does not capture yet, the :ref:`poll() <func-poll>` function starts
+capturing. When that fails it returns a ``POLLERR`` as above. Otherwise
+it waits until data has been captured and can be read. When the driver
+captures continuously (as opposed to, for example, still images) the
+function may return immediately.
+
+When use of the :ref:`write() <func-write>` function has been negotiated and the
+driver does not stream yet, the :ref:`poll() <func-poll>` function starts
+streaming. When that fails it returns a ``POLLERR`` as above. Otherwise
+it waits until the driver is ready for a non-blocking
+:ref:`write() <func-write>` call.
+
+If the caller is only interested in events (just ``POLLPRI`` is set in
+the ``events`` field), then :ref:`poll() <func-poll>` will *not* start
+streaming if the driver does not stream yet. This makes it possible to
+just poll for events and not for buffers.
+
+All drivers implementing the :ref:`read() <func-read>` or :ref:`write() <func-write>`
+function or streaming I/O must also support the :ref:`poll() <func-poll>`
+function.
+
+For more details see the :ref:`poll() <func-poll>` manual page.
+
+
+Return Value
+============
+
+On success, :ref:`poll() <func-poll>` returns the number structures which have
+non-zero ``revents`` fields, or zero if the call timed out. On error -1
+is returned, and the ``errno`` variable is set appropriately:
+
+EBADF
+ One or more of the ``ufds`` members specify an invalid file
+ descriptor.
+
+EBUSY
+ The driver does not support multiple read or write streams and the
+ device is already in use.
+
+EFAULT
+ ``ufds`` references an inaccessible memory area.
+
+EINTR
+ The call was interrupted by a signal.
+
+EINVAL
+ The ``nfds`` argument is greater than ``OPEN_MAX``.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _func-read:
+
+***********
+V4L2 read()
+***********
+
+Name
+====
+
+v4l2-read - Read from a V4L2 device
+
+
+Synopsis
+========
+
+.. code-block:: c
+
+ #include <unistd.h>
+
+
+.. cpp:function:: ssize_t read( int fd, void *buf, size_t count )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``buf``
+``count``
+
+
+Description
+===========
+
+:ref:`read() <func-read>` attempts to read up to ``count`` bytes from file
+descriptor ``fd`` into the buffer starting at ``buf``. The layout of the
+data in the buffer is discussed in the respective device interface
+section, see ##. If ``count`` is zero, :ref:`read() <func-read>` returns zero
+and has no other results. If ``count`` is greater than ``SSIZE_MAX``,
+the result is unspecified. Regardless of the ``count`` value each
+:ref:`read() <func-read>` call will provide at most one frame (two fields)
+worth of data.
+
+By default :ref:`read() <func-read>` blocks until data becomes available. When
+the ``O_NONBLOCK`` flag was given to the :ref:`open() <func-open>`
+function it returns immediately with an ``EAGAIN`` error code when no data
+is available. The :ref:`select() <func-select>` or
+:ref:`poll() <func-poll>` functions can always be used to suspend
+execution until data becomes available. All drivers supporting the
+:ref:`read() <func-read>` function must also support :ref:`select() <func-select>` and
+:ref:`poll() <func-poll>`.
+
+Drivers can implement read functionality in different ways, using a
+single or multiple buffers and discarding the oldest or newest frames
+once the internal buffers are filled.
+
+:ref:`read() <func-read>` never returns a "snapshot" of a buffer being filled.
+Using a single buffer the driver will stop capturing when the
+application starts reading the buffer until the read is finished. Thus
+only the period of the vertical blanking interval is available for
+reading, or the capture rate must fall below the nominal frame rate of
+the video standard.
+
+The behavior of :ref:`read() <func-read>` when called during the active picture
+period or the vertical blanking separating the top and bottom field
+depends on the discarding policy. A driver discarding the oldest frames
+keeps capturing into an internal buffer, continuously overwriting the
+previously, not read frame, and returns the frame being received at the
+time of the :ref:`read() <func-read>` call as soon as it is complete.
+
+A driver discarding the newest frames stops capturing until the next
+:ref:`read() <func-read>` call. The frame being received at :ref:`read() <func-read>`
+time is discarded, returning the following frame instead. Again this
+implies a reduction of the capture rate to one half or less of the
+nominal frame rate. An example of this model is the video read mode of
+the bttv driver, initiating a DMA to user memory when :ref:`read() <func-read>`
+is called and returning when the DMA finished.
+
+In the multiple buffer model drivers maintain a ring of internal
+buffers, automatically advancing to the next free buffer. This allows
+continuous capturing when the application can empty the buffers fast
+enough. Again, the behavior when the driver runs out of free buffers
+depends on the discarding policy.
+
+Applications can get and set the number of buffers used internally by
+the driver with the :ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and
+:ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` ioctls. They are optional,
+however. The discarding policy is not reported and cannot be changed.
+For minimum requirements see :ref:`devices`.
+
+
+Return Value
+============
+
+On success, the number of bytes read is returned. It is not an error if
+this number is smaller than the number of bytes requested, or the amount
+of data required for one frame. This may happen for example because
+:ref:`read() <func-read>` was interrupted by a signal. On error, -1 is
+returned, and the ``errno`` variable is set appropriately. In this case
+the next read will start at the beginning of a new frame. Possible error
+codes are:
+
+EAGAIN
+ Non-blocking I/O has been selected using O_NONBLOCK and no data was
+ immediately available for reading.
+
+EBADF
+ ``fd`` is not a valid file descriptor or is not open for reading, or
+ the process already has the maximum number of files open.
+
+EBUSY
+ The driver does not support multiple read streams and the device is
+ already in use.
+
+EFAULT
+ ``buf`` references an inaccessible memory area.
+
+EINTR
+ The call was interrupted by a signal before any data was read.
+
+EIO
+ I/O error. This indicates some hardware problem or a failure to
+ communicate with a remote device (USB camera etc.).
+
+EINVAL
+ The :ref:`read() <func-read>` function is not supported by this driver, not
+ on this device, or generally not on this type of device.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _func-select:
+
+*************
+V4L2 select()
+*************
+
+Name
+====
+
+v4l2-select - Synchronous I/O multiplexing
+
+
+Synopsis
+========
+
+.. code-block:: c
+
+ #include <sys/time.h>
+ #include <sys/types.h>
+ #include <unistd.h>
+
+
+.. cpp:function:: int select( int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout )
+
+
+Arguments
+=========
+
+
+
+Description
+===========
+
+With the :ref:`select() <func-select>` function applications can suspend
+execution until the driver has captured data or is ready to accept data
+for output.
+
+When streaming I/O has been negotiated this function waits until a
+buffer has been filled or displayed and can be dequeued with the
+:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. When buffers are already in
+the outgoing queue of the driver the function returns immediately.
+
+On success :ref:`select() <func-select>` returns the total number of bits set in
+:c:func:`struct fd_set`. When the function timed out it returns
+a value of zero. On failure it returns -1 and the ``errno`` variable is
+set appropriately. When the application did not call
+:ref:`VIDIOC_QBUF` or
+:ref:`VIDIOC_STREAMON` yet the :ref:`select() <func-select>`
+function succeeds, setting the bit of the file descriptor in ``readfds``
+or ``writefds``, but subsequent :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`
+calls will fail. [1]_
+
+When use of the :ref:`read() <func-read>` function has been negotiated and the
+driver does not capture yet, the :ref:`select() <func-select>` function starts
+capturing. When that fails, :ref:`select() <func-select>` returns successful and
+a subsequent :ref:`read() <func-read>` call, which also attempts to start
+capturing, will return an appropriate error code. When the driver
+captures continuously (as opposed to, for example, still images) and
+data is already available the :ref:`select() <func-select>` function returns
+immediately.
+
+When use of the :ref:`write() <func-write>` function has been negotiated the
+:ref:`select() <func-select>` function just waits until the driver is ready for a
+non-blocking :ref:`write() <func-write>` call.
+
+All drivers implementing the :ref:`read() <func-read>` or :ref:`write() <func-write>`
+function or streaming I/O must also support the :ref:`select() <func-select>`
+function.
+
+For more details see the :ref:`select() <func-select>` manual page.
+
+
+Return Value
+============
+
+On success, :ref:`select() <func-select>` returns the number of descriptors
+contained in the three returned descriptor sets, which will be zero if
+the timeout expired. On error -1 is returned, and the ``errno`` variable
+is set appropriately; the sets and ``timeout`` are undefined. Possible
+error codes are:
+
+EBADF
+ One or more of the file descriptor sets specified a file descriptor
+ that is not open.
+
+EBUSY
+ The driver does not support multiple read or write streams and the
+ device is already in use.
+
+EFAULT
+ The ``readfds``, ``writefds``, ``exceptfds`` or ``timeout`` pointer
+ references an inaccessible memory area.
+
+EINTR
+ The call was interrupted by a signal.
+
+EINVAL
+ The ``nfds`` argument is less than zero or greater than
+ ``FD_SETSIZE``.
+
+.. [1]
+ The Linux kernel implements :ref:`select() <func-select>` like the
+ :ref:`poll() <func-poll>` function, but :ref:`select() <func-select>` cannot
+ return a ``POLLERR``.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _func-write:
+
+************
+V4L2 write()
+************
+
+Name
+====
+
+v4l2-write - Write to a V4L2 device
+
+
+Synopsis
+========
+
+.. code-block:: c
+
+ #include <unistd.h>
+
+
+.. cpp:function:: ssize_t write( int fd, void *buf, size_t count )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``buf``
+``count``
+
+
+Description
+===========
+
+:ref:`write() <func-write>` writes up to ``count`` bytes to the device
+referenced by the file descriptor ``fd`` from the buffer starting at
+``buf``. When the hardware outputs are not active yet, this function
+enables them. When ``count`` is zero, :ref:`write() <func-write>` returns 0
+without any other effect.
+
+When the application does not provide more data in time, the previous
+video frame, raw VBI image, sliced VPS or WSS data is displayed again.
+Sliced Teletext or Closed Caption data is not repeated, the driver
+inserts a blank line instead.
+
+
+Return Value
+============
+
+On success, the number of bytes written are returned. Zero indicates
+nothing was written. On error, -1 is returned, and the ``errno``
+variable is set appropriately. In this case the next write will start at
+the beginning of a new frame. Possible error codes are:
+
+EAGAIN
+ Non-blocking I/O has been selected using the
+ :ref:`O_NONBLOCK <func-open>` flag and no buffer space was
+ available to write the data immediately.
+
+EBADF
+ ``fd`` is not a valid file descriptor or is not open for writing.
+
+EBUSY
+ The driver does not support multiple write streams and the device is
+ already in use.
+
+EFAULT
+ ``buf`` references an inaccessible memory area.
+
+EINTR
+ The call was interrupted by a signal before any data was written.
+
+EIO
+ I/O error. This indicates some hardware problem.
+
+EINVAL
+ The :ref:`write() <func-write>` function is not supported by this driver,
+ not on this device, or generally not on this type of device.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _hist-v4l2:
+
+***********************
+Changes of the V4L2 API
+***********************
+
+Soon after the V4L API was added to the kernel it was criticised as too
+inflexible. In August 1998 Bill Dirks proposed a number of improvements
+and began to work on documentation, example drivers and applications.
+With the help of other volunteers this eventually became the V4L2 API,
+not just an extension but a replacement for the V4L API. However it took
+another four years and two stable kernel releases until the new API was
+finally accepted for inclusion into the kernel in its present form.
+
+
+Early Versions
+==============
+
+1998-08-20: First version.
+
+1998-08-27: The :ref:`select() <func-select>` function was introduced.
+
+1998-09-10: New video standard interface.
+
+1998-09-18: The ``VIDIOC_NONCAP`` ioctl was replaced by the otherwise
+meaningless ``O_TRUNC`` :ref:`open() <func-open>` flag, and the
+aliases ``O_NONCAP`` and ``O_NOIO`` were defined. Applications can set
+this flag if they intend to access controls only, as opposed to capture
+applications which need exclusive access. The ``VIDEO_STD_XXX``
+identifiers are now ordinals instead of flags, and the
+:c:func:`video_std_construct()` helper function takes id and
+transmission arguments.
+
+1998-09-28: Revamped video standard. Made video controls individually
+enumerable.
+
+1998-10-02: The ``id`` field was removed from struct
+:c:type:`struct video_standard` and the color subcarrier fields were
+renamed. The :ref:`VIDIOC_QUERYSTD` ioctl was
+renamed to :ref:`VIDIOC_ENUMSTD`,
+:ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` to
+:ref:`VIDIOC_ENUMINPUT`. A first draft of the
+Codec API was released.
+
+1998-11-08: Many minor changes. Most symbols have been renamed. Some
+material changes to struct :ref:`v4l2_capability <v4l2-capability>`.
+
+1998-11-12: The read/write directon of some ioctls was misdefined.
+
+1998-11-14: ``V4L2_PIX_FMT_RGB24`` changed to ``V4L2_PIX_FMT_BGR24``,
+and ``V4L2_PIX_FMT_RGB32`` changed to ``V4L2_PIX_FMT_BGR32``. Audio
+controls are now accessible with the
+:ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and
+:ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls under names starting
+with ``V4L2_CID_AUDIO``. The ``V4L2_MAJOR`` define was removed from
+``videodev.h`` since it was only used once in the ``videodev`` kernel
+module. The ``YUV422`` and ``YUV411`` planar image formats were added.
+
+1998-11-28: A few ioctl symbols changed. Interfaces for codecs and video
+output devices were added.
+
+1999-01-14: A raw VBI capture interface was added.
+
+1999-01-19: The ``VIDIOC_NEXTBUF`` ioctl was removed.
+
+
+V4L2 Version 0.16 1999-01-31
+============================
+
+1999-01-27: There is now one QBUF ioctl, VIDIOC_QWBUF and VIDIOC_QRBUF
+are gone. VIDIOC_QBUF takes a v4l2_buffer as a parameter. Added
+digital zoom (cropping) controls.
+
+
+V4L2 Version 0.18 1999-03-16
+============================
+
+Added a v4l to V4L2 ioctl compatibility layer to videodev.c. Driver
+writers, this changes how you implement your ioctl handler. See the
+Driver Writer's Guide. Added some more control id codes.
+
+
+V4L2 Version 0.19 1999-06-05
+============================
+
+1999-03-18: Fill in the category and catname fields of v4l2_queryctrl
+objects before passing them to the driver. Required a minor change to
+the VIDIOC_QUERYCTRL handlers in the sample drivers.
+
+1999-03-31: Better compatibility for v4l memory capture ioctls. Requires
+changes to drivers to fully support new compatibility features, see
+Driver Writer's Guide and v4l2cap.c. Added new control IDs:
+V4L2_CID_HFLIP, _VFLIP. Changed V4L2_PIX_FMT_YUV422P to _YUV422P,
+and _YUV411P to _YUV411P.
+
+1999-04-04: Added a few more control IDs.
+
+1999-04-07: Added the button control type.
+
+1999-05-02: Fixed a typo in videodev.h, and added the
+V4L2_CTRL_FLAG_GRAYED (later V4L2_CTRL_FLAG_GRABBED) flag.
+
+1999-05-20: Definition of VIDIOC_G_CTRL was wrong causing a
+malfunction of this ioctl.
+
+1999-06-05: Changed the value of V4L2_CID_WHITENESS.
+
+
+V4L2 Version 0.20 (1999-09-10)
+==============================
+
+Version 0.20 introduced a number of changes which were *not backward
+compatible* with 0.19 and earlier versions. Purpose of these changes was
+to simplify the API, while making it more extensible and following
+common Linux driver API conventions.
+
+1. Some typos in ``V4L2_FMT_FLAG`` symbols were fixed. struct
+ :ref:`v4l2_clip <v4l2-clip>` was changed for compatibility with
+ v4l. (1999-08-30)
+
+2. ``V4L2_TUNER_SUB_LANG1`` was added. (1999-09-05)
+
+3. All ioctl() commands that used an integer argument now take a pointer
+ to an integer. Where it makes sense, ioctls will return the actual
+ new value in the integer pointed to by the argument, a common
+ convention in the V4L2 API. The affected ioctls are: VIDIOC_PREVIEW,
+ VIDIOC_STREAMON, VIDIOC_STREAMOFF, VIDIOC_S_FREQ,
+ VIDIOC_S_INPUT, VIDIOC_S_OUTPUT, VIDIOC_S_EFFECT. For example
+
+
+ .. code-block:: c
+
+ err = ioctl (fd, VIDIOC_XXX, V4L2_XXX);
+
+ becomes
+
+
+ .. code-block:: c
+
+ int a = V4L2_XXX; err = ioctl(fd, VIDIOC_XXX, &a);
+
+4. All the different get- and set-format commands were swept into one
+ :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
+ :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl taking a union and a
+ type field selecting the union member as parameter. Purpose is to
+ simplify the API by eliminating several ioctls and to allow new and
+ driver private data streams without adding new ioctls.
+
+ This change obsoletes the following ioctls: ``VIDIOC_S_INFMT``,
+ ``VIDIOC_G_INFMT``, ``VIDIOC_S_OUTFMT``, ``VIDIOC_G_OUTFMT``,
+ ``VIDIOC_S_VBIFMT`` and ``VIDIOC_G_VBIFMT``. The image format
+ structure :c:type:`struct v4l2_format` was renamed to struct
+ :ref:`v4l2_pix_format <v4l2-pix-format>`, while struct
+ :ref:`v4l2_format <v4l2-format>` is now the envelopping structure
+ for all format negotiations.
+
+5. Similar to the changes above, the ``VIDIOC_G_PARM`` and
+ ``VIDIOC_S_PARM`` ioctls were merged with ``VIDIOC_G_OUTPARM`` and
+ ``VIDIOC_S_OUTPARM``. A ``type`` field in the new struct
+ :ref:`v4l2_streamparm <v4l2-streamparm>` selects the respective
+ union member.
+
+ This change obsoletes the ``VIDIOC_G_OUTPARM`` and
+ ``VIDIOC_S_OUTPARM`` ioctls.
+
+6. Control enumeration was simplified, and two new control flags were
+ introduced and one dropped. The ``catname`` field was replaced by a
+ ``group`` field.
+
+ Drivers can now flag unsupported and temporarily unavailable controls
+ with ``V4L2_CTRL_FLAG_DISABLED`` and ``V4L2_CTRL_FLAG_GRABBED``
+ respectively. The ``group`` name indicates a possibly narrower
+ classification than the ``category``. In other words, there may be
+ multiple groups within a category. Controls within a group would
+ typically be drawn within a group box. Controls in different
+ categories might have a greater separation, or may even appear in
+ separate windows.
+
+7. The struct :ref:`v4l2_buffer <v4l2-buffer>` ``timestamp`` was
+ changed to a 64 bit integer, containing the sampling or output time
+ of the frame in nanoseconds. Additionally timestamps will be in
+ absolute system time, not starting from zero at the beginning of a
+ stream. The data type name for timestamps is stamp_t, defined as a
+ signed 64-bit integer. Output devices should not send a buffer out
+ until the time in the timestamp field has arrived. I would like to
+ follow SGI's lead, and adopt a multimedia timestamping system like
+ their UST (Unadjusted System Time). See
+ http://web.archive.org/web/\*/http://reality.sgi.com
+ /cpirazzi_engr/lg/time/intro.html. UST uses timestamps that are
+ 64-bit signed integers (not struct timeval's) and given in nanosecond
+ units. The UST clock starts at zero when the system is booted and
+ runs continuously and uniformly. It takes a little over 292 years for
+ UST to overflow. There is no way to set the UST clock. The regular
+ Linux time-of-day clock can be changed periodically, which would
+ cause errors if it were being used for timestamping a multimedia
+ stream. A real UST style clock will require some support in the
+ kernel that is not there yet. But in anticipation, I will change the
+ timestamp field to a 64-bit integer, and I will change the
+ v4l2_masterclock_gettime() function (used only by drivers) to
+ return a 64-bit integer.
+
+8. A ``sequence`` field was added to struct
+ :ref:`v4l2_buffer <v4l2-buffer>`. The ``sequence`` field counts
+ captured frames, it is ignored by output devices. When a capture
+ driver drops a frame, the sequence number of that frame is skipped.
+
+
+V4L2 Version 0.20 incremental changes
+=====================================
+
+1999-12-23: In struct :ref:`v4l2_vbi_format <v4l2-vbi-format>` the
+``reserved1`` field became ``offset``. Previously drivers were required
+to clear the ``reserved1`` field.
+
+2000-01-13: The ``V4L2_FMT_FLAG_NOT_INTERLACED`` flag was added.
+
+2000-07-31: The ``linux/poll.h`` header is now included by
+``videodev.h`` for compatibility with the original ``videodev.h`` file.
+
+2000-11-20: ``V4L2_TYPE_VBI_OUTPUT`` and ``V4L2_PIX_FMT_Y41P`` were
+added.
+
+2000-11-25: ``V4L2_TYPE_VBI_INPUT`` was added.
+
+2000-12-04: A couple typos in symbol names were fixed.
+
+2001-01-18: To avoid namespace conflicts the ``fourcc`` macro defined in
+the ``videodev.h`` header file was renamed to ``v4l2_fourcc``.
+
+2001-01-25: A possible driver-level compatibility problem between the
+``videodev.h`` file in Linux 2.4.0 and the ``videodev.h`` file included
+in the ``videodevX`` patch was fixed. Users of an earlier version of
+``videodevX`` on Linux 2.4.0 should recompile their V4L and V4L2
+drivers.
+
+2001-01-26: A possible kernel-level incompatibility between the
+``videodev.h`` file in the ``videodevX`` patch and the ``videodev.h``
+file in Linux 2.2.x with devfs patches applied was fixed.
+
+2001-03-02: Certain V4L ioctls which pass data in both direction
+although they are defined with read-only parameter, did not work
+correctly through the backward compatibility layer. [Solution?]
+
+2001-04-13: Big endian 16-bit RGB formats were added.
+
+2001-09-17: New YUV formats and the
+:ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` and
+:ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctls were added.
+(The old ``VIDIOC_G_FREQ`` and ``VIDIOC_S_FREQ`` ioctls did not take
+multiple tuners into account.)
+
+2000-09-18: ``V4L2_BUF_TYPE_VBI`` was added. This may *break
+compatibility* as the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
+:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls may fail now if the struct
+:c:type:`struct v4l2_fmt` ``type`` field does not contain
+``V4L2_BUF_TYPE_VBI``. In the documentation of the struct
+:ref:`v4l2_vbi_format <v4l2-vbi-format>` ``offset`` field the
+ambiguous phrase "rising edge" was changed to "leading edge".
+
+
+V4L2 Version 0.20 2000-11-23
+============================
+
+A number of changes were made to the raw VBI interface.
+
+1. Figures clarifying the line numbering scheme were added to the V4L2
+ API specification. The ``start``\ [0] and ``start``\ [1] fields no
+ longer count line numbers beginning at zero. Rationale: a) The
+ previous definition was unclear. b) The ``start``\ [] values are
+ ordinal numbers. c) There is no point in inventing a new line
+ numbering scheme. We now use line number as defined by ITU-R, period.
+ Compatibility: Add one to the start values. Applications depending on
+ the previous semantics may not function correctly.
+
+2. The restriction "count[0] > 0 and count[1] > 0" has been relaxed to
+ "(count[0] + count[1]) > 0". Rationale: Drivers may allocate
+ resources at scan line granularity and some data services are
+ transmitted only on the first field. The comment that both ``count``
+ values will usually be equal is misleading and pointless and has been
+ removed. This change *breaks compatibility* with earlier versions:
+ Drivers may return ``EINVAL``, applications may not function correctly.
+
+3. Drivers are again permitted to return negative (unknown) start values
+ as proposed earlier. Why this feature was dropped is unclear. This
+ change may *break compatibility* with applications depending on the
+ start values being positive. The use of ``EBUSY`` and ``EINVAL``
+ error codes with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl was
+ clarified. The ``EBUSY`` error code was finally documented, and the
+ ``reserved2`` field which was previously mentioned only in the
+ ``videodev.h`` header file.
+
+4. New buffer types ``V4L2_TYPE_VBI_INPUT`` and ``V4L2_TYPE_VBI_OUTPUT``
+ were added. The former is an alias for the old ``V4L2_TYPE_VBI``, the
+ latter was missing in the ``videodev.h`` file.
+
+
+V4L2 Version 0.20 2002-07-25
+============================
+
+Added sliced VBI interface proposal.
+
+
+V4L2 in Linux 2.5.46, 2002-10
+=============================
+
+Around October-November 2002, prior to an announced feature freeze of
+Linux 2.5, the API was revised, drawing from experience with V4L2 0.20.
+This unnamed version was finally merged into Linux 2.5.46.
+
+1. As specified in :ref:`related`, drivers must make related device
+ functions available under all minor device numbers.
+
+2. The :ref:`open() <func-open>` function requires access mode
+ ``O_RDWR`` regardless of the device type. All V4L2 drivers
+ exchanging data with applications must support the ``O_NONBLOCK``
+ flag. The ``O_NOIO`` flag, a V4L2 symbol which aliased the
+ meaningless ``O_TRUNC`` to indicate accesses without data exchange
+ (panel applications) was dropped. Drivers must stay in "panel mode"
+ until the application attempts to initiate a data exchange, see
+ :ref:`open`.
+
+3. The struct :ref:`v4l2_capability <v4l2-capability>` changed
+ dramatically. Note that also the size of the structure changed,
+ which is encoded in the ioctl request code, thus older V4L2 devices
+ will respond with an ``EINVAL`` error code to the new
+ :ref:`VIDIOC_QUERYCAP` ioctl.
+
+ There are new fields to identify the driver, a new RDS device
+ function ``V4L2_CAP_RDS_CAPTURE``, the ``V4L2_CAP_AUDIO`` flag
+ indicates if the device has any audio connectors, another I/O
+ capability ``V4L2_CAP_ASYNCIO`` can be flagged. In response to these
+ changes the ``type`` field became a bit set and was merged into the
+ ``flags`` field. ``V4L2_FLAG_TUNER`` was renamed to
+ ``V4L2_CAP_TUNER``, ``V4L2_CAP_VIDEO_OVERLAY`` replaced
+ ``V4L2_FLAG_PREVIEW`` and ``V4L2_CAP_VBI_CAPTURE`` and
+ ``V4L2_CAP_VBI_OUTPUT`` replaced ``V4L2_FLAG_DATA_SERVICE``.
+ ``V4L2_FLAG_READ`` and ``V4L2_FLAG_WRITE`` were merged into
+ ``V4L2_CAP_READWRITE``.
+
+ The redundant fields ``inputs``, ``outputs`` and ``audios`` were
+ removed. These properties can be determined as described in
+ :ref:`video` and :ref:`audio`.
+
+ The somewhat volatile and therefore barely useful fields
+ ``maxwidth``, ``maxheight``, ``minwidth``, ``minheight``,
+ ``maxframerate`` were removed. This information is available as
+ described in :ref:`format` and :ref:`standard`.
+
+ ``V4L2_FLAG_SELECT`` was removed. We believe the select() function
+ is important enough to require support of it in all V4L2 drivers
+ exchanging data with applications. The redundant
+ ``V4L2_FLAG_MONOCHROME`` flag was removed, this information is
+ available as described in :ref:`format`.
+
+4. In struct :ref:`v4l2_input <v4l2-input>` the ``assoc_audio``
+ field and the ``capability`` field and its only flag
+ ``V4L2_INPUT_CAP_AUDIO`` was replaced by the new ``audioset`` field.
+ Instead of linking one video input to one audio input this field
+ reports all audio inputs this video input combines with.
+
+ New fields are ``tuner`` (reversing the former link from tuners to
+ video inputs), ``std`` and ``status``.
+
+ Accordingly struct :ref:`v4l2_output <v4l2-output>` lost its
+ ``capability`` and ``assoc_audio`` fields. ``audioset``,
+ ``modulator`` and ``std`` where added instead.
+
+5. The struct :ref:`v4l2_audio <v4l2-audio>` field ``audio`` was
+ renamed to ``index``, for consistency with other structures. A new
+ capability flag ``V4L2_AUDCAP_STEREO`` was added to indicated if the
+ audio input in question supports stereo sound.
+ ``V4L2_AUDCAP_EFFECTS`` and the corresponding ``V4L2_AUDMODE`` flags
+ where removed. This can be easily implemented using controls.
+ (However the same applies to AVL which is still there.)
+
+ Again for consistency the struct
+ :ref:`v4l2_audioout <v4l2-audioout>` field ``audio`` was renamed
+ to ``index``.
+
+6. The struct :ref:`v4l2_tuner <v4l2-tuner>` ``input`` field was
+ replaced by an ``index`` field, permitting devices with multiple
+ tuners. The link between video inputs and tuners is now reversed,
+ inputs point to their tuner. The ``std`` substructure became a
+ simple set (more about this below) and moved into struct
+ :ref:`v4l2_input <v4l2-input>`. A ``type`` field was added.
+
+ Accordingly in struct :ref:`v4l2_modulator <v4l2-modulator>` the
+ ``output`` was replaced by an ``index`` field.
+
+ In struct :ref:`v4l2_frequency <v4l2-frequency>` the ``port``
+ field was replaced by a ``tuner`` field containing the respective
+ tuner or modulator index number. A tuner ``type`` field was added
+ and the ``reserved`` field became larger for future extensions
+ (satellite tuners in particular).
+
+7. The idea of completely transparent video standards was dropped.
+ Experience showed that applications must be able to work with video
+ standards beyond presenting the user a menu. Instead of enumerating
+ supported standards with an ioctl applications can now refer to
+ standards by :ref:`v4l2_std_id <v4l2-std-id>` and symbols
+ defined in the ``videodev2.h`` header file. For details see
+ :ref:`standard`. The :ref:`VIDIOC_G_STD <VIDIOC_G_STD>` and
+ :ref:`VIDIOC_S_STD <VIDIOC_G_STD>` now take a pointer to this
+ type as argument. :ref:`VIDIOC_QUERYSTD` was
+ added to autodetect the received standard, if the hardware has this
+ capability. In struct :ref:`v4l2_standard <v4l2-standard>` an
+ ``index`` field was added for
+ :ref:`VIDIOC_ENUMSTD`. A
+ :ref:`v4l2_std_id <v4l2-std-id>` field named ``id`` was added as
+ machine readable identifier, also replacing the ``transmission``
+ field. The misleading ``framerate`` field was renamed to
+ ``frameperiod``. The now obsolete ``colorstandard`` information,
+ originally needed to distguish between variations of standards, were
+ removed.
+
+ Struct :c:type:`struct v4l2_enumstd` ceased to be.
+ :ref:`VIDIOC_ENUMSTD` now takes a pointer to a
+ struct :ref:`v4l2_standard <v4l2-standard>` directly. The
+ information which standards are supported by a particular video
+ input or output moved into struct :ref:`v4l2_input <v4l2-input>`
+ and struct :ref:`v4l2_output <v4l2-output>` fields named ``std``,
+ respectively.
+
+8. The struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` fields
+ ``category`` and ``group`` did not catch on and/or were not
+ implemented as expected and therefore removed.
+
+9. The :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl was added to
+ negotiate data formats as with
+ :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`, but without the overhead of
+ programming the hardware and regardless of I/O in progress.
+
+ In struct :ref:`v4l2_format <v4l2-format>` the ``fmt`` union was
+ extended to contain struct :ref:`v4l2_window <v4l2-window>`. All
+ image format negotiations are now possible with ``VIDIOC_G_FMT``,
+ ``VIDIOC_S_FMT`` and ``VIDIOC_TRY_FMT``; ioctl. The ``VIDIOC_G_WIN``
+ and ``VIDIOC_S_WIN`` ioctls to prepare for a video overlay were
+ removed. The ``type`` field changed to type enum
+ :ref:`v4l2_buf_type <v4l2-buf-type>` and the buffer type names
+ changed as follows.
+
+
+
+ .. flat-table::
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Old defines
+
+ - enum :ref:`v4l2_buf_type <v4l2-buf-type>`
+
+ - .. row 2
+
+ - ``V4L2_BUF_TYPE_CAPTURE``
+
+ - ``V4L2_BUF_TYPE_VIDEO_CAPTURE``
+
+ - .. row 3
+
+ - ``V4L2_BUF_TYPE_CODECIN``
+
+ - Omitted for now
+
+ - .. row 4
+
+ - ``V4L2_BUF_TYPE_CODECOUT``
+
+ - Omitted for now
+
+ - .. row 5
+
+ - ``V4L2_BUF_TYPE_EFFECTSIN``
+
+ - Omitted for now
+
+ - .. row 6
+
+ - ``V4L2_BUF_TYPE_EFFECTSIN2``
+
+ - Omitted for now
+
+ - .. row 7
+
+ - ``V4L2_BUF_TYPE_EFFECTSOUT``
+
+ - Omitted for now
+
+ - .. row 8
+
+ - ``V4L2_BUF_TYPE_VIDEOOUT``
+
+ - ``V4L2_BUF_TYPE_VIDEO_OUTPUT``
+
+ - .. row 9
+
+ - ``-``
+
+ - ``V4L2_BUF_TYPE_VIDEO_OVERLAY``
+
+ - .. row 10
+
+ - ``-``
+
+ - ``V4L2_BUF_TYPE_VBI_CAPTURE``
+
+ - .. row 11
+
+ - ``-``
+
+ - ``V4L2_BUF_TYPE_VBI_OUTPUT``
+
+ - .. row 12
+
+ - ``-``
+
+ - ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE``
+
+ - .. row 13
+
+ - ``-``
+
+ - ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT``
+
+ - .. row 14
+
+ - ``V4L2_BUF_TYPE_PRIVATE_BASE``
+
+ - ``V4L2_BUF_TYPE_PRIVATE`` (but this is deprecated)
+
+
+10. In struct :ref:`v4l2_fmtdesc <v4l2-fmtdesc>` a enum
+ :ref:`v4l2_buf_type <v4l2-buf-type>` field named ``type`` was
+ added as in struct :ref:`v4l2_format <v4l2-format>`. The
+ ``VIDIOC_ENUM_FBUFFMT`` ioctl is no longer needed and was removed.
+ These calls can be replaced by
+ :ref:`VIDIOC_ENUM_FMT` with type
+ ``V4L2_BUF_TYPE_VIDEO_OVERLAY``.
+
+11. In struct :ref:`v4l2_pix_format <v4l2-pix-format>` the ``depth``
+ field was removed, assuming applications which recognize the format
+ by its four-character-code already know the color depth, and others
+ do not care about it. The same rationale lead to the removal of the
+ ``V4L2_FMT_FLAG_COMPRESSED`` flag. The
+ ``V4L2_FMT_FLAG_SWCONVECOMPRESSED`` flag was removed because drivers
+ are not supposed to convert images in kernel space. A user library
+ of conversion functions should be provided instead. The
+ ``V4L2_FMT_FLAG_BYTESPERLINE`` flag was redundant. Applications can
+ set the ``bytesperline`` field to zero to get a reasonable default.
+ Since the remaining flags were replaced as well, the ``flags`` field
+ itself was removed.
+
+ The interlace flags were replaced by a enum
+ :ref:`v4l2_field <v4l2-field>` value in a newly added ``field``
+ field.
+
+
+
+ .. flat-table::
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Old flag
+
+ - enum :ref:`v4l2_field <v4l2-field>`
+
+ - .. row 2
+
+ - ``V4L2_FMT_FLAG_NOT_INTERLACED``
+
+ - ?
+
+ - .. row 3
+
+ - ``V4L2_FMT_FLAG_INTERLACED`` = ``V4L2_FMT_FLAG_COMBINED``
+
+ - ``V4L2_FIELD_INTERLACED``
+
+ - .. row 4
+
+ - ``V4L2_FMT_FLAG_TOPFIELD`` = ``V4L2_FMT_FLAG_ODDFIELD``
+
+ - ``V4L2_FIELD_TOP``
+
+ - .. row 5
+
+ - ``V4L2_FMT_FLAG_BOTFIELD`` = ``V4L2_FMT_FLAG_EVENFIELD``
+
+ - ``V4L2_FIELD_BOTTOM``
+
+ - .. row 6
+
+ - ``-``
+
+ - ``V4L2_FIELD_SEQ_TB``
+
+ - .. row 7
+
+ - ``-``
+
+ - ``V4L2_FIELD_SEQ_BT``
+
+ - .. row 8
+
+ - ``-``
+
+ - ``V4L2_FIELD_ALTERNATE``
+
+
+ The color space flags were replaced by a enum
+ :ref:`v4l2_colorspace <v4l2-colorspace>` value in a newly added
+ ``colorspace`` field, where one of ``V4L2_COLORSPACE_SMPTE170M``,
+ ``V4L2_COLORSPACE_BT878``, ``V4L2_COLORSPACE_470_SYSTEM_M`` or
+ ``V4L2_COLORSPACE_470_SYSTEM_BG`` replaces ``V4L2_FMT_CS_601YUV``.
+
+12. In struct :ref:`v4l2_requestbuffers <v4l2-requestbuffers>` the
+ ``type`` field was properly defined as enum
+ :ref:`v4l2_buf_type <v4l2-buf-type>`. Buffer types changed as
+ mentioned above. A new ``memory`` field of type enum
+ :ref:`v4l2_memory <v4l2-memory>` was added to distinguish between
+ I/O methods using buffers allocated by the driver or the
+ application. See :ref:`io` for details.
+
+13. In struct :ref:`v4l2_buffer <v4l2-buffer>` the ``type`` field was
+ properly defined as enum :ref:`v4l2_buf_type <v4l2-buf-type>`.
+ Buffer types changed as mentioned above. A ``field`` field of type
+ enum :ref:`v4l2_field <v4l2-field>` was added to indicate if a
+ buffer contains a top or bottom field. The old field flags were
+ removed. Since no unadjusted system time clock was added to the
+ kernel as planned, the ``timestamp`` field changed back from type
+ stamp_t, an unsigned 64 bit integer expressing the sample time in
+ nanoseconds, to struct :c:type:`struct timeval`. With the addition
+ of a second memory mapping method the ``offset`` field moved into
+ union ``m``, and a new ``memory`` field of type enum
+ :ref:`v4l2_memory <v4l2-memory>` was added to distinguish between
+ I/O methods. See :ref:`io` for details.
+
+ The ``V4L2_BUF_REQ_CONTIG`` flag was used by the V4L compatibility
+ layer, after changes to this code it was no longer needed. The
+ ``V4L2_BUF_ATTR_DEVICEMEM`` flag would indicate if the buffer was
+ indeed allocated in device memory rather than DMA-able system
+ memory. It was barely useful and so was removed.
+
+14. In struct :ref:`v4l2_framebuffer <v4l2-framebuffer>` the
+ ``base[3]`` array anticipating double- and triple-buffering in
+ off-screen video memory, however without defining a synchronization
+ mechanism, was replaced by a single pointer. The
+ ``V4L2_FBUF_CAP_SCALEUP`` and ``V4L2_FBUF_CAP_SCALEDOWN`` flags were
+ removed. Applications can determine this capability more accurately
+ using the new cropping and scaling interface. The
+ ``V4L2_FBUF_CAP_CLIPPING`` flag was replaced by
+ ``V4L2_FBUF_CAP_LIST_CLIPPING`` and
+ ``V4L2_FBUF_CAP_BITMAP_CLIPPING``.
+
+15. In struct :ref:`v4l2_clip <v4l2-clip>` the ``x``, ``y``,
+ ``width`` and ``height`` field moved into a ``c`` substructure of
+ type struct :ref:`v4l2_rect <v4l2-rect>`. The ``x`` and ``y``
+ fields were renamed to ``left`` and ``top``, i. e. offsets to a
+ context dependent origin.
+
+16. In struct :ref:`v4l2_window <v4l2-window>` the ``x``, ``y``,
+ ``width`` and ``height`` field moved into a ``w`` substructure as
+ above. A ``field`` field of type %v4l2-field; was added to
+ distinguish between field and frame (interlaced) overlay.
+
+17. The digital zoom interface, including struct
+ :c:type:`struct v4l2_zoomcap`, struct
+ :c:type:`struct v4l2_zoom`, ``V4L2_ZOOM_NONCAP`` and
+ ``V4L2_ZOOM_WHILESTREAMING`` was replaced by a new cropping and
+ scaling interface. The previously unused struct
+ :c:type:`struct v4l2_cropcap` and :c:type:`struct v4l2_crop`
+ where redefined for this purpose. See :ref:`crop` for details.
+
+18. In struct :ref:`v4l2_vbi_format <v4l2-vbi-format>` the
+ ``SAMPLE_FORMAT`` field now contains a four-character-code as used
+ to identify video image formats and ``V4L2_PIX_FMT_GREY`` replaces
+ the ``V4L2_VBI_SF_UBYTE`` define. The ``reserved`` field was
+ extended.
+
+19. In struct :ref:`v4l2_captureparm <v4l2-captureparm>` the type of
+ the ``timeperframe`` field changed from unsigned long to struct
+ :ref:`v4l2_fract <v4l2-fract>`. This allows the accurate
+ expression of multiples of the NTSC-M frame rate 30000 / 1001. A new
+ field ``readbuffers`` was added to control the driver behaviour in
+ read I/O mode.
+
+ Similar changes were made to struct
+ :ref:`v4l2_outputparm <v4l2-outputparm>`.
+
+20. The struct :c:type:`struct v4l2_performance` and
+ ``VIDIOC_G_PERF`` ioctl were dropped. Except when using the
+ :ref:`read/write I/O method <rw>`, which is limited anyway, this
+ information is already available to applications.
+
+21. The example transformation from RGB to YCbCr color space in the old
+ V4L2 documentation was inaccurate, this has been corrected in
+ :ref:`pixfmt`.
+
+
+V4L2 2003-06-19
+===============
+
+1. A new capability flag ``V4L2_CAP_RADIO`` was added for radio devices.
+ Prior to this change radio devices would identify solely by having
+ exactly one tuner whose type field reads ``V4L2_TUNER_RADIO``.
+
+2. An optional driver access priority mechanism was added, see
+ :ref:`app-pri` for details.
+
+3. The audio input and output interface was found to be incomplete.
+
+ Previously the :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` ioctl would
+ enumerate the available audio inputs. An ioctl to determine the
+ current audio input, if more than one combines with the current video
+ input, did not exist. So ``VIDIOC_G_AUDIO`` was renamed to
+ ``VIDIOC_G_AUDIO_OLD``, this ioctl was removed on Kernel 2.6.39. The
+ :ref:`VIDIOC_ENUMAUDIO` ioctl was added to
+ enumerate audio inputs, while
+ :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` now reports the current
+ audio input.
+
+ The same changes were made to
+ :ref:`VIDIOC_G_AUDOUT <VIDIOC_G_AUDOUT>` and
+ :ref:`VIDIOC_ENUMAUDOUT <VIDIOC_ENUMAUDOUT>`.
+
+ Until further the "videodev" module will automatically translate
+ between the old and new ioctls, but drivers and applications must be
+ updated to successfully compile again.
+
+4. The :ref:`VIDIOC_OVERLAY` ioctl was incorrectly
+ defined with write-read parameter. It was changed to write-only,
+ while the write-read version was renamed to ``VIDIOC_OVERLAY_OLD``.
+ The old ioctl was removed on Kernel 2.6.39. Until further the
+ "videodev" kernel module will automatically translate to the new
+ version, so drivers must be recompiled, but not applications.
+
+5. :ref:`overlay` incorrectly stated that clipping rectangles define
+ regions where the video can be seen. Correct is that clipping
+ rectangles define regions where *no* video shall be displayed and so
+ the graphics surface can be seen.
+
+6. The :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` and
+ :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls were defined with
+ write-only parameter, inconsistent with other ioctls modifying their
+ argument. They were changed to write-read, while a ``_OLD`` suffix
+ was added to the write-only versions. The old ioctls were removed on
+ Kernel 2.6.39. Drivers and applications assuming a constant parameter
+ need an update.
+
+
+V4L2 2003-11-05
+===============
+
+1. In :ref:`pixfmt-rgb` the following pixel formats were incorrectly
+ transferred from Bill Dirks' V4L2 specification. Descriptions below
+ refer to bytes in memory, in ascending address order.
+
+
+
+ .. flat-table::
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Symbol
+
+ - In this document prior to revision 0.5
+
+ - Corrected
+
+ - .. row 2
+
+ - ``V4L2_PIX_FMT_RGB24``
+
+ - B, G, R
+
+ - R, G, B
+
+ - .. row 3
+
+ - ``V4L2_PIX_FMT_BGR24``
+
+ - R, G, B
+
+ - B, G, R
+
+ - .. row 4
+
+ - ``V4L2_PIX_FMT_RGB32``
+
+ - B, G, R, X
+
+ - R, G, B, X
+
+ - .. row 5
+
+ - ``V4L2_PIX_FMT_BGR32``
+
+ - R, G, B, X
+
+ - B, G, R, X
+
+
+ The ``V4L2_PIX_FMT_BGR24`` example was always correct.
+
+ In :ref:`v4l-image-properties` the mapping of the V4L
+ ``VIDEO_PALETTE_RGB24`` and ``VIDEO_PALETTE_RGB32`` formats to V4L2
+ pixel formats was accordingly corrected.
+
+2. Unrelated to the fixes above, drivers may still interpret some V4L2
+ RGB pixel formats differently. These issues have yet to be addressed,
+ for details see :ref:`pixfmt-rgb`.
+
+
+V4L2 in Linux 2.6.6, 2004-05-09
+===============================
+
+1. The :ref:`VIDIOC_CROPCAP` ioctl was incorrectly
+ defined with read-only parameter. It is now defined as write-read
+ ioctl, while the read-only version was renamed to
+ ``VIDIOC_CROPCAP_OLD``. The old ioctl was removed on Kernel 2.6.39.
+
+
+V4L2 in Linux 2.6.8
+===================
+
+1. A new field ``input`` (former ``reserved[0]``) was added to the
+ struct :ref:`v4l2_buffer <v4l2-buffer>` structure. Purpose of this
+ field is to alternate between video inputs (e. g. cameras) in step
+ with the video capturing process. This function must be enabled with
+ the new ``V4L2_BUF_FLAG_INPUT`` flag. The ``flags`` field is no
+ longer read-only.
+
+
+V4L2 spec erratum 2004-08-01
+============================
+
+1. The return value of the :ref:`func-open` function was incorrectly
+ documented.
+
+2. Audio output ioctls end in -AUDOUT, not -AUDIOOUT.
+
+3. In the Current Audio Input example the ``VIDIOC_G_AUDIO`` ioctl took
+ the wrong argument.
+
+4. The documentation of the :ref:`VIDIOC_QBUF` and
+ :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctls did not mention the
+ struct :ref:`v4l2_buffer <v4l2-buffer>` ``memory`` field. It was
+ also missing from examples. Also on the ``VIDIOC_DQBUF`` page the ``EIO``
+ error code was not documented.
+
+
+V4L2 in Linux 2.6.14
+====================
+
+1. A new sliced VBI interface was added. It is documented in
+ :ref:`sliced` and replaces the interface first proposed in V4L2
+ specification 0.8.
+
+
+V4L2 in Linux 2.6.15
+====================
+
+1. The :ref:`VIDIOC_LOG_STATUS` ioctl was added.
+
+2. New video standards ``V4L2_STD_NTSC_443``, ``V4L2_STD_SECAM_LC``,
+ ``V4L2_STD_SECAM_DK`` (a set of SECAM D, K and K1), and
+ ``V4L2_STD_ATSC`` (a set of ``V4L2_STD_ATSC_8_VSB`` and
+ ``V4L2_STD_ATSC_16_VSB``) were defined. Note the ``V4L2_STD_525_60``
+ set now includes ``V4L2_STD_NTSC_443``. See also
+ :ref:`v4l2-std-id`.
+
+3. The ``VIDIOC_G_COMP`` and ``VIDIOC_S_COMP`` ioctl were renamed to
+ ``VIDIOC_G_MPEGCOMP`` and ``VIDIOC_S_MPEGCOMP`` respectively. Their
+ argument was replaced by a struct
+ :c:type:`struct v4l2_mpeg_compression` pointer. (The
+ ``VIDIOC_G_MPEGCOMP`` and ``VIDIOC_S_MPEGCOMP`` ioctls where removed
+ in Linux 2.6.25.)
+
+
+V4L2 spec erratum 2005-11-27
+============================
+
+The capture example in :ref:`capture-example` called the
+:ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` ioctl without checking if
+cropping is supported. In the video standard selection example in
+:ref:`standard` the :ref:`VIDIOC_S_STD <VIDIOC_G_STD>` call used
+the wrong argument type.
+
+
+V4L2 spec erratum 2006-01-10
+============================
+
+1. The ``V4L2_IN_ST_COLOR_KILL`` flag in struct
+ :ref:`v4l2_input <v4l2-input>` not only indicates if the color
+ killer is enabled, but also if it is active. (The color killer
+ disables color decoding when it detects no color in the video signal
+ to improve the image quality.)
+
+2. :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` is a write-read ioctl, not
+ write-only as stated on its reference page. The ioctl changed in 2003
+ as noted above.
+
+
+V4L2 spec erratum 2006-02-03
+============================
+
+1. In struct :ref:`v4l2_captureparm <v4l2-captureparm>` and struct
+ :ref:`v4l2_outputparm <v4l2-outputparm>` the ``timeperframe``
+ field gives the time in seconds, not microseconds.
+
+
+V4L2 spec erratum 2006-02-04
+============================
+
+1. The ``clips`` field in struct :ref:`v4l2_window <v4l2-window>`
+ must point to an array of struct :ref:`v4l2_clip <v4l2-clip>`, not
+ a linked list, because drivers ignore the struct
+ :c:type:`struct v4l2_clip`. ``next`` pointer.
+
+
+V4L2 in Linux 2.6.17
+====================
+
+1. New video standard macros were added: ``V4L2_STD_NTSC_M_KR`` (NTSC M
+ South Korea), and the sets ``V4L2_STD_MN``, ``V4L2_STD_B``,
+ ``V4L2_STD_GH`` and ``V4L2_STD_DK``. The ``V4L2_STD_NTSC`` and
+ ``V4L2_STD_SECAM`` sets now include ``V4L2_STD_NTSC_M_KR`` and
+ ``V4L2_STD_SECAM_LC`` respectively.
+
+2. A new ``V4L2_TUNER_MODE_LANG1_LANG2`` was defined to record both
+ languages of a bilingual program. The use of
+ ``V4L2_TUNER_MODE_STEREO`` for this purpose is deprecated now. See
+ the :ref:`VIDIOC_G_TUNER <VIDIOC_G_TUNER>` section for details.
+
+
+V4L2 spec erratum 2006-09-23 (Draft 0.15)
+=========================================
+
+1. In various places ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE`` and
+ ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT`` of the sliced VBI interface were
+ not mentioned along with other buffer types.
+
+2. In :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` it was clarified that the struct
+ :ref:`v4l2_audio <v4l2-audio>` ``mode`` field is a flags field.
+
+3. :ref:`VIDIOC_QUERYCAP` did not mention the sliced VBI and radio
+ capability flags.
+
+4. In :ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` it was clarified that applications
+ must initialize the tuner ``type`` field of struct
+ :ref:`v4l2_frequency <v4l2-frequency>` before calling
+ :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>`.
+
+5. The ``reserved`` array in struct
+ :ref:`v4l2_requestbuffers <v4l2-requestbuffers>` has 2 elements,
+ not 32.
+
+6. In :ref:`output` and :ref:`raw-vbi` the device file names
+ ``/dev/vout`` which never caught on were replaced by ``/dev/video``.
+
+7. With Linux 2.6.15 the possible range for VBI device minor numbers was
+ extended from 224-239 to 224-255. Accordingly device file names
+ ``/dev/vbi0`` to ``/dev/vbi31`` are possible now.
+
+
+V4L2 in Linux 2.6.18
+====================
+
+1. New ioctls :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`,
+ :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` and
+ :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` were added, a
+ flag to skip unsupported controls with
+ :ref:`VIDIOC_QUERYCTRL`, new control types
+ ``V4L2_CTRL_TYPE_INTEGER64`` and ``V4L2_CTRL_TYPE_CTRL_CLASS``
+ (:ref:`v4l2-ctrl-type`), and new control flags
+ ``V4L2_CTRL_FLAG_READ_ONLY``, ``V4L2_CTRL_FLAG_UPDATE``,
+ ``V4L2_CTRL_FLAG_INACTIVE`` and ``V4L2_CTRL_FLAG_SLIDER``
+ (:ref:`control-flags`). See :ref:`extended-controls` for details.
+
+
+V4L2 in Linux 2.6.19
+====================
+
+1. In struct :ref:`v4l2_sliced_vbi_cap <v4l2-sliced-vbi-cap>` a
+ buffer type field was added replacing a reserved field. Note on
+ architectures where the size of enum types differs from int types the
+ size of the structure changed. The
+ :ref:`VIDIOC_G_SLICED_VBI_CAP <VIDIOC_G_SLICED_VBI_CAP>` ioctl
+ was redefined from being read-only to write-read. Applications must
+ initialize the type field and clear the reserved fields now. These
+ changes may *break the compatibility* with older drivers and
+ applications.
+
+2. The ioctls :ref:`VIDIOC_ENUM_FRAMESIZES`
+ and
+ :ref:`VIDIOC_ENUM_FRAMEINTERVALS`
+ were added.
+
+3. A new pixel format ``V4L2_PIX_FMT_RGB444`` (:ref:`rgb-formats`) was
+ added.
+
+
+V4L2 spec erratum 2006-10-12 (Draft 0.17)
+=========================================
+
+1. ``V4L2_PIX_FMT_HM12`` (:ref:`reserved-formats`) is a YUV 4:2:0, not
+ 4:2:2 format.
+
+
+V4L2 in Linux 2.6.21
+====================
+
+1. The ``videodev2.h`` header file is now dual licensed under GNU
+ General Public License version two or later, and under a 3-clause
+ BSD-style license.
+
+
+V4L2 in Linux 2.6.22
+====================
+
+1. Two new field orders ``V4L2_FIELD_INTERLACED_TB`` and
+ ``V4L2_FIELD_INTERLACED_BT`` were added. See :ref:`v4l2-field` for
+ details.
+
+2. Three new clipping/blending methods with a global or straight or
+ inverted local alpha value were added to the video overlay interface.
+ See the description of the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`
+ and :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctls for details.
+
+ A new ``global_alpha`` field was added to
+ :ref:`v4l2_window <v4l2-window>`, extending the structure. This
+ may *break compatibility* with applications using a struct
+ :c:type:`struct v4l2_window` directly. However the
+ :ref:`VIDIOC_G/S/TRY_FMT <VIDIOC_G_FMT>` ioctls, which take a
+ pointer to a :ref:`v4l2_format <v4l2-format>` parent structure
+ with padding bytes at the end, are not affected.
+
+3. The format of the ``chromakey`` field in struct
+ :ref:`v4l2_window <v4l2-window>` changed from "host order RGB32"
+ to a pixel value in the same format as the framebuffer. This may
+ *break compatibility* with existing applications. Drivers supporting
+ the "host order RGB32" format are not known.
+
+
+V4L2 in Linux 2.6.24
+====================
+
+1. The pixel formats ``V4L2_PIX_FMT_PAL8``, ``V4L2_PIX_FMT_YUV444``,
+ ``V4L2_PIX_FMT_YUV555``, ``V4L2_PIX_FMT_YUV565`` and
+ ``V4L2_PIX_FMT_YUV32`` were added.
+
+
+V4L2 in Linux 2.6.25
+====================
+
+1. The pixel formats :ref:`V4L2_PIX_FMT_Y16 <V4L2-PIX-FMT-Y16>` and
+ :ref:`V4L2_PIX_FMT_SBGGR16 <V4L2-PIX-FMT-SBGGR16>` were added.
+
+2. New :ref:`controls <control>` ``V4L2_CID_POWER_LINE_FREQUENCY``,
+ ``V4L2_CID_HUE_AUTO``, ``V4L2_CID_WHITE_BALANCE_TEMPERATURE``,
+ ``V4L2_CID_SHARPNESS`` and ``V4L2_CID_BACKLIGHT_COMPENSATION`` were
+ added. The controls ``V4L2_CID_BLACK_LEVEL``, ``V4L2_CID_WHITENESS``,
+ ``V4L2_CID_HCENTER`` and ``V4L2_CID_VCENTER`` were deprecated.
+
+3. A :ref:`Camera controls class <camera-controls>` was added, with
+ the new controls ``V4L2_CID_EXPOSURE_AUTO``,
+ ``V4L2_CID_EXPOSURE_ABSOLUTE``, ``V4L2_CID_EXPOSURE_AUTO_PRIORITY``,
+ ``V4L2_CID_PAN_RELATIVE``, ``V4L2_CID_TILT_RELATIVE``,
+ ``V4L2_CID_PAN_RESET``, ``V4L2_CID_TILT_RESET``,
+ ``V4L2_CID_PAN_ABSOLUTE``, ``V4L2_CID_TILT_ABSOLUTE``,
+ ``V4L2_CID_FOCUS_ABSOLUTE``, ``V4L2_CID_FOCUS_RELATIVE`` and
+ ``V4L2_CID_FOCUS_AUTO``.
+
+4. The ``VIDIOC_G_MPEGCOMP`` and ``VIDIOC_S_MPEGCOMP`` ioctls, which
+ were superseded by the :ref:`extended controls <extended-controls>`
+ interface in Linux 2.6.18, where finally removed from the
+ ``videodev2.h`` header file.
+
+
+V4L2 in Linux 2.6.26
+====================
+
+1. The pixel formats ``V4L2_PIX_FMT_Y16`` and ``V4L2_PIX_FMT_SBGGR16``
+ were added.
+
+2. Added user controls ``V4L2_CID_CHROMA_AGC`` and
+ ``V4L2_CID_COLOR_KILLER``.
+
+
+V4L2 in Linux 2.6.27
+====================
+
+1. The :ref:`VIDIOC_S_HW_FREQ_SEEK` ioctl
+ and the ``V4L2_CAP_HW_FREQ_SEEK`` capability were added.
+
+2. The pixel formats ``V4L2_PIX_FMT_YVYU``, ``V4L2_PIX_FMT_PCA501``,
+ ``V4L2_PIX_FMT_PCA505``, ``V4L2_PIX_FMT_PCA508``,
+ ``V4L2_PIX_FMT_PCA561``, ``V4L2_PIX_FMT_SGBRG8``,
+ ``V4L2_PIX_FMT_PAC207`` and ``V4L2_PIX_FMT_PJPG`` were added.
+
+
+V4L2 in Linux 2.6.28
+====================
+
+1. Added ``V4L2_MPEG_AUDIO_ENCODING_AAC`` and
+ ``V4L2_MPEG_AUDIO_ENCODING_AC3`` MPEG audio encodings.
+
+2. Added ``V4L2_MPEG_VIDEO_ENCODING_MPEG_4_AVC`` MPEG video encoding.
+
+3. The pixel formats ``V4L2_PIX_FMT_SGRBG10`` and
+ ``V4L2_PIX_FMT_SGRBG10DPCM8`` were added.
+
+
+V4L2 in Linux 2.6.29
+====================
+
+1. The ``VIDIOC_G_CHIP_IDENT`` ioctl was renamed to
+ ``VIDIOC_G_CHIP_IDENT_OLD`` and ``VIDIOC_DBG_G_CHIP_IDENT`` was
+ introduced in its place. The old struct
+ :c:type:`struct v4l2_chip_ident` was renamed to
+ :c:type:`struct v4l2_chip_ident_old`.
+
+2. The pixel formats ``V4L2_PIX_FMT_VYUY``, ``V4L2_PIX_FMT_NV16`` and
+ ``V4L2_PIX_FMT_NV61`` were added.
+
+3. Added camera controls ``V4L2_CID_ZOOM_ABSOLUTE``,
+ ``V4L2_CID_ZOOM_RELATIVE``, ``V4L2_CID_ZOOM_CONTINUOUS`` and
+ ``V4L2_CID_PRIVACY``.
+
+
+V4L2 in Linux 2.6.30
+====================
+
+1. New control flag ``V4L2_CTRL_FLAG_WRITE_ONLY`` was added.
+
+2. New control ``V4L2_CID_COLORFX`` was added.
+
+
+V4L2 in Linux 2.6.32
+====================
+
+1. In order to be easier to compare a V4L2 API and a kernel version, now
+ V4L2 API is numbered using the Linux Kernel version numeration.
+
+2. Finalized the RDS capture API. See :ref:`rds` for more information.
+
+3. Added new capabilities for modulators and RDS encoders.
+
+4. Add description for libv4l API.
+
+5. Added support for string controls via new type
+ ``V4L2_CTRL_TYPE_STRING``.
+
+6. Added ``V4L2_CID_BAND_STOP_FILTER`` documentation.
+
+7. Added FM Modulator (FM TX) Extended Control Class:
+ ``V4L2_CTRL_CLASS_FM_TX`` and their Control IDs.
+
+8. Added FM Receiver (FM RX) Extended Control Class:
+ ``V4L2_CTRL_CLASS_FM_RX`` and their Control IDs.
+
+9. Added Remote Controller chapter, describing the default Remote
+ Controller mapping for media devices.
+
+
+V4L2 in Linux 2.6.33
+====================
+
+1. Added support for Digital Video timings in order to support HDTV
+ receivers and transmitters.
+
+
+V4L2 in Linux 2.6.34
+====================
+
+1. Added ``V4L2_CID_IRIS_ABSOLUTE`` and ``V4L2_CID_IRIS_RELATIVE``
+ controls to the :ref:`Camera controls class <camera-controls>`.
+
+
+V4L2 in Linux 2.6.37
+====================
+
+1. Remove the vtx (videotext/teletext) API. This API was no longer used
+ and no hardware exists to verify the API. Nor were any userspace
+ applications found that used it. It was originally scheduled for
+ removal in 2.6.35.
+
+
+V4L2 in Linux 2.6.39
+====================
+
+1. The old VIDIOC_*_OLD symbols and V4L1 support were removed.
+
+2. Multi-planar API added. Does not affect the compatibility of current
+ drivers and applications. See :ref:`multi-planar API <planar-apis>`
+ for details.
+
+
+V4L2 in Linux 3.1
+=================
+
+1. VIDIOC_QUERYCAP now returns a per-subsystem version instead of a
+ per-driver one.
+
+ Standardize an error code for invalid ioctl.
+
+ Added V4L2_CTRL_TYPE_BITMASK.
+
+
+V4L2 in Linux 3.2
+=================
+
+1. V4L2_CTRL_FLAG_VOLATILE was added to signal volatile controls to
+ userspace.
+
+2. Add selection API for extended control over cropping and composing.
+ Does not affect the compatibility of current drivers and
+ applications. See :ref:`selection API <selection-api>` for details.
+
+
+V4L2 in Linux 3.3
+=================
+
+1. Added ``V4L2_CID_ALPHA_COMPONENT`` control to the
+ :ref:`User controls class <control>`.
+
+2. Added the device_caps field to struct v4l2_capabilities and added
+ the new V4L2_CAP_DEVICE_CAPS capability.
+
+
+V4L2 in Linux 3.4
+=================
+
+1. Added :ref:`JPEG compression control class <jpeg-controls>`.
+
+2. Extended the DV Timings API:
+ :ref:`VIDIOC_ENUM_DV_TIMINGS`,
+ :ref:`VIDIOC_QUERY_DV_TIMINGS` and
+ :ref:`VIDIOC_DV_TIMINGS_CAP`.
+
+
+V4L2 in Linux 3.5
+=================
+
+1. Added integer menus, the new type will be
+ V4L2_CTRL_TYPE_INTEGER_MENU.
+
+2. Added selection API for V4L2 subdev interface:
+ :ref:`VIDIOC_SUBDEV_G_SELECTION` and
+ :ref:`VIDIOC_SUBDEV_S_SELECTION <VIDIOC_SUBDEV_G_SELECTION>`.
+
+3. Added ``V4L2_COLORFX_ANTIQUE``, ``V4L2_COLORFX_ART_FREEZE``,
+ ``V4L2_COLORFX_AQUA``, ``V4L2_COLORFX_SILHOUETTE``,
+ ``V4L2_COLORFX_SOLARIZATION``, ``V4L2_COLORFX_VIVID`` and
+ ``V4L2_COLORFX_ARBITRARY_CBCR`` menu items to the
+ ``V4L2_CID_COLORFX`` control.
+
+4. Added ``V4L2_CID_COLORFX_CBCR`` control.
+
+5. Added camera controls ``V4L2_CID_AUTO_EXPOSURE_BIAS``,
+ ``V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE``,
+ ``V4L2_CID_IMAGE_STABILIZATION``, ``V4L2_CID_ISO_SENSITIVITY``,
+ ``V4L2_CID_ISO_SENSITIVITY_AUTO``, ``V4L2_CID_EXPOSURE_METERING``,
+ ``V4L2_CID_SCENE_MODE``, ``V4L2_CID_3A_LOCK``,
+ ``V4L2_CID_AUTO_FOCUS_START``, ``V4L2_CID_AUTO_FOCUS_STOP``,
+ ``V4L2_CID_AUTO_FOCUS_STATUS`` and ``V4L2_CID_AUTO_FOCUS_RANGE``.
+
+
+V4L2 in Linux 3.6
+=================
+
+1. Replaced ``input`` in :c:type:`struct v4l2_buffer` by
+ ``reserved2`` and removed ``V4L2_BUF_FLAG_INPUT``.
+
+2. Added V4L2_CAP_VIDEO_M2M and V4L2_CAP_VIDEO_M2M_MPLANE
+ capabilities.
+
+3. Added support for frequency band enumerations:
+ :ref:`VIDIOC_ENUM_FREQ_BANDS`.
+
+
+V4L2 in Linux 3.9
+=================
+
+1. Added timestamp types to ``flags`` field in
+ :c:type:`struct v4l2_buffer`. See :ref:`buffer-flags`.
+
+2. Added ``V4L2_EVENT_CTRL_CH_RANGE`` control event changes flag. See
+ :ref:`ctrl-changes-flags`.
+
+
+V4L2 in Linux 3.10
+==================
+
+1. Removed obsolete and unused DV_PRESET ioctls VIDIOC_G_DV_PRESET,
+ VIDIOC_S_DV_PRESET, VIDIOC_QUERY_DV_PRESET and
+ VIDIOC_ENUM_DV_PRESET. Remove the related v4l2_input/output
+ capability flags V4L2_IN_CAP_PRESETS and V4L2_OUT_CAP_PRESETS.
+
+2. Added new debugging ioctl
+ :ref:`VIDIOC_DBG_G_CHIP_INFO`.
+
+
+V4L2 in Linux 3.11
+==================
+
+1. Remove obsolete ``VIDIOC_DBG_G_CHIP_IDENT`` ioctl.
+
+
+V4L2 in Linux 3.14
+==================
+
+1. In struct :c:type:`struct v4l2_rect`, the type of ``width`` and
+ ``height`` fields changed from _s32 to _u32.
+
+
+V4L2 in Linux 3.15
+==================
+
+1. Added Software Defined Radio (SDR) Interface.
+
+
+V4L2 in Linux 3.16
+==================
+
+1. Added event V4L2_EVENT_SOURCE_CHANGE.
+
+
+V4L2 in Linux 3.17
+==================
+
+1. Extended struct :ref:`v4l2_pix_format <v4l2-pix-format>`. Added
+ format flags.
+
+2. Added compound control types and
+ :ref:`VIDIOC_QUERY_EXT_CTRL <VIDIOC_QUERYCTRL>`.
+
+
+V4L2 in Linux 3.18
+==================
+
+1. Added ``V4L2_CID_PAN_SPEED`` and ``V4L2_CID_TILT_SPEED`` camera
+ controls.
+
+
+V4L2 in Linux 3.19
+==================
+
+1. Rewrote Colorspace chapter, added new enum
+ :ref:`v4l2_ycbcr_encoding <v4l2-ycbcr-encoding>` and enum
+ :ref:`v4l2_quantization <v4l2-quantization>` fields to struct
+ :ref:`v4l2_pix_format <v4l2-pix-format>`, struct
+ :ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` and
+ struct :ref:`v4l2_mbus_framefmt <v4l2-mbus-framefmt>`.
+
+
+V4L2 in Linux 4.4
+=================
+
+1. Renamed ``V4L2_TUNER_ADC`` to ``V4L2_TUNER_SDR``. The use of
+ ``V4L2_TUNER_ADC`` is deprecated now.
+
+2. Added ``V4L2_CID_RF_TUNER_RF_GAIN`` RF Tuner control.
+
+3. Added transmitter support for Software Defined Radio (SDR) Interface.
+
+
+.. _other:
+
+Relation of V4L2 to other Linux multimedia APIs
+===============================================
+
+
+.. _xvideo:
+
+X Video Extension
+-----------------
+
+The X Video Extension (abbreviated XVideo or just Xv) is an extension of
+the X Window system, implemented for example by the XFree86 project. Its
+scope is similar to V4L2, an API to video capture and output devices for
+X clients. Xv allows applications to display live video in a window,
+send window contents to a TV output, and capture or output still images
+in XPixmaps [1]_. With their implementation XFree86 makes the extension
+available across many operating systems and architectures.
+
+Because the driver is embedded into the X server Xv has a number of
+advantages over the V4L2 :ref:`video overlay interface <overlay>`. The
+driver can easily determine the overlay target, i. e. visible graphics
+memory or off-screen buffers for a destructive overlay. It can program
+the RAMDAC for a non-destructive overlay, scaling or color-keying, or
+the clipping functions of the video capture hardware, always in sync
+with drawing operations or windows moving or changing their stacking
+order.
+
+To combine the advantages of Xv and V4L a special Xv driver exists in
+XFree86 and XOrg, just programming any overlay capable Video4Linux
+device it finds. To enable it ``/etc/X11/XF86Config`` must contain these
+lines:
+
+::
+
+ Section "Module"
+ Load "v4l"
+ EndSection
+
+As of XFree86 4.2 this driver still supports only V4L ioctls, however it
+should work just fine with all V4L2 devices through the V4L2
+backward-compatibility layer. Since V4L2 permits multiple opens it is
+possible (if supported by the V4L2 driver) to capture video while an X
+client requested video overlay. Restrictions of simultaneous capturing
+and overlay are discussed in :ref:`overlay` apply.
+
+Only marginally related to V4L2, XFree86 extended Xv to support hardware
+YUV to RGB conversion and scaling for faster video playback, and added
+an interface to MPEG-2 decoding hardware. This API is useful to display
+images captured with V4L2 devices.
+
+
+Digital Video
+-------------
+
+V4L2 does not support digital terrestrial, cable or satellite broadcast.
+A separate project aiming at digital receivers exists. You can find its
+homepage at `https://linuxtv.org <https://linuxtv.org>`__. The Linux
+DVB API has no connection to the V4L2 API except that drivers for hybrid
+hardware may support both.
+
+
+Audio Interfaces
+----------------
+
+[to do - OSS/ALSA]
+
+
+.. _experimental:
+
+Experimental API Elements
+=========================
+
+The following V4L2 API elements are currently experimental and may
+change in the future.
+
+- :ref:`VIDIOC_DBG_G_REGISTER` and
+ :ref:`VIDIOC_DBG_S_REGISTER <VIDIOC_DBG_G_REGISTER>` ioctls.
+
+- :ref:`VIDIOC_DBG_G_CHIP_INFO` ioctl.
+
+
+.. _obsolete:
+
+Obsolete API Elements
+=====================
+
+The following V4L2 API elements were superseded by new interfaces and
+should not be implemented in new drivers.
+
+- ``VIDIOC_G_MPEGCOMP`` and ``VIDIOC_S_MPEGCOMP`` ioctls. Use Extended
+ Controls, :ref:`extended-controls`.
+
+- VIDIOC_G_DV_PRESET, VIDIOC_S_DV_PRESET,
+ VIDIOC_ENUM_DV_PRESETS and VIDIOC_QUERY_DV_PRESET ioctls. Use
+ the DV Timings API (:ref:`dv-timings`).
+
+- ``VIDIOC_SUBDEV_G_CROP`` and ``VIDIOC_SUBDEV_S_CROP`` ioctls. Use
+ ``VIDIOC_SUBDEV_G_SELECTION`` and ``VIDIOC_SUBDEV_S_SELECTION``,
+ :ref:`VIDIOC_SUBDEV_G_SELECTION`.
+
+.. [1]
+ This is not implemented in XFree86.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _io:
+
+############
+Input/Output
+############
+The V4L2 API defines several different methods to read from or write to
+a device. All drivers exchanging data with applications must support at
+least one of them.
+
+The classic I/O method using the :ref:`read() <func-read>` and
+:ref:`write() <func-write>` function is automatically selected after opening a
+V4L2 device. When the driver does not support this method attempts to
+read or write will fail at any time.
+
+Other methods must be negotiated. To select the streaming I/O method
+with memory mapped or user buffers applications call the
+:ref:`VIDIOC_REQBUFS` ioctl. The asynchronous I/O
+method is not defined yet.
+
+Video overlay can be considered another I/O method, although the
+application does not directly receive the image data. It is selected by
+initiating video overlay with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
+ioctl. For more information see :ref:`overlay`.
+
+Generally exactly one I/O method, including overlay, is associated with
+each file descriptor. The only exceptions are applications not
+exchanging data with a driver ("panel applications", see :ref:`open`)
+and drivers permitting simultaneous video capturing and overlay using
+the same file descriptor, for compatibility with V4L and earlier
+versions of V4L2.
+
+:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_REQBUFS` would permit this to some
+degree, but for simplicity drivers need not support switching the I/O
+method (after first switching away from read/write) other than by
+closing and reopening the device.
+
+The following sections describe the various I/O methods in more detail.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ rw
+ mmap
+ userp
+ dmabuf
+ async
+ buffer
+ field-order
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _libv4l-introduction:
+
+************
+Introduction
+************
+
+libv4l is a collection of libraries which adds a thin abstraction layer
+on top of video4linux2 devices. The purpose of this (thin) layer is to
+make it easy for application writers to support a wide variety of
+devices without having to write separate code for different devices in
+the same class.
+
+An example of using libv4l is provided by
+:ref:`v4l2grab <v4l2grab-example>`.
+
+libv4l consists of 3 different libraries:
+
+
+libv4lconvert
+=============
+
+libv4lconvert is a library that converts several different pixelformats
+found in V4L2 drivers into a few common RGB and YUY formats.
+
+It currently accepts the following V4L2 driver formats:
+:ref:`V4L2_PIX_FMT_BGR24 <V4L2-PIX-FMT-BGR24>`,
+:ref:`V4L2_PIX_FMT_HM12 <V4L2-PIX-FMT-HM12>`,
+:ref:`V4L2_PIX_FMT_JPEG <V4L2-PIX-FMT-JPEG>`,
+:ref:`V4L2_PIX_FMT_MJPEG <V4L2-PIX-FMT-MJPEG>`,
+:ref:`V4L2_PIX_FMT_MR97310A <V4L2-PIX-FMT-MR97310A>`,
+:ref:`V4L2_PIX_FMT_OV511 <V4L2-PIX-FMT-OV511>`,
+:ref:`V4L2_PIX_FMT_OV518 <V4L2-PIX-FMT-OV518>`,
+:ref:`V4L2_PIX_FMT_PAC207 <V4L2-PIX-FMT-PAC207>`,
+:ref:`V4L2_PIX_FMT_PJPG <V4L2-PIX-FMT-PJPG>`,
+:ref:`V4L2_PIX_FMT_RGB24 <V4L2-PIX-FMT-RGB24>`,
+:ref:`V4L2_PIX_FMT_SBGGR8 <V4L2-PIX-FMT-SBGGR8>`,
+:ref:`V4L2_PIX_FMT_SGBRG8 <V4L2-PIX-FMT-SGBRG8>`,
+:ref:`V4L2_PIX_FMT_SGRBG8 <V4L2-PIX-FMT-SGRBG8>`,
+:ref:`V4L2_PIX_FMT_SN9C10X <V4L2-PIX-FMT-SN9C10X>`,
+:ref:`V4L2_PIX_FMT_SN9C20X_I420 <V4L2-PIX-FMT-SN9C20X-I420>`,
+:ref:`V4L2_PIX_FMT_SPCA501 <V4L2-PIX-FMT-SPCA501>`,
+:ref:`V4L2_PIX_FMT_SPCA505 <V4L2-PIX-FMT-SPCA505>`,
+:ref:`V4L2_PIX_FMT_SPCA508 <V4L2-PIX-FMT-SPCA508>`,
+:ref:`V4L2_PIX_FMT_SPCA561 <V4L2-PIX-FMT-SPCA561>`,
+:ref:`V4L2_PIX_FMT_SQ905C <V4L2-PIX-FMT-SQ905C>`,
+:ref:`V4L2_PIX_FMT_SRGGB8 <V4L2-PIX-FMT-SRGGB8>`,
+:ref:`V4L2_PIX_FMT_UYVY <V4L2-PIX-FMT-UYVY>`,
+:ref:`V4L2_PIX_FMT_YUV420 <V4L2-PIX-FMT-YUV420>`,
+:ref:`V4L2_PIX_FMT_YUYV <V4L2-PIX-FMT-YUYV>`,
+:ref:`V4L2_PIX_FMT_YVU420 <V4L2-PIX-FMT-YVU420>`, and
+:ref:`V4L2_PIX_FMT_YVYU <V4L2-PIX-FMT-YVYU>`.
+
+Later on libv4lconvert was expanded to also be able to do various video
+processing functions to improve webcam video quality. The video
+processing is split in to 2 parts: libv4lconvert/control and
+libv4lconvert/processing.
+
+The control part is used to offer video controls which can be used to
+control the video processing functions made available by
+libv4lconvert/processing. These controls are stored application wide
+(until reboot) by using a persistent shared memory object.
+
+libv4lconvert/processing offers the actual video processing
+functionality.
+
+
+libv4l1
+=======
+
+This library offers functions that can be used to quickly make v4l1
+applications work with v4l2 devices. These functions work exactly like
+the normal open/close/etc, except that libv4l1 does full emulation of
+the v4l1 api on top of v4l2 drivers, in case of v4l1 drivers it will
+just pass calls through.
+
+Since those functions are emulations of the old V4L1 API, it shouldn't
+be used for new applications.
+
+
+libv4l2
+=======
+
+This library should be used for all modern V4L2 applications.
+
+It provides handles to call V4L2 open/ioctl/close/poll methods. Instead
+of just providing the raw output of the device, it enhances the calls in
+the sense that it will use libv4lconvert to provide more video formats
+and to enhance the image quality.
+
+In most cases, libv4l2 just passes the calls directly through to the
+v4l2 driver, intercepting the calls to
+:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>`,
+:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`,
+:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`,
+:ref:`VIDIOC_ENUM_FRAMESIZES <VIDIOC_ENUM_FRAMESIZES>` and
+:ref:`VIDIOC_ENUM_FRAMEINTERVALS <VIDIOC_ENUM_FRAMEINTERVALS>` in
+order to emulate the formats
+:ref:`V4L2_PIX_FMT_BGR24 <V4L2-PIX-FMT-BGR24>`,
+:ref:`V4L2_PIX_FMT_RGB24 <V4L2-PIX-FMT-RGB24>`,
+:ref:`V4L2_PIX_FMT_YUV420 <V4L2-PIX-FMT-YUV420>`, and
+:ref:`V4L2_PIX_FMT_YVU420 <V4L2-PIX-FMT-YVU420>`, if they aren't
+available in the driver. :ref:`VIDIOC_ENUM_FMT <VIDIOC_ENUM_FMT>`
+keeps enumerating the hardware supported formats, plus the emulated
+formats offered by libv4l at the end.
+
+
+.. _libv4l-ops:
+
+Libv4l device control functions
+-------------------------------
+
+The common file operation methods are provided by libv4l.
+
+Those functions operate just like glibc
+open/close/dup/ioctl/read/mmap/munmap:
+
+- :c:type:`int v4l2_open(const char *file, int oflag, ...)` - operates like the
+ standard :ref:`open() <func-open>` function.
+
+- :c:type:`int v4l2_close(int fd)` - operates like the standard
+ :ref:`close() <func-close>` function.
+
+- :c:type:`int v4l2_dup(int fd)` - operates like the standard dup() function,
+ duplicating a file handler.
+
+- :c:type:`int v4l2_ioctl (int fd, unsigned long int request, ...)` - operates
+ like the standard :ref:`ioctl() <func-ioctl>` function.
+
+- :c:type:`int v4l2_read (int fd, void* buffer, size_t n)` - operates like the
+ standard :ref:`read() <func-read>` function.
+
+- :c:type:`void v4l2_mmap(void *start, size_t length, int prot, int flags, int
+ fd, int64_t offset);` - operates like the standard
+ :ref:`mmap() <func-mmap>` function.
+
+- :c:type:`int v4l2_munmap(void *_start, size_t length);` - operates like the
+ standard :ref:`munmap() <func-munmap>` function.
+
+Those functions provide additional control:
+
+- :c:type:`int v4l2_fd_open(int fd, int v4l2_flags)` - opens an already opened
+ fd for further use through v4l2lib and possibly modify libv4l2's
+ default behavior through the v4l2_flags argument. Currently,
+ v4l2_flags can be ``V4L2_DISABLE_CONVERSION``, to disable format
+ conversion.
+
+- :c:type:`int v4l2_set_control(int fd, int cid, int value)` - This function
+ takes a value of 0 - 65535, and then scales that range to the actual
+ range of the given v4l control id, and then if the cid exists and is
+ not locked sets the cid to the scaled value.
+
+- :c:type:`int v4l2_get_control(int fd, int cid)` - This function returns a
+ value of 0 - 65535, scaled to from the actual range of the given v4l
+ control id. when the cid does not exist, could not be accessed for
+ some reason, or some error occurred 0 is returned.
+
+
+v4l1compat.so wrapper library
+=============================
+
+This library intercepts calls to open/close/ioctl/mmap/mmunmap
+operations and redirects them to the libv4l counterparts, by using
+LD_PRELOAD=/usr/lib/v4l1compat.so. It also emulates V4L1 calls via V4L2
+API.
+
+It allows usage of binary legacy applications that still don't use
+libv4l.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _libv4l:
+
+************************
+Libv4l Userspace Library
+************************
+
+
+.. toctree::
+ :maxdepth: 1
+
+ libv4l-introduction
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _mmap:
+
+******************************
+Streaming I/O (Memory Mapping)
+******************************
+
+Input and output devices support this I/O method when the
+``V4L2_CAP_STREAMING`` flag in the ``capabilities`` field of struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP` ioctl is set. There are two
+streaming methods, to determine if the memory mapping flavor is
+supported applications must call the
+:ref:`VIDIOC_REQBUFS` ioctl.
+
+Streaming is an I/O method where only pointers to buffers are exchanged
+between application and driver, the data itself is not copied. Memory
+mapping is primarily intended to map buffers in device memory into the
+application's address space. Device memory can be for example the video
+memory on a graphics card with a video capture add-on. However, being
+the most efficient I/O method available for a long time, many other
+drivers support streaming as well, allocating buffers in DMA-able main
+memory.
+
+A driver can support many sets of buffers. Each set is identified by a
+unique buffer type value. The sets are independent and each set can hold
+a different type of data. To access different sets at the same time
+different file descriptors must be used. [1]_
+
+To allocate device buffers applications call the
+:ref:`VIDIOC_REQBUFS` ioctl with the desired number
+of buffers and buffer type, for example ``V4L2_BUF_TYPE_VIDEO_CAPTURE``.
+This ioctl can also be used to change the number of buffers or to free
+the allocated memory, provided none of the buffers are still mapped.
+
+Before applications can access the buffers they must map them into their
+address space with the :ref:`mmap() <func-mmap>` function. The
+location of the buffers in device memory can be determined with the
+:ref:`VIDIOC_QUERYBUF` ioctl. In the single-planar
+API case, the ``m.offset`` and ``length`` returned in a struct
+:ref:`v4l2_buffer <v4l2-buffer>` are passed as sixth and second
+parameter to the :ref:`mmap() <func-mmap>` function. When using the
+multi-planar API, struct :ref:`v4l2_buffer <v4l2-buffer>` contains an
+array of struct :ref:`v4l2_plane <v4l2-plane>` structures, each
+containing its own ``m.offset`` and ``length``. When using the
+multi-planar API, every plane of every buffer has to be mapped
+separately, so the number of calls to :ref:`mmap() <func-mmap>` should
+be equal to number of buffers times number of planes in each buffer. The
+offset and length values must not be modified. Remember, the buffers are
+allocated in physical memory, as opposed to virtual memory, which can be
+swapped out to disk. Applications should free the buffers as soon as
+possible with the :ref:`munmap() <func-munmap>` function.
+
+
+.. code-block:: c
+ :caption: Example 3.1. Mapping buffers in the single-planar API
+
+ struct v4l2_requestbuffers reqbuf;
+ struct {
+ void *start;
+ size_t length;
+ } *buffers;
+ unsigned int i;
+
+ memset(&reqbuf, 0, sizeof(reqbuf));
+ reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ reqbuf.memory = V4L2_MEMORY_MMAP;
+ reqbuf.count = 20;
+
+ if (-1 == ioctl (fd, VIDIOC_REQBUFS, &reqbuf)) {
+ if (errno == EINVAL)
+ printf("Video capturing or mmap-streaming is not supported\\n");
+ else
+ perror("VIDIOC_REQBUFS");
+
+ exit(EXIT_FAILURE);
+ }
+
+ /* We want at least five buffers. */
+
+ if (reqbuf.count < 5) {
+ /* You may need to free the buffers here. */
+ printf("Not enough buffer memory\\n");
+ exit(EXIT_FAILURE);
+ }
+
+ buffers = calloc(reqbuf.count, sizeof(*buffers));
+ assert(buffers != NULL);
+
+ for (i = 0; i < reqbuf.count; i++) {
+ struct v4l2_buffer buffer;
+
+ memset(&buffer, 0, sizeof(buffer));
+ buffer.type = reqbuf.type;
+ buffer.memory = V4L2_MEMORY_MMAP;
+ buffer.index = i;
+
+ if (-1 == ioctl (fd, VIDIOC_QUERYBUF, &buffer)) {
+ perror("VIDIOC_QUERYBUF");
+ exit(EXIT_FAILURE);
+ }
+
+ buffers[i].length = buffer.length; /* remember for munmap() */
+
+ buffers[i].start = mmap(NULL, buffer.length,
+ PROT_READ | PROT_WRITE, /* recommended */
+ MAP_SHARED, /* recommended */
+ fd, buffer.m.offset);
+
+ if (MAP_FAILED == buffers[i].start) {
+ /* If you do not exit here you should unmap() and free()
+ the buffers mapped so far. */
+ perror("mmap");
+ exit(EXIT_FAILURE);
+ }
+ }
+
+ /* Cleanup. */
+
+ for (i = 0; i < reqbuf.count; i++)
+ munmap(buffers[i].start, buffers[i].length);
+
+
+.. code-block:: c
+ :caption: Example 3.2. Mapping buffers in the multi-planar API
+
+ struct v4l2_requestbuffers reqbuf;
+ /* Our current format uses 3 planes per buffer */
+ #define FMT_NUM_PLANES = 3
+
+ struct {
+ void *start[FMT_NUM_PLANES];
+ size_t length[FMT_NUM_PLANES];
+ } *buffers;
+ unsigned int i, j;
+
+ memset(&reqbuf, 0, sizeof(reqbuf));
+ reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE;
+ reqbuf.memory = V4L2_MEMORY_MMAP;
+ reqbuf.count = 20;
+
+ if (ioctl(fd, VIDIOC_REQBUFS, &reqbuf) < 0) {
+ if (errno == EINVAL)
+ printf("Video capturing or mmap-streaming is not supported\\n");
+ else
+ perror("VIDIOC_REQBUFS");
+
+ exit(EXIT_FAILURE);
+ }
+
+ /* We want at least five buffers. */
+
+ if (reqbuf.count < 5) {
+ /* You may need to free the buffers here. */
+ printf("Not enough buffer memory\\n");
+ exit(EXIT_FAILURE);
+ }
+
+ buffers = calloc(reqbuf.count, sizeof(*buffers));
+ assert(buffers != NULL);
+
+ for (i = 0; i < reqbuf.count; i++) {
+ struct v4l2_buffer buffer;
+ struct v4l2_plane planes[FMT_NUM_PLANES];
+
+ memset(&buffer, 0, sizeof(buffer));
+ buffer.type = reqbuf.type;
+ buffer.memory = V4L2_MEMORY_MMAP;
+ buffer.index = i;
+ /* length in struct v4l2_buffer in multi-planar API stores the size
+ * of planes array. */
+ buffer.length = FMT_NUM_PLANES;
+ buffer.m.planes = planes;
+
+ if (ioctl(fd, VIDIOC_QUERYBUF, &buffer) < 0) {
+ perror("VIDIOC_QUERYBUF");
+ exit(EXIT_FAILURE);
+ }
+
+ /* Every plane has to be mapped separately */
+ for (j = 0; j < FMT_NUM_PLANES; j++) {
+ buffers[i].length[j] = buffer.m.planes[j].length; /* remember for munmap() */
+
+ buffers[i].start[j] = mmap(NULL, buffer.m.planes[j].length,
+ PROT_READ | PROT_WRITE, /* recommended */
+ MAP_SHARED, /* recommended */
+ fd, buffer.m.planes[j].m.offset);
+
+ if (MAP_FAILED == buffers[i].start[j]) {
+ /* If you do not exit here you should unmap() and free()
+ the buffers and planes mapped so far. */
+ perror("mmap");
+ exit(EXIT_FAILURE);
+ }
+ }
+ }
+
+ /* Cleanup. */
+
+ for (i = 0; i < reqbuf.count; i++)
+ for (j = 0; j < FMT_NUM_PLANES; j++)
+ munmap(buffers[i].start[j], buffers[i].length[j]);
+
+Conceptually streaming drivers maintain two buffer queues, an incoming
+and an outgoing queue. They separate the synchronous capture or output
+operation locked to a video clock from the application which is subject
+to random disk or network delays and preemption by other processes,
+thereby reducing the probability of data loss. The queues are organized
+as FIFOs, buffers will be output in the order enqueued in the incoming
+FIFO, and were captured in the order dequeued from the outgoing FIFO.
+
+The driver may require a minimum number of buffers enqueued at all times
+to function, apart of this no limit exists on the number of buffers
+applications can enqueue in advance, or dequeue and process. They can
+also enqueue in a different order than buffers have been dequeued, and
+the driver can *fill* enqueued *empty* buffers in any order. [2]_ The
+index number of a buffer (struct :ref:`v4l2_buffer <v4l2-buffer>`
+``index``) plays no role here, it only identifies the buffer.
+
+Initially all mapped buffers are in dequeued state, inaccessible by the
+driver. For capturing applications it is customary to first enqueue all
+mapped buffers, then to start capturing and enter the read loop. Here
+the application waits until a filled buffer can be dequeued, and
+re-enqueues the buffer when the data is no longer needed. Output
+applications fill and enqueue buffers, when enough buffers are stacked
+up the output is started with :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`.
+In the write loop, when the application runs out of free buffers, it
+must wait until an empty buffer can be dequeued and reused.
+
+To enqueue and dequeue a buffer applications use the :ref:`VIDIOC_QBUF`
+and :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. The status of a buffer
+being mapped, enqueued, full or empty can be determined at any time
+using the :ref:`VIDIOC_QUERYBUF` ioctl. Two methods exist to suspend
+execution of the application until one or more buffers can be dequeued.
+By default :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` blocks when no buffer is
+in the outgoing queue. When the ``O_NONBLOCK`` flag was given to the
+:ref:`open() <func-open>` function, :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`
+returns immediately with an ``EAGAIN`` error code when no buffer is
+available. The :ref:`select() <func-select>` or :ref:`poll()
+<func-poll>` functions are always available.
+
+To start and stop capturing or output applications call the
+:ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and :ref:`VIDIOC_STREAMOFF
+<VIDIOC_STREAMON>` ioctl. Note :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`
+removes all buffers from both queues as a side effect. Since there is
+no notion of doing anything "now" on a multitasking system, if an
+application needs to synchronize with another event it should examine
+the struct ::ref:`v4l2_buffer <v4l2-buffer>` ``timestamp`` of captured
+or outputted buffers.
+
+Drivers implementing memory mapping I/O must support the
+:ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, :ref:`VIDIOC_QUERYBUF
+<VIDIOC_QUERYBUF>`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_DQBUF
+<VIDIOC_QBUF>`, :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`
+and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls, the :ref:`mmap()
+<func-mmap>`, :ref:`munmap() <func-munmap>`, :ref:`select()
+<func-select>` and :ref:`poll() <func-poll>` function. [3]_
+
+[capture example]
+
+.. [1]
+ One could use one file descriptor and set the buffer type field
+ accordingly when calling :ref:`VIDIOC_QBUF` etc.,
+ but it makes the :ref:`select() <func-select>` function ambiguous. We also
+ like the clean approach of one file descriptor per logical stream.
+ Video overlay for example is also a logical stream, although the CPU
+ is not needed for continuous operation.
+
+.. [2]
+ Random enqueue order permits applications processing images out of
+ order (such as video codecs) to return buffers earlier, reducing the
+ probability of data loss. Random fill order allows drivers to reuse
+ buffers on a LIFO-basis, taking advantage of caches holding
+ scatter-gather lists and the like.
+
+.. [3]
+ At the driver level :ref:`select() <func-select>` and :ref:`poll() <func-poll>` are
+ the same, and :ref:`select() <func-select>` is too important to be optional.
+ The rest should be evident.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _open:
+
+***************************
+Opening and Closing Devices
+***************************
+
+
+Device Naming
+=============
+
+V4L2 drivers are implemented as kernel modules, loaded manually by the
+system administrator or automatically when a device is first discovered.
+The driver modules plug into the "videodev" kernel module. It provides
+helper functions and a common application interface specified in this
+document.
+
+Each driver thus loaded registers one or more device nodes with major
+number 81 and a minor number between 0 and 255. Minor numbers are
+allocated dynamically unless the kernel is compiled with the kernel
+option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers
+are allocated in ranges depending on the device node type (video, radio,
+etc.).
+
+Many drivers support "video_nr", "radio_nr" or "vbi_nr" module
+options to select specific video/radio/vbi node numbers. This allows the
+user to request that the device node is named e.g. /dev/video5 instead
+of leaving it to chance. When the driver supports multiple devices of
+the same type more than one device node number can be assigned,
+separated by commas:
+
+.. code-block:: none
+
+ # modprobe mydriver video_nr=0,1 radio_nr=0,1
+
+In ``/etc/modules.conf`` this may be written as:
+
+::
+
+ options mydriver video_nr=0,1 radio_nr=0,1
+
+When no device node number is given as module option the driver supplies
+a default.
+
+Normally udev will create the device nodes in /dev automatically for
+you. If udev is not installed, then you need to enable the
+CONFIG_VIDEO_FIXED_MINOR_RANGES kernel option in order to be able to
+correctly relate a minor number to a device node number. I.e., you need
+to be certain that minor number 5 maps to device node name video5. With
+this kernel option different device types have different minor number
+ranges. These ranges are listed in :ref:`devices`.
+
+The creation of character special files (with mknod) is a privileged
+operation and devices cannot be opened by major and minor number. That
+means applications cannot *reliable* scan for loaded or installed
+drivers. The user must enter a device name, or the application can try
+the conventional device names.
+
+
+.. _related:
+
+Related Devices
+===============
+
+Devices can support several functions. For example video capturing, VBI
+capturing and radio support.
+
+The V4L2 API creates different nodes for each of these functions.
+
+The V4L2 API was designed with the idea that one device node could
+support all functions. However, in practice this never worked: this
+'feature' was never used by applications and many drivers did not
+support it and if they did it was certainly never tested. In addition,
+switching a device node between different functions only works when
+using the streaming I/O API, not with the
+:ref:`read() <func-read>`/\ :ref:`write() <func-write>` API.
+
+Today each device node supports just one function.
+
+Besides video input or output the hardware may also support audio
+sampling or playback. If so, these functions are implemented as ALSA PCM
+devices with optional ALSA audio mixer devices.
+
+One problem with all these devices is that the V4L2 API makes no
+provisions to find these related devices. Some really complex devices
+use the Media Controller (see :ref:`media_controller`) which can be
+used for this purpose. But most drivers do not use it, and while some
+code exists that uses sysfs to discover related devices (see
+libmedia_dev in the
+`v4l-utils <http://git.linuxtv.org/cgit.cgi/v4l-utils.git/>`__ git
+repository), there is no library yet that can provide a single API
+towards both Media Controller-based devices and devices that do not use
+the Media Controller. If you want to work on this please write to the
+linux-media mailing list:
+`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__.
+
+
+Multiple Opens
+==============
+
+V4L2 devices can be opened more than once. [1]_ When this is supported
+by the driver, users can for example start a "panel" application to
+change controls like brightness or audio volume, while another
+application captures video and audio. In other words, panel applications
+are comparable to an ALSA audio mixer application. Just opening a V4L2
+device should not change the state of the device. [2]_
+
+Once an application has allocated the memory buffers needed for
+streaming data (by calling the :ref:`VIDIOC_REQBUFS`
+or :ref:`VIDIOC_CREATE_BUFS` ioctls, or
+implicitly by calling the :ref:`read() <func-read>` or
+:ref:`write() <func-write>` functions) that application (filehandle)
+becomes the owner of the device. It is no longer allowed to make changes
+that would affect the buffer sizes (e.g. by calling the
+:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl) and other applications are
+no longer allowed to allocate buffers or start or stop streaming. The
+EBUSY error code will be returned instead.
+
+Merely opening a V4L2 device does not grant exclusive access. [3]_
+Initiating data exchange however assigns the right to read or write the
+requested type of data, and to change related properties, to this file
+descriptor. Applications can request additional access privileges using
+the priority mechanism described in :ref:`app-pri`.
+
+
+Shared Data Streams
+===================
+
+V4L2 drivers should not support multiple applications reading or writing
+the same data stream on a device by copying buffers, time multiplexing
+or similar means. This is better handled by a proxy application in user
+space.
+
+
+Functions
+=========
+
+To open and close V4L2 devices applications use the
+:ref:`open() <func-open>` and :ref:`close() <func-close>` function,
+respectively. Devices are programmed using the
+:ref:`ioctl() <func-ioctl>` function as explained in the following
+sections.
+
+.. [1]
+ There are still some old and obscure drivers that have not been
+ updated to allow for multiple opens. This implies that for such
+ drivers :ref:`open() <func-open>` can return an ``EBUSY`` error code
+ when the device is already in use.
+
+.. [2]
+ Unfortunately, opening a radio device often switches the state of the
+ device to radio mode in many drivers. This behavior should be fixed
+ eventually as it violates the V4L2 specification.
+
+.. [3]
+ Drivers could recognize the ``O_EXCL`` open flag. Presently this is
+ not required, so applications cannot know if it really works.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+******************************
+Single-planar format structure
+******************************
+
+
+.. _v4l2-pix-format:
+
+.. flat-table:: struct v4l2_pix_format
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``width``
+
+ - Image width in pixels.
+
+ - .. row 2
+
+ - __u32
+
+ - ``height``
+
+ - Image height in pixels. If ``field`` is one of ``V4L2_FIELD_TOP``,
+ ``V4L2_FIELD_BOTTOM`` or ``V4L2_FIELD_ALTERNATE`` then height
+ refers to the number of lines in the field, otherwise it refers to
+ the number of lines in the frame (which is twice the field height
+ for interlaced formats).
+
+ - .. row 3
+
+ - :cspan:`2` Applications set these fields to request an image
+ size, drivers return the closest possible values. In case of
+ planar formats the ``width`` and ``height`` applies to the largest
+ plane. To avoid ambiguities drivers must return values rounded up
+ to a multiple of the scale factor of any smaller planes. For
+ example when the image format is YUV 4:2:0, ``width`` and
+ ``height`` must be multiples of two.
+
+ - .. row 4
+
+ - __u32
+
+ - ``pixelformat``
+
+ - The pixel format or type of compression, set by the application.
+ This is a little endian
+ :ref:`four character code <v4l2-fourcc>`. V4L2 defines standard
+ RGB formats in :ref:`rgb-formats`, YUV formats in
+ :ref:`yuv-formats`, and reserved codes in
+ :ref:`reserved-formats`
+
+ - .. row 5
+
+ - enum :ref:`v4l2_field <v4l2-field>`
+
+ - ``field``
+
+ - Video images are typically interlaced. Applications can request to
+ capture or output only the top or bottom field, or both fields
+ interlaced or sequentially stored in one buffer or alternating in
+ separate buffers. Drivers return the actual field order selected.
+ For more details on fields see :ref:`field-order`.
+
+ - .. row 6
+
+ - __u32
+
+ - ``bytesperline``
+
+ - Distance in bytes between the leftmost pixels in two adjacent
+ lines.
+
+ - .. row 7
+
+ - :cspan:`2`
+
+ Both applications and drivers can set this field to request
+ padding bytes at the end of each line. Drivers however may ignore
+ the value requested by the application, returning ``width`` times
+ bytes per pixel or a larger value required by the hardware. That
+ implies applications can just set this field to zero to get a
+ reasonable default.
+
+ Video hardware may access padding bytes, therefore they must
+ reside in accessible memory. Consider cases where padding bytes
+ after the last line of an image cross a system page boundary.
+ Input devices may write padding bytes, the value is undefined.
+ Output devices ignore the contents of padding bytes.
+
+ When the image format is planar the ``bytesperline`` value applies
+ to the first plane and is divided by the same factor as the
+ ``width`` field for the other planes. For example the Cb and Cr
+ planes of a YUV 4:2:0 image have half as many padding bytes
+ following each line as the Y plane. To avoid ambiguities drivers
+ must return a ``bytesperline`` value rounded up to a multiple of
+ the scale factor.
+
+ For compressed formats the ``bytesperline`` value makes no sense.
+ Applications and drivers must set this to 0 in that case.
+
+ - .. row 8
+
+ - __u32
+
+ - ``sizeimage``
+
+ - Size in bytes of the buffer to hold a complete image, set by the
+ driver. Usually this is ``bytesperline`` times ``height``. When
+ the image consists of variable length compressed data this is the
+ maximum number of bytes required to hold an image.
+
+ - .. row 9
+
+ - enum :ref:`v4l2_colorspace <v4l2-colorspace>`
+
+ - ``colorspace``
+
+ - This information supplements the ``pixelformat`` and must be set
+ by the driver for capture streams and by the application for
+ output streams, see :ref:`colorspaces`.
+
+ - .. row 10
+
+ - __u32
+
+ - ``priv``
+
+ - This field indicates whether the remaining fields of the
+ :ref:`struct v4l2_pix_format <v4l2-pix-format>` structure, also called the
+ extended fields, are valid. When set to
+ ``V4L2_PIX_FMT_PRIV_MAGIC``, it indicates that the extended fields
+ have been correctly initialized. When set to any other value it
+ indicates that the extended fields contain undefined values.
+
+ Applications that wish to use the pixel format extended fields
+ must first ensure that the feature is supported by querying the
+ device for the :ref:`V4L2_CAP_EXT_PIX_FORMAT <querycap>`
+ capability. If the capability isn't set the pixel format extended
+ fields are not supported and using the extended fields will lead
+ to undefined results.
+
+ To use the extended fields, applications must set the ``priv``
+ field to ``V4L2_PIX_FMT_PRIV_MAGIC``, initialize all the extended
+ fields and zero the unused bytes of the
+ :ref:`struct v4l2_format <v4l2-format>` ``raw_data`` field.
+
+ When the ``priv`` field isn't set to ``V4L2_PIX_FMT_PRIV_MAGIC``
+ drivers must act as if all the extended fields were set to zero.
+ On return drivers must set the ``priv`` field to
+ ``V4L2_PIX_FMT_PRIV_MAGIC`` and all the extended fields to
+ applicable values.
+
+ - .. row 11
+
+ - __u32
+
+ - ``flags``
+
+ - Flags set by the application or driver, see :ref:`format-flags`.
+
+ - .. row 12
+
+ - enum :ref:`v4l2_ycbcr_encoding <v4l2-ycbcr-encoding>`
+
+ - ``ycbcr_enc``
+
+ - This information supplements the ``colorspace`` and must be set by
+ the driver for capture streams and by the application for output
+ streams, see :ref:`colorspaces`.
+
+ - .. row 13
+
+ - enum :ref:`v4l2_quantization <v4l2-quantization>`
+
+ - ``quantization``
+
+ - This information supplements the ``colorspace`` and must be set by
+ the driver for capture streams and by the application for output
+ streams, see :ref:`colorspaces`.
+
+ - .. row 14
+
+ - enum :ref:`v4l2_xfer_func <v4l2-xfer-func>`
+
+ - ``xfer_func``
+
+ - This information supplements the ``colorspace`` and must be set by
+ the driver for capture streams and by the application for output
+ streams, see :ref:`colorspaces`.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+******************************
+Multi-planar format structures
+******************************
+
+The :ref:`struct v4l2_plane_pix_format <v4l2-plane-pix-format>` structures define size
+and layout for each of the planes in a multi-planar format. The
+:ref:`struct v4l2_pix_format_mplane <v4l2-pix-format-mplane>` structure contains
+information common to all planes (such as image width and height) and an
+array of :ref:`struct v4l2_plane_pix_format <v4l2-plane-pix-format>` structures,
+describing all planes of that format.
+
+
+.. _v4l2-plane-pix-format:
+
+.. flat-table:: struct v4l2_plane_pix_format
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``sizeimage``
+
+ - Maximum size in bytes required for image data in this plane.
+
+ - .. row 2
+
+ - __u32
+
+ - ``bytesperline``
+
+ - Distance in bytes between the leftmost pixels in two adjacent
+ lines. See struct :ref:`v4l2_pix_format <v4l2-pix-format>`.
+
+ - .. row 3
+
+ - __u16
+
+ - ``reserved[6]``
+
+ - Reserved for future extensions. Should be zeroed by drivers and
+ applications.
+
+
+
+.. _v4l2-pix-format-mplane:
+
+.. flat-table:: struct v4l2_pix_format_mplane
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``width``
+
+ - Image width in pixels. See struct
+ :ref:`v4l2_pix_format <v4l2-pix-format>`.
+
+ - .. row 2
+
+ - __u32
+
+ - ``height``
+
+ - Image height in pixels. See struct
+ :ref:`v4l2_pix_format <v4l2-pix-format>`.
+
+ - .. row 3
+
+ - __u32
+
+ - ``pixelformat``
+
+ - The pixel format. Both single- and multi-planar four character
+ codes can be used.
+
+ - .. row 4
+
+ - enum :ref:`v4l2_field <v4l2-field>`
+
+ - ``field``
+
+ - See struct :ref:`v4l2_pix_format <v4l2-pix-format>`.
+
+ - .. row 5
+
+ - enum :ref:`v4l2_colorspace <v4l2-colorspace>`
+
+ - ``colorspace``
+
+ - See struct :ref:`v4l2_pix_format <v4l2-pix-format>`.
+
+ - .. row 6
+
+ - struct :ref:`v4l2_plane_pix_format <v4l2-plane-pix-format>`
+
+ - ``plane_fmt[VIDEO_MAX_PLANES]``
+
+ - An array of structures describing format of each plane this pixel
+ format consists of. The number of valid entries in this array has
+ to be put in the ``num_planes`` field.
+
+ - .. row 7
+
+ - __u8
+
+ - ``num_planes``
+
+ - Number of planes (i.e. separate memory buffers) for this format
+ and the number of valid entries in the ``plane_fmt`` array.
+
+ - .. row 8
+
+ - __u8
+
+ - ``flags``
+
+ - Flags set by the application or driver, see :ref:`format-flags`.
+
+ - .. row 9
+
+ - enum :ref:`v4l2_ycbcr_encoding <v4l2-ycbcr-encoding>`
+
+ - ``ycbcr_enc``
+
+ - This information supplements the ``colorspace`` and must be set by
+ the driver for capture streams and by the application for output
+ streams, see :ref:`colorspaces`.
+
+ - .. row 10
+
+ - enum :ref:`v4l2_quantization <v4l2-quantization>`
+
+ - ``quantization``
+
+ - This information supplements the ``colorspace`` and must be set by
+ the driver for capture streams and by the application for output
+ streams, see :ref:`colorspaces`.
+
+ - .. row 11
+
+ - enum :ref:`v4l2_xfer_func <v4l2-xfer-func>`
+
+ - ``xfer_func``
+
+ - This information supplements the ``colorspace`` and must be set by
+ the driver for capture streams and by the application for output
+ streams, see :ref:`colorspaces`.
+
+ - .. row 12
+
+ - __u8
+
+ - ``reserved[7]``
+
+ - Reserved for future extensions. Should be zeroed by drivers and
+ applications.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+**********************
+Standard Image Formats
+**********************
+
+In order to exchange images between drivers and applications, it is
+necessary to have standard image data formats which both sides will
+interpret the same way. V4L2 includes several such formats, and this
+section is intended to be an unambiguous specification of the standard
+image data formats in V4L2.
+
+V4L2 drivers are not limited to these formats, however. Driver-specific
+formats are possible. In that case the application may depend on a codec
+to convert images to one of the standard formats when needed. But the
+data can still be stored and retrieved in the proprietary format. For
+example, a device may support a proprietary compressed format.
+Applications can still capture and save the data in the compressed
+format, saving much disk space, and later use a codec to convert the
+images to the X Windows screen format when the video is to be displayed.
+
+Even so, ultimately, some standard formats are needed, so the V4L2
+specification would not be complete without well-defined standard
+formats.
+
+The V4L2 standard formats are mainly uncompressed formats. The pixels
+are always arranged in memory from left to right, and from top to
+bottom. The first byte of data in the image buffer is always for the
+leftmost pixel of the topmost row. Following that is the pixel
+immediately to its right, and so on until the end of the top row of
+pixels. Following the rightmost pixel of the row there may be zero or
+more bytes of padding to guarantee that each row of pixel data has a
+certain alignment. Following the pad bytes, if any, is data for the
+leftmost pixel of the second row from the top, and so on. The last row
+has just as many pad bytes after it as the other rows.
+
+In V4L2 each format has an identifier which looks like ``PIX_FMT_XXX``,
+defined in the :ref:`videodev2.h <videodev>` header file. These
+identifiers represent
+:ref:`four character (FourCC) codes <v4l2-fourcc>` which are also
+listed below, however they are not the same as those used in the Windows
+world.
+
+For some formats, data is stored in separate, discontiguous memory
+buffers. Those formats are identified by a separate set of FourCC codes
+and are referred to as "multi-planar formats". For example, a
+:ref:`YUV422 <V4L2-PIX-FMT-YUV422M>` frame is normally stored in one
+memory buffer, but it can also be placed in two or three separate
+buffers, with Y component in one buffer and CbCr components in another
+in the 2-planar version or with each component in its own buffer in the
+3-planar case. Those sub-buffers are referred to as "*planes*".
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+****************************
+Defining Colorspaces in V4L2
+****************************
+
+In V4L2 colorspaces are defined by four values. The first is the
+colorspace identifier (enum :ref:`v4l2_colorspace <v4l2-colorspace>`)
+which defines the chromaticities, the default transfer function, the
+default Y'CbCr encoding and the default quantization method. The second
+is the transfer function identifier (enum
+:ref:`v4l2_xfer_func <v4l2-xfer-func>`) to specify non-standard
+transfer functions. The third is the Y'CbCr encoding identifier (enum
+:ref:`v4l2_ycbcr_encoding <v4l2-ycbcr-encoding>`) to specify
+non-standard Y'CbCr encodings and the fourth is the quantization
+identifier (enum :ref:`v4l2_quantization <v4l2-quantization>`) to
+specify non-standard quantization methods. Most of the time only the
+colorspace field of struct :ref:`v4l2_pix_format <v4l2-pix-format>`
+or struct :ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>`
+needs to be filled in. Note that the default R'G'B' quantization is full
+range for all colorspaces except for BT.2020 which uses limited range
+R'G'B' quantization.
+
+
+.. _v4l2-colorspace:
+
+.. flat-table:: V4L2 Colorspaces
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Details
+
+ - .. row 2
+
+ - ``V4L2_COLORSPACE_DEFAULT``
+
+ - The default colorspace. This can be used by applications to let
+ the driver fill in the colorspace.
+
+ - .. row 3
+
+ - ``V4L2_COLORSPACE_SMPTE170M``
+
+ - See :ref:`col-smpte-170m`.
+
+ - .. row 4
+
+ - ``V4L2_COLORSPACE_REC709``
+
+ - See :ref:`col-rec709`.
+
+ - .. row 5
+
+ - ``V4L2_COLORSPACE_SRGB``
+
+ - See :ref:`col-srgb`.
+
+ - .. row 6
+
+ - ``V4L2_COLORSPACE_ADOBERGB``
+
+ - See :ref:`col-adobergb`.
+
+ - .. row 7
+
+ - ``V4L2_COLORSPACE_BT2020``
+
+ - See :ref:`col-bt2020`.
+
+ - .. row 8
+
+ - ``V4L2_COLORSPACE_DCI_P3``
+
+ - See :ref:`col-dcip3`.
+
+ - .. row 9
+
+ - ``V4L2_COLORSPACE_SMPTE240M``
+
+ - See :ref:`col-smpte-240m`.
+
+ - .. row 10
+
+ - ``V4L2_COLORSPACE_470_SYSTEM_M``
+
+ - See :ref:`col-sysm`.
+
+ - .. row 11
+
+ - ``V4L2_COLORSPACE_470_SYSTEM_BG``
+
+ - See :ref:`col-sysbg`.
+
+ - .. row 12
+
+ - ``V4L2_COLORSPACE_JPEG``
+
+ - See :ref:`col-jpeg`.
+
+ - .. row 13
+
+ - ``V4L2_COLORSPACE_RAW``
+
+ - The raw colorspace. This is used for raw image capture where the
+ image is minimally processed and is using the internal colorspace
+ of the device. The software that processes an image using this
+ 'colorspace' will have to know the internals of the capture
+ device.
+
+
+
+.. _v4l2-xfer-func:
+
+.. flat-table:: V4L2 Transfer Function
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Details
+
+ - .. row 2
+
+ - ``V4L2_XFER_FUNC_DEFAULT``
+
+ - Use the default transfer function as defined by the colorspace.
+
+ - .. row 3
+
+ - ``V4L2_XFER_FUNC_709``
+
+ - Use the Rec. 709 transfer function.
+
+ - .. row 4
+
+ - ``V4L2_XFER_FUNC_SRGB``
+
+ - Use the sRGB transfer function.
+
+ - .. row 5
+
+ - ``V4L2_XFER_FUNC_ADOBERGB``
+
+ - Use the AdobeRGB transfer function.
+
+ - .. row 6
+
+ - ``V4L2_XFER_FUNC_SMPTE240M``
+
+ - Use the SMPTE 240M transfer function.
+
+ - .. row 7
+
+ - ``V4L2_XFER_FUNC_NONE``
+
+ - Do not use a transfer function (i.e. use linear RGB values).
+
+ - .. row 8
+
+ - ``V4L2_XFER_FUNC_DCI_P3``
+
+ - Use the DCI-P3 transfer function.
+
+ - .. row 9
+
+ - ``V4L2_XFER_FUNC_SMPTE2084``
+
+ - Use the SMPTE 2084 transfer function.
+
+
+
+.. _v4l2-ycbcr-encoding:
+
+.. flat-table:: V4L2 Y'CbCr Encodings
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Details
+
+ - .. row 2
+
+ - ``V4L2_YCBCR_ENC_DEFAULT``
+
+ - Use the default Y'CbCr encoding as defined by the colorspace.
+
+ - .. row 3
+
+ - ``V4L2_YCBCR_ENC_601``
+
+ - Use the BT.601 Y'CbCr encoding.
+
+ - .. row 4
+
+ - ``V4L2_YCBCR_ENC_709``
+
+ - Use the Rec. 709 Y'CbCr encoding.
+
+ - .. row 5
+
+ - ``V4L2_YCBCR_ENC_XV601``
+
+ - Use the extended gamut xvYCC BT.601 encoding.
+
+ - .. row 6
+
+ - ``V4L2_YCBCR_ENC_XV709``
+
+ - Use the extended gamut xvYCC Rec. 709 encoding.
+
+ - .. row 7
+
+ - ``V4L2_YCBCR_ENC_SYCC``
+
+ - Use the extended gamut sYCC encoding.
+
+ - .. row 8
+
+ - ``V4L2_YCBCR_ENC_BT2020``
+
+ - Use the default non-constant luminance BT.2020 Y'CbCr encoding.
+
+ - .. row 9
+
+ - ``V4L2_YCBCR_ENC_BT2020_CONST_LUM``
+
+ - Use the constant luminance BT.2020 Yc'CbcCrc encoding.
+
+
+
+.. _v4l2-quantization:
+
+.. flat-table:: V4L2 Quantization Methods
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Details
+
+ - .. row 2
+
+ - ``V4L2_QUANTIZATION_DEFAULT``
+
+ - Use the default quantization encoding as defined by the
+ colorspace. This is always full range for R'G'B' (except for the
+ BT.2020 colorspace) and usually limited range for Y'CbCr.
+
+ - .. row 3
+
+ - ``V4L2_QUANTIZATION_FULL_RANGE``
+
+ - Use the full range quantization encoding. I.e. the range [0…1] is
+ mapped to [0…255] (with possible clipping to [1…254] to avoid the
+ 0x00 and 0xff values). Cb and Cr are mapped from [-0.5…0.5] to
+ [0…255] (with possible clipping to [1…254] to avoid the 0x00 and
+ 0xff values).
+
+ - .. row 4
+
+ - ``V4L2_QUANTIZATION_LIM_RANGE``
+
+ - Use the limited range quantization encoding. I.e. the range [0…1]
+ is mapped to [16…235]. Cb and Cr are mapped from [-0.5…0.5] to
+ [16…240].
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+********************************
+Detailed Colorspace Descriptions
+********************************
+
+
+.. _col-smpte-170m:
+
+Colorspace SMPTE 170M (V4L2_COLORSPACE_SMPTE170M)
+=================================================
+
+The :ref:`smpte170m` standard defines the colorspace used by NTSC and
+PAL and by SDTV in general. The default transfer function is
+``V4L2_XFER_FUNC_709``. The default Y'CbCr encoding is
+``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is limited
+range. The chromaticities of the primary colors and the white reference
+are:
+
+
+
+.. flat-table:: SMPTE 170M Chromaticities
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - Color
+
+ - x
+
+ - y
+
+ - .. row 2
+
+ - Red
+
+ - 0.630
+
+ - 0.340
+
+ - .. row 3
+
+ - Green
+
+ - 0.310
+
+ - 0.595
+
+ - .. row 4
+
+ - Blue
+
+ - 0.155
+
+ - 0.070
+
+ - .. row 5
+
+ - White Reference (D65)
+
+ - 0.3127
+
+ - 0.3290
+
+
+The red, green and blue chromaticities are also often referred to as the
+SMPTE C set, so this colorspace is sometimes called SMPTE C as well.
+
+The transfer function defined for SMPTE 170M is the same as the one
+defined in Rec. 709.
+
+ L' = -1.099(-L) :sup:`0.45` + 0.099 for L ≤ -0.018
+
+ L' = 4.5L for -0.018 < L < 0.018
+
+ L' = 1.099L :sup:`0.45` - 0.099 for L ≥ 0.018
+
+Inverse Transfer function:
+
+ L = -((L' - 0.099) / -1.099) :sup:`1/0.45` for L' ≤ -0.081
+
+ L = L' / 4.5 for -0.081 < L' < 0.081
+
+ L = ((L' + 0.099) / 1.099) :sup:`1/0.45` for L' ≥ 0.081
+
+The luminance (Y') and color difference (Cb and Cr) are obtained with
+the following ``V4L2_YCBCR_ENC_601`` encoding:
+
+ Y' = 0.299R' + 0.587G' + 0.114B'
+
+ Cb = -0.169R' - 0.331G' + 0.5B'
+
+ Cr = 0.5R' - 0.419G' - 0.081B'
+
+Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
+[-0.5…0.5]. This conversion to Y'CbCr is identical to the one defined in
+the :ref:`itu601` standard and this colorspace is sometimes called
+BT.601 as well, even though BT.601 does not mention any color primaries.
+
+The default quantization is limited range, but full range is possible
+although rarely seen.
+
+
+.. _col-rec709:
+
+Colorspace Rec. 709 (V4L2_COLORSPACE_REC709)
+============================================
+
+The :ref:`itu709` standard defines the colorspace used by HDTV in
+general. The default transfer function is ``V4L2_XFER_FUNC_709``. The
+default Y'CbCr encoding is ``V4L2_YCBCR_ENC_709``. The default Y'CbCr
+quantization is limited range. The chromaticities of the primary colors
+and the white reference are:
+
+
+
+.. flat-table:: Rec. 709 Chromaticities
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - Color
+
+ - x
+
+ - y
+
+ - .. row 2
+
+ - Red
+
+ - 0.640
+
+ - 0.330
+
+ - .. row 3
+
+ - Green
+
+ - 0.300
+
+ - 0.600
+
+ - .. row 4
+
+ - Blue
+
+ - 0.150
+
+ - 0.060
+
+ - .. row 5
+
+ - White Reference (D65)
+
+ - 0.3127
+
+ - 0.3290
+
+
+The full name of this standard is Rec. ITU-R BT.709-5.
+
+Transfer function. Normally L is in the range [0…1], but for the
+extended gamut xvYCC encoding values outside that range are allowed.
+
+ L' = -1.099(-L) :sup:`0.45` + 0.099 for L ≤ -0.018
+
+ L' = 4.5L for -0.018 < L < 0.018
+
+ L' = 1.099L :sup:`0.45` - 0.099 for L ≥ 0.018
+
+Inverse Transfer function:
+
+ L = -((L' - 0.099) / -1.099) :sup:`1/0.45` for L' ≤ -0.081
+
+ L = L' / 4.5 for -0.081 < L' < 0.081
+
+ L = ((L' + 0.099) / 1.099) :sup:`1/0.45` for L' ≥ 0.081
+
+The luminance (Y') and color difference (Cb and Cr) are obtained with
+the following ``V4L2_YCBCR_ENC_709`` encoding:
+
+ Y' = 0.2126R' + 0.7152G' + 0.0722B'
+
+ Cb = -0.1146R' - 0.3854G' + 0.5B'
+
+ Cr = 0.5R' - 0.4542G' - 0.0458B'
+
+Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
+[-0.5…0.5].
+
+The default quantization is limited range, but full range is possible
+although rarely seen.
+
+The ``V4L2_YCBCR_ENC_709`` encoding described above is the default for
+this colorspace, but it can be overridden with ``V4L2_YCBCR_ENC_601``,
+in which case the BT.601 Y'CbCr encoding is used.
+
+Two additional extended gamut Y'CbCr encodings are also possible with
+this colorspace:
+
+The xvYCC 709 encoding (``V4L2_YCBCR_ENC_XV709``, :ref:`xvycc`) is
+similar to the Rec. 709 encoding, but it allows for R', G' and B' values
+that are outside the range [0…1]. The resulting Y', Cb and Cr values are
+scaled and offset:
+
+ Y' = (219 / 256) * (0.2126R' + 0.7152G' + 0.0722B') + (16 / 256)
+
+ Cb = (224 / 256) * (-0.1146R' - 0.3854G' + 0.5B')
+
+ Cr = (224 / 256) * (0.5R' - 0.4542G' - 0.0458B')
+
+The xvYCC 601 encoding (``V4L2_YCBCR_ENC_XV601``, :ref:`xvycc`) is
+similar to the BT.601 encoding, but it allows for R', G' and B' values
+that are outside the range [0…1]. The resulting Y', Cb and Cr values are
+scaled and offset:
+
+ Y' = (219 / 256) * (0.299R' + 0.587G' + 0.114B') + (16 / 256)
+
+ Cb = (224 / 256) * (-0.169R' - 0.331G' + 0.5B')
+
+ Cr = (224 / 256) * (0.5R' - 0.419G' - 0.081B')
+
+Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
+[-0.5…0.5]. The non-standard xvYCC 709 or xvYCC 601 encodings can be
+used by selecting ``V4L2_YCBCR_ENC_XV709`` or ``V4L2_YCBCR_ENC_XV601``.
+The xvYCC encodings always use full range quantization.
+
+
+.. _col-srgb:
+
+Colorspace sRGB (V4L2_COLORSPACE_SRGB)
+======================================
+
+The :ref:`srgb` standard defines the colorspace used by most webcams
+and computer graphics. The default transfer function is
+``V4L2_XFER_FUNC_SRGB``. The default Y'CbCr encoding is
+``V4L2_YCBCR_ENC_SYCC``. The default Y'CbCr quantization is full range.
+The chromaticities of the primary colors and the white reference are:
+
+
+
+.. flat-table:: sRGB Chromaticities
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - Color
+
+ - x
+
+ - y
+
+ - .. row 2
+
+ - Red
+
+ - 0.640
+
+ - 0.330
+
+ - .. row 3
+
+ - Green
+
+ - 0.300
+
+ - 0.600
+
+ - .. row 4
+
+ - Blue
+
+ - 0.150
+
+ - 0.060
+
+ - .. row 5
+
+ - White Reference (D65)
+
+ - 0.3127
+
+ - 0.3290
+
+
+These chromaticities are identical to the Rec. 709 colorspace.
+
+Transfer function. Note that negative values for L are only used by the
+Y'CbCr conversion.
+
+ L' = -1.055(-L) :sup:`1/2.4` + 0.055 for L < -0.0031308
+
+ L' = 12.92L for -0.0031308 ≤ L ≤ 0.0031308
+
+ L' = 1.055L :sup:`1/2.4` - 0.055 for 0.0031308 < L ≤ 1
+
+Inverse Transfer function:
+
+ L = -((-L' + 0.055) / 1.055) :sup:`2.4` for L' < -0.04045
+
+ L = L' / 12.92 for -0.04045 ≤ L' ≤ 0.04045
+
+ L = ((L' + 0.055) / 1.055) :sup:`2.4` for L' > 0.04045
+
+The luminance (Y') and color difference (Cb and Cr) are obtained with
+the following ``V4L2_YCBCR_ENC_SYCC`` encoding as defined by
+:ref:`sycc`:
+
+ Y' = 0.2990R' + 0.5870G' + 0.1140B'
+
+ Cb = -0.1687R' - 0.3313G' + 0.5B'
+
+ Cr = 0.5R' - 0.4187G' - 0.0813B'
+
+Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
+[-0.5…0.5]. The ``V4L2_YCBCR_ENC_SYCC`` quantization is always full
+range. Although this Y'CbCr encoding looks very similar to the
+``V4L2_YCBCR_ENC_XV601`` encoding, it is not. The
+``V4L2_YCBCR_ENC_XV601`` scales and offsets the Y'CbCr values before
+quantization, but this encoding does not do that.
+
+
+.. _col-adobergb:
+
+Colorspace Adobe RGB (V4L2_COLORSPACE_ADOBERGB)
+===============================================
+
+The :ref:`adobergb` standard defines the colorspace used by computer
+graphics that use the AdobeRGB colorspace. This is also known as the
+:ref:`oprgb` standard. The default transfer function is
+``V4L2_XFER_FUNC_ADOBERGB``. The default Y'CbCr encoding is
+``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is limited
+range. The chromaticities of the primary colors and the white reference
+are:
+
+
+
+.. flat-table:: Adobe RGB Chromaticities
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - Color
+
+ - x
+
+ - y
+
+ - .. row 2
+
+ - Red
+
+ - 0.6400
+
+ - 0.3300
+
+ - .. row 3
+
+ - Green
+
+ - 0.2100
+
+ - 0.7100
+
+ - .. row 4
+
+ - Blue
+
+ - 0.1500
+
+ - 0.0600
+
+ - .. row 5
+
+ - White Reference (D65)
+
+ - 0.3127
+
+ - 0.3290
+
+
+
+Transfer function:
+
+ L' = L :sup:`1/2.19921875`
+
+Inverse Transfer function:
+
+ L = L' :sup:`2.19921875`
+
+The luminance (Y') and color difference (Cb and Cr) are obtained with
+the following ``V4L2_YCBCR_ENC_601`` encoding:
+
+ Y' = 0.299R' + 0.587G' + 0.114B'
+
+ Cb = -0.169R' - 0.331G' + 0.5B'
+
+ Cr = 0.5R' - 0.419G' - 0.081B'
+
+Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
+[-0.5…0.5]. This transform is identical to one defined in SMPTE
+170M/BT.601. The Y'CbCr quantization is limited range.
+
+
+.. _col-bt2020:
+
+Colorspace BT.2020 (V4L2_COLORSPACE_BT2020)
+===========================================
+
+The :ref:`itu2020` standard defines the colorspace used by Ultra-high
+definition television (UHDTV). The default transfer function is
+``V4L2_XFER_FUNC_709``. The default Y'CbCr encoding is
+``V4L2_YCBCR_ENC_BT2020``. The default R'G'B' quantization is limited
+range (!), and so is the default Y'CbCr quantization. The chromaticities
+of the primary colors and the white reference are:
+
+
+
+.. flat-table:: BT.2020 Chromaticities
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - Color
+
+ - x
+
+ - y
+
+ - .. row 2
+
+ - Red
+
+ - 0.708
+
+ - 0.292
+
+ - .. row 3
+
+ - Green
+
+ - 0.170
+
+ - 0.797
+
+ - .. row 4
+
+ - Blue
+
+ - 0.131
+
+ - 0.046
+
+ - .. row 5
+
+ - White Reference (D65)
+
+ - 0.3127
+
+ - 0.3290
+
+
+
+Transfer function (same as Rec. 709):
+
+ L' = 4.5L for 0 ≤ L < 0.018
+
+ L' = 1.099L :sup:`0.45` - 0.099 for 0.018 ≤ L ≤ 1
+
+Inverse Transfer function:
+
+ L = L' / 4.5 for L' < 0.081
+
+ L = ((L' + 0.099) / 1.099) :sup:`1/0.45` for L' ≥ 0.081
+
+The luminance (Y') and color difference (Cb and Cr) are obtained with
+the following ``V4L2_YCBCR_ENC_BT2020`` encoding:
+
+ Y' = 0.2627R' + 0.6780G' + 0.0593B'
+
+ Cb = -0.1396R' - 0.3604G' + 0.5B'
+
+ Cr = 0.5R' - 0.4598G' - 0.0402B'
+
+Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
+[-0.5…0.5]. The Y'CbCr quantization is limited range.
+
+There is also an alternate constant luminance R'G'B' to Yc'CbcCrc
+(``V4L2_YCBCR_ENC_BT2020_CONST_LUM``) encoding:
+
+Luma:
+
+ Yc' = (0.2627R + 0.6780G + 0.0593B)'
+
+B' - Yc' ≤ 0:
+
+ Cbc = (B' - Yc') / 1.9404
+
+B' - Yc' > 0:
+
+ Cbc = (B' - Yc') / 1.5816
+
+R' - Yc' ≤ 0:
+
+ Crc = (R' - Y') / 1.7184
+
+R' - Yc' > 0:
+
+ Crc = (R' - Y') / 0.9936
+
+Yc' is clamped to the range [0…1] and Cbc and Crc are clamped to the
+range [-0.5…0.5]. The Yc'CbcCrc quantization is limited range.
+
+
+.. _col-dcip3:
+
+Colorspace DCI-P3 (V4L2_COLORSPACE_DCI_P3)
+==========================================
+
+The :ref:`smpte431` standard defines the colorspace used by cinema
+projectors that use the DCI-P3 colorspace. The default transfer function
+is ``V4L2_XFER_FUNC_DCI_P3``. The default Y'CbCr encoding is
+``V4L2_YCBCR_ENC_709``. Note that this colorspace does not specify a
+Y'CbCr encoding since it is not meant to be encoded to Y'CbCr. So this
+default Y'CbCr encoding was picked because it is the HDTV encoding. The
+default Y'CbCr quantization is limited range. The chromaticities of the
+primary colors and the white reference are:
+
+
+
+.. flat-table:: DCI-P3 Chromaticities
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - Color
+
+ - x
+
+ - y
+
+ - .. row 2
+
+ - Red
+
+ - 0.6800
+
+ - 0.3200
+
+ - .. row 3
+
+ - Green
+
+ - 0.2650
+
+ - 0.6900
+
+ - .. row 4
+
+ - Blue
+
+ - 0.1500
+
+ - 0.0600
+
+ - .. row 5
+
+ - White Reference
+
+ - 0.3140
+
+ - 0.3510
+
+
+
+Transfer function:
+
+ L' = L :sup:`1/2.6`
+
+Inverse Transfer function:
+
+ L = L' :sup:`2.6`
+
+Y'CbCr encoding is not specified. V4L2 defaults to Rec. 709.
+
+
+.. _col-smpte-240m:
+
+Colorspace SMPTE 240M (V4L2_COLORSPACE_SMPTE240M)
+=================================================
+
+The :ref:`smpte240m` standard was an interim standard used during the
+early days of HDTV (1988-1998). It has been superseded by Rec. 709. The
+default transfer function is ``V4L2_XFER_FUNC_SMPTE240M``. The default
+Y'CbCr encoding is ``V4L2_YCBCR_ENC_SMPTE240M``. The default Y'CbCr
+quantization is limited range. The chromaticities of the primary colors
+and the white reference are:
+
+
+
+.. flat-table:: SMPTE 240M Chromaticities
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - Color
+
+ - x
+
+ - y
+
+ - .. row 2
+
+ - Red
+
+ - 0.630
+
+ - 0.340
+
+ - .. row 3
+
+ - Green
+
+ - 0.310
+
+ - 0.595
+
+ - .. row 4
+
+ - Blue
+
+ - 0.155
+
+ - 0.070
+
+ - .. row 5
+
+ - White Reference (D65)
+
+ - 0.3127
+
+ - 0.3290
+
+
+These chromaticities are identical to the SMPTE 170M colorspace.
+
+Transfer function:
+
+ L' = 4L for 0 ≤ L < 0.0228
+
+ L' = 1.1115L :sup:`0.45` - 0.1115 for 0.0228 ≤ L ≤ 1
+
+Inverse Transfer function:
+
+ L = L' / 4 for 0 ≤ L' < 0.0913
+
+ L = ((L' + 0.1115) / 1.1115) :sup:`1/0.45` for L' ≥ 0.0913
+
+The luminance (Y') and color difference (Cb and Cr) are obtained with
+the following ``V4L2_YCBCR_ENC_SMPTE240M`` encoding:
+
+ Y' = 0.2122R' + 0.7013G' + 0.0865B'
+
+ Cb = -0.1161R' - 0.3839G' + 0.5B'
+
+ Cr = 0.5R' - 0.4451G' - 0.0549B'
+
+Yc' is clamped to the range [0…1] and Cbc and Crc are clamped to the
+range [-0.5…0.5]. The Y'CbCr quantization is limited range.
+
+
+.. _col-sysm:
+
+Colorspace NTSC 1953 (V4L2_COLORSPACE_470_SYSTEM_M)
+===================================================
+
+This standard defines the colorspace used by NTSC in 1953. In practice
+this colorspace is obsolete and SMPTE 170M should be used instead. The
+default transfer function is ``V4L2_XFER_FUNC_709``. The default Y'CbCr
+encoding is ``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is
+limited range. The chromaticities of the primary colors and the white
+reference are:
+
+
+
+.. flat-table:: NTSC 1953 Chromaticities
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - Color
+
+ - x
+
+ - y
+
+ - .. row 2
+
+ - Red
+
+ - 0.67
+
+ - 0.33
+
+ - .. row 3
+
+ - Green
+
+ - 0.21
+
+ - 0.71
+
+ - .. row 4
+
+ - Blue
+
+ - 0.14
+
+ - 0.08
+
+ - .. row 5
+
+ - White Reference (C)
+
+ - 0.310
+
+ - 0.316
+
+
+Note that this colorspace uses Illuminant C instead of D65 as the white
+reference. To correctly convert an image in this colorspace to another
+that uses D65 you need to apply a chromatic adaptation algorithm such as
+the Bradford method.
+
+The transfer function was never properly defined for NTSC 1953. The Rec.
+709 transfer function is recommended in the literature:
+
+ L' = 4.5L for 0 ≤ L < 0.018
+
+ L' = 1.099L :sup:`0.45` - 0.099 for 0.018 ≤ L ≤ 1
+
+Inverse Transfer function:
+
+ L = L' / 4.5 for L' < 0.081
+
+ L = ((L' + 0.099) / 1.099) :sup:`1/0.45` for L' ≥ 0.081
+
+The luminance (Y') and color difference (Cb and Cr) are obtained with
+the following ``V4L2_YCBCR_ENC_601`` encoding:
+
+ Y' = 0.299R' + 0.587G' + 0.114B'
+
+ Cb = -0.169R' - 0.331G' + 0.5B'
+
+ Cr = 0.5R' - 0.419G' - 0.081B'
+
+Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
+[-0.5…0.5]. The Y'CbCr quantization is limited range. This transform is
+identical to one defined in SMPTE 170M/BT.601.
+
+
+.. _col-sysbg:
+
+Colorspace EBU Tech. 3213 (V4L2_COLORSPACE_470_SYSTEM_BG)
+=========================================================
+
+The :ref:`tech3213` standard defines the colorspace used by PAL/SECAM
+in 1975. In practice this colorspace is obsolete and SMPTE 170M should
+be used instead. The default transfer function is
+``V4L2_XFER_FUNC_709``. The default Y'CbCr encoding is
+``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is limited
+range. The chromaticities of the primary colors and the white reference
+are:
+
+
+
+.. flat-table:: EBU Tech. 3213 Chromaticities
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - Color
+
+ - x
+
+ - y
+
+ - .. row 2
+
+ - Red
+
+ - 0.64
+
+ - 0.33
+
+ - .. row 3
+
+ - Green
+
+ - 0.29
+
+ - 0.60
+
+ - .. row 4
+
+ - Blue
+
+ - 0.15
+
+ - 0.06
+
+ - .. row 5
+
+ - White Reference (D65)
+
+ - 0.3127
+
+ - 0.3290
+
+
+
+The transfer function was never properly defined for this colorspace.
+The Rec. 709 transfer function is recommended in the literature:
+
+ L' = 4.5L for 0 ≤ L < 0.018
+
+ L' = 1.099L :sup:`0.45` - 0.099 for 0.018 ≤ L ≤ 1
+
+Inverse Transfer function:
+
+ L = L' / 4.5 for L' < 0.081
+
+ L = ((L' + 0.099) / 1.099) :sup:`1/0.45` for L' ≥ 0.081
+
+The luminance (Y') and color difference (Cb and Cr) are obtained with
+the following ``V4L2_YCBCR_ENC_601`` encoding:
+
+ Y' = 0.299R' + 0.587G' + 0.114B'
+
+ Cb = -0.169R' - 0.331G' + 0.5B'
+
+ Cr = 0.5R' - 0.419G' - 0.081B'
+
+Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
+[-0.5…0.5]. The Y'CbCr quantization is limited range. This transform is
+identical to one defined in SMPTE 170M/BT.601.
+
+
+.. _col-jpeg:
+
+Colorspace JPEG (V4L2_COLORSPACE_JPEG)
+======================================
+
+This colorspace defines the colorspace used by most (Motion-)JPEG
+formats. The chromaticities of the primary colors and the white
+reference are identical to sRGB. The transfer function use is
+``V4L2_XFER_FUNC_SRGB``. The Y'CbCr encoding is ``V4L2_YCBCR_ENC_601``
+with full range quantization where Y' is scaled to [0…255] and Cb/Cr are
+scaled to [-128…128] and then clipped to [-128…127].
+
+Note that the JPEG standard does not actually store colorspace
+information. So if something other than sRGB is used, then the driver
+will have to set that information explicitly. Effectively
+``V4L2_COLORSPACE_JPEG`` can be considered to be an abbreviation for
+``V4L2_COLORSPACE_SRGB``, ``V4L2_YCBCR_ENC_601`` and
+``V4L2_QUANTIZATION_FULL_RANGE``.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+***************************************
+Detailed Transfer Function Descriptions
+***************************************
+
+
+.. _xf-smpte-2084:
+
+Transfer Function SMPTE 2084 (V4L2_XFER_FUNC_SMPTE2084)
+=======================================================
+
+The :ref:`smpte2084` standard defines the transfer function used by
+High Dynamic Range content.
+
+Constants:
+ m1 = (2610 / 4096) / 4
+
+ m2 = (2523 / 4096) * 128
+
+ c1 = 3424 / 4096
+
+ c2 = (2413 / 4096) * 32
+
+ c3 = (2392 / 4096) * 32
+
+Transfer function:
+ L' = ((c1 + c2 * L\ :sup:`m1`) / (1 + c3 * L\ :sup:`m1`))\ :sup:`m2`
+
+Inverse Transfer function:
+ L = (max(L':sup:`1/m2` - c1, 0) / (c2 - c3 *
+ L'\ :sup:`1/m2`))\ :sup:`1/m1`
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+******************
+Compressed Formats
+******************
+
+
+.. _compressed-formats:
+
+.. flat-table:: Compressed Image Formats
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Code
+
+ - Details
+
+ - .. _V4L2-PIX-FMT-JPEG:
+
+ - ``V4L2_PIX_FMT_JPEG``
+
+ - 'JPEG'
+
+ - TBD. See also :ref:`VIDIOC_G_JPEGCOMP <VIDIOC_G_JPEGCOMP>`,
+ :ref:`VIDIOC_S_JPEGCOMP <VIDIOC_G_JPEGCOMP>`.
+
+ - .. _V4L2-PIX-FMT-MPEG:
+
+ - ``V4L2_PIX_FMT_MPEG``
+
+ - 'MPEG'
+
+ - MPEG multiplexed stream. The actual format is determined by
+ extended control ``V4L2_CID_MPEG_STREAM_TYPE``, see
+ :ref:`mpeg-control-id`.
+
+ - .. _V4L2-PIX-FMT-H264:
+
+ - ``V4L2_PIX_FMT_H264``
+
+ - 'H264'
+
+ - H264 video elementary stream with start codes.
+
+ - .. _V4L2-PIX-FMT-H264-NO-SC:
+
+ - ``V4L2_PIX_FMT_H264_NO_SC``
+
+ - 'AVC1'
+
+ - H264 video elementary stream without start codes.
+
+ - .. _V4L2-PIX-FMT-H264-MVC:
+
+ - ``V4L2_PIX_FMT_H264_MVC``
+
+ - 'M264'
+
+ - H264 MVC video elementary stream.
+
+ - .. _V4L2-PIX-FMT-H263:
+
+ - ``V4L2_PIX_FMT_H263``
+
+ - 'H263'
+
+ - H263 video elementary stream.
+
+ - .. _V4L2-PIX-FMT-MPEG1:
+
+ - ``V4L2_PIX_FMT_MPEG1``
+
+ - 'MPG1'
+
+ - MPEG1 video elementary stream.
+
+ - .. _V4L2-PIX-FMT-MPEG2:
+
+ - ``V4L2_PIX_FMT_MPEG2``
+
+ - 'MPG2'
+
+ - MPEG2 video elementary stream.
+
+ - .. _V4L2-PIX-FMT-MPEG4:
+
+ - ``V4L2_PIX_FMT_MPEG4``
+
+ - 'MPG4'
+
+ - MPEG4 video elementary stream.
+
+ - .. _V4L2-PIX-FMT-XVID:
+
+ - ``V4L2_PIX_FMT_XVID``
+
+ - 'XVID'
+
+ - Xvid video elementary stream.
+
+ - .. _V4L2-PIX-FMT-VC1-ANNEX-G:
+
+ - ``V4L2_PIX_FMT_VC1_ANNEX_G``
+
+ - 'VC1G'
+
+ - VC1, SMPTE 421M Annex G compliant stream.
+
+ - .. _V4L2-PIX-FMT-VC1-ANNEX-L:
+
+ - ``V4L2_PIX_FMT_VC1_ANNEX_L``
+
+ - 'VC1L'
+
+ - VC1, SMPTE 421M Annex L compliant stream.
+
+ - .. _V4L2-PIX-FMT-VP8:
+
+ - ``V4L2_PIX_FMT_VP8``
+
+ - 'VP80'
+
+ - VP8 video elementary stream.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-GREY:
+
+**************************
+V4L2_PIX_FMT_GREY ('GREY')
+**************************
+
+*man V4L2_PIX_FMT_GREY(2)*
+
+Grey-scale image
+
+
+Description
+===========
+
+This is a grey-scale image. It is really a degenerate Y'CbCr format
+which simply contains no Cb or Cr data.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Y'\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start + 4:
+
+ - Y'\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start + 8:
+
+ - Y'\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Y'\ :sub:`23`
+
+ - .. row 4
+
+ - start + 12:
+
+ - Y'\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Y'\ :sub:`33`
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _pixfmt-indexed:
+
+**************
+Indexed Format
+**************
+
+In this format each pixel is represented by an 8 bit index into a 256
+entry ARGB palette. It is intended for
+:ref:`Video Output Overlays <osd>` only. There are no ioctls to access
+the palette, this must be done with ioctls of the Linux framebuffer API.
+
+
+
+.. flat-table:: Indexed Image Format
+ :header-rows: 2
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Code
+
+ -
+ - :cspan:`7` Byte 0
+
+ - .. row 2
+
+ -
+ -
+ - Bit
+
+ - 7
+
+ - 6
+
+ - 5
+
+ - 4
+
+ - 3
+
+ - 2
+
+ - 1
+
+ - 0
+
+ - .. _V4L2-PIX-FMT-PAL8:
+
+ - ``V4L2_PIX_FMT_PAL8``
+
+ - 'PAL8'
+
+ -
+ - i\ :sub:`7`
+
+ - i\ :sub:`6`
+
+ - i\ :sub:`5`
+
+ - i\ :sub:`4`
+
+ - i\ :sub:`3`
+
+ - i\ :sub:`2`
+
+ - i\ :sub:`1`
+
+ - i\ :sub:`0`
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-M420:
+
+**************************
+V4L2_PIX_FMT_M420 ('M420')
+**************************
+
+*man V4L2_PIX_FMT_M420(2)*
+
+Format with ½ horizontal and vertical chroma resolution, also known as
+YUV 4:2:0. Hybrid plane line-interleaved layout.
+
+
+Description
+===========
+
+M420 is a YUV format with ½ horizontal and vertical chroma subsampling
+(YUV 4:2:0). Pixels are organized as interleaved luma and chroma planes.
+Two lines of luma data are followed by one line of chroma data.
+
+The luma plane has one byte per pixel. The chroma plane contains
+interleaved CbCr pixels subsampled by ½ in the horizontal and vertical
+directions. Each CbCr pair belongs to four pixels. For example,
+Cb\ :sub:`0`/Cr\ :sub:`0` belongs to Y'\ :sub:`00`, Y'\ :sub:`01`,
+Y'\ :sub:`10`, Y'\ :sub:`11`.
+
+All line lengths are identical: if the Y lines include pad bytes so do
+the CbCr lines.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Y'\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start + 4:
+
+ - Y'\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start + 8:
+
+ - Cb\ :sub:`00`
+
+ - Cr\ :sub:`00`
+
+ - Cb\ :sub:`01`
+
+ - Cr\ :sub:`01`
+
+ - .. row 4
+
+ - start + 16:
+
+ - Y'\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Y'\ :sub:`23`
+
+ - .. row 5
+
+ - start + 20:
+
+ - Y'\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Y'\ :sub:`33`
+
+ - .. row 6
+
+ - start + 24:
+
+ - Cb\ :sub:`10`
+
+ - Cr\ :sub:`10`
+
+ - Cb\ :sub:`11`
+
+ - Cr\ :sub:`11`
+
+
+**Color Sample Location..**
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ -
+ - 1
+
+ - 2
+
+ -
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ -
+ - Y
+
+ - Y
+
+ -
+ - Y
+
+ - .. row 3
+
+ -
+ -
+ - C
+
+ -
+ -
+ - C
+
+ -
+
+ - .. row 4
+
+ - 1
+
+ - Y
+
+ -
+ - Y
+
+ - Y
+
+ -
+ - Y
+
+ - .. row 5
+
+ -
+
+ - .. row 6
+
+ - 2
+
+ - Y
+
+ -
+ - Y
+
+ - Y
+
+ -
+ - Y
+
+ - .. row 7
+
+ -
+ -
+ - C
+
+ -
+ -
+ - C
+
+ -
+
+ - .. row 8
+
+ - 3
+
+ - Y
+
+ -
+ - Y
+
+ - Y
+
+ -
+ - Y
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-NV12:
+.. _V4L2-PIX-FMT-NV21:
+
+******************************************************
+V4L2_PIX_FMT_NV12 ('NV12'), V4L2_PIX_FMT_NV21 ('NV21')
+******************************************************
+
+*man V4L2_PIX_FMT_NV12(2)*
+
+V4L2_PIX_FMT_NV21
+Formats with ½ horizontal and vertical chroma resolution, also known as
+YUV 4:2:0. One luminance and one chrominance plane with alternating
+chroma samples as opposed to ``V4L2_PIX_FMT_YVU420``
+
+
+Description
+===========
+
+These are two-plane versions of the YUV 4:2:0 format. The three
+components are separated into two sub-images or planes. The Y plane is
+first. The Y plane has one byte per pixel. For ``V4L2_PIX_FMT_NV12``, a
+combined CbCr plane immediately follows the Y plane in memory. The CbCr
+plane is the same width, in bytes, as the Y plane (and of the image),
+but is half as tall in pixels. Each CbCr pair belongs to four pixels.
+For example, Cb\ :sub:`0`/Cr\ :sub:`0` belongs to Y'\ :sub:`00`,
+Y'\ :sub:`01`, Y'\ :sub:`10`, Y'\ :sub:`11`. ``V4L2_PIX_FMT_NV21`` is
+the same except the Cb and Cr bytes are swapped, the CrCb plane starts
+with a Cr byte.
+
+If the Y plane has pad bytes after each row, then the CbCr plane has as
+many pad bytes after its rows.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Y'\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start + 4:
+
+ - Y'\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start + 8:
+
+ - Y'\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Y'\ :sub:`23`
+
+ - .. row 4
+
+ - start + 12:
+
+ - Y'\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Y'\ :sub:`33`
+
+ - .. row 5
+
+ - start + 16:
+
+ - Cb\ :sub:`00`
+
+ - Cr\ :sub:`00`
+
+ - Cb\ :sub:`01`
+
+ - Cr\ :sub:`01`
+
+ - .. row 6
+
+ - start + 20:
+
+ - Cb\ :sub:`10`
+
+ - Cr\ :sub:`10`
+
+ - Cb\ :sub:`11`
+
+ - Cr\ :sub:`11`
+
+
+**Color Sample Location..**
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ -
+ - 1
+
+ - 2
+
+ -
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ -
+ - Y
+
+ - Y
+
+ -
+ - Y
+
+ - .. row 3
+
+ -
+ -
+ - C
+
+ -
+ -
+ - C
+
+ -
+
+ - .. row 4
+
+ - 1
+
+ - Y
+ -
+
+ - Y
+
+ - Y
+
+ -
+ - Y
+
+ - .. row 5
+
+ -
+
+ - .. row 6
+
+ - 2
+
+ - Y
+ -
+
+ - Y
+
+ - Y
+
+ -
+ - Y
+
+ - .. row 7
+
+ -
+ -
+ - C
+
+ -
+ -
+ - C
+
+ -
+
+ - .. row 8
+
+ - 3
+
+ - Y
+
+ -
+ - Y
+
+ - Y
+
+ -
+ - Y
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-NV12M:
+.. _v4l2-pix-fmt-nv12mt-16x16:
+.. _V4L2-PIX-FMT-NV21M:
+
+***********************************************************************************
+V4L2_PIX_FMT_NV12M ('NM12'), V4L2_PIX_FMT_NV21M ('NM21'), V4L2_PIX_FMT_NV12MT_16X16
+***********************************************************************************
+
+*man V4L2_PIX_FMT_NV12M(2)*
+
+V4L2_PIX_FMT_NV21M
+V4L2_PIX_FMT_NV12MT_16X16
+Variation of ``V4L2_PIX_FMT_NV12`` and ``V4L2_PIX_FMT_NV21`` with planes
+non contiguous in memory.
+
+
+Description
+===========
+
+This is a multi-planar, two-plane version of the YUV 4:2:0 format. The
+three components are separated into two sub-images or planes.
+``V4L2_PIX_FMT_NV12M`` differs from ``V4L2_PIX_FMT_NV12`` in that the
+two planes are non-contiguous in memory, i.e. the chroma plane do not
+necessarily immediately follows the luma plane. The luminance data
+occupies the first plane. The Y plane has one byte per pixel. In the
+second plane there is a chrominance data with alternating chroma
+samples. The CbCr plane is the same width, in bytes, as the Y plane (and
+of the image), but is half as tall in pixels. Each CbCr pair belongs to
+four pixels. For example, Cb\ :sub:`0`/Cr\ :sub:`0` belongs to
+Y'\ :sub:`00`, Y'\ :sub:`01`, Y'\ :sub:`10`, Y'\ :sub:`11`.
+``V4L2_PIX_FMT_NV12MT_16X16`` is the tiled version of
+``V4L2_PIX_FMT_NV12M`` with 16x16 macroblock tiles. Here pixels are
+arranged in 16x16 2D tiles and tiles are arranged in linear order in
+memory. ``V4L2_PIX_FMT_NV21M`` is the same as ``V4L2_PIX_FMT_NV12M``
+except the Cb and Cr bytes are swapped, the CrCb plane starts with a Cr
+byte.
+
+``V4L2_PIX_FMT_NV12M`` is intended to be used only in drivers and
+applications that support the multi-planar API, described in
+:ref:`planar-apis`.
+
+If the Y plane has pad bytes after each row, then the CbCr plane has as
+many pad bytes after its rows.
+
+**Byte Order.**
+Each cell is one byte.
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start0 + 0:
+
+ - Y'\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start0 + 4:
+
+ - Y'\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start0 + 8:
+
+ - Y'\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Y'\ :sub:`23`
+
+ - .. row 4
+
+ - start0 + 12:
+
+ - Y'\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Y'\ :sub:`33`
+
+ - .. row 5
+
+ -
+
+ - .. row 6
+
+ - start1 + 0:
+
+ - Cb\ :sub:`00`
+
+ - Cr\ :sub:`00`
+
+ - Cb\ :sub:`01`
+
+ - Cr\ :sub:`01`
+
+ - .. row 7
+
+ - start1 + 4:
+
+ - Cb\ :sub:`10`
+
+ - Cr\ :sub:`10`
+
+ - Cb\ :sub:`11`
+
+ - Cr\ :sub:`11`
+
+
+**Color Sample Location..**
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ -
+ - 1
+
+ - 2
+
+ -
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ -
+ - Y
+
+ - Y
+
+ -
+ - Y
+
+ - .. row 3
+
+ -
+ -
+ - C
+
+ -
+ -
+ - C
+
+ -
+
+ - .. row 4
+
+ - 1
+
+ - Y
+
+ -
+ - Y
+
+ - Y
+
+ -
+ - Y
+
+ - .. row 5
+
+ -
+
+ - .. row 6
+
+ - 2
+
+ - Y
+
+ -
+ - Y
+
+ - Y
+
+ -
+ - Y
+
+ - .. row 7
+
+ -
+ -
+ - C
+
+ -
+ -
+ -
+ - C
+
+ -
+
+ - .. row 8
+
+ - 3
+
+ - Y
+
+ -
+ - Y
+
+ - Y
+
+ -
+ - Y
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-NV12MT:
+
+****************************
+V4L2_PIX_FMT_NV12MT ('TM12')
+****************************
+
+*man V4L2_PIX_FMT_NV12MT(2)*
+
+Formats with ½ horizontal and vertical chroma resolution. This format
+has two planes - one for luminance and one for chrominance. Chroma
+samples are interleaved. The difference to ``V4L2_PIX_FMT_NV12`` is the
+memory layout. Pixels are grouped in macroblocks of 64x32 size. The
+order of macroblocks in memory is also not standard.
+
+
+Description
+===========
+
+This is the two-plane versions of the YUV 4:2:0 format where data is
+grouped into 64x32 macroblocks. The three components are separated into
+two sub-images or planes. The Y plane has one byte per pixel and pixels
+are grouped into 64x32 macroblocks. The CbCr plane has the same width,
+in bytes, as the Y plane (and the image), but is half as tall in pixels.
+The chroma plane is also grouped into 64x32 macroblocks.
+
+Width of the buffer has to be aligned to the multiple of 128, and height
+alignment is 32. Every four adjacent buffers - two horizontally and two
+vertically are grouped together and are located in memory in Z or
+flipped Z order.
+
+Layout of macroblocks in memory is presented in the following figure.
+
+
+.. _nv12mt:
+
+.. figure:: pixfmt-nv12mt_files/nv12mt.*
+ :alt: nv12mt.gif
+ :align: center
+
+ V4L2_PIX_FMT_NV12MT macroblock Z shape memory layout
+
+The requirement that width is multiple of 128 is implemented because,
+the Z shape cannot be cut in half horizontally. In case the vertical
+resolution of macroblocks is odd then the last row of macroblocks is
+arranged in a linear order.
+
+In case of chroma the layout is identical. Cb and Cr samples are
+interleaved. Height of the buffer is aligned to 32.
+
+
+.. _nv12mt_ex:
+
+.. figure:: pixfmt-nv12mt_files/nv12mt_example.*
+ :alt: nv12mt_example.gif
+ :align: center
+
+ Example V4L2_PIX_FMT_NV12MT memory layout of macroblocks
+
+Memory layout of macroblocks of ``V4L2_PIX_FMT_NV12MT`` format in most
+extreme case.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-NV16:
+.. _V4L2-PIX-FMT-NV61:
+
+******************************************************
+V4L2_PIX_FMT_NV16 ('NV16'), V4L2_PIX_FMT_NV61 ('NV61')
+******************************************************
+
+*man V4L2_PIX_FMT_NV16(2)*
+
+V4L2_PIX_FMT_NV61
+Formats with ½ horizontal chroma resolution, also known as YUV 4:2:2.
+One luminance and one chrominance plane with alternating chroma samples
+as opposed to ``V4L2_PIX_FMT_YVU420``
+
+
+Description
+===========
+
+These are two-plane versions of the YUV 4:2:2 format. The three
+components are separated into two sub-images or planes. The Y plane is
+first. The Y plane has one byte per pixel. For ``V4L2_PIX_FMT_NV16``, a
+combined CbCr plane immediately follows the Y plane in memory. The CbCr
+plane is the same width and height, in bytes, as the Y plane (and of the
+image). Each CbCr pair belongs to two pixels. For example,
+Cb\ :sub:`0`/Cr\ :sub:`0` belongs to Y'\ :sub:`00`, Y'\ :sub:`01`.
+``V4L2_PIX_FMT_NV61`` is the same except the Cb and Cr bytes are
+swapped, the CrCb plane starts with a Cr byte.
+
+If the Y plane has pad bytes after each row, then the CbCr plane has as
+many pad bytes after its rows.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Y'\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start + 4:
+
+ - Y'\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start + 8:
+
+ - Y'\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Y'\ :sub:`23`
+
+ - .. row 4
+
+ - start + 12:
+
+ - Y'\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Y'\ :sub:`33`
+
+ - .. row 5
+
+ - start + 16:
+
+ - Cb\ :sub:`00`
+
+ - Cr\ :sub:`00`
+
+ - Cb\ :sub:`01`
+
+ - Cr\ :sub:`01`
+
+ - .. row 6
+
+ - start + 20:
+
+ - Cb\ :sub:`10`
+
+ - Cr\ :sub:`10`
+
+ - Cb\ :sub:`11`
+
+ - Cr\ :sub:`11`
+
+ - .. row 7
+
+ - start + 24:
+
+ - Cb\ :sub:`20`
+
+ - Cr\ :sub:`20`
+
+ - Cb\ :sub:`21`
+
+ - Cr\ :sub:`21`
+
+ - .. row 8
+
+ - start + 28:
+
+ - Cb\ :sub:`30`
+
+ - Cr\ :sub:`30`
+
+ - Cb\ :sub:`31`
+
+ - Cr\ :sub:`31`
+
+
+**Color Sample Location..**
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ -
+ - 1
+
+ - 2
+
+ -
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ -
+ - Y
+
+ - Y
+
+ -
+ - Y
+
+ - .. row 3
+
+ -
+ -
+ - C
+
+ -
+ -
+ - C
+
+ -
+
+ - .. row 4
+
+ - 1
+
+ - Y
+
+ -
+ - Y
+
+ - Y
+
+ -
+ - Y
+
+ - .. row 5
+
+ -
+ -
+ - C
+
+ -
+ -
+ - C
+
+ -
+
+ - .. row 6
+
+ -
+
+ - .. row 7
+
+ - 2
+
+ - Y
+
+ -
+ - Y
+
+ - Y
+
+ -
+ - Y
+
+ - .. row 8
+
+ -
+ -
+ - C
+
+ -
+ -
+ - C
+
+ -
+
+ - .. row 9
+
+ - 3
+
+ - Y
+
+ -
+ - Y
+
+ - Y
+
+ -
+ - Y
+
+ - .. row 10
+
+ -
+ -
+ - C
+
+ -
+ -
+ - C
+
+ -
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-NV16M:
+.. _v4l2-pix-fmt-nv61m:
+
+********************************************************
+V4L2_PIX_FMT_NV16M ('NM16'), V4L2_PIX_FMT_NV61M ('NM61')
+********************************************************
+
+*man V4L2_PIX_FMT_NV16M(2)*
+
+V4L2_PIX_FMT_NV61M
+Variation of ``V4L2_PIX_FMT_NV16`` and ``V4L2_PIX_FMT_NV61`` with planes
+non contiguous in memory.
+
+
+Description
+===========
+
+This is a multi-planar, two-plane version of the YUV 4:2:2 format. The
+three components are separated into two sub-images or planes.
+``V4L2_PIX_FMT_NV16M`` differs from ``V4L2_PIX_FMT_NV16`` in that the
+two planes are non-contiguous in memory, i.e. the chroma plane does not
+necessarily immediately follow the luma plane. The luminance data
+occupies the first plane. The Y plane has one byte per pixel. In the
+second plane there is chrominance data with alternating chroma samples.
+The CbCr plane is the same width and height, in bytes, as the Y plane.
+Each CbCr pair belongs to two pixels. For example,
+Cb\ :sub:`0`/Cr\ :sub:`0` belongs to Y'\ :sub:`00`, Y'\ :sub:`01`.
+``V4L2_PIX_FMT_NV61M`` is the same as ``V4L2_PIX_FMT_NV16M`` except the
+Cb and Cr bytes are swapped, the CrCb plane starts with a Cr byte.
+
+``V4L2_PIX_FMT_NV16M`` and ``V4L2_PIX_FMT_NV61M`` are intended to be
+used only in drivers and applications that support the multi-planar API,
+described in :ref:`planar-apis`.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start0 + 0:
+
+ - Y'\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start0 + 4:
+
+ - Y'\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start0 + 8:
+
+ - Y'\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Y'\ :sub:`23`
+
+ - .. row 4
+
+ - start0 + 12:
+
+ - Y'\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Y'\ :sub:`33`
+
+ - .. row 5
+
+ -
+
+ - .. row 6
+
+ - start1 + 0:
+
+ - Cb\ :sub:`00`
+
+ - Cr\ :sub:`00`
+
+ - Cb\ :sub:`02`
+
+ - Cr\ :sub:`02`
+
+ - .. row 7
+
+ - start1 + 4:
+
+ - Cb\ :sub:`10`
+
+ - Cr\ :sub:`10`
+
+ - Cb\ :sub:`12`
+
+ - Cr\ :sub:`12`
+
+ - .. row 8
+
+ - start1 + 8:
+
+ - Cb\ :sub:`20`
+
+ - Cr\ :sub:`20`
+
+ - Cb\ :sub:`22`
+
+ - Cr\ :sub:`22`
+
+ - .. row 9
+
+ - start1 + 12:
+
+ - Cb\ :sub:`30`
+
+ - Cr\ :sub:`30`
+
+ - Cb\ :sub:`32`
+
+ - Cr\ :sub:`32`
+
+
+**Color Sample Location..**
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ -
+ - 1
+
+ - 2
+
+ -
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ -
+ - Y
+
+ - Y
+
+ -
+ - Y
+
+ - .. row 3
+
+ -
+ -
+ - C
+
+ -
+ -
+ - C
+
+ -
+
+ - .. row 4
+
+ - 1
+
+ - Y
+
+ -
+ - Y
+
+ - Y
+
+ -
+ - Y
+
+ - .. row 5
+
+ -
+ -
+ - C
+
+ -
+ -
+ - C
+
+ -
+
+ - .. row 6
+
+ -
+
+ - .. row 7
+
+ - 2
+
+ - Y
+
+ -
+ - Y
+
+ - Y
+
+ -
+ - Y
+
+ - .. row 8
+
+ -
+ -
+ - C
+
+ -
+ -
+ - C
+
+ -
+
+ - .. row 9
+
+ - 3
+
+ - Y
+
+ -
+ - Y
+
+ - Y
+
+ -
+ - Y
+
+ - .. row 10
+
+ -
+ -
+ - C
+
+ -
+ -
+ - C
+
+ -
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-NV24:
+.. _V4L2-PIX-FMT-NV42:
+
+******************************************************
+V4L2_PIX_FMT_NV24 ('NV24'), V4L2_PIX_FMT_NV42 ('NV42')
+******************************************************
+
+*man V4L2_PIX_FMT_NV24(2)*
+
+V4L2_PIX_FMT_NV42
+Formats with full horizontal and vertical chroma resolutions, also known
+as YUV 4:4:4. One luminance and one chrominance plane with alternating
+chroma samples as opposed to ``V4L2_PIX_FMT_YVU420``
+
+
+Description
+===========
+
+These are two-plane versions of the YUV 4:4:4 format. The three
+components are separated into two sub-images or planes. The Y plane is
+first, with each Y sample stored in one byte per pixel. For
+``V4L2_PIX_FMT_NV24``, a combined CbCr plane immediately follows the Y
+plane in memory. The CbCr plane has the same width and height, in
+pixels, as the Y plane (and the image). Each line contains one CbCr pair
+per pixel, with each Cb and Cr sample stored in one byte.
+``V4L2_PIX_FMT_NV42`` is the same except that the Cb and Cr samples are
+swapped, the CrCb plane starts with a Cr sample.
+
+If the Y plane has pad bytes after each row, then the CbCr plane has
+twice as many pad bytes after its rows.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Y'\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start + 4:
+
+ - Y'\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start + 8:
+
+ - Y'\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Y'\ :sub:`23`
+
+ - .. row 4
+
+ - start + 12:
+
+ - Y'\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Y'\ :sub:`33`
+
+ - .. row 5
+
+ - start + 16:
+
+ - Cb\ :sub:`00`
+
+ - Cr\ :sub:`00`
+
+ - Cb\ :sub:`01`
+
+ - Cr\ :sub:`01`
+
+ - Cb\ :sub:`02`
+
+ - Cr\ :sub:`02`
+
+ - Cb\ :sub:`03`
+
+ - Cr\ :sub:`03`
+
+ - .. row 6
+
+ - start + 24:
+
+ - Cb\ :sub:`10`
+
+ - Cr\ :sub:`10`
+
+ - Cb\ :sub:`11`
+
+ - Cr\ :sub:`11`
+
+ - Cb\ :sub:`12`
+
+ - Cr\ :sub:`12`
+
+ - Cb\ :sub:`13`
+
+ - Cr\ :sub:`13`
+
+ - .. row 7
+
+ - start + 32:
+
+ - Cb\ :sub:`20`
+
+ - Cr\ :sub:`20`
+
+ - Cb\ :sub:`21`
+
+ - Cr\ :sub:`21`
+
+ - Cb\ :sub:`22`
+
+ - Cr\ :sub:`22`
+
+ - Cb\ :sub:`23`
+
+ - Cr\ :sub:`23`
+
+ - .. row 8
+
+ - start + 40:
+
+ - Cb\ :sub:`30`
+
+ - Cr\ :sub:`30`
+
+ - Cb\ :sub:`31`
+
+ - Cr\ :sub:`31`
+
+ - Cb\ :sub:`32`
+
+ - Cr\ :sub:`32`
+
+ - Cb\ :sub:`33`
+
+ - Cr\ :sub:`33`
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _packed-rgb:
+
+******************
+Packed RGB formats
+******************
+
+*man Packed RGB formats(2)*
+
+Packed RGB formats
+
+
+Description
+===========
+
+These formats are designed to match the pixel formats of typical PC
+graphics frame buffers. They occupy 8, 16, 24 or 32 bits per pixel.
+These are all packed-pixel formats, meaning all the data for a pixel lie
+next to each other in memory.
+
+
+.. _rgb-formats:
+
+.. flat-table:: Packed RGB Image Formats
+ :header-rows: 2
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Code
+
+ -
+ - :cspan:`7` Byte 0 in memory
+
+ - :cspan:`7` Byte 1
+
+ - :cspan:`7` Byte 2
+
+ - :cspan:`7` Byte 3
+
+ - .. row 2
+
+ -
+ -
+ - Bit
+
+ - 7
+
+ - 6
+
+ - 5
+
+ - 4
+
+ - 3
+
+ - 2
+
+ - 1
+
+ - 0
+
+ -
+ - 7
+
+ - 6
+
+ - 5
+
+ - 4
+
+ - 3
+
+ - 2
+
+ - 1
+
+ - 0
+
+ -
+ - 7
+
+ - 6
+
+ - 5
+
+ - 4
+
+ - 3
+
+ - 2
+
+ - 1
+
+ - 0
+
+ -
+ - 7
+
+ - 6
+
+ - 5
+
+ - 4
+
+ - 3
+
+ - 2
+
+ - 1
+
+ - 0
+
+ - .. _V4L2-PIX-FMT-RGB332:
+
+ - ``V4L2_PIX_FMT_RGB332``
+
+ - 'RGB1'
+
+ -
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _V4L2-PIX-FMT-ARGB444:
+
+ - ``V4L2_PIX_FMT_ARGB444``
+
+ - 'AR12'
+
+ -
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ -
+ - a\ :sub:`3`
+
+ - a\ :sub:`2`
+
+ - a\ :sub:`1`
+
+ - a\ :sub:`0`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - .. _V4L2-PIX-FMT-XRGB444:
+
+ - ``V4L2_PIX_FMT_XRGB444``
+
+ - 'XR12'
+
+ -
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - .. _V4L2-PIX-FMT-ARGB555:
+
+ - ``V4L2_PIX_FMT_ARGB555``
+
+ - 'AR15'
+
+ -
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ -
+ - a
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - .. _V4L2-PIX-FMT-XRGB555:
+
+ - ``V4L2_PIX_FMT_XRGB555``
+
+ - 'XR15'
+
+ -
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ -
+ - -
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - .. _V4L2-PIX-FMT-RGB565:
+
+ - ``V4L2_PIX_FMT_RGB565``
+
+ - 'RGBP'
+
+ -
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ -
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - .. _V4L2-PIX-FMT-ARGB555X:
+
+ - ``V4L2_PIX_FMT_ARGB555X``
+
+ - 'AR15' | (1 << 31)
+
+ -
+ - a
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ -
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _V4L2-PIX-FMT-XRGB555X:
+
+ - ``V4L2_PIX_FMT_XRGB555X``
+
+ - 'XR15' | (1 << 31)
+
+ -
+ - -
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ -
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _V4L2-PIX-FMT-RGB565X:
+
+ - ``V4L2_PIX_FMT_RGB565X``
+
+ - 'RGBR'
+
+ -
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ -
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _V4L2-PIX-FMT-BGR24:
+
+ - ``V4L2_PIX_FMT_BGR24``
+
+ - 'BGR3'
+
+ -
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ -
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ -
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - .. _V4L2-PIX-FMT-RGB24:
+
+ - ``V4L2_PIX_FMT_RGB24``
+
+ - 'RGB3'
+
+ -
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ -
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ -
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _V4L2-PIX-FMT-BGR666:
+
+ - ``V4L2_PIX_FMT_BGR666``
+
+ - 'BGRH'
+
+ -
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ -
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ -
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - .. _V4L2-PIX-FMT-ABGR32:
+
+ - ``V4L2_PIX_FMT_ABGR32``
+
+ - 'AR24'
+
+ -
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ -
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ -
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ -
+ - a\ :sub:`7`
+
+ - a\ :sub:`6`
+
+ - a\ :sub:`5`
+
+ - a\ :sub:`4`
+
+ - a\ :sub:`3`
+
+ - a\ :sub:`2`
+
+ - a\ :sub:`1`
+
+ - a\ :sub:`0`
+
+ - .. _V4L2-PIX-FMT-XBGR32:
+
+ - ``V4L2_PIX_FMT_XBGR32``
+
+ - 'XR24'
+
+ -
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ -
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ -
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - .. _V4L2-PIX-FMT-ARGB32:
+
+ - ``V4L2_PIX_FMT_ARGB32``
+
+ - 'BA24'
+
+ -
+ - a\ :sub:`7`
+
+ - a\ :sub:`6`
+
+ - a\ :sub:`5`
+
+ - a\ :sub:`4`
+
+ - a\ :sub:`3`
+
+ - a\ :sub:`2`
+
+ - a\ :sub:`1`
+
+ - a\ :sub:`0`
+
+ -
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ -
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ -
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _V4L2-PIX-FMT-XRGB32:
+
+ - ``V4L2_PIX_FMT_XRGB32``
+
+ - 'BX24'
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ -
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ -
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ -
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+
+Bit 7 is the most significant bit.
+
+The usage and value of the alpha bits (a) in the ARGB and ABGR formats
+(collectively referred to as alpha formats) depend on the device type
+and hardware operation. :ref:`Capture <capture>` devices (including
+capture queues of mem-to-mem devices) fill the alpha component in
+memory. When the device outputs an alpha channel the alpha component
+will have a meaningful value. Otherwise, when the device doesn't output
+an alpha channel but can set the alpha bit to a user-configurable value,
+the :ref:`V4L2_CID_ALPHA_COMPONENT <v4l2-alpha-component>` control
+is used to specify that alpha value, and the alpha component of all
+pixels will be set to the value specified by that control. Otherwise a
+corresponding format without an alpha component (XRGB or XBGR) must be
+used instead of an alpha format.
+
+:ref:`Output <output>` devices (including output queues of mem-to-mem
+devices and :ref:`video output overlay <osd>` devices) read the alpha
+component from memory. When the device processes the alpha channel the
+alpha component must be filled with meaningful values by applications.
+Otherwise a corresponding format without an alpha component (XRGB or
+XBGR) must be used instead of an alpha format.
+
+The XRGB and XBGR formats contain undefined bits (-). Applications,
+devices and drivers must ignore those bits, for both
+:ref:`capture` and :ref:`output` devices.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - B\ :sub:`00`
+
+ - G\ :sub:`00`
+
+ - R\ :sub:`00`
+
+ - B\ :sub:`01`
+
+ - G\ :sub:`01`
+
+ - R\ :sub:`01`
+
+ - B\ :sub:`02`
+
+ - G\ :sub:`02`
+
+ - R\ :sub:`02`
+
+ - B\ :sub:`03`
+
+ - G\ :sub:`03`
+
+ - R\ :sub:`03`
+
+ - .. row 2
+
+ - start + 12:
+
+ - B\ :sub:`10`
+
+ - G\ :sub:`10`
+
+ - R\ :sub:`10`
+
+ - B\ :sub:`11`
+
+ - G\ :sub:`11`
+
+ - R\ :sub:`11`
+
+ - B\ :sub:`12`
+
+ - G\ :sub:`12`
+
+ - R\ :sub:`12`
+
+ - B\ :sub:`13`
+
+ - G\ :sub:`13`
+
+ - R\ :sub:`13`
+
+ - .. row 3
+
+ - start + 24:
+
+ - B\ :sub:`20`
+
+ - G\ :sub:`20`
+
+ - R\ :sub:`20`
+
+ - B\ :sub:`21`
+
+ - G\ :sub:`21`
+
+ - R\ :sub:`21`
+
+ - B\ :sub:`22`
+
+ - G\ :sub:`22`
+
+ - R\ :sub:`22`
+
+ - B\ :sub:`23`
+
+ - G\ :sub:`23`
+
+ - R\ :sub:`23`
+
+ - .. row 4
+
+ - start + 36:
+
+ - B\ :sub:`30`
+
+ - G\ :sub:`30`
+
+ - R\ :sub:`30`
+
+ - B\ :sub:`31`
+
+ - G\ :sub:`31`
+
+ - R\ :sub:`31`
+
+ - B\ :sub:`32`
+
+ - G\ :sub:`32`
+
+ - R\ :sub:`32`
+
+ - B\ :sub:`33`
+
+ - G\ :sub:`33`
+
+ - R\ :sub:`33`
+
+
+Formats defined in :ref:`rgb-formats-deprecated` are deprecated and
+must not be used by new drivers. They are documented here for reference.
+The meaning of their alpha bits (a) is ill-defined and interpreted as in
+either the corresponding ARGB or XRGB format, depending on the driver.
+
+
+.. _rgb-formats-deprecated:
+
+.. flat-table:: Deprecated Packed RGB Image Formats
+ :header-rows: 2
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Code
+
+ -
+ - :cspan:`7` Byte 0 in memory
+
+ - :cspan:`7` Byte 1
+
+ - :cspan:`7` Byte 2
+
+ - :cspan:`7` Byte 3
+
+ - .. row 2
+
+ -
+ -
+ - Bit
+
+ - 7
+
+ - 6
+
+ - 5
+
+ - 4
+
+ - 3
+
+ - 2
+
+ - 1
+
+ - 0
+
+ -
+ - 7
+
+ - 6
+
+ - 5
+
+ - 4
+
+ - 3
+
+ - 2
+
+ - 1
+
+ - 0
+
+ -
+ - 7
+
+ - 6
+
+ - 5
+
+ - 4
+
+ - 3
+
+ - 2
+
+ - 1
+
+ - 0
+
+ -
+ - 7
+
+ - 6
+
+ - 5
+
+ - 4
+
+ - 3
+
+ - 2
+
+ - 1
+
+ - 0
+
+ - .. _V4L2-PIX-FMT-RGB444:
+
+ - ``V4L2_PIX_FMT_RGB444``
+
+ - 'R444'
+
+ -
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ -
+ - a\ :sub:`3`
+
+ - a\ :sub:`2`
+
+ - a\ :sub:`1`
+
+ - a\ :sub:`0`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - .. _V4L2-PIX-FMT-RGB555:
+
+ - ``V4L2_PIX_FMT_RGB555``
+
+ - 'RGBO'
+
+ -
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ -
+ - a
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - .. _V4L2-PIX-FMT-RGB555X:
+
+ - ``V4L2_PIX_FMT_RGB555X``
+
+ - 'RGBQ'
+
+ -
+ - a
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ -
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _V4L2-PIX-FMT-BGR32:
+
+ - ``V4L2_PIX_FMT_BGR32``
+
+ - 'BGR4'
+
+ -
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ -
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ -
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ -
+ - a\ :sub:`7`
+
+ - a\ :sub:`6`
+
+ - a\ :sub:`5`
+
+ - a\ :sub:`4`
+
+ - a\ :sub:`3`
+
+ - a\ :sub:`2`
+
+ - a\ :sub:`1`
+
+ - a\ :sub:`0`
+
+ - .. _V4L2-PIX-FMT-RGB32:
+
+ - ``V4L2_PIX_FMT_RGB32``
+
+ - 'RGB4'
+
+ -
+ - a\ :sub:`7`
+
+ - a\ :sub:`6`
+
+ - a\ :sub:`5`
+
+ - a\ :sub:`4`
+
+ - a\ :sub:`3`
+
+ - a\ :sub:`2`
+
+ - a\ :sub:`1`
+
+ - a\ :sub:`0`
+
+ -
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ -
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ -
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+
+A test utility to determine which RGB formats a driver actually supports
+is available from the LinuxTV v4l-dvb repository. See
+`https://linuxtv.org/repo/ <https://linuxtv.org/repo/>`__ for access
+instructions.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _packed-yuv:
+
+******************
+Packed YUV formats
+******************
+
+*man Packed YUV formats(2)*
+
+Packed YUV formats
+
+
+Description
+===========
+
+Similar to the packed RGB formats these formats store the Y, Cb and Cr
+component of each pixel in one 16 or 32 bit word.
+
+
+
+.. flat-table:: Packed YUV Image Formats
+ :header-rows: 2
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Code
+
+ -
+ - :cspan:`7` Byte 0 in memory
+
+ -
+ - :cspan:`7` Byte 1
+
+ -
+ - :cspan:`7` Byte 2
+
+ -
+ - :cspan:`7` Byte 3
+
+ - .. row 2
+
+ -
+ -
+ - Bit
+
+ - 7
+
+ - 6
+
+ - 5
+
+ - 4
+
+ - 3
+
+ - 2
+
+ - 1
+
+ - 0
+
+ -
+ - 7
+
+ - 6
+
+ - 5
+
+ - 4
+
+ - 3
+
+ - 2
+
+ - 1
+
+ - 0
+
+ -
+ - 7
+
+ - 6
+
+ - 5
+
+ - 4
+
+ - 3
+
+ - 2
+
+ - 1
+
+ - 0
+
+ -
+ - 7
+
+ - 6
+
+ - 5
+
+ - 4
+
+ - 3
+
+ - 2
+
+ - 1
+
+ - 0
+
+ - .. _V4L2-PIX-FMT-YUV444:
+
+ - ``V4L2_PIX_FMT_YUV444``
+
+ - 'Y444'
+
+ -
+ - Cb\ :sub:`3`
+
+ - Cb\ :sub:`2`
+
+ - Cb\ :sub:`1`
+
+ - Cb\ :sub:`0`
+
+ - Cr\ :sub:`3`
+
+ - Cr\ :sub:`2`
+
+ - Cr\ :sub:`1`
+
+ - Cr\ :sub:`0`
+
+ -
+ - a\ :sub:`3`
+
+ - a\ :sub:`2`
+
+ - a\ :sub:`1`
+
+ - a\ :sub:`0`
+
+ - Y'\ :sub:`3`
+
+ - Y'\ :sub:`2`
+
+ - Y'\ :sub:`1`
+
+ - Y'\ :sub:`0`
+
+ - .. _V4L2-PIX-FMT-YUV555:
+
+ - ``V4L2_PIX_FMT_YUV555``
+
+ - 'YUVO'
+
+ -
+ - Cb\ :sub:`2`
+
+ - Cb\ :sub:`1`
+
+ - Cb\ :sub:`0`
+
+ - Cr\ :sub:`4`
+
+ - Cr\ :sub:`3`
+
+ - Cr\ :sub:`2`
+
+ - Cr\ :sub:`1`
+
+ - Cr\ :sub:`0`
+
+ -
+ - a
+
+ - Y'\ :sub:`4`
+
+ - Y'\ :sub:`3`
+
+ - Y'\ :sub:`2`
+
+ - Y'\ :sub:`1`
+
+ - Y'\ :sub:`0`
+
+ - Cb\ :sub:`4`
+
+ - Cb\ :sub:`3`
+
+ - .. _V4L2-PIX-FMT-YUV565:
+
+ - ``V4L2_PIX_FMT_YUV565``
+
+ - 'YUVP'
+
+ -
+ - Cb\ :sub:`2`
+
+ - Cb\ :sub:`1`
+
+ - Cb\ :sub:`0`
+
+ - Cr\ :sub:`4`
+
+ - Cr\ :sub:`3`
+
+ - Cr\ :sub:`2`
+
+ - Cr\ :sub:`1`
+
+ - Cr\ :sub:`0`
+
+ -
+ - Y'\ :sub:`4`
+
+ - Y'\ :sub:`3`
+
+ - Y'\ :sub:`2`
+
+ - Y'\ :sub:`1`
+
+ - Y'\ :sub:`0`
+
+ - Cb\ :sub:`5`
+
+ - Cb\ :sub:`4`
+
+ - Cb\ :sub:`3`
+
+ - .. _V4L2-PIX-FMT-YUV32:
+
+ - ``V4L2_PIX_FMT_YUV32``
+
+ - 'YUV4'
+
+ -
+ - a\ :sub:`7`
+
+ - a\ :sub:`6`
+
+ - a\ :sub:`5`
+
+ - a\ :sub:`4`
+
+ - a\ :sub:`3`
+
+ - a\ :sub:`2`
+
+ - a\ :sub:`1`
+
+ - a\ :sub:`0`
+
+ -
+ - Y'\ :sub:`7`
+
+ - Y'\ :sub:`6`
+
+ - Y'\ :sub:`5`
+
+ - Y'\ :sub:`4`
+
+ - Y'\ :sub:`3`
+
+ - Y'\ :sub:`2`
+
+ - Y'\ :sub:`1`
+
+ - Y'\ :sub:`0`
+
+ -
+ - Cb\ :sub:`7`
+
+ - Cb\ :sub:`6`
+
+ - Cb\ :sub:`5`
+
+ - Cb\ :sub:`4`
+
+ - Cb\ :sub:`3`
+
+ - Cb\ :sub:`2`
+
+ - Cb\ :sub:`1`
+
+ - Cb\ :sub:`0`
+
+ -
+ - Cr\ :sub:`7`
+
+ - Cr\ :sub:`6`
+
+ - Cr\ :sub:`5`
+
+ - Cr\ :sub:`4`
+
+ - Cr\ :sub:`3`
+
+ - Cr\ :sub:`2`
+
+ - Cr\ :sub:`1`
+
+ - Cr\ :sub:`0`
+
+
+Bit 7 is the most significant bit. The value of a = alpha bits is
+undefined when reading from the driver, ignored when writing to the
+driver, except when alpha blending has been negotiated for a
+:ref:`Video Overlay <overlay>` or :ref:`Video Output Overlay <osd>`.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _pixfmt-reserved:
+
+***************************
+Reserved Format Identifiers
+***************************
+
+These formats are not defined by this specification, they are just
+listed for reference and to avoid naming conflicts. If you want to
+register your own format, send an e-mail to the linux-media mailing list
+`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__
+for inclusion in the ``videodev2.h`` file. If you want to share your
+format with other developers add a link to your documentation and send a
+copy to the linux-media mailing list for inclusion in this section. If
+you think your format should be listed in a standard format section
+please make a proposal on the linux-media mailing list.
+
+
+.. _reserved-formats:
+
+.. flat-table:: Reserved Image Formats
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Code
+
+ - Details
+
+ - .. _V4L2-PIX-FMT-DV:
+
+ - ``V4L2_PIX_FMT_DV``
+
+ - 'dvsd'
+
+ - unknown
+
+ - .. _V4L2-PIX-FMT-ET61X251:
+
+ - ``V4L2_PIX_FMT_ET61X251``
+
+ - 'E625'
+
+ - Compressed format of the ET61X251 driver.
+
+ - .. _V4L2-PIX-FMT-HI240:
+
+ - ``V4L2_PIX_FMT_HI240``
+
+ - 'HI24'
+
+ - 8 bit RGB format used by the BTTV driver.
+
+ - .. _V4L2-PIX-FMT-HM12:
+
+ - ``V4L2_PIX_FMT_HM12``
+
+ - 'HM12'
+
+ - YUV 4:2:0 format used by the IVTV driver,
+ `http://www.ivtvdriver.org/ <http://www.ivtvdriver.org/>`__
+
+ The format is documented in the kernel sources in the file
+ ``Documentation/video4linux/cx2341x/README.hm12``
+
+ - .. _V4L2-PIX-FMT-CPIA1:
+
+ - ``V4L2_PIX_FMT_CPIA1``
+
+ - 'CPIA'
+
+ - YUV format used by the gspca cpia1 driver.
+
+ - .. _V4L2-PIX-FMT-JPGL:
+
+ - ``V4L2_PIX_FMT_JPGL``
+
+ - 'JPGL'
+
+ - JPEG-Light format (Pegasus Lossless JPEG) used in Divio webcams NW
+ 80x.
+
+ - .. _V4L2-PIX-FMT-SPCA501:
+
+ - ``V4L2_PIX_FMT_SPCA501``
+
+ - 'S501'
+
+ - YUYV per line used by the gspca driver.
+
+ - .. _V4L2-PIX-FMT-SPCA505:
+
+ - ``V4L2_PIX_FMT_SPCA505``
+
+ - 'S505'
+
+ - YYUV per line used by the gspca driver.
+
+ - .. _V4L2-PIX-FMT-SPCA508:
+
+ - ``V4L2_PIX_FMT_SPCA508``
+
+ - 'S508'
+
+ - YUVY per line used by the gspca driver.
+
+ - .. _V4L2-PIX-FMT-SPCA561:
+
+ - ``V4L2_PIX_FMT_SPCA561``
+
+ - 'S561'
+
+ - Compressed GBRG Bayer format used by the gspca driver.
+
+ - .. _V4L2-PIX-FMT-PAC207:
+
+ - ``V4L2_PIX_FMT_PAC207``
+
+ - 'P207'
+
+ - Compressed BGGR Bayer format used by the gspca driver.
+
+ - .. _V4L2-PIX-FMT-MR97310A:
+
+ - ``V4L2_PIX_FMT_MR97310A``
+
+ - 'M310'
+
+ - Compressed BGGR Bayer format used by the gspca driver.
+
+ - .. _V4L2-PIX-FMT-JL2005BCD:
+
+ - ``V4L2_PIX_FMT_JL2005BCD``
+
+ - 'JL20'
+
+ - JPEG compressed RGGB Bayer format used by the gspca driver.
+
+ - .. _V4L2-PIX-FMT-OV511:
+
+ - ``V4L2_PIX_FMT_OV511``
+
+ - 'O511'
+
+ - OV511 JPEG format used by the gspca driver.
+
+ - .. _V4L2-PIX-FMT-OV518:
+
+ - ``V4L2_PIX_FMT_OV518``
+
+ - 'O518'
+
+ - OV518 JPEG format used by the gspca driver.
+
+ - .. _V4L2-PIX-FMT-PJPG:
+
+ - ``V4L2_PIX_FMT_PJPG``
+
+ - 'PJPG'
+
+ - Pixart 73xx JPEG format used by the gspca driver.
+
+ - .. _V4L2-PIX-FMT-SE401:
+
+ - ``V4L2_PIX_FMT_SE401``
+
+ - 'S401'
+
+ - Compressed RGB format used by the gspca se401 driver
+
+ - .. _V4L2-PIX-FMT-SQ905C:
+
+ - ``V4L2_PIX_FMT_SQ905C``
+
+ - '905C'
+
+ - Compressed RGGB bayer format used by the gspca driver.
+
+ - .. _V4L2-PIX-FMT-MJPEG:
+
+ - ``V4L2_PIX_FMT_MJPEG``
+
+ - 'MJPG'
+
+ - Compressed format used by the Zoran driver
+
+ - .. _V4L2-PIX-FMT-PWC1:
+
+ - ``V4L2_PIX_FMT_PWC1``
+
+ - 'PWC1'
+
+ - Compressed format of the PWC driver.
+
+ - .. _V4L2-PIX-FMT-PWC2:
+
+ - ``V4L2_PIX_FMT_PWC2``
+
+ - 'PWC2'
+
+ - Compressed format of the PWC driver.
+
+ - .. _V4L2-PIX-FMT-SN9C10X:
+
+ - ``V4L2_PIX_FMT_SN9C10X``
+
+ - 'S910'
+
+ - Compressed format of the SN9C102 driver.
+
+ - .. _V4L2-PIX-FMT-SN9C20X-I420:
+
+ - ``V4L2_PIX_FMT_SN9C20X_I420``
+
+ - 'S920'
+
+ - YUV 4:2:0 format of the gspca sn9c20x driver.
+
+ - .. _V4L2-PIX-FMT-SN9C2028:
+
+ - ``V4L2_PIX_FMT_SN9C2028``
+
+ - 'SONX'
+
+ - Compressed GBRG bayer format of the gspca sn9c2028 driver.
+
+ - .. _V4L2-PIX-FMT-STV0680:
+
+ - ``V4L2_PIX_FMT_STV0680``
+
+ - 'S680'
+
+ - Bayer format of the gspca stv0680 driver.
+
+ - .. _V4L2-PIX-FMT-WNVA:
+
+ - ``V4L2_PIX_FMT_WNVA``
+
+ - 'WNVA'
+
+ - Used by the Winnov Videum driver,
+ `http://www.thedirks.org/winnov/ <http://www.thedirks.org/winnov/>`__
+
+ - .. _V4L2-PIX-FMT-TM6000:
+
+ - ``V4L2_PIX_FMT_TM6000``
+
+ - 'TM60'
+
+ - Used by Trident tm6000
+
+ - .. _V4L2-PIX-FMT-CIT-YYVYUY:
+
+ - ``V4L2_PIX_FMT_CIT_YYVYUY``
+
+ - 'CITV'
+
+ - Used by xirlink CIT, found at IBM webcams.
+
+ Uses one line of Y then 1 line of VYUY
+
+ - .. _V4L2-PIX-FMT-KONICA420:
+
+ - ``V4L2_PIX_FMT_KONICA420``
+
+ - 'KONI'
+
+ - Used by Konica webcams.
+
+ YUV420 planar in blocks of 256 pixels.
+
+ - .. _V4L2-PIX-FMT-YYUV:
+
+ - ``V4L2_PIX_FMT_YYUV``
+
+ - 'YYUV'
+
+ - unknown
+
+ - .. _V4L2-PIX-FMT-Y4:
+
+ - ``V4L2_PIX_FMT_Y4``
+
+ - 'Y04 '
+
+ - Old 4-bit greyscale format. Only the most significant 4 bits of
+ each byte are used, the other bits are set to 0.
+
+ - .. _V4L2-PIX-FMT-Y6:
+
+ - ``V4L2_PIX_FMT_Y6``
+
+ - 'Y06 '
+
+ - Old 6-bit greyscale format. Only the most significant 6 bits of
+ each byte are used, the other bits are set to 0.
+
+ - .. _V4L2-PIX-FMT-S5C-UYVY-JPG:
+
+ - ``V4L2_PIX_FMT_S5C_UYVY_JPG``
+
+ - 'S5CI'
+
+ - Two-planar format used by Samsung S5C73MX cameras. The first plane
+ contains interleaved JPEG and UYVY image data, followed by meta
+ data in form of an array of offsets to the UYVY data blocks. The
+ actual pointer array follows immediately the interleaved JPEG/UYVY
+ data, the number of entries in this array equals the height of the
+ UYVY image. Each entry is a 4-byte unsigned integer in big endian
+ order and it's an offset to a single pixel line of the UYVY image.
+ The first plane can start either with JPEG or UYVY data chunk. The
+ size of a single UYVY block equals the UYVY image's width
+ multiplied by 2. The size of a JPEG chunk depends on the image and
+ can vary with each line.
+
+ The second plane, at an offset of 4084 bytes, contains a 4-byte
+ offset to the pointer array in the first plane. This offset is
+ followed by a 4-byte value indicating size of the pointer array.
+ All numbers in the second plane are also in big endian order.
+ Remaining data in the second plane is undefined. The information
+ in the second plane allows to easily find location of the pointer
+ array, which can be different for each frame. The size of the
+ pointer array is constant for given UYVY image height.
+
+ In order to extract UYVY and JPEG frames an application can
+ initially set a data pointer to the start of first plane and then
+ add an offset from the first entry of the pointers table. Such a
+ pointer indicates start of an UYVY image pixel line. Whole UYVY
+ line can be copied to a separate buffer. These steps should be
+ repeated for each line, i.e. the number of entries in the pointer
+ array. Anything what's in between the UYVY lines is JPEG data and
+ should be concatenated to form the JPEG stream.
+
+
+
+.. _format-flags:
+
+.. flat-table:: Format Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_PIX_FMT_FLAG_PREMUL_ALPHA``
+
+ - 0x00000001
+
+ - The color values are premultiplied by the alpha channel value. For
+ example, if a light blue pixel with 50% transparency was described
+ by RGBA values (128, 192, 255, 128), the same pixel described with
+ premultiplied colors would be described by RGBA values (64, 96,
+ 128, 128)
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _pixfmt-rgb:
+
+***********
+RGB Formats
+***********
+
+
+.. toctree::
+ :maxdepth: 1
+
+ pixfmt-packed-rgb
+ pixfmt-sbggr8
+ pixfmt-sgbrg8
+ pixfmt-sgrbg8
+ pixfmt-srggb8
+ pixfmt-sbggr16
+ pixfmt-srggb10
+ pixfmt-srggb10p
+ pixfmt-srggb10alaw8
+ pixfmt-srggb10dpcm8
+ pixfmt-srggb12
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-SBGGR16:
+
+*****************************
+V4L2_PIX_FMT_SBGGR16 ('BYR2')
+*****************************
+
+*man V4L2_PIX_FMT_SBGGR16(2)*
+
+Bayer RGB format
+
+
+Description
+===========
+
+This format is similar to
+:ref:`V4L2_PIX_FMT_SBGGR8 <V4L2-PIX-FMT-SBGGR8>`, except each pixel
+has a depth of 16 bits. The least significant byte is stored at lower
+memory addresses (little-endian). Note the actual sampling precision may
+be lower than 16 bits, for example 10 bits per pixel with values in
+range 0 to 1023.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - B\ :sub:`00low`
+
+ - B\ :sub:`00high`
+
+ - G\ :sub:`01low`
+
+ - G\ :sub:`01high`
+
+ - B\ :sub:`02low`
+
+ - B\ :sub:`02high`
+
+ - G\ :sub:`03low`
+
+ - G\ :sub:`03high`
+
+ - .. row 2
+
+ - start + 8:
+
+ - G\ :sub:`10low`
+
+ - G\ :sub:`10high`
+
+ - R\ :sub:`11low`
+
+ - R\ :sub:`11high`
+
+ - G\ :sub:`12low`
+
+ - G\ :sub:`12high`
+
+ - R\ :sub:`13low`
+
+ - R\ :sub:`13high`
+
+ - .. row 3
+
+ - start + 16:
+
+ - B\ :sub:`20low`
+
+ - B\ :sub:`20high`
+
+ - G\ :sub:`21low`
+
+ - G\ :sub:`21high`
+
+ - B\ :sub:`22low`
+
+ - B\ :sub:`22high`
+
+ - G\ :sub:`23low`
+
+ - G\ :sub:`23high`
+
+ - .. row 4
+
+ - start + 24:
+
+ - G\ :sub:`30low`
+
+ - G\ :sub:`30high`
+
+ - R\ :sub:`31low`
+
+ - R\ :sub:`31high`
+
+ - G\ :sub:`32low`
+
+ - G\ :sub:`32high`
+
+ - R\ :sub:`33low`
+
+ - R\ :sub:`33high`
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-SBGGR8:
+
+****************************
+V4L2_PIX_FMT_SBGGR8 ('BA81')
+****************************
+
+*man V4L2_PIX_FMT_SBGGR8(2)*
+
+Bayer RGB format
+
+
+Description
+===========
+
+This is commonly the native format of digital cameras, reflecting the
+arrangement of sensors on the CCD device. Only one red, green or blue
+value is given for each pixel. Missing components must be interpolated
+from neighbouring pixels. From left to right the first row consists of a
+blue and green value, the second row of a green and red value. This
+scheme repeats to the right and down for every two columns and rows.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - B\ :sub:`00`
+
+ - G\ :sub:`01`
+
+ - B\ :sub:`02`
+
+ - G\ :sub:`03`
+
+ - .. row 2
+
+ - start + 4:
+
+ - G\ :sub:`10`
+
+ - R\ :sub:`11`
+
+ - G\ :sub:`12`
+
+ - R\ :sub:`13`
+
+ - .. row 3
+
+ - start + 8:
+
+ - B\ :sub:`20`
+
+ - G\ :sub:`21`
+
+ - B\ :sub:`22`
+
+ - G\ :sub:`23`
+
+ - .. row 4
+
+ - start + 12:
+
+ - G\ :sub:`30`
+
+ - R\ :sub:`31`
+
+ - G\ :sub:`32`
+
+ - R\ :sub:`33`
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _v4l2-sdr-fmt-cs8:
+
+*************************
+V4L2_SDR_FMT_CS8 ('CS08')
+*************************
+
+*man V4L2_SDR_FMT_CS8(2)*
+
+Complex signed 8-bit IQ sample
+
+
+Description
+===========
+
+This format contains sequence of complex number samples. Each complex
+number consist two parts, called In-phase and Quadrature (IQ). Both I
+and Q are represented as a 8 bit signed number. I value comes first and
+Q value after that.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - I'\ :sub:`0`
+
+ - .. row 2
+
+ - start + 1:
+
+ - Q'\ :sub:`0`
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-SDR-FMT-CS14LE:
+
+****************************
+V4L2_SDR_FMT_CS14LE ('CS14')
+****************************
+
+*man V4L2_SDR_FMT_CS14LE(2)*
+
+Complex signed 14-bit little endian IQ sample
+
+
+Description
+===========
+
+This format contains sequence of complex number samples. Each complex
+number consist two parts, called In-phase and Quadrature (IQ). Both I
+and Q are represented as a 14 bit signed little endian number. I value
+comes first and Q value after that. 14 bit value is stored in 16 bit
+space with unused high bits padded with 0.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - I'\ :sub:`0[7:0]`
+
+ - I'\ :sub:`0[13:8]`
+
+ - .. row 2
+
+ - start + 2:
+
+ - Q'\ :sub:`0[7:0]`
+
+ - Q'\ :sub:`0[13:8]`
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _v4l2-sdr-fmt-cu8:
+
+*************************
+V4L2_SDR_FMT_CU8 ('CU08')
+*************************
+
+*man V4L2_SDR_FMT_CU8(2)*
+
+Complex unsigned 8-bit IQ sample
+
+
+Description
+===========
+
+This format contains sequence of complex number samples. Each complex
+number consist two parts, called In-phase and Quadrature (IQ). Both I
+and Q are represented as a 8 bit unsigned number. I value comes first
+and Q value after that.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - I'\ :sub:`0`
+
+ - .. row 2
+
+ - start + 1:
+
+ - Q'\ :sub:`0`
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-SDR-FMT-CU16LE:
+
+****************************
+V4L2_SDR_FMT_CU16LE ('CU16')
+****************************
+
+*man V4L2_SDR_FMT_CU16LE(2)*
+
+Complex unsigned 16-bit little endian IQ sample
+
+
+Description
+===========
+
+This format contains sequence of complex number samples. Each complex
+number consist two parts, called In-phase and Quadrature (IQ). Both I
+and Q are represented as a 16 bit unsigned little endian number. I value
+comes first and Q value after that.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - I'\ :sub:`0[7:0]`
+
+ - I'\ :sub:`0[15:8]`
+
+ - .. row 2
+
+ - start + 2:
+
+ - Q'\ :sub:`0[7:0]`
+
+ - Q'\ :sub:`0[15:8]`
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-SDR-FMT-RU12LE:
+
+****************************
+V4L2_SDR_FMT_RU12LE ('RU12')
+****************************
+
+*man V4L2_SDR_FMT_RU12LE(2)*
+
+Real unsigned 12-bit little endian sample
+
+
+Description
+===========
+
+This format contains sequence of real number samples. Each sample is
+represented as a 12 bit unsigned little endian number. Sample is stored
+in 16 bit space with unused high bits padded with 0.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - I'\ :sub:`0[7:0]`
+
+ - I'\ :sub:`0[11:8]`
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-SGBRG8:
+
+****************************
+V4L2_PIX_FMT_SGBRG8 ('GBRG')
+****************************
+
+*man V4L2_PIX_FMT_SGBRG8(2)*
+
+Bayer RGB format
+
+
+Description
+===========
+
+This is commonly the native format of digital cameras, reflecting the
+arrangement of sensors on the CCD device. Only one red, green or blue
+value is given for each pixel. Missing components must be interpolated
+from neighbouring pixels. From left to right the first row consists of a
+green and blue value, the second row of a red and green value. This
+scheme repeats to the right and down for every two columns and rows.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - G\ :sub:`00`
+
+ - B\ :sub:`01`
+
+ - G\ :sub:`02`
+
+ - B\ :sub:`03`
+
+ - .. row 2
+
+ - start + 4:
+
+ - R\ :sub:`10`
+
+ - G\ :sub:`11`
+
+ - R\ :sub:`12`
+
+ - G\ :sub:`13`
+
+ - .. row 3
+
+ - start + 8:
+
+ - G\ :sub:`20`
+
+ - B\ :sub:`21`
+
+ - G\ :sub:`22`
+
+ - B\ :sub:`23`
+
+ - .. row 4
+
+ - start + 12:
+
+ - R\ :sub:`30`
+
+ - G\ :sub:`31`
+
+ - R\ :sub:`32`
+
+ - G\ :sub:`33`
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-SGRBG8:
+
+****************************
+V4L2_PIX_FMT_SGRBG8 ('GRBG')
+****************************
+
+*man V4L2_PIX_FMT_SGRBG8(2)*
+
+Bayer RGB format
+
+
+Description
+===========
+
+This is commonly the native format of digital cameras, reflecting the
+arrangement of sensors on the CCD device. Only one red, green or blue
+value is given for each pixel. Missing components must be interpolated
+from neighbouring pixels. From left to right the first row consists of a
+green and blue value, the second row of a red and green value. This
+scheme repeats to the right and down for every two columns and rows.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - G\ :sub:`00`
+
+ - R\ :sub:`01`
+
+ - G\ :sub:`02`
+
+ - R\ :sub:`03`
+
+ - .. row 2
+
+ - start + 4:
+
+ - B\ :sub:`10`
+
+ - G\ :sub:`11`
+
+ - B\ :sub:`12`
+
+ - G\ :sub:`13`
+
+ - .. row 3
+
+ - start + 8:
+
+ - G\ :sub:`20`
+
+ - R\ :sub:`21`
+
+ - G\ :sub:`22`
+
+ - R\ :sub:`23`
+
+ - .. row 4
+
+ - start + 12:
+
+ - B\ :sub:`30`
+
+ - G\ :sub:`31`
+
+ - B\ :sub:`32`
+
+ - G\ :sub:`33`
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-SRGGB10:
+.. _v4l2-pix-fmt-sbggr10:
+.. _v4l2-pix-fmt-sgbrg10:
+.. _v4l2-pix-fmt-sgrbg10:
+
+***************************************************************************************************************************
+V4L2_PIX_FMT_SRGGB10 ('RG10'), V4L2_PIX_FMT_SGRBG10 ('BA10'), V4L2_PIX_FMT_SGBRG10 ('GB10'), V4L2_PIX_FMT_SBGGR10 ('BG10'),
+***************************************************************************************************************************
+
+*man V4L2_PIX_FMT_SRGGB10(2)*
+
+V4L2_PIX_FMT_SGRBG10
+V4L2_PIX_FMT_SGBRG10
+V4L2_PIX_FMT_SBGGR10
+10-bit Bayer formats expanded to 16 bits
+
+
+Description
+===========
+
+These four pixel formats are raw sRGB / Bayer formats with 10 bits per
+colour. Each colour component is stored in a 16-bit word, with 6 unused
+high bits filled with zeros. Each n-pixel row contains n/2 green samples
+and n/2 blue or red samples, with alternating red and blue rows. Bytes
+are stored in memory in little endian order. They are conventionally
+described as GRGR... BGBG..., RGRG... GBGB..., etc. Below is an example
+of one of these formats
+
+**Byte Order.**
+Each cell is one byte, high 6 bits in high bytes are 0.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - B\ :sub:`00low`
+
+ - B\ :sub:`00high`
+
+ - G\ :sub:`01low`
+
+ - G\ :sub:`01high`
+
+ - B\ :sub:`02low`
+
+ - B\ :sub:`02high`
+
+ - G\ :sub:`03low`
+
+ - G\ :sub:`03high`
+
+ - .. row 2
+
+ - start + 8:
+
+ - G\ :sub:`10low`
+
+ - G\ :sub:`10high`
+
+ - R\ :sub:`11low`
+
+ - R\ :sub:`11high`
+
+ - G\ :sub:`12low`
+
+ - G\ :sub:`12high`
+
+ - R\ :sub:`13low`
+
+ - R\ :sub:`13high`
+
+ - .. row 3
+
+ - start + 16:
+
+ - B\ :sub:`20low`
+
+ - B\ :sub:`20high`
+
+ - G\ :sub:`21low`
+
+ - G\ :sub:`21high`
+
+ - B\ :sub:`22low`
+
+ - B\ :sub:`22high`
+
+ - G\ :sub:`23low`
+
+ - G\ :sub:`23high`
+
+ - .. row 4
+
+ - start + 24:
+
+ - G\ :sub:`30low`
+
+ - G\ :sub:`30high`
+
+ - R\ :sub:`31low`
+
+ - R\ :sub:`31high`
+
+ - G\ :sub:`32low`
+
+ - G\ :sub:`32high`
+
+ - R\ :sub:`33low`
+
+ - R\ :sub:`33high`
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-SBGGR10ALAW8:
+.. _v4l2-pix-fmt-sgbrg10alaw8:
+.. _v4l2-pix-fmt-sgrbg10alaw8:
+.. _v4l2-pix-fmt-srggb10alaw8:
+
+***********************************************************************************************************************************************
+V4L2_PIX_FMT_SBGGR10ALAW8 ('aBA8'), V4L2_PIX_FMT_SGBRG10ALAW8 ('aGA8'), V4L2_PIX_FMT_SGRBG10ALAW8 ('agA8'), V4L2_PIX_FMT_SRGGB10ALAW8 ('aRA8'),
+***********************************************************************************************************************************************
+
+*man V4L2_PIX_FMT_SBGGR10ALAW8(2)*
+
+V4L2_PIX_FMT_SGBRG10ALAW8
+V4L2_PIX_FMT_SGRBG10ALAW8
+V4L2_PIX_FMT_SRGGB10ALAW8
+10-bit Bayer formats compressed to 8 bits
+
+
+Description
+===========
+
+These four pixel formats are raw sRGB / Bayer formats with 10 bits per
+color compressed to 8 bits each, using the A-LAW algorithm. Each color
+component consumes 8 bits of memory. In other respects this format is
+similar to :ref:`V4L2-PIX-FMT-SRGGB8`.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-SBGGR10DPCM8:
+.. _v4l2-pix-fmt-sgbrg10dpcm8:
+.. _v4l2-pix-fmt-sgrbg10dpcm8:
+.. _v4l2-pix-fmt-srggb10dpcm8:
+
+
+***********************************************************************************************************************************************
+V4L2_PIX_FMT_SBGGR10DPCM8 ('bBA8'), V4L2_PIX_FMT_SGBRG10DPCM8 ('bGA8'), V4L2_PIX_FMT_SGRBG10DPCM8 ('BD10'), V4L2_PIX_FMT_SRGGB10DPCM8 ('bRA8'),
+***********************************************************************************************************************************************
+
+*man V4L2_PIX_FMT_SBGGR10DPCM8(2)*
+
+V4L2_PIX_FMT_SGBRG10DPCM8
+V4L2_PIX_FMT_SGRBG10DPCM8
+V4L2_PIX_FMT_SRGGB10DPCM8
+10-bit Bayer formats compressed to 8 bits
+
+
+Description
+===========
+
+These four pixel formats are raw sRGB / Bayer formats with 10 bits per
+colour compressed to 8 bits each, using DPCM compression. DPCM,
+differential pulse-code modulation, is lossy. Each colour component
+consumes 8 bits of memory. In other respects this format is similar to
+:ref:`V4L2-PIX-FMT-SRGGB10`.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-SRGGB10P:
+.. _v4l2-pix-fmt-sbggr10p:
+.. _v4l2-pix-fmt-sgbrg10p:
+.. _v4l2-pix-fmt-sgrbg10p:
+
+*******************************************************************************************************************************
+V4L2_PIX_FMT_SRGGB10P ('pRAA'), V4L2_PIX_FMT_SGRBG10P ('pgAA'), V4L2_PIX_FMT_SGBRG10P ('pGAA'), V4L2_PIX_FMT_SBGGR10P ('pBAA'),
+*******************************************************************************************************************************
+
+*man V4L2_PIX_FMT_SRGGB10P(2)*
+
+V4L2_PIX_FMT_SGRBG10P
+V4L2_PIX_FMT_SGBRG10P
+V4L2_PIX_FMT_SBGGR10P
+10-bit packed Bayer formats
+
+
+Description
+===========
+
+These four pixel formats are packed raw sRGB / Bayer formats with 10
+bits per colour. Every four consecutive colour components are packed
+into 5 bytes. Each of the first 4 bytes contain the 8 high order bits of
+the pixels, and the fifth byte contains the two least significants bits
+of each pixel, in the same order.
+
+Each n-pixel row contains n/2 green samples and n/2 blue or red samples,
+with alternating green-red and green-blue rows. They are conventionally
+described as GRGR... BGBG..., RGRG... GBGB..., etc. Below is an example
+of one of these formats:
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - B\ :sub:`00high`
+
+ - G\ :sub:`01high`
+
+ - B\ :sub:`02high`
+
+ - G\ :sub:`03high`
+
+ - B\ :sub:`00low`\ (bits 7--6) G\ :sub:`01low`\ (bits 5--4)
+ B\ :sub:`02low`\ (bits 3--2) G\ :sub:`03low`\ (bits 1--0)
+
+ - .. row 2
+
+ - start + 5:
+
+ - G\ :sub:`10high`
+
+ - R\ :sub:`11high`
+
+ - G\ :sub:`12high`
+
+ - R\ :sub:`13high`
+
+ - G\ :sub:`10low`\ (bits 7--6) R\ :sub:`11low`\ (bits 5--4)
+ G\ :sub:`12low`\ (bits 3--2) R\ :sub:`13low`\ (bits 1--0)
+
+ - .. row 3
+
+ - start + 10:
+
+ - B\ :sub:`20high`
+
+ - G\ :sub:`21high`
+
+ - B\ :sub:`22high`
+
+ - G\ :sub:`23high`
+
+ - B\ :sub:`20low`\ (bits 7--6) G\ :sub:`21low`\ (bits 5--4)
+ B\ :sub:`22low`\ (bits 3--2) G\ :sub:`23low`\ (bits 1--0)
+
+ - .. row 4
+
+ - start + 15:
+
+ - G\ :sub:`30high`
+
+ - R\ :sub:`31high`
+
+ - G\ :sub:`32high`
+
+ - R\ :sub:`33high`
+
+ - G\ :sub:`30low`\ (bits 7--6) R\ :sub:`31low`\ (bits 5--4)
+ G\ :sub:`32low`\ (bits 3--2) R\ :sub:`33low`\ (bits 1--0)
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-SRGGB12:
+.. _v4l2-pix-fmt-sbggr12:
+.. _v4l2-pix-fmt-sgbrg12:
+.. _v4l2-pix-fmt-sgrbg12:
+
+
+***************************************************************************************************************************
+V4L2_PIX_FMT_SRGGB12 ('RG12'), V4L2_PIX_FMT_SGRBG12 ('BA12'), V4L2_PIX_FMT_SGBRG12 ('GB12'), V4L2_PIX_FMT_SBGGR12 ('BG12'),
+***************************************************************************************************************************
+
+*man V4L2_PIX_FMT_SRGGB12(2)*
+
+V4L2_PIX_FMT_SGRBG12
+V4L2_PIX_FMT_SGBRG12
+V4L2_PIX_FMT_SBGGR12
+12-bit Bayer formats expanded to 16 bits
+
+
+Description
+===========
+
+These four pixel formats are raw sRGB / Bayer formats with 12 bits per
+colour. Each colour component is stored in a 16-bit word, with 4 unused
+high bits filled with zeros. Each n-pixel row contains n/2 green samples
+and n/2 blue or red samples, with alternating red and blue rows. Bytes
+are stored in memory in little endian order. They are conventionally
+described as GRGR... BGBG..., RGRG... GBGB..., etc. Below is an example
+of one of these formats
+
+**Byte Order.**
+Each cell is one byte, high 6 bits in high bytes are 0.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - B\ :sub:`00low`
+
+ - B\ :sub:`00high`
+
+ - G\ :sub:`01low`
+
+ - G\ :sub:`01high`
+
+ - B\ :sub:`02low`
+
+ - B\ :sub:`02high`
+
+ - G\ :sub:`03low`
+
+ - G\ :sub:`03high`
+
+ - .. row 2
+
+ - start + 8:
+
+ - G\ :sub:`10low`
+
+ - G\ :sub:`10high`
+
+ - R\ :sub:`11low`
+
+ - R\ :sub:`11high`
+
+ - G\ :sub:`12low`
+
+ - G\ :sub:`12high`
+
+ - R\ :sub:`13low`
+
+ - R\ :sub:`13high`
+
+ - .. row 3
+
+ - start + 16:
+
+ - B\ :sub:`20low`
+
+ - B\ :sub:`20high`
+
+ - G\ :sub:`21low`
+
+ - G\ :sub:`21high`
+
+ - B\ :sub:`22low`
+
+ - B\ :sub:`22high`
+
+ - G\ :sub:`23low`
+
+ - G\ :sub:`23high`
+
+ - .. row 4
+
+ - start + 24:
+
+ - G\ :sub:`30low`
+
+ - G\ :sub:`30high`
+
+ - R\ :sub:`31low`
+
+ - R\ :sub:`31high`
+
+ - G\ :sub:`32low`
+
+ - G\ :sub:`32high`
+
+ - R\ :sub:`33low`
+
+ - R\ :sub:`33high`
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-SRGGB8:
+
+****************************
+V4L2_PIX_FMT_SRGGB8 ('RGGB')
+****************************
+
+*man V4L2_PIX_FMT_SRGGB8(2)*
+
+Bayer RGB format
+
+
+Description
+===========
+
+This is commonly the native format of digital cameras, reflecting the
+arrangement of sensors on the CCD device. Only one red, green or blue
+value is given for each pixel. Missing components must be interpolated
+from neighbouring pixels. From left to right the first row consists of a
+red and green value, the second row of a green and blue value. This
+scheme repeats to the right and down for every two columns and rows.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - R\ :sub:`00`
+
+ - G\ :sub:`01`
+
+ - R\ :sub:`02`
+
+ - G\ :sub:`03`
+
+ - .. row 2
+
+ - start + 4:
+
+ - G\ :sub:`10`
+
+ - B\ :sub:`11`
+
+ - G\ :sub:`12`
+
+ - B\ :sub:`13`
+
+ - .. row 3
+
+ - start + 8:
+
+ - R\ :sub:`20`
+
+ - G\ :sub:`21`
+
+ - R\ :sub:`22`
+
+ - G\ :sub:`23`
+
+ - .. row 4
+
+ - start + 12:
+
+ - G\ :sub:`30`
+
+ - B\ :sub:`31`
+
+ - G\ :sub:`32`
+
+ - B\ :sub:`33`
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-UV8:
+
+************************
+V4L2_PIX_FMT_UV8 ('UV8')
+************************
+
+*man V4L2_PIX_FMT_UV8(2)*
+
+UV plane interleaved
+
+
+Description
+===========
+
+In this format there is no Y plane, Only CbCr plane. ie (UV interleaved)
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Cb\ :sub:`00`
+
+ - Cr\ :sub:`00`
+
+ - Cb\ :sub:`01`
+
+ - Cr\ :sub:`01`
+
+ - .. row 2
+
+ - start + 4:
+
+ - Cb\ :sub:`10`
+
+ - Cr\ :sub:`10`
+
+ - Cb\ :sub:`11`
+
+ - Cr\ :sub:`11`
+
+ - .. row 3
+
+ - start + 8:
+
+ - Cb\ :sub:`20`
+
+ - Cr\ :sub:`20`
+
+ - Cb\ :sub:`21`
+
+ - Cr\ :sub:`21`
+
+ - .. row 4
+
+ - start + 12:
+
+ - Cb\ :sub:`30`
+
+ - Cr\ :sub:`30`
+
+ - Cb\ :sub:`31`
+
+ - Cr\ :sub:`31`
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-UYVY:
+
+**************************
+V4L2_PIX_FMT_UYVY ('UYVY')
+**************************
+
+*man V4L2_PIX_FMT_UYVY(2)*
+
+Variation of ``V4L2_PIX_FMT_YUYV`` with different order of samples in
+memory
+
+
+Description
+===========
+
+In this format each four bytes is two pixels. Each four bytes is two
+Y's, a Cb and a Cr. Each Y goes to one of the pixels, and the Cb and Cr
+belong to both pixels. As you can see, the Cr and Cb components have
+half the horizontal resolution of the Y component.
+
+**Byte Order.**
+Each cell is one byte.
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Cb\ :sub:`00`
+
+ - Y'\ :sub:`00`
+
+ - Cr\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Cb\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Cr\ :sub:`01`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start + 8:
+
+ - Cb\ :sub:`10`
+
+ - Y'\ :sub:`10`
+
+ - Cr\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Cb\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Cr\ :sub:`11`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start + 16:
+
+ - Cb\ :sub:`20`
+
+ - Y'\ :sub:`20`
+
+ - Cr\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Cb\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Cr\ :sub:`21`
+
+ - Y'\ :sub:`23`
+
+ - .. row 4
+
+ - start + 24:
+
+ - Cb\ :sub:`30`
+
+ - Y'\ :sub:`30`
+
+ - Cr\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Cb\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Cr\ :sub:`31`
+
+ - Y'\ :sub:`33`
+
+
+**Color Sample Location..**
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ -
+ - 1
+
+ - 2
+
+ -
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 3
+
+ - 1
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 4
+
+ - 2
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 5
+
+ - 3
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-VYUY:
+
+**************************
+V4L2_PIX_FMT_VYUY ('VYUY')
+**************************
+
+*man V4L2_PIX_FMT_VYUY(2)*
+
+Variation of ``V4L2_PIX_FMT_YUYV`` with different order of samples in
+memory
+
+
+Description
+===========
+
+In this format each four bytes is two pixels. Each four bytes is two
+Y's, a Cb and a Cr. Each Y goes to one of the pixels, and the Cb and Cr
+belong to both pixels. As you can see, the Cr and Cb components have
+half the horizontal resolution of the Y component.
+
+**Byte Order.**
+Each cell is one byte.
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Cr\ :sub:`00`
+
+ - Y'\ :sub:`00`
+
+ - Cb\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Cr\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Cb\ :sub:`01`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start + 8:
+
+ - Cr\ :sub:`10`
+
+ - Y'\ :sub:`10`
+
+ - Cb\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Cr\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Cb\ :sub:`11`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start + 16:
+
+ - Cr\ :sub:`20`
+
+ - Y'\ :sub:`20`
+
+ - Cb\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Cr\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Cb\ :sub:`21`
+
+ - Y'\ :sub:`23`
+
+ - .. row 4
+
+ - start + 24:
+
+ - Cr\ :sub:`30`
+
+ - Y'\ :sub:`30`
+
+ - Cb\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Cr\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Cb\ :sub:`31`
+
+ - Y'\ :sub:`33`
+
+
+**Color Sample Location..**
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ -
+ - 1
+
+ -
+ - 2
+
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 3
+
+ - 1
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 4
+
+ - 2
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 5
+
+ - 3
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-Y10:
+
+*************************
+V4L2_PIX_FMT_Y10 ('Y10 ')
+*************************
+
+*man V4L2_PIX_FMT_Y10(2)*
+
+Grey-scale image
+
+
+Description
+===========
+
+This is a grey-scale image with a depth of 10 bits per pixel. Pixels are
+stored in 16-bit words with unused high bits padded with 0. The least
+significant byte is stored at lower memory addresses (little-endian).
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Y'\ :sub:`00low`
+
+ - Y'\ :sub:`00high`
+
+ - Y'\ :sub:`01low`
+
+ - Y'\ :sub:`01high`
+
+ - Y'\ :sub:`02low`
+
+ - Y'\ :sub:`02high`
+
+ - Y'\ :sub:`03low`
+
+ - Y'\ :sub:`03high`
+
+ - .. row 2
+
+ - start + 8:
+
+ - Y'\ :sub:`10low`
+
+ - Y'\ :sub:`10high`
+
+ - Y'\ :sub:`11low`
+
+ - Y'\ :sub:`11high`
+
+ - Y'\ :sub:`12low`
+
+ - Y'\ :sub:`12high`
+
+ - Y'\ :sub:`13low`
+
+ - Y'\ :sub:`13high`
+
+ - .. row 3
+
+ - start + 16:
+
+ - Y'\ :sub:`20low`
+
+ - Y'\ :sub:`20high`
+
+ - Y'\ :sub:`21low`
+
+ - Y'\ :sub:`21high`
+
+ - Y'\ :sub:`22low`
+
+ - Y'\ :sub:`22high`
+
+ - Y'\ :sub:`23low`
+
+ - Y'\ :sub:`23high`
+
+ - .. row 4
+
+ - start + 24:
+
+ - Y'\ :sub:`30low`
+
+ - Y'\ :sub:`30high`
+
+ - Y'\ :sub:`31low`
+
+ - Y'\ :sub:`31high`
+
+ - Y'\ :sub:`32low`
+
+ - Y'\ :sub:`32high`
+
+ - Y'\ :sub:`33low`
+
+ - Y'\ :sub:`33high`
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-Y10BPACK:
+
+******************************
+V4L2_PIX_FMT_Y10BPACK ('Y10B')
+******************************
+
+*man V4L2_PIX_FMT_Y10BPACK(2)*
+
+Grey-scale image as a bit-packed array
+
+
+Description
+===========
+
+This is a packed grey-scale image format with a depth of 10 bits per
+pixel. Pixels are stored in a bit-packed array of 10bit bits per pixel,
+with no padding between them and with the most significant bits coming
+first from the left.
+
+**Bit-packed representation.**
+
+pixels cross the byte boundary and have a ratio of 5 bytes for each 4
+pixels.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - Y'\ :sub:`00[9:2]`
+
+ - Y'\ :sub:`00[1:0]`\ Y'\ :sub:`01[9:4]`
+
+ - Y'\ :sub:`01[3:0]`\ Y'\ :sub:`02[9:6]`
+
+ - Y'\ :sub:`02[5:0]`\ Y'\ :sub:`03[9:8]`
+
+ - Y'\ :sub:`03[7:0]`
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-Y12:
+
+*************************
+V4L2_PIX_FMT_Y12 ('Y12 ')
+*************************
+
+*man V4L2_PIX_FMT_Y12(2)*
+
+Grey-scale image
+
+
+Description
+===========
+
+This is a grey-scale image with a depth of 12 bits per pixel. Pixels are
+stored in 16-bit words with unused high bits padded with 0. The least
+significant byte is stored at lower memory addresses (little-endian).
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Y'\ :sub:`00low`
+
+ - Y'\ :sub:`00high`
+
+ - Y'\ :sub:`01low`
+
+ - Y'\ :sub:`01high`
+
+ - Y'\ :sub:`02low`
+
+ - Y'\ :sub:`02high`
+
+ - Y'\ :sub:`03low`
+
+ - Y'\ :sub:`03high`
+
+ - .. row 2
+
+ - start + 8:
+
+ - Y'\ :sub:`10low`
+
+ - Y'\ :sub:`10high`
+
+ - Y'\ :sub:`11low`
+
+ - Y'\ :sub:`11high`
+
+ - Y'\ :sub:`12low`
+
+ - Y'\ :sub:`12high`
+
+ - Y'\ :sub:`13low`
+
+ - Y'\ :sub:`13high`
+
+ - .. row 3
+
+ - start + 16:
+
+ - Y'\ :sub:`20low`
+
+ - Y'\ :sub:`20high`
+
+ - Y'\ :sub:`21low`
+
+ - Y'\ :sub:`21high`
+
+ - Y'\ :sub:`22low`
+
+ - Y'\ :sub:`22high`
+
+ - Y'\ :sub:`23low`
+
+ - Y'\ :sub:`23high`
+
+ - .. row 4
+
+ - start + 24:
+
+ - Y'\ :sub:`30low`
+
+ - Y'\ :sub:`30high`
+
+ - Y'\ :sub:`31low`
+
+ - Y'\ :sub:`31high`
+
+ - Y'\ :sub:`32low`
+
+ - Y'\ :sub:`32high`
+
+ - Y'\ :sub:`33low`
+
+ - Y'\ :sub:`33high`
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-Y12I:
+
+**************************
+V4L2_PIX_FMT_Y12I ('Y12I')
+**************************
+
+*man V4L2_PIX_FMT_Y12I(2)*
+
+Interleaved grey-scale image, e.g. from a stereo-pair
+
+
+Description
+===========
+
+This is a grey-scale image with a depth of 12 bits per pixel, but with
+pixels from 2 sources interleaved and bit-packed. Each pixel is stored
+in a 24-bit word in the little-endian order. On a little-endian machine
+these pixels can be deinterlaced using
+
+.. code-block:: c
+
+ __u8 *buf;
+ left0 = 0xfff & *(__u16 *)buf;
+ right0 = *(__u16 *)(buf + 1) >> 4;
+
+**Bit-packed representation.**
+pixels cross the byte boundary and have a ratio of 3 bytes for each
+interleaved pixel.
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1
+
+
+ - .. row 1
+
+ - Y'\ :sub:`0left[7:0]`
+
+ - Y'\ :sub:`0right[3:0]`\ Y'\ :sub:`0left[11:8]`
+
+ - Y'\ :sub:`0right[11:4]`
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-Y16-BE:
+
+****************************************
+V4L2_PIX_FMT_Y16_BE ('Y16 ' | (1 << 31))
+****************************************
+
+*man V4L2_PIX_FMT_Y16_BE(2)*
+
+Grey-scale image
+
+
+Description
+===========
+
+This is a grey-scale image with a depth of 16 bits per pixel. The most
+significant byte is stored at lower memory addresses (big-endian). Note
+the actual sampling precision may be lower than 16 bits, for example 10
+bits per pixel with values in range 0 to 1023.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Y'\ :sub:`00high`
+
+ - Y'\ :sub:`00low`
+
+ - Y'\ :sub:`01high`
+
+ - Y'\ :sub:`01low`
+
+ - Y'\ :sub:`02high`
+
+ - Y'\ :sub:`02low`
+
+ - Y'\ :sub:`03high`
+
+ - Y'\ :sub:`03low`
+
+ - .. row 2
+
+ - start + 8:
+
+ - Y'\ :sub:`10high`
+
+ - Y'\ :sub:`10low`
+
+ - Y'\ :sub:`11high`
+
+ - Y'\ :sub:`11low`
+
+ - Y'\ :sub:`12high`
+
+ - Y'\ :sub:`12low`
+
+ - Y'\ :sub:`13high`
+
+ - Y'\ :sub:`13low`
+
+ - .. row 3
+
+ - start + 16:
+
+ - Y'\ :sub:`20high`
+
+ - Y'\ :sub:`20low`
+
+ - Y'\ :sub:`21high`
+
+ - Y'\ :sub:`21low`
+
+ - Y'\ :sub:`22high`
+
+ - Y'\ :sub:`22low`
+
+ - Y'\ :sub:`23high`
+
+ - Y'\ :sub:`23low`
+
+ - .. row 4
+
+ - start + 24:
+
+ - Y'\ :sub:`30high`
+
+ - Y'\ :sub:`30low`
+
+ - Y'\ :sub:`31high`
+
+ - Y'\ :sub:`31low`
+
+ - Y'\ :sub:`32high`
+
+ - Y'\ :sub:`32low`
+
+ - Y'\ :sub:`33high`
+
+ - Y'\ :sub:`33low`
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-Y16:
+
+*************************
+V4L2_PIX_FMT_Y16 ('Y16 ')
+*************************
+
+*man V4L2_PIX_FMT_Y16(2)*
+
+Grey-scale image
+
+
+Description
+===========
+
+This is a grey-scale image with a depth of 16 bits per pixel. The least
+significant byte is stored at lower memory addresses (little-endian).
+Note the actual sampling precision may be lower than 16 bits, for
+example 10 bits per pixel with values in range 0 to 1023.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Y'\ :sub:`00low`
+
+ - Y'\ :sub:`00high`
+
+ - Y'\ :sub:`01low`
+
+ - Y'\ :sub:`01high`
+
+ - Y'\ :sub:`02low`
+
+ - Y'\ :sub:`02high`
+
+ - Y'\ :sub:`03low`
+
+ - Y'\ :sub:`03high`
+
+ - .. row 2
+
+ - start + 8:
+
+ - Y'\ :sub:`10low`
+
+ - Y'\ :sub:`10high`
+
+ - Y'\ :sub:`11low`
+
+ - Y'\ :sub:`11high`
+
+ - Y'\ :sub:`12low`
+
+ - Y'\ :sub:`12high`
+
+ - Y'\ :sub:`13low`
+
+ - Y'\ :sub:`13high`
+
+ - .. row 3
+
+ - start + 16:
+
+ - Y'\ :sub:`20low`
+
+ - Y'\ :sub:`20high`
+
+ - Y'\ :sub:`21low`
+
+ - Y'\ :sub:`21high`
+
+ - Y'\ :sub:`22low`
+
+ - Y'\ :sub:`22high`
+
+ - Y'\ :sub:`23low`
+
+ - Y'\ :sub:`23high`
+
+ - .. row 4
+
+ - start + 24:
+
+ - Y'\ :sub:`30low`
+
+ - Y'\ :sub:`30high`
+
+ - Y'\ :sub:`31low`
+
+ - Y'\ :sub:`31high`
+
+ - Y'\ :sub:`32low`
+
+ - Y'\ :sub:`32high`
+
+ - Y'\ :sub:`33low`
+
+ - Y'\ :sub:`33high`
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-Y41P:
+
+**************************
+V4L2_PIX_FMT_Y41P ('Y41P')
+**************************
+
+*man V4L2_PIX_FMT_Y41P(2)*
+
+Format with ¼ horizontal chroma resolution, also known as YUV 4:1:1
+
+
+Description
+===========
+
+In this format each 12 bytes is eight pixels. In the twelve bytes are
+two CbCr pairs and eight Y's. The first CbCr pair goes with the first
+four Y's, and the second CbCr pair goes with the other four Y's. The Cb
+and Cr components have one fourth the horizontal resolution of the Y
+component.
+
+Do not confuse this format with
+:ref:`V4L2_PIX_FMT_YUV411P <V4L2-PIX-FMT-YUV411P>`. Y41P is derived
+from "YUV 4:1:1 *packed*", while YUV411P stands for "YUV 4:1:1
+*planar*".
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Cb\ :sub:`00`
+
+ - Y'\ :sub:`00`
+
+ - Cr\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Cb\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Cr\ :sub:`01`
+
+ - Y'\ :sub:`03`
+
+ - Y'\ :sub:`04`
+
+ - Y'\ :sub:`05`
+
+ - Y'\ :sub:`06`
+
+ - Y'\ :sub:`07`
+
+ - .. row 2
+
+ - start + 12:
+
+ - Cb\ :sub:`10`
+
+ - Y'\ :sub:`10`
+
+ - Cr\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Cb\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Cr\ :sub:`11`
+
+ - Y'\ :sub:`13`
+
+ - Y'\ :sub:`14`
+
+ - Y'\ :sub:`15`
+
+ - Y'\ :sub:`16`
+
+ - Y'\ :sub:`17`
+
+ - .. row 3
+
+ - start + 24:
+
+ - Cb\ :sub:`20`
+
+ - Y'\ :sub:`20`
+
+ - Cr\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Cb\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Cr\ :sub:`21`
+
+ - Y'\ :sub:`23`
+
+ - Y'\ :sub:`24`
+
+ - Y'\ :sub:`25`
+
+ - Y'\ :sub:`26`
+
+ - Y'\ :sub:`27`
+
+ - .. row 4
+
+ - start + 36:
+
+ - Cb\ :sub:`30`
+
+ - Y'\ :sub:`30`
+
+ - Cr\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Cb\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Cr\ :sub:`31`
+
+ - Y'\ :sub:`33`
+
+ - Y'\ :sub:`34`
+
+ - Y'\ :sub:`35`
+
+ - Y'\ :sub:`36`
+
+ - Y'\ :sub:`37`
+
+
+**Color Sample Location..**
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ - 1
+
+ -
+ - 2
+
+ - 3
+
+ - 4
+
+ - 5
+
+ -
+ - 6
+
+ - 7
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - .. row 3
+
+ - 1
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - .. row 4
+
+ - 2
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - .. row 5
+
+ - 3
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-Y8I:
+
+*************************
+V4L2_PIX_FMT_Y8I ('Y8I ')
+*************************
+
+*man V4L2_PIX_FMT_Y8I(2)*
+
+Interleaved grey-scale image, e.g. from a stereo-pair
+
+
+Description
+===========
+
+This is a grey-scale image with a depth of 8 bits per pixel, but with
+pixels from 2 sources interleaved. Each pixel is stored in a 16-bit
+word. E.g. the R200 RealSense camera stores pixel from the left sensor
+in lower and from the right sensor in the higher 8 bits.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Y'\ :sub:`00left`
+
+ - Y'\ :sub:`00right`
+
+ - Y'\ :sub:`01left`
+
+ - Y'\ :sub:`01right`
+
+ - Y'\ :sub:`02left`
+
+ - Y'\ :sub:`02right`
+
+ - Y'\ :sub:`03left`
+
+ - Y'\ :sub:`03right`
+
+ - .. row 2
+
+ - start + 8:
+
+ - Y'\ :sub:`10left`
+
+ - Y'\ :sub:`10right`
+
+ - Y'\ :sub:`11left`
+
+ - Y'\ :sub:`11right`
+
+ - Y'\ :sub:`12left`
+
+ - Y'\ :sub:`12right`
+
+ - Y'\ :sub:`13left`
+
+ - Y'\ :sub:`13right`
+
+ - .. row 3
+
+ - start + 16:
+
+ - Y'\ :sub:`20left`
+
+ - Y'\ :sub:`20right`
+
+ - Y'\ :sub:`21left`
+
+ - Y'\ :sub:`21right`
+
+ - Y'\ :sub:`22left`
+
+ - Y'\ :sub:`22right`
+
+ - Y'\ :sub:`23left`
+
+ - Y'\ :sub:`23right`
+
+ - .. row 4
+
+ - start + 24:
+
+ - Y'\ :sub:`30left`
+
+ - Y'\ :sub:`30right`
+
+ - Y'\ :sub:`31left`
+
+ - Y'\ :sub:`31right`
+
+ - Y'\ :sub:`32left`
+
+ - Y'\ :sub:`32right`
+
+ - Y'\ :sub:`33left`
+
+ - Y'\ :sub:`33right`
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-YVU410:
+.. _v4l2-pix-fmt-yuv410:
+
+**********************************************************
+V4L2_PIX_FMT_YVU410 ('YVU9'), V4L2_PIX_FMT_YUV410 ('YUV9')
+**********************************************************
+
+*man V4L2_PIX_FMT_YVU410(2)*
+
+V4L2_PIX_FMT_YUV410
+Planar formats with ¼ horizontal and vertical chroma resolution, also
+known as YUV 4:1:0
+
+
+Description
+===========
+
+These are planar formats, as opposed to a packed format. The three
+components are separated into three sub-images or planes. The Y plane is
+first. The Y plane has one byte per pixel. For ``V4L2_PIX_FMT_YVU410``,
+the Cr plane immediately follows the Y plane in memory. The Cr plane is
+¼ the width and ¼ the height of the Y plane (and of the image). Each Cr
+belongs to 16 pixels, a four-by-four square of the image. Following the
+Cr plane is the Cb plane, just like the Cr plane.
+``V4L2_PIX_FMT_YUV410`` is the same, except the Cb plane comes first,
+then the Cr plane.
+
+If the Y plane has pad bytes after each row, then the Cr and Cb planes
+have ¼ as many pad bytes after their rows. In other words, four Cx rows
+(including padding) are exactly as long as one Y row (including
+padding).
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Y'\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start + 4:
+
+ - Y'\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start + 8:
+
+ - Y'\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Y'\ :sub:`23`
+
+ - .. row 4
+
+ - start + 12:
+
+ - Y'\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Y'\ :sub:`33`
+
+ - .. row 5
+
+ - start + 16:
+
+ - Cr\ :sub:`00`
+
+ - .. row 6
+
+ - start + 17:
+
+ - Cb\ :sub:`00`
+
+
+**Color Sample Location..**
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ -
+ - 1
+
+ -
+ - 2
+
+ -
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - .. row 3
+
+ -
+
+ - .. row 4
+
+ - 1
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - .. row 5
+
+ -
+ -
+ -
+ -
+ - C
+
+ -
+ -
+ -
+
+ - .. row 6
+
+ - 2
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - .. row 7
+
+ -
+
+ - .. row 8
+
+ - 3
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-YUV411P:
+
+*****************************
+V4L2_PIX_FMT_YUV411P ('411P')
+*****************************
+
+*man V4L2_PIX_FMT_YUV411P(2)*
+
+Format with ¼ horizontal chroma resolution, also known as YUV 4:1:1.
+Planar layout as opposed to ``V4L2_PIX_FMT_Y41P``
+
+
+Description
+===========
+
+This format is not commonly used. This is a planar format similar to the
+4:2:2 planar format except with half as many chroma. The three
+components are separated into three sub-images or planes. The Y plane is
+first. The Y plane has one byte per pixel. The Cb plane immediately
+follows the Y plane in memory. The Cb plane is ¼ the width of the Y
+plane (and of the image). Each Cb belongs to 4 pixels all on the same
+row. For example, Cb\ :sub:`0` belongs to Y'\ :sub:`00`, Y'\ :sub:`01`,
+Y'\ :sub:`02` and Y'\ :sub:`03`. Following the Cb plane is the Cr plane,
+just like the Cb plane.
+
+If the Y plane has pad bytes after each row, then the Cr and Cb planes
+have ¼ as many pad bytes after their rows. In other words, four C x rows
+(including padding) is exactly as long as one Y row (including padding).
+
+**Byte Order.**
+Each cell is one byte.
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Y'\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start + 4:
+
+ - Y'\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start + 8:
+
+ - Y'\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Y'\ :sub:`23`
+
+ - .. row 4
+
+ - start + 12:
+
+ - Y'\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Y'\ :sub:`33`
+
+ - .. row 5
+
+ - start + 16:
+
+ - Cb\ :sub:`00`
+
+ - .. row 6
+
+ - start + 17:
+
+ - Cb\ :sub:`10`
+
+ - .. row 7
+
+ - start + 18:
+
+ - Cb\ :sub:`20`
+
+ - .. row 8
+
+ - start + 19:
+
+ - Cb\ :sub:`30`
+
+ - .. row 9
+
+ - start + 20:
+
+ - Cr\ :sub:`00`
+
+ - .. row 10
+
+ - start + 21:
+
+ - Cr\ :sub:`10`
+
+ - .. row 11
+
+ - start + 22:
+
+ - Cr\ :sub:`20`
+
+ - .. row 12
+
+ - start + 23:
+
+ - Cr\ :sub:`30`
+
+
+**Color Sample Location..**
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ - 1
+
+ -
+ - 2
+
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - .. row 3
+
+ - 1
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - .. row 4
+
+ - 2
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - .. row 5
+
+ - 3
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-YVU420:
+.. _V4L2-PIX-FMT-YUV420:
+
+**********************************************************
+V4L2_PIX_FMT_YVU420 ('YV12'), V4L2_PIX_FMT_YUV420 ('YU12')
+**********************************************************
+
+*man V4L2_PIX_FMT_YVU420(2)*
+
+V4L2_PIX_FMT_YUV420
+Planar formats with ½ horizontal and vertical chroma resolution, also
+known as YUV 4:2:0
+
+
+Description
+===========
+
+These are planar formats, as opposed to a packed format. The three
+components are separated into three sub- images or planes. The Y plane
+is first. The Y plane has one byte per pixel. For
+``V4L2_PIX_FMT_YVU420``, the Cr plane immediately follows the Y plane in
+memory. The Cr plane is half the width and half the height of the Y
+plane (and of the image). Each Cr belongs to four pixels, a two-by-two
+square of the image. For example, Cr\ :sub:`0` belongs to Y'\ :sub:`00`,
+Y'\ :sub:`01`, Y'\ :sub:`10`, and Y'\ :sub:`11`. Following the Cr plane
+is the Cb plane, just like the Cr plane. ``V4L2_PIX_FMT_YUV420`` is the
+same except the Cb plane comes first, then the Cr plane.
+
+If the Y plane has pad bytes after each row, then the Cr and Cb planes
+have half as many pad bytes after their rows. In other words, two Cx
+rows (including padding) is exactly as long as one Y row (including
+padding).
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Y'\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start + 4:
+
+ - Y'\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start + 8:
+
+ - Y'\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Y'\ :sub:`23`
+
+ - .. row 4
+
+ - start + 12:
+
+ - Y'\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Y'\ :sub:`33`
+
+ - .. row 5
+
+ - start + 16:
+
+ - Cr\ :sub:`00`
+
+ - Cr\ :sub:`01`
+
+ - .. row 6
+
+ - start + 18:
+
+ - Cr\ :sub:`10`
+
+ - Cr\ :sub:`11`
+
+ - .. row 7
+
+ - start + 20:
+
+ - Cb\ :sub:`00`
+
+ - Cb\ :sub:`01`
+
+ - .. row 8
+
+ - start + 22:
+
+ - Cb\ :sub:`10`
+
+ - Cb\ :sub:`11`
+
+
+**Color Sample Location..**
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ -
+ - 1
+
+ -
+ - 2
+
+ -
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - .. row 3
+
+ -
+ -
+ - C
+
+ -
+ -
+ -
+ - C
+
+ -
+
+ - .. row 4
+
+ - 1
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - .. row 5
+
+ -
+
+ - .. row 6
+
+ - 2
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - .. row 7
+
+ -
+ -
+ - C
+
+ -
+ -
+ -
+ - C
+
+ -
+
+ - .. row 8
+
+ - 3
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-YUV420M:
+.. _v4l2-pix-fmt-yvu420m:
+
+************************************************************
+V4L2_PIX_FMT_YUV420M ('YM12'), V4L2_PIX_FMT_YVU420M ('YM21')
+************************************************************
+
+*man V4L2_PIX_FMT_YUV420M(2)*
+
+V4L2_PIX_FMT_YVU420M
+Variation of ``V4L2_PIX_FMT_YUV420`` and ``V4L2_PIX_FMT_YVU420`` with
+planes non contiguous in memory.
+
+
+Description
+===========
+
+This is a multi-planar format, as opposed to a packed format. The three
+components are separated into three sub-images or planes.
+
+The Y plane is first. The Y plane has one byte per pixel. For
+``V4L2_PIX_FMT_YUV420M`` the Cb data constitutes the second plane which
+is half the width and half the height of the Y plane (and of the image).
+Each Cb belongs to four pixels, a two-by-two square of the image. For
+example, Cb\ :sub:`0` belongs to Y'\ :sub:`00`, Y'\ :sub:`01`,
+Y'\ :sub:`10`, and Y'\ :sub:`11`. The Cr data, just like the Cb plane,
+is in the third plane.
+
+``V4L2_PIX_FMT_YVU420M`` is the same except the Cr data is stored in the
+second plane and the Cb data in the third plane.
+
+If the Y plane has pad bytes after each row, then the Cb and Cr planes
+have half as many pad bytes after their rows. In other words, two Cx
+rows (including padding) is exactly as long as one Y row (including
+padding).
+
+``V4L2_PIX_FMT_YUV420M`` and ``V4L2_PIX_FMT_YVU420M`` are intended to be
+used only in drivers and applications that support the multi-planar API,
+described in :ref:`planar-apis`.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start0 + 0:
+
+ - Y'\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start0 + 4:
+
+ - Y'\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start0 + 8:
+
+ - Y'\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Y'\ :sub:`23`
+
+ - .. row 4
+
+ - start0 + 12:
+
+ - Y'\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Y'\ :sub:`33`
+
+ - .. row 5
+
+ -
+
+ - .. row 6
+
+ - start1 + 0:
+
+ - Cb\ :sub:`00`
+
+ - Cb\ :sub:`01`
+
+ - .. row 7
+
+ - start1 + 2:
+
+ - Cb\ :sub:`10`
+
+ - Cb\ :sub:`11`
+
+ - .. row 8
+
+ -
+
+ - .. row 9
+
+ - start2 + 0:
+
+ - Cr\ :sub:`00`
+
+ - Cr\ :sub:`01`
+
+ - .. row 10
+
+ - start2 + 2:
+
+ - Cr\ :sub:`10`
+
+ - Cr\ :sub:`11`
+
+
+**Color Sample Location..**
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ -
+ - 1
+
+ -
+ - 2
+
+ -
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - .. row 3
+
+ -
+ -
+ - C
+
+ -
+ -
+ -
+ - C
+
+ -
+
+ - .. row 4
+
+ - 1
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - .. row 5
+
+ -
+
+ - .. row 6
+
+ - 2
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - .. row 7
+
+ -
+ -
+ - C
+
+ -
+ -
+ -
+ - C
+
+ -
+
+ - .. row 8
+
+ - 3
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-YUV422M:
+.. _v4l2-pix-fmt-yvu422m:
+
+************************************************************
+V4L2_PIX_FMT_YUV422M ('YM16'), V4L2_PIX_FMT_YVU422M ('YM61')
+************************************************************
+
+*man V4L2_PIX_FMT_YUV422M(2)*
+
+V4L2_PIX_FMT_YVU422M
+Planar formats with ½ horizontal resolution, also known as YUV and YVU
+4:2:2
+
+
+Description
+===========
+
+This is a multi-planar format, as opposed to a packed format. The three
+components are separated into three sub-images or planes.
+
+The Y plane is first. The Y plane has one byte per pixel. For
+``V4L2_PIX_FMT_YUV422M`` the Cb data constitutes the second plane which
+is half the width of the Y plane (and of the image). Each Cb belongs to
+two pixels. For example, Cb\ :sub:`0` belongs to Y'\ :sub:`00`,
+Y'\ :sub:`01`. The Cr data, just like the Cb plane, is in the third
+plane.
+
+``V4L2_PIX_FMT_YVU422M`` is the same except the Cr data is stored in the
+second plane and the Cb data in the third plane.
+
+If the Y plane has pad bytes after each row, then the Cb and Cr planes
+have half as many pad bytes after their rows. In other words, two Cx
+rows (including padding) is exactly as long as one Y row (including
+padding).
+
+``V4L2_PIX_FMT_YUV422M`` and ``V4L2_PIX_FMT_YVU422M`` are intended to be
+used only in drivers and applications that support the multi-planar API,
+described in :ref:`planar-apis`.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start0 + 0:
+
+ - Y'\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start0 + 4:
+
+ - Y'\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start0 + 8:
+
+ - Y'\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Y'\ :sub:`23`
+
+ - .. row 4
+
+ - start0 + 12:
+
+ - Y'\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Y'\ :sub:`33`
+
+ - .. row 5
+
+ -
+
+ - .. row 6
+
+ - start1 + 0:
+
+ - Cb\ :sub:`00`
+
+ - Cb\ :sub:`01`
+
+ - .. row 7
+
+ - start1 + 2:
+
+ - Cb\ :sub:`10`
+
+ - Cb\ :sub:`11`
+
+ - .. row 8
+
+ - start1 + 4:
+
+ - Cb\ :sub:`20`
+
+ - Cb\ :sub:`21`
+
+ - .. row 9
+
+ - start1 + 6:
+
+ - Cb\ :sub:`30`
+
+ - Cb\ :sub:`31`
+
+ - .. row 10
+
+ -
+
+ - .. row 11
+
+ - start2 + 0:
+
+ - Cr\ :sub:`00`
+
+ - Cr\ :sub:`01`
+
+ - .. row 12
+
+ - start2 + 2:
+
+ - Cr\ :sub:`10`
+
+ - Cr\ :sub:`11`
+
+ - .. row 13
+
+ - start2 + 4:
+
+ - Cr\ :sub:`20`
+
+ - Cr\ :sub:`21`
+
+ - .. row 14
+
+ - start2 + 6:
+
+ - Cr\ :sub:`30`
+
+ - Cr\ :sub:`31`
+
+
+**Color Sample Location..**
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ -
+ - 1
+
+ - 2
+
+ -
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 3
+
+ - 1
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 4
+
+ - 2
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 5
+
+ - 3
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-YUV422P:
+
+*****************************
+V4L2_PIX_FMT_YUV422P ('422P')
+*****************************
+
+*man V4L2_PIX_FMT_YUV422P(2)*
+
+Format with ½ horizontal chroma resolution, also known as YUV 4:2:2.
+Planar layout as opposed to ``V4L2_PIX_FMT_YUYV``
+
+
+Description
+===========
+
+This format is not commonly used. This is a planar version of the YUYV
+format. The three components are separated into three sub-images or
+planes. The Y plane is first. The Y plane has one byte per pixel. The Cb
+plane immediately follows the Y plane in memory. The Cb plane is half
+the width of the Y plane (and of the image). Each Cb belongs to two
+pixels. For example, Cb\ :sub:`0` belongs to Y'\ :sub:`00`,
+Y'\ :sub:`01`. Following the Cb plane is the Cr plane, just like the Cb
+plane.
+
+If the Y plane has pad bytes after each row, then the Cr and Cb planes
+have half as many pad bytes after their rows. In other words, two Cx
+rows (including padding) is exactly as long as one Y row (including
+padding).
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Y'\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start + 4:
+
+ - Y'\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start + 8:
+
+ - Y'\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Y'\ :sub:`23`
+
+ - .. row 4
+
+ - start + 12:
+
+ - Y'\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Y'\ :sub:`33`
+
+ - .. row 5
+
+ - start + 16:
+
+ - Cb\ :sub:`00`
+
+ - Cb\ :sub:`01`
+
+ - .. row 6
+
+ - start + 18:
+
+ - Cb\ :sub:`10`
+
+ - Cb\ :sub:`11`
+
+ - .. row 7
+
+ - start + 20:
+
+ - Cb\ :sub:`20`
+
+ - Cb\ :sub:`21`
+
+ - .. row 8
+
+ - start + 22:
+
+ - Cb\ :sub:`30`
+
+ - Cb\ :sub:`31`
+
+ - .. row 9
+
+ - start + 24:
+
+ - Cr\ :sub:`00`
+
+ - Cr\ :sub:`01`
+
+ - .. row 10
+
+ - start + 26:
+
+ - Cr\ :sub:`10`
+
+ - Cr\ :sub:`11`
+
+ - .. row 11
+
+ - start + 28:
+
+ - Cr\ :sub:`20`
+
+ - Cr\ :sub:`21`
+
+ - .. row 12
+
+ - start + 30:
+
+ - Cr\ :sub:`30`
+
+ - Cr\ :sub:`31`
+
+
+**Color Sample Location..**
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ -
+ - 1
+
+ - 2
+
+ -
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 3
+
+ - 1
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 4
+
+ - 2
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 5
+
+ - 3
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-YUV444M:
+.. _v4l2-pix-fmt-yvu444m:
+
+************************************************************
+V4L2_PIX_FMT_YUV444M ('YM24'), V4L2_PIX_FMT_YVU444M ('YM42')
+************************************************************
+
+*man V4L2_PIX_FMT_YUV444M(2)*
+
+V4L2_PIX_FMT_YVU444M
+Planar formats with full horizontal resolution, also known as YUV and
+YVU 4:4:4
+
+
+Description
+===========
+
+This is a multi-planar format, as opposed to a packed format. The three
+components are separated into three sub-images or planes.
+
+The Y plane is first. The Y plane has one byte per pixel. For
+``V4L2_PIX_FMT_YUV444M`` the Cb data constitutes the second plane which
+is the same width and height as the Y plane (and as the image). The Cr
+data, just like the Cb plane, is in the third plane.
+
+``V4L2_PIX_FMT_YVU444M`` is the same except the Cr data is stored in the
+second plane and the Cb data in the third plane.
+
+If the Y plane has pad bytes after each row, then the Cb and Cr planes
+have the same number of pad bytes after their rows.
+
+``V4L2_PIX_FMT_YUV444M`` and ``V4L2_PIX_FMT_YUV444M`` are intended to be
+used only in drivers and applications that support the multi-planar API,
+described in :ref:`planar-apis`.
+
+**Byte Order.**
+Each cell is one byte.
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start0 + 0:
+
+ - Y'\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start0 + 4:
+
+ - Y'\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start0 + 8:
+
+ - Y'\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Y'\ :sub:`23`
+
+ - .. row 4
+
+ - start0 + 12:
+
+ - Y'\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Y'\ :sub:`33`
+
+ - .. row 5
+
+ -
+
+ - .. row 6
+
+ - start1 + 0:
+
+ - Cb\ :sub:`00`
+
+ - Cb\ :sub:`01`
+
+ - Cb\ :sub:`02`
+
+ - Cb\ :sub:`03`
+
+ - .. row 7
+
+ - start1 + 4:
+
+ - Cb\ :sub:`10`
+
+ - Cb\ :sub:`11`
+
+ - Cb\ :sub:`12`
+
+ - Cb\ :sub:`13`
+
+ - .. row 8
+
+ - start1 + 8:
+
+ - Cb\ :sub:`20`
+
+ - Cb\ :sub:`21`
+
+ - Cb\ :sub:`22`
+
+ - Cb\ :sub:`23`
+
+ - .. row 9
+
+ - start1 + 12:
+
+ - Cb\ :sub:`20`
+
+ - Cb\ :sub:`21`
+
+ - Cb\ :sub:`32`
+
+ - Cb\ :sub:`33`
+
+ - .. row 10
+
+ -
+
+ - .. row 11
+
+ - start2 + 0:
+
+ - Cr\ :sub:`00`
+
+ - Cr\ :sub:`01`
+
+ - Cr\ :sub:`02`
+
+ - Cr\ :sub:`03`
+
+ - .. row 12
+
+ - start2 + 4:
+
+ - Cr\ :sub:`10`
+
+ - Cr\ :sub:`11`
+
+ - Cr\ :sub:`12`
+
+ - Cr\ :sub:`13`
+
+ - .. row 13
+
+ - start2 + 8:
+
+ - Cr\ :sub:`20`
+
+ - Cr\ :sub:`21`
+
+ - Cr\ :sub:`22`
+
+ - Cr\ :sub:`23`
+
+ - .. row 14
+
+ - start2 + 12:
+
+ - Cr\ :sub:`30`
+
+ - Cr\ :sub:`31`
+
+ - Cr\ :sub:`32`
+
+ - Cr\ :sub:`33`
+
+
+**Color Sample Location..**
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ - 1
+
+ - 2
+
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - YC
+
+ - YC
+
+ - YC
+
+ - YC
+
+ - .. row 3
+
+ - 1
+
+ - YC
+
+ - YC
+
+ - YC
+
+ - YC
+
+ - .. row 4
+
+ - 2
+
+ - YC
+
+ - YC
+
+ - YC
+
+ - YC
+
+ - .. row 5
+
+ - 3
+
+ - YC
+
+ - YC
+
+ - YC
+
+ - YC
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-YUYV:
+
+**************************
+V4L2_PIX_FMT_YUYV ('YUYV')
+**************************
+
+*man V4L2_PIX_FMT_YUYV(2)*
+
+Packed format with ½ horizontal chroma resolution, also known as YUV
+4:2:2
+
+
+Description
+===========
+
+In this format each four bytes is two pixels. Each four bytes is two
+Y's, a Cb and a Cr. Each Y goes to one of the pixels, and the Cb and Cr
+belong to both pixels. As you can see, the Cr and Cb components have
+half the horizontal resolution of the Y component. ``V4L2_PIX_FMT_YUYV``
+is known in the Windows environment as YUY2.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Y'\ :sub:`00`
+
+ - Cb\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Cr\ :sub:`00`
+
+ - Y'\ :sub:`02`
+
+ - Cb\ :sub:`01`
+
+ - Y'\ :sub:`03`
+
+ - Cr\ :sub:`01`
+
+ - .. row 2
+
+ - start + 8:
+
+ - Y'\ :sub:`10`
+
+ - Cb\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Cr\ :sub:`10`
+
+ - Y'\ :sub:`12`
+
+ - Cb\ :sub:`11`
+
+ - Y'\ :sub:`13`
+
+ - Cr\ :sub:`11`
+
+ - .. row 3
+
+ - start + 16:
+
+ - Y'\ :sub:`20`
+
+ - Cb\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Cr\ :sub:`20`
+
+ - Y'\ :sub:`22`
+
+ - Cb\ :sub:`21`
+
+ - Y'\ :sub:`23`
+
+ - Cr\ :sub:`21`
+
+ - .. row 4
+
+ - start + 24:
+
+ - Y'\ :sub:`30`
+
+ - Cb\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Cr\ :sub:`30`
+
+ - Y'\ :sub:`32`
+
+ - Cb\ :sub:`31`
+
+ - Y'\ :sub:`33`
+
+ - Cr\ :sub:`31`
+
+
+**Color Sample Location..**
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ -
+ - 1
+
+ -
+ - 2
+
+ -
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ - C
+
+ - Y
+
+ -
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 3
+
+ - 1
+
+ - Y
+
+ - C
+
+ - Y
+
+ -
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 4
+
+ - 2
+
+ - Y
+
+ - C
+
+ - Y
+
+ -
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 5
+
+ - 3
+
+ - Y
+
+ - C
+
+ - Y
+
+ -
+ - Y
+
+ - C
+
+ - Y
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-YVYU:
+
+**************************
+V4L2_PIX_FMT_YVYU ('YVYU')
+**************************
+
+*man V4L2_PIX_FMT_YVYU(2)*
+
+Variation of ``V4L2_PIX_FMT_YUYV`` with different order of samples in
+memory
+
+
+Description
+===========
+
+In this format each four bytes is two pixels. Each four bytes is two
+Y's, a Cb and a Cr. Each Y goes to one of the pixels, and the Cb and Cr
+belong to both pixels. As you can see, the Cr and Cb components have
+half the horizontal resolution of the Y component.
+
+**Byte Order.**
+Each cell is one byte.
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Y'\ :sub:`00`
+
+ - Cr\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Cb\ :sub:`00`
+
+ - Y'\ :sub:`02`
+
+ - Cr\ :sub:`01`
+
+ - Y'\ :sub:`03`
+
+ - Cb\ :sub:`01`
+
+ - .. row 2
+
+ - start + 8:
+
+ - Y'\ :sub:`10`
+
+ - Cr\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Cb\ :sub:`10`
+
+ - Y'\ :sub:`12`
+
+ - Cr\ :sub:`11`
+
+ - Y'\ :sub:`13`
+
+ - Cb\ :sub:`11`
+
+ - .. row 3
+
+ - start + 16:
+
+ - Y'\ :sub:`20`
+
+ - Cr\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Cb\ :sub:`20`
+
+ - Y'\ :sub:`22`
+
+ - Cr\ :sub:`21`
+
+ - Y'\ :sub:`23`
+
+ - Cb\ :sub:`21`
+
+ - .. row 4
+
+ - start + 24:
+
+ - Y'\ :sub:`30`
+
+ - Cr\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Cb\ :sub:`30`
+
+ - Y'\ :sub:`32`
+
+ - Cr\ :sub:`31`
+
+ - Y'\ :sub:`33`
+
+ - Cb\ :sub:`31`
+
+
+**Color Sample Location..**
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ -
+ - 1
+
+ - 2
+
+ -
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 3
+
+ - 1
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 4
+
+ - 2
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 5
+
+ - 3
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-Z16:
+
+*************************
+V4L2_PIX_FMT_Z16 ('Z16 ')
+*************************
+
+*man V4L2_PIX_FMT_Z16(2)*
+
+Interleaved grey-scale image, e.g. from a stereo-pair
+
+
+Description
+===========
+
+This is a 16-bit format, representing depth data. Each pixel is a
+distance to the respective point in the image coordinates. Distance unit
+can vary and has to be negotiated with the device separately. Each pixel
+is stored in a 16-bit word in the little endian byte order.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Z\ :sub:`00low`
+
+ - Z\ :sub:`00high`
+
+ - Z\ :sub:`01low`
+
+ - Z\ :sub:`01high`
+
+ - Z\ :sub:`02low`
+
+ - Z\ :sub:`02high`
+
+ - Z\ :sub:`03low`
+
+ - Z\ :sub:`03high`
+
+ - .. row 2
+
+ - start + 8:
+
+ - Z\ :sub:`10low`
+
+ - Z\ :sub:`10high`
+
+ - Z\ :sub:`11low`
+
+ - Z\ :sub:`11high`
+
+ - Z\ :sub:`12low`
+
+ - Z\ :sub:`12high`
+
+ - Z\ :sub:`13low`
+
+ - Z\ :sub:`13high`
+
+ - .. row 3
+
+ - start + 16:
+
+ - Z\ :sub:`20low`
+
+ - Z\ :sub:`20high`
+
+ - Z\ :sub:`21low`
+
+ - Z\ :sub:`21high`
+
+ - Z\ :sub:`22low`
+
+ - Z\ :sub:`22high`
+
+ - Z\ :sub:`23low`
+
+ - Z\ :sub:`23high`
+
+ - .. row 4
+
+ - start + 24:
+
+ - Z\ :sub:`30low`
+
+ - Z\ :sub:`30high`
+
+ - Z\ :sub:`31low`
+
+ - Z\ :sub:`31high`
+
+ - Z\ :sub:`32low`
+
+ - Z\ :sub:`32high`
+
+ - Z\ :sub:`33low`
+
+ - Z\ :sub:`33high`
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _pixfmt:
+
+#############
+Image Formats
+#############
+The V4L2 API was primarily designed for devices exchanging image data
+with applications. The :ref:`struct v4l2_pix_format <v4l2-pix-format>` and
+:ref:`struct v4l2_pix_format_mplane <v4l2-pix-format-mplane>` structures define the
+format and layout of an image in memory. The former is used with the
+single-planar API, while the latter is used with the multi-planar
+version (see :ref:`planar-apis`). Image formats are negotiated with
+the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. (The explanations here
+focus on video capturing and output, for overlay frame buffer formats
+see also :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`.)
+
+
+.. toctree::
+ :maxdepth: 1
+
+ pixfmt-002
+ pixfmt-003
+ pixfmt-004
+ colorspaces
+ pixfmt-006
+ pixfmt-007
+ pixfmt-008
+ pixfmt-indexed
+ pixfmt-rgb
+ yuv-formats
+ depth-formats
+ pixfmt-013
+ sdr-formats
+ pixfmt-reserved
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _planar-apis:
+
+*****************************
+Single- and multi-planar APIs
+*****************************
+
+Some devices require data for each input or output video frame to be
+placed in discontiguous memory buffers. In such cases, one video frame
+has to be addressed using more than one memory address, i.e. one pointer
+per "plane". A plane is a sub-buffer of the current frame. For examples
+of such formats see :ref:`pixfmt`.
+
+Initially, V4L2 API did not support multi-planar buffers and a set of
+extensions has been introduced to handle them. Those extensions
+constitute what is being referred to as the "multi-planar API".
+
+Some of the V4L2 API calls and structures are interpreted differently,
+depending on whether single- or multi-planar API is being used. An
+application can choose whether to use one or the other by passing a
+corresponding buffer type to its ioctl calls. Multi-planar versions of
+buffer types are suffixed with an ``_MPLANE`` string. For a list of
+available multi-planar buffer types see enum
+:ref:`v4l2_buf_type <v4l2-buf-type>`.
+
+
+Multi-planar formats
+====================
+
+Multi-planar API introduces new multi-planar formats. Those formats use
+a separate set of FourCC codes. It is important to distinguish between
+the multi-planar API and a multi-planar format. Multi-planar API calls
+can handle all single-planar formats as well (as long as they are passed
+in multi-planar API structures), while the single-planar API cannot
+handle multi-planar formats.
+
+
+Calls that distinguish between single and multi-planar APIs
+===========================================================
+
+:ref:`VIDIOC_QUERYCAP <VIDIOC_QUERYCAP>`
+ Two additional multi-planar capabilities are added. They can be set
+ together with non-multi-planar ones for devices that handle both
+ single- and multi-planar formats.
+
+:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>`
+ New structures for describing multi-planar formats are added: struct
+ :ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` and
+ struct :ref:`v4l2_plane_pix_format <v4l2-plane-pix-format>`.
+ Drivers may define new multi-planar formats, which have distinct
+ FourCC codes from the existing single-planar ones.
+
+:ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_QUERYBUF <VIDIOC_QUERYBUF>`
+ A new struct :ref:`v4l2_plane <v4l2-plane>` structure for
+ describing planes is added. Arrays of this structure are passed in
+ the new ``m.planes`` field of struct
+ :ref:`v4l2_buffer <v4l2-buffer>`.
+
+:ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`
+ Will allocate multi-planar buffers as requested.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _querycap:
+
+*********************
+Querying Capabilities
+*********************
+
+Because V4L2 covers a wide variety of devices not all aspects of the API
+are equally applicable to all types of devices. Furthermore devices of
+the same type have different capabilities and this specification permits
+the omission of a few complicated and less important parts of the API.
+
+The :ref:`VIDIOC_QUERYCAP` ioctl is available to
+check if the kernel device is compatible with this specification, and to
+query the :ref:`functions <devices>` and :ref:`I/O methods <io>`
+supported by the device.
+
+Starting with kernel version 3.1, :ref:`VIDIOC_QUERYCAP`
+will return the V4L2 API version used by the driver, with generally
+matches the Kernel version. There's no need of using
+:ref:`VIDIOC_QUERYCAP` to check if a specific ioctl
+is supported, the V4L2 core now returns ``ENOTTY`` if a driver doesn't
+provide support for an ioctl.
+
+Other features can be queried by calling the respective ioctl, for
+example :ref:`VIDIOC_ENUMINPUT` to learn about the
+number, types and names of video connectors on the device. Although
+abstraction is a major objective of this API, the
+:ref:`VIDIOC_QUERYCAP` ioctl also allows driver
+specific applications to reliably identify the driver.
+
+All V4L2 drivers must support :ref:`VIDIOC_QUERYCAP`.
+Applications should always call this ioctl after opening the device.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _rw:
+
+**********
+Read/Write
+**********
+
+Input and output devices support the :ref:`read() <func-read>` and
+:ref:`write() <func-write>` function, respectively, when the
+``V4L2_CAP_READWRITE`` flag in the ``capabilities`` field of struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP` ioctl is set.
+
+Drivers may need the CPU to copy the data, but they may also support DMA
+to or from user memory, so this I/O method is not necessarily less
+efficient than other methods merely exchanging buffer pointers. It is
+considered inferior though because no meta-information like frame
+counters or timestamps are passed. This information is necessary to
+recognize frame dropping and to synchronize with other data streams.
+However this is also the simplest I/O method, requiring little or no
+setup to exchange data. It permits command line stunts like this (the
+vidctrl tool is fictitious):
+
+
+.. code-block:: none
+
+ $ vidctrl /dev/video --input=0 --format=YUYV --size=352x288
+ $ dd if=/dev/video of=myimage.422 bs=202752 count=1
+
+To read from the device applications use the :ref:`read() <func-read>`
+function, to write the :ref:`write() <func-write>` function. Drivers
+must implement one I/O method if they exchange data with applications,
+but it need not be this. [1]_ When reading or writing is supported, the
+driver must also support the :ref:`select() <func-select>` and
+:ref:`poll() <func-poll>` function. [2]_
+
+.. [1]
+ It would be desirable if applications could depend on drivers
+ supporting all I/O interfaces, but as much as the complex memory
+ mapping I/O can be inadequate for some devices we have no reason to
+ require this interface, which is most useful for simple applications
+ capturing still images.
+
+.. [2]
+ At the driver level :ref:`select() <func-select>` and :ref:`poll() <func-poll>` are
+ the same, and :ref:`select() <func-select>` is too important to be optional.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _sdr-formats:
+
+***********
+SDR Formats
+***********
+
+These formats are used for :ref:`SDR <sdr>` interface only.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ pixfmt-sdr-cu08
+ pixfmt-sdr-cu16le
+ pixfmt-sdr-cs08
+ pixfmt-sdr-cs14le
+ pixfmt-sdr-ru12le
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+************
+Introduction
+************
+
+Some video capture devices can sample a subsection of a picture and
+shrink or enlarge it to an image of arbitrary size. Next, the devices
+can insert the image into larger one. Some video output devices can crop
+part of an input image, scale it up or down and insert it at an
+arbitrary scan line and horizontal offset into a video signal. We call
+these abilities cropping, scaling and composing.
+
+On a video *capture* device the source is a video signal, and the
+cropping target determine the area actually sampled. The sink is an
+image stored in a memory buffer. The composing area specifies which part
+of the buffer is actually written to by the hardware.
+
+On a video *output* device the source is an image in a memory buffer,
+and the cropping target is a part of an image to be shown on a display.
+The sink is the display or the graphics screen. The application may
+select the part of display where the image should be displayed. The size
+and position of such a window is controlled by the compose target.
+
+Rectangles for all cropping and composing targets are defined even if
+the device does supports neither cropping nor composing. Their size and
+position will be fixed in such a case. If the device does not support
+scaling then the cropping and composing rectangles have the same size.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+*****************
+Selection targets
+*****************
+
+
+.. _sel-targets-capture:
+
+.. figure:: selection-api-003_files/selection.*
+ :alt: selection.png
+ :align: center
+
+ Cropping and composing targets
+
+ Targets used by a cropping, composing and scaling process
+
+
+
+See :ref:`v4l2-selection-targets` for more information.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+*************
+Configuration
+*************
+
+Applications can use the :ref:`selection API <VIDIOC_G_SELECTION>` to
+select an area in a video signal or a buffer, and to query for default
+settings and hardware limits.
+
+Video hardware can have various cropping, composing and scaling
+limitations. It may only scale up or down, support only discrete scaling
+factors, or have different scaling abilities in the horizontal and
+vertical directions. Also it may not support scaling at all. At the same
+time the cropping/composing rectangles may have to be aligned, and both
+the source and the sink may have arbitrary upper and lower size limits.
+Therefore, as usual, drivers are expected to adjust the requested
+parameters and return the actual values selected. An application can
+control the rounding behaviour using
+:ref:`constraint flags <v4l2-selection-flags>`.
+
+
+Configuration of video capture
+==============================
+
+See figure :ref:`sel-targets-capture` for examples of the selection
+targets available for a video capture device. It is recommended to
+configure the cropping targets before to the composing targets.
+
+The range of coordinates of the top left corner, width and height of
+areas that can be sampled is given by the ``V4L2_SEL_TGT_CROP_BOUNDS``
+target. It is recommended for the driver developers to put the top/left
+corner at position ``(0,0)``. The rectangle's coordinates are expressed
+in pixels.
+
+The top left corner, width and height of the source rectangle, that is
+the area actually sampled, is given by the ``V4L2_SEL_TGT_CROP`` target.
+It uses the same coordinate system as ``V4L2_SEL_TGT_CROP_BOUNDS``. The
+active cropping area must lie completely inside the capture boundaries.
+The driver may further adjust the requested size and/or position
+according to hardware limitations.
+
+Each capture device has a default source rectangle, given by the
+``V4L2_SEL_TGT_CROP_DEFAULT`` target. This rectangle shall over what the
+driver writer considers the complete picture. Drivers shall set the
+active crop rectangle to the default when the driver is first loaded,
+but not later.
+
+The composing targets refer to a memory buffer. The limits of composing
+coordinates are obtained using ``V4L2_SEL_TGT_COMPOSE_BOUNDS``. All
+coordinates are expressed in pixels. The rectangle's top/left corner
+must be located at position ``(0,0)``. The width and height are equal to
+the image size set by :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`.
+
+The part of a buffer into which the image is inserted by the hardware is
+controlled by the ``V4L2_SEL_TGT_COMPOSE`` target. The rectangle's
+coordinates are also expressed in the same coordinate system as the
+bounds rectangle. The composing rectangle must lie completely inside
+bounds rectangle. The driver must adjust the composing rectangle to fit
+to the bounding limits. Moreover, the driver can perform other
+adjustments according to hardware limitations. The application can
+control rounding behaviour using
+:ref:`constraint flags <v4l2-selection-flags>`.
+
+For capture devices the default composing rectangle is queried using
+``V4L2_SEL_TGT_COMPOSE_DEFAULT``. It is usually equal to the bounding
+rectangle.
+
+The part of a buffer that is modified by the hardware is given by
+``V4L2_SEL_TGT_COMPOSE_PADDED``. It contains all pixels defined using
+``V4L2_SEL_TGT_COMPOSE`` plus all padding data modified by hardware
+during insertion process. All pixels outside this rectangle *must not*
+be changed by the hardware. The content of pixels that lie inside the
+padded area but outside active area is undefined. The application can
+use the padded and active rectangles to detect where the rubbish pixels
+are located and remove them if needed.
+
+
+Configuration of video output
+=============================
+
+For output devices targets and ioctls are used similarly to the video
+capture case. The *composing* rectangle refers to the insertion of an
+image into a video signal. The cropping rectangles refer to a memory
+buffer. It is recommended to configure the composing targets before to
+the cropping targets.
+
+The cropping targets refer to the memory buffer that contains an image
+to be inserted into a video signal or graphical screen. The limits of
+cropping coordinates are obtained using ``V4L2_SEL_TGT_CROP_BOUNDS``.
+All coordinates are expressed in pixels. The top/left corner is always
+point ``(0,0)``. The width and height is equal to the image size
+specified using :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
+
+The top left corner, width and height of the source rectangle, that is
+the area from which image date are processed by the hardware, is given
+by the ``V4L2_SEL_TGT_CROP``. Its coordinates are expressed in in the
+same coordinate system as the bounds rectangle. The active cropping area
+must lie completely inside the crop boundaries and the driver may
+further adjust the requested size and/or position according to hardware
+limitations.
+
+For output devices the default cropping rectangle is queried using
+``V4L2_SEL_TGT_CROP_DEFAULT``. It is usually equal to the bounding
+rectangle.
+
+The part of a video signal or graphics display where the image is
+inserted by the hardware is controlled by ``V4L2_SEL_TGT_COMPOSE``
+target. The rectangle's coordinates are expressed in pixels. The
+composing rectangle must lie completely inside the bounds rectangle. The
+driver must adjust the area to fit to the bounding limits. Moreover, the
+driver can perform other adjustments according to hardware limitations.
+
+The device has a default composing rectangle, given by the
+``V4L2_SEL_TGT_COMPOSE_DEFAULT`` target. This rectangle shall cover what
+the driver writer considers the complete picture. It is recommended for
+the driver developers to put the top/left corner at position ``(0,0)``.
+Drivers shall set the active composing rectangle to the default one when
+the driver is first loaded.
+
+The devices may introduce additional content to video signal other than
+an image from memory buffers. It includes borders around an image.
+However, such a padded area is driver-dependent feature not covered by
+this document. Driver developers are encouraged to keep padded rectangle
+equal to active one. The padded target is accessed by the
+``V4L2_SEL_TGT_COMPOSE_PADDED`` identifier. It must contain all pixels
+from the ``V4L2_SEL_TGT_COMPOSE`` target.
+
+
+Scaling control
+===============
+
+An application can detect if scaling is performed by comparing the width
+and the height of rectangles obtained using ``V4L2_SEL_TGT_CROP`` and
+``V4L2_SEL_TGT_COMPOSE`` targets. If these are not equal then the
+scaling is applied. The application can compute the scaling ratios using
+these values.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+********************************
+Comparison with old cropping API
+********************************
+
+The selection API was introduced to cope with deficiencies of previous
+:ref:`API <crop>`, that was designed to control simple capture
+devices. Later the cropping API was adopted by video output drivers. The
+ioctls are used to select a part of the display were the video signal is
+inserted. It should be considered as an API abuse because the described
+operation is actually the composing. The selection API makes a clear
+distinction between composing and cropping operations by setting the
+appropriate targets. The V4L2 API lacks any support for composing to and
+cropping from an image inside a memory buffer. The application could
+configure a capture device to fill only a part of an image by abusing
+V4L2 API. Cropping a smaller image from a larger one is achieved by
+setting the field ``bytesperline`` at struct
+:ref:`v4l2_pix_format <v4l2-pix-format>`.
+Introducing an image offsets could be done by modifying field ``m_userptr``
+at struct
+:ref:`v4l2_buffer <v4l2-buffer>` before calling
+:ref:`VIDIOC_QBUF`. Those operations should be avoided because they are not
+portable (endianness), and do not work for macroblock and Bayer formats
+and mmap buffers. The selection API deals with configuration of buffer
+cropping/composing in a clear, intuitive and portable way. Next, with
+the selection API the concepts of the padded target and constraints
+flags are introduced. Finally, struct :ref:`v4l2_crop <v4l2-crop>`
+and struct :ref:`v4l2_cropcap <v4l2-cropcap>` have no reserved
+fields. Therefore there is no way to extend their functionality. The new
+struct :ref:`v4l2_selection <v4l2-selection>` provides a lot of place
+for future extensions. Driver developers are encouraged to implement
+only selection API. The former cropping API would be simulated using the
+new one.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+********
+Examples
+********
+
+(A video capture device is assumed; change
+``V4L2_BUF_TYPE_VIDEO_CAPTURE`` for other devices; change target to
+``V4L2_SEL_TGT_COMPOSE_*`` family to configure composing area)
+
+
+.. code-block:: c
+ :caption: Example 1.15. Resetting the cropping parameters
+
+ struct v4l2_selection sel = {
+ .type = V4L2_BUF_TYPE_VIDEO_CAPTURE,
+ .target = V4L2_SEL_TGT_CROP_DEFAULT,
+ };
+ ret = ioctl(fd, VIDIOC_G_SELECTION, &sel);
+ if (ret)
+ exit(-1);
+ sel.target = V4L2_SEL_TGT_CROP;
+ ret = ioctl(fd, VIDIOC_S_SELECTION, &sel);
+ if (ret)
+ exit(-1);
+
+Setting a composing area on output of size of *at most* half of limit
+placed at a center of a display.
+
+
+.. code-block:: c
+ :caption: Example 1.16. Simple downscaling
+
+ struct v4l2_selection sel = {
+ .type = V4L2_BUF_TYPE_VIDEO_OUTPUT,
+ .target = V4L2_SEL_TGT_COMPOSE_BOUNDS,
+ };
+ struct v4l2_rect r;
+
+ ret = ioctl(fd, VIDIOC_G_SELECTION, &sel);
+ if (ret)
+ exit(-1);
+ /* setting smaller compose rectangle */
+ r.width = sel.r.width / 2;
+ r.height = sel.r.height / 2;
+ r.left = sel.r.width / 4;
+ r.top = sel.r.height / 4;
+ sel.r = r;
+ sel.target = V4L2_SEL_TGT_COMPOSE;
+ sel.flags = V4L2_SEL_FLAG_LE;
+ ret = ioctl(fd, VIDIOC_S_SELECTION, &sel);
+ if (ret)
+ exit(-1);
+
+A video output device is assumed; change ``V4L2_BUF_TYPE_VIDEO_OUTPUT``
+for other devices
+
+
+.. code-block:: c
+ :caption: Example 1.17. Querying for scaling factors
+
+ struct v4l2_selection compose = {
+ .type = V4L2_BUF_TYPE_VIDEO_OUTPUT,
+ .target = V4L2_SEL_TGT_COMPOSE,
+ };
+ struct v4l2_selection crop = {
+ .type = V4L2_BUF_TYPE_VIDEO_OUTPUT,
+ .target = V4L2_SEL_TGT_CROP,
+ };
+ double hscale, vscale;
+
+ ret = ioctl(fd, VIDIOC_G_SELECTION, &compose);
+ if (ret)
+ exit(-1);
+ ret = ioctl(fd, VIDIOC_G_SELECTION, &crop);
+ if (ret)
+ exit(-1);
+
+ /* computing scaling factors */
+ hscale = (double)compose.r.width / crop.r.width;
+ vscale = (double)compose.r.height / crop.r.height;
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _selection-api:
+
+API for cropping, composing and scaling
+=======================================
+
+
+.. toctree::
+ :maxdepth: 1
+
+ selection-api-002
+ selection-api-003
+ selection-api-004
+ selection-api-005
+ selection-api-006
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _v4l2-selections-common:
+
+Common selection definitions
+============================
+
+While the :ref:`V4L2 selection API <selection-api>` and
+:ref:`V4L2 subdev selection APIs <v4l2-subdev-selections>` are very
+similar, there's one fundamental difference between the two. On
+sub-device API, the selection rectangle refers to the media bus format,
+and is bound to a sub-device's pad. On the V4L2 interface the selection
+rectangles refer to the in-memory pixel format.
+
+This section defines the common definitions of the selection interfaces
+on the two APIs.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ v4l2-selection-targets
+ v4l2-selection-flags
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _standard:
+
+***************
+Video Standards
+***************
+
+Video devices typically support one or more different video standards or
+variations of standards. Each video input and output may support another
+set of standards. This set is reported by the ``std`` field of struct
+:ref:`v4l2_input <v4l2-input>` and struct
+:ref:`v4l2_output <v4l2-output>` returned by the
+:ref:`VIDIOC_ENUMINPUT` and
+:ref:`VIDIOC_ENUMOUTPUT` ioctls, respectively.
+
+V4L2 defines one bit for each analog video standard currently in use
+worldwide, and sets aside bits for driver defined standards, e. g.
+hybrid standards to watch NTSC video tapes on PAL TVs and vice versa.
+Applications can use the predefined bits to select a particular
+standard, although presenting the user a menu of supported standards is
+preferred. To enumerate and query the attributes of the supported
+standards applications use the :ref:`VIDIOC_ENUMSTD`
+ioctl.
+
+Many of the defined standards are actually just variations of a few
+major standards. The hardware may in fact not distinguish between them,
+or do so internal and switch automatically. Therefore enumerated
+standards also contain sets of one or more standard bits.
+
+Assume a hypothetic tuner capable of demodulating B/PAL, G/PAL and I/PAL
+signals. The first enumerated standard is a set of B and G/PAL, switched
+automatically depending on the selected radio frequency in UHF or VHF
+band. Enumeration gives a "PAL-B/G" or "PAL-I" choice. Similar a
+Composite input may collapse standards, enumerating "PAL-B/G/H/I",
+"NTSC-M" and "SECAM-D/K". [1]_
+
+To query and select the standard used by the current video input or
+output applications call the :ref:`VIDIOC_G_STD <VIDIOC_G_STD>` and
+:ref:`VIDIOC_S_STD <VIDIOC_G_STD>` ioctl, respectively. The
+*received* standard can be sensed with the
+:ref:`VIDIOC_QUERYSTD` ioctl. Note that the
+parameter of all these ioctls is a pointer to a
+:ref:`v4l2_std_id <v4l2-std-id>` type (a standard set), *not* an
+index into the standard enumeration. Drivers must implement all video
+standard ioctls when the device has one or more video inputs or outputs.
+
+Special rules apply to devices such as USB cameras where the notion of
+video standards makes little sense. More generally for any capture or
+output device which is:
+
+- incapable of capturing fields or frames at the nominal rate of the
+ video standard, or
+
+- that does not support the video standard formats at all.
+
+Here the driver shall set the ``std`` field of struct
+:ref:`v4l2_input <v4l2-input>` and struct
+:ref:`v4l2_output <v4l2-output>` to zero and the :ref:`VIDIOC_G_STD <VIDIOC_G_STD>`,
+:ref:`VIDIOC_S_STD <VIDIOC_G_STD>`, :ref:`VIDIOC_QUERYSTD` and :ref:`VIDIOC_ENUMSTD` ioctls
+shall return the ``ENOTTY`` error code or the ``EINVAL`` error code.
+
+Applications can make use of the :ref:`input-capabilities` and
+:ref:`output-capabilities` flags to determine whether the video
+standard ioctls can be used with the given input or output.
+
+
+.. code-block:: c
+ :caption: Example 1.5. Information about the current video standard
+
+ v4l2_std_id std_id;
+ struct v4l2_standard standard;
+
+ if (-1 == ioctl(fd, VIDIOC_G_STD, &std_id)) {
+ /* Note when VIDIOC_ENUMSTD always returns ENOTTY this
+ is no video device or it falls under the USB exception,
+ and VIDIOC_G_STD returning ENOTTY is no error. */
+
+ perror("VIDIOC_G_STD");
+ exit(EXIT_FAILURE);
+ }
+
+ memset(&standard, 0, sizeof(standard));
+ standard.index = 0;
+
+ while (0 == ioctl(fd, VIDIOC_ENUMSTD, &standard)) {
+ if (standard.id & std_id) {
+ printf("Current video standard: %s\\n", standard.name);
+ exit(EXIT_SUCCESS);
+ }
+
+ standard.index++;
+ }
+
+ /* EINVAL indicates the end of the enumeration, which cannot be
+ empty unless this device falls under the USB exception. */
+
+ if (errno == EINVAL || standard.index == 0) {
+ perror("VIDIOC_ENUMSTD");
+ exit(EXIT_FAILURE);
+ }
+
+
+.. code-block:: c
+ :caption: Example 1.6. Listing the video standards supported by the current input
+
+ struct v4l2_input input;
+ struct v4l2_standard standard;
+
+ memset(&input, 0, sizeof(input));
+
+ if (-1 == ioctl(fd, VIDIOC_G_INPUT, &input.index)) {
+ perror("VIDIOC_G_INPUT");
+ exit(EXIT_FAILURE);
+ }
+
+ if (-1 == ioctl(fd, VIDIOC_ENUMINPUT, &input)) {
+ perror("VIDIOC_ENUM_INPUT");
+ exit(EXIT_FAILURE);
+ }
+
+ printf("Current input %s supports:\\n", input.name);
+
+ memset(&standard, 0, sizeof(standard));
+ standard.index = 0;
+
+ while (0 == ioctl(fd, VIDIOC_ENUMSTD, &standard)) {
+ if (standard.id & input.std)
+ printf("%s\\n", standard.name);
+
+ standard.index++;
+ }
+
+ /* EINVAL indicates the end of the enumeration, which cannot be
+ empty unless this device falls under the USB exception. */
+
+ if (errno != EINVAL || standard.index == 0) {
+ perror("VIDIOC_ENUMSTD");
+ exit(EXIT_FAILURE);
+ }
+
+
+.. code-block:: c
+ :caption: Example 1.7. Selecting a new video standard
+
+ struct v4l2_input input;
+ v4l2_std_id std_id;
+
+ memset(&input, 0, sizeof(input));
+
+ if (-1 == ioctl(fd, VIDIOC_G_INPUT, &input.index)) {
+ perror("VIDIOC_G_INPUT");
+ exit(EXIT_FAILURE);
+ }
+
+ if (-1 == ioctl(fd, VIDIOC_ENUMINPUT, &input)) {
+ perror("VIDIOC_ENUM_INPUT");
+ exit(EXIT_FAILURE);
+ }
+
+ if (0 == (input.std & V4L2_STD_PAL_BG)) {
+ fprintf(stderr, "Oops. B/G PAL is not supported.\\n");
+ exit(EXIT_FAILURE);
+ }
+
+ /* Note this is also supposed to work when only B
+ or G/PAL is supported. */
+
+ std_id = V4L2_STD_PAL_BG;
+
+ if (-1 == ioctl(fd, VIDIOC_S_STD, &std_id)) {
+ perror("VIDIOC_S_STD");
+ exit(EXIT_FAILURE);
+ }
+
+.. [1]
+ Some users are already confused by technical terms PAL, NTSC and
+ SECAM. There is no point asking them to distinguish between B, G, D,
+ or K when the software or hardware can do that automatically.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _streaming-par:
+
+********************
+Streaming Parameters
+********************
+
+Streaming parameters are intended to optimize the video capture process
+as well as I/O. Presently applications can request a high quality
+capture mode with the :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` ioctl.
+
+The current video standard determines a nominal number of frames per
+second. If less than this number of frames is to be captured or output,
+applications can request frame skipping or duplicating on the driver
+side. This is especially useful when using the
+:ref:`read() <func-read>` or :ref:`write() <func-write>`, which are
+not augmented by timestamps or sequence counters, and to avoid
+unnecessary data copying.
+
+Finally these ioctls can be used to determine the number of buffers used
+internally by a driver in read/write mode. For implications see the
+section discussing the :ref:`read() <func-read>` function.
+
+To get and set the streaming parameters applications call the
+:ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and
+:ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` ioctl, respectively. They take
+a pointer to a struct :ref:`v4l2_streamparm <v4l2-streamparm>`, which
+contains a union holding separate parameters for input and output
+devices.
+
+These ioctls are optional, drivers need not implement them. If so, they
+return the ``EINVAL`` error code.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _v4l2-mbus-format:
+
+Media Bus Formats
+=================
+
+
+.. _v4l2-mbus-framefmt:
+
+.. flat-table:: struct v4l2_mbus_framefmt
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``width``
+
+ - Image width, in pixels.
+
+ - .. row 2
+
+ - __u32
+
+ - ``height``
+
+ - Image height, in pixels.
+
+ - .. row 3
+
+ - __u32
+
+ - ``code``
+
+ - Format code, from enum
+ :ref:`v4l2_mbus_pixelcode <v4l2-mbus-pixelcode>`.
+
+ - .. row 4
+
+ - __u32
+
+ - ``field``
+
+ - Field order, from enum :ref:`v4l2_field <v4l2-field>`. See
+ :ref:`field-order` for details.
+
+ - .. row 5
+
+ - __u32
+
+ - ``colorspace``
+
+ - Image colorspace, from enum
+ :ref:`v4l2_colorspace <v4l2-colorspace>`. See
+ :ref:`colorspaces` for details.
+
+ - .. row 6
+
+ - enum :ref:`v4l2_ycbcr_encoding <v4l2-ycbcr-encoding>`
+
+ - ``ycbcr_enc``
+
+ - This information supplements the ``colorspace`` and must be set by
+ the driver for capture streams and by the application for output
+ streams, see :ref:`colorspaces`.
+
+ - .. row 7
+
+ - enum :ref:`v4l2_quantization <v4l2-quantization>`
+
+ - ``quantization``
+
+ - This information supplements the ``colorspace`` and must be set by
+ the driver for capture streams and by the application for output
+ streams, see :ref:`colorspaces`.
+
+ - .. row 8
+
+ - enum :ref:`v4l2_xfer_func <v4l2-xfer-func>`
+
+ - ``xfer_func``
+
+ - This information supplements the ``colorspace`` and must be set by
+ the driver for capture streams and by the application for output
+ streams, see :ref:`colorspaces`.
+
+ - .. row 9
+
+ - __u16
+
+ - ``reserved``\ [11]
+
+ - Reserved for future extensions. Applications and drivers must set
+ the array to zero.
+
+
+
+.. _v4l2-mbus-pixelcode:
+
+Media Bus Pixel Codes
+---------------------
+
+The media bus pixel codes describe image formats as flowing over
+physical busses (both between separate physical components and inside
+SoC devices). This should not be confused with the V4L2 pixel formats
+that describe, using four character codes, image formats as stored in
+memory.
+
+While there is a relationship between image formats on busses and image
+formats in memory (a raw Bayer image won't be magically converted to
+JPEG just by storing it to memory), there is no one-to-one
+correspondance between them.
+
+
+Packed RGB Formats
+^^^^^^^^^^^^^^^^^^
+
+Those formats transfer pixel data as red, green and blue components. The
+format code is made of the following information.
+
+- The red, green and blue components order code, as encoded in a pixel
+ sample. Possible values are RGB and BGR.
+
+- The number of bits per component, for each component. The values can
+ be different for all components. Common values are 555 and 565.
+
+- The number of bus samples per pixel. Pixels that are wider than the
+ bus width must be transferred in multiple samples. Common values are
+ 1 and 2.
+
+- The bus width.
+
+- For formats where the total number of bits per pixel is smaller than
+ the number of bus samples per pixel times the bus width, a padding
+ value stating if the bytes are padded in their most high order bits
+ (PADHI) or low order bits (PADLO). A "C" prefix is used for
+ component-wise padding in the most high order bits (CPADHI) or low
+ order bits (CPADLO) of each separate component.
+
+- For formats where the number of bus samples per pixel is larger than
+ 1, an endianness value stating if the pixel is transferred MSB first
+ (BE) or LSB first (LE).
+
+For instance, a format where pixels are encoded as 5-bits red, 5-bits
+green and 5-bit blue values padded on the high bit, transferred as 2
+8-bit samples per pixel with the most significant bits (padding, red and
+half of the green value) transferred first will be named
+``MEDIA_BUS_FMT_RGB555_2X8_PADHI_BE``.
+
+The following tables list existing packed RGB formats.
+
+
+.. _v4l2-mbus-pixelcode-rgb:
+
+.. flat-table:: RGB formats
+ :header-rows: 2
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Code
+
+ -
+ - :cspan:`31` Data organization
+
+ - .. row 2
+
+ -
+ -
+ - Bit
+
+ - 31
+
+ - 30
+
+ - 29
+
+ - 28
+
+ - 27
+
+ - 26
+
+ - 25
+
+ - 24
+
+ - 23
+
+ - 22
+
+ - 21
+
+ - 20
+
+ - 19
+
+ - 18
+
+ - 17
+
+ - 16
+
+ - 15
+
+ - 14
+
+ - 13
+
+ - 12
+
+ - 11
+
+ - 10
+
+ - 9
+
+ - 8
+
+ - 7
+
+ - 6
+
+ - 5
+
+ - 4
+
+ - 3
+
+ - 2
+
+ - 1
+
+ - 0
+
+ - .. _MEDIA-BUS-FMT-RGB444-1X12:
+
+ - MEDIA_BUS_FMT_RGB444_1X12
+
+ - 0x1016
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-RGB444-2X8-PADHI-BE:
+
+ - MEDIA_BUS_FMT_RGB444_2X8_PADHI_BE
+
+ - 0x1001
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - .. row 5
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-RGB444-2X8-PADHI-LE:
+
+ - MEDIA_BUS_FMT_RGB444_2X8_PADHI_LE
+
+ - 0x1002
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. row 7
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-RGB555-2X8-PADHI-BE:
+
+ - MEDIA_BUS_FMT_RGB555_2X8_PADHI_BE
+
+ - 0x1003
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 0
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - .. row 9
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-RGB555-2X8-PADHI-LE:
+
+ - MEDIA_BUS_FMT_RGB555_2X8_PADHI_LE
+
+ - 0x1004
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. row 11
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 0
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - .. _MEDIA-BUS-FMT-RGB565-1X16:
+
+ - MEDIA_BUS_FMT_RGB565_1X16
+
+ - 0x1017
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-BGR565-2X8-BE:
+
+ - MEDIA_BUS_FMT_BGR565_2X8_BE
+
+ - 0x1005
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - .. row 14
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-BGR565-2X8-LE:
+
+ - MEDIA_BUS_FMT_BGR565_2X8_LE
+
+ - 0x1006
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - .. row 16
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - .. _MEDIA-BUS-FMT-RGB565-2X8-BE:
+
+ - MEDIA_BUS_FMT_RGB565_2X8_BE
+
+ - 0x1007
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - .. row 18
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-RGB565-2X8-LE:
+
+ - MEDIA_BUS_FMT_RGB565_2X8_LE
+
+ - 0x1008
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. row 20
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - .. _MEDIA-BUS-FMT-RGB666-1X18:
+
+ - MEDIA_BUS_FMT_RGB666_1X18
+
+ - 0x1009
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-RBG888-1X24:
+
+ - MEDIA_BUS_FMT_RBG888_1X24
+
+ - 0x100e
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-RGB666-1X24_CPADHI:
+
+ - MEDIA_BUS_FMT_RGB666_1X24_CPADHI
+
+ - 0x1015
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 0
+
+ - 0
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - 0
+
+ - 0
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - 0
+
+ - 0
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-BGR888-1X24:
+
+ - MEDIA_BUS_FMT_BGR888_1X24
+
+ - 0x1013
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-GBR888-1X24:
+
+ - MEDIA_BUS_FMT_GBR888_1X24
+
+ - 0x1014
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-RGB888-1X24:
+
+ - MEDIA_BUS_FMT_RGB888_1X24
+
+ - 0x100a
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-RGB888-2X12-BE:
+
+ - MEDIA_BUS_FMT_RGB888_2X12_BE
+
+ - 0x100b
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - .. row 28
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-RGB888-2X12-LE:
+
+ - MEDIA_BUS_FMT_RGB888_2X12_LE
+
+ - 0x100c
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. row 30
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - .. _MEDIA-BUS-FMT-ARGB888-1X32:
+
+ - MEDIA_BUS_FMT_ARGB888_1X32
+
+ - 0x100d
+
+ -
+ - a\ :sub:`7`
+
+ - a\ :sub:`6`
+
+ - a\ :sub:`5`
+
+ - a\ :sub:`4`
+
+ - a\ :sub:`3`
+
+ - a\ :sub:`2`
+
+ - a\ :sub:`1`
+
+ - a\ :sub:`0`
+
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-RGB888-1X32-PADHI:
+
+ - MEDIA_BUS_FMT_RGB888_1X32_PADHI
+
+ - 0x100f
+
+ -
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+
+On LVDS buses, usually each sample is transferred serialized in seven
+time slots per pixel clock, on three (18-bit) or four (24-bit)
+differential data pairs at the same time. The remaining bits are used
+for control signals as defined by SPWG/PSWG/VESA or JEIDA standards. The
+24-bit RGB format serialized in seven time slots on four lanes using
+JEIDA defined bit mapping will be named
+``MEDIA_BUS_FMT_RGB888_1X7X4_JEIDA``, for example.
+
+
+.. _v4l2-mbus-pixelcode-rgb-lvds:
+
+.. flat-table:: LVDS RGB formats
+ :header-rows: 2
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Code
+
+ -
+ -
+ - :cspan:`3` Data organization
+
+ - .. row 2
+
+ -
+ -
+ - Timeslot
+
+ - Lane
+
+ - 3
+
+ - 2
+
+ - 1
+
+ - 0
+
+ - .. _MEDIA-BUS-FMT-RGB666-1X7X3-SPWG:
+
+ - MEDIA_BUS_FMT_RGB666_1X7X3_SPWG
+
+ - 0x1010
+
+ - 0
+
+ -
+ - -
+
+ - d
+
+ - b\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - .. row 4
+
+ -
+ -
+ - 1
+
+ -
+ - -
+
+ - d
+
+ - b\ :sub:`0`
+
+ - r\ :sub:`5`
+
+ - .. row 5
+
+ -
+ -
+ - 2
+
+ -
+ - -
+
+ - d
+
+ - g\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - .. row 6
+
+ -
+ -
+ - 3
+
+ -
+ - -
+
+ - b\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - .. row 7
+
+ -
+ -
+ - 4
+
+ -
+ - -
+
+ - b\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - .. row 8
+
+ -
+ -
+ - 5
+
+ -
+ - -
+
+ - b\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - .. row 9
+
+ -
+ -
+ - 6
+
+ -
+ - -
+
+ - b\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-RGB888-1X7X4-SPWG:
+
+ - MEDIA_BUS_FMT_RGB888_1X7X4_SPWG
+
+ - 0x1011
+
+ - 0
+
+ -
+ - d
+
+ - d
+
+ - b\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - .. row 11
+
+ -
+ -
+ - 1
+
+ -
+ - b\ :sub:`7`
+
+ - d
+
+ - b\ :sub:`0`
+
+ - r\ :sub:`5`
+
+ - .. row 12
+
+ -
+ -
+ - 2
+
+ -
+ - b\ :sub:`6`
+
+ - d
+
+ - g\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - .. row 13
+
+ -
+ -
+ - 3
+
+ -
+ - g\ :sub:`7`
+
+ - b\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - .. row 14
+
+ -
+ -
+ - 4
+
+ -
+ - g\ :sub:`6`
+
+ - b\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - .. row 15
+
+ -
+ -
+ - 5
+
+ -
+ - r\ :sub:`7`
+
+ - b\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - .. row 16
+
+ -
+ -
+ - 6
+
+ -
+ - r\ :sub:`6`
+
+ - b\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-RGB888-1X7X4-JEIDA:
+
+ - MEDIA_BUS_FMT_RGB888_1X7X4_JEIDA
+
+ - 0x1012
+
+ - 0
+
+ -
+ - d
+
+ - d
+
+ - b\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - .. row 18
+
+ -
+ -
+ - 1
+
+ -
+ - b\ :sub:`1`
+
+ - d
+
+ - b\ :sub:`2`
+
+ - r\ :sub:`7`
+
+ - .. row 19
+
+ -
+ -
+ - 2
+
+ -
+ - b\ :sub:`0`
+
+ - d
+
+ - g\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - .. row 20
+
+ -
+ -
+ - 3
+
+ -
+ - g\ :sub:`1`
+
+ - b\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - .. row 21
+
+ -
+ -
+ - 4
+
+ -
+ - g\ :sub:`0`
+
+ - b\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - .. row 22
+
+ -
+ -
+ - 5
+
+ -
+ - r\ :sub:`1`
+
+ - b\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - .. row 23
+
+ -
+ -
+ - 6
+
+ -
+ - r\ :sub:`0`
+
+ - b\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - r\ :sub:`2`
+
+
+
+Bayer Formats
+^^^^^^^^^^^^^
+
+Those formats transfer pixel data as red, green and blue components. The
+format code is made of the following information.
+
+- The red, green and blue components order code, as encoded in a pixel
+ sample. The possible values are shown in :ref:`bayer-patterns`.
+
+- The number of bits per pixel component. All components are
+ transferred on the same number of bits. Common values are 8, 10 and
+ 12.
+
+- The compression (optional). If the pixel components are ALAW- or
+ DPCM-compressed, a mention of the compression scheme and the number
+ of bits per compressed pixel component.
+
+- The number of bus samples per pixel. Pixels that are wider than the
+ bus width must be transferred in multiple samples. Common values are
+ 1 and 2.
+
+- The bus width.
+
+- For formats where the total number of bits per pixel is smaller than
+ the number of bus samples per pixel times the bus width, a padding
+ value stating if the bytes are padded in their most high order bits
+ (PADHI) or low order bits (PADLO).
+
+- For formats where the number of bus samples per pixel is larger than
+ 1, an endianness value stating if the pixel is transferred MSB first
+ (BE) or LSB first (LE).
+
+For instance, a format with uncompressed 10-bit Bayer components
+arranged in a red, green, green, blue pattern transferred as 2 8-bit
+samples per pixel with the least significant bits transferred first will
+be named ``MEDIA_BUS_FMT_SRGGB10_2X8_PADHI_LE``.
+
+
+.. _bayer-patterns:
+
+.. figure:: subdev-formats_files/bayer.*
+ :alt: bayer.png
+ :align: center
+
+ **Figure 4.8 Bayer Patterns**
+
+
+
+The following table lists existing packed Bayer formats. The data
+organization is given as an example for the first pixel only.
+
+
+.. _v4l2-mbus-pixelcode-bayer:
+
+.. flat-table:: Bayer Formats
+ :header-rows: 2
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Code
+
+ -
+ - :cspan:`11` Data organization
+
+ - .. row 2
+
+ -
+ -
+ - Bit
+
+ - 11
+
+ - 10
+
+ - 9
+
+ - 8
+
+ - 7
+
+ - 6
+
+ - 5
+
+ - 4
+
+ - 3
+
+ - 2
+
+ - 1
+
+ - 0
+
+ - .. _MEDIA-BUS-FMT-SBGGR8-1X8:
+
+ - MEDIA_BUS_FMT_SBGGR8_1X8
+
+ - 0x3001
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-SGBRG8-1X8:
+
+ - MEDIA_BUS_FMT_SGBRG8_1X8
+
+ - 0x3013
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-SGRBG8-1X8:
+
+ - MEDIA_BUS_FMT_SGRBG8_1X8
+
+ - 0x3002
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-SRGGB8-1X8:
+
+ - MEDIA_BUS_FMT_SRGGB8_1X8
+
+ - 0x3014
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-SBGGR10-ALAW8-1X8:
+
+ - MEDIA_BUS_FMT_SBGGR10_ALAW8_1X8
+
+ - 0x3015
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-SGBRG10-ALAW8-1X8:
+
+ - MEDIA_BUS_FMT_SGBRG10_ALAW8_1X8
+
+ - 0x3016
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-SGRBG10-ALAW8-1X8:
+
+ - MEDIA_BUS_FMT_SGRBG10_ALAW8_1X8
+
+ - 0x3017
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-SRGGB10-ALAW8-1X8:
+
+ - MEDIA_BUS_FMT_SRGGB10_ALAW8_1X8
+
+ - 0x3018
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-SBGGR10-DPCM8-1X8:
+
+ - MEDIA_BUS_FMT_SBGGR10_DPCM8_1X8
+
+ - 0x300b
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-SGBRG10-DPCM8-1X8:
+
+ - MEDIA_BUS_FMT_SGBRG10_DPCM8_1X8
+
+ - 0x300c
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-SGRBG10-DPCM8-1X8:
+
+ - MEDIA_BUS_FMT_SGRBG10_DPCM8_1X8
+
+ - 0x3009
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-SRGGB10-DPCM8-1X8:
+
+ - MEDIA_BUS_FMT_SRGGB10_DPCM8_1X8
+
+ - 0x300d
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-SBGGR10-2X8-PADHI-BE:
+
+ - MEDIA_BUS_FMT_SBGGR10_2X8_PADHI_BE
+
+ - 0x3003
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - b\ :sub:`9`
+
+ - b\ :sub:`8`
+
+ - .. row 16
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-SBGGR10-2X8-PADHI-LE:
+
+ - MEDIA_BUS_FMT_SBGGR10_2X8_PADHI_LE
+
+ - 0x3004
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. row 18
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - b\ :sub:`9`
+
+ - b\ :sub:`8`
+
+ - .. _MEDIA-BUS-FMT-SBGGR10-2X8-PADLO-BE:
+
+ - MEDIA_BUS_FMT_SBGGR10_2X8_PADLO_BE
+
+ - 0x3005
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - b\ :sub:`9`
+
+ - b\ :sub:`8`
+
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - .. row 20
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - .. _MEDIA-BUS-FMT-SBGGR10-2X8-PADLO-LE:
+
+ - MEDIA_BUS_FMT_SBGGR10_2X8_PADLO_LE
+
+ - 0x3006
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - .. row 22
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - b\ :sub:`9`
+
+ - b\ :sub:`8`
+
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - .. _MEDIA-BUS-FMT-SBGGR10-1X10:
+
+ - MEDIA_BUS_FMT_SBGGR10_1X10
+
+ - 0x3007
+
+ -
+ - -
+
+ - -
+
+ - b\ :sub:`9`
+
+ - b\ :sub:`8`
+
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-SGBRG10-1X10:
+
+ - MEDIA_BUS_FMT_SGBRG10_1X10
+
+ - 0x300e
+
+ -
+ - -
+
+ - -
+
+ - g\ :sub:`9`
+
+ - g\ :sub:`8`
+
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-SGRBG10-1X10:
+
+ - MEDIA_BUS_FMT_SGRBG10_1X10
+
+ - 0x300a
+
+ -
+ - -
+
+ - -
+
+ - g\ :sub:`9`
+
+ - g\ :sub:`8`
+
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-SRGGB10-1X10:
+
+ - MEDIA_BUS_FMT_SRGGB10_1X10
+
+ - 0x300f
+
+ -
+ - -
+
+ - -
+
+ - r\ :sub:`9`
+
+ - r\ :sub:`8`
+
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-SBGGR12-1X12:
+
+ - MEDIA_BUS_FMT_SBGGR12_1X12
+
+ - 0x3008
+
+ -
+ - b\ :sub:`11`
+
+ - b\ :sub:`10`
+
+ - b\ :sub:`9`
+
+ - b\ :sub:`8`
+
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-SGBRG12-1X12:
+
+ - MEDIA_BUS_FMT_SGBRG12_1X12
+
+ - 0x3010
+
+ -
+ - g\ :sub:`11`
+
+ - g\ :sub:`10`
+
+ - g\ :sub:`9`
+
+ - g\ :sub:`8`
+
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-SGRBG12-1X12:
+
+ - MEDIA_BUS_FMT_SGRBG12_1X12
+
+ - 0x3011
+
+ -
+ - g\ :sub:`11`
+
+ - g\ :sub:`10`
+
+ - g\ :sub:`9`
+
+ - g\ :sub:`8`
+
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-SRGGB12-1X12:
+
+ - MEDIA_BUS_FMT_SRGGB12_1X12
+
+ - 0x3012
+
+ -
+ - r\ :sub:`11`
+
+ - r\ :sub:`10`
+
+ - r\ :sub:`9`
+
+ - r\ :sub:`8`
+
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+
+
+Packed YUV Formats
+^^^^^^^^^^^^^^^^^^
+
+Those data formats transfer pixel data as (possibly downsampled) Y, U
+and V components. Some formats include dummy bits in some of their
+samples and are collectively referred to as "YDYC" (Y-Dummy-Y-Chroma)
+formats. One cannot rely on the values of these dummy bits as those are
+undefined.
+
+The format code is made of the following information.
+
+- The Y, U and V components order code, as transferred on the bus.
+ Possible values are YUYV, UYVY, YVYU and VYUY for formats with no
+ dummy bit, and YDYUYDYV, YDYVYDYU, YUYDYVYD and YVYDYUYD for YDYC
+ formats.
+
+- The number of bits per pixel component. All components are
+ transferred on the same number of bits. Common values are 8, 10 and
+ 12.
+
+- The number of bus samples per pixel. Pixels that are wider than the
+ bus width must be transferred in multiple samples. Common values are
+ 1, 1.5 (encoded as 1_5) and 2.
+
+- The bus width. When the bus width is larger than the number of bits
+ per pixel component, several components are packed in a single bus
+ sample. The components are ordered as specified by the order code,
+ with components on the left of the code transferred in the high order
+ bits. Common values are 8 and 16.
+
+For instance, a format where pixels are encoded as 8-bit YUV values
+downsampled to 4:2:2 and transferred as 2 8-bit bus samples per pixel in
+the U, Y, V, Y order will be named ``MEDIA_BUS_FMT_UYVY8_2X8``.
+
+:ref:`v4l2-mbus-pixelcode-yuv8` lists existing packed YUV formats and
+describes the organization of each pixel data in each sample. When a
+format pattern is split across multiple samples each of the samples in
+the pattern is described.
+
+The role of each bit transferred over the bus is identified by one of
+the following codes.
+
+- y\ :sub:`x` for luma component bit number x
+
+- u\ :sub:`x` for blue chroma component bit number x
+
+- v\ :sub:`x` for red chroma component bit number x
+
+- a\ :sub:`x` for alpha component bit number x
+
+- - for non-available bits (for positions higher than the bus width)
+
+- d for dummy bits
+
+
+.. _v4l2-mbus-pixelcode-yuv8:
+
+.. flat-table:: YUV Formats
+ :header-rows: 2
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Code
+
+ -
+ - :cspan:`31` Data organization
+
+ - .. row 2
+
+ -
+ -
+ - Bit
+
+ - 31
+
+ - 30
+
+ - 29
+
+ - 28
+
+ - 27
+
+ - 26
+
+ - 25
+
+ - 24
+
+ - 23
+
+ - 22
+
+ - 21
+
+ - 10
+
+ - 19
+
+ - 18
+
+ - 17
+
+ - 16
+
+ - 15
+
+ - 14
+
+ - 13
+
+ - 12
+
+ - 11
+
+ - 10
+
+ - 9
+
+ - 8
+
+ - 7
+
+ - 6
+
+ - 5
+
+ - 4
+
+ - 3
+
+ - 2
+
+ - 1
+
+ - 0
+
+ - .. _MEDIA-BUS-FMT-Y8-1X8:
+
+ - MEDIA_BUS_FMT_Y8_1X8
+
+ - 0x2001
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-UV8-1X8:
+
+ - MEDIA_BUS_FMT_UV8_1X8
+
+ - 0x2015
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 5
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-UYVY8-1_5X8:
+
+ - MEDIA_BUS_FMT_UYVY8_1_5X8
+
+ - 0x2002
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 7
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 8
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 9
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. row 10
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 11
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-VYUY8-1_5X8:
+
+ - MEDIA_BUS_FMT_VYUY8_1_5X8
+
+ - 0x2003
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. row 13
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 14
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 15
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 16
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 17
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-YUYV8-1_5X8:
+
+ - MEDIA_BUS_FMT_YUYV8_1_5X8
+
+ - 0x2004
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 19
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 20
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 21
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 22
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 23
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-YVYU8-1_5X8:
+
+ - MEDIA_BUS_FMT_YVYU8_1_5X8
+
+ - 0x2005
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 25
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 26
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. row 27
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 28
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 29
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-UYVY8-2X8:
+
+ - MEDIA_BUS_FMT_UYVY8_2X8
+
+ - 0x2006
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 31
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 32
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. row 33
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-VYUY8-2X8:
+
+ - MEDIA_BUS_FMT_VYUY8_2X8
+
+ - 0x2007
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. row 35
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 36
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 37
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-YUYV8-2X8:
+
+ - MEDIA_BUS_FMT_YUYV8_2X8
+
+ - 0x2008
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 39
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 40
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 41
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-YVYU8-2X8:
+
+ - MEDIA_BUS_FMT_YVYU8_2X8
+
+ - 0x2009
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 43
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. row 44
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 45
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-Y10-1X10:
+
+ - MEDIA_BUS_FMT_Y10_1X10
+
+ - 0x200a
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-UYVY10-2X10:
+
+ - MEDIA_BUS_FMT_UYVY10_2X10
+
+ - 0x2018
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 48
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 49
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. row 50
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-VYUY10-2X10:
+
+ - MEDIA_BUS_FMT_VYUY10_2X10
+
+ - 0x2019
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. row 52
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 53
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 54
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-YUYV10-2X10:
+
+ - MEDIA_BUS_FMT_YUYV10_2X10
+
+ - 0x200b
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 56
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 57
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 58
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-YVYU10-2X10:
+
+ - MEDIA_BUS_FMT_YVYU10_2X10
+
+ - 0x200c
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 60
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. row 61
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 62
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-Y12-1X12:
+
+ - MEDIA_BUS_FMT_Y12_1X12
+
+ - 0x2013
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`11`
+
+ - y\ :sub:`10`
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-UYVY12-2X12:
+
+ - MEDIA_BUS_FMT_UYVY12_2X12
+
+ - 0x201c
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`11`
+
+ - u\ :sub:`10`
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 65
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`11`
+
+ - y\ :sub:`10`
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 66
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`11`
+
+ - v\ :sub:`10`
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. row 67
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`11`
+
+ - y\ :sub:`10`
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-VYUY12-2X12:
+
+ - MEDIA_BUS_FMT_VYUY12_2X12
+
+ - 0x201d
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`11`
+
+ - v\ :sub:`10`
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. row 69
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`11`
+
+ - y\ :sub:`10`
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 70
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`11`
+
+ - u\ :sub:`10`
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 71
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`11`
+
+ - y\ :sub:`10`
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-YUYV12-2X12:
+
+ - MEDIA_BUS_FMT_YUYV12_2X12
+
+ - 0x201e
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`11`
+
+ - y\ :sub:`10`
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 73
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`11`
+
+ - u\ :sub:`10`
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 74
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`11`
+
+ - y\ :sub:`10`
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 75
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`11`
+
+ - v\ :sub:`10`
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-YVYU12-2X12:
+
+ - MEDIA_BUS_FMT_YVYU12_2X12
+
+ - 0x201f
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`11`
+
+ - y\ :sub:`10`
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 77
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`11`
+
+ - v\ :sub:`10`
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. row 78
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`11`
+
+ - y\ :sub:`10`
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 79
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`11`
+
+ - u\ :sub:`10`
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-UYVY8-1X16:
+
+ - MEDIA_BUS_FMT_UYVY8_1X16
+
+ - 0x200f
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 81
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-VYUY8-1X16:
+
+ - MEDIA_BUS_FMT_VYUY8_1X16
+
+ - 0x2010
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 83
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-YUYV8-1X16:
+
+ - MEDIA_BUS_FMT_YUYV8_1X16
+
+ - 0x2011
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 85
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-YVYU8-1X16:
+
+ - MEDIA_BUS_FMT_YVYU8_1X16
+
+ - 0x2012
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. row 87
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-YDYUYDYV8-1X16:
+
+ - MEDIA_BUS_FMT_YDYUYDYV8_1X16
+
+ - 0x2014
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - d
+
+ - d
+
+ - d
+
+ - d
+
+ - d
+
+ - d
+
+ - d
+
+ - d
+
+ - .. row 89
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 90
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - d
+
+ - d
+
+ - d
+
+ - d
+
+ - d
+
+ - d
+
+ - d
+
+ - d
+
+ - .. row 91
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-UYVY10-1X20:
+
+ - MEDIA_BUS_FMT_UYVY10_1X20
+
+ - 0x201a
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 93
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-VYUY10-1X20:
+
+ - MEDIA_BUS_FMT_VYUY10_1X20
+
+ - 0x201b
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 95
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-YUYV10-1X20:
+
+ - MEDIA_BUS_FMT_YUYV10_1X20
+
+ - 0x200d
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 97
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-YVYU10-1X20:
+
+ - MEDIA_BUS_FMT_YVYU10_1X20
+
+ - 0x200e
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. row 99
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-VUY8-1X24:
+
+ - MEDIA_BUS_FMT_VUY8_1X24
+
+ - 0x201a
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-YUV8-1X24:
+
+ - MEDIA_BUS_FMT_YUV8_1X24
+
+ - 0x2025
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-UYVY12-1X24:
+
+ - MEDIA_BUS_FMT_UYVY12_1X24
+
+ - 0x2020
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`11`
+
+ - u\ :sub:`10`
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - y\ :sub:`11`
+
+ - y\ :sub:`10`
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 103
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`11`
+
+ - v\ :sub:`10`
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - y\ :sub:`11`
+
+ - y\ :sub:`10`
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-VYUY12-1X24:
+
+ - MEDIA_BUS_FMT_VYUY12_1X24
+
+ - 0x2021
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`11`
+
+ - v\ :sub:`10`
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - y\ :sub:`11`
+
+ - y\ :sub:`10`
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 105
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`11`
+
+ - u\ :sub:`10`
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - y\ :sub:`11`
+
+ - y\ :sub:`10`
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-YUYV12-1X24:
+
+ - MEDIA_BUS_FMT_YUYV12_1X24
+
+ - 0x2022
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`11`
+
+ - y\ :sub:`10`
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - u\ :sub:`11`
+
+ - u\ :sub:`10`
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 107
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`11`
+
+ - y\ :sub:`10`
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - v\ :sub:`11`
+
+ - v\ :sub:`10`
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-YVYU12-1X24:
+
+ - MEDIA_BUS_FMT_YVYU12_1X24
+
+ - 0x2023
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`11`
+
+ - y\ :sub:`10`
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - v\ :sub:`11`
+
+ - v\ :sub:`10`
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. row 109
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`11`
+
+ - y\ :sub:`10`
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - u\ :sub:`11`
+
+ - u\ :sub:`10`
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-YUV10-1X30:
+
+ - MEDIA_BUS_FMT_YUV10_1X30
+
+ - 0x2016
+
+ -
+ - -
+
+ - -
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-AYUV8-1X32:
+
+ - MEDIA_BUS_FMT_AYUV8_1X32
+
+ - 0x2017
+
+ -
+ - a\ :sub:`7`
+
+ - a\ :sub:`6`
+
+ - a\ :sub:`5`
+
+ - a\ :sub:`4`
+
+ - a\ :sub:`3`
+
+ - a\ :sub:`2`
+
+ - a\ :sub:`1`
+
+ - a\ :sub:`0`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+
+
+HSV/HSL Formats
+^^^^^^^^^^^^^^^
+
+Those formats transfer pixel data as RGB values in a
+cylindrical-coordinate system using Hue-Saturation-Value or
+Hue-Saturation-Lightness components. The format code is made of the
+following information.
+
+- The hue, saturation, value or lightness and optional alpha components
+ order code, as encoded in a pixel sample. The only currently
+ supported value is AHSV.
+
+- The number of bits per component, for each component. The values can
+ be different for all components. The only currently supported value
+ is 8888.
+
+- The number of bus samples per pixel. Pixels that are wider than the
+ bus width must be transferred in multiple samples. The only currently
+ supported value is 1.
+
+- The bus width.
+
+- For formats where the total number of bits per pixel is smaller than
+ the number of bus samples per pixel times the bus width, a padding
+ value stating if the bytes are padded in their most high order bits
+ (PADHI) or low order bits (PADLO).
+
+- For formats where the number of bus samples per pixel is larger than
+ 1, an endianness value stating if the pixel is transferred MSB first
+ (BE) or LSB first (LE).
+
+The following table lists existing HSV/HSL formats.
+
+
+.. _v4l2-mbus-pixelcode-hsv:
+
+.. flat-table:: HSV/HSL formats
+ :header-rows: 2
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Code
+
+ -
+ - :cspan:`31` Data organization
+
+ - .. row 2
+
+ -
+ -
+ - Bit
+
+ - 31
+
+ - 30
+
+ - 29
+
+ - 28
+
+ - 27
+
+ - 26
+
+ - 25
+
+ - 24
+
+ - 23
+
+ - 22
+
+ - 21
+
+ - 20
+
+ - 19
+
+ - 18
+
+ - 17
+
+ - 16
+
+ - 15
+
+ - 14
+
+ - 13
+
+ - 12
+
+ - 11
+
+ - 10
+
+ - 9
+
+ - 8
+
+ - 7
+
+ - 6
+
+ - 5
+
+ - 4
+
+ - 3
+
+ - 2
+
+ - 1
+
+ - 0
+
+ - .. _MEDIA-BUS-FMT-AHSV8888-1X32:
+
+ - MEDIA_BUS_FMT_AHSV8888_1X32
+
+ - 0x6001
+
+ -
+ - a\ :sub:`7`
+
+ - a\ :sub:`6`
+
+ - a\ :sub:`5`
+
+ - a\ :sub:`4`
+
+ - a\ :sub:`3`
+
+ - a\ :sub:`2`
+
+ - a\ :sub:`1`
+
+ - a\ :sub:`0`
+
+ - h\ :sub:`7`
+
+ - h\ :sub:`6`
+
+ - h\ :sub:`5`
+
+ - h\ :sub:`4`
+
+ - h\ :sub:`3`
+
+ - h\ :sub:`2`
+
+ - h\ :sub:`1`
+
+ - h\ :sub:`0`
+
+ - s\ :sub:`7`
+
+ - s\ :sub:`6`
+
+ - s\ :sub:`5`
+
+ - s\ :sub:`4`
+
+ - s\ :sub:`3`
+
+ - s\ :sub:`2`
+
+ - s\ :sub:`1`
+
+ - s\ :sub:`0`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+
+
+JPEG Compressed Formats
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Those data formats consist of an ordered sequence of 8-bit bytes
+obtained from JPEG compression process. Additionally to the ``_JPEG``
+postfix the format code is made of the following information.
+
+- The number of bus samples per entropy encoded byte.
+
+- The bus width.
+
+For instance, for a JPEG baseline process and an 8-bit bus width the
+format will be named ``MEDIA_BUS_FMT_JPEG_1X8``.
+
+The following table lists existing JPEG compressed formats.
+
+
+.. _v4l2-mbus-pixelcode-jpeg:
+
+.. flat-table:: JPEG Formats
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Code
+
+ - Remarks
+
+ - .. _MEDIA-BUS-FMT-JPEG-1X8:
+
+ - MEDIA_BUS_FMT_JPEG_1X8
+
+ - 0x4001
+
+ - Besides of its usage for the parallel bus this format is
+ recommended for transmission of JPEG data over MIPI CSI bus using
+ the User Defined 8-bit Data types.
+
+
+
+.. _v4l2-mbus-vendor-spec-fmts:
+
+Vendor and Device Specific Formats
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This section lists complex data formats that are either vendor or device
+specific.
+
+The following table lists the existing vendor and device specific
+formats.
+
+
+.. _v4l2-mbus-pixelcode-vendor-specific:
+
+.. flat-table:: Vendor and device specific formats
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Code
+
+ - Comments
+
+ - .. _MEDIA-BUS-FMT-S5C-UYVY-JPEG-1X8:
+
+ - MEDIA_BUS_FMT_S5C_UYVY_JPEG_1X8
+
+ - 0x5001
+
+ - Interleaved raw UYVY and JPEG image format with embedded meta-data
+ used by Samsung S3C73MX camera sensors.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _tuner:
+
+*********************
+Tuners and Modulators
+*********************
+
+
+Tuners
+======
+
+Video input devices can have one or more tuners demodulating a RF
+signal. Each tuner is associated with one or more video inputs,
+depending on the number of RF connectors on the tuner. The ``type``
+field of the respective struct :ref:`v4l2_input <v4l2-input>`
+returned by the :ref:`VIDIOC_ENUMINPUT` ioctl is
+set to ``V4L2_INPUT_TYPE_TUNER`` and its ``tuner`` field contains the
+index number of the tuner.
+
+Radio input devices have exactly one tuner with index zero, no video
+inputs.
+
+To query and change tuner properties applications use the
+:ref:`VIDIOC_G_TUNER <VIDIOC_G_TUNER>` and
+:ref:`VIDIOC_S_TUNER <VIDIOC_G_TUNER>` ioctls, respectively. The
+struct :ref:`v4l2_tuner <v4l2-tuner>` returned by :ref:`VIDIOC_G_TUNER <VIDIOC_G_TUNER>`
+also contains signal status information applicable when the tuner of the
+current video or radio input is queried. Note that :ref:`VIDIOC_S_TUNER <VIDIOC_G_TUNER>`
+does not switch the current tuner, when there is more than one at all.
+The tuner is solely determined by the current video input. Drivers must
+support both ioctls and set the ``V4L2_CAP_TUNER`` flag in the struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP` ioctl when the device has
+one or more tuners.
+
+
+Modulators
+==========
+
+Video output devices can have one or more modulators, uh, modulating a
+video signal for radiation or connection to the antenna input of a TV
+set or video recorder. Each modulator is associated with one or more
+video outputs, depending on the number of RF connectors on the
+modulator. The ``type`` field of the respective struct
+:ref:`v4l2_output <v4l2-output>` returned by the
+:ref:`VIDIOC_ENUMOUTPUT` ioctl is set to
+``V4L2_OUTPUT_TYPE_MODULATOR`` and its ``modulator`` field contains the
+index number of the modulator.
+
+Radio output devices have exactly one modulator with index zero, no
+video outputs.
+
+A video or radio device cannot support both a tuner and a modulator. Two
+separate device nodes will have to be used for such hardware, one that
+supports the tuner functionality and one that supports the modulator
+functionality. The reason is a limitation with the
+:ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl where you
+cannot specify whether the frequency is for a tuner or a modulator.
+
+To query and change modulator properties applications use the
+:ref:`VIDIOC_G_MODULATOR <VIDIOC_G_MODULATOR>` and
+:ref:`VIDIOC_S_MODULATOR <VIDIOC_G_MODULATOR>` ioctl. Note that
+:ref:`VIDIOC_S_MODULATOR <VIDIOC_G_MODULATOR>` does not switch the current modulator, when there
+is more than one at all. The modulator is solely determined by the
+current video output. Drivers must support both ioctls and set the
+``V4L2_CAP_MODULATOR`` flag in the struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP` ioctl when the device has
+one or more modulators.
+
+
+Radio Frequency
+===============
+
+To get and set the tuner or modulator radio frequency applications use
+the :ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` and
+:ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl which both take
+a pointer to a struct :ref:`v4l2_frequency <v4l2-frequency>`. These
+ioctls are used for TV and radio devices alike. Drivers must support
+both ioctls when the tuner or modulator ioctls are supported, or when
+the device is a radio device.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _user-func:
+
+******************
+Function Reference
+******************
+
+
+.. toctree::
+ :maxdepth: 1
+
+ func-close
+ func-ioctl
+ vidioc-create-bufs
+ vidioc-cropcap
+ vidioc-dbg-g-chip-info
+ vidioc-dbg-g-register
+ vidioc-decoder-cmd
+ vidioc-dqevent
+ vidioc-dv-timings-cap
+ vidioc-encoder-cmd
+ vidioc-enumaudio
+ vidioc-enumaudioout
+ vidioc-enum-dv-timings
+ vidioc-enum-fmt
+ vidioc-enum-framesizes
+ vidioc-enum-frameintervals
+ vidioc-enum-freq-bands
+ vidioc-enuminput
+ vidioc-enumoutput
+ vidioc-enumstd
+ vidioc-expbuf
+ vidioc-g-audio
+ vidioc-g-audioout
+ vidioc-g-crop
+ vidioc-g-ctrl
+ vidioc-g-dv-timings
+ vidioc-g-edid
+ vidioc-g-enc-index
+ vidioc-g-ext-ctrls
+ vidioc-g-fbuf
+ vidioc-g-fmt
+ vidioc-g-frequency
+ vidioc-g-input
+ vidioc-g-jpegcomp
+ vidioc-g-modulator
+ vidioc-g-output
+ vidioc-g-parm
+ vidioc-g-priority
+ vidioc-g-selection
+ vidioc-g-sliced-vbi-cap
+ vidioc-g-std
+ vidioc-g-tuner
+ vidioc-log-status
+ vidioc-overlay
+ vidioc-prepare-buf
+ vidioc-qbuf
+ vidioc-querybuf
+ vidioc-querycap
+ vidioc-queryctrl
+ vidioc-query-dv-timings
+ vidioc-querystd
+ vidioc-reqbufs
+ vidioc-s-hw-freq-seek
+ vidioc-streamon
+ vidioc-subdev-enum-frame-interval
+ vidioc-subdev-enum-frame-size
+ vidioc-subdev-enum-mbus-code
+ vidioc-subdev-g-crop
+ vidioc-subdev-g-fmt
+ vidioc-subdev-g-frame-interval
+ vidioc-subdev-g-selection
+ vidioc-subscribe-event
+ func-mmap
+ func-munmap
+ func-open
+ func-poll
+ func-read
+ func-select
+ func-write
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _userp:
+
+*****************************
+Streaming I/O (User Pointers)
+*****************************
+
+Input and output devices support this I/O method when the
+``V4L2_CAP_STREAMING`` flag in the ``capabilities`` field of struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP` ioctl is set. If the
+particular user pointer method (not only memory mapping) is supported
+must be determined by calling the
+:ref:`VIDIOC_REQBUFS` ioctl.
+
+This I/O method combines advantages of the read/write and memory mapping
+methods. Buffers (planes) are allocated by the application itself, and
+can reside for example in virtual or shared memory. Only pointers to
+data are exchanged, these pointers and meta-information are passed in
+struct :ref:`v4l2_buffer <v4l2-buffer>` (or in struct
+:ref:`v4l2_plane <v4l2-plane>` in the multi-planar API case). The
+driver must be switched into user pointer I/O mode by calling the
+:ref:`VIDIOC_REQBUFS` with the desired buffer type.
+No buffers (planes) are allocated beforehand, consequently they are not
+indexed and cannot be queried like mapped buffers with the
+:ref:`VIDIOC_QUERYBUF <VIDIOC_QUERYBUF>` ioctl.
+
+
+.. code-block:: c
+ :caption: Example 3.3. Initiating streaming I/O with user pointers
+
+ struct v4l2_requestbuffers reqbuf;
+
+ memset (&reqbuf, 0, sizeof (reqbuf));
+ reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ reqbuf.memory = V4L2_MEMORY_USERPTR;
+
+ if (ioctl (fd, VIDIOC_REQBUFS, &reqbuf) == -1) {
+ if (errno == EINVAL)
+ printf ("Video capturing or user pointer streaming is not supported\\n");
+ else
+ perror ("VIDIOC_REQBUFS");
+
+ exit (EXIT_FAILURE);
+ }
+
+Buffer (plane) addresses and sizes are passed on the fly with the
+:ref:`VIDIOC_QBUF <VIDIOC_QBUF>` ioctl. Although buffers are commonly
+cycled, applications can pass different addresses and sizes at each
+:ref:`VIDIOC_QBUF <VIDIOC_QBUF>` call. If required by the hardware the
+driver swaps memory pages within physical memory to create a continuous
+area of memory. This happens transparently to the application in the
+virtual memory subsystem of the kernel. When buffer pages have been
+swapped out to disk they are brought back and finally locked in physical
+memory for DMA. [1]_
+
+Filled or displayed buffers are dequeued with the
+:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. The driver can unlock the
+memory pages at any time between the completion of the DMA and this
+ioctl. The memory is also unlocked when
+:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` is called,
+:ref:`VIDIOC_REQBUFS`, or when the device is closed.
+Applications must take care not to free buffers without dequeuing. For
+once, the buffers remain locked until further, wasting physical memory.
+Second the driver will not be notified when the memory is returned to
+the application's free list and subsequently reused for other purposes,
+possibly completing the requested DMA and overwriting valuable data.
+
+For capturing applications it is customary to enqueue a number of empty
+buffers, to start capturing and enter the read loop. Here the
+application waits until a filled buffer can be dequeued, and re-enqueues
+the buffer when the data is no longer needed. Output applications fill
+and enqueue buffers, when enough buffers are stacked up output is
+started. In the write loop, when the application runs out of free
+buffers it must wait until an empty buffer can be dequeued and reused.
+Two methods exist to suspend execution of the application until one or
+more buffers can be dequeued. By default :ref:`VIDIOC_DQBUF
+<VIDIOC_QBUF>` blocks when no buffer is in the outgoing queue. When the
+``O_NONBLOCK`` flag was given to the :ref:`open() <func-open>` function,
+:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` returns immediately with an ``EAGAIN``
+error code when no buffer is available. The :ref:`select()
+<func-select>` or :ref:`poll() <func-poll>` function are always
+available.
+
+To start and stop capturing or output applications call the
+:ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and
+:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctl. Note
+:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` removes all buffers from both
+queues and unlocks all buffers as a side effect. Since there is no
+notion of doing anything "now" on a multitasking system, if an
+application needs to synchronize with another event it should examine
+the struct :ref:`v4l2_buffer <v4l2-buffer>` ``timestamp`` of captured or
+outputted buffers.
+
+Drivers implementing user pointer I/O must support the
+:ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`,
+:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`
+and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls, the
+:ref:`select() <func-select>` and :ref:`poll() <func-poll>` function. [2]_
+
+.. [1]
+ We expect that frequently used buffers are typically not swapped out.
+ Anyway, the process of swapping, locking or generating scatter-gather
+ lists may be time consuming. The delay can be masked by the depth of
+ the incoming buffer queue, and perhaps by maintaining caches assuming
+ a buffer will be soon enqueued again. On the other hand, to optimize
+ memory usage drivers can limit the number of buffers locked in
+ advance and recycle the most recently used buffers first. Of course,
+ the pages of empty buffers in the incoming queue need not be saved to
+ disk. Output buffers must be saved on the incoming and outgoing queue
+ because an application may share them with other processes.
+
+.. [2]
+ At the driver level :ref:`select() <func-select>` and :ref:`poll() <func-poll>` are
+ the same, and :ref:`select() <func-select>` is too important to be optional.
+ The rest should be evident.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _v4l2-selection-flags:
+
+***************
+Selection flags
+***************
+
+
+.. _v4l2-selection-flags-table:
+
+.. flat-table:: Selection flag definitions
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Flag name
+
+ - id
+
+ - Definition
+
+ - Valid for V4L2
+
+ - Valid for V4L2 subdev
+
+ - .. row 2
+
+ - ``V4L2_SEL_FLAG_GE``
+
+ - (1 << 0)
+
+ - Suggest the driver it should choose greater or equal rectangle (in
+ size) than was requested. Albeit the driver may choose a lesser
+ size, it will only do so due to hardware limitations. Without this
+ flag (and ``V4L2_SEL_FLAG_LE``) the behaviour is to choose the
+ closest possible rectangle.
+
+ - Yes
+
+ - Yes
+
+ - .. row 3
+
+ - ``V4L2_SEL_FLAG_LE``
+
+ - (1 << 1)
+
+ - Suggest the driver it should choose lesser or equal rectangle (in
+ size) than was requested. Albeit the driver may choose a greater
+ size, it will only do so due to hardware limitations.
+
+ - Yes
+
+ - Yes
+
+ - .. row 4
+
+ - ``V4L2_SEL_FLAG_KEEP_CONFIG``
+
+ - (1 << 2)
+
+ - The configuration must not be propagated to any further processing
+ steps. If this flag is not given, the configuration is propagated
+ inside the subdevice to all further processing steps.
+
+ - No
+
+ - Yes
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _v4l2-selection-targets:
+
+*****************
+Selection targets
+*****************
+
+The precise meaning of the selection targets may be dependent on which
+of the two interfaces they are used.
+
+
+.. _v4l2-selection-targets-table:
+
+.. flat-table:: Selection target definitions
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Target name
+
+ - id
+
+ - Definition
+
+ - Valid for V4L2
+
+ - Valid for V4L2 subdev
+
+ - .. row 2
+
+ - ``V4L2_SEL_TGT_CROP``
+
+ - 0x0000
+
+ - Crop rectangle. Defines the cropped area.
+
+ - Yes
+
+ - Yes
+
+ - .. row 3
+
+ - ``V4L2_SEL_TGT_CROP_DEFAULT``
+
+ - 0x0001
+
+ - Suggested cropping rectangle that covers the "whole picture".
+
+ - Yes
+
+ - No
+
+ - .. row 4
+
+ - ``V4L2_SEL_TGT_CROP_BOUNDS``
+
+ - 0x0002
+
+ - Bounds of the crop rectangle. All valid crop rectangles fit inside
+ the crop bounds rectangle.
+
+ - Yes
+
+ - Yes
+
+ - .. row 5
+
+ - ``V4L2_SEL_TGT_NATIVE_SIZE``
+
+ - 0x0003
+
+ - The native size of the device, e.g. a sensor's pixel array.
+ ``left`` and ``top`` fields are zero for this target. Setting the
+ native size will generally only make sense for memory to memory
+ devices where the software can create a canvas of a given size in
+ which for example a video frame can be composed. In that case
+ V4L2_SEL_TGT_NATIVE_SIZE can be used to configure the size of
+ that canvas.
+
+ - Yes
+
+ - Yes
+
+ - .. row 6
+
+ - ``V4L2_SEL_TGT_COMPOSE``
+
+ - 0x0100
+
+ - Compose rectangle. Used to configure scaling and composition.
+
+ - Yes
+
+ - Yes
+
+ - .. row 7
+
+ - ``V4L2_SEL_TGT_COMPOSE_DEFAULT``
+
+ - 0x0101
+
+ - Suggested composition rectangle that covers the "whole picture".
+
+ - Yes
+
+ - No
+
+ - .. row 8
+
+ - ``V4L2_SEL_TGT_COMPOSE_BOUNDS``
+
+ - 0x0102
+
+ - Bounds of the compose rectangle. All valid compose rectangles fit
+ inside the compose bounds rectangle.
+
+ - Yes
+
+ - Yes
+
+ - .. row 9
+
+ - ``V4L2_SEL_TGT_COMPOSE_PADDED``
+
+ - 0x0103
+
+ - The active area and all padding pixels that are inserted or
+ modified by hardware.
+
+ - Yes
+
+ - No
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. include:: <isonum.txt>
+.. _v4l2spec:
+
+###################
+Video for Linux API
+###################
+
+This part describes the Video for Linux API version 2 (V4L2 API) specification.
+
+**Revision 4.5**
+
+.. toctree::
+ :numbered:
+ :maxdepth: 1
+ :caption: Table of Contents
+
+ common
+ pixfmt
+ io
+ devices
+ driver
+ libv4l
+ compat
+ user-func
+ common-defs
+ videodev
+ capture-example
+ v4l2grab-example
+ biblio
+
+
+**********************
+Revision and Copyright
+**********************
+
+Authors, in alphabetical order:
+
+- Ailus, Sakari <sakari.ailus@iki.fi>
+
+ - Subdev selections API.
+
+- Carvalho Chehab, Mauro <m.chehab@kernel.org>
+
+ - Documented libv4l, designed and added v4l2grab example, Remote Controller chapter.
+
+- Dirks, Bill
+
+ - Original author of the V4L2 API and documentation.
+
+- H Schimek, Michael <mschimek@gmx.at>
+
+ - Original author of the V4L2 API and documentation.
+
+- Karicheri, Muralidharan <m-karicheri2@ti.com>
+
+ - Documented the Digital Video timings API.
+
+- Osciak, Pawel <pawel@osciak.com>
+
+ - Designed and documented the multi-planar API.
+
+- Palosaari, Antti <crope@iki.fi>
+
+ - SDR API.
+
+- Rubli, Martin
+
+ - Designed and documented the VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS ioctls.
+
+- Walls, Andy <awalls@md.metrocast.net>
+
+ - Documented the fielded V4L2_MPEG_STREAM_VBI_FMT_IVTV MPEG stream embedded, sliced VBI data format in this specification.
+
+- Verkuil, Hans <hverkuil@xs4all.nl>
+
+ - Designed and documented the VIDIOC_LOG_STATUS ioctl, the extended control ioctls, major parts of the sliced VBI API, the MPEG encoder and decoder APIs and the DV Timings API.
+
+**Copyright** |copy| 1999-2016: Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab, Pawel Osciak, Sakari Ailus & Antti Palosaari.
+
+Except when explicitly stated as GPL, programming examples within this
+part can be used and distributed without restrictions.
+
+****************
+Revision History
+****************
+
+:revision: 4.5 / 2015-10-29 (*rr*)
+
+Extend VIDIOC_G_EXT_CTRLS;. Replace ctrl_class with a new union with
+ctrl_class and which. Which is used to select the current value of the
+control or the default value.
+
+
+:revision: 4.4 / 2015-05-26 (*ap*)
+
+Renamed V4L2_TUNER_ADC to V4L2_TUNER_SDR. Added
+V4L2_CID_RF_TUNER_RF_GAIN control. Added transmitter support for
+Software Defined Radio (SDR) Interface.
+
+
+:revision: 4.1 / 2015-02-13 (*mcc*)
+
+Fix documentation for media controller device nodes and add support for
+DVB device nodes. Add support for Tuner sub-device.
+
+
+:revision: 3.19 / 2014-12-05 (*hv*)
+
+Rewrote Colorspace chapter, added new enum
+:ref:`v4l2_ycbcr_encoding <v4l2-ycbcr-encoding>` and enum
+:ref:`v4l2_quantization <v4l2-quantization>` fields to struct
+:ref:`v4l2_pix_format <v4l2-pix-format>`, struct
+:ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` and struct
+:ref:`v4l2_mbus_framefmt <v4l2-mbus-framefmt>`.
+
+
+:revision: 3.17 / 2014-08-04 (*lp, hv*)
+
+Extended struct :ref:`v4l2_pix_format <v4l2-pix-format>`. Added
+format flags. Added compound control types and VIDIOC_QUERY_EXT_CTRL.
+
+
+:revision: 3.15 / 2014-02-03 (*hv, ap*)
+
+Update several sections of "Common API Elements": "Opening and Closing
+Devices" "Querying Capabilities", "Application Priority", "Video Inputs
+and Outputs", "Audio Inputs and Outputs" "Tuners and Modulators", "Video
+Standards" and "Digital Video (DV) Timings". Added SDR API.
+
+
+:revision: 3.14 / 2013-11-25 (*rr*)
+
+Set width and height as unsigned on v4l2_rect.
+
+
+:revision: 3.11 / 2013-05-26 (*hv*)
+
+Remove obsolete VIDIOC_DBG_G_CHIP_IDENT ioctl.
+
+
+:revision: 3.10 / 2013-03-25 (*hv*)
+
+Remove obsolete and unused DV_PRESET ioctls: VIDIOC_G_DV_PRESET,
+VIDIOC_S_DV_PRESET, VIDIOC_QUERY_DV_PRESET and
+VIDIOC_ENUM_DV_PRESET. Remove the related v4l2_input/output
+capability flags V4L2_IN_CAP_PRESETS and V4L2_OUT_CAP_PRESETS.
+Added VIDIOC_DBG_G_CHIP_INFO.
+
+
+:revision: 3.9 / 2012-12-03 (*sa, sn*)
+
+Added timestamp types to v4l2_buffer. Added
+V4L2_EVENT_CTRL_CH_RANGE control event changes flag.
+
+
+:revision: 3.6 / 2012-07-02 (*hv*)
+
+Added VIDIOC_ENUM_FREQ_BANDS.
+
+
+:revision: 3.5 / 2012-05-07 (*sa, sn, hv*)
+
+Added V4L2_CTRL_TYPE_INTEGER_MENU and V4L2 subdev selections API.
+Improved the description of V4L2_CID_COLORFX control, added
+V4L2_CID_COLORFX_CBCR control. Added camera controls
+V4L2_CID_AUTO_EXPOSURE_BIAS,
+V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE,
+V4L2_CID_IMAGE_STABILIZATION, V4L2_CID_ISO_SENSITIVITY,
+V4L2_CID_ISO_SENSITIVITY_AUTO, V4L2_CID_EXPOSURE_METERING,
+V4L2_CID_SCENE_MODE, V4L2_CID_3A_LOCK,
+V4L2_CID_AUTO_FOCUS_START, V4L2_CID_AUTO_FOCUS_STOP,
+V4L2_CID_AUTO_FOCUS_STATUS and V4L2_CID_AUTO_FOCUS_RANGE. Added
+VIDIOC_ENUM_DV_TIMINGS, VIDIOC_QUERY_DV_TIMINGS and
+VIDIOC_DV_TIMINGS_CAP.
+
+
+:revision: 3.4 / 2012-01-25 (*sn*)
+
+Added :ref:`JPEG compression control class. <jpeg-controls>`
+
+
+:revision: 3.3 / 2012-01-11 (*hv*)
+
+Added device_caps field to struct v4l2_capabilities.
+
+
+:revision: 3.2 / 2011-08-26 (*hv*)
+
+Added V4L2_CTRL_FLAG_VOLATILE.
+
+
+:revision: 3.1 / 2011-06-27 (*mcc, po, hv*)
+
+Documented that VIDIOC_QUERYCAP now returns a per-subsystem version
+instead of a per-driver one. Standardize an error code for invalid
+ioctl. Added V4L2_CTRL_TYPE_BITMASK.
+
+
+:revision: 2.6.39 / 2011-03-01 (*mcc, po*)
+
+Removed VIDIOC_*_OLD from videodev2.h header and update it to reflect
+latest changes. Added the :ref:`multi-planar API <planar-apis>`.
+
+
+:revision: 2.6.37 / 2010-08-06 (*hv*)
+
+Removed obsolete vtx (videotext) API.
+
+
+:revision: 2.6.33 / 2009-12-03 (*mk*)
+
+Added documentation for the Digital Video timings API.
+
+
+:revision: 2.6.32 / 2009-08-31 (*mcc*)
+
+Now, revisions will match the kernel version where the V4L2 API changes
+will be used by the Linux Kernel. Also added Remote Controller chapter.
+
+
+:revision: 0.29 / 2009-08-26 (*ev*)
+
+Added documentation for string controls and for FM Transmitter controls.
+
+
+:revision: 0.28 / 2009-08-26 (*gl*)
+
+Added V4L2_CID_BAND_STOP_FILTER documentation.
+
+
+:revision: 0.27 / 2009-08-15 (*mcc*)
+
+Added libv4l and Remote Controller documentation; added v4l2grab and
+keytable application examples.
+
+
+:revision: 0.26 / 2009-07-23 (*hv*)
+
+Finalized the RDS capture API. Added modulator and RDS encoder
+capabilities. Added support for string controls.
+
+
+:revision: 0.25 / 2009-01-18 (*hv*)
+
+Added pixel formats VYUY, NV16 and NV61, and changed the debug ioctls
+VIDIOC_DBG_G/S_REGISTER and VIDIOC_DBG_G_CHIP_IDENT. Added camera
+controls V4L2_CID_ZOOM_ABSOLUTE, V4L2_CID_ZOOM_RELATIVE,
+V4L2_CID_ZOOM_CONTINUOUS and V4L2_CID_PRIVACY.
+
+
+:revision: 0.24 / 2008-03-04 (*mhs*)
+
+Added pixel formats Y16 and SBGGR16, new controls and a camera controls
+class. Removed VIDIOC_G/S_MPEGCOMP.
+
+
+:revision: 0.23 / 2007-08-30 (*mhs*)
+
+Fixed a typo in VIDIOC_DBG_G/S_REGISTER. Clarified the byte order of
+packed pixel formats.
+
+
+:revision: 0.22 / 2007-08-29 (*mhs*)
+
+Added the Video Output Overlay interface, new MPEG controls,
+V4L2_FIELD_INTERLACED_TB and V4L2_FIELD_INTERLACED_BT,
+VIDIOC_DBG_G/S_REGISTER, VIDIOC\_(TRY\_)ENCODER_CMD,
+VIDIOC_G_CHIP_IDENT, VIDIOC_G_ENC_INDEX, new pixel formats.
+Clarifications in the cropping chapter, about RGB pixel formats, the
+mmap(), poll(), select(), read() and write() functions. Typographical
+fixes.
+
+
+:revision: 0.21 / 2006-12-19 (*mhs*)
+
+Fixed a link in the VIDIOC_G_EXT_CTRLS section.
+
+
+:revision: 0.20 / 2006-11-24 (*mhs*)
+
+Clarified the purpose of the audioset field in struct v4l2_input and
+v4l2_output.
+
+
+:revision: 0.19 / 2006-10-19 (*mhs*)
+
+Documented V4L2_PIX_FMT_RGB444.
+
+
+:revision: 0.18 / 2006-10-18 (*mhs*)
+
+Added the description of extended controls by Hans Verkuil. Linked
+V4L2_PIX_FMT_MPEG to V4L2_CID_MPEG_STREAM_TYPE.
+
+
+:revision: 0.17 / 2006-10-12 (*mhs*)
+
+Corrected V4L2_PIX_FMT_HM12 description.
+
+
+:revision: 0.16 / 2006-10-08 (*mhs*)
+
+VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS are now part
+of the API.
+
+
+:revision: 0.15 / 2006-09-23 (*mhs*)
+
+Cleaned up the bibliography, added BT.653 and BT.1119.
+capture.c/start_capturing() for user pointer I/O did not initialize the
+buffer index. Documented the V4L MPEG and MJPEG VID_TYPEs and
+V4L2_PIX_FMT_SBGGR8. Updated the list of reserved pixel formats. See
+the history chapter for API changes.
+
+
+:revision: 0.14 / 2006-09-14 (*mr*)
+
+Added VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS proposal
+for frame format enumeration of digital devices.
+
+
+:revision: 0.13 / 2006-04-07 (*mhs*)
+
+Corrected the description of struct v4l2_window clips. New V4L2_STD\_
+and V4L2_TUNER_MODE_LANG1_LANG2 defines.
+
+
+:revision: 0.12 / 2006-02-03 (*mhs*)
+
+Corrected the description of struct v4l2_captureparm and
+v4l2_outputparm.
+
+
+:revision: 0.11 / 2006-01-27 (*mhs*)
+
+Improved the description of struct v4l2_tuner.
+
+
+:revision: 0.10 / 2006-01-10 (*mhs*)
+
+VIDIOC_G_INPUT and VIDIOC_S_PARM clarifications.
+
+
+:revision: 0.9 / 2005-11-27 (*mhs*)
+
+Improved the 525 line numbering diagram. Hans Verkuil and I rewrote the
+sliced VBI section. He also contributed a VIDIOC_LOG_STATUS page.
+Fixed VIDIOC_S_STD call in the video standard selection example.
+Various updates.
+
+
+:revision: 0.8 / 2004-10-04 (*mhs*)
+
+Somehow a piece of junk slipped into the capture example, removed.
+
+
+:revision: 0.7 / 2004-09-19 (*mhs*)
+
+Fixed video standard selection, control enumeration, downscaling and
+aspect example. Added read and user pointer i/o to video capture
+example.
+
+
+:revision: 0.6 / 2004-08-01 (*mhs*)
+
+v4l2_buffer changes, added video capture example, various corrections.
+
+
+:revision: 0.5 / 2003-11-05 (*mhs*)
+
+Pixel format erratum.
+
+
+:revision: 0.4 / 2003-09-17 (*mhs*)
+
+Corrected source and Makefile to generate a PDF. SGML fixes. Added
+latest API changes. Closed gaps in the history chapter.
+
+
+:revision: 0.3 / 2003-02-05 (*mhs*)
+
+Another draft, more corrections.
+
+
+:revision: 0.2 / 2003-01-15 (*mhs*)
+
+Second draft, with corrections pointed out by Gerd Knorr.
+
+
+:revision: 0.1 / 2002-12-01 (*mhs*)
+
+First draft, based on documentation by Bill Dirks and discussions on the
+V4L mailing list.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _v4l2grab-example:
+
+**********************************
+Video Grabber example using libv4l
+**********************************
+
+This program demonstrates how to grab V4L2 images in ppm format by using
+libv4l handlers. The advantage is that this grabber can potentially work
+with any V4L2 driver.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ v4l2grab.c
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+file: media/v4l/v4l2grab.c
+==========================
+
+.. code-block:: c
+
+ /* V4L2 video picture grabber
+ Copyright (C) 2009 Mauro Carvalho Chehab <mchehab@infradead.org>
+
+ This program is free software; you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation version 2 of the License.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU General Public License for more details.
+ */
+
+ #include <stdio.h>
+ #include <stdlib.h>
+ #include <string.h>
+ #include <fcntl.h>
+ #include <errno.h>
+ #include <sys/ioctl.h>
+ #include <sys/types.h>
+ #include <sys/time.h>
+ #include <sys/mman.h>
+ #include <linux/videodev2.h>
+ #include "../libv4l/include/libv4l2.h"
+
+ #define CLEAR(x) memset(&(x), 0, sizeof(x))
+
+ struct buffer {
+ void *start;
+ size_t length;
+ };
+
+ static void xioctl(int fh, int request, void *arg)
+ {
+ int r;
+
+ do {
+ r = v4l2_ioctl(fh, request, arg);
+ } while (r == -1 && ((errno == EINTR) || (errno == EAGAIN)));
+
+ if (r == -1) {
+ fprintf(stderr, "error %d, %s\\n", errno, strerror(errno));
+ exit(EXIT_FAILURE);
+ }
+ }
+
+ int main(int argc, char **argv)
+ {
+ struct v4l2_format fmt;
+ struct v4l2_buffer buf;
+ struct v4l2_requestbuffers req;
+ enum v4l2_buf_type type;
+ fd_set fds;
+ struct timeval tv;
+ int r, fd = -1;
+ unsigned int i, n_buffers;
+ char *dev_name = "/dev/video0";
+ char out_name[256];
+ FILE *fout;
+ struct buffer *buffers;
+
+ fd = v4l2_open(dev_name, O_RDWR | O_NONBLOCK, 0);
+ if (fd < 0) {
+ perror("Cannot open device");
+ exit(EXIT_FAILURE);
+ }
+
+ CLEAR(fmt);
+ fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ fmt.fmt.pix.width = 640;
+ fmt.fmt.pix.height = 480;
+ fmt.fmt.pix.pixelformat = V4L2_PIX_FMT_RGB24;
+ fmt.fmt.pix.field = V4L2_FIELD_INTERLACED;
+ xioctl(fd, VIDIOC_S_FMT, &fmt);
+ if (fmt.fmt.pix.pixelformat != V4L2_PIX_FMT_RGB24) {
+ printf("Libv4l didn't accept RGB24 format. Can't proceed.\\n");
+ exit(EXIT_FAILURE);
+ }
+ if ((fmt.fmt.pix.width != 640) || (fmt.fmt.pix.height != 480))
+ printf("Warning: driver is sending image at %dx%d\\n",
+ fmt.fmt.pix.width, fmt.fmt.pix.height);
+
+ CLEAR(req);
+ req.count = 2;
+ req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ req.memory = V4L2_MEMORY_MMAP;
+ xioctl(fd, VIDIOC_REQBUFS, &req);
+
+ buffers = calloc(req.count, sizeof(*buffers));
+ for (n_buffers = 0; n_buffers < req.count; ++n_buffers) {
+ CLEAR(buf);
+
+ buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ buf.memory = V4L2_MEMORY_MMAP;
+ buf.index = n_buffers;
+
+ xioctl(fd, VIDIOC_QUERYBUF, &buf);
+
+ buffers[n_buffers].length = buf.length;
+ buffers[n_buffers].start = v4l2_mmap(NULL, buf.length,
+ PROT_READ | PROT_WRITE, MAP_SHARED,
+ fd, buf.m.offset);
+
+ if (MAP_FAILED == buffers[n_buffers].start) {
+ perror("mmap");
+ exit(EXIT_FAILURE);
+ }
+ }
+
+ for (i = 0; i < n_buffers; ++i) {
+ CLEAR(buf);
+ buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ buf.memory = V4L2_MEMORY_MMAP;
+ buf.index = i;
+ xioctl(fd, VIDIOC_QBUF, &buf);
+ }
+ type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+
+ xioctl(fd, VIDIOC_STREAMON, &type);
+ for (i = 0; i < 20; i++) {
+ do {
+ FD_ZERO(&fds);
+ FD_SET(fd, &fds);
+
+ /* Timeout. */
+ tv.tv_sec = 2;
+ tv.tv_usec = 0;
+
+ r = select(fd + 1, &fds, NULL, NULL, &tv);
+ } while ((r == -1 && (errno = EINTR)));
+ if (r == -1) {
+ perror("select");
+ return errno;
+ }
+
+ CLEAR(buf);
+ buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ buf.memory = V4L2_MEMORY_MMAP;
+ xioctl(fd, VIDIOC_DQBUF, &buf);
+
+ sprintf(out_name, "out%03d.ppm", i);
+ fout = fopen(out_name, "w");
+ if (!fout) {
+ perror("Cannot open image");
+ exit(EXIT_FAILURE);
+ }
+ fprintf(fout, "P6\\n%d %d 255\\n",
+ fmt.fmt.pix.width, fmt.fmt.pix.height);
+ fwrite(buffers[buf.index].start, buf.bytesused, 1, fout);
+ fclose(fout);
+
+ xioctl(fd, VIDIOC_QBUF, &buf);
+ }
+
+ type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ xioctl(fd, VIDIOC_STREAMOFF, &type);
+ for (i = 0; i < n_buffers; ++i)
+ v4l2_munmap(buffers[i].start, buffers[i].length);
+ v4l2_close(fd);
+
+ return 0;
+ }
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _video:
+
+************************
+Video Inputs and Outputs
+************************
+
+Video inputs and outputs are physical connectors of a device. These can
+be for example RF connectors (antenna/cable), CVBS a.k.a. Composite
+Video, S-Video or RGB connectors. Video and VBI capture devices have
+inputs. Video and VBI output devices have outputs, at least one each.
+Radio devices have no video inputs or outputs.
+
+To learn about the number and attributes of the available inputs and
+outputs applications can enumerate them with the
+:ref:`VIDIOC_ENUMINPUT` and
+:ref:`VIDIOC_ENUMOUTPUT` ioctl, respectively. The
+struct :ref:`v4l2_input <v4l2-input>` returned by the
+:ref:`VIDIOC_ENUMINPUT` ioctl also contains signal
+:status information applicable when the current video input is queried.
+
+The :ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` and
+:ref:`VIDIOC_G_OUTPUT <VIDIOC_G_OUTPUT>` ioctls return the index of
+the current video input or output. To select a different input or output
+applications call the :ref:`VIDIOC_S_INPUT <VIDIOC_G_INPUT>` and
+:ref:`VIDIOC_S_OUTPUT <VIDIOC_G_OUTPUT>` ioctls. Drivers must
+implement all the input ioctls when the device has one or more inputs,
+all the output ioctls when the device has one or more outputs.
+
+.. code-block:: c
+ :caption: Example 1.1. Information about the current video input
+
+ struct v4l2_input input;
+ int index;
+
+ if (-1 == ioctl(fd, VIDIOC_G_INPUT, &index)) {
+ perror("VIDIOC_G_INPUT");
+ exit(EXIT_FAILURE);
+ }
+
+ memset(&input, 0, sizeof(input));
+ input.index = index;
+
+ if (-1 == ioctl(fd, VIDIOC_ENUMINPUT, &input)) {
+ perror("VIDIOC_ENUMINPUT");
+ exit(EXIT_FAILURE);
+ }
+
+ printf("Current input: %s\\n", input.name);
+
+
+.. code-block:: c
+ :caption: Example 1.2. Switching to the first video input
+
+ int index;
+
+ index = 0;
+
+ if (-1 == ioctl(fd, VIDIOC_S_INPUT, &index)) {
+ perror("VIDIOC_S_INPUT");
+ exit(EXIT_FAILURE);
+ }
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _videodev:
+
+*******************************
+Video For Linux Two Header File
+*******************************
+
+.. kernel-include:: $BUILDDIR/videodev2.h.rst
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_CREATE_BUFS:
+
+************************
+ioctl VIDIOC_CREATE_BUFS
+************************
+
+Name
+====
+
+VIDIOC_CREATE_BUFS - Create buffers for Memory Mapped or User Pointer or DMA Buffer I/O
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_create_buffers *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_CREATE_BUFS
+
+``argp``
+
+
+Description
+===========
+
+This ioctl is used to create buffers for :ref:`memory mapped <mmap>`
+or :ref:`user pointer <userp>` or :ref:`DMA buffer <dmabuf>` I/O. It
+can be used as an alternative or in addition to the
+:ref:`VIDIOC_REQBUFS` ioctl, when a tighter control
+over buffers is required. This ioctl can be called multiple times to
+create buffers of different sizes.
+
+To allocate the device buffers applications must initialize the relevant
+fields of the :ref:`struct v4l2_create_buffers <v4l2-create-buffers>` structure. The
+``count`` field must be set to the number of requested buffers, the
+``memory`` field specifies the requested I/O method and the ``reserved``
+array must be zeroed.
+
+The ``format`` field specifies the image format that the buffers must be
+able to handle. The application has to fill in this struct
+:ref:`v4l2_format <v4l2-format>`. Usually this will be done using the
+:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` or
+:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctls to ensure that the
+requested format is supported by the driver. Based on the format's
+``type`` field the requested buffer size (for single-planar) or plane
+sizes (for multi-planar formats) will be used for the allocated buffers.
+The driver may return an error if the size(s) are not supported by the
+hardware (usually because they are too small).
+
+The buffers created by this ioctl will have as minimum size the size
+defined by the ``format.pix.sizeimage`` field (or the corresponding
+fields for other format types). Usually if the ``format.pix.sizeimage``
+field is less than the minimum required for the given format, then an
+error will be returned since drivers will typically not allow this. If
+it is larger, then the value will be used as-is. In other words, the
+driver may reject the requested size, but if it is accepted the driver
+will use it unchanged.
+
+When the ioctl is called with a pointer to this structure the driver
+will attempt to allocate up to the requested number of buffers and store
+the actual number allocated and the starting index in the ``count`` and
+the ``index`` fields respectively. On return ``count`` can be smaller
+than the number requested.
+
+
+.. _v4l2-create-buffers:
+
+.. flat-table:: struct v4l2_create_buffers
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``index``
+
+ - The starting buffer index, returned by the driver.
+
+ - .. row 2
+
+ - __u32
+
+ - ``count``
+
+ - The number of buffers requested or granted. If count == 0, then
+ :ref:`VIDIOC_CREATE_BUFS` will set ``index`` to the current number of
+ created buffers, and it will check the validity of ``memory`` and
+ ``format.type``. If those are invalid -1 is returned and errno is
+ set to ``EINVAL`` error code, otherwise :ref:`VIDIOC_CREATE_BUFS` returns
+ 0. It will never set errno to ``EBUSY`` error code in this particular
+ case.
+
+ - .. row 3
+
+ - __u32
+
+ - ``memory``
+
+ - Applications set this field to ``V4L2_MEMORY_MMAP``,
+ ``V4L2_MEMORY_DMABUF`` or ``V4L2_MEMORY_USERPTR``. See
+ :ref:`v4l2-memory`
+
+ - .. row 4
+
+ - struct :ref:`v4l2_format <v4l2-format>`
+
+ - ``format``
+
+ - Filled in by the application, preserved by the driver.
+
+ - .. row 5
+
+ - __u32
+
+ - ``reserved``\ [8]
+
+ - A place holder for future extensions. Drivers and applications
+ must set the array to zero.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+ENOMEM
+ No memory to allocate buffers for :ref:`memory mapped <mmap>` I/O.
+
+EINVAL
+ The buffer type (``format.type`` field), requested I/O method
+ (``memory``) or format (``format`` field) is not valid.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_CROPCAP:
+
+********************
+ioctl VIDIOC_CROPCAP
+********************
+
+Name
+====
+
+VIDIOC_CROPCAP - Information about the video cropping and scaling abilities
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_cropcap *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_CROPCAP
+
+``argp``
+
+
+Description
+===========
+
+Applications use this function to query the cropping limits, the pixel
+aspect of images and to calculate scale factors. They set the ``type``
+field of a v4l2_cropcap structure to the respective buffer (stream)
+type and call the :ref:`VIDIOC_CROPCAP` ioctl with a pointer to this
+structure. Drivers fill the rest of the structure. The results are
+constant except when switching the video standard. Remember this switch
+can occur implicit when switching the video input or output.
+
+Do not use the multiplanar buffer types. Use
+``V4L2_BUF_TYPE_VIDEO_CAPTURE`` instead of
+``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and use
+``V4L2_BUF_TYPE_VIDEO_OUTPUT`` instead of
+``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``.
+
+This ioctl must be implemented for video capture or output devices that
+support cropping and/or scaling and/or have non-square pixels, and for
+overlay devices.
+
+
+.. _v4l2-cropcap:
+
+.. flat-table:: struct v4l2_cropcap
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``type``
+
+ - Type of the data stream, set by the application. Only these types
+ are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``,
+ ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` and
+ ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :ref:`v4l2-buf-type`.
+
+ - .. row 2
+
+ - struct :ref:`v4l2_rect <v4l2-rect-crop>`
+
+ - ``bounds``
+
+ - Defines the window within capturing or output is possible, this
+ may exclude for example the horizontal and vertical blanking
+ areas. The cropping rectangle cannot exceed these limits. Width
+ and height are defined in pixels, the driver writer is free to
+ choose origin and units of the coordinate system in the analog
+ domain.
+
+ - .. row 3
+
+ - struct :ref:`v4l2_rect <v4l2-rect-crop>`
+
+ - ``defrect``
+
+ - Default cropping rectangle, it shall cover the "whole picture".
+ Assuming pixel aspect 1/1 this could be for example a 640 × 480
+ rectangle for NTSC, a 768 × 576 rectangle for PAL and SECAM
+ centered over the active picture area. The same co-ordinate system
+ as for ``bounds`` is used.
+
+ - .. row 4
+
+ - struct :ref:`v4l2_fract <v4l2-fract>`
+
+ - ``pixelaspect``
+
+ - This is the pixel aspect (y / x) when no scaling is applied, the
+ ratio of the actual sampling frequency and the frequency required
+ to get square pixels.
+
+ When cropping coordinates refer to square pixels, the driver sets
+ ``pixelaspect`` to 1/1. Other common values are 54/59 for PAL and
+ SECAM, 11/10 for NTSC sampled according to [:ref:`itu601`].
+
+
+
+.. _v4l2-rect-crop:
+
+.. flat-table:: struct v4l2_rect
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __s32
+
+ - ``left``
+
+ - Horizontal offset of the top, left corner of the rectangle, in
+ pixels.
+
+ - .. row 2
+
+ - __s32
+
+ - ``top``
+
+ - Vertical offset of the top, left corner of the rectangle, in
+ pixels.
+
+ - .. row 3
+
+ - __u32
+
+ - ``width``
+
+ - Width of the rectangle, in pixels.
+
+ - .. row 4
+
+ - __u32
+
+ - ``height``
+
+ - Height of the rectangle, in pixels.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The struct :ref:`v4l2_cropcap <v4l2-cropcap>` ``type`` is
+ invalid.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_DBG_G_CHIP_INFO:
+
+****************************
+ioctl VIDIOC_DBG_G_CHIP_INFO
+****************************
+
+Name
+====
+
+VIDIOC_DBG_G_CHIP_INFO - Identify the chips on a TV card
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_dbg_chip_info *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_DBG_G_CHIP_INFO
+
+``argp``
+
+
+Description
+===========
+
+ **Note**
+
+ This is an :ref:`experimental` interface and may
+ change in the future.
+
+For driver debugging purposes this ioctl allows test applications to
+query the driver about the chips present on the TV card. Regular
+applications must not use it. When you found a chip specific bug, please
+contact the linux-media mailing list
+(`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__)
+so it can be fixed.
+
+Additionally the Linux kernel must be compiled with the
+``CONFIG_VIDEO_ADV_DEBUG`` option to enable this ioctl.
+
+To query the driver applications must initialize the ``match.type`` and
+``match.addr`` or ``match.name`` fields of a struct
+:ref:`v4l2_dbg_chip_info <v4l2-dbg-chip-info>` and call
+:ref:`VIDIOC_DBG_G_CHIP_INFO` with a pointer to this structure. On success
+the driver stores information about the selected chip in the ``name``
+and ``flags`` fields.
+
+When ``match.type`` is ``V4L2_CHIP_MATCH_BRIDGE``, ``match.addr``
+selects the nth bridge 'chip' on the TV card. You can enumerate all
+chips by starting at zero and incrementing ``match.addr`` by one until
+:ref:`VIDIOC_DBG_G_CHIP_INFO` fails with an ``EINVAL`` error code. The number
+zero always selects the bridge chip itself, e. g. the chip connected to
+the PCI or USB bus. Non-zero numbers identify specific parts of the
+bridge chip such as an AC97 register block.
+
+When ``match.type`` is ``V4L2_CHIP_MATCH_SUBDEV``, ``match.addr``
+selects the nth sub-device. This allows you to enumerate over all
+sub-devices.
+
+On success, the ``name`` field will contain a chip name and the
+``flags`` field will contain ``V4L2_CHIP_FL_READABLE`` if the driver
+supports reading registers from the device or ``V4L2_CHIP_FL_WRITABLE``
+if the driver supports writing registers to the device.
+
+We recommended the v4l2-dbg utility over calling this ioctl directly. It
+is available from the LinuxTV v4l-dvb repository; see
+`https://linuxtv.org/repo/ <https://linuxtv.org/repo/>`__ for access
+instructions.
+
+
+.. _name-v4l2-dbg-match:
+
+.. flat-table:: struct v4l2_dbg_match
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``type``
+
+ - See :ref:`name-chip-match-types` for a list of possible types.
+
+ - .. row 2
+
+ - union
+
+ - (anonymous)
+
+ - .. row 3
+
+ -
+ - __u32
+
+ - ``addr``
+
+ - Match a chip by this number, interpreted according to the ``type``
+ field.
+
+ - .. row 4
+
+ -
+ - char
+
+ - ``name[32]``
+
+ - Match a chip by this name, interpreted according to the ``type``
+ field. Currently unused.
+
+
+
+.. _v4l2-dbg-chip-info:
+
+.. flat-table:: struct v4l2_dbg_chip_info
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - struct v4l2_dbg_match
+
+ - ``match``
+
+ - How to match the chip, see :ref:`name-v4l2-dbg-match`.
+
+ - .. row 2
+
+ - char
+
+ - ``name[32]``
+
+ - The name of the chip.
+
+ - .. row 3
+
+ - __u32
+
+ - ``flags``
+
+ - Set by the driver. If ``V4L2_CHIP_FL_READABLE`` is set, then the
+ driver supports reading registers from the device. If
+ ``V4L2_CHIP_FL_WRITABLE`` is set, then it supports writing
+ registers.
+
+ - .. row 4
+
+ - __u32
+
+ - ``reserved[8]``
+
+ - Reserved fields, both application and driver must set these to 0.
+
+
+
+.. _name-chip-match-types:
+
+.. flat-table:: Chip Match Types
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_CHIP_MATCH_BRIDGE``
+
+ - 0
+
+ - Match the nth chip on the card, zero for the bridge chip. Does not
+ match sub-devices.
+
+ - .. row 2
+
+ - ``V4L2_CHIP_MATCH_SUBDEV``
+
+ - 4
+
+ - Match the nth sub-device.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The ``match_type`` is invalid or no device could be matched.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_DBG_G_REGISTER:
+
+**************************************************
+ioctl VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER
+**************************************************
+
+Name
+====
+
+VIDIOC_DBG_G_REGISTER - VIDIOC_DBG_S_REGISTER - Read or write hardware registers
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_dbg_register *argp )
+
+.. cpp:function:: int ioctl( int fd, int request, const struct v4l2_dbg_register *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER
+
+``argp``
+
+
+Description
+===========
+
+ **Note**
+
+ This is an :ref:`experimental` interface and may
+ change in the future.
+
+For driver debugging purposes these ioctls allow test applications to
+access hardware registers directly. Regular applications must not use
+them.
+
+Since writing or even reading registers can jeopardize the system
+security, its stability and damage the hardware, both ioctls require
+superuser privileges. Additionally the Linux kernel must be compiled
+with the ``CONFIG_VIDEO_ADV_DEBUG`` option to enable these ioctls.
+
+To write a register applications must initialize all fields of a struct
+:ref:`v4l2_dbg_register <v4l2-dbg-register>` except for ``size`` and
+call ``VIDIOC_DBG_S_REGISTER`` with a pointer to this structure. The
+``match.type`` and ``match.addr`` or ``match.name`` fields select a chip
+on the TV card, the ``reg`` field specifies a register number and the
+``val`` field the value to be written into the register.
+
+To read a register applications must initialize the ``match.type``,
+``match.addr`` or ``match.name`` and ``reg`` fields, and call
+``VIDIOC_DBG_G_REGISTER`` with a pointer to this structure. On success
+the driver stores the register value in the ``val`` field and the size
+(in bytes) of the value in ``size``.
+
+When ``match.type`` is ``V4L2_CHIP_MATCH_BRIDGE``, ``match.addr``
+selects the nth non-sub-device chip on the TV card. The number zero
+always selects the host chip, e. g. the chip connected to the PCI or USB
+bus. You can find out which chips are present with the
+:ref:`VIDIOC_DBG_G_CHIP_INFO` ioctl.
+
+When ``match.type`` is ``V4L2_CHIP_MATCH_SUBDEV``, ``match.addr``
+selects the nth sub-device.
+
+These ioctls are optional, not all drivers may support them. However
+when a driver supports these ioctls it must also support
+:ref:`VIDIOC_DBG_G_CHIP_INFO`. Conversely
+it may support ``VIDIOC_DBG_G_CHIP_INFO`` but not these ioctls.
+
+``VIDIOC_DBG_G_REGISTER`` and ``VIDIOC_DBG_S_REGISTER`` were introduced
+in Linux 2.6.21, but their API was changed to the one described here in
+kernel 2.6.29.
+
+We recommended the v4l2-dbg utility over calling these ioctls directly.
+It is available from the LinuxTV v4l-dvb repository; see
+`https://linuxtv.org/repo/ <https://linuxtv.org/repo/>`__ for access
+instructions.
+
+
+.. _v4l2-dbg-match:
+
+.. flat-table:: struct v4l2_dbg_match
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``type``
+
+ - See :ref:`chip-match-types` for a list of possible types.
+
+ - .. row 2
+
+ - union
+
+ - (anonymous)
+
+ - .. row 3
+
+ -
+ - __u32
+
+ - ``addr``
+
+ - Match a chip by this number, interpreted according to the ``type``
+ field.
+
+ - .. row 4
+
+ -
+ - char
+
+ - ``name[32]``
+
+ - Match a chip by this name, interpreted according to the ``type``
+ field. Currently unused.
+
+
+
+.. _v4l2-dbg-register:
+
+.. flat-table:: struct v4l2_dbg_register
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - struct v4l2_dbg_match
+
+ - ``match``
+
+ - How to match the chip, see :ref:`v4l2-dbg-match`.
+
+ - .. row 2
+
+ - __u32
+
+ - ``size``
+
+ - The register size in bytes.
+
+ - .. row 3
+
+ - __u64
+
+ - ``reg``
+
+ - A register number.
+
+ - .. row 4
+
+ - __u64
+
+ - ``val``
+
+ - The value read from, or to be written into the register.
+
+
+
+.. _chip-match-types:
+
+.. flat-table:: Chip Match Types
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_CHIP_MATCH_BRIDGE``
+
+ - 0
+
+ - Match the nth chip on the card, zero for the bridge chip. Does not
+ match sub-devices.
+
+ - .. row 2
+
+ - ``V4L2_CHIP_MATCH_SUBDEV``
+
+ - 4
+
+ - Match the nth sub-device.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EPERM
+ Insufficient permissions. Root privileges are required to execute
+ these ioctls.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_DECODER_CMD:
+
+************************************************
+ioctl VIDIOC_DECODER_CMD, VIDIOC_TRY_DECODER_CMD
+************************************************
+
+Name
+====
+
+VIDIOC_DECODER_CMD - VIDIOC_TRY_DECODER_CMD - Execute an decoder command
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_decoder_cmd *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_DECODER_CMD, VIDIOC_TRY_DECODER_CMD
+
+``argp``
+
+
+Description
+===========
+
+These ioctls control an audio/video (usually MPEG-) decoder.
+``VIDIOC_DECODER_CMD`` sends a command to the decoder,
+``VIDIOC_TRY_DECODER_CMD`` can be used to try a command without actually
+executing it. To send a command applications must initialize all fields
+of a struct :ref:`v4l2_decoder_cmd <v4l2-decoder-cmd>` and call
+``VIDIOC_DECODER_CMD`` or ``VIDIOC_TRY_DECODER_CMD`` with a pointer to
+this structure.
+
+The ``cmd`` field must contain the command code. Some commands use the
+``flags`` field for additional information.
+
+A :ref:`write() <func-write>` or :ref:`VIDIOC_STREAMON`
+call sends an implicit START command to the decoder if it has not been
+started yet.
+
+A :ref:`close() <func-close>` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`
+call of a streaming file descriptor sends an implicit immediate STOP
+command to the decoder, and all buffered data is discarded.
+
+These ioctls are optional, not all drivers may support them. They were
+introduced in Linux 3.3.
+
+
+.. _v4l2-decoder-cmd:
+
+.. flat-table:: struct v4l2_decoder_cmd
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2 1 1
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``cmd``
+
+ -
+ -
+ - The decoder command, see :ref:`decoder-cmds`.
+
+ - .. row 2
+
+ - __u32
+
+ - ``flags``
+
+ -
+ -
+ - Flags to go with the command. If no flags are defined for this
+ command, drivers and applications must set this field to zero.
+
+ - .. row 3
+
+ - union
+
+ - (anonymous)
+
+ -
+ -
+ -
+
+ - .. row 4
+
+ -
+ - struct
+
+ - ``start``
+
+ -
+ - Structure containing additional data for the
+ ``V4L2_DEC_CMD_START`` command.
+
+ - .. row 5
+
+ -
+ -
+ - __s32
+
+ - ``speed``
+
+ - Playback speed and direction. The playback speed is defined as
+ ``speed``/1000 of the normal speed. So 1000 is normal playback.
+ Negative numbers denote reverse playback, so -1000 does reverse
+ playback at normal speed. Speeds -1, 0 and 1 have special
+ meanings: speed 0 is shorthand for 1000 (normal playback). A speed
+ of 1 steps just one frame forward, a speed of -1 steps just one
+ frame back.
+
+ - .. row 6
+
+ -
+ -
+ - __u32
+
+ - ``format``
+
+ - Format restrictions. This field is set by the driver, not the
+ application. Possible values are ``V4L2_DEC_START_FMT_NONE`` if
+ there are no format restrictions or ``V4L2_DEC_START_FMT_GOP`` if
+ the decoder operates on full GOPs (*Group Of Pictures*). This is
+ usually the case for reverse playback: the decoder needs full
+ GOPs, which it can then play in reverse order. So to implement
+ reverse playback the application must feed the decoder the last
+ GOP in the video file, then the GOP before that, etc. etc.
+
+ - .. row 7
+
+ -
+ - struct
+
+ - ``stop``
+
+ -
+ - Structure containing additional data for the ``V4L2_DEC_CMD_STOP``
+ command.
+
+ - .. row 8
+
+ -
+ -
+ - __u64
+
+ - ``pts``
+
+ - Stop playback at this ``pts`` or immediately if the playback is
+ already past that timestamp. Leave to 0 if you want to stop after
+ the last frame was decoded.
+
+ - .. row 9
+
+ -
+ - struct
+
+ - ``raw``
+
+ -
+ -
+
+ - .. row 10
+
+ -
+ -
+ - __u32
+
+ - ``data``\ [16]
+
+ - Reserved for future extensions. Drivers and applications must set
+ the array to zero.
+
+
+
+.. _decoder-cmds:
+
+.. flat-table:: Decoder Commands
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_DEC_CMD_START``
+
+ - 0
+
+ - Start the decoder. When the decoder is already running or paused,
+ this command will just change the playback speed. That means that
+ calling ``V4L2_DEC_CMD_START`` when the decoder was paused will
+ *not* resume the decoder. You have to explicitly call
+ ``V4L2_DEC_CMD_RESUME`` for that. This command has one flag:
+ ``V4L2_DEC_CMD_START_MUTE_AUDIO``. If set, then audio will be
+ muted when playing back at a non-standard speed.
+
+ - .. row 2
+
+ - ``V4L2_DEC_CMD_STOP``
+
+ - 1
+
+ - Stop the decoder. When the decoder is already stopped, this
+ command does nothing. This command has two flags: if
+ ``V4L2_DEC_CMD_STOP_TO_BLACK`` is set, then the decoder will set
+ the picture to black after it stopped decoding. Otherwise the last
+ image will repeat. mem2mem decoders will stop producing new frames
+ altogether. They will send a ``V4L2_EVENT_EOS`` event when the
+ last frame has been decoded and all frames are ready to be
+ dequeued and will set the ``V4L2_BUF_FLAG_LAST`` buffer flag on
+ the last buffer of the capture queue to indicate there will be no
+ new buffers produced to dequeue. This buffer may be empty,
+ indicated by the driver setting the ``bytesused`` field to 0. Once
+ the ``V4L2_BUF_FLAG_LAST`` flag was set, the
+ :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will not block anymore,
+ but return an ``EPIPE`` error code. If
+ ``V4L2_DEC_CMD_STOP_IMMEDIATELY`` is set, then the decoder stops
+ immediately (ignoring the ``pts`` value), otherwise it will keep
+ decoding until timestamp >= pts or until the last of the pending
+ data from its internal buffers was decoded.
+
+ - .. row 3
+
+ - ``V4L2_DEC_CMD_PAUSE``
+
+ - 2
+
+ - Pause the decoder. When the decoder has not been started yet, the
+ driver will return an ``EPERM`` error code. When the decoder is
+ already paused, this command does nothing. This command has one
+ flag: if ``V4L2_DEC_CMD_PAUSE_TO_BLACK`` is set, then set the
+ decoder output to black when paused.
+
+ - .. row 4
+
+ - ``V4L2_DEC_CMD_RESUME``
+
+ - 3
+
+ - Resume decoding after a PAUSE command. When the decoder has not
+ been started yet, the driver will return an ``EPERM`` error code. When
+ the decoder is already running, this command does nothing. No
+ flags are defined for this command.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The ``cmd`` field is invalid.
+
+EPERM
+ The application sent a PAUSE or RESUME command when the decoder was
+ not running.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_DQEVENT:
+
+********************
+ioctl VIDIOC_DQEVENT
+********************
+
+Name
+====
+
+VIDIOC_DQEVENT - Dequeue event
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_event *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_DQEVENT
+
+``argp``
+
+
+Description
+===========
+
+Dequeue an event from a video device. No input is required for this
+ioctl. All the fields of the struct :ref:`v4l2_event <v4l2-event>`
+structure are filled by the driver. The file handle will also receive
+exceptions which the application may get by e.g. using the select system
+call.
+
+
+.. _v4l2-event:
+
+.. flat-table:: struct v4l2_event
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2 1
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``type``
+
+ -
+ - Type of the event, see :ref:`event-type`.
+
+ - .. row 2
+
+ - union
+
+ - ``u``
+
+ -
+ -
+
+ - .. row 3
+
+ -
+ - struct :ref:`v4l2_event_vsync <v4l2-event-vsync>`
+
+ - ``vsync``
+
+ - Event data for event ``V4L2_EVENT_VSYNC``.
+
+ - .. row 4
+
+ -
+ - struct :ref:`v4l2_event_ctrl <v4l2-event-ctrl>`
+
+ - ``ctrl``
+
+ - Event data for event ``V4L2_EVENT_CTRL``.
+
+ - .. row 5
+
+ -
+ - struct :ref:`v4l2_event_frame_sync <v4l2-event-frame-sync>`
+
+ - ``frame_sync``
+
+ - Event data for event ``V4L2_EVENT_FRAME_SYNC``.
+
+ - .. row 6
+
+ -
+ - struct :ref:`v4l2_event_motion_det <v4l2-event-motion-det>`
+
+ - ``motion_det``
+
+ - Event data for event V4L2_EVENT_MOTION_DET.
+
+ - .. row 7
+
+ -
+ - struct :ref:`v4l2_event_src_change <v4l2-event-src-change>`
+
+ - ``src_change``
+
+ - Event data for event V4L2_EVENT_SOURCE_CHANGE.
+
+ - .. row 8
+
+ -
+ - __u8
+
+ - ``data``\ [64]
+
+ - Event data. Defined by the event type. The union should be used to
+ define easily accessible type for events.
+
+ - .. row 9
+
+ - __u32
+
+ - ``pending``
+
+ -
+ - Number of pending events excluding this one.
+
+ - .. row 10
+
+ - __u32
+
+ - ``sequence``
+
+ -
+ - Event sequence number. The sequence number is incremented for
+ every subscribed event that takes place. If sequence numbers are
+ not contiguous it means that events have been lost.
+
+ - .. row 11
+
+ - struct timespec
+
+ - ``timestamp``
+
+ -
+ - Event timestamp. The timestamp has been taken from the
+ ``CLOCK_MONOTONIC`` clock. To access the same clock outside V4L2,
+ use :c:func:`clock_gettime(2)`.
+
+ - .. row 12
+
+ - u32
+
+ - ``id``
+
+ -
+ - The ID associated with the event source. If the event does not
+ have an associated ID (this depends on the event type), then this
+ is 0.
+
+ - .. row 13
+
+ - __u32
+
+ - ``reserved``\ [8]
+
+ -
+ - Reserved for future extensions. Drivers must set the array to
+ zero.
+
+
+
+.. _event-type:
+
+.. flat-table:: Event Types
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_EVENT_ALL``
+
+ - 0
+
+ - All events. V4L2_EVENT_ALL is valid only for
+ VIDIOC_UNSUBSCRIBE_EVENT for unsubscribing all events at once.
+
+ - .. row 2
+
+ - ``V4L2_EVENT_VSYNC``
+
+ - 1
+
+ - This event is triggered on the vertical sync. This event has a
+ struct :ref:`v4l2_event_vsync <v4l2-event-vsync>` associated
+ with it.
+
+ - .. row 3
+
+ - ``V4L2_EVENT_EOS``
+
+ - 2
+
+ - This event is triggered when the end of a stream is reached. This
+ is typically used with MPEG decoders to report to the application
+ when the last of the MPEG stream has been decoded.
+
+ - .. row 4
+
+ - ``V4L2_EVENT_CTRL``
+
+ - 3
+
+ - This event requires that the ``id`` matches the control ID from
+ which you want to receive events. This event is triggered if the
+ control's value changes, if a button control is pressed or if the
+ control's flags change. This event has a struct
+ :ref:`v4l2_event_ctrl <v4l2-event-ctrl>` associated with it.
+ This struct contains much of the same information as struct
+ :ref:`v4l2_queryctrl <v4l2-queryctrl>` and struct
+ :ref:`v4l2_control <v4l2-control>`.
+
+ If the event is generated due to a call to
+ :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` or
+ :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`, then the
+ event will *not* be sent to the file handle that called the ioctl
+ function. This prevents nasty feedback loops. If you *do* want to
+ get the event, then set the ``V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK``
+ flag.
+
+ This event type will ensure that no information is lost when more
+ events are raised than there is room internally. In that case the
+ struct :ref:`v4l2_event_ctrl <v4l2-event-ctrl>` of the
+ second-oldest event is kept, but the ``changes`` field of the
+ second-oldest event is ORed with the ``changes`` field of the
+ oldest event.
+
+ - .. row 5
+
+ - ``V4L2_EVENT_FRAME_SYNC``
+
+ - 4
+
+ - Triggered immediately when the reception of a frame has begun.
+ This event has a struct
+ :ref:`v4l2_event_frame_sync <v4l2-event-frame-sync>`
+ associated with it.
+
+ If the hardware needs to be stopped in the case of a buffer
+ underrun it might not be able to generate this event. In such
+ cases the ``frame_sequence`` field in struct
+ :ref:`v4l2_event_frame_sync <v4l2-event-frame-sync>` will not
+ be incremented. This causes two consecutive frame sequence numbers
+ to have n times frame interval in between them.
+
+ - .. row 6
+
+ - ``V4L2_EVENT_SOURCE_CHANGE``
+
+ - 5
+
+ - This event is triggered when a source parameter change is detected
+ during runtime by the video device. It can be a runtime resolution
+ change triggered by a video decoder or the format change happening
+ on an input connector. This event requires that the ``id`` matches
+ the input index (when used with a video device node) or the pad
+ index (when used with a subdevice node) from which you want to
+ receive events.
+
+ This event has a struct
+ :ref:`v4l2_event_src_change <v4l2-event-src-change>`
+ associated with it. The ``changes`` bitfield denotes what has
+ changed for the subscribed pad. If multiple events occurred before
+ application could dequeue them, then the changes will have the
+ ORed value of all the events generated.
+
+ - .. row 7
+
+ - ``V4L2_EVENT_MOTION_DET``
+
+ - 6
+
+ - Triggered whenever the motion detection state for one or more of
+ the regions changes. This event has a struct
+ :ref:`v4l2_event_motion_det <v4l2-event-motion-det>`
+ associated with it.
+
+ - .. row 8
+
+ - ``V4L2_EVENT_PRIVATE_START``
+
+ - 0x08000000
+
+ - Base event number for driver-private events.
+
+
+
+.. _v4l2-event-vsync:
+
+.. flat-table:: struct v4l2_event_vsync
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u8
+
+ - ``field``
+
+ - The upcoming field. See enum :ref:`v4l2_field <v4l2-field>`.
+
+
+
+.. _v4l2-event-ctrl:
+
+.. flat-table:: struct v4l2_event_ctrl
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2 1
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``changes``
+
+ -
+ - A bitmask that tells what has changed. See
+ :ref:`ctrl-changes-flags`.
+
+ - .. row 2
+
+ - __u32
+
+ - ``type``
+
+ -
+ - The type of the control. See enum
+ :ref:`v4l2_ctrl_type <v4l2-ctrl-type>`.
+
+ - .. row 3
+
+ - union (anonymous)
+
+ -
+ -
+ -
+
+ - .. row 4
+
+ -
+ - __s32
+
+ - ``value``
+
+ - The 32-bit value of the control for 32-bit control types. This is
+ 0 for string controls since the value of a string cannot be passed
+ using :ref:`VIDIOC_DQEVENT`.
+
+ - .. row 5
+
+ -
+ - __s64
+
+ - ``value64``
+
+ - The 64-bit value of the control for 64-bit control types.
+
+ - .. row 6
+
+ - __u32
+
+ - ``flags``
+
+ -
+ - The control flags. See :ref:`control-flags`.
+
+ - .. row 7
+
+ - __s32
+
+ - ``minimum``
+
+ -
+ - The minimum value of the control. See struct
+ :ref:`v4l2_queryctrl <v4l2-queryctrl>`.
+
+ - .. row 8
+
+ - __s32
+
+ - ``maximum``
+
+ -
+ - The maximum value of the control. See struct
+ :ref:`v4l2_queryctrl <v4l2-queryctrl>`.
+
+ - .. row 9
+
+ - __s32
+
+ - ``step``
+
+ -
+ - The step value of the control. See struct
+ :ref:`v4l2_queryctrl <v4l2-queryctrl>`.
+
+ - .. row 10
+
+ - __s32
+
+ - ``default_value``
+
+ -
+ - The default value value of the control. See struct
+ :ref:`v4l2_queryctrl <v4l2-queryctrl>`.
+
+
+
+.. _v4l2-event-frame-sync:
+
+.. flat-table:: struct v4l2_event_frame_sync
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``frame_sequence``
+
+ - The sequence number of the frame being received.
+
+
+
+.. _v4l2-event-src-change:
+
+.. flat-table:: struct v4l2_event_src_change
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``changes``
+
+ - A bitmask that tells what has changed. See
+ :ref:`src-changes-flags`.
+
+
+
+.. _v4l2-event-motion-det:
+
+.. flat-table:: struct v4l2_event_motion_det
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``flags``
+
+ - Currently only one flag is available: if
+ ``V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ`` is set, then the
+ ``frame_sequence`` field is valid, otherwise that field should be
+ ignored.
+
+ - .. row 2
+
+ - __u32
+
+ - ``frame_sequence``
+
+ - The sequence number of the frame being received. Only valid if the
+ ``V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ`` flag was set.
+
+ - .. row 3
+
+ - __u32
+
+ - ``region_mask``
+
+ - The bitmask of the regions that reported motion. There is at least
+ one region. If this field is 0, then no motion was detected at
+ all. If there is no ``V4L2_CID_DETECT_MD_REGION_GRID`` control
+ (see :ref:`detect-controls`) to assign a different region to
+ each cell in the motion detection grid, then that all cells are
+ automatically assigned to the default region 0.
+
+
+
+.. _ctrl-changes-flags:
+
+.. flat-table:: Control Changes
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_EVENT_CTRL_CH_VALUE``
+
+ - 0x0001
+
+ - This control event was triggered because the value of the control
+ changed. Special cases: Volatile controls do no generate this
+ event; If a control has the ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE``
+ flag set, then this event is sent as well, regardless its value.
+
+ - .. row 2
+
+ - ``V4L2_EVENT_CTRL_CH_FLAGS``
+
+ - 0x0002
+
+ - This control event was triggered because the control flags
+ changed.
+
+ - .. row 3
+
+ - ``V4L2_EVENT_CTRL_CH_RANGE``
+
+ - 0x0004
+
+ - This control event was triggered because the minimum, maximum,
+ step or the default value of the control changed.
+
+
+
+.. _src-changes-flags:
+
+.. flat-table:: Source Changes
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_EVENT_SRC_CH_RESOLUTION``
+
+ - 0x0001
+
+ - This event gets triggered when a resolution change is detected at
+ an input. This can come from an input connector or from a video
+ decoder.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_DV_TIMINGS_CAP:
+
+*********************************************************
+ioctl VIDIOC_DV_TIMINGS_CAP, VIDIOC_SUBDEV_DV_TIMINGS_CAP
+*********************************************************
+
+Name
+====
+
+VIDIOC_DV_TIMINGS_CAP - VIDIOC_SUBDEV_DV_TIMINGS_CAP - The capabilities of the Digital Video receiver/transmitter
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_dv_timings_cap *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_DV_TIMINGS_CAP, VIDIOC_SUBDEV_DV_TIMINGS_CAP
+
+``argp``
+
+
+Description
+===========
+
+To query the capabilities of the DV receiver/transmitter applications
+initialize the ``pad`` field to 0, zero the reserved array of struct
+:ref:`v4l2_dv_timings_cap <v4l2-dv-timings-cap>` and call the
+``VIDIOC_DV_TIMINGS_CAP`` ioctl on a video node and the driver will fill
+in the structure. Note that drivers may return different values after
+switching the video input or output.
+
+When implemented by the driver DV capabilities of subdevices can be
+queried by calling the ``VIDIOC_SUBDEV_DV_TIMINGS_CAP`` ioctl directly
+on a subdevice node. The capabilities are specific to inputs (for DV
+receivers) or outputs (for DV transmitters), applications must specify
+the desired pad number in the struct
+:ref:`v4l2_dv_timings_cap <v4l2-dv-timings-cap>` ``pad`` field and
+zero the ``reserved`` array. Attempts to query capabilities on a pad
+that doesn't support them will return an ``EINVAL`` error code.
+
+
+.. _v4l2-bt-timings-cap:
+
+.. flat-table:: struct v4l2_bt_timings_cap
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``min_width``
+
+ - Minimum width of the active video in pixels.
+
+ - .. row 2
+
+ - __u32
+
+ - ``max_width``
+
+ - Maximum width of the active video in pixels.
+
+ - .. row 3
+
+ - __u32
+
+ - ``min_height``
+
+ - Minimum height of the active video in lines.
+
+ - .. row 4
+
+ - __u32
+
+ - ``max_height``
+
+ - Maximum height of the active video in lines.
+
+ - .. row 5
+
+ - __u64
+
+ - ``min_pixelclock``
+
+ - Minimum pixelclock frequency in Hz.
+
+ - .. row 6
+
+ - __u64
+
+ - ``max_pixelclock``
+
+ - Maximum pixelclock frequency in Hz.
+
+ - .. row 7
+
+ - __u32
+
+ - ``standards``
+
+ - The video standard(s) supported by the hardware. See
+ :ref:`dv-bt-standards` for a list of standards.
+
+ - .. row 8
+
+ - __u32
+
+ - ``capabilities``
+
+ - Several flags giving more information about the capabilities. See
+ :ref:`dv-bt-cap-capabilities` for a description of the flags.
+
+ - .. row 9
+
+ - __u32
+
+ - ``reserved``\ [16]
+
+ - Reserved for future extensions. Drivers must set the array to
+ zero.
+
+
+
+.. _v4l2-dv-timings-cap:
+
+.. flat-table:: struct v4l2_dv_timings_cap
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2 1
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``type``
+
+ - Type of DV timings as listed in :ref:`dv-timing-types`.
+
+ - .. row 2
+
+ - __u32
+
+ - ``pad``
+
+ - Pad number as reported by the media controller API. This field is
+ only used when operating on a subdevice node. When operating on a
+ video node applications must set this field to zero.
+
+ - .. row 3
+
+ - __u32
+
+ - ``reserved``\ [2]
+
+ - Reserved for future extensions. Drivers and applications must set
+ the array to zero.
+
+ - .. row 4
+
+ - union
+
+ -
+ -
+
+ - .. row 5
+
+ -
+ - struct :ref:`v4l2_bt_timings_cap <v4l2-bt-timings-cap>`
+
+ - ``bt``
+
+ - BT.656/1120 timings capabilities of the hardware.
+
+ - .. row 6
+
+ -
+ - __u32
+
+ - ``raw_data``\ [32]
+
+ -
+
+
+
+.. _dv-bt-cap-capabilities:
+
+.. flat-table:: DV BT Timing capabilities
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Flag
+
+ - Description
+
+ - .. row 2
+
+ -
+ -
+
+ - .. row 3
+
+ - ``V4L2_DV_BT_CAP_INTERLACED``
+
+ - Interlaced formats are supported.
+
+ - .. row 4
+
+ - ``V4L2_DV_BT_CAP_PROGRESSIVE``
+
+ - Progressive formats are supported.
+
+ - .. row 5
+
+ - ``V4L2_DV_BT_CAP_REDUCED_BLANKING``
+
+ - CVT/GTF specific: the timings can make use of reduced blanking
+ (CVT) or the 'Secondary GTF' curve (GTF).
+
+ - .. row 6
+
+ - ``V4L2_DV_BT_CAP_CUSTOM``
+
+ - Can support non-standard timings, i.e. timings not belonging to
+ the standards set in the ``standards`` field.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_ENCODER_CMD:
+
+************************************************
+ioctl VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD
+************************************************
+
+Name
+====
+
+VIDIOC_ENCODER_CMD - VIDIOC_TRY_ENCODER_CMD - Execute an encoder command
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_encoder_cmd *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD
+
+``argp``
+
+
+Description
+===========
+
+These ioctls control an audio/video (usually MPEG-) encoder.
+``VIDIOC_ENCODER_CMD`` sends a command to the encoder,
+``VIDIOC_TRY_ENCODER_CMD`` can be used to try a command without actually
+executing it.
+
+To send a command applications must initialize all fields of a struct
+:ref:`v4l2_encoder_cmd <v4l2-encoder-cmd>` and call
+``VIDIOC_ENCODER_CMD`` or ``VIDIOC_TRY_ENCODER_CMD`` with a pointer to
+this structure.
+
+The ``cmd`` field must contain the command code. The ``flags`` field is
+currently only used by the STOP command and contains one bit: If the
+``V4L2_ENC_CMD_STOP_AT_GOP_END`` flag is set, encoding will continue
+until the end of the current *Group Of Pictures*, otherwise it will stop
+immediately.
+
+A :ref:`read() <func-read>` or :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`
+call sends an implicit START command to the encoder if it has not been
+started yet. After a STOP command, :ref:`read() <func-read>` calls will read
+the remaining data buffered by the driver. When the buffer is empty,
+:ref:`read() <func-read>` will return zero and the next :ref:`read() <func-read>`
+call will restart the encoder.
+
+A :ref:`close() <func-close>` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`
+call of a streaming file descriptor sends an implicit immediate STOP to
+the encoder, and all buffered data is discarded.
+
+These ioctls are optional, not all drivers may support them. They were
+introduced in Linux 2.6.21.
+
+
+.. _v4l2-encoder-cmd:
+
+.. flat-table:: struct v4l2_encoder_cmd
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``cmd``
+
+ - The encoder command, see :ref:`encoder-cmds`.
+
+ - .. row 2
+
+ - __u32
+
+ - ``flags``
+
+ - Flags to go with the command, see :ref:`encoder-flags`. If no
+ flags are defined for this command, drivers and applications must
+ set this field to zero.
+
+ - .. row 3
+
+ - __u32
+
+ - ``data``\ [8]
+
+ - Reserved for future extensions. Drivers and applications must set
+ the array to zero.
+
+
+
+.. _encoder-cmds:
+
+.. flat-table:: Encoder Commands
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_ENC_CMD_START``
+
+ - 0
+
+ - Start the encoder. When the encoder is already running or paused,
+ this command does nothing. No flags are defined for this command.
+
+ - .. row 2
+
+ - ``V4L2_ENC_CMD_STOP``
+
+ - 1
+
+ - Stop the encoder. When the ``V4L2_ENC_CMD_STOP_AT_GOP_END`` flag
+ is set, encoding will continue until the end of the current *Group
+ Of Pictures*, otherwise encoding will stop immediately. When the
+ encoder is already stopped, this command does nothing. mem2mem
+ encoders will send a ``V4L2_EVENT_EOS`` event when the last frame
+ has been encoded and all frames are ready to be dequeued and will
+ set the ``V4L2_BUF_FLAG_LAST`` buffer flag on the last buffer of
+ the capture queue to indicate there will be no new buffers
+ produced to dequeue. This buffer may be empty, indicated by the
+ driver setting the ``bytesused`` field to 0. Once the
+ ``V4L2_BUF_FLAG_LAST`` flag was set, the
+ :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will not block anymore,
+ but return an ``EPIPE`` error code.
+
+ - .. row 3
+
+ - ``V4L2_ENC_CMD_PAUSE``
+
+ - 2
+
+ - Pause the encoder. When the encoder has not been started yet, the
+ driver will return an ``EPERM`` error code. When the encoder is
+ already paused, this command does nothing. No flags are defined
+ for this command.
+
+ - .. row 4
+
+ - ``V4L2_ENC_CMD_RESUME``
+
+ - 3
+
+ - Resume encoding after a PAUSE command. When the encoder has not
+ been started yet, the driver will return an ``EPERM`` error code. When
+ the encoder is already running, this command does nothing. No
+ flags are defined for this command.
+
+
+
+.. _encoder-flags:
+
+.. flat-table:: Encoder Command Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_ENC_CMD_STOP_AT_GOP_END``
+
+ - 0x0001
+
+ - Stop encoding at the end of the current *Group Of Pictures*,
+ rather than immediately.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The ``cmd`` field is invalid.
+
+EPERM
+ The application sent a PAUSE or RESUME command when the encoder was
+ not running.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_ENUM_DV_TIMINGS:
+
+***********************************************************
+ioctl VIDIOC_ENUM_DV_TIMINGS, VIDIOC_SUBDEV_ENUM_DV_TIMINGS
+***********************************************************
+
+Name
+====
+
+VIDIOC_ENUM_DV_TIMINGS - VIDIOC_SUBDEV_ENUM_DV_TIMINGS - Enumerate supported Digital Video timings
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_enum_dv_timings *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_ENUM_DV_TIMINGS, VIDIOC_SUBDEV_ENUM_DV_TIMINGS
+
+``argp``
+
+
+Description
+===========
+
+While some DV receivers or transmitters support a wide range of timings,
+others support only a limited number of timings. With this ioctl
+applications can enumerate a list of known supported timings. Call
+:ref:`VIDIOC_DV_TIMINGS_CAP` to check if it
+also supports other standards or even custom timings that are not in
+this list.
+
+To query the available timings, applications initialize the ``index``
+field, set the ``pad`` field to 0, zero the reserved array of struct
+:ref:`v4l2_enum_dv_timings <v4l2-enum-dv-timings>` and call the
+``VIDIOC_ENUM_DV_TIMINGS`` ioctl on a video node with a pointer to this
+structure. Drivers fill the rest of the structure or return an ``EINVAL``
+error code when the index is out of bounds. To enumerate all supported
+DV timings, applications shall begin at index zero, incrementing by one
+until the driver returns ``EINVAL``. Note that drivers may enumerate a
+different set of DV timings after switching the video input or output.
+
+When implemented by the driver DV timings of subdevices can be queried
+by calling the ``VIDIOC_SUBDEV_ENUM_DV_TIMINGS`` ioctl directly on a
+subdevice node. The DV timings are specific to inputs (for DV receivers)
+or outputs (for DV transmitters), applications must specify the desired
+pad number in the struct
+:ref:`v4l2_enum_dv_timings <v4l2-enum-dv-timings>` ``pad`` field.
+Attempts to enumerate timings on a pad that doesn't support them will
+return an ``EINVAL`` error code.
+
+
+.. _v4l2-enum-dv-timings:
+
+.. flat-table:: struct v4l2_enum_dv_timings
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``index``
+
+ - Number of the DV timings, set by the application.
+
+ - .. row 2
+
+ - __u32
+
+ - ``pad``
+
+ - Pad number as reported by the media controller API. This field is
+ only used when operating on a subdevice node. When operating on a
+ video node applications must set this field to zero.
+
+ - .. row 3
+
+ - __u32
+
+ - ``reserved``\ [2]
+
+ - Reserved for future extensions. Drivers and applications must set
+ the array to zero.
+
+ - .. row 4
+
+ - struct :ref:`v4l2_dv_timings <v4l2-dv-timings>`
+
+ - ``timings``
+
+ - The timings.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The struct :ref:`v4l2_enum_dv_timings <v4l2-enum-dv-timings>`
+ ``index`` is out of bounds or the ``pad`` number is invalid.
+
+ENODATA
+ Digital video presets are not supported for this input or output.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_ENUM_FMT:
+
+*********************
+ioctl VIDIOC_ENUM_FMT
+*********************
+
+Name
+====
+
+VIDIOC_ENUM_FMT - Enumerate image formats
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_fmtdesc *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_ENUM_FMT
+
+``argp``
+
+
+Description
+===========
+
+To enumerate image formats applications initialize the ``type`` and
+``index`` field of struct :ref:`v4l2_fmtdesc <v4l2-fmtdesc>` and call
+the :ref:`VIDIOC_ENUM_FMT` ioctl with a pointer to this structure. Drivers
+fill the rest of the structure or return an ``EINVAL`` error code. All
+formats are enumerable by beginning at index zero and incrementing by
+one until ``EINVAL`` is returned.
+
+Note that after switching input or output the list of enumerated image
+formats may be different.
+
+
+.. _v4l2-fmtdesc:
+
+.. flat-table:: struct v4l2_fmtdesc
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``index``
+
+ - Number of the format in the enumeration, set by the application.
+ This is in no way related to the ``pixelformat`` field.
+
+ - .. row 2
+
+ - __u32
+
+ - ``type``
+
+ - Type of the data stream, set by the application. Only these types
+ are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``,
+ ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``,
+ ``V4L2_BUF_TYPE_VIDEO_OUTPUT``,
+ ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE`` and
+ ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :ref:`v4l2-buf-type`.
+
+ - .. row 3
+
+ - __u32
+
+ - ``flags``
+
+ - See :ref:`fmtdesc-flags`
+
+ - .. row 4
+
+ - __u8
+
+ - ``description``\ [32]
+
+ - Description of the format, a NUL-terminated ASCII string. This
+ information is intended for the user, for example: "YUV 4:2:2".
+
+ - .. row 5
+
+ - __u32
+
+ - ``pixelformat``
+
+ - The image format identifier. This is a four character code as
+ computed by the v4l2_fourcc() macro:
+
+ - .. row 6
+
+ - :cspan:`2`
+
+
+ .. _v4l2-fourcc:
+ .. code-block:: c
+
+ #define v4l2_fourcc(a,b,c,d) (((__u32)(a)<<0)|((__u32)(b)<<8)|((__u32)(c)<<16)|((__u32)(d)<<24))
+
+ Several image formats are already defined by this specification in
+ :ref:`pixfmt`. Note these codes are not the same as those used
+ in the Windows world.
+
+ - .. row 7
+
+ - __u32
+
+ - ``reserved``\ [4]
+
+ - Reserved for future extensions. Drivers must set the array to
+ zero.
+
+
+
+.. _fmtdesc-flags:
+
+.. flat-table:: Image Format Description Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_FMT_FLAG_COMPRESSED``
+
+ - 0x0001
+
+ - This is a compressed format.
+
+ - .. row 2
+
+ - ``V4L2_FMT_FLAG_EMULATED``
+
+ - 0x0002
+
+ - This format is not native to the device but emulated through
+ software (usually libv4l2), where possible try to use a native
+ format instead for better performance.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The struct :ref:`v4l2_fmtdesc <v4l2-fmtdesc>` ``type`` is not
+ supported or the ``index`` is out of bounds.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_ENUM_FRAMEINTERVALS:
+
+********************************
+ioctl VIDIOC_ENUM_FRAMEINTERVALS
+********************************
+
+Name
+====
+
+VIDIOC_ENUM_FRAMEINTERVALS - Enumerate frame intervals
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_frmivalenum *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_ENUM_FRAMEINTERVALS
+
+``argp``
+ Pointer to a struct :ref:`v4l2_frmivalenum <v4l2-frmivalenum>`
+ structure that contains a pixel format and size and receives a frame
+ interval.
+
+
+Description
+===========
+
+This ioctl allows applications to enumerate all frame intervals that the
+device supports for the given pixel format and frame size.
+
+The supported pixel formats and frame sizes can be obtained by using the
+:ref:`VIDIOC_ENUM_FMT` and
+:ref:`VIDIOC_ENUM_FRAMESIZES` functions.
+
+The return value and the content of the ``v4l2_frmivalenum.type`` field
+depend on the type of frame intervals the device supports. Here are the
+semantics of the function for the different cases:
+
+- **Discrete:** The function returns success if the given index value
+ (zero-based) is valid. The application should increase the index by
+ one for each call until ``EINVAL`` is returned. The
+ `v4l2_frmivalenum.type` field is set to
+ `V4L2_FRMIVAL_TYPE_DISCRETE` by the driver. Of the union only
+ the `discrete` member is valid.
+
+- **Step-wise:** The function returns success if the given index value
+ is zero and ``EINVAL`` for any other index value. The
+ ``v4l2_frmivalenum.type`` field is set to
+ ``V4L2_FRMIVAL_TYPE_STEPWISE`` by the driver. Of the union only the
+ ``stepwise`` member is valid.
+
+- **Continuous:** This is a special case of the step-wise type above.
+ The function returns success if the given index value is zero and
+ ``EINVAL`` for any other index value. The ``v4l2_frmivalenum.type``
+ field is set to ``V4L2_FRMIVAL_TYPE_CONTINUOUS`` by the driver. Of
+ the union only the ``stepwise`` member is valid and the ``step``
+ value is set to 1.
+
+When the application calls the function with index zero, it must check
+the ``type`` field to determine the type of frame interval enumeration
+the device supports. Only for the ``V4L2_FRMIVAL_TYPE_DISCRETE`` type
+does it make sense to increase the index value to receive more frame
+intervals.
+
+Note that the order in which the frame intervals are returned has no
+special meaning. In particular does it not say anything about potential
+default frame intervals.
+
+Applications can assume that the enumeration data does not change
+without any interaction from the application itself. This means that the
+enumeration data is consistent if the application does not perform any
+other ioctl calls while it runs the frame interval enumeration.
+
+
+Notes
+=====
+
+- **Frame intervals and frame rates:** The V4L2 API uses frame
+ intervals instead of frame rates. Given the frame interval the frame
+ rate can be computed as follows:
+
+
+
+ ::
+
+ frame_rate = 1 / frame_interval
+
+
+Structs
+=======
+
+In the structs below, *IN* denotes a value that has to be filled in by
+the application, *OUT* denotes values that the driver fills in. The
+application should zero out all members except for the *IN* fields.
+
+
+.. _v4l2-frmival-stepwise:
+
+.. flat-table:: struct v4l2_frmival_stepwise
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - struct :ref:`v4l2_fract <v4l2-fract>`
+
+ - ``min``
+
+ - Minimum frame interval [s].
+
+ - .. row 2
+
+ - struct :ref:`v4l2_fract <v4l2-fract>`
+
+ - ``max``
+
+ - Maximum frame interval [s].
+
+ - .. row 3
+
+ - struct :ref:`v4l2_fract <v4l2-fract>`
+
+ - ``step``
+
+ - Frame interval step size [s].
+
+
+
+.. _v4l2-frmivalenum:
+
+.. flat-table:: struct v4l2_frmivalenum
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``index``
+
+ -
+ - IN: Index of the given frame interval in the enumeration.
+
+ - .. row 2
+
+ - __u32
+
+ - ``pixel_format``
+
+ -
+ - IN: Pixel format for which the frame intervals are enumerated.
+
+ - .. row 3
+
+ - __u32
+
+ - ``width``
+
+ -
+ - IN: Frame width for which the frame intervals are enumerated.
+
+ - .. row 4
+
+ - __u32
+
+ - ``height``
+
+ -
+ - IN: Frame height for which the frame intervals are enumerated.
+
+ - .. row 5
+
+ - __u32
+
+ - ``type``
+
+ -
+ - OUT: Frame interval type the device supports.
+
+ - .. row 6
+
+ - union
+
+ -
+ -
+ - OUT: Frame interval with the given index.
+
+ - .. row 7
+
+ -
+ - struct :ref:`v4l2_fract <v4l2-fract>`
+
+ - ``discrete``
+
+ - Frame interval [s].
+
+ - .. row 8
+
+ -
+ - struct :ref:`v4l2_frmival_stepwise <v4l2-frmival-stepwise>`
+
+ - ``stepwise``
+
+ -
+
+ - .. row 9
+
+ - __u32
+
+ - ``reserved[2]``
+
+ -
+ - Reserved space for future use. Must be zeroed by drivers and
+ applications.
+
+
+
+Enums
+=====
+
+
+.. _v4l2-frmivaltypes:
+
+.. flat-table:: enum v4l2_frmivaltypes
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_FRMIVAL_TYPE_DISCRETE``
+
+ - 1
+
+ - Discrete frame interval.
+
+ - .. row 2
+
+ - ``V4L2_FRMIVAL_TYPE_CONTINUOUS``
+
+ - 2
+
+ - Continuous frame interval.
+
+ - .. row 3
+
+ - ``V4L2_FRMIVAL_TYPE_STEPWISE``
+
+ - 3
+
+ - Step-wise defined frame interval.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_ENUM_FRAMESIZES:
+
+****************************
+ioctl VIDIOC_ENUM_FRAMESIZES
+****************************
+
+Name
+====
+
+VIDIOC_ENUM_FRAMESIZES - Enumerate frame sizes
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_frmsizeenum *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_ENUM_FRAMESIZES
+
+``argp``
+ Pointer to a struct :ref:`v4l2_frmsizeenum <v4l2-frmsizeenum>`
+ that contains an index and pixel format and receives a frame width
+ and height.
+
+
+Description
+===========
+
+This ioctl allows applications to enumerate all frame sizes (i. e. width
+and height in pixels) that the device supports for the given pixel
+format.
+
+The supported pixel formats can be obtained by using the
+:ref:`VIDIOC_ENUM_FMT` function.
+
+The return value and the content of the ``v4l2_frmsizeenum.type`` field
+depend on the type of frame sizes the device supports. Here are the
+semantics of the function for the different cases:
+
+- **Discrete:** The function returns success if the given index value
+ (zero-based) is valid. The application should increase the index by
+ one for each call until ``EINVAL`` is returned. The
+ ``v4l2_frmsizeenum.type`` field is set to
+ ``V4L2_FRMSIZE_TYPE_DISCRETE`` by the driver. Of the union only the
+ ``discrete`` member is valid.
+
+- **Step-wise:** The function returns success if the given index value
+ is zero and ``EINVAL`` for any other index value. The
+ ``v4l2_frmsizeenum.type`` field is set to
+ ``V4L2_FRMSIZE_TYPE_STEPWISE`` by the driver. Of the union only the
+ ``stepwise`` member is valid.
+
+- **Continuous:** This is a special case of the step-wise type above.
+ The function returns success if the given index value is zero and
+ ``EINVAL`` for any other index value. The ``v4l2_frmsizeenum.type``
+ field is set to ``V4L2_FRMSIZE_TYPE_CONTINUOUS`` by the driver. Of
+ the union only the ``stepwise`` member is valid and the
+ ``step_width`` and ``step_height`` values are set to 1.
+
+When the application calls the function with index zero, it must check
+the ``type`` field to determine the type of frame size enumeration the
+device supports. Only for the ``V4L2_FRMSIZE_TYPE_DISCRETE`` type does
+it make sense to increase the index value to receive more frame sizes.
+
+Note that the order in which the frame sizes are returned has no special
+meaning. In particular does it not say anything about potential default
+format sizes.
+
+Applications can assume that the enumeration data does not change
+without any interaction from the application itself. This means that the
+enumeration data is consistent if the application does not perform any
+other ioctl calls while it runs the frame size enumeration.
+
+
+Structs
+=======
+
+In the structs below, *IN* denotes a value that has to be filled in by
+the application, *OUT* denotes values that the driver fills in. The
+application should zero out all members except for the *IN* fields.
+
+
+.. _v4l2-frmsize-discrete:
+
+.. flat-table:: struct v4l2_frmsize_discrete
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``width``
+
+ - Width of the frame [pixel].
+
+ - .. row 2
+
+ - __u32
+
+ - ``height``
+
+ - Height of the frame [pixel].
+
+
+
+.. _v4l2-frmsize-stepwise:
+
+.. flat-table:: struct v4l2_frmsize_stepwise
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``min_width``
+
+ - Minimum frame width [pixel].
+
+ - .. row 2
+
+ - __u32
+
+ - ``max_width``
+
+ - Maximum frame width [pixel].
+
+ - .. row 3
+
+ - __u32
+
+ - ``step_width``
+
+ - Frame width step size [pixel].
+
+ - .. row 4
+
+ - __u32
+
+ - ``min_height``
+
+ - Minimum frame height [pixel].
+
+ - .. row 5
+
+ - __u32
+
+ - ``max_height``
+
+ - Maximum frame height [pixel].
+
+ - .. row 6
+
+ - __u32
+
+ - ``step_height``
+
+ - Frame height step size [pixel].
+
+
+
+.. _v4l2-frmsizeenum:
+
+.. flat-table:: struct v4l2_frmsizeenum
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``index``
+
+ -
+ - IN: Index of the given frame size in the enumeration.
+
+ - .. row 2
+
+ - __u32
+
+ - ``pixel_format``
+
+ -
+ - IN: Pixel format for which the frame sizes are enumerated.
+
+ - .. row 3
+
+ - __u32
+
+ - ``type``
+
+ -
+ - OUT: Frame size type the device supports.
+
+ - .. row 4
+
+ - union
+
+ -
+ -
+ - OUT: Frame size with the given index.
+
+ - .. row 5
+
+ -
+ - struct :ref:`v4l2_frmsize_discrete <v4l2-frmsize-discrete>`
+
+ - ``discrete``
+
+ -
+
+ - .. row 6
+
+ -
+ - struct :ref:`v4l2_frmsize_stepwise <v4l2-frmsize-stepwise>`
+
+ - ``stepwise``
+
+ -
+
+ - .. row 7
+
+ - __u32
+
+ - ``reserved[2]``
+
+ -
+ - Reserved space for future use. Must be zeroed by drivers and
+ applications.
+
+
+
+Enums
+=====
+
+
+.. _v4l2-frmsizetypes:
+
+.. flat-table:: enum v4l2_frmsizetypes
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_FRMSIZE_TYPE_DISCRETE``
+
+ - 1
+
+ - Discrete frame size.
+
+ - .. row 2
+
+ - ``V4L2_FRMSIZE_TYPE_CONTINUOUS``
+
+ - 2
+
+ - Continuous frame size.
+
+ - .. row 3
+
+ - ``V4L2_FRMSIZE_TYPE_STEPWISE``
+
+ - 3
+
+ - Step-wise defined frame size.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_ENUM_FREQ_BANDS:
+
+****************************
+ioctl VIDIOC_ENUM_FREQ_BANDS
+****************************
+
+Name
+====
+
+VIDIOC_ENUM_FREQ_BANDS - Enumerate supported frequency bands
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_frequency_band *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_ENUM_FREQ_BANDS
+
+``argp``
+
+
+Description
+===========
+
+Enumerates the frequency bands that a tuner or modulator supports. To do
+this applications initialize the ``tuner``, ``type`` and ``index``
+fields, and zero out the ``reserved`` array of a struct
+:ref:`v4l2_frequency_band <v4l2-frequency-band>` and call the
+:ref:`VIDIOC_ENUM_FREQ_BANDS` ioctl with a pointer to this structure.
+
+This ioctl is supported if the ``V4L2_TUNER_CAP_FREQ_BANDS`` capability
+of the corresponding tuner/modulator is set.
+
+
+.. _v4l2-frequency-band:
+
+.. flat-table:: struct v4l2_frequency_band
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2 1 1
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``tuner``
+
+ - The tuner or modulator index number. This is the same value as in
+ the struct :ref:`v4l2_input <v4l2-input>` ``tuner`` field and
+ the struct :ref:`v4l2_tuner <v4l2-tuner>` ``index`` field, or
+ the struct :ref:`v4l2_output <v4l2-output>` ``modulator`` field
+ and the struct :ref:`v4l2_modulator <v4l2-modulator>` ``index``
+ field.
+
+ - .. row 2
+
+ - __u32
+
+ - ``type``
+
+ - The tuner type. This is the same value as in the struct
+ :ref:`v4l2_tuner <v4l2-tuner>` ``type`` field. The type must be
+ set to ``V4L2_TUNER_RADIO`` for ``/dev/radioX`` device nodes, and
+ to ``V4L2_TUNER_ANALOG_TV`` for all others. Set this field to
+ ``V4L2_TUNER_RADIO`` for modulators (currently only radio
+ modulators are supported). See :ref:`v4l2-tuner-type`
+
+ - .. row 3
+
+ - __u32
+
+ - ``index``
+
+ - Identifies the frequency band, set by the application.
+
+ - .. row 4
+
+ - __u32
+
+ - ``capability``
+
+ - :cspan:`2` The tuner/modulator capability flags for this
+ frequency band, see :ref:`tuner-capability`. The
+ ``V4L2_TUNER_CAP_LOW`` or ``V4L2_TUNER_CAP_1HZ`` capability must
+ be the same for all frequency bands of the selected
+ tuner/modulator. So either all bands have that capability set, or
+ none of them have that capability.
+
+ - .. row 5
+
+ - __u32
+
+ - ``rangelow``
+
+ - :cspan:`2` The lowest tunable frequency in units of 62.5 kHz, or
+ if the ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in units
+ of 62.5 Hz, for this frequency band. A 1 Hz unit is used when the
+ ``capability`` flag ``V4L2_TUNER_CAP_1HZ`` is set.
+
+ - .. row 6
+
+ - __u32
+
+ - ``rangehigh``
+
+ - :cspan:`2` The highest tunable frequency in units of 62.5 kHz,
+ or if the ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in
+ units of 62.5 Hz, for this frequency band. A 1 Hz unit is used
+ when the ``capability`` flag ``V4L2_TUNER_CAP_1HZ`` is set.
+
+ - .. row 7
+
+ - __u32
+
+ - ``modulation``
+
+ - :cspan:`2` The supported modulation systems of this frequency
+ band. See :ref:`band-modulation`. Note that currently only one
+ modulation system per frequency band is supported. More work will
+ need to be done if multiple modulation systems are possible.
+ Contact the linux-media mailing list
+ (`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__)
+ if you need that functionality.
+
+ - .. row 8
+
+ - __u32
+
+ - ``reserved``\ [9]
+
+ - Reserved for future extensions. Applications and drivers must set
+ the array to zero.
+
+
+
+.. _band-modulation:
+
+.. flat-table:: Band Modulation Systems
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_BAND_MODULATION_VSB``
+
+ - 0x02
+
+ - Vestigial Sideband modulation, used for analog TV.
+
+ - .. row 2
+
+ - ``V4L2_BAND_MODULATION_FM``
+
+ - 0x04
+
+ - Frequency Modulation, commonly used for analog radio.
+
+ - .. row 3
+
+ - ``V4L2_BAND_MODULATION_AM``
+
+ - 0x08
+
+ - Amplitude Modulation, commonly used for analog radio.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The ``tuner`` or ``index`` is out of bounds or the ``type`` field is
+ wrong.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_ENUMAUDIO:
+
+**********************
+ioctl VIDIOC_ENUMAUDIO
+**********************
+
+Name
+====
+
+VIDIOC_ENUMAUDIO - Enumerate audio inputs
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_audio *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_ENUMAUDIO
+
+``argp``
+
+
+Description
+===========
+
+To query the attributes of an audio input applications initialize the
+``index`` field and zero out the ``reserved`` array of a struct
+:ref:`v4l2_audio <v4l2-audio>` and call the :ref:`VIDIOC_ENUMAUDIO`
+ioctl with a pointer to this structure. Drivers fill the rest of the
+structure or return an ``EINVAL`` error code when the index is out of
+bounds. To enumerate all audio inputs applications shall begin at index
+zero, incrementing by one until the driver returns ``EINVAL``.
+
+See :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` for a description of struct
+:ref:`v4l2_audio <v4l2-audio>`.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The number of the audio input is out of bounds.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_ENUMAUDOUT:
+
+***********************
+ioctl VIDIOC_ENUMAUDOUT
+***********************
+
+Name
+====
+
+VIDIOC_ENUMAUDOUT - Enumerate audio outputs
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_audioout *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_ENUMAUDOUT
+
+``argp``
+
+
+Description
+===========
+
+To query the attributes of an audio output applications initialize the
+``index`` field and zero out the ``reserved`` array of a struct
+:ref:`v4l2_audioout <v4l2-audioout>` and call the ``VIDIOC_G_AUDOUT``
+ioctl with a pointer to this structure. Drivers fill the rest of the
+structure or return an ``EINVAL`` error code when the index is out of
+bounds. To enumerate all audio outputs applications shall begin at index
+zero, incrementing by one until the driver returns ``EINVAL``.
+
+Note connectors on a TV card to loop back the received audio signal to a
+sound card are not audio outputs in this sense.
+
+See :ref:`VIDIOC_G_AUDIOout <VIDIOC_G_AUDOUT>` for a description of struct
+:ref:`v4l2_audioout <v4l2-audioout>`.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The number of the audio output is out of bounds.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_ENUMINPUT:
+
+**********************
+ioctl VIDIOC_ENUMINPUT
+**********************
+
+Name
+====
+
+VIDIOC_ENUMINPUT - Enumerate video inputs
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_input *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_ENUMINPUT
+
+``argp``
+
+
+Description
+===========
+
+To query the attributes of a video input applications initialize the
+``index`` field of struct :ref:`v4l2_input <v4l2-input>` and call the
+:ref:`VIDIOC_ENUMINPUT` ioctl with a pointer to this structure. Drivers
+fill the rest of the structure or return an ``EINVAL`` error code when the
+index is out of bounds. To enumerate all inputs applications shall begin
+at index zero, incrementing by one until the driver returns ``EINVAL``.
+
+
+.. _v4l2-input:
+
+.. flat-table:: struct v4l2_input
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``index``
+
+ - Identifies the input, set by the application.
+
+ - .. row 2
+
+ - __u8
+
+ - ``name``\ [32]
+
+ - Name of the video input, a NUL-terminated ASCII string, for
+ example: "Vin (Composite 2)". This information is intended for the
+ user, preferably the connector label on the device itself.
+
+ - .. row 3
+
+ - __u32
+
+ - ``type``
+
+ - Type of the input, see :ref:`input-type`.
+
+ - .. row 4
+
+ - __u32
+
+ - ``audioset``
+
+ - Drivers can enumerate up to 32 video and audio inputs. This field
+ shows which audio inputs were selectable as audio source if this
+ was the currently selected video input. It is a bit mask. The LSB
+ corresponds to audio input 0, the MSB to input 31. Any number of
+ bits can be set, or none.
+
+ When the driver does not enumerate audio inputs no bits must be
+ set. Applications shall not interpret this as lack of audio
+ support. Some drivers automatically select audio sources and do
+ not enumerate them since there is no choice anyway.
+
+ For details on audio inputs and how to select the current input
+ see :ref:`audio`.
+
+ - .. row 5
+
+ - __u32
+
+ - ``tuner``
+
+ - Capture devices can have zero or more tuners (RF demodulators).
+ When the ``type`` is set to ``V4L2_INPUT_TYPE_TUNER`` this is an
+ RF connector and this field identifies the tuner. It corresponds
+ to struct :ref:`v4l2_tuner <v4l2-tuner>` field ``index``. For
+ details on tuners see :ref:`tuner`.
+
+ - .. row 6
+
+ - :ref:`v4l2_std_id <v4l2-std-id>`
+
+ - ``std``
+
+ - Every video input supports one or more different video standards.
+ This field is a set of all supported standards. For details on
+ video standards and how to switch see :ref:`standard`.
+
+ - .. row 7
+
+ - __u32
+
+ - ``status``
+
+ - This field provides status information about the input. See
+ :ref:`input-status` for flags. With the exception of the sensor
+ orientation bits ``status`` is only valid when this is the current
+ input.
+
+ - .. row 8
+
+ - __u32
+
+ - ``capabilities``
+
+ - This field provides capabilities for the input. See
+ :ref:`input-capabilities` for flags.
+
+ - .. row 9
+
+ - __u32
+
+ - ``reserved``\ [3]
+
+ - Reserved for future extensions. Drivers must set the array to
+ zero.
+
+
+
+.. _input-type:
+
+.. flat-table:: Input Types
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_INPUT_TYPE_TUNER``
+
+ - 1
+
+ - This input uses a tuner (RF demodulator).
+
+ - .. row 2
+
+ - ``V4L2_INPUT_TYPE_CAMERA``
+
+ - 2
+
+ - Analog baseband input, for example CVBS / Composite Video,
+ S-Video, RGB.
+
+
+
+.. _input-status:
+
+.. flat-table:: Input Status Flags
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - :cspan:`2` General
+
+ - .. row 2
+
+ - ``V4L2_IN_ST_NO_POWER``
+
+ - 0x00000001
+
+ - Attached device is off.
+
+ - .. row 3
+
+ - ``V4L2_IN_ST_NO_SIGNAL``
+
+ - 0x00000002
+
+ -
+
+ - .. row 4
+
+ - ``V4L2_IN_ST_NO_COLOR``
+
+ - 0x00000004
+
+ - The hardware supports color decoding, but does not detect color
+ modulation in the signal.
+
+ - .. row 5
+
+ - :cspan:`2` Sensor Orientation
+
+ - .. row 6
+
+ - ``V4L2_IN_ST_HFLIP``
+
+ - 0x00000010
+
+ - The input is connected to a device that produces a signal that is
+ flipped horizontally and does not correct this before passing the
+ signal to userspace.
+
+ - .. row 7
+
+ - ``V4L2_IN_ST_VFLIP``
+
+ - 0x00000020
+
+ - The input is connected to a device that produces a signal that is
+ flipped vertically and does not correct this before passing the
+ signal to userspace. Note that a 180 degree rotation is the same
+ as HFLIP | VFLIP
+
+ - .. row 8
+
+ - :cspan:`2` Analog Video
+
+ - .. row 9
+
+ - ``V4L2_IN_ST_NO_H_LOCK``
+
+ - 0x00000100
+
+ - No horizontal sync lock.
+
+ - .. row 10
+
+ - ``V4L2_IN_ST_COLOR_KILL``
+
+ - 0x00000200
+
+ - A color killer circuit automatically disables color decoding when
+ it detects no color modulation. When this flag is set the color
+ killer is enabled *and* has shut off color decoding.
+
+ - .. row 11
+
+ - :cspan:`2` Digital Video
+
+ - .. row 12
+
+ - ``V4L2_IN_ST_NO_SYNC``
+
+ - 0x00010000
+
+ - No synchronization lock.
+
+ - .. row 13
+
+ - ``V4L2_IN_ST_NO_EQU``
+
+ - 0x00020000
+
+ - No equalizer lock.
+
+ - .. row 14
+
+ - ``V4L2_IN_ST_NO_CARRIER``
+
+ - 0x00040000
+
+ - Carrier recovery failed.
+
+ - .. row 15
+
+ - :cspan:`2` VCR and Set-Top Box
+
+ - .. row 16
+
+ - ``V4L2_IN_ST_MACROVISION``
+
+ - 0x01000000
+
+ - Macrovision is an analog copy prevention system mangling the video
+ signal to confuse video recorders. When this flag is set
+ Macrovision has been detected.
+
+ - .. row 17
+
+ - ``V4L2_IN_ST_NO_ACCESS``
+
+ - 0x02000000
+
+ - Conditional access denied.
+
+ - .. row 18
+
+ - ``V4L2_IN_ST_VTR``
+
+ - 0x04000000
+
+ - VTR time constant. [?]
+
+
+
+.. _input-capabilities:
+
+.. flat-table:: Input capabilities
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_IN_CAP_DV_TIMINGS``
+
+ - 0x00000002
+
+ - This input supports setting video timings by using
+ VIDIOC_S_DV_TIMINGS.
+
+ - .. row 2
+
+ - ``V4L2_IN_CAP_STD``
+
+ - 0x00000004
+
+ - This input supports setting the TV standard by using
+ VIDIOC_S_STD.
+
+ - .. row 3
+
+ - ``V4L2_IN_CAP_NATIVE_SIZE``
+
+ - 0x00000008
+
+ - This input supports setting the native size using the
+ ``V4L2_SEL_TGT_NATIVE_SIZE`` selection target, see
+ :ref:`v4l2-selections-common`.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The struct :ref:`v4l2_input <v4l2-input>` ``index`` is out of
+ bounds.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_ENUMOUTPUT:
+
+***********************
+ioctl VIDIOC_ENUMOUTPUT
+***********************
+
+Name
+====
+
+VIDIOC_ENUMOUTPUT - Enumerate video outputs
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_output *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_ENUMOUTPUT
+
+``argp``
+
+
+Description
+===========
+
+To query the attributes of a video outputs applications initialize the
+``index`` field of struct :ref:`v4l2_output <v4l2-output>` and call
+the :ref:`VIDIOC_ENUMOUTPUT` ioctl with a pointer to this structure.
+Drivers fill the rest of the structure or return an ``EINVAL`` error code
+when the index is out of bounds. To enumerate all outputs applications
+shall begin at index zero, incrementing by one until the driver returns
+EINVAL.
+
+
+.. _v4l2-output:
+
+.. flat-table:: struct v4l2_output
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``index``
+
+ - Identifies the output, set by the application.
+
+ - .. row 2
+
+ - __u8
+
+ - ``name``\ [32]
+
+ - Name of the video output, a NUL-terminated ASCII string, for
+ example: "Vout". This information is intended for the user,
+ preferably the connector label on the device itself.
+
+ - .. row 3
+
+ - __u32
+
+ - ``type``
+
+ - Type of the output, see :ref:`output-type`.
+
+ - .. row 4
+
+ - __u32
+
+ - ``audioset``
+
+ - Drivers can enumerate up to 32 video and audio outputs. This field
+ shows which audio outputs were selectable as the current output if
+ this was the currently selected video output. It is a bit mask.
+ The LSB corresponds to audio output 0, the MSB to output 31. Any
+ number of bits can be set, or none.
+
+ When the driver does not enumerate audio outputs no bits must be
+ set. Applications shall not interpret this as lack of audio
+ support. Drivers may automatically select audio outputs without
+ enumerating them.
+
+ For details on audio outputs and how to select the current output
+ see :ref:`audio`.
+
+ - .. row 5
+
+ - __u32
+
+ - ``modulator``
+
+ - Output devices can have zero or more RF modulators. When the
+ ``type`` is ``V4L2_OUTPUT_TYPE_MODULATOR`` this is an RF connector
+ and this field identifies the modulator. It corresponds to struct
+ :ref:`v4l2_modulator <v4l2-modulator>` field ``index``. For
+ details on modulators see :ref:`tuner`.
+
+ - .. row 6
+
+ - :ref:`v4l2_std_id <v4l2-std-id>`
+
+ - ``std``
+
+ - Every video output supports one or more different video standards.
+ This field is a set of all supported standards. For details on
+ video standards and how to switch see :ref:`standard`.
+
+ - .. row 7
+
+ - __u32
+
+ - ``capabilities``
+
+ - This field provides capabilities for the output. See
+ :ref:`output-capabilities` for flags.
+
+ - .. row 8
+
+ - __u32
+
+ - ``reserved``\ [3]
+
+ - Reserved for future extensions. Drivers must set the array to
+ zero.
+
+
+
+.. _output-type:
+
+.. flat-table:: Output Type
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_OUTPUT_TYPE_MODULATOR``
+
+ - 1
+
+ - This output is an analog TV modulator.
+
+ - .. row 2
+
+ - ``V4L2_OUTPUT_TYPE_ANALOG``
+
+ - 2
+
+ - Analog baseband output, for example Composite / CVBS, S-Video,
+ RGB.
+
+ - .. row 3
+
+ - ``V4L2_OUTPUT_TYPE_ANALOGVGAOVERLAY``
+
+ - 3
+
+ - [?]
+
+
+
+.. _output-capabilities:
+
+.. flat-table:: Output capabilities
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_OUT_CAP_DV_TIMINGS``
+
+ - 0x00000002
+
+ - This output supports setting video timings by using
+ VIDIOC_S_DV_TIMINGS.
+
+ - .. row 2
+
+ - ``V4L2_OUT_CAP_STD``
+
+ - 0x00000004
+
+ - This output supports setting the TV standard by using
+ VIDIOC_S_STD.
+
+ - .. row 3
+
+ - ``V4L2_OUT_CAP_NATIVE_SIZE``
+
+ - 0x00000008
+
+ - This output supports setting the native size using the
+ ``V4L2_SEL_TGT_NATIVE_SIZE`` selection target, see
+ :ref:`v4l2-selections-common`.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The struct :ref:`v4l2_output <v4l2-output>` ``index`` is out of
+ bounds.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_ENUMSTD:
+
+********************
+ioctl VIDIOC_ENUMSTD
+********************
+
+Name
+====
+
+VIDIOC_ENUMSTD - Enumerate supported video standards
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_standard *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_ENUMSTD
+
+``argp``
+
+
+Description
+===========
+
+To query the attributes of a video standard, especially a custom (driver
+defined) one, applications initialize the ``index`` field of struct
+:ref:`v4l2_standard <v4l2-standard>` and call the :ref:`VIDIOC_ENUMSTD`
+ioctl with a pointer to this structure. Drivers fill the rest of the
+structure or return an ``EINVAL`` error code when the index is out of
+bounds. To enumerate all standards applications shall begin at index
+zero, incrementing by one until the driver returns ``EINVAL``. Drivers may
+enumerate a different set of standards after switching the video input
+or output. [1]_
+
+
+.. _v4l2-standard:
+
+.. flat-table:: struct v4l2_standard
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``index``
+
+ - Number of the video standard, set by the application.
+
+ - .. row 2
+
+ - :ref:`v4l2_std_id <v4l2-std-id>`
+
+ - ``id``
+
+ - The bits in this field identify the standard as one of the common
+ standards listed in :ref:`v4l2-std-id`, or if bits 32 to 63 are
+ set as custom standards. Multiple bits can be set if the hardware
+ does not distinguish between these standards, however separate
+ indices do not indicate the opposite. The ``id`` must be unique.
+ No other enumerated :ref:`struct v4l2_standard <v4l2-standard>` structure,
+ for this input or output anyway, can contain the same set of bits.
+
+ - .. row 3
+
+ - __u8
+
+ - ``name``\ [24]
+
+ - Name of the standard, a NUL-terminated ASCII string, for example:
+ "PAL-B/G", "NTSC Japan". This information is intended for the
+ user.
+
+ - .. row 4
+
+ - struct :ref:`v4l2_fract <v4l2-fract>`
+
+ - ``frameperiod``
+
+ - The frame period (not field period) is numerator / denominator.
+ For example M/NTSC has a frame period of 1001 / 30000 seconds.
+
+ - .. row 5
+
+ - __u32
+
+ - ``framelines``
+
+ - Total lines per frame including blanking, e. g. 625 for B/PAL.
+
+ - .. row 6
+
+ - __u32
+
+ - ``reserved``\ [4]
+
+ - Reserved for future extensions. Drivers must set the array to
+ zero.
+
+
+
+.. _v4l2-fract:
+
+.. flat-table:: struct v4l2_fract
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``numerator``
+
+ -
+
+ - .. row 2
+
+ - __u32
+
+ - ``denominator``
+
+ -
+
+
+
+.. _v4l2-std-id:
+
+.. flat-table:: typedef v4l2_std_id
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u64
+
+ - ``v4l2_std_id``
+
+ - This type is a set, each bit representing another video standard
+ as listed below and in :ref:`video-standards`. The 32 most
+ significant bits are reserved for custom (driver defined) video
+ standards.
+
+
+
+.. code-block:: c
+
+ #define V4L2_STD_PAL_B ((v4l2_std_id)0x00000001)
+ #define V4L2_STD_PAL_B1 ((v4l2_std_id)0x00000002)
+ #define V4L2_STD_PAL_G ((v4l2_std_id)0x00000004)
+ #define V4L2_STD_PAL_H ((v4l2_std_id)0x00000008)
+ #define V4L2_STD_PAL_I ((v4l2_std_id)0x00000010)
+ #define V4L2_STD_PAL_D ((v4l2_std_id)0x00000020)
+ #define V4L2_STD_PAL_D1 ((v4l2_std_id)0x00000040)
+ #define V4L2_STD_PAL_K ((v4l2_std_id)0x00000080)
+
+ #define V4L2_STD_PAL_M ((v4l2_std_id)0x00000100)
+ #define V4L2_STD_PAL_N ((v4l2_std_id)0x00000200)
+ #define V4L2_STD_PAL_Nc ((v4l2_std_id)0x00000400)
+ #define V4L2_STD_PAL_60 ((v4l2_std_id)0x00000800)
+
+``V4L2_STD_PAL_60`` is a hybrid standard with 525 lines, 60 Hz refresh
+rate, and PAL color modulation with a 4.43 MHz color subcarrier. Some
+PAL video recorders can play back NTSC tapes in this mode for display on
+a 50/60 Hz agnostic PAL TV.
+
+
+.. code-block:: c
+
+ #define V4L2_STD_NTSC_M ((v4l2_std_id)0x00001000)
+ #define V4L2_STD_NTSC_M_JP ((v4l2_std_id)0x00002000)
+ #define V4L2_STD_NTSC_443 ((v4l2_std_id)0x00004000)
+
+``V4L2_STD_NTSC_443`` is a hybrid standard with 525 lines, 60 Hz refresh
+rate, and NTSC color modulation with a 4.43 MHz color subcarrier.
+
+
+.. code-block:: c
+
+ #define V4L2_STD_NTSC_M_KR ((v4l2_std_id)0x00008000)
+
+ #define V4L2_STD_SECAM_B ((v4l2_std_id)0x00010000)
+ #define V4L2_STD_SECAM_D ((v4l2_std_id)0x00020000)
+ #define V4L2_STD_SECAM_G ((v4l2_std_id)0x00040000)
+ #define V4L2_STD_SECAM_H ((v4l2_std_id)0x00080000)
+ #define V4L2_STD_SECAM_K ((v4l2_std_id)0x00100000)
+ #define V4L2_STD_SECAM_K1 ((v4l2_std_id)0x00200000)
+ #define V4L2_STD_SECAM_L ((v4l2_std_id)0x00400000)
+ #define V4L2_STD_SECAM_LC ((v4l2_std_id)0x00800000)
+
+ /* ATSC/HDTV */
+ #define V4L2_STD_ATSC_8_VSB ((v4l2_std_id)0x01000000)
+ #define V4L2_STD_ATSC_16_VSB ((v4l2_std_id)0x02000000)
+
+``V4L2_STD_ATSC_8_VSB`` and ``V4L2_STD_ATSC_16_VSB`` are U.S.
+terrestrial digital TV standards. Presently the V4L2 API does not
+support digital TV. See also the Linux DVB API at
+`https://linuxtv.org <https://linuxtv.org>`__.
+
+
+.. code-block:: c
+
+ #define V4L2_STD_PAL_BG (V4L2_STD_PAL_B |
+ V4L2_STD_PAL_B1 |
+ V4L2_STD_PAL_G)
+ #define V4L2_STD_B (V4L2_STD_PAL_B |
+ V4L2_STD_PAL_B1 |
+ V4L2_STD_SECAM_B)
+ #define V4L2_STD_GH (V4L2_STD_PAL_G |
+ V4L2_STD_PAL_H |
+ V4L2_STD_SECAM_G |
+ V4L2_STD_SECAM_H)
+ #define V4L2_STD_PAL_DK (V4L2_STD_PAL_D |
+ V4L2_STD_PAL_D1 |
+ V4L2_STD_PAL_K)
+ #define V4L2_STD_PAL (V4L2_STD_PAL_BG |
+ V4L2_STD_PAL_DK |
+ V4L2_STD_PAL_H |
+ V4L2_STD_PAL_I)
+ #define V4L2_STD_NTSC (V4L2_STD_NTSC_M |
+ V4L2_STD_NTSC_M_JP |
+ V4L2_STD_NTSC_M_KR)
+ #define V4L2_STD_MN (V4L2_STD_PAL_M |
+ V4L2_STD_PAL_N |
+ V4L2_STD_PAL_Nc |
+ V4L2_STD_NTSC)
+ #define V4L2_STD_SECAM_DK (V4L2_STD_SECAM_D |
+ V4L2_STD_SECAM_K |
+ V4L2_STD_SECAM_K1)
+ #define V4L2_STD_DK (V4L2_STD_PAL_DK |
+ V4L2_STD_SECAM_DK)
+
+ #define V4L2_STD_SECAM (V4L2_STD_SECAM_B |
+ V4L2_STD_SECAM_G |
+ V4L2_STD_SECAM_H |
+ V4L2_STD_SECAM_DK |
+ V4L2_STD_SECAM_L |
+ V4L2_STD_SECAM_LC)
+
+ #define V4L2_STD_525_60 (V4L2_STD_PAL_M |
+ V4L2_STD_PAL_60 |
+ V4L2_STD_NTSC |
+ V4L2_STD_NTSC_443)
+ #define V4L2_STD_625_50 (V4L2_STD_PAL |
+ V4L2_STD_PAL_N |
+ V4L2_STD_PAL_Nc |
+ V4L2_STD_SECAM)
+
+ #define V4L2_STD_UNKNOWN 0
+ #define V4L2_STD_ALL (V4L2_STD_525_60 |
+ V4L2_STD_625_50)
+
+
+.. _video-standards:
+
+.. flat-table:: Video Standards (based on [])
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Characteristics
+
+ - M/NTSC [2]_
+
+ - M/PAL
+
+ - N/PAL [3]_
+
+ - B, B1, G/PAL
+
+ - D, D1, K/PAL
+
+ - H/PAL
+
+ - I/PAL
+
+ - B, G/SECAM
+
+ - D, K/SECAM
+
+ - K1/SECAM
+
+ - L/SECAM
+
+ - .. row 2
+
+ - Frame lines
+
+ - :cspan:`1` 525
+
+ - :cspan:`9` 625
+
+ - .. row 3
+
+ - Frame period (s)
+
+ - :cspan:`1` 1001/30000
+
+ - :cspan:`9` 1/25
+
+ - .. row 4
+
+ - Chrominance sub-carrier frequency (Hz)
+
+ - 3579545 ± 10
+
+ - 3579611.49 ± 10
+
+ - 4433618.75 ± 5 (3582056.25 ± 5)
+
+ - :cspan:`3` 4433618.75 ± 5
+
+ - 4433618.75 ± 1
+
+ - :cspan:`3` f\ :sub:`OR` = 4406250 ± 2000, f\ :sub:`OB` = 4250000
+ ± 2000
+
+ - .. row 5
+
+ - Nominal radio-frequency channel bandwidth (MHz)
+
+ - 6
+
+ - 6
+
+ - 6
+
+ - B: 7; B1, G: 8
+
+ - 8
+
+ - 8
+
+ - 8
+
+ - 8
+
+ - 8
+
+ - 8
+
+ - 8
+
+ - .. row 6
+
+ - Sound carrier relative to vision carrier (MHz)
+
+ - + 4.5
+
+ - + 4.5
+
+ - + 4.5
+
+ - + 5.5 ± 0.001 [4]_ [5]_ [6]_ [7]_
+
+ - + 6.5 ± 0.001
+
+ - + 5.5
+
+ - + 5.9996 ± 0.0005
+
+ - + 5.5 ± 0.001
+
+ - + 6.5 ± 0.001
+
+ - + 6.5
+
+ - + 6.5 [8]_
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The struct :ref:`v4l2_standard <v4l2-standard>` ``index`` is out
+ of bounds.
+
+ENODATA
+ Standard video timings are not supported for this input or output.
+
+.. [1]
+ The supported standards may overlap and we need an unambiguous set to
+ find the current standard returned by :ref:`VIDIOC_G_STD <VIDIOC_G_STD>`.
+
+.. [2]
+ Japan uses a standard similar to M/NTSC (V4L2_STD_NTSC_M_JP).
+
+.. [3]
+ The values in brackets apply to the combination N/PAL a.k.a.
+ N\ :sub:`C` used in Argentina (V4L2_STD_PAL_Nc).
+
+.. [4]
+ In the Federal Republic of Germany, Austria, Italy, the Netherlands,
+ Slovakia and Switzerland a system of two sound carriers is used, the
+ frequency of the second carrier being 242.1875 kHz above the
+ frequency of the first sound carrier. For stereophonic sound
+ transmissions a similar system is used in Australia.
+
+.. [5]
+ New Zealand uses a sound carrier displaced 5.4996 ± 0.0005 MHz from
+ the vision carrier.
+
+.. [6]
+ In Denmark, Finland, New Zealand, Sweden and Spain a system of two
+ sound carriers is used. In Iceland, Norway and Poland the same system
+ is being introduced. The second carrier is 5.85 MHz above the vision
+ carrier and is DQPSK modulated with 728 kbit/s sound and data
+ multiplex. (NICAM system)
+
+.. [7]
+ In the United Kingdom, a system of two sound carriers is used. The
+ second sound carrier is 6.552 MHz above the vision carrier and is
+ DQPSK modulated with a 728 kbit/s sound and data multiplex able to
+ carry two sound channels. (NICAM system)
+
+.. [8]
+ In France, a digital carrier 5.85 MHz away from the vision carrier
+ may be used in addition to the main sound carrier. It is modulated in
+ differentially encoded QPSK with a 728 kbit/s sound and data
+ multiplexer capable of carrying two sound channels. (NICAM system)
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_EXPBUF:
+
+*******************
+ioctl VIDIOC_EXPBUF
+*******************
+
+Name
+====
+
+VIDIOC_EXPBUF - Export a buffer as a DMABUF file descriptor.
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_exportbuffer *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_EXPBUF
+
+``argp``
+
+
+Description
+===========
+
+This ioctl is an extension to the :ref:`memory mapping <mmap>` I/O
+method, therefore it is available only for ``V4L2_MEMORY_MMAP`` buffers.
+It can be used to export a buffer as a DMABUF file at any time after
+buffers have been allocated with the
+:ref:`VIDIOC_REQBUFS` ioctl.
+
+To export a buffer, applications fill struct
+:ref:`v4l2_exportbuffer <v4l2-exportbuffer>`. The ``type`` field is
+set to the same buffer type as was previously used with struct
+:ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``type``.
+Applications must also set the ``index`` field. Valid index numbers
+range from zero to the number of buffers allocated with
+:ref:`VIDIOC_REQBUFS` (struct
+:ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``count``) minus
+one. For the multi-planar API, applications set the ``plane`` field to
+the index of the plane to be exported. Valid planes range from zero to
+the maximal number of valid planes for the currently active format. For
+the single-planar API, applications must set ``plane`` to zero.
+Additional flags may be posted in the ``flags`` field. Refer to a manual
+for open() for details. Currently only O_CLOEXEC, O_RDONLY, O_WRONLY,
+and O_RDWR are supported. All other fields must be set to zero. In the
+case of multi-planar API, every plane is exported separately using
+multiple :ref:`VIDIOC_EXPBUF` calls.
+
+After calling :ref:`VIDIOC_EXPBUF` the ``fd`` field will be set by a
+driver. This is a DMABUF file descriptor. The application may pass it to
+other DMABUF-aware devices. Refer to :ref:`DMABUF importing <dmabuf>`
+for details about importing DMABUF files into V4L2 nodes. It is
+recommended to close a DMABUF file when it is no longer used to allow
+the associated memory to be reclaimed.
+
+
+Examples
+========
+
+
+.. code-block:: c
+
+ int buffer_export(int v4lfd, enum v4l2_buf_type bt, int index, int *dmafd)
+ {
+ struct v4l2_exportbuffer expbuf;
+
+ memset(&expbuf, 0, sizeof(expbuf));
+ expbuf.type = bt;
+ expbuf.index = index;
+ if (ioctl(v4lfd, VIDIOC_EXPBUF, &expbuf) == -1) {
+ perror("VIDIOC_EXPBUF");
+ return -1;
+ }
+
+ *dmafd = expbuf.fd;
+
+ return 0;
+ }
+
+
+.. code-block:: c
+
+ int buffer_export_mp(int v4lfd, enum v4l2_buf_type bt, int index,
+ int dmafd[], int n_planes)
+ {
+ int i;
+
+ for (i = 0; i < n_planes; ++i) {
+ struct v4l2_exportbuffer expbuf;
+
+ memset(&expbuf, 0, sizeof(expbuf));
+ expbuf.type = bt;
+ expbuf.index = index;
+ expbuf.plane = i;
+ if (ioctl(v4lfd, VIDIOC_EXPBUF, &expbuf) == -1) {
+ perror("VIDIOC_EXPBUF");
+ while (i)
+ close(dmafd[--i]);
+ return -1;
+ }
+ dmafd[i] = expbuf.fd;
+ }
+
+ return 0;
+ }
+
+
+.. _v4l2-exportbuffer:
+
+.. flat-table:: struct v4l2_exportbuffer
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``type``
+
+ - Type of the buffer, same as struct
+ :ref:`v4l2_format <v4l2-format>` ``type`` or struct
+ :ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``type``, set
+ by the application. See :ref:`v4l2-buf-type`
+
+ - .. row 2
+
+ - __u32
+
+ - ``index``
+
+ - Number of the buffer, set by the application. This field is only
+ used for :ref:`memory mapping <mmap>` I/O and can range from
+ zero to the number of buffers allocated with the
+ :ref:`VIDIOC_REQBUFS` and/or
+ :ref:`VIDIOC_CREATE_BUFS` ioctls.
+
+ - .. row 3
+
+ - __u32
+
+ - ``plane``
+
+ - Index of the plane to be exported when using the multi-planar API.
+ Otherwise this value must be set to zero.
+
+ - .. row 4
+
+ - __u32
+
+ - ``flags``
+
+ - Flags for the newly created file, currently only ``O_CLOEXEC``,
+ ``O_RDONLY``, ``O_WRONLY``, and ``O_RDWR`` are supported, refer to
+ the manual of open() for more details.
+
+ - .. row 5
+
+ - __s32
+
+ - ``fd``
+
+ - The DMABUF file descriptor associated with a buffer. Set by the
+ driver.
+
+ - .. row 6
+
+ - __u32
+
+ - ``reserved[11]``
+
+ - Reserved field for future use. Drivers and applications must set
+ the array to zero.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ A queue is not in MMAP mode or DMABUF exporting is not supported or
+ ``flags`` or ``type`` or ``index`` or ``plane`` fields are invalid.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_G_AUDIO:
+
+************************************
+ioctl VIDIOC_G_AUDIO, VIDIOC_S_AUDIO
+************************************
+
+Name
+====
+
+VIDIOC_G_AUDIO - VIDIOC_S_AUDIO - Query or select the current audio input and its attributes
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_audio *argp )
+
+.. cpp:function:: int ioctl( int fd, int request, const struct v4l2_audio *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_AUDIO, VIDIOC_S_AUDIO
+
+``argp``
+
+
+Description
+===========
+
+To query the current audio input applications zero out the ``reserved``
+array of a struct :ref:`v4l2_audio <v4l2-audio>` and call the
+:ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` ioctl with a pointer to this structure. Drivers fill
+the rest of the structure or return an ``EINVAL`` error code when the device
+has no audio inputs, or none which combine with the current video input.
+
+Audio inputs have one writable property, the audio mode. To select the
+current audio input *and* change the audio mode, applications initialize
+the ``index`` and ``mode`` fields, and the ``reserved`` array of a
+:ref:`struct v4l2_audio <v4l2-audio>` structure and call the :ref:`VIDIOC_S_AUDIO <VIDIOC_G_AUDIO>`
+ioctl. Drivers may switch to a different audio mode if the request
+cannot be satisfied. However, this is a write-only ioctl, it does not
+return the actual new audio mode.
+
+
+.. _v4l2-audio:
+
+.. flat-table:: struct v4l2_audio
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``index``
+
+ - Identifies the audio input, set by the driver or application.
+
+ - .. row 2
+
+ - __u8
+
+ - ``name``\ [32]
+
+ - Name of the audio input, a NUL-terminated ASCII string, for
+ example: "Line In". This information is intended for the user,
+ preferably the connector label on the device itself.
+
+ - .. row 3
+
+ - __u32
+
+ - ``capability``
+
+ - Audio capability flags, see :ref:`audio-capability`.
+
+ - .. row 4
+
+ - __u32
+
+ - ``mode``
+
+ - Audio mode flags set by drivers and applications (on
+ :ref:`VIDIOC_S_AUDIO <VIDIOC_G_AUDIO>` ioctl), see :ref:`audio-mode`.
+
+ - .. row 5
+
+ - __u32
+
+ - ``reserved``\ [2]
+
+ - Reserved for future extensions. Drivers and applications must set
+ the array to zero.
+
+
+
+.. _audio-capability:
+
+.. flat-table:: Audio Capability Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_AUDCAP_STEREO``
+
+ - 0x00001
+
+ - This is a stereo input. The flag is intended to automatically
+ disable stereo recording etc. when the signal is always monaural.
+ The API provides no means to detect if stereo is *received*,
+ unless the audio input belongs to a tuner.
+
+ - .. row 2
+
+ - ``V4L2_AUDCAP_AVL``
+
+ - 0x00002
+
+ - Automatic Volume Level mode is supported.
+
+
+
+.. _audio-mode:
+
+.. flat-table:: Audio Mode Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_AUDMODE_AVL``
+
+ - 0x00001
+
+ - AVL mode is on.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ No audio inputs combine with the current video input, or the number
+ of the selected audio input is out of bounds or it does not combine.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_G_AUDOUT:
+
+**************************************
+ioctl VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT
+**************************************
+
+Name
+====
+
+VIDIOC_G_AUDOUT - VIDIOC_S_AUDOUT - Query or select the current audio output
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_audioout *argp )
+
+.. cpp:function:: int ioctl( int fd, int request, const struct v4l2_audioout *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT
+
+``argp``
+
+
+Description
+===========
+
+To query the current audio output applications zero out the ``reserved``
+array of a struct :ref:`v4l2_audioout <v4l2-audioout>` and call the
+``VIDIOC_G_AUDOUT`` ioctl with a pointer to this structure. Drivers fill
+the rest of the structure or return an ``EINVAL`` error code when the device
+has no audio inputs, or none which combine with the current video
+output.
+
+Audio outputs have no writable properties. Nevertheless, to select the
+current audio output applications can initialize the ``index`` field and
+``reserved`` array (which in the future may contain writable properties)
+of a :ref:`struct v4l2_audioout <v4l2-audioout>` structure and call the
+``VIDIOC_S_AUDOUT`` ioctl. Drivers switch to the requested output or
+return the ``EINVAL`` error code when the index is out of bounds. This is a
+write-only ioctl, it does not return the current audio output attributes
+as ``VIDIOC_G_AUDOUT`` does.
+
+Note connectors on a TV card to loop back the received audio signal to a
+sound card are not audio outputs in this sense.
+
+
+.. _v4l2-audioout:
+
+.. flat-table:: struct v4l2_audioout
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``index``
+
+ - Identifies the audio output, set by the driver or application.
+
+ - .. row 2
+
+ - __u8
+
+ - ``name``\ [32]
+
+ - Name of the audio output, a NUL-terminated ASCII string, for
+ example: "Line Out". This information is intended for the user,
+ preferably the connector label on the device itself.
+
+ - .. row 3
+
+ - __u32
+
+ - ``capability``
+
+ - Audio capability flags, none defined yet. Drivers must set this
+ field to zero.
+
+ - .. row 4
+
+ - __u32
+
+ - ``mode``
+
+ - Audio mode, none defined yet. Drivers and applications (on
+ ``VIDIOC_S_AUDOUT``) must set this field to zero.
+
+ - .. row 5
+
+ - __u32
+
+ - ``reserved``\ [2]
+
+ - Reserved for future extensions. Drivers and applications must set
+ the array to zero.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ No audio outputs combine with the current video output, or the
+ number of the selected audio output is out of bounds or it does not
+ combine.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_G_CROP:
+
+**********************************
+ioctl VIDIOC_G_CROP, VIDIOC_S_CROP
+**********************************
+
+Name
+====
+
+VIDIOC_G_CROP - VIDIOC_S_CROP - Get or set the current cropping rectangle
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_crop *argp )
+
+.. cpp:function:: int ioctl( int fd, int request, const struct v4l2_crop *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_CROP, VIDIOC_S_CROP
+
+``argp``
+
+
+Description
+===========
+
+To query the cropping rectangle size and position applications set the
+``type`` field of a :ref:`struct v4l2_crop <v4l2-crop>` structure to the
+respective buffer (stream) type and call the :ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` ioctl
+with a pointer to this structure. The driver fills the rest of the
+structure or returns the ``EINVAL`` error code if cropping is not supported.
+
+To change the cropping rectangle applications initialize the ``type``
+and struct :ref:`v4l2_rect <v4l2-rect>` substructure named ``c`` of a
+v4l2_crop structure and call the :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` ioctl with a pointer
+to this structure.
+
+Do not use the multiplanar buffer types. Use
+``V4L2_BUF_TYPE_VIDEO_CAPTURE`` instead of
+``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and use
+``V4L2_BUF_TYPE_VIDEO_OUTPUT`` instead of
+``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``.
+
+The driver first adjusts the requested dimensions against hardware
+limits, i. e. the bounds given by the capture/output window, and it
+rounds to the closest possible values of horizontal and vertical offset,
+width and height. In particular the driver must round the vertical
+offset of the cropping rectangle to frame lines modulo two, such that
+the field order cannot be confused.
+
+Second the driver adjusts the image size (the opposite rectangle of the
+scaling process, source or target depending on the data direction) to
+the closest size possible while maintaining the current horizontal and
+vertical scaling factor.
+
+Finally the driver programs the hardware with the actual cropping and
+image parameters. :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` is a write-only ioctl, it does not
+return the actual parameters. To query them applications must call
+:ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and :ref:`VIDIOC_G_FMT`. When the
+parameters are unsuitable the application may modify the cropping or
+image parameters and repeat the cycle until satisfactory parameters have
+been negotiated.
+
+When cropping is not supported then no parameters are changed and
+:ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` returns the ``EINVAL`` error code.
+
+
+.. _v4l2-crop:
+
+.. flat-table:: struct v4l2_crop
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``type``
+
+ - Type of the data stream, set by the application. Only these types
+ are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``,
+ ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` and
+ ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :ref:`v4l2-buf-type`.
+
+ - .. row 2
+
+ - struct :ref:`v4l2_rect <v4l2-rect>`
+
+ - ``c``
+
+ - Cropping rectangle. The same co-ordinate system as for struct
+ :ref:`v4l2_cropcap <v4l2-cropcap>` ``bounds`` is used.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_G_CTRL:
+
+**********************************
+ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL
+**********************************
+
+Name
+====
+
+VIDIOC_G_CTRL - VIDIOC_S_CTRL - Get or set the value of a control
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_control *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_CTRL, VIDIOC_S_CTRL
+
+``argp``
+
+
+Description
+===========
+
+To get the current value of a control applications initialize the ``id``
+field of a struct :ref:`struct v4l2_control <v4l2-control>` and call the
+:ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` ioctl with a pointer to this structure. To change the
+value of a control applications initialize the ``id`` and ``value``
+fields of a struct :ref:`struct v4l2_control <v4l2-control>` and call the
+:ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctl.
+
+When the ``id`` is invalid drivers return an ``EINVAL`` error code. When the
+``value`` is out of bounds drivers can choose to take the closest valid
+value or return an ``ERANGE`` error code, whatever seems more appropriate.
+However, :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` is a write-only ioctl, it does not return the
+actual new value. If the ``value`` is inappropriate for the control
+(e.g. if it refers to an unsupported menu index of a menu control), then
+EINVAL error code is returned as well.
+
+These ioctls work only with user controls. For other control classes the
+:ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`,
+:ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` or
+:ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` must be used.
+
+
+.. _v4l2-control:
+
+.. flat-table:: struct v4l2_control
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``id``
+
+ - Identifies the control, set by the application.
+
+ - .. row 2
+
+ - __s32
+
+ - ``value``
+
+ - New value or current value.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The struct :ref:`v4l2_control <v4l2-control>` ``id`` is invalid
+ or the ``value`` is inappropriate for the given control (i.e. if a
+ menu item is selected that is not supported by the driver according
+ to :ref:`VIDIOC_QUERYMENU <VIDIOC_QUERYCTRL>`).
+
+ERANGE
+ The struct :ref:`v4l2_control <v4l2-control>` ``value`` is out of
+ bounds.
+
+EBUSY
+ The control is temporarily not changeable, possibly because another
+ applications took over control of the device function this control
+ belongs to.
+
+EACCES
+ Attempt to set a read-only control or to get a write-only control.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_G_DV_TIMINGS:
+
+**********************************************
+ioctl VIDIOC_G_DV_TIMINGS, VIDIOC_S_DV_TIMINGS
+**********************************************
+
+Name
+====
+
+VIDIOC_G_DV_TIMINGS - VIDIOC_S_DV_TIMINGS - VIDIOC_SUBDEV_G_DV_TIMINGS - VIDIOC_SUBDEV_S_DV_TIMINGS - Get or set DV timings for input or output
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_dv_timings *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_DV_TIMINGS, VIDIOC_S_DV_TIMINGS,
+ VIDIOC_SUBDEV_G_DV_TIMINGS, VIDIOC_SUBDEV_S_DV_TIMINGS
+
+``argp``
+
+
+Description
+===========
+
+To set DV timings for the input or output, applications use the
+:ref:`VIDIOC_S_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>` ioctl and to get the current timings,
+applications use the :ref:`VIDIOC_G_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>` ioctl. The detailed timing
+information is filled in using the structure struct
+:ref:`v4l2_dv_timings <v4l2-dv-timings>`. These ioctls take a
+pointer to the struct :ref:`v4l2_dv_timings <v4l2-dv-timings>`
+structure as argument. If the ioctl is not supported or the timing
+values are not correct, the driver returns ``EINVAL`` error code.
+
+The ``linux/v4l2-dv-timings.h`` header can be used to get the timings of
+the formats in the :ref:`cea861` and :ref:`vesadmt` standards. If
+the current input or output does not support DV timings (e.g. if
+:ref:`VIDIOC_ENUMINPUT` does not set the
+``V4L2_IN_CAP_DV_TIMINGS`` flag), then ``ENODATA`` error code is returned.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ This ioctl is not supported, or the :ref:`VIDIOC_S_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>`
+ parameter was unsuitable.
+
+ENODATA
+ Digital video timings are not supported for this input or output.
+
+EBUSY
+ The device is busy and therefore can not change the timings.
+
+
+.. _v4l2-bt-timings:
+
+.. flat-table:: struct v4l2_bt_timings
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``width``
+
+ - Width of the active video in pixels.
+
+ - .. row 2
+
+ - __u32
+
+ - ``height``
+
+ - Height of the active video frame in lines. So for interlaced
+ formats the height of the active video in each field is
+ ``height``/2.
+
+ - .. row 3
+
+ - __u32
+
+ - ``interlaced``
+
+ - Progressive (0) or interlaced (1)
+
+ - .. row 4
+
+ - __u32
+
+ - ``polarities``
+
+ - This is a bit mask that defines polarities of sync signals. bit 0
+ (``V4L2_DV_VSYNC_POS_POL``) is for vertical sync polarity and bit
+ 1 (``V4L2_DV_HSYNC_POS_POL``) is for horizontal sync polarity. If
+ the bit is set (1) it is positive polarity and if is cleared (0),
+ it is negative polarity.
+
+ - .. row 5
+
+ - __u64
+
+ - ``pixelclock``
+
+ - Pixel clock in Hz. Ex. 74.25MHz->74250000
+
+ - .. row 6
+
+ - __u32
+
+ - ``hfrontporch``
+
+ - Horizontal front porch in pixels
+
+ - .. row 7
+
+ - __u32
+
+ - ``hsync``
+
+ - Horizontal sync length in pixels
+
+ - .. row 8
+
+ - __u32
+
+ - ``hbackporch``
+
+ - Horizontal back porch in pixels
+
+ - .. row 9
+
+ - __u32
+
+ - ``vfrontporch``
+
+ - Vertical front porch in lines. For interlaced formats this refers
+ to the odd field (aka field 1).
+
+ - .. row 10
+
+ - __u32
+
+ - ``vsync``
+
+ - Vertical sync length in lines. For interlaced formats this refers
+ to the odd field (aka field 1).
+
+ - .. row 11
+
+ - __u32
+
+ - ``vbackporch``
+
+ - Vertical back porch in lines. For interlaced formats this refers
+ to the odd field (aka field 1).
+
+ - .. row 12
+
+ - __u32
+
+ - ``il_vfrontporch``
+
+ - Vertical front porch in lines for the even field (aka field 2) of
+ interlaced field formats. Must be 0 for progressive formats.
+
+ - .. row 13
+
+ - __u32
+
+ - ``il_vsync``
+
+ - Vertical sync length in lines for the even field (aka field 2) of
+ interlaced field formats. Must be 0 for progressive formats.
+
+ - .. row 14
+
+ - __u32
+
+ - ``il_vbackporch``
+
+ - Vertical back porch in lines for the even field (aka field 2) of
+ interlaced field formats. Must be 0 for progressive formats.
+
+ - .. row 15
+
+ - __u32
+
+ - ``standards``
+
+ - The video standard(s) this format belongs to. This will be filled
+ in by the driver. Applications must set this to 0. See
+ :ref:`dv-bt-standards` for a list of standards.
+
+ - .. row 16
+
+ - __u32
+
+ - ``flags``
+
+ - Several flags giving more information about the format. See
+ :ref:`dv-bt-flags` for a description of the flags.
+
+
+
+.. _v4l2-dv-timings:
+
+.. flat-table:: struct v4l2_dv_timings
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2 1
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``type``
+
+ -
+ - Type of DV timings as listed in :ref:`dv-timing-types`.
+
+ - .. row 2
+
+ - union
+
+ -
+ -
+
+ - .. row 3
+
+ -
+ - struct :ref:`v4l2_bt_timings <v4l2-bt-timings>`
+
+ - ``bt``
+
+ - Timings defined by BT.656/1120 specifications
+
+ - .. row 4
+
+ -
+ - __u32
+
+ - ``reserved``\ [32]
+
+ -
+
+
+
+.. _dv-timing-types:
+
+.. flat-table:: DV Timing types
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - Timing type
+
+ - value
+
+ - Description
+
+ - .. row 2
+
+ -
+ -
+ -
+
+ - .. row 3
+
+ - ``V4L2_DV_BT_656_1120``
+
+ - 0
+
+ - BT.656/1120 timings
+
+
+
+.. _dv-bt-standards:
+
+.. flat-table:: DV BT Timing standards
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Timing standard
+
+ - Description
+
+ - .. row 2
+
+ -
+ -
+
+ - .. row 3
+
+ - ``V4L2_DV_BT_STD_CEA861``
+
+ - The timings follow the CEA-861 Digital TV Profile standard
+
+ - .. row 4
+
+ - ``V4L2_DV_BT_STD_DMT``
+
+ - The timings follow the VESA Discrete Monitor Timings standard
+
+ - .. row 5
+
+ - ``V4L2_DV_BT_STD_CVT``
+
+ - The timings follow the VESA Coordinated Video Timings standard
+
+ - .. row 6
+
+ - ``V4L2_DV_BT_STD_GTF``
+
+ - The timings follow the VESA Generalized Timings Formula standard
+
+
+
+.. _dv-bt-flags:
+
+.. flat-table:: DV BT Timing flags
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Flag
+
+ - Description
+
+ - .. row 2
+
+ -
+ -
+
+ - .. row 3
+
+ - ``V4L2_DV_FL_REDUCED_BLANKING``
+
+ - CVT/GTF specific: the timings use reduced blanking (CVT) or the
+ 'Secondary GTF' curve (GTF). In both cases the horizontal and/or
+ vertical blanking intervals are reduced, allowing a higher
+ resolution over the same bandwidth. This is a read-only flag,
+ applications must not set this.
+
+ - .. row 4
+
+ - ``V4L2_DV_FL_CAN_REDUCE_FPS``
+
+ - CEA-861 specific: set for CEA-861 formats with a framerate that is
+ a multiple of six. These formats can be optionally played at 1 /
+ 1.001 speed to be compatible with 60 Hz based standards such as
+ NTSC and PAL-M that use a framerate of 29.97 frames per second. If
+ the transmitter can't generate such frequencies, then the flag
+ will also be cleared. This is a read-only flag, applications must
+ not set this.
+
+ - .. row 5
+
+ - ``V4L2_DV_FL_REDUCED_FPS``
+
+ - CEA-861 specific: only valid for video transmitters, the flag is
+ cleared by receivers. It is also only valid for formats with the
+ ``V4L2_DV_FL_CAN_REDUCE_FPS`` flag set, for other formats the
+ flag will be cleared by the driver. If the application sets this
+ flag, then the pixelclock used to set up the transmitter is
+ divided by 1.001 to make it compatible with NTSC framerates. If
+ the transmitter can't generate such frequencies, then the flag
+ will also be cleared.
+
+ - .. row 6
+
+ - ``V4L2_DV_FL_HALF_LINE``
+
+ - Specific to interlaced formats: if set, then the vertical
+ frontporch of field 1 (aka the odd field) is really one half-line
+ longer and the vertical backporch of field 2 (aka the even field)
+ is really one half-line shorter, so each field has exactly the
+ same number of half-lines. Whether half-lines can be detected or
+ used depends on the hardware.
+
+ - .. row 7
+
+ - ``V4L2_DV_FL_IS_CE_VIDEO``
+
+ - If set, then this is a Consumer Electronics (CE) video format.
+ Such formats differ from other formats (commonly called IT
+ formats) in that if R'G'B' encoding is used then by default the
+ R'G'B' values use limited range (i.e. 16-235) as opposed to full
+ range (i.e. 0-255). All formats defined in CEA-861 except for the
+ 640x480p59.94 format are CE formats.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_G_EDID:
+
+******************************************************************************
+ioctl VIDIOC_G_EDID, VIDIOC_S_EDID, VIDIOC_SUBDEV_G_EDID, VIDIOC_SUBDEV_S_EDID
+******************************************************************************
+
+Name
+====
+
+VIDIOC_G_EDID - VIDIOC_S_EDID - VIDIOC_SUBDEV_G_EDID - VIDIOC_SUBDEV_S_EDID - Get or set the EDID of a video receiver/transmitter
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_edid *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_EDID, VIDIOC_S_EDID, VIDIOC_SUBDEV_G_EDID,
+ VIDIOC_SUBDEV_S_EDID
+
+``argp``
+
+
+Description
+===========
+
+These ioctls can be used to get or set an EDID associated with an input
+from a receiver or an output of a transmitter device. They can be used
+with subdevice nodes (/dev/v4l-subdevX) or with video nodes
+(/dev/videoX).
+
+When used with video nodes the ``pad`` field represents the input (for
+video capture devices) or output (for video output devices) index as is
+returned by :ref:`VIDIOC_ENUMINPUT` and
+:ref:`VIDIOC_ENUMOUTPUT` respectively. When used
+with subdevice nodes the ``pad`` field represents the input or output
+pad of the subdevice. If there is no EDID support for the given ``pad``
+value, then the ``EINVAL`` error code will be returned.
+
+To get the EDID data the application has to fill in the ``pad``,
+``start_block``, ``blocks`` and ``edid`` fields, zero the ``reserved``
+array and call :ref:`VIDIOC_G_EDID <VIDIOC_G_EDID>`. The current EDID from block
+``start_block`` and of size ``blocks`` will be placed in the memory
+``edid`` points to. The ``edid`` pointer must point to memory at least
+``blocks`` * 128 bytes large (the size of one block is 128 bytes).
+
+If there are fewer blocks than specified, then the driver will set
+``blocks`` to the actual number of blocks. If there are no EDID blocks
+available at all, then the error code ``ENODATA`` is set.
+
+If blocks have to be retrieved from the sink, then this call will block
+until they have been read.
+
+If ``start_block`` and ``blocks`` are both set to 0 when
+:ref:`VIDIOC_G_EDID <VIDIOC_G_EDID>` is called, then the driver will set ``blocks`` to the
+total number of available EDID blocks and it will return 0 without
+copying any data. This is an easy way to discover how many EDID blocks
+there are. Note that if there are no EDID blocks available at all, then
+the driver will set ``blocks`` to 0 and it returns 0.
+
+To set the EDID blocks of a receiver the application has to fill in the
+``pad``, ``blocks`` and ``edid`` fields, set ``start_block`` to 0 and
+zero the ``reserved`` array. It is not possible to set part of an EDID,
+it is always all or nothing. Setting the EDID data is only valid for
+receivers as it makes no sense for a transmitter.
+
+The driver assumes that the full EDID is passed in. If there are more
+EDID blocks than the hardware can handle then the EDID is not written,
+but instead the error code ``E2BIG`` is set and ``blocks`` is set to the
+maximum that the hardware supports. If ``start_block`` is any value
+other than 0 then the error code ``EINVAL`` is set.
+
+To disable an EDID you set ``blocks`` to 0. Depending on the hardware
+this will drive the hotplug pin low and/or block the source from reading
+the EDID data in some way. In any case, the end result is the same: the
+EDID is no longer available.
+
+
+.. _v4l2-edid:
+
+.. flat-table:: struct v4l2_edid
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``pad``
+
+ - Pad for which to get/set the EDID blocks. When used with a video
+ device node the pad represents the input or output index as
+ returned by :ref:`VIDIOC_ENUMINPUT` and
+ :ref:`VIDIOC_ENUMOUTPUT` respectively.
+
+ - .. row 2
+
+ - __u32
+
+ - ``start_block``
+
+ - Read the EDID from starting with this block. Must be 0 when
+ setting the EDID.
+
+ - .. row 3
+
+ - __u32
+
+ - ``blocks``
+
+ - The number of blocks to get or set. Must be less or equal to 256
+ (the maximum number of blocks as defined by the standard). When
+ you set the EDID and ``blocks`` is 0, then the EDID is disabled or
+ erased.
+
+ - .. row 4
+
+ - __u32
+
+ - ``reserved``\ [5]
+
+ - Reserved for future extensions. Applications and drivers must set
+ the array to zero.
+
+ - .. row 5
+
+ - __u8 *
+
+ - ``edid``
+
+ - Pointer to memory that contains the EDID. The minimum size is
+ ``blocks`` * 128.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+``ENODATA``
+ The EDID data is not available.
+
+``E2BIG``
+ The EDID data you provided is more than the hardware can handle.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_G_ENC_INDEX:
+
+************************
+ioctl VIDIOC_G_ENC_INDEX
+************************
+
+Name
+====
+
+VIDIOC_G_ENC_INDEX - Get meta data about a compressed video stream
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_enc_idx *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_ENC_INDEX
+
+``argp``
+
+
+Description
+===========
+
+The :ref:`VIDIOC_G_ENC_INDEX <VIDIOC_G_ENC_INDEX>` ioctl provides meta data about a compressed
+video stream the same or another application currently reads from the
+driver, which is useful for random access into the stream without
+decoding it.
+
+To read the data applications must call :ref:`VIDIOC_G_ENC_INDEX <VIDIOC_G_ENC_INDEX>` with a
+pointer to a struct :ref:`v4l2_enc_idx <v4l2-enc-idx>`. On success
+the driver fills the ``entry`` array, stores the number of elements
+written in the ``entries`` field, and initializes the ``entries_cap``
+field.
+
+Each element of the ``entry`` array contains meta data about one
+picture. A :ref:`VIDIOC_G_ENC_INDEX <VIDIOC_G_ENC_INDEX>` call reads up to
+``V4L2_ENC_IDX_ENTRIES`` entries from a driver buffer, which can hold up
+to ``entries_cap`` entries. This number can be lower or higher than
+``V4L2_ENC_IDX_ENTRIES``, but not zero. When the application fails to
+read the meta data in time the oldest entries will be lost. When the
+buffer is empty or no capturing/encoding is in progress, ``entries``
+will be zero.
+
+Currently this ioctl is only defined for MPEG-2 program streams and
+video elementary streams.
+
+
+.. _v4l2-enc-idx:
+
+.. flat-table:: struct v4l2_enc_idx
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2 1 1
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``entries``
+
+ - The number of entries the driver stored in the ``entry`` array.
+
+ - .. row 2
+
+ - __u32
+
+ - ``entries_cap``
+
+ - The number of entries the driver can buffer. Must be greater than
+ zero.
+
+ - .. row 3
+
+ - __u32
+
+ - ``reserved``\ [4]
+
+ - :cspan:`2` Reserved for future extensions. Drivers must set the
+ array to zero.
+
+ - .. row 4
+
+ - struct :ref:`v4l2_enc_idx_entry <v4l2-enc-idx-entry>`
+
+ - ``entry``\ [``V4L2_ENC_IDX_ENTRIES``]
+
+ - Meta data about a compressed video stream. Each element of the
+ array corresponds to one picture, sorted in ascending order by
+ their ``offset``.
+
+
+
+.. _v4l2-enc-idx-entry:
+
+.. flat-table:: struct v4l2_enc_idx_entry
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u64
+
+ - ``offset``
+
+ - The offset in bytes from the beginning of the compressed video
+ stream to the beginning of this picture, that is a *PES packet
+ header* as defined in :ref:`mpeg2part1` or a *picture header* as
+ defined in :ref:`mpeg2part2`. When the encoder is stopped, the
+ driver resets the offset to zero.
+
+ - .. row 2
+
+ - __u64
+
+ - ``pts``
+
+ - The 33 bit *Presentation Time Stamp* of this picture as defined in
+ :ref:`mpeg2part1`.
+
+ - .. row 3
+
+ - __u32
+
+ - ``length``
+
+ - The length of this picture in bytes.
+
+ - .. row 4
+
+ - __u32
+
+ - ``flags``
+
+ - Flags containing the coding type of this picture, see
+ :ref:`enc-idx-flags`.
+
+ - .. row 5
+
+ - __u32
+
+ - ``reserved``\ [2]
+
+ - Reserved for future extensions. Drivers must set the array to
+ zero.
+
+
+
+.. _enc-idx-flags:
+
+.. flat-table:: Index Entry Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_ENC_IDX_FRAME_I``
+
+ - 0x00
+
+ - This is an Intra-coded picture.
+
+ - .. row 2
+
+ - ``V4L2_ENC_IDX_FRAME_P``
+
+ - 0x01
+
+ - This is a Predictive-coded picture.
+
+ - .. row 3
+
+ - ``V4L2_ENC_IDX_FRAME_B``
+
+ - 0x02
+
+ - This is a Bidirectionally predictive-coded picture.
+
+ - .. row 4
+
+ - ``V4L2_ENC_IDX_FRAME_MASK``
+
+ - 0x0F
+
+ - *AND* the flags field with this mask to obtain the picture coding
+ type.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_G_EXT_CTRLS:
+
+******************************************************************
+ioctl VIDIOC_G_EXT_CTRLS, VIDIOC_S_EXT_CTRLS, VIDIOC_TRY_EXT_CTRLS
+******************************************************************
+
+Name
+====
+
+VIDIOC_G_EXT_CTRLS - VIDIOC_S_EXT_CTRLS - VIDIOC_TRY_EXT_CTRLS - Get or set the value of several controls, try control values
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_ext_controls *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_EXT_CTRLS, VIDIOC_S_EXT_CTRLS,
+ VIDIOC_TRY_EXT_CTRLS
+
+``argp``
+
+
+Description
+===========
+
+These ioctls allow the caller to get or set multiple controls
+atomically. Control IDs are grouped into control classes (see
+:ref:`ctrl-class`) and all controls in the control array must belong
+to the same control class.
+
+Applications must always fill in the ``count``, ``which``, ``controls``
+and ``reserved`` fields of struct
+:ref:`v4l2_ext_controls <v4l2-ext-controls>`, and initialize the
+struct :ref:`v4l2_ext_control <v4l2-ext-control>` array pointed to
+by the ``controls`` fields.
+
+To get the current value of a set of controls applications initialize
+the ``id``, ``size`` and ``reserved2`` fields of each struct
+:ref:`v4l2_ext_control <v4l2-ext-control>` and call the
+:ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctl. String controls controls must also set the
+``string`` field. Controls of compound types
+(``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is set) must set the ``ptr`` field.
+
+If the ``size`` is too small to receive the control result (only
+relevant for pointer-type controls like strings), then the driver will
+set ``size`` to a valid value and return an ``ENOSPC`` error code. You
+should re-allocate the memory to this new size and try again. For the
+string type it is possible that the same issue occurs again if the
+string has grown in the meantime. It is recommended to call
+:ref:`VIDIOC_QUERYCTRL` first and use
+``maximum``\ +1 as the new ``size`` value. It is guaranteed that that is
+sufficient memory.
+
+N-dimensional arrays are set and retrieved row-by-row. You cannot set a
+partial array, all elements have to be set or retrieved. The total size
+is calculated as ``elems`` * ``elem_size``. These values can be obtained
+by calling :ref:`VIDIOC_QUERY_EXT_CTRL <VIDIOC_QUERYCTRL>`.
+
+To change the value of a set of controls applications initialize the
+``id``, ``size``, ``reserved2`` and ``value/value64/string/ptr`` fields
+of each struct :ref:`v4l2_ext_control <v4l2-ext-control>` and call
+the :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctl. The controls will only be set if *all*
+control values are valid.
+
+To check if a set of controls have correct values applications
+initialize the ``id``, ``size``, ``reserved2`` and
+``value/value64/string/ptr`` fields of each struct
+:ref:`v4l2_ext_control <v4l2-ext-control>` and call the
+:ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctl. It is up to the driver whether wrong
+values are automatically adjusted to a valid value or if an error is
+returned.
+
+When the ``id`` or ``which`` is invalid drivers return an ``EINVAL`` error
+code. When the value is out of bounds drivers can choose to take the
+closest valid value or return an ``ERANGE`` error code, whatever seems more
+appropriate. In the first case the new value is set in struct
+:ref:`v4l2_ext_control <v4l2-ext-control>`. If the new control value
+is inappropriate (e.g. the given menu index is not supported by the menu
+control), then this will also result in an ``EINVAL`` error code error.
+
+The driver will only set/get these controls if all control values are
+correct. This prevents the situation where only some of the controls
+were set/get. Only low-level errors (e. g. a failed i2c command) can
+still cause this situation.
+
+
+.. _v4l2-ext-control:
+
+.. flat-table:: struct v4l2_ext_control
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``id``
+
+ -
+ - Identifies the control, set by the application.
+
+ - .. row 2
+
+ - __u32
+
+ - ``size``
+
+ -
+ - The total size in bytes of the payload of this control. This is
+ normally 0, but for pointer controls this should be set to the
+ size of the memory containing the payload, or that will receive
+ the payload. If :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` finds that this value is
+ less than is required to store the payload result, then it is set
+ to a value large enough to store the payload result and ``ENOSPC`` is
+ returned. Note that for string controls this ``size`` field should
+ not be confused with the length of the string. This field refers
+ to the size of the memory that contains the string. The actual
+ *length* of the string may well be much smaller.
+
+ - .. row 3
+
+ - __u32
+
+ - ``reserved2``\ [1]
+
+ -
+ - Reserved for future extensions. Drivers and applications must set
+ the array to zero.
+
+ - .. row 4
+
+ - union
+
+ - (anonymous)
+
+ - .. row 5
+
+ -
+ - __s32
+
+ - ``value``
+
+ - New value or current value. Valid if this control is not of type
+ ``V4L2_CTRL_TYPE_INTEGER64`` and ``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is
+ not set.
+
+ - .. row 6
+
+ -
+ - __s64
+
+ - ``value64``
+
+ - New value or current value. Valid if this control is of type
+ ``V4L2_CTRL_TYPE_INTEGER64`` and ``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is
+ not set.
+
+ - .. row 7
+
+ -
+ - char *
+
+ - ``string``
+
+ - A pointer to a string. Valid if this control is of type
+ ``V4L2_CTRL_TYPE_STRING``.
+
+ - .. row 8
+
+ -
+ - __u8 *
+
+ - ``p_u8``
+
+ - A pointer to a matrix control of unsigned 8-bit values. Valid if
+ this control is of type ``V4L2_CTRL_TYPE_U8``.
+
+ - .. row 9
+
+ -
+ - __u16 *
+
+ - ``p_u16``
+
+ - A pointer to a matrix control of unsigned 16-bit values. Valid if
+ this control is of type ``V4L2_CTRL_TYPE_U16``.
+
+ - .. row 10
+
+ -
+ - __u32 *
+
+ - ``p_u32``
+
+ - A pointer to a matrix control of unsigned 32-bit values. Valid if
+ this control is of type ``V4L2_CTRL_TYPE_U32``.
+
+ - .. row 11
+
+ -
+ - void *
+
+ - ``ptr``
+
+ - A pointer to a compound type which can be an N-dimensional array
+ and/or a compound type (the control's type is >=
+ ``V4L2_CTRL_COMPOUND_TYPES``). Valid if
+ ``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is set for this control.
+
+
+
+.. _v4l2-ext-controls:
+
+.. flat-table:: struct v4l2_ext_controls
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2 1
+
+
+ - .. row 1
+
+ - union
+
+ - (anonymous)
+
+ - .. row 2
+
+ -
+ - __u32
+
+ - ``ctrl_class``
+
+ - The control class to which all controls belong, see
+ :ref:`ctrl-class`. Drivers that use a kernel framework for
+ handling controls will also accept a value of 0 here, meaning that
+ the controls can belong to any control class. Whether drivers
+ support this can be tested by setting ``ctrl_class`` to 0 and
+ calling :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` with a ``count`` of 0. If that
+ succeeds, then the driver supports this feature.
+
+ - .. row 3
+
+ -
+ - __u32
+
+ - ``which``
+
+ - Which value of the control to get/set/try.
+ ``V4L2_CTRL_WHICH_CUR_VAL`` will return the current value of the
+ control and ``V4L2_CTRL_WHICH_DEF_VAL`` will return the default
+ value of the control. Please note that you can only get the
+ default value of the control, you cannot set or try it.
+
+ For backwards compatibility you can also use a control class here
+ (see :ref:`ctrl-class`). In that case all controls have to
+ belong to that control class. This usage is deprecated, instead
+ just use ``V4L2_CTRL_WHICH_CUR_VAL``. There are some very old
+ drivers that do not yet support ``V4L2_CTRL_WHICH_CUR_VAL`` and
+ that require a control class here. You can test for such drivers
+ by setting ctrl_class to ``V4L2_CTRL_WHICH_CUR_VAL`` and calling
+ VIDIOC_TRY_EXT_CTRLS with a count of 0. If that fails, then the
+ driver does not support ``V4L2_CTRL_WHICH_CUR_VAL``.
+
+ - .. row 4
+
+ - __u32
+
+ - ``count``
+
+ - The number of controls in the controls array. May also be zero.
+
+ - .. row 5
+
+ - __u32
+
+ - ``error_idx``
+
+ - Set by the driver in case of an error. If the error is associated
+ with a particular control, then ``error_idx`` is set to the index
+ of that control. If the error is not related to a specific
+ control, or the validation step failed (see below), then
+ ``error_idx`` is set to ``count``. The value is undefined if the
+ ioctl returned 0 (success).
+
+ Before controls are read from/written to hardware a validation
+ step takes place: this checks if all controls in the list are
+ valid controls, if no attempt is made to write to a read-only
+ control or read from a write-only control, and any other up-front
+ checks that can be done without accessing the hardware. The exact
+ validations done during this step are driver dependent since some
+ checks might require hardware access for some devices, thus making
+ it impossible to do those checks up-front. However, drivers should
+ make a best-effort to do as many up-front checks as possible.
+
+ This check is done to avoid leaving the hardware in an
+ inconsistent state due to easy-to-avoid problems. But it leads to
+ another problem: the application needs to know whether an error
+ came from the validation step (meaning that the hardware was not
+ touched) or from an error during the actual reading from/writing
+ to hardware.
+
+ The, in hindsight quite poor, solution for that is to set
+ ``error_idx`` to ``count`` if the validation failed. This has the
+ unfortunate side-effect that it is not possible to see which
+ control failed the validation. If the validation was successful
+ and the error happened while accessing the hardware, then
+ ``error_idx`` is less than ``count`` and only the controls up to
+ ``error_idx-1`` were read or written correctly, and the state of
+ the remaining controls is undefined.
+
+ Since :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` does not access hardware there is
+ also no need to handle the validation step in this special way, so
+ ``error_idx`` will just be set to the control that failed the
+ validation step instead of to ``count``. This means that if
+ :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` fails with ``error_idx`` set to ``count``,
+ then you can call :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` to try to discover the
+ actual control that failed the validation step. Unfortunately,
+ there is no ``TRY`` equivalent for :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`.
+
+ - .. row 6
+
+ - __u32
+
+ - ``reserved``\ [2]
+
+ - Reserved for future extensions. Drivers and applications must set
+ the array to zero.
+
+ - .. row 7
+
+ - struct :ref:`v4l2_ext_control <v4l2-ext-control>` *
+
+ - ``controls``
+
+ - Pointer to an array of ``count`` v4l2_ext_control structures.
+ Ignored if ``count`` equals zero.
+
+
+
+.. _ctrl-class:
+
+.. flat-table:: Control classes
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_CTRL_CLASS_USER``
+
+ - 0x980000
+
+ - The class containing user controls. These controls are described
+ in :ref:`control`. All controls that can be set using the
+ :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` and
+ :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` ioctl belong to this
+ class.
+
+ - .. row 2
+
+ - ``V4L2_CTRL_CLASS_MPEG``
+
+ - 0x990000
+
+ - The class containing MPEG compression controls. These controls are
+ described in :ref:`mpeg-controls`.
+
+ - .. row 3
+
+ - ``V4L2_CTRL_CLASS_CAMERA``
+
+ - 0x9a0000
+
+ - The class containing camera controls. These controls are described
+ in :ref:`camera-controls`.
+
+ - .. row 4
+
+ - ``V4L2_CTRL_CLASS_FM_TX``
+
+ - 0x9b0000
+
+ - The class containing FM Transmitter (FM TX) controls. These
+ controls are described in :ref:`fm-tx-controls`.
+
+ - .. row 5
+
+ - ``V4L2_CTRL_CLASS_FLASH``
+
+ - 0x9c0000
+
+ - The class containing flash device controls. These controls are
+ described in :ref:`flash-controls`.
+
+ - .. row 6
+
+ - ``V4L2_CTRL_CLASS_JPEG``
+
+ - 0x9d0000
+
+ - The class containing JPEG compression controls. These controls are
+ described in :ref:`jpeg-controls`.
+
+ - .. row 7
+
+ - ``V4L2_CTRL_CLASS_IMAGE_SOURCE``
+
+ - 0x9e0000
+
+ - The class containing image source controls. These controls are
+ described in :ref:`image-source-controls`.
+
+ - .. row 8
+
+ - ``V4L2_CTRL_CLASS_IMAGE_PROC``
+
+ - 0x9f0000
+
+ - The class containing image processing controls. These controls are
+ described in :ref:`image-process-controls`.
+
+ - .. row 9
+
+ - ``V4L2_CTRL_CLASS_FM_RX``
+
+ - 0xa10000
+
+ - The class containing FM Receiver (FM RX) controls. These controls
+ are described in :ref:`fm-rx-controls`.
+
+ - .. row 10
+
+ - ``V4L2_CTRL_CLASS_RF_TUNER``
+
+ - 0xa20000
+
+ - The class containing RF tuner controls. These controls are
+ described in :ref:`rf-tuner-controls`.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The struct :ref:`v4l2_ext_control <v4l2-ext-control>` ``id`` is
+ invalid, the struct :ref:`v4l2_ext_controls <v4l2-ext-controls>`
+ ``which`` is invalid, or the struct
+ :ref:`v4l2_ext_control <v4l2-ext-control>` ``value`` was
+ inappropriate (e.g. the given menu index is not supported by the
+ driver). This error code is also returned by the
+ :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` and :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctls if two or
+ more control values are in conflict.
+
+ERANGE
+ The struct :ref:`v4l2_ext_control <v4l2-ext-control>` ``value``
+ is out of bounds.
+
+EBUSY
+ The control is temporarily not changeable, possibly because another
+ applications took over control of the device function this control
+ belongs to.
+
+ENOSPC
+ The space reserved for the control's payload is insufficient. The
+ field ``size`` is set to a value that is enough to store the payload
+ and this error code is returned.
+
+EACCES
+ Attempt to try or set a read-only control or to get a write-only
+ control.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_G_FBUF:
+
+**********************************
+ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF
+**********************************
+
+Name
+====
+
+VIDIOC_G_FBUF - VIDIOC_S_FBUF - Get or set frame buffer overlay parameters
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_framebuffer *argp )
+
+.. cpp:function:: int ioctl( int fd, int request, const struct v4l2_framebuffer *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_FBUF, VIDIOC_S_FBUF
+
+``argp``
+
+
+Description
+===========
+
+Applications can use the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` and :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctl
+to get and set the framebuffer parameters for a
+:ref:`Video Overlay <overlay>` or :ref:`Video Output Overlay <osd>`
+(OSD). The type of overlay is implied by the device type (capture or
+output device) and can be determined with the
+:ref:`VIDIOC_QUERYCAP` ioctl. One ``/dev/videoN``
+device must not support both kinds of overlay.
+
+The V4L2 API distinguishes destructive and non-destructive overlays. A
+destructive overlay copies captured video images into the video memory
+of a graphics card. A non-destructive overlay blends video images into a
+VGA signal or graphics into a video signal. *Video Output Overlays* are
+always non-destructive.
+
+To get the current parameters applications call the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`
+ioctl with a pointer to a :ref:`struct v4l2_framebuffer <v4l2-framebuffer>`
+structure. The driver fills all fields of the structure or returns an
+EINVAL error code when overlays are not supported.
+
+To set the parameters for a *Video Output Overlay*, applications must
+initialize the ``flags`` field of a struct
+:ref:`struct v4l2_framebuffer <v4l2-framebuffer>`. Since the framebuffer is
+implemented on the TV card all other parameters are determined by the
+driver. When an application calls :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` with a pointer to
+this structure, the driver prepares for the overlay and returns the
+framebuffer parameters as :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` does, or it returns an error
+code.
+
+To set the parameters for a *non-destructive Video Overlay*,
+applications must initialize the ``flags`` field, the ``fmt``
+substructure, and call :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`. Again the driver prepares for
+the overlay and returns the framebuffer parameters as :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`
+does, or it returns an error code.
+
+For a *destructive Video Overlay* applications must additionally provide
+a ``base`` address. Setting up a DMA to a random memory location can
+jeopardize the system security, its stability or even damage the
+hardware, therefore only the superuser can set the parameters for a
+destructive video overlay.
+
+
+.. _v4l2-framebuffer:
+
+.. flat-table:: struct v4l2_framebuffer
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``capability``
+
+ -
+ - Overlay capability flags set by the driver, see
+ :ref:`framebuffer-cap`.
+
+ - .. row 2
+
+ - __u32
+
+ - ``flags``
+
+ -
+ - Overlay control flags set by application and driver, see
+ :ref:`framebuffer-flags`
+
+ - .. row 3
+
+ - void *
+
+ - ``base``
+
+ -
+ - Physical base address of the framebuffer, that is the address of
+ the pixel in the top left corner of the framebuffer. [1]_
+
+ - .. row 4
+
+ -
+ -
+ -
+ - This field is irrelevant to *non-destructive Video Overlays*. For
+ *destructive Video Overlays* applications must provide a base
+ address. The driver may accept only base addresses which are a
+ multiple of two, four or eight bytes. For *Video Output Overlays*
+ the driver must return a valid base address, so applications can
+ find the corresponding Linux framebuffer device (see
+ :ref:`osd`).
+
+ - .. row 5
+
+ - struct
+
+ - ``fmt``
+
+ -
+ - Layout of the frame buffer.
+
+ - .. row 6
+
+ -
+ - __u32
+
+ - ``width``
+
+ - Width of the frame buffer in pixels.
+
+ - .. row 7
+
+ -
+ - __u32
+
+ - ``height``
+
+ - Height of the frame buffer in pixels.
+
+ - .. row 8
+
+ -
+ - __u32
+
+ - ``pixelformat``
+
+ - The pixel format of the framebuffer.
+
+ - .. row 9
+
+ -
+ -
+ -
+ - For *non-destructive Video Overlays* this field only defines a
+ format for the struct :ref:`v4l2_window <v4l2-window>`
+ ``chromakey`` field.
+
+ - .. row 10
+
+ -
+ -
+ -
+ - For *destructive Video Overlays* applications must initialize this
+ field. For *Video Output Overlays* the driver must return a valid
+ format.
+
+ - .. row 11
+
+ -
+ -
+ -
+ - Usually this is an RGB format (for example
+ :ref:`V4L2_PIX_FMT_RGB565 <V4L2-PIX-FMT-RGB565>`) but YUV
+ formats (only packed YUV formats when chroma keying is used, not
+ including ``V4L2_PIX_FMT_YUYV`` and ``V4L2_PIX_FMT_UYVY``) and the
+ ``V4L2_PIX_FMT_PAL8`` format are also permitted. The behavior of
+ the driver when an application requests a compressed format is
+ undefined. See :ref:`pixfmt` for information on pixel formats.
+
+ - .. row 12
+
+ -
+ - enum :ref:`v4l2_field <v4l2-field>`
+
+ - ``field``
+
+ - Drivers and applications shall ignore this field. If applicable,
+ the field order is selected with the
+ :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, using the ``field``
+ field of struct :ref:`v4l2_window <v4l2-window>`.
+
+ - .. row 13
+
+ -
+ - __u32
+
+ - ``bytesperline``
+
+ - Distance in bytes between the leftmost pixels in two adjacent
+ lines.
+
+ - .. row 14
+
+ - :cspan:`3`
+
+ This field is irrelevant to *non-destructive Video Overlays*.
+
+ For *destructive Video Overlays* both applications and drivers can
+ set this field to request padding bytes at the end of each line.
+ Drivers however may ignore the requested value, returning
+ ``width`` times bytes-per-pixel or a larger value required by the
+ hardware. That implies applications can just set this field to
+ zero to get a reasonable default.
+
+ For *Video Output Overlays* the driver must return a valid value.
+
+ Video hardware may access padding bytes, therefore they must
+ reside in accessible memory. Consider for example the case where
+ padding bytes after the last line of an image cross a system page
+ boundary. Capture devices may write padding bytes, the value is
+ undefined. Output devices ignore the contents of padding bytes.
+
+ When the image format is planar the ``bytesperline`` value applies
+ to the first plane and is divided by the same factor as the
+ ``width`` field for the other planes. For example the Cb and Cr
+ planes of a YUV 4:2:0 image have half as many padding bytes
+ following each line as the Y plane. To avoid ambiguities drivers
+ must return a ``bytesperline`` value rounded up to a multiple of
+ the scale factor.
+
+ - .. row 15
+
+ -
+ - __u32
+
+ - ``sizeimage``
+
+ - This field is irrelevant to *non-destructive Video Overlays*. For
+ *destructive Video Overlays* applications must initialize this
+ field. For *Video Output Overlays* the driver must return a valid
+ format.
+
+ Together with ``base`` it defines the framebuffer memory
+ accessible by the driver.
+
+ - .. row 16
+
+ -
+ - enum :ref:`v4l2_colorspace <v4l2-colorspace>`
+
+ - ``colorspace``
+
+ - This information supplements the ``pixelformat`` and must be set
+ by the driver, see :ref:`colorspaces`.
+
+ - .. row 17
+
+ -
+ - __u32
+
+ - ``priv``
+
+ - Reserved. Drivers and applications must set this field to zero.
+
+
+
+.. _framebuffer-cap:
+
+.. flat-table:: Frame Buffer Capability Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_FBUF_CAP_EXTERNOVERLAY``
+
+ - 0x0001
+
+ - The device is capable of non-destructive overlays. When the driver
+ clears this flag, only destructive overlays are supported. There
+ are no drivers yet which support both destructive and
+ non-destructive overlays. Video Output Overlays are in practice
+ always non-destructive.
+
+ - .. row 2
+
+ - ``V4L2_FBUF_CAP_CHROMAKEY``
+
+ - 0x0002
+
+ - The device supports clipping by chroma-keying the images. That is,
+ image pixels replace pixels in the VGA or video signal only where
+ the latter assume a certain color. Chroma-keying makes no sense
+ for destructive overlays.
+
+ - .. row 3
+
+ - ``V4L2_FBUF_CAP_LIST_CLIPPING``
+
+ - 0x0004
+
+ - The device supports clipping using a list of clip rectangles.
+
+ - .. row 4
+
+ - ``V4L2_FBUF_CAP_BITMAP_CLIPPING``
+
+ - 0x0008
+
+ - The device supports clipping using a bit mask.
+
+ - .. row 5
+
+ - ``V4L2_FBUF_CAP_LOCAL_ALPHA``
+
+ - 0x0010
+
+ - The device supports clipping/blending using the alpha channel of
+ the framebuffer or VGA signal. Alpha blending makes no sense for
+ destructive overlays.
+
+ - .. row 6
+
+ - ``V4L2_FBUF_CAP_GLOBAL_ALPHA``
+
+ - 0x0020
+
+ - The device supports alpha blending using a global alpha value.
+ Alpha blending makes no sense for destructive overlays.
+
+ - .. row 7
+
+ - ``V4L2_FBUF_CAP_LOCAL_INV_ALPHA``
+
+ - 0x0040
+
+ - The device supports clipping/blending using the inverted alpha
+ channel of the framebuffer or VGA signal. Alpha blending makes no
+ sense for destructive overlays.
+
+ - .. row 8
+
+ - ``V4L2_FBUF_CAP_SRC_CHROMAKEY``
+
+ - 0x0080
+
+ - The device supports Source Chroma-keying. Video pixels with the
+ chroma-key colors are replaced by framebuffer pixels, which is
+ exactly opposite of ``V4L2_FBUF_CAP_CHROMAKEY``
+
+
+
+.. _framebuffer-flags:
+
+.. flat-table:: Frame Buffer Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_FBUF_FLAG_PRIMARY``
+
+ - 0x0001
+
+ - The framebuffer is the primary graphics surface. In other words,
+ the overlay is destructive. This flag is typically set by any
+ driver that doesn't have the ``V4L2_FBUF_CAP_EXTERNOVERLAY``
+ capability and it is cleared otherwise.
+
+ - .. row 2
+
+ - ``V4L2_FBUF_FLAG_OVERLAY``
+
+ - 0x0002
+
+ - If this flag is set for a video capture device, then the driver
+ will set the initial overlay size to cover the full framebuffer
+ size, otherwise the existing overlay size (as set by
+ :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`) will be used. Only one
+ video capture driver (bttv) supports this flag. The use of this
+ flag for capture devices is deprecated. There is no way to detect
+ which drivers support this flag, so the only reliable method of
+ setting the overlay size is through
+ :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. If this flag is set for a
+ video output device, then the video output overlay window is
+ relative to the top-left corner of the framebuffer and restricted
+ to the size of the framebuffer. If it is cleared, then the video
+ output overlay window is relative to the video output display.
+
+ - .. row 3
+
+ - ``V4L2_FBUF_FLAG_CHROMAKEY``
+
+ - 0x0004
+
+ - Use chroma-keying. The chroma-key color is determined by the
+ ``chromakey`` field of struct :ref:`v4l2_window <v4l2-window>`
+ and negotiated with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
+ ioctl, see :ref:`overlay` and :ref:`osd`.
+
+ - .. row 4
+
+ - :cspan:`2` There are no flags to enable clipping using a list of
+ clip rectangles or a bitmap. These methods are negotiated with the
+ :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay`
+ and :ref:`osd`.
+
+ - .. row 5
+
+ - ``V4L2_FBUF_FLAG_LOCAL_ALPHA``
+
+ - 0x0008
+
+ - Use the alpha channel of the framebuffer to clip or blend
+ framebuffer pixels with video images. The blend function is:
+ output = framebuffer pixel * alpha + video pixel * (1 - alpha).
+ The actual alpha depth depends on the framebuffer pixel format.
+
+ - .. row 6
+
+ - ``V4L2_FBUF_FLAG_GLOBAL_ALPHA``
+
+ - 0x0010
+
+ - Use a global alpha value to blend the framebuffer with video
+ images. The blend function is: output = (framebuffer pixel * alpha
+ + video pixel * (255 - alpha)) / 255. The alpha value is
+ determined by the ``global_alpha`` field of struct
+ :ref:`v4l2_window <v4l2-window>` and negotiated with the
+ :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay`
+ and :ref:`osd`.
+
+ - .. row 7
+
+ - ``V4L2_FBUF_FLAG_LOCAL_INV_ALPHA``
+
+ - 0x0020
+
+ - Like ``V4L2_FBUF_FLAG_LOCAL_ALPHA``, use the alpha channel of the
+ framebuffer to clip or blend framebuffer pixels with video images,
+ but with an inverted alpha value. The blend function is: output =
+ framebuffer pixel * (1 - alpha) + video pixel * alpha. The actual
+ alpha depth depends on the framebuffer pixel format.
+
+ - .. row 8
+
+ - ``V4L2_FBUF_FLAG_SRC_CHROMAKEY``
+
+ - 0x0040
+
+ - Use source chroma-keying. The source chroma-key color is
+ determined by the ``chromakey`` field of struct
+ :ref:`v4l2_window <v4l2-window>` and negotiated with the
+ :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay`
+ and :ref:`osd`. Both chroma-keying are mutual exclusive to each
+ other, so same ``chromakey`` field of struct
+ :ref:`v4l2_window <v4l2-window>` is being used.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EPERM
+ :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` can only be called by a privileged user to
+ negotiate the parameters for a destructive overlay.
+
+EINVAL
+ The :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` parameters are unsuitable.
+
+.. [1]
+ A physical base address may not suit all platforms. GK notes in
+ theory we should pass something like PCI device + memory region +
+ offset instead. If you encounter problems please discuss on the
+ linux-media mailing list:
+ `https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_G_FMT:
+
+************************************************
+ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT
+************************************************
+
+Name
+====
+
+VIDIOC_G_FMT - VIDIOC_S_FMT - VIDIOC_TRY_FMT - Get or set the data format, try a format
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_format *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT
+
+``argp``
+
+
+Description
+===========
+
+These ioctls are used to negotiate the format of data (typically image
+format) exchanged between driver and application.
+
+To query the current parameters applications set the ``type`` field of a
+struct :ref:`struct v4l2_format <v4l2-format>` to the respective buffer (stream)
+type. For example video capture devices use
+``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or
+``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``. When the application calls the
+:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl with a pointer to this structure the driver fills
+the respective member of the ``fmt`` union. In case of video capture
+devices that is either the struct
+:ref:`v4l2_pix_format <v4l2-pix-format>` ``pix`` or the struct
+:ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` ``pix_mp``
+member. When the requested buffer type is not supported drivers return
+an ``EINVAL`` error code.
+
+To change the current format parameters applications initialize the
+``type`` field and all fields of the respective ``fmt`` union member.
+For details see the documentation of the various devices types in
+:ref:`devices`. Good practice is to query the current parameters
+first, and to modify only those parameters not suitable for the
+application. When the application calls the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with
+a pointer to a :ref:`struct v4l2_format <v4l2-format>` structure the driver
+checks and adjusts the parameters against hardware abilities. Drivers
+should not return an error code unless the ``type`` field is invalid,
+this is a mechanism to fathom device capabilities and to approach
+parameters acceptable for both the application and driver. On success
+the driver may program the hardware, allocate resources and generally
+prepare for data exchange. Finally the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl returns
+the current format parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. Very simple,
+inflexible devices may even ignore all input and always return the
+default parameters. However all V4L2 devices exchanging data with the
+application must implement the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
+ioctl. When the requested buffer type is not supported drivers return an
+EINVAL error code on a :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` attempt. When I/O is already in
+progress or the resource is not available for other reasons drivers
+return the ``EBUSY`` error code.
+
+The :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl is equivalent to :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` with one
+exception: it does not change driver state. It can also be called at any
+time, never returning ``EBUSY``. This function is provided to negotiate
+parameters, to learn about hardware limitations, without disabling I/O
+or possibly time consuming hardware preparations. Although strongly
+recommended drivers are not required to implement this ioctl.
+
+The format as returned by :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` must be identical to what
+:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` returns for the same input or output.
+
+
+.. _v4l2-format:
+
+.. flat-table:: struct v4l2_format
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``type``
+
+ -
+ - Type of the data stream, see :ref:`v4l2-buf-type`.
+
+ - .. row 2
+
+ - union
+
+ - ``fmt``
+
+ - .. row 3
+
+ -
+ - struct :ref:`v4l2_pix_format <v4l2-pix-format>`
+
+ - ``pix``
+
+ - Definition of an image format, see :ref:`pixfmt`, used by video
+ capture and output devices.
+
+ - .. row 4
+
+ -
+ - struct :ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>`
+
+ - ``pix_mp``
+
+ - Definition of an image format, see :ref:`pixfmt`, used by video
+ capture and output devices that support the
+ :ref:`multi-planar version of the API <planar-apis>`.
+
+ - .. row 5
+
+ -
+ - struct :ref:`v4l2_window <v4l2-window>`
+
+ - ``win``
+
+ - Definition of an overlaid image, see :ref:`overlay`, used by
+ video overlay devices.
+
+ - .. row 6
+
+ -
+ - struct :ref:`v4l2_vbi_format <v4l2-vbi-format>`
+
+ - ``vbi``
+
+ - Raw VBI capture or output parameters. This is discussed in more
+ detail in :ref:`raw-vbi`. Used by raw VBI capture and output
+ devices.
+
+ - .. row 7
+
+ -
+ - struct :ref:`v4l2_sliced_vbi_format <v4l2-sliced-vbi-format>`
+
+ - ``sliced``
+
+ - Sliced VBI capture or output parameters. See :ref:`sliced` for
+ details. Used by sliced VBI capture and output devices.
+
+ - .. row 8
+
+ -
+ - struct :ref:`v4l2_sdr_format <v4l2-sdr-format>`
+
+ - ``sdr``
+
+ - Definition of a data format, see :ref:`pixfmt`, used by SDR
+ capture and output devices.
+
+ - .. row 9
+
+ -
+ - __u8
+
+ - ``raw_data``\ [200]
+
+ - Place holder for future extensions.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The struct :ref:`v4l2_format <v4l2-format>` ``type`` field is
+ invalid or the requested buffer type not supported.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_G_FREQUENCY:
+
+********************************************
+ioctl VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY
+********************************************
+
+Name
+====
+
+VIDIOC_G_FREQUENCY - VIDIOC_S_FREQUENCY - Get or set tuner or modulator radio frequency
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_frequency *argp )
+
+.. cpp:function:: int ioctl( int fd, int request, const struct v4l2_frequency *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY
+
+``argp``
+
+
+Description
+===========
+
+To get the current tuner or modulator radio frequency applications set
+the ``tuner`` field of a struct
+:ref:`v4l2_frequency <v4l2-frequency>` to the respective tuner or
+modulator number (only input devices have tuners, only output devices
+have modulators), zero out the ``reserved`` array and call the
+:ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl with a pointer to this structure. The
+driver stores the current frequency in the ``frequency`` field.
+
+To change the current tuner or modulator radio frequency applications
+initialize the ``tuner``, ``type`` and ``frequency`` fields, and the
+``reserved`` array of a struct :ref:`v4l2_frequency <v4l2-frequency>`
+and call the :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl with a pointer to this
+structure. When the requested frequency is not possible the driver
+assumes the closest possible value. However :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` is a
+write-only ioctl, it does not return the actual new frequency.
+
+
+.. _v4l2-frequency:
+
+.. flat-table:: struct v4l2_frequency
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``tuner``
+
+ - The tuner or modulator index number. This is the same value as in
+ the struct :ref:`v4l2_input <v4l2-input>` ``tuner`` field and
+ the struct :ref:`v4l2_tuner <v4l2-tuner>` ``index`` field, or
+ the struct :ref:`v4l2_output <v4l2-output>` ``modulator`` field
+ and the struct :ref:`v4l2_modulator <v4l2-modulator>` ``index``
+ field.
+
+ - .. row 2
+
+ - __u32
+
+ - ``type``
+
+ - The tuner type. This is the same value as in the struct
+ :ref:`v4l2_tuner <v4l2-tuner>` ``type`` field. The type must be
+ set to ``V4L2_TUNER_RADIO`` for ``/dev/radioX`` device nodes, and
+ to ``V4L2_TUNER_ANALOG_TV`` for all others. Set this field to
+ ``V4L2_TUNER_RADIO`` for modulators (currently only radio
+ modulators are supported). See :ref:`v4l2-tuner-type`
+
+ - .. row 3
+
+ - __u32
+
+ - ``frequency``
+
+ - Tuning frequency in units of 62.5 kHz, or if the struct
+ :ref:`v4l2_tuner <v4l2-tuner>` or struct
+ :ref:`v4l2_modulator <v4l2-modulator>` ``capability`` flag
+ ``V4L2_TUNER_CAP_LOW`` is set, in units of 62.5 Hz. A 1 Hz unit is
+ used when the ``capability`` flag ``V4L2_TUNER_CAP_1HZ`` is set.
+
+ - .. row 4
+
+ - __u32
+
+ - ``reserved``\ [8]
+
+ - Reserved for future extensions. Drivers and applications must set
+ the array to zero.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The ``tuner`` index is out of bounds or the value in the ``type``
+ field is wrong.
+
+EBUSY
+ A hardware seek is in progress.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_G_INPUT:
+
+************************************
+ioctl VIDIOC_G_INPUT, VIDIOC_S_INPUT
+************************************
+
+Name
+====
+
+VIDIOC_G_INPUT - VIDIOC_S_INPUT - Query or select the current video input
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, int *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_INPUT, VIDIOC_S_INPUT
+
+``argp``
+
+
+Description
+===========
+
+To query the current video input applications call the
+:ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` ioctl with a pointer to an integer where the driver
+stores the number of the input, as in the struct
+:ref:`v4l2_input <v4l2-input>` ``index`` field. This ioctl will fail
+only when there are no video inputs, returning ``EINVAL``.
+
+To select a video input applications store the number of the desired
+input in an integer and call the :ref:`VIDIOC_S_INPUT <VIDIOC_G_INPUT>` ioctl with a pointer
+to this integer. Side effects are possible. For example inputs may
+support different video standards, so the driver may implicitly switch
+the current standard. Because of these possible side effects
+applications must select an input before querying or negotiating any
+other parameters.
+
+Information about video inputs is available using the
+:ref:`VIDIOC_ENUMINPUT` ioctl.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The number of the video input is out of bounds.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_G_JPEGCOMP:
+
+******************************************
+ioctl VIDIOC_G_JPEGCOMP, VIDIOC_S_JPEGCOMP
+******************************************
+
+Name
+====
+
+VIDIOC_G_JPEGCOMP - VIDIOC_S_JPEGCOMP
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, v4l2_jpegcompression *argp )
+
+.. cpp:function:: int ioctl( int fd, int request, const v4l2_jpegcompression *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_JPEGCOMP, VIDIOC_S_JPEGCOMP
+
+``argp``
+
+
+Description
+===========
+
+These ioctls are **deprecated**. New drivers and applications should use
+:ref:`JPEG class controls <jpeg-controls>` for image quality and JPEG
+markers control.
+
+[to do]
+
+Ronald Bultje elaborates:
+
+APP is some application-specific information. The application can set it
+itself, and it'll be stored in the JPEG-encoded fields (eg; interlacing
+information for in an AVI or so). COM is the same, but it's comments,
+like 'encoded by me' or so.
+
+jpeg_markers describes whether the huffman tables, quantization tables
+and the restart interval information (all JPEG-specific stuff) should be
+stored in the JPEG-encoded fields. These define how the JPEG field is
+encoded. If you omit them, applications assume you've used standard
+encoding. You usually do want to add them.
+
+
+.. _v4l2-jpegcompression:
+
+.. flat-table:: struct v4l2_jpegcompression
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - int
+
+ - ``quality``
+
+ - Deprecated. If
+ :ref:`V4L2_CID_JPEG_COMPRESSION_QUALITY <jpeg-quality-control>`
+ control is exposed by a driver applications should use it instead
+ and ignore this field.
+
+ - .. row 2
+
+ - int
+
+ - ``APPn``
+
+ -
+
+ - .. row 3
+
+ - int
+
+ - ``APP_len``
+
+ -
+
+ - .. row 4
+
+ - char
+
+ - ``APP_data``\ [60]
+
+ -
+
+ - .. row 5
+
+ - int
+
+ - ``COM_len``
+
+ -
+
+ - .. row 6
+
+ - char
+
+ - ``COM_data``\ [60]
+
+ -
+
+ - .. row 7
+
+ - __u32
+
+ - ``jpeg_markers``
+
+ - See :ref:`jpeg-markers`. Deprecated. If
+ :ref:`V4L2_CID_JPEG_ACTIVE_MARKER <jpeg-active-marker-control>`
+ control is exposed by a driver applications should use it instead
+ and ignore this field.
+
+
+
+.. _jpeg-markers:
+
+.. flat-table:: JPEG Markers Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_JPEG_MARKER_DHT``
+
+ - (1<<3)
+
+ - Define Huffman Tables
+
+ - .. row 2
+
+ - ``V4L2_JPEG_MARKER_DQT``
+
+ - (1<<4)
+
+ - Define Quantization Tables
+
+ - .. row 3
+
+ - ``V4L2_JPEG_MARKER_DRI``
+
+ - (1<<5)
+
+ - Define Restart Interval
+
+ - .. row 4
+
+ - ``V4L2_JPEG_MARKER_COM``
+
+ - (1<<6)
+
+ - Comment segment
+
+ - .. row 5
+
+ - ``V4L2_JPEG_MARKER_APP``
+
+ - (1<<7)
+
+ - App segment, driver will always use APP0
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_G_MODULATOR:
+
+********************************************
+ioctl VIDIOC_G_MODULATOR, VIDIOC_S_MODULATOR
+********************************************
+
+Name
+====
+
+VIDIOC_G_MODULATOR - VIDIOC_S_MODULATOR - Get or set modulator attributes
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_modulator *argp )
+
+.. cpp:function:: int ioctl( int fd, int request, const struct v4l2_modulator *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_MODULATOR, VIDIOC_S_MODULATOR
+
+``argp``
+
+
+Description
+===========
+
+To query the attributes of a modulator applications initialize the
+``index`` field and zero out the ``reserved`` array of a struct
+:ref:`v4l2_modulator <v4l2-modulator>` and call the
+:ref:`VIDIOC_G_MODULATOR <VIDIOC_G_MODULATOR>` ioctl with a pointer to this structure. Drivers
+fill the rest of the structure or return an ``EINVAL`` error code when the
+index is out of bounds. To enumerate all modulators applications shall
+begin at index zero, incrementing by one until the driver returns
+EINVAL.
+
+Modulators have two writable properties, an audio modulation set and the
+radio frequency. To change the modulated audio subprograms, applications
+initialize the ``index`` and ``txsubchans`` fields and the ``reserved``
+array and call the :ref:`VIDIOC_S_MODULATOR <VIDIOC_G_MODULATOR>` ioctl. Drivers may choose a
+different audio modulation if the request cannot be satisfied. However
+this is a write-only ioctl, it does not return the actual audio
+modulation selected.
+
+:ref:`SDR <sdr>` specific modulator types are ``V4L2_TUNER_SDR`` and
+``V4L2_TUNER_RF``. For SDR devices ``txsubchans`` field must be
+initialized to zero. The term 'modulator' means SDR transmitter in this
+context.
+
+To change the radio frequency the
+:ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl is available.
+
+
+.. _v4l2-modulator:
+
+.. flat-table:: struct v4l2_modulator
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2 1 1
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``index``
+
+ - Identifies the modulator, set by the application.
+
+ - .. row 2
+
+ - __u8
+
+ - ``name``\ [32]
+
+ - Name of the modulator, a NUL-terminated ASCII string. This
+ information is intended for the user.
+
+ - .. row 3
+
+ - __u32
+
+ - ``capability``
+
+ - Modulator capability flags. No flags are defined for this field,
+ the tuner flags in struct :ref:`v4l2_tuner <v4l2-tuner>` are
+ used accordingly. The audio flags indicate the ability to encode
+ audio subprograms. They will *not* change for example with the
+ current video standard.
+
+ - .. row 4
+
+ - __u32
+
+ - ``rangelow``
+
+ - The lowest tunable frequency in units of 62.5 KHz, or if the
+ ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in units of
+ 62.5 Hz, or if the ``capability`` flag ``V4L2_TUNER_CAP_1HZ`` is
+ set, in units of 1 Hz.
+
+ - .. row 5
+
+ - __u32
+
+ - ``rangehigh``
+
+ - The highest tunable frequency in units of 62.5 KHz, or if the
+ ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in units of
+ 62.5 Hz, or if the ``capability`` flag ``V4L2_TUNER_CAP_1HZ`` is
+ set, in units of 1 Hz.
+
+ - .. row 6
+
+ - __u32
+
+ - ``txsubchans``
+
+ - With this field applications can determine how audio sub-carriers
+ shall be modulated. It contains a set of flags as defined in
+ :ref:`modulator-txsubchans`. Note the tuner ``rxsubchans`` flags
+ are reused, but the semantics are different. Video output devices
+ are assumed to have an analog or PCM audio input with 1-3
+ channels. The ``txsubchans`` flags select one or more channels for
+ modulation, together with some audio subprogram indicator, for
+ example a stereo pilot tone.
+
+ - .. row 7
+
+ - __u32
+
+ - ``type``
+
+ - :cspan:`2` Type of the modulator, see :ref:`v4l2-tuner-type`.
+
+ - .. row 8
+
+ - __u32
+
+ - ``reserved``\ [3]
+
+ - Reserved for future extensions. Drivers and applications must set
+ the array to zero.
+
+
+
+.. _modulator-txsubchans:
+
+.. flat-table:: Modulator Audio Transmission Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_TUNER_SUB_MONO``
+
+ - 0x0001
+
+ - Modulate channel 1 as mono audio, when the input has more
+ channels, a down-mix of channel 1 and 2. This flag does not
+ combine with ``V4L2_TUNER_SUB_STEREO`` or
+ ``V4L2_TUNER_SUB_LANG1``.
+
+ - .. row 2
+
+ - ``V4L2_TUNER_SUB_STEREO``
+
+ - 0x0002
+
+ - Modulate channel 1 and 2 as left and right channel of a stereo
+ audio signal. When the input has only one channel or two channels
+ and ``V4L2_TUNER_SUB_SAP`` is also set, channel 1 is encoded as
+ left and right channel. This flag does not combine with
+ ``V4L2_TUNER_SUB_MONO`` or ``V4L2_TUNER_SUB_LANG1``. When the
+ driver does not support stereo audio it shall fall back to mono.
+
+ - .. row 3
+
+ - ``V4L2_TUNER_SUB_LANG1``
+
+ - 0x0008
+
+ - Modulate channel 1 and 2 as primary and secondary language of a
+ bilingual audio signal. When the input has only one channel it is
+ used for both languages. It is not possible to encode the primary
+ or secondary language only. This flag does not combine with
+ ``V4L2_TUNER_SUB_MONO``, ``V4L2_TUNER_SUB_STEREO`` or
+ ``V4L2_TUNER_SUB_SAP``. If the hardware does not support the
+ respective audio matrix, or the current video standard does not
+ permit bilingual audio the :ref:`VIDIOC_S_MODULATOR <VIDIOC_G_MODULATOR>` ioctl shall
+ return an ``EINVAL`` error code and the driver shall fall back to mono
+ or stereo mode.
+
+ - .. row 4
+
+ - ``V4L2_TUNER_SUB_LANG2``
+
+ - 0x0004
+
+ - Same effect as ``V4L2_TUNER_SUB_SAP``.
+
+ - .. row 5
+
+ - ``V4L2_TUNER_SUB_SAP``
+
+ - 0x0004
+
+ - When combined with ``V4L2_TUNER_SUB_MONO`` the first channel is
+ encoded as mono audio, the last channel as Second Audio Program.
+ When the input has only one channel it is used for both audio
+ tracks. When the input has three channels the mono track is a
+ down-mix of channel 1 and 2. When combined with
+ ``V4L2_TUNER_SUB_STEREO`` channel 1 and 2 are encoded as left and
+ right stereo audio, channel 3 as Second Audio Program. When the
+ input has only two channels, the first is encoded as left and
+ right channel and the second as SAP. When the input has only one
+ channel it is used for all audio tracks. It is not possible to
+ encode a Second Audio Program only. This flag must combine with
+ ``V4L2_TUNER_SUB_MONO`` or ``V4L2_TUNER_SUB_STEREO``. If the
+ hardware does not support the respective audio matrix, or the
+ current video standard does not permit SAP the
+ :ref:`VIDIOC_S_MODULATOR <VIDIOC_G_MODULATOR>` ioctl shall return an ``EINVAL`` error code and
+ driver shall fall back to mono or stereo mode.
+
+ - .. row 6
+
+ - ``V4L2_TUNER_SUB_RDS``
+
+ - 0x0010
+
+ - Enable the RDS encoder for a radio FM transmitter.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The struct :ref:`v4l2_modulator <v4l2-modulator>` ``index`` is
+ out of bounds.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_G_OUTPUT:
+
+**************************************
+ioctl VIDIOC_G_OUTPUT, VIDIOC_S_OUTPUT
+**************************************
+
+Name
+====
+
+VIDIOC_G_OUTPUT - VIDIOC_S_OUTPUT - Query or select the current video output
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, int *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_OUTPUT, VIDIOC_S_OUTPUT
+
+``argp``
+
+
+Description
+===========
+
+To query the current video output applications call the
+:ref:`VIDIOC_G_OUTPUT <VIDIOC_G_OUTPUT>` ioctl with a pointer to an integer where the driver
+stores the number of the output, as in the struct
+:ref:`v4l2_output <v4l2-output>` ``index`` field. This ioctl will
+fail only when there are no video outputs, returning the ``EINVAL`` error
+code.
+
+To select a video output applications store the number of the desired
+output in an integer and call the :ref:`VIDIOC_S_OUTPUT <VIDIOC_G_OUTPUT>` ioctl with a
+pointer to this integer. Side effects are possible. For example outputs
+may support different video standards, so the driver may implicitly
+switch the current standard. standard. Because of these possible side
+effects applications must select an output before querying or
+negotiating any other parameters.
+
+Information about video outputs is available using the
+:ref:`VIDIOC_ENUMOUTPUT` ioctl.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The number of the video output is out of bounds, or there are no
+ video outputs at all.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_G_PARM:
+
+**********************************
+ioctl VIDIOC_G_PARM, VIDIOC_S_PARM
+**********************************
+
+Name
+====
+
+VIDIOC_G_PARM - VIDIOC_S_PARM - Get or set streaming parameters
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, v4l2_streamparm *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_PARM, VIDIOC_S_PARM
+
+``argp``
+
+
+Description
+===========
+
+The current video standard determines a nominal number of frames per
+second. If less than this number of frames is to be captured or output,
+applications can request frame skipping or duplicating on the driver
+side. This is especially useful when using the :ref:`read() <func-read>` or
+:ref:`write() <func-write>`, which are not augmented by timestamps or sequence
+counters, and to avoid unnecessary data copying.
+
+Further these ioctls can be used to determine the number of buffers used
+internally by a driver in read/write mode. For implications see the
+section discussing the :ref:`read() <func-read>` function.
+
+To get and set the streaming parameters applications call the
+:ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` ioctl, respectively. They take a
+pointer to a struct :ref:`struct v4l2_streamparm <v4l2-streamparm>` which contains a
+union holding separate parameters for input and output devices.
+
+
+.. _v4l2-streamparm:
+
+.. flat-table:: struct v4l2_streamparm
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``type``
+
+ -
+ - The buffer (stream) type, same as struct
+ :ref:`v4l2_format <v4l2-format>` ``type``, set by the
+ application. See :ref:`v4l2-buf-type`
+
+ - .. row 2
+
+ - union
+
+ - ``parm``
+
+ -
+ -
+
+ - .. row 3
+
+ -
+ - struct :ref:`v4l2_captureparm <v4l2-captureparm>`
+
+ - ``capture``
+
+ - Parameters for capture devices, used when ``type`` is
+ ``V4L2_BUF_TYPE_VIDEO_CAPTURE``.
+
+ - .. row 4
+
+ -
+ - struct :ref:`v4l2_outputparm <v4l2-outputparm>`
+
+ - ``output``
+
+ - Parameters for output devices, used when ``type`` is
+ ``V4L2_BUF_TYPE_VIDEO_OUTPUT``.
+
+ - .. row 5
+
+ -
+ - __u8
+
+ - ``raw_data``\ [200]
+
+ - A place holder for future extensions.
+
+
+
+.. _v4l2-captureparm:
+
+.. flat-table:: struct v4l2_captureparm
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``capability``
+
+ - See :ref:`parm-caps`.
+
+ - .. row 2
+
+ - __u32
+
+ - ``capturemode``
+
+ - Set by drivers and applications, see :ref:`parm-flags`.
+
+ - .. row 3
+
+ - struct :ref:`v4l2_fract <v4l2-fract>`
+
+ - ``timeperframe``
+
+ - This is the desired period between successive frames captured by
+ the driver, in seconds. The field is intended to skip frames on
+ the driver side, saving I/O bandwidth.
+
+ Applications store here the desired frame period, drivers return
+ the actual frame period, which must be greater or equal to the
+ nominal frame period determined by the current video standard
+ (struct :ref:`v4l2_standard <v4l2-standard>` ``frameperiod``
+ field). Changing the video standard (also implicitly by switching
+ the video input) may reset this parameter to the nominal frame
+ period. To reset manually applications can just set this field to
+ zero.
+
+ Drivers support this function only when they set the
+ ``V4L2_CAP_TIMEPERFRAME`` flag in the ``capability`` field.
+
+ - .. row 4
+
+ - __u32
+
+ - ``extendedmode``
+
+ - Custom (driver specific) streaming parameters. When unused,
+ applications and drivers must set this field to zero. Applications
+ using this field should check the driver name and version, see
+ :ref:`querycap`.
+
+ - .. row 5
+
+ - __u32
+
+ - ``readbuffers``
+
+ - Applications set this field to the desired number of buffers used
+ internally by the driver in :ref:`read() <func-read>` mode.
+ Drivers return the actual number of buffers. When an application
+ requests zero buffers, drivers should just return the current
+ setting rather than the minimum or an error code. For details see
+ :ref:`rw`.
+
+ - .. row 6
+
+ - __u32
+
+ - ``reserved``\ [4]
+
+ - Reserved for future extensions. Drivers and applications must set
+ the array to zero.
+
+
+
+.. _v4l2-outputparm:
+
+.. flat-table:: struct v4l2_outputparm
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``capability``
+
+ - See :ref:`parm-caps`.
+
+ - .. row 2
+
+ - __u32
+
+ - ``outputmode``
+
+ - Set by drivers and applications, see :ref:`parm-flags`.
+
+ - .. row 3
+
+ - struct :ref:`v4l2_fract <v4l2-fract>`
+
+ - ``timeperframe``
+
+ - This is the desired period between successive frames output by the
+ driver, in seconds.
+
+ - .. row 4
+
+ - :cspan:`2`
+
+ The field is intended to repeat frames on the driver side in
+ :ref:`write() <func-write>` mode (in streaming mode timestamps
+ can be used to throttle the output), saving I/O bandwidth.
+
+ Applications store here the desired frame period, drivers return
+ the actual frame period, which must be greater or equal to the
+ nominal frame period determined by the current video standard
+ (struct :ref:`v4l2_standard <v4l2-standard>` ``frameperiod``
+ field). Changing the video standard (also implicitly by switching
+ the video output) may reset this parameter to the nominal frame
+ period. To reset manually applications can just set this field to
+ zero.
+
+ Drivers support this function only when they set the
+ ``V4L2_CAP_TIMEPERFRAME`` flag in the ``capability`` field.
+
+ - .. row 5
+
+ - __u32
+
+ - ``extendedmode``
+
+ - Custom (driver specific) streaming parameters. When unused,
+ applications and drivers must set this field to zero. Applications
+ using this field should check the driver name and version, see
+ :ref:`querycap`.
+
+ - .. row 6
+
+ - __u32
+
+ - ``writebuffers``
+
+ - Applications set this field to the desired number of buffers used
+ internally by the driver in :ref:`write() <func-write>` mode. Drivers
+ return the actual number of buffers. When an application requests
+ zero buffers, drivers should just return the current setting
+ rather than the minimum or an error code. For details see
+ :ref:`rw`.
+
+ - .. row 7
+
+ - __u32
+
+ - ``reserved``\ [4]
+
+ - Reserved for future extensions. Drivers and applications must set
+ the array to zero.
+
+
+
+.. _parm-caps:
+
+.. flat-table:: Streaming Parameters Capabilites
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_CAP_TIMEPERFRAME``
+
+ - 0x1000
+
+ - The frame skipping/repeating controlled by the ``timeperframe``
+ field is supported.
+
+
+
+.. _parm-flags:
+
+.. flat-table:: Capture Parameters Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_MODE_HIGHQUALITY``
+
+ - 0x0001
+
+ - High quality imaging mode. High quality mode is intended for still
+ imaging applications. The idea is to get the best possible image
+ quality that the hardware can deliver. It is not defined how the
+ driver writer may achieve that; it will depend on the hardware and
+ the ingenuity of the driver writer. High quality mode is a
+ different mode from the regular motion video capture modes. In
+ high quality mode:
+
+ - The driver may be able to capture higher resolutions than for
+ motion capture.
+
+ - The driver may support fewer pixel formats than motion capture
+ (eg; true color).
+
+ - The driver may capture and arithmetically combine multiple
+ successive fields or frames to remove color edge artifacts and
+ reduce the noise in the video data.
+
+ - The driver may capture images in slices like a scanner in order
+ to handle larger format images than would otherwise be
+ possible.
+
+ - An image capture operation may be significantly slower than
+ motion capture.
+
+ - Moving objects in the image might have excessive motion blur.
+
+ - Capture might only work through the :ref:`read() <func-read>` call.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_G_PRIORITY:
+
+******************************************
+ioctl VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY
+******************************************
+
+Name
+====
+
+VIDIOC_G_PRIORITY - VIDIOC_S_PRIORITY - Query or request the access priority associated with a file descriptor
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, enum v4l2_priority *argp )
+
+.. cpp:function:: int ioctl( int fd, int request, const enum v4l2_priority *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY
+
+``argp``
+ Pointer to an enum v4l2_priority type.
+
+
+Description
+===========
+
+To query the current access priority applications call the
+:ref:`VIDIOC_G_PRIORITY <VIDIOC_G_PRIORITY>` ioctl with a pointer to an enum v4l2_priority
+variable where the driver stores the current priority.
+
+To request an access priority applications store the desired priority in
+an enum v4l2_priority variable and call :ref:`VIDIOC_S_PRIORITY <VIDIOC_G_PRIORITY>` ioctl
+with a pointer to this variable.
+
+
+.. _v4l2-priority:
+
+.. flat-table:: enum v4l2_priority
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_PRIORITY_UNSET``
+
+ - 0
+
+ -
+
+ - .. row 2
+
+ - ``V4L2_PRIORITY_BACKGROUND``
+
+ - 1
+
+ - Lowest priority, usually applications running in background, for
+ example monitoring VBI transmissions. A proxy application running
+ in user space will be necessary if multiple applications want to
+ read from a device at this priority.
+
+ - .. row 3
+
+ - ``V4L2_PRIORITY_INTERACTIVE``
+
+ - 2
+
+ -
+
+ - .. row 4
+
+ - ``V4L2_PRIORITY_DEFAULT``
+
+ - 2
+
+ - Medium priority, usually applications started and interactively
+ controlled by the user. For example TV viewers, Teletext browsers,
+ or just "panel" applications to change the channel or video
+ controls. This is the default priority unless an application
+ requests another.
+
+ - .. row 5
+
+ - ``V4L2_PRIORITY_RECORD``
+
+ - 3
+
+ - Highest priority. Only one file descriptor can have this priority,
+ it blocks any other fd from changing device properties. Usually
+ applications which must not be interrupted, like video recording.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The requested priority value is invalid.
+
+EBUSY
+ Another application already requested higher priority.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_G_SELECTION:
+
+********************************************
+ioctl VIDIOC_G_SELECTION, VIDIOC_S_SELECTION
+********************************************
+
+Name
+====
+
+VIDIOC_G_SELECTION - VIDIOC_S_SELECTION - Get or set one of the selection rectangles
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_selection *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_SELECTION, VIDIOC_S_SELECTION
+
+``argp``
+
+
+Description
+===========
+
+The ioctls are used to query and configure selection rectangles.
+
+To query the cropping (composing) rectangle set struct
+:ref:`v4l2_selection <v4l2-selection>` ``type`` field to the
+respective buffer type. Do not use the multiplanar buffer types. Use
+``V4L2_BUF_TYPE_VIDEO_CAPTURE`` instead of
+``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and use
+``V4L2_BUF_TYPE_VIDEO_OUTPUT`` instead of
+``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``. The next step is setting the
+value of struct :ref:`v4l2_selection <v4l2-selection>` ``target``
+field to ``V4L2_SEL_TGT_CROP`` (``V4L2_SEL_TGT_COMPOSE``). Please refer
+to table :ref:`v4l2-selections-common` or :ref:`selection-api` for
+additional targets. The ``flags`` and ``reserved`` fields of struct
+:ref:`v4l2_selection <v4l2-selection>` are ignored and they must be
+filled with zeros. The driver fills the rest of the structure or returns
+EINVAL error code if incorrect buffer type or target was used. If
+cropping (composing) is not supported then the active rectangle is not
+mutable and it is always equal to the bounds rectangle. Finally, the
+struct :ref:`v4l2_rect <v4l2-rect>` ``r`` rectangle is filled with
+the current cropping (composing) coordinates. The coordinates are
+expressed in driver-dependent units. The only exception are rectangles
+for images in raw formats, whose coordinates are always expressed in
+pixels.
+
+To change the cropping (composing) rectangle set the struct
+:ref:`v4l2_selection <v4l2-selection>` ``type`` field to the
+respective buffer type. Do not use multiplanar buffers. Use
+``V4L2_BUF_TYPE_VIDEO_CAPTURE`` instead of
+``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``. Use
+``V4L2_BUF_TYPE_VIDEO_OUTPUT`` instead of
+``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``. The next step is setting the
+value of struct :ref:`v4l2_selection <v4l2-selection>` ``target`` to
+``V4L2_SEL_TGT_CROP`` (``V4L2_SEL_TGT_COMPOSE``). Please refer to table
+:ref:`v4l2-selections-common` or :ref:`selection-api` for additional
+targets. The struct :ref:`v4l2_rect <v4l2-rect>` ``r`` rectangle need
+to be set to the desired active area. Field struct
+:ref:`v4l2_selection <v4l2-selection>` ``reserved`` is ignored and
+must be filled with zeros. The driver may adjust coordinates of the
+requested rectangle. An application may introduce constraints to control
+rounding behaviour. The struct :ref:`v4l2_selection <v4l2-selection>`
+``flags`` field must be set to one of the following:
+
+- ``0`` - The driver can adjust the rectangle size freely and shall
+ choose a crop/compose rectangle as close as possible to the requested
+ one.
+
+- ``V4L2_SEL_FLAG_GE`` - The driver is not allowed to shrink the
+ rectangle. The original rectangle must lay inside the adjusted one.
+
+- ``V4L2_SEL_FLAG_LE`` - The driver is not allowed to enlarge the
+ rectangle. The adjusted rectangle must lay inside the original one.
+
+- ``V4L2_SEL_FLAG_GE | V4L2_SEL_FLAG_LE`` - The driver must choose the
+ size exactly the same as in the requested rectangle.
+
+Please refer to :ref:`sel-const-adjust`.
+
+The driver may have to adjusts the requested dimensions against hardware
+limits and other parts as the pipeline, i.e. the bounds given by the
+capture/output window or TV display. The closest possible values of
+horizontal and vertical offset and sizes are chosen according to
+following priority:
+
+1. Satisfy constraints from struct
+ :ref:`v4l2_selection <v4l2-selection>` ``flags``.
+
+2. Adjust width, height, left, and top to hardware limits and
+ alignments.
+
+3. Keep center of adjusted rectangle as close as possible to the
+ original one.
+
+4. Keep width and height as close as possible to original ones.
+
+5. Keep horizontal and vertical offset as close as possible to original
+ ones.
+
+On success the struct :ref:`v4l2_rect <v4l2-rect>` ``r`` field
+contains the adjusted rectangle. When the parameters are unsuitable the
+application may modify the cropping (composing) or image parameters and
+repeat the cycle until satisfactory parameters have been negotiated. If
+constraints flags have to be violated at then ``ERANGE`` is returned. The
+error indicates that *there exist no rectangle* that satisfies the
+constraints.
+
+Selection targets and flags are documented in
+:ref:`v4l2-selections-common`.
+
+
+.. _sel-const-adjust:
+
+.. figure:: vidioc-g-selection_files/constraints.*
+ :alt: constraints.png
+ :align: center
+
+ Size adjustments with constraint flags.
+
+ Behaviour of rectangle adjustment for different constraint flags.
+
+
+
+
+.. _v4l2-selection:
+
+.. flat-table:: struct v4l2_selection
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``type``
+
+ - Type of the buffer (from enum
+ :ref:`v4l2_buf_type <v4l2-buf-type>`).
+
+ - .. row 2
+
+ - __u32
+
+ - ``target``
+
+ - Used to select between
+ :ref:`cropping and composing rectangles <v4l2-selections-common>`.
+
+ - .. row 3
+
+ - __u32
+
+ - ``flags``
+
+ - Flags controlling the selection rectangle adjustments, refer to
+ :ref:`selection flags <v4l2-selection-flags>`.
+
+ - .. row 4
+
+ - struct :ref:`v4l2_rect <v4l2-rect>`
+
+ - ``r``
+
+ - The selection rectangle.
+
+ - .. row 5
+
+ - __u32
+
+ - ``reserved[9]``
+
+ - Reserved fields for future use. Drivers and applications must zero
+ this array.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ Given buffer type ``type`` or the selection target ``target`` is not
+ supported, or the ``flags`` argument is not valid.
+
+ERANGE
+ It is not possible to adjust struct :ref:`v4l2_rect <v4l2-rect>`
+ ``r`` rectangle to satisfy all constraints given in the ``flags``
+ argument.
+
+EBUSY
+ It is not possible to apply change of the selection rectangle at the
+ moment. Usually because streaming is in progress.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_G_SLICED_VBI_CAP:
+
+*****************************
+ioctl VIDIOC_G_SLICED_VBI_CAP
+*****************************
+
+Name
+====
+
+VIDIOC_G_SLICED_VBI_CAP - Query sliced VBI capabilities
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_sliced_vbi_cap *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_SLICED_VBI_CAP
+
+``argp``
+
+
+Description
+===========
+
+To find out which data services are supported by a sliced VBI capture or
+output device, applications initialize the ``type`` field of a struct
+:ref:`v4l2_sliced_vbi_cap <v4l2-sliced-vbi-cap>`, clear the
+``reserved`` array and call the :ref:`VIDIOC_G_SLICED_VBI_CAP <VIDIOC_G_SLICED_VBI_CAP>` ioctl. The
+driver fills in the remaining fields or returns an ``EINVAL`` error code if
+the sliced VBI API is unsupported or ``type`` is invalid.
+
+Note the ``type`` field was added, and the ioctl changed from read-only
+to write-read, in Linux 2.6.19.
+
+
+.. _v4l2-sliced-vbi-cap:
+
+.. flat-table:: struct v4l2_sliced_vbi_cap
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 3 2 2 2
+
+
+ - .. row 1
+
+ - __u16
+
+ - ``service_set``
+
+ - :cspan:`2` A set of all data services supported by the driver.
+ Equal to the union of all elements of the ``service_lines`` array.
+
+ - .. row 2
+
+ - __u16
+
+ - ``service_lines``\ [2][24]
+
+ - :cspan:`2` Each element of this array contains a set of data
+ services the hardware can look for or insert into a particular
+ scan line. Data services are defined in :ref:`vbi-services`.
+ Array indices map to ITU-R line numbers (see also :ref:`vbi-525`
+ and :ref:`vbi-625`) as follows:
+
+ - .. row 3
+
+ -
+ -
+ - Element
+
+ - 525 line systems
+
+ - 625 line systems
+
+ - .. row 4
+
+ -
+ -
+ - ``service_lines``\ [0][1]
+
+ - 1
+
+ - 1
+
+ - .. row 5
+
+ -
+ -
+ - ``service_lines``\ [0][23]
+
+ - 23
+
+ - 23
+
+ - .. row 6
+
+ -
+ -
+ - ``service_lines``\ [1][1]
+
+ - 264
+
+ - 314
+
+ - .. row 7
+
+ -
+ -
+ - ``service_lines``\ [1][23]
+
+ - 286
+
+ - 336
+
+ - .. row 8
+
+ -
+
+ - .. row 9
+
+ -
+ -
+ - :cspan:`2` The number of VBI lines the hardware can capture or
+ output per frame, or the number of services it can identify on a
+ given line may be limited. For example on PAL line 16 the hardware
+ may be able to look for a VPS or Teletext signal, but not both at
+ the same time. Applications can learn about these limits using the
+ :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl as described in
+ :ref:`sliced`.
+
+ - .. row 10
+
+ -
+
+ - .. row 11
+
+ -
+ -
+ - :cspan:`2` Drivers must set ``service_lines`` [0][0] and
+ ``service_lines``\ [1][0] to zero.
+
+ - .. row 12
+
+ - __u32
+
+ - ``type``
+
+ - Type of the data stream, see :ref:`v4l2-buf-type`. Should be
+ ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE`` or
+ ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT``.
+
+ - .. row 13
+
+ - __u32
+
+ - ``reserved``\ [3]
+
+ - :cspan:`2` This array is reserved for future extensions.
+ Applications and drivers must set it to zero.
+
+
+
+.. _vbi-services:
+
+.. flat-table:: Sliced VBI services
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 2 1 1 2 2
+
+
+ - .. row 1
+
+ - Symbol
+
+ - Value
+
+ - Reference
+
+ - Lines, usually
+
+ - Payload
+
+ - .. row 2
+
+ - ``V4L2_SLICED_TELETEXT_B`` (Teletext System B)
+
+ - 0x0001
+
+ - :ref:`ets300706`, :ref:`itu653`
+
+ - PAL/SECAM line 7-22, 320-335 (second field 7-22)
+
+ - Last 42 of the 45 byte Teletext packet, that is without clock
+ run-in and framing code, lsb first transmitted.
+
+ - .. row 3
+
+ - ``V4L2_SLICED_VPS``
+
+ - 0x0400
+
+ - :ref:`ets300231`
+
+ - PAL line 16
+
+ - Byte number 3 to 15 according to Figure 9 of ETS 300 231, lsb
+ first transmitted.
+
+ - .. row 4
+
+ - ``V4L2_SLICED_CAPTION_525``
+
+ - 0x1000
+
+ - :ref:`cea608`
+
+ - NTSC line 21, 284 (second field 21)
+
+ - Two bytes in transmission order, including parity bit, lsb first
+ transmitted.
+
+ - .. row 5
+
+ - ``V4L2_SLICED_WSS_625``
+
+ - 0x4000
+
+ - :ref:`en300294`, :ref:`itu1119`
+
+ - PAL/SECAM line 23
+
+ -
+
+ ::
+
+ Byte 0 1
+ msb lsb msb lsb
+ Bit 7 6 5 4 3 2 1 0 x x 13 12 11 10 9
+
+ - .. row 6
+
+ - ``V4L2_SLICED_VBI_525``
+
+ - 0x1000
+
+ - :cspan:`2` Set of services applicable to 525 line systems.
+
+ - .. row 7
+
+ - ``V4L2_SLICED_VBI_625``
+
+ - 0x4401
+
+ - :cspan:`2` Set of services applicable to 625 line systems.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The value in the ``type`` field is wrong.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_G_STD:
+
+********************************
+ioctl VIDIOC_G_STD, VIDIOC_S_STD
+********************************
+
+Name
+====
+
+VIDIOC_G_STD - VIDIOC_S_STD - Query or select the video standard of the current input
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, v4l2_std_id *argp )
+
+.. cpp:function:: int ioctl( int fd, int request, const v4l2_std_id *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_STD, VIDIOC_S_STD
+
+``argp``
+
+
+Description
+===========
+
+To query and select the current video standard applications use the
+:ref:`VIDIOC_G_STD <VIDIOC_G_STD>` and :ref:`VIDIOC_S_STD <VIDIOC_G_STD>` ioctls which take a pointer to a
+:ref:`v4l2_std_id <v4l2-std-id>` type as argument. :ref:`VIDIOC_G_STD <VIDIOC_G_STD>`
+can return a single flag or a set of flags as in struct
+:ref:`v4l2_standard <v4l2-standard>` field ``id``. The flags must be
+unambiguous such that they appear in only one enumerated
+:ref:`struct v4l2_standard <v4l2-standard>` structure.
+
+:ref:`VIDIOC_S_STD <VIDIOC_G_STD>` accepts one or more flags, being a write-only ioctl it
+does not return the actual new standard as :ref:`VIDIOC_G_STD <VIDIOC_G_STD>` does. When
+no flags are given or the current input does not support the requested
+standard the driver returns an ``EINVAL`` error code. When the standard set
+is ambiguous drivers may return ``EINVAL`` or choose any of the requested
+standards. If the current input or output does not support standard
+video timings (e.g. if :ref:`VIDIOC_ENUMINPUT`
+does not set the ``V4L2_IN_CAP_STD`` flag), then ``ENODATA`` error code is
+returned.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The :ref:`VIDIOC_S_STD <VIDIOC_G_STD>` parameter was unsuitable.
+
+ENODATA
+ Standard video timings are not supported for this input or output.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_G_TUNER:
+
+************************************
+ioctl VIDIOC_G_TUNER, VIDIOC_S_TUNER
+************************************
+
+Name
+====
+
+VIDIOC_G_TUNER - VIDIOC_S_TUNER - Get or set tuner attributes
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_tuner *argp )
+
+.. cpp:function:: int ioctl( int fd, int request, const struct v4l2_tuner *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_TUNER, VIDIOC_S_TUNER
+
+``argp``
+
+
+Description
+===========
+
+To query the attributes of a tuner applications initialize the ``index``
+field and zero out the ``reserved`` array of a struct
+:ref:`v4l2_tuner <v4l2-tuner>` and call the ``VIDIOC_G_TUNER`` ioctl
+with a pointer to this structure. Drivers fill the rest of the structure
+or return an ``EINVAL`` error code when the index is out of bounds. To
+enumerate all tuners applications shall begin at index zero,
+incrementing by one until the driver returns ``EINVAL``.
+
+Tuners have two writable properties, the audio mode and the radio
+frequency. To change the audio mode, applications initialize the
+``index``, ``audmode`` and ``reserved`` fields and call the
+``VIDIOC_S_TUNER`` ioctl. This will *not* change the current tuner,
+which is determined by the current video input. Drivers may choose a
+different audio mode if the requested mode is invalid or unsupported.
+Since this is a write-only ioctl, it does not return the actually
+selected audio mode.
+
+:ref:`SDR <sdr>` specific tuner types are ``V4L2_TUNER_SDR`` and
+``V4L2_TUNER_RF``. For SDR devices ``audmode`` field must be initialized
+to zero. The term 'tuner' means SDR receiver in this context.
+
+To change the radio frequency the
+:ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl is available.
+
+
+.. _v4l2-tuner:
+
+.. flat-table:: struct v4l2_tuner
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``index``
+
+ - :cspan:`1` Identifies the tuner, set by the application.
+
+ - .. row 2
+
+ - __u8
+
+ - ``name``\ [32]
+
+ - :cspan:`1`
+
+ Name of the tuner, a NUL-terminated ASCII string. This information
+ is intended for the user.
+
+ - .. row 3
+
+ - __u32
+
+ - ``type``
+
+ - :cspan:`1` Type of the tuner, see :ref:`v4l2-tuner-type`.
+
+ - .. row 4
+
+ - __u32
+
+ - ``capability``
+
+ - :cspan:`1`
+
+ Tuner capability flags, see :ref:`tuner-capability`. Audio flags
+ indicate the ability to decode audio subprograms. They will *not*
+ change, for example with the current video standard.
+
+ When the structure refers to a radio tuner the
+ ``V4L2_TUNER_CAP_LANG1``, ``V4L2_TUNER_CAP_LANG2`` and
+ ``V4L2_TUNER_CAP_NORM`` flags can't be used.
+
+ If multiple frequency bands are supported, then ``capability`` is
+ the union of all ``capability`` fields of each struct
+ :ref:`v4l2_frequency_band <v4l2-frequency-band>`.
+
+ - .. row 5
+
+ - __u32
+
+ - ``rangelow``
+
+ - :cspan:`1` The lowest tunable frequency in units of 62.5 kHz, or
+ if the ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in units
+ of 62.5 Hz, or if the ``capability`` flag ``V4L2_TUNER_CAP_1HZ``
+ is set, in units of 1 Hz. If multiple frequency bands are
+ supported, then ``rangelow`` is the lowest frequency of all the
+ frequency bands.
+
+ - .. row 6
+
+ - __u32
+
+ - ``rangehigh``
+
+ - :cspan:`1` The highest tunable frequency in units of 62.5 kHz,
+ or if the ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in
+ units of 62.5 Hz, or if the ``capability`` flag
+ ``V4L2_TUNER_CAP_1HZ`` is set, in units of 1 Hz. If multiple
+ frequency bands are supported, then ``rangehigh`` is the highest
+ frequency of all the frequency bands.
+
+ - .. row 7
+
+ - __u32
+
+ - ``rxsubchans``
+
+ - :cspan:`1`
+
+ Some tuners or audio decoders can determine the received audio
+ subprograms by analyzing audio carriers, pilot tones or other
+ indicators. To pass this information drivers set flags defined in
+ :ref:`tuner-rxsubchans` in this field. For example:
+
+ - .. row 8
+
+ -
+ -
+ - ``V4L2_TUNER_SUB_MONO``
+
+ - receiving mono audio
+
+ - .. row 9
+
+ -
+ -
+ - ``STEREO | SAP``
+
+ - receiving stereo audio and a secondary audio program
+
+ - .. row 10
+
+ -
+ -
+ - ``MONO | STEREO``
+
+ - receiving mono or stereo audio, the hardware cannot distinguish
+
+ - .. row 11
+
+ -
+ -
+ - ``LANG1 | LANG2``
+
+ - receiving bilingual audio
+
+ - .. row 12
+
+ -
+ -
+ - ``MONO | STEREO | LANG1 | LANG2``
+
+ - receiving mono, stereo or bilingual audio
+
+ - .. row 13
+
+ -
+ -
+ - :cspan:`1`
+
+ When the ``V4L2_TUNER_CAP_STEREO``, ``_LANG1``, ``_LANG2`` or
+ ``_SAP`` flag is cleared in the ``capability`` field, the
+ corresponding ``V4L2_TUNER_SUB_`` flag must not be set here.
+
+ This field is valid only if this is the tuner of the current video
+ input, or when the structure refers to a radio tuner.
+
+ - .. row 14
+
+ - __u32
+
+ - ``audmode``
+
+ - :cspan:`1`
+
+ The selected audio mode, see :ref:`tuner-audmode` for valid
+ values. The audio mode does not affect audio subprogram detection,
+ and like a :ref:`control` it does not automatically
+ change unless the requested mode is invalid or unsupported. See
+ :ref:`tuner-matrix` for possible results when the selected and
+ received audio programs do not match.
+
+ Currently this is the only field of struct
+ :ref:`struct v4l2_tuner <v4l2-tuner>` applications can change.
+
+ - .. row 15
+
+ - __u32
+
+ - ``signal``
+
+ - :cspan:`1` The signal strength if known, ranging from 0 to
+ 65535. Higher values indicate a better signal.
+
+ - .. row 16
+
+ - __s32
+
+ - ``afc``
+
+ - :cspan:`1` Automatic frequency control: When the ``afc`` value
+ is negative, the frequency is too low, when positive too high.
+
+ - .. row 17
+
+ - __u32
+
+ - ``reserved``\ [4]
+
+ - :cspan:`1` Reserved for future extensions. Drivers and
+ applications must set the array to zero.
+
+
+
+.. _v4l2-tuner-type:
+
+.. flat-table:: enum v4l2_tuner_type
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_TUNER_RADIO``
+
+ - 1
+
+ -
+
+ - .. row 2
+
+ - ``V4L2_TUNER_ANALOG_TV``
+
+ - 2
+
+ -
+
+ - .. row 3
+
+ - ``V4L2_TUNER_SDR``
+
+ - 4
+
+ -
+
+ - .. row 4
+
+ - ``V4L2_TUNER_RF``
+
+ - 5
+
+ -
+
+
+
+.. _tuner-capability:
+
+.. flat-table:: Tuner and Modulator Capability Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_TUNER_CAP_LOW``
+
+ - 0x0001
+
+ - When set, tuning frequencies are expressed in units of 62.5 Hz
+ instead of 62.5 kHz.
+
+ - .. row 2
+
+ - ``V4L2_TUNER_CAP_NORM``
+
+ - 0x0002
+
+ - This is a multi-standard tuner; the video standard can or must be
+ switched. (B/G PAL tuners for example are typically not considered
+ multi-standard because the video standard is automatically
+ determined from the frequency band.) The set of supported video
+ standards is available from the struct
+ :ref:`v4l2_input <v4l2-input>` pointing to this tuner, see the
+ description of ioctl :ref:`VIDIOC_ENUMINPUT`
+ for details. Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this
+ capability.
+
+ - .. row 3
+
+ - ``V4L2_TUNER_CAP_HWSEEK_BOUNDED``
+
+ - 0x0004
+
+ - If set, then this tuner supports the hardware seek functionality
+ where the seek stops when it reaches the end of the frequency
+ range.
+
+ - .. row 4
+
+ - ``V4L2_TUNER_CAP_HWSEEK_WRAP``
+
+ - 0x0008
+
+ - If set, then this tuner supports the hardware seek functionality
+ where the seek wraps around when it reaches the end of the
+ frequency range.
+
+ - .. row 5
+
+ - ``V4L2_TUNER_CAP_STEREO``
+
+ - 0x0010
+
+ - Stereo audio reception is supported.
+
+ - .. row 6
+
+ - ``V4L2_TUNER_CAP_LANG1``
+
+ - 0x0040
+
+ - Reception of the primary language of a bilingual audio program is
+ supported. Bilingual audio is a feature of two-channel systems,
+ transmitting the primary language monaural on the main audio
+ carrier and a secondary language monaural on a second carrier.
+ Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this capability.
+
+ - .. row 7
+
+ - ``V4L2_TUNER_CAP_LANG2``
+
+ - 0x0020
+
+ - Reception of the secondary language of a bilingual audio program
+ is supported. Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this
+ capability.
+
+ - .. row 8
+
+ - ``V4L2_TUNER_CAP_SAP``
+
+ - 0x0020
+
+ - Reception of a secondary audio program is supported. This is a
+ feature of the BTSC system which accompanies the NTSC video
+ standard. Two audio carriers are available for mono or stereo
+ transmissions of a primary language, and an independent third
+ carrier for a monaural secondary language. Only
+ ``V4L2_TUNER_ANALOG_TV`` tuners can have this capability.
+
+ Note the ``V4L2_TUNER_CAP_LANG2`` and ``V4L2_TUNER_CAP_SAP`` flags
+ are synonyms. ``V4L2_TUNER_CAP_SAP`` applies when the tuner
+ supports the ``V4L2_STD_NTSC_M`` video standard.
+
+ - .. row 9
+
+ - ``V4L2_TUNER_CAP_RDS``
+
+ - 0x0080
+
+ - RDS capture is supported. This capability is only valid for radio
+ tuners.
+
+ - .. row 10
+
+ - ``V4L2_TUNER_CAP_RDS_BLOCK_IO``
+
+ - 0x0100
+
+ - The RDS data is passed as unparsed RDS blocks.
+
+ - .. row 11
+
+ - ``V4L2_TUNER_CAP_RDS_CONTROLS``
+
+ - 0x0200
+
+ - The RDS data is parsed by the hardware and set via controls.
+
+ - .. row 12
+
+ - ``V4L2_TUNER_CAP_FREQ_BANDS``
+
+ - 0x0400
+
+ - The :ref:`VIDIOC_ENUM_FREQ_BANDS`
+ ioctl can be used to enumerate the available frequency bands.
+
+ - .. row 13
+
+ - ``V4L2_TUNER_CAP_HWSEEK_PROG_LIM``
+
+ - 0x0800
+
+ - The range to search when using the hardware seek functionality is
+ programmable, see
+ :ref:`VIDIOC_S_HW_FREQ_SEEK` for
+ details.
+
+ - .. row 14
+
+ - ``V4L2_TUNER_CAP_1HZ``
+
+ - 0x1000
+
+ - When set, tuning frequencies are expressed in units of 1 Hz
+ instead of 62.5 kHz.
+
+
+
+.. _tuner-rxsubchans:
+
+.. flat-table:: Tuner Audio Reception Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_TUNER_SUB_MONO``
+
+ - 0x0001
+
+ - The tuner receives a mono audio signal.
+
+ - .. row 2
+
+ - ``V4L2_TUNER_SUB_STEREO``
+
+ - 0x0002
+
+ - The tuner receives a stereo audio signal.
+
+ - .. row 3
+
+ - ``V4L2_TUNER_SUB_LANG1``
+
+ - 0x0008
+
+ - The tuner receives the primary language of a bilingual audio
+ signal. Drivers must clear this flag when the current video
+ standard is ``V4L2_STD_NTSC_M``.
+
+ - .. row 4
+
+ - ``V4L2_TUNER_SUB_LANG2``
+
+ - 0x0004
+
+ - The tuner receives the secondary language of a bilingual audio
+ signal (or a second audio program).
+
+ - .. row 5
+
+ - ``V4L2_TUNER_SUB_SAP``
+
+ - 0x0004
+
+ - The tuner receives a Second Audio Program. Note the
+ ``V4L2_TUNER_SUB_LANG2`` and ``V4L2_TUNER_SUB_SAP`` flags are
+ synonyms. The ``V4L2_TUNER_SUB_SAP`` flag applies when the current
+ video standard is ``V4L2_STD_NTSC_M``.
+
+ - .. row 6
+
+ - ``V4L2_TUNER_SUB_RDS``
+
+ - 0x0010
+
+ - The tuner receives an RDS channel.
+
+
+
+.. _tuner-audmode:
+
+.. flat-table:: Tuner Audio Modes
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_TUNER_MODE_MONO``
+
+ - 0
+
+ - Play mono audio. When the tuner receives a stereo signal this a
+ down-mix of the left and right channel. When the tuner receives a
+ bilingual or SAP signal this mode selects the primary language.
+
+ - .. row 2
+
+ - ``V4L2_TUNER_MODE_STEREO``
+
+ - 1
+
+ - Play stereo audio. When the tuner receives bilingual audio it may
+ play different languages on the left and right channel or the
+ primary language is played on both channels.
+
+ Playing different languages in this mode is deprecated. New
+ drivers should do this only in ``MODE_LANG1_LANG2``.
+
+ When the tuner receives no stereo signal or does not support
+ stereo reception the driver shall fall back to ``MODE_MONO``.
+
+ - .. row 3
+
+ - ``V4L2_TUNER_MODE_LANG1``
+
+ - 3
+
+ - Play the primary language, mono or stereo. Only
+ ``V4L2_TUNER_ANALOG_TV`` tuners support this mode.
+
+ - .. row 4
+
+ - ``V4L2_TUNER_MODE_LANG2``
+
+ - 2
+
+ - Play the secondary language, mono. When the tuner receives no
+ bilingual audio or SAP, or their reception is not supported the
+ driver shall fall back to mono or stereo mode. Only
+ ``V4L2_TUNER_ANALOG_TV`` tuners support this mode.
+
+ - .. row 5
+
+ - ``V4L2_TUNER_MODE_SAP``
+
+ - 2
+
+ - Play the Second Audio Program. When the tuner receives no
+ bilingual audio or SAP, or their reception is not supported the
+ driver shall fall back to mono or stereo mode. Only
+ ``V4L2_TUNER_ANALOG_TV`` tuners support this mode. Note the
+ ``V4L2_TUNER_MODE_LANG2`` and ``V4L2_TUNER_MODE_SAP`` are
+ synonyms.
+
+ - .. row 6
+
+ - ``V4L2_TUNER_MODE_LANG1_LANG2``
+
+ - 4
+
+ - Play the primary language on the left channel, the secondary
+ language on the right channel. When the tuner receives no
+ bilingual audio or SAP, it shall fall back to ``MODE_LANG1`` or
+ ``MODE_MONO``. Only ``V4L2_TUNER_ANALOG_TV`` tuners support this
+ mode.
+
+
+
+.. _tuner-matrix:
+
+.. flat-table:: Tuner Audio Matrix
+ :header-rows: 2
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - :cspan:`5` Selected ``V4L2_TUNER_MODE_``
+
+ - .. row 2
+
+ - Received ``V4L2_TUNER_SUB_``
+
+ - ``MONO``
+
+ - ``STEREO``
+
+ - ``LANG1``
+
+ - ``LANG2 = SAP``
+
+ - ``LANG1_LANG2``\ [1]_
+
+ - .. row 3
+
+ - ``MONO``
+
+ - Mono
+
+ - Mono/Mono
+
+ - Mono
+
+ - Mono
+
+ - Mono/Mono
+
+ - .. row 4
+
+ - ``MONO | SAP``
+
+ - Mono
+
+ - Mono/Mono
+
+ - Mono
+
+ - SAP
+
+ - Mono/SAP (preferred) or Mono/Mono
+
+ - .. row 5
+
+ - ``STEREO``
+
+ - L+R
+
+ - L/R
+
+ - Stereo L/R (preferred) or Mono L+R
+
+ - Stereo L/R (preferred) or Mono L+R
+
+ - L/R (preferred) or L+R/L+R
+
+ - .. row 6
+
+ - ``STEREO | SAP``
+
+ - L+R
+
+ - L/R
+
+ - Stereo L/R (preferred) or Mono L+R
+
+ - SAP
+
+ - L+R/SAP (preferred) or L/R or L+R/L+R
+
+ - .. row 7
+
+ - ``LANG1 | LANG2``
+
+ - Language 1
+
+ - Lang1/Lang2 (deprecated [2]_) or Lang1/Lang1
+
+ - Language 1
+
+ - Language 2
+
+ - Lang1/Lang2 (preferred) or Lang1/Lang1
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The struct :ref:`v4l2_tuner <v4l2-tuner>` ``index`` is out of
+ bounds.
+
+.. [1]
+ This mode has been added in Linux 2.6.17 and may not be supported by
+ older drivers.
+
+.. [2]
+ Playback of both languages in ``MODE_STEREO`` is deprecated. In the
+ future drivers should produce only the primary language in this mode.
+ Applications should request ``MODE_LANG1_LANG2`` to record both
+ languages or a stereo signal.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_LOG_STATUS:
+
+***********************
+ioctl VIDIOC_LOG_STATUS
+***********************
+
+Name
+====
+
+VIDIOC_LOG_STATUS - Log driver status information
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request )
+
+
+Arguments
+=========
+
+
+
+Description
+===========
+
+As the video/audio devices become more complicated it becomes harder to
+debug problems. When this ioctl is called the driver will output the
+current device status to the kernel log. This is particular useful when
+dealing with problems like no sound, no video and incorrectly tuned
+channels. Also many modern devices autodetect video and audio standards
+and this ioctl will report what the device thinks what the standard is.
+Mismatches may give an indication where the problem is.
+
+This ioctl is optional and not all drivers support it. It was introduced
+in Linux 2.6.15.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_OVERLAY:
+
+********************
+ioctl VIDIOC_OVERLAY
+********************
+
+Name
+====
+
+VIDIOC_OVERLAY - Start or stop video overlay
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, const int *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_OVERLAY
+
+``argp``
+
+
+Description
+===========
+
+This ioctl is part of the :ref:`video overlay <overlay>` I/O method.
+Applications call :ref:`VIDIOC_OVERLAY` to start or stop the overlay. It
+takes a pointer to an integer which must be set to zero by the
+application to stop overlay, to one to start.
+
+Drivers do not support :ref:`VIDIOC_STREAMON` or
+:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` with
+``V4L2_BUF_TYPE_VIDEO_OVERLAY``.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The overlay parameters have not been set up. See :ref:`overlay`
+ for the necessary steps.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_PREPARE_BUF:
+
+************************
+ioctl VIDIOC_PREPARE_BUF
+************************
+
+Name
+====
+
+VIDIOC_PREPARE_BUF - Prepare a buffer for I/O
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_buffer *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_PREPARE_BUF
+
+``argp``
+
+
+Description
+===========
+
+Applications can optionally call the :ref:`VIDIOC_PREPARE_BUF` ioctl to
+pass ownership of the buffer to the driver before actually enqueuing it,
+using the :ref:`VIDIOC_QBUF` ioctl, and to prepare it for future I/O. Such
+preparations may include cache invalidation or cleaning. Performing them
+in advance saves time during the actual I/O. In case such cache
+operations are not required, the application can use one of
+``V4L2_BUF_FLAG_NO_CACHE_INVALIDATE`` and
+``V4L2_BUF_FLAG_NO_CACHE_CLEAN`` flags to skip the respective step.
+
+The :ref:`struct v4l2_buffer <v4l2-buffer>` structure is specified in
+:ref:`buffer`.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EBUSY
+ File I/O is in progress.
+
+EINVAL
+ The buffer ``type`` is not supported, or the ``index`` is out of
+ bounds, or no buffers have been allocated yet, or the ``userptr`` or
+ ``length`` are invalid.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_QBUF:
+
+*******************************
+ioctl VIDIOC_QBUF, VIDIOC_DQBUF
+*******************************
+
+Name
+====
+
+VIDIOC_QBUF - VIDIOC_DQBUF - Exchange a buffer with the driver
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_buffer *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_QBUF, VIDIOC_DQBUF
+
+``argp``
+
+
+Description
+===========
+
+Applications call the ``VIDIOC_QBUF`` ioctl to enqueue an empty
+(capturing) or filled (output) buffer in the driver's incoming queue.
+The semantics depend on the selected I/O method.
+
+To enqueue a buffer applications set the ``type`` field of a struct
+:ref:`v4l2_buffer <v4l2-buffer>` to the same buffer type as was
+previously used with struct :ref:`v4l2_format <v4l2-format>` ``type``
+and struct :ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``type``.
+Applications must also set the ``index`` field. Valid index numbers
+range from zero to the number of buffers allocated with
+:ref:`VIDIOC_REQBUFS` (struct
+:ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``count``) minus
+one. The contents of the struct :ref:`struct v4l2_buffer <v4l2-buffer>` returned
+by a :ref:`VIDIOC_QUERYBUF` ioctl will do as well.
+When the buffer is intended for output (``type`` is
+``V4L2_BUF_TYPE_VIDEO_OUTPUT``, ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``,
+or ``V4L2_BUF_TYPE_VBI_OUTPUT``) applications must also initialize the
+``bytesused``, ``field`` and ``timestamp`` fields, see :ref:`buffer`
+for details. Applications must also set ``flags`` to 0. The
+``reserved2`` and ``reserved`` fields must be set to 0. When using the
+:ref:`multi-planar API <planar-apis>`, the ``m.planes`` field must
+contain a userspace pointer to a filled-in array of struct
+:ref:`v4l2_plane <v4l2-plane>` and the ``length`` field must be set
+to the number of elements in that array.
+
+To enqueue a :ref:`memory mapped <mmap>` buffer applications set the
+``memory`` field to ``V4L2_MEMORY_MMAP``. When ``VIDIOC_QBUF`` is called
+with a pointer to this structure the driver sets the
+``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_QUEUED`` flags and clears
+the ``V4L2_BUF_FLAG_DONE`` flag in the ``flags`` field, or it returns an
+EINVAL error code.
+
+To enqueue a :ref:`user pointer <userp>` buffer applications set the
+``memory`` field to ``V4L2_MEMORY_USERPTR``, the ``m.userptr`` field to
+the address of the buffer and ``length`` to its size. When the
+multi-planar API is used, ``m.userptr`` and ``length`` members of the
+passed array of struct :ref:`v4l2_plane <v4l2-plane>` have to be used
+instead. When ``VIDIOC_QBUF`` is called with a pointer to this structure
+the driver sets the ``V4L2_BUF_FLAG_QUEUED`` flag and clears the
+``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_DONE`` flags in the
+``flags`` field, or it returns an error code. This ioctl locks the
+memory pages of the buffer in physical memory, they cannot be swapped
+out to disk. Buffers remain locked until dequeued, until the
+:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or
+:ref:`VIDIOC_REQBUFS` ioctl is called, or until the
+device is closed.
+
+To enqueue a :ref:`DMABUF <dmabuf>` buffer applications set the
+``memory`` field to ``V4L2_MEMORY_DMABUF`` and the ``m.fd`` field to a
+file descriptor associated with a DMABUF buffer. When the multi-planar
+API is used the ``m.fd`` fields of the passed array of struct
+:ref:`v4l2_plane <v4l2-plane>` have to be used instead. When
+``VIDIOC_QBUF`` is called with a pointer to this structure the driver
+sets the ``V4L2_BUF_FLAG_QUEUED`` flag and clears the
+``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_DONE`` flags in the
+``flags`` field, or it returns an error code. This ioctl locks the
+buffer. Locking a buffer means passing it to a driver for a hardware
+access (usually DMA). If an application accesses (reads/writes) a locked
+buffer then the result is undefined. Buffers remain locked until
+dequeued, until the :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or
+:ref:`VIDIOC_REQBUFS` ioctl is called, or until the
+device is closed.
+
+Applications call the ``VIDIOC_DQBUF`` ioctl to dequeue a filled
+(capturing) or displayed (output) buffer from the driver's outgoing
+queue. They just set the ``type``, ``memory`` and ``reserved`` fields of
+a struct :ref:`v4l2_buffer <v4l2-buffer>` as above, when
+``VIDIOC_DQBUF`` is called with a pointer to this structure the driver
+fills the remaining fields or returns an error code. The driver may also
+set ``V4L2_BUF_FLAG_ERROR`` in the ``flags`` field. It indicates a
+non-critical (recoverable) streaming error. In such case the application
+may continue as normal, but should be aware that data in the dequeued
+buffer might be corrupted. When using the multi-planar API, the planes
+array must be passed in as well.
+
+By default ``VIDIOC_DQBUF`` blocks when no buffer is in the outgoing
+queue. When the ``O_NONBLOCK`` flag was given to the
+:ref:`open() <func-open>` function, ``VIDIOC_DQBUF`` returns
+immediately with an ``EAGAIN`` error code when no buffer is available.
+
+The :ref:`struct v4l2_buffer <v4l2-buffer>` structure is specified in
+:ref:`buffer`.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EAGAIN
+ Non-blocking I/O has been selected using ``O_NONBLOCK`` and no
+ buffer was in the outgoing queue.
+
+EINVAL
+ The buffer ``type`` is not supported, or the ``index`` is out of
+ bounds, or no buffers have been allocated yet, or the ``userptr`` or
+ ``length`` are invalid.
+
+EIO
+ ``VIDIOC_DQBUF`` failed due to an internal error. Can also indicate
+ temporary problems like signal loss. Note the driver might dequeue
+ an (empty) buffer despite returning an error, or even stop
+ capturing. Reusing such buffer may be unsafe though and its details
+ (e.g. ``index``) may not be returned either. It is recommended that
+ drivers indicate recoverable errors by setting the
+ ``V4L2_BUF_FLAG_ERROR`` and returning 0 instead. In that case the
+ application should be able to safely reuse the buffer and continue
+ streaming.
+
+EPIPE
+ ``VIDIOC_DQBUF`` returns this on an empty capture queue for mem2mem
+ codecs if a buffer with the ``V4L2_BUF_FLAG_LAST`` was already
+ dequeued and no new buffers are expected to become available.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_QUERY_DV_TIMINGS:
+
+*****************************
+ioctl VIDIOC_QUERY_DV_TIMINGS
+*****************************
+
+Name
+====
+
+VIDIOC_QUERY_DV_TIMINGS - VIDIOC_SUBDEV_QUERY_DV_TIMINGS - Sense the DV preset received by the current input
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_dv_timings *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_QUERY_DV_TIMINGS, VIDIOC_SUBDEV_QUERY_DV_TIMINGS
+
+``argp``
+
+
+Description
+===========
+
+The hardware may be able to detect the current DV timings automatically,
+similar to sensing the video standard. To do so, applications call
+:ref:`VIDIOC_QUERY_DV_TIMINGS` with a pointer to a struct
+:ref:`v4l2_dv_timings <v4l2-dv-timings>`. Once the hardware detects
+the timings, it will fill in the timings structure.
+
+Please note that drivers shall *not* switch timings automatically if new
+timings are detected. Instead, drivers should send the
+``V4L2_EVENT_SOURCE_CHANGE`` event (if they support this) and expect
+that userspace will take action by calling :ref:`VIDIOC_QUERY_DV_TIMINGS`.
+The reason is that new timings usually mean different buffer sizes as
+well, and you cannot change buffer sizes on the fly. In general,
+applications that receive the Source Change event will have to call
+:ref:`VIDIOC_QUERY_DV_TIMINGS`, and if the detected timings are valid they
+will have to stop streaming, set the new timings, allocate new buffers
+and start streaming again.
+
+If the timings could not be detected because there was no signal, then
+ENOLINK is returned. If a signal was detected, but it was unstable and
+the receiver could not lock to the signal, then ``ENOLCK`` is returned. If
+the receiver could lock to the signal, but the format is unsupported
+(e.g. because the pixelclock is out of range of the hardware
+capabilities), then the driver fills in whatever timings it could find
+and returns ``ERANGE``. In that case the application can call
+:ref:`VIDIOC_DV_TIMINGS_CAP` to compare the
+found timings with the hardware's capabilities in order to give more
+precise feedback to the user.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+ENODATA
+ Digital video timings are not supported for this input or output.
+
+ENOLINK
+ No timings could be detected because no signal was found.
+
+ENOLCK
+ The signal was unstable and the hardware could not lock on to it.
+
+ERANGE
+ Timings were found, but they are out of range of the hardware
+ capabilities.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_QUERYBUF:
+
+*********************
+ioctl VIDIOC_QUERYBUF
+*********************
+
+Name
+====
+
+VIDIOC_QUERYBUF - Query the status of a buffer
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_buffer *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_QUERYBUF
+
+``argp``
+
+
+Description
+===========
+
+This ioctl is part of the :ref:`streaming <mmap>` I/O method. It can
+be used to query the status of a buffer at any time after buffers have
+been allocated with the :ref:`VIDIOC_REQBUFS` ioctl.
+
+Applications set the ``type`` field of a struct
+:ref:`v4l2_buffer <v4l2-buffer>` to the same buffer type as was
+previously used with struct :ref:`v4l2_format <v4l2-format>` ``type``
+and struct :ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``type``,
+and the ``index`` field. Valid index numbers range from zero to the
+number of buffers allocated with
+:ref:`VIDIOC_REQBUFS` (struct
+:ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``count``) minus
+one. The ``reserved`` and ``reserved2`` fields must be set to 0. When
+using the :ref:`multi-planar API <planar-apis>`, the ``m.planes``
+field must contain a userspace pointer to an array of struct
+:ref:`v4l2_plane <v4l2-plane>` and the ``length`` field has to be set
+to the number of elements in that array. After calling
+:ref:`VIDIOC_QUERYBUF` with a pointer to this structure drivers return an
+error code or fill the rest of the structure.
+
+In the ``flags`` field the ``V4L2_BUF_FLAG_MAPPED``,
+``V4L2_BUF_FLAG_PREPARED``, ``V4L2_BUF_FLAG_QUEUED`` and
+``V4L2_BUF_FLAG_DONE`` flags will be valid. The ``memory`` field will be
+set to the current I/O method. For the single-planar API, the
+``m.offset`` contains the offset of the buffer from the start of the
+device memory, the ``length`` field its size. For the multi-planar API,
+fields ``m.mem_offset`` and ``length`` in the ``m.planes`` array
+elements will be used instead and the ``length`` field of struct
+:ref:`v4l2_buffer <v4l2-buffer>` is set to the number of filled-in
+array elements. The driver may or may not set the remaining fields and
+flags, they are meaningless in this context.
+
+The :ref:`struct v4l2_buffer <v4l2-buffer>` structure is specified in
+:ref:`buffer`.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The buffer ``type`` is not supported, or the ``index`` is out of
+ bounds.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_QUERYCAP:
+
+*********************
+ioctl VIDIOC_QUERYCAP
+*********************
+
+Name
+====
+
+VIDIOC_QUERYCAP - Query device capabilities
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_capability *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_QUERYCAP
+
+``argp``
+
+
+Description
+===========
+
+All V4L2 devices support the ``VIDIOC_QUERYCAP`` ioctl. It is used to
+identify kernel devices compatible with this specification and to obtain
+information about driver and hardware capabilities. The ioctl takes a
+pointer to a struct :ref:`v4l2_capability <v4l2-capability>` which is
+filled by the driver. When the driver is not compatible with this
+specification the ioctl returns an ``EINVAL`` error code.
+
+
+.. _v4l2-capability:
+
+.. flat-table:: struct v4l2_capability
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u8
+
+ - ``driver``\ [16]
+
+ - Name of the driver, a unique NUL-terminated ASCII string. For
+ example: "bttv". Driver specific applications can use this
+ information to verify the driver identity. It is also useful to
+ work around known bugs, or to identify drivers in error reports.
+
+ Storing strings in fixed sized arrays is bad practice but
+ unavoidable here. Drivers and applications should take precautions
+ to never read or write beyond the end of the array and to make
+ sure the strings are properly NUL-terminated.
+
+ - .. row 2
+
+ - __u8
+
+ - ``card``\ [32]
+
+ - Name of the device, a NUL-terminated UTF-8 string. For example:
+ "Yoyodyne TV/FM". One driver may support different brands or
+ models of video hardware. This information is intended for users,
+ for example in a menu of available devices. Since multiple TV
+ cards of the same brand may be installed which are supported by
+ the same driver, this name should be combined with the character
+ device file name (e. g. ``/dev/video2``) or the ``bus_info``
+ string to avoid ambiguities.
+
+ - .. row 3
+
+ - __u8
+
+ - ``bus_info``\ [32]
+
+ - Location of the device in the system, a NUL-terminated ASCII
+ string. For example: "PCI:0000:05:06.0". This information is
+ intended for users, to distinguish multiple identical devices. If
+ no such information is available the field must simply count the
+ devices controlled by the driver ("platform:vivi-000"). The
+ bus_info must start with "PCI:" for PCI boards, "PCIe:" for PCI
+ Express boards, "usb-" for USB devices, "I2C:" for i2c devices,
+ "ISA:" for ISA devices, "parport" for parallel port devices and
+ "platform:" for platform devices.
+
+ - .. row 4
+
+ - __u32
+
+ - ``version``
+
+ - Version number of the driver.
+
+ Starting with kernel 3.1, the version reported is provided by the
+ V4L2 subsystem following the kernel numbering scheme. However, it
+ may not always return the same version as the kernel if, for
+ example, a stable or distribution-modified kernel uses the V4L2
+ stack from a newer kernel.
+
+ The version number is formatted using the ``KERNEL_VERSION()``
+ macro:
+
+ - .. row 5
+
+ - :cspan:`2`
+
+
+ .. code-block:: c
+
+ #define KERNEL_VERSION(a,b,c) (((a) << 16) + ((b) << 8) + (c))
+
+ __u32 version = KERNEL_VERSION(0, 8, 1);
+
+ printf ("Version: %u.%u.%u\\n",
+ (version >> 16) & 0xFF,
+ (version >> 8) & 0xFF,
+ version & 0xFF);
+
+ - .. row 6
+
+ - __u32
+
+ - ``capabilities``
+
+ - Available capabilities of the physical device as a whole, see
+ :ref:`device-capabilities`. The same physical device can export
+ multiple devices in /dev (e.g. /dev/videoX, /dev/vbiY and
+ /dev/radioZ). The ``capabilities`` field should contain a union of
+ all capabilities available around the several V4L2 devices
+ exported to userspace. For all those devices the ``capabilities``
+ field returns the same set of capabilities. This allows
+ applications to open just one of the devices (typically the video
+ device) and discover whether video, vbi and/or radio are also
+ supported.
+
+ - .. row 7
+
+ - __u32
+
+ - ``device_caps``
+
+ - Device capabilities of the opened device, see
+ :ref:`device-capabilities`. Should contain the available
+ capabilities of that specific device node. So, for example,
+ ``device_caps`` of a radio device will only contain radio related
+ capabilities and no video or vbi capabilities. This field is only
+ set if the ``capabilities`` field contains the
+ ``V4L2_CAP_DEVICE_CAPS`` capability. Only the ``capabilities``
+ field can have the ``V4L2_CAP_DEVICE_CAPS`` capability,
+ ``device_caps`` will never set ``V4L2_CAP_DEVICE_CAPS``.
+
+ - .. row 8
+
+ - __u32
+
+ - ``reserved``\ [3]
+
+ - Reserved for future extensions. Drivers must set this array to
+ zero.
+
+
+
+.. _device-capabilities:
+
+.. flat-table:: Device Capabilities Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_CAP_VIDEO_CAPTURE``
+
+ - 0x00000001
+
+ - The device supports the single-planar API through the
+ :ref:`Video Capture <capture>` interface.
+
+ - .. row 2
+
+ - ``V4L2_CAP_VIDEO_CAPTURE_MPLANE``
+
+ - 0x00001000
+
+ - The device supports the :ref:`multi-planar API <planar-apis>`
+ through the :ref:`Video Capture <capture>` interface.
+
+ - .. row 3
+
+ - ``V4L2_CAP_VIDEO_OUTPUT``
+
+ - 0x00000002
+
+ - The device supports the single-planar API through the
+ :ref:`Video Output <output>` interface.
+
+ - .. row 4
+
+ - ``V4L2_CAP_VIDEO_OUTPUT_MPLANE``
+
+ - 0x00002000
+
+ - The device supports the :ref:`multi-planar API <planar-apis>`
+ through the :ref:`Video Output <output>` interface.
+
+ - .. row 5
+
+ - ``V4L2_CAP_VIDEO_M2M``
+
+ - 0x00004000
+
+ - The device supports the single-planar API through the Video
+ Memory-To-Memory interface.
+
+ - .. row 6
+
+ - ``V4L2_CAP_VIDEO_M2M_MPLANE``
+
+ - 0x00008000
+
+ - The device supports the :ref:`multi-planar API <planar-apis>`
+ through the Video Memory-To-Memory interface.
+
+ - .. row 7
+
+ - ``V4L2_CAP_VIDEO_OVERLAY``
+
+ - 0x00000004
+
+ - The device supports the :ref:`Video Overlay <overlay>`
+ interface. A video overlay device typically stores captured images
+ directly in the video memory of a graphics card, with hardware
+ clipping and scaling.
+
+ - .. row 8
+
+ - ``V4L2_CAP_VBI_CAPTURE``
+
+ - 0x00000010
+
+ - The device supports the :ref:`Raw VBI Capture <raw-vbi>`
+ interface, providing Teletext and Closed Caption data.
+
+ - .. row 9
+
+ - ``V4L2_CAP_VBI_OUTPUT``
+
+ - 0x00000020
+
+ - The device supports the :ref:`Raw VBI Output <raw-vbi>`
+ interface.
+
+ - .. row 10
+
+ - ``V4L2_CAP_SLICED_VBI_CAPTURE``
+
+ - 0x00000040
+
+ - The device supports the :ref:`Sliced VBI Capture <sliced>`
+ interface.
+
+ - .. row 11
+
+ - ``V4L2_CAP_SLICED_VBI_OUTPUT``
+
+ - 0x00000080
+
+ - The device supports the :ref:`Sliced VBI Output <sliced>`
+ interface.
+
+ - .. row 12
+
+ - ``V4L2_CAP_RDS_CAPTURE``
+
+ - 0x00000100
+
+ - The device supports the :ref:`RDS <rds>` capture interface.
+
+ - .. row 13
+
+ - ``V4L2_CAP_VIDEO_OUTPUT_OVERLAY``
+
+ - 0x00000200
+
+ - The device supports the :ref:`Video Output Overlay <osd>` (OSD)
+ interface. Unlike the *Video Overlay* interface, this is a
+ secondary function of video output devices and overlays an image
+ onto an outgoing video signal. When the driver sets this flag, it
+ must clear the ``V4L2_CAP_VIDEO_OVERLAY`` flag and vice
+ versa. [1]_
+
+ - .. row 14
+
+ - ``V4L2_CAP_HW_FREQ_SEEK``
+
+ - 0x00000400
+
+ - The device supports the
+ :ref:`VIDIOC_S_HW_FREQ_SEEK` ioctl
+ for hardware frequency seeking.
+
+ - .. row 15
+
+ - ``V4L2_CAP_RDS_OUTPUT``
+
+ - 0x00000800
+
+ - The device supports the :ref:`RDS <rds>` output interface.
+
+ - .. row 16
+
+ - ``V4L2_CAP_TUNER``
+
+ - 0x00010000
+
+ - The device has some sort of tuner to receive RF-modulated video
+ signals. For more information about tuner programming see
+ :ref:`tuner`.
+
+ - .. row 17
+
+ - ``V4L2_CAP_AUDIO``
+
+ - 0x00020000
+
+ - The device has audio inputs or outputs. It may or may not support
+ audio recording or playback, in PCM or compressed formats. PCM
+ audio support must be implemented as ALSA or OSS interface. For
+ more information on audio inputs and outputs see :ref:`audio`.
+
+ - .. row 18
+
+ - ``V4L2_CAP_RADIO``
+
+ - 0x00040000
+
+ - This is a radio receiver.
+
+ - .. row 19
+
+ - ``V4L2_CAP_MODULATOR``
+
+ - 0x00080000
+
+ - The device has some sort of modulator to emit RF-modulated
+ video/audio signals. For more information about modulator
+ programming see :ref:`tuner`.
+
+ - .. row 20
+
+ - ``V4L2_CAP_SDR_CAPTURE``
+
+ - 0x00100000
+
+ - The device supports the :ref:`SDR Capture <sdr>` interface.
+
+ - .. row 21
+
+ - ``V4L2_CAP_EXT_PIX_FORMAT``
+
+ - 0x00200000
+
+ - The device supports the struct
+ :ref:`v4l2_pix_format <v4l2-pix-format>` extended fields.
+
+ - .. row 22
+
+ - ``V4L2_CAP_SDR_OUTPUT``
+
+ - 0x00400000
+
+ - The device supports the :ref:`SDR Output <sdr>` interface.
+
+ - .. row 23
+
+ - ``V4L2_CAP_READWRITE``
+
+ - 0x01000000
+
+ - The device supports the :ref:`read() <rw>` and/or
+ :ref:`write() <rw>` I/O methods.
+
+ - .. row 24
+
+ - ``V4L2_CAP_ASYNCIO``
+
+ - 0x02000000
+
+ - The device supports the :ref:`asynchronous <async>` I/O methods.
+
+ - .. row 25
+
+ - ``V4L2_CAP_STREAMING``
+
+ - 0x04000000
+
+ - The device supports the :ref:`streaming <mmap>` I/O method.
+
+ - .. row 26
+
+ - ``V4L2_CAP_DEVICE_CAPS``
+
+ - 0x80000000
+
+ - The driver fills the ``device_caps`` field. This capability can
+ only appear in the ``capabilities`` field and never in the
+ ``device_caps`` field.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+.. [1]
+ The struct :ref:`v4l2_framebuffer <v4l2-framebuffer>` lacks an
+ enum :ref:`v4l2_buf_type <v4l2-buf-type>` field, therefore the
+ type of overlay is implied by the driver capabilities.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_QUERYCTRL:
+
+*******************************************************************
+ioctls VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL and VIDIOC_QUERYMENU
+*******************************************************************
+
+Name
+====
+
+VIDIOC_QUERYCTRL - VIDIOC_QUERY_EXT_CTRL - VIDIOC_QUERYMENU - Enumerate controls and menu control items
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_queryctrl *argp )
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_query_ext_ctrl *argp )
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_querymenu *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL, VIDIOC_QUERYMENU
+
+``argp``
+
+
+Description
+===========
+
+To query the attributes of a control applications set the ``id`` field
+of a struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` and call the
+``VIDIOC_QUERYCTRL`` ioctl with a pointer to this structure. The driver
+fills the rest of the structure or returns an ``EINVAL`` error code when the
+``id`` is invalid.
+
+It is possible to enumerate controls by calling ``VIDIOC_QUERYCTRL``
+with successive ``id`` values starting from ``V4L2_CID_BASE`` up to and
+exclusive ``V4L2_CID_LASTP1``. Drivers may return ``EINVAL`` if a control in
+this range is not supported. Further applications can enumerate private
+controls, which are not defined in this specification, by starting at
+``V4L2_CID_PRIVATE_BASE`` and incrementing ``id`` until the driver
+returns ``EINVAL``.
+
+In both cases, when the driver sets the ``V4L2_CTRL_FLAG_DISABLED`` flag
+in the ``flags`` field this control is permanently disabled and should
+be ignored by the application. [1]_
+
+When the application ORs ``id`` with ``V4L2_CTRL_FLAG_NEXT_CTRL`` the
+driver returns the next supported non-compound control, or ``EINVAL`` if
+there is none. In addition, the ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` flag
+can be specified to enumerate all compound controls (i.e. controls with
+type ≥ ``V4L2_CTRL_COMPOUND_TYPES`` and/or array control, in other words
+controls that contain more than one value). Specify both
+``V4L2_CTRL_FLAG_NEXT_CTRL`` and ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` in
+order to enumerate all controls, compound or not. Drivers which do not
+support these flags yet always return ``EINVAL``.
+
+The ``VIDIOC_QUERY_EXT_CTRL`` ioctl was introduced in order to better
+support controls that can use compound types, and to expose additional
+control information that cannot be returned in struct
+:ref:`v4l2_queryctrl <v4l2-queryctrl>` since that structure is full.
+
+``VIDIOC_QUERY_EXT_CTRL`` is used in the same way as
+``VIDIOC_QUERYCTRL``, except that the ``reserved`` array must be zeroed
+as well.
+
+Additional information is required for menu controls: the names of the
+menu items. To query them applications set the ``id`` and ``index``
+fields of struct :ref:`v4l2_querymenu <v4l2-querymenu>` and call the
+``VIDIOC_QUERYMENU`` ioctl with a pointer to this structure. The driver
+fills the rest of the structure or returns an ``EINVAL`` error code when the
+``id`` or ``index`` is invalid. Menu items are enumerated by calling
+``VIDIOC_QUERYMENU`` with successive ``index`` values from struct
+:ref:`v4l2_queryctrl <v4l2-queryctrl>` ``minimum`` to ``maximum``,
+inclusive. Note that it is possible for ``VIDIOC_QUERYMENU`` to return
+an ``EINVAL`` error code for some indices between ``minimum`` and
+``maximum``. In that case that particular menu item is not supported by
+this driver. Also note that the ``minimum`` value is not necessarily 0.
+
+See also the examples in :ref:`control`.
+
+
+.. _v4l2-queryctrl:
+
+.. flat-table:: struct v4l2_queryctrl
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``id``
+
+ - Identifies the control, set by the application. See
+ :ref:`control-id` for predefined IDs. When the ID is ORed with
+ V4L2_CTRL_FLAG_NEXT_CTRL the driver clears the flag and
+ returns the first control with a higher ID. Drivers which do not
+ support this flag yet always return an ``EINVAL`` error code.
+
+ - .. row 2
+
+ - __u32
+
+ - ``type``
+
+ - Type of control, see :ref:`v4l2-ctrl-type`.
+
+ - .. row 3
+
+ - __u8
+
+ - ``name``\ [32]
+
+ - Name of the control, a NUL-terminated ASCII string. This
+ information is intended for the user.
+
+ - .. row 4
+
+ - __s32
+
+ - ``minimum``
+
+ - Minimum value, inclusive. This field gives a lower bound for the
+ control. See enum :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how
+ the minimum value is to be used for each possible control type.
+ Note that this a signed 32-bit value.
+
+ - .. row 5
+
+ - __s32
+
+ - ``maximum``
+
+ - Maximum value, inclusive. This field gives an upper bound for the
+ control. See enum :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how
+ the maximum value is to be used for each possible control type.
+ Note that this a signed 32-bit value.
+
+ - .. row 6
+
+ - __s32
+
+ - ``step``
+
+ - This field gives a step size for the control. See enum
+ :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how the step value is
+ to be used for each possible control type. Note that this an
+ unsigned 32-bit value.
+
+ Generally drivers should not scale hardware control values. It may
+ be necessary for example when the ``name`` or ``id`` imply a
+ particular unit and the hardware actually accepts only multiples
+ of said unit. If so, drivers must take care values are properly
+ rounded when scaling, such that errors will not accumulate on
+ repeated read-write cycles.
+
+ This field gives the smallest change of an integer control
+ actually affecting hardware. Often the information is needed when
+ the user can change controls by keyboard or GUI buttons, rather
+ than a slider. When for example a hardware register accepts values
+ 0-511 and the driver reports 0-65535, step should be 128.
+
+ Note that although signed, the step value is supposed to be always
+ positive.
+
+ - .. row 7
+
+ - __s32
+
+ - ``default_value``
+
+ - The default value of a ``V4L2_CTRL_TYPE_INTEGER``, ``_BOOLEAN``,
+ ``_BITMASK``, ``_MENU`` or ``_INTEGER_MENU`` control. Not valid
+ for other types of controls. Note that drivers reset controls to
+ their default value only when the driver is first loaded, never
+ afterwards.
+
+ - .. row 8
+
+ - __u32
+
+ - ``flags``
+
+ - Control flags, see :ref:`control-flags`.
+
+ - .. row 9
+
+ - __u32
+
+ - ``reserved``\ [2]
+
+ - Reserved for future extensions. Drivers must set the array to
+ zero.
+
+
+
+.. _v4l2-query-ext-ctrl:
+
+.. flat-table:: struct v4l2_query_ext_ctrl
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``id``
+
+ - Identifies the control, set by the application. See
+ :ref:`control-id` for predefined IDs. When the ID is ORed with
+ ``V4L2_CTRL_FLAG_NEXT_CTRL`` the driver clears the flag and
+ returns the first non-compound control with a higher ID. When the
+ ID is ORed with ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` the driver clears
+ the flag and returns the first compound control with a higher ID.
+ Set both to get the first control (compound or not) with a higher
+ ID.
+
+ - .. row 2
+
+ - __u32
+
+ - ``type``
+
+ - Type of control, see :ref:`v4l2-ctrl-type`.
+
+ - .. row 3
+
+ - char
+
+ - ``name``\ [32]
+
+ - Name of the control, a NUL-terminated ASCII string. This
+ information is intended for the user.
+
+ - .. row 4
+
+ - __s64
+
+ - ``minimum``
+
+ - Minimum value, inclusive. This field gives a lower bound for the
+ control. See enum :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how
+ the minimum value is to be used for each possible control type.
+ Note that this a signed 64-bit value.
+
+ - .. row 5
+
+ - __s64
+
+ - ``maximum``
+
+ - Maximum value, inclusive. This field gives an upper bound for the
+ control. See enum :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how
+ the maximum value is to be used for each possible control type.
+ Note that this a signed 64-bit value.
+
+ - .. row 6
+
+ - __u64
+
+ - ``step``
+
+ - This field gives a step size for the control. See enum
+ :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how the step value is
+ to be used for each possible control type. Note that this an
+ unsigned 64-bit value.
+
+ Generally drivers should not scale hardware control values. It may
+ be necessary for example when the ``name`` or ``id`` imply a
+ particular unit and the hardware actually accepts only multiples
+ of said unit. If so, drivers must take care values are properly
+ rounded when scaling, such that errors will not accumulate on
+ repeated read-write cycles.
+
+ This field gives the smallest change of an integer control
+ actually affecting hardware. Often the information is needed when
+ the user can change controls by keyboard or GUI buttons, rather
+ than a slider. When for example a hardware register accepts values
+ 0-511 and the driver reports 0-65535, step should be 128.
+
+ - .. row 7
+
+ - __s64
+
+ - ``default_value``
+
+ - The default value of a ``V4L2_CTRL_TYPE_INTEGER``, ``_INTEGER64``,
+ ``_BOOLEAN``, ``_BITMASK``, ``_MENU``, ``_INTEGER_MENU``, ``_U8``
+ or ``_U16`` control. Not valid for other types of controls. Note
+ that drivers reset controls to their default value only when the
+ driver is first loaded, never afterwards.
+
+ - .. row 8
+
+ - __u32
+
+ - ``flags``
+
+ - Control flags, see :ref:`control-flags`.
+
+ - .. row 9
+
+ - __u32
+
+ - ``elem_size``
+
+ - The size in bytes of a single element of the array. Given a char
+ pointer ``p`` to a 3-dimensional array you can find the position
+ of cell ``(z, y, x)`` as follows:
+ ``p + ((z * dims[1] + y) * dims[0] + x) * elem_size``.
+ ``elem_size`` is always valid, also when the control isn't an
+ array. For string controls ``elem_size`` is equal to
+ ``maximum + 1``.
+
+ - .. row 10
+
+ - __u32
+
+ - ``elems``
+
+ - The number of elements in the N-dimensional array. If this control
+ is not an array, then ``elems`` is 1. The ``elems`` field can
+ never be 0.
+
+ - .. row 11
+
+ - __u32
+
+ - ``nr_of_dims``
+
+ - The number of dimension in the N-dimensional array. If this
+ control is not an array, then this field is 0.
+
+ - .. row 12
+
+ - __u32
+
+ - ``dims[V4L2_CTRL_MAX_DIMS]``
+
+ - The size of each dimension. The first ``nr_of_dims`` elements of
+ this array must be non-zero, all remaining elements must be zero.
+
+ - .. row 13
+
+ - __u32
+
+ - ``reserved``\ [32]
+
+ - Reserved for future extensions. Applications and drivers must set
+ the array to zero.
+
+
+
+.. _v4l2-querymenu:
+
+.. flat-table:: struct v4l2_querymenu
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2 1
+
+
+ - .. row 1
+
+ - __u32
+
+ -
+ - ``id``
+
+ - Identifies the control, set by the application from the respective
+ struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``id``.
+
+ - .. row 2
+
+ - __u32
+
+ -
+ - ``index``
+
+ - Index of the menu item, starting at zero, set by the application.
+
+ - .. row 3
+
+ - union
+
+ -
+ -
+ -
+
+ - .. row 4
+
+ -
+ - __u8
+
+ - ``name``\ [32]
+
+ - Name of the menu item, a NUL-terminated ASCII string. This
+ information is intended for the user. This field is valid for
+ ``V4L2_CTRL_FLAG_MENU`` type controls.
+
+ - .. row 5
+
+ -
+ - __s64
+
+ - ``value``
+
+ - Value of the integer menu item. This field is valid for
+ ``V4L2_CTRL_FLAG_INTEGER_MENU`` type controls.
+
+ - .. row 6
+
+ - __u32
+
+ -
+ - ``reserved``
+
+ - Reserved for future extensions. Drivers must set the array to
+ zero.
+
+
+
+.. _v4l2-ctrl-type:
+
+.. flat-table:: enum v4l2_ctrl_type
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 30 5 5 5 55
+
+
+ - .. row 1
+
+ - Type
+
+ - ``minimum``
+
+ - ``step``
+
+ - ``maximum``
+
+ - Description
+
+ - .. row 2
+
+ - ``V4L2_CTRL_TYPE_INTEGER``
+
+ - any
+
+ - any
+
+ - any
+
+ - An integer-valued control ranging from minimum to maximum
+ inclusive. The step value indicates the increment between values.
+
+ - .. row 3
+
+ - ``V4L2_CTRL_TYPE_BOOLEAN``
+
+ - 0
+
+ - 1
+
+ - 1
+
+ - A boolean-valued control. Zero corresponds to "disabled", and one
+ means "enabled".
+
+ - .. row 4
+
+ - ``V4L2_CTRL_TYPE_MENU``
+
+ - ≥ 0
+
+ - 1
+
+ - N-1
+
+ - The control has a menu of N choices. The names of the menu items
+ can be enumerated with the ``VIDIOC_QUERYMENU`` ioctl.
+
+ - .. row 5
+
+ - ``V4L2_CTRL_TYPE_INTEGER_MENU``
+
+ - ≥ 0
+
+ - 1
+
+ - N-1
+
+ - The control has a menu of N choices. The values of the menu items
+ can be enumerated with the ``VIDIOC_QUERYMENU`` ioctl. This is
+ similar to ``V4L2_CTRL_TYPE_MENU`` except that instead of strings,
+ the menu items are signed 64-bit integers.
+
+ - .. row 6
+
+ - ``V4L2_CTRL_TYPE_BITMASK``
+
+ - 0
+
+ - n/a
+
+ - any
+
+ - A bitmask field. The maximum value is the set of bits that can be
+ used, all other bits are to be 0. The maximum value is interpreted
+ as a __u32, allowing the use of bit 31 in the bitmask.
+
+ - .. row 7
+
+ - ``V4L2_CTRL_TYPE_BUTTON``
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - A control which performs an action when set. Drivers must ignore
+ the value passed with ``VIDIOC_S_CTRL`` and return an ``EINVAL`` error
+ code on a ``VIDIOC_G_CTRL`` attempt.
+
+ - .. row 8
+
+ - ``V4L2_CTRL_TYPE_INTEGER64``
+
+ - any
+
+ - any
+
+ - any
+
+ - A 64-bit integer valued control. Minimum, maximum and step size
+ cannot be queried using ``VIDIOC_QUERYCTRL``. Only
+ ``VIDIOC_QUERY_EXT_CTRL`` can retrieve the 64-bit min/max/step
+ values, they should be interpreted as n/a when using
+ ``VIDIOC_QUERYCTRL``.
+
+ - .. row 9
+
+ - ``V4L2_CTRL_TYPE_STRING``
+
+ - ≥ 0
+
+ - ≥ 1
+
+ - ≥ 0
+
+ - The minimum and maximum string lengths. The step size means that
+ the string must be (minimum + N * step) characters long for N ≥ 0.
+ These lengths do not include the terminating zero, so in order to
+ pass a string of length 8 to
+ :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` you need to
+ set the ``size`` field of struct
+ :ref:`v4l2_ext_control <v4l2-ext-control>` to 9. For
+ :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` you can set
+ the ``size`` field to ``maximum`` + 1. Which character encoding is
+ used will depend on the string control itself and should be part
+ of the control documentation.
+
+ - .. row 10
+
+ - ``V4L2_CTRL_TYPE_CTRL_CLASS``
+
+ - n/a
+
+ - n/a
+
+ - n/a
+
+ - This is not a control. When ``VIDIOC_QUERYCTRL`` is called with a
+ control ID equal to a control class code (see :ref:`ctrl-class`)
+ + 1, the ioctl returns the name of the control class and this
+ control type. Older drivers which do not support this feature
+ return an ``EINVAL`` error code.
+
+ - .. row 11
+
+ - ``V4L2_CTRL_TYPE_U8``
+
+ - any
+
+ - any
+
+ - any
+
+ - An unsigned 8-bit valued control ranging from minimum to maximum
+ inclusive. The step value indicates the increment between values.
+
+ - .. row 12
+
+ - ``V4L2_CTRL_TYPE_U16``
+
+ - any
+
+ - any
+
+ - any
+
+ - An unsigned 16-bit valued control ranging from minimum to maximum
+ inclusive. The step value indicates the increment between values.
+
+ - .. row 13
+
+ - ``V4L2_CTRL_TYPE_U32``
+
+ - any
+
+ - any
+
+ - any
+
+ - An unsigned 32-bit valued control ranging from minimum to maximum
+ inclusive. The step value indicates the increment between values.
+
+
+
+.. _control-flags:
+
+.. flat-table:: Control Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_CTRL_FLAG_DISABLED``
+
+ - 0x0001
+
+ - This control is permanently disabled and should be ignored by the
+ application. Any attempt to change the control will result in an
+ ``EINVAL`` error code.
+
+ - .. row 2
+
+ - ``V4L2_CTRL_FLAG_GRABBED``
+
+ - 0x0002
+
+ - This control is temporarily unchangeable, for example because
+ another application took over control of the respective resource.
+ Such controls may be displayed specially in a user interface.
+ Attempts to change the control may result in an ``EBUSY`` error code.
+
+ - .. row 3
+
+ - ``V4L2_CTRL_FLAG_READ_ONLY``
+
+ - 0x0004
+
+ - This control is permanently readable only. Any attempt to change
+ the control will result in an ``EINVAL`` error code.
+
+ - .. row 4
+
+ - ``V4L2_CTRL_FLAG_UPDATE``
+
+ - 0x0008
+
+ - A hint that changing this control may affect the value of other
+ controls within the same control class. Applications should update
+ their user interface accordingly.
+
+ - .. row 5
+
+ - ``V4L2_CTRL_FLAG_INACTIVE``
+
+ - 0x0010
+
+ - This control is not applicable to the current configuration and
+ should be displayed accordingly in a user interface. For example
+ the flag may be set on a MPEG audio level 2 bitrate control when
+ MPEG audio encoding level 1 was selected with another control.
+
+ - .. row 6
+
+ - ``V4L2_CTRL_FLAG_SLIDER``
+
+ - 0x0020
+
+ - A hint that this control is best represented as a slider-like
+ element in a user interface.
+
+ - .. row 7
+
+ - ``V4L2_CTRL_FLAG_WRITE_ONLY``
+
+ - 0x0040
+
+ - This control is permanently writable only. Any attempt to read the
+ control will result in an ``EACCES`` error code error code. This flag
+ is typically present for relative controls or action controls
+ where writing a value will cause the device to carry out a given
+ action (e. g. motor control) but no meaningful value can be
+ returned.
+
+ - .. row 8
+
+ - ``V4L2_CTRL_FLAG_VOLATILE``
+
+ - 0x0080
+
+ - This control is volatile, which means that the value of the
+ control changes continuously. A typical example would be the
+ current gain value if the device is in auto-gain mode. In such a
+ case the hardware calculates the gain value based on the lighting
+ conditions which can change over time. Note that setting a new
+ value for a volatile control will have no effect and no
+ ``V4L2_EVENT_CTRL_CH_VALUE`` will be sent, unless the
+ ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE`` flag (see below) is also set.
+ Otherwise the new value will just be ignored.
+
+ - .. row 9
+
+ - ``V4L2_CTRL_FLAG_HAS_PAYLOAD``
+
+ - 0x0100
+
+ - This control has a pointer type, so its value has to be accessed
+ using one of the pointer fields of struct
+ :ref:`v4l2_ext_control <v4l2-ext-control>`. This flag is set
+ for controls that are an array, string, or have a compound type.
+ In all cases you have to set a pointer to memory containing the
+ payload of the control.
+
+ - .. row 10
+
+ - ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE``
+
+ - 0x0200
+
+ - The value provided to the control will be propagated to the driver
+ even if it remains constant. This is required when the control
+ represents an action on the hardware. For example: clearing an
+ error flag or triggering the flash. All the controls of the type
+ ``V4L2_CTRL_TYPE_BUTTON`` have this flag set.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``id`` is
+ invalid. The struct :ref:`v4l2_querymenu <v4l2-querymenu>` ``id``
+ is invalid or ``index`` is out of range (less than ``minimum`` or
+ greater than ``maximum``) or this particular menu item is not
+ supported by the driver.
+
+EACCES
+ An attempt was made to read a write-only control.
+
+.. [1]
+ ``V4L2_CTRL_FLAG_DISABLED`` was intended for two purposes: Drivers
+ can skip predefined controls not supported by the hardware (although
+ returning ``EINVAL`` would do as well), or disable predefined and private
+ controls after hardware detection without the trouble of reordering
+ control arrays and indices (``EINVAL`` cannot be used to skip private
+ controls because it would prematurely end the enumeration).
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_QUERYSTD:
+
+*********************
+ioctl VIDIOC_QUERYSTD
+*********************
+
+Name
+====
+
+VIDIOC_QUERYSTD - Sense the video standard received by the current input
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, v4l2_std_id *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_QUERYSTD
+
+``argp``
+
+
+Description
+===========
+
+The hardware may be able to detect the current video standard
+automatically. To do so, applications call :ref:`VIDIOC_QUERYSTD` with a
+pointer to a :ref:`v4l2_std_id <v4l2-std-id>` type. The driver
+stores here a set of candidates, this can be a single flag or a set of
+supported standards if for example the hardware can only distinguish
+between 50 and 60 Hz systems. If no signal was detected, then the driver
+will return V4L2_STD_UNKNOWN. When detection is not possible or fails,
+the set must contain all standards supported by the current video input
+or output.
+
+Please note that drivers shall *not* switch the video standard
+automatically if a new video standard is detected. Instead, drivers
+should send the ``V4L2_EVENT_SOURCE_CHANGE`` event (if they support
+this) and expect that userspace will take action by calling
+:ref:`VIDIOC_QUERYSTD`. The reason is that a new video standard can mean
+different buffer sizes as well, and you cannot change buffer sizes on
+the fly. In general, applications that receive the Source Change event
+will have to call :ref:`VIDIOC_QUERYSTD`, and if the detected video
+standard is valid they will have to stop streaming, set the new
+standard, allocate new buffers and start streaming again.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+ENODATA
+ Standard video timings are not supported for this input or output.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_REQBUFS:
+
+********************
+ioctl VIDIOC_REQBUFS
+********************
+
+Name
+====
+
+VIDIOC_REQBUFS - Initiate Memory Mapping or User Pointer I/O
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_requestbuffers *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_REQBUFS
+
+``argp``
+
+
+Description
+===========
+
+This ioctl is used to initiate :ref:`memory mapped <mmap>`,
+:ref:`user pointer <userp>` or :ref:`DMABUF <dmabuf>` based I/O.
+Memory mapped buffers are located in device memory and must be allocated
+with this ioctl before they can be mapped into the application's address
+space. User buffers are allocated by applications themselves, and this
+ioctl is merely used to switch the driver into user pointer I/O mode and
+to setup some internal structures. Similarly, DMABUF buffers are
+allocated by applications through a device driver, and this ioctl only
+configures the driver into DMABUF I/O mode without performing any direct
+allocation.
+
+To allocate device buffers applications initialize all fields of the
+:ref:`struct v4l2_requestbuffers <v4l2-requestbuffers>` structure. They set the ``type``
+field to the respective stream or buffer type, the ``count`` field to
+the desired number of buffers, ``memory`` must be set to the requested
+I/O method and the ``reserved`` array must be zeroed. When the ioctl is
+called with a pointer to this structure the driver will attempt to
+allocate the requested number of buffers and it stores the actual number
+allocated in the ``count`` field. It can be smaller than the number
+requested, even zero, when the driver runs out of free memory. A larger
+number is also possible when the driver requires more buffers to
+function correctly. For example video output requires at least two
+buffers, one displayed and one filled by the application.
+
+When the I/O method is not supported the ioctl returns an ``EINVAL`` error
+code.
+
+Applications can call :ref:`VIDIOC_REQBUFS` again to change the number of
+buffers, however this cannot succeed when any buffers are still mapped.
+A ``count`` value of zero frees all buffers, after aborting or finishing
+any DMA in progress, an implicit
+:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`.
+
+
+.. _v4l2-requestbuffers:
+
+.. flat-table:: struct v4l2_requestbuffers
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``count``
+
+ - The number of buffers requested or granted.
+
+ - .. row 2
+
+ - __u32
+
+ - ``type``
+
+ - Type of the stream or buffers, this is the same as the struct
+ :ref:`v4l2_format <v4l2-format>` ``type`` field. See
+ :ref:`v4l2-buf-type` for valid values.
+
+ - .. row 3
+
+ - __u32
+
+ - ``memory``
+
+ - Applications set this field to ``V4L2_MEMORY_MMAP``,
+ ``V4L2_MEMORY_DMABUF`` or ``V4L2_MEMORY_USERPTR``. See
+ :ref:`v4l2-memory`.
+
+ - .. row 4
+
+ - __u32
+
+ - ``reserved``\ [2]
+
+ - A place holder for future extensions. Drivers and applications
+ must set the array to zero.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The buffer type (``type`` field) or the requested I/O method
+ (``memory``) is not supported.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_S_HW_FREQ_SEEK:
+
+***************************
+ioctl VIDIOC_S_HW_FREQ_SEEK
+***************************
+
+Name
+====
+
+VIDIOC_S_HW_FREQ_SEEK - Perform a hardware frequency seek
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_hw_freq_seek *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_S_HW_FREQ_SEEK
+
+``argp``
+
+
+Description
+===========
+
+Start a hardware frequency seek from the current frequency. To do this
+applications initialize the ``tuner``, ``type``, ``seek_upward``,
+``wrap_around``, ``spacing``, ``rangelow`` and ``rangehigh`` fields, and
+zero out the ``reserved`` array of a struct
+:ref:`v4l2_hw_freq_seek <v4l2-hw-freq-seek>` and call the
+``VIDIOC_S_HW_FREQ_SEEK`` ioctl with a pointer to this structure.
+
+The ``rangelow`` and ``rangehigh`` fields can be set to a non-zero value
+to tell the driver to search a specific band. If the struct
+:ref:`v4l2_tuner <v4l2-tuner>` ``capability`` field has the
+``V4L2_TUNER_CAP_HWSEEK_PROG_LIM`` flag set, these values must fall
+within one of the bands returned by
+:ref:`VIDIOC_ENUM_FREQ_BANDS`. If the
+``V4L2_TUNER_CAP_HWSEEK_PROG_LIM`` flag is not set, then these values
+must exactly match those of one of the bands returned by
+:ref:`VIDIOC_ENUM_FREQ_BANDS`. If the
+current frequency of the tuner does not fall within the selected band it
+will be clamped to fit in the band before the seek is started.
+
+If an error is returned, then the original frequency will be restored.
+
+This ioctl is supported if the ``V4L2_CAP_HW_FREQ_SEEK`` capability is
+set.
+
+If this ioctl is called from a non-blocking filehandle, then ``EAGAIN``
+error code is returned and no seek takes place.
+
+
+.. _v4l2-hw-freq-seek:
+
+.. flat-table:: struct v4l2_hw_freq_seek
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``tuner``
+
+ - The tuner index number. This is the same value as in the struct
+ :ref:`v4l2_input <v4l2-input>` ``tuner`` field and the struct
+ :ref:`v4l2_tuner <v4l2-tuner>` ``index`` field.
+
+ - .. row 2
+
+ - __u32
+
+ - ``type``
+
+ - The tuner type. This is the same value as in the struct
+ :ref:`v4l2_tuner <v4l2-tuner>` ``type`` field. See
+ :ref:`v4l2-tuner-type`
+
+ - .. row 3
+
+ - __u32
+
+ - ``seek_upward``
+
+ - If non-zero, seek upward from the current frequency, else seek
+ downward.
+
+ - .. row 4
+
+ - __u32
+
+ - ``wrap_around``
+
+ - If non-zero, wrap around when at the end of the frequency range,
+ else stop seeking. The struct :ref:`v4l2_tuner <v4l2-tuner>`
+ ``capability`` field will tell you what the hardware supports.
+
+ - .. row 5
+
+ - __u32
+
+ - ``spacing``
+
+ - If non-zero, defines the hardware seek resolution in Hz. The
+ driver selects the nearest value that is supported by the device.
+ If spacing is zero a reasonable default value is used.
+
+ - .. row 6
+
+ - __u32
+
+ - ``rangelow``
+
+ - If non-zero, the lowest tunable frequency of the band to search in
+ units of 62.5 kHz, or if the struct
+ :ref:`v4l2_tuner <v4l2-tuner>` ``capability`` field has the
+ ``V4L2_TUNER_CAP_LOW`` flag set, in units of 62.5 Hz or if the
+ struct :ref:`v4l2_tuner <v4l2-tuner>` ``capability`` field has
+ the ``V4L2_TUNER_CAP_1HZ`` flag set, in units of 1 Hz. If
+ ``rangelow`` is zero a reasonable default value is used.
+
+ - .. row 7
+
+ - __u32
+
+ - ``rangehigh``
+
+ - If non-zero, the highest tunable frequency of the band to search
+ in units of 62.5 kHz, or if the struct
+ :ref:`v4l2_tuner <v4l2-tuner>` ``capability`` field has the
+ ``V4L2_TUNER_CAP_LOW`` flag set, in units of 62.5 Hz or if the
+ struct :ref:`v4l2_tuner <v4l2-tuner>` ``capability`` field has
+ the ``V4L2_TUNER_CAP_1HZ`` flag set, in units of 1 Hz. If
+ ``rangehigh`` is zero a reasonable default value is used.
+
+ - .. row 8
+
+ - __u32
+
+ - ``reserved``\ [5]
+
+ - Reserved for future extensions. Applications must set the array to
+ zero.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The ``tuner`` index is out of bounds, the ``wrap_around`` value is
+ not supported or one of the values in the ``type``, ``rangelow`` or
+ ``rangehigh`` fields is wrong.
+
+EAGAIN
+ Attempted to call ``VIDIOC_S_HW_FREQ_SEEK`` with the filehandle in
+ non-blocking mode.
+
+ENODATA
+ The hardware seek found no channels.
+
+EBUSY
+ Another hardware seek is already in progress.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_STREAMON:
+
+***************************************
+ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF
+***************************************
+
+Name
+====
+
+VIDIOC_STREAMON - VIDIOC_STREAMOFF - Start or stop streaming I/O
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, const int *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_STREAMON, VIDIOC_STREAMOFF
+
+``argp``
+
+
+Description
+===========
+
+The ``VIDIOC_STREAMON`` and ``VIDIOC_STREAMOFF`` ioctl start and stop
+the capture or output process during streaming
+(:ref:`memory mapping <mmap>`, :ref:`user pointer <userp>` or
+:ref:`DMABUF <dmabuf>`) I/O.
+
+Capture hardware is disabled and no input buffers are filled (if there
+are any empty buffers in the incoming queue) until ``VIDIOC_STREAMON``
+has been called. Output hardware is disabled and no video signal is
+produced until ``VIDIOC_STREAMON`` has been called. The ioctl will
+succeed when at least one output buffer is in the incoming queue.
+
+Memory-to-memory devices will not start until ``VIDIOC_STREAMON`` has
+been called for both the capture and output stream types.
+
+If ``VIDIOC_STREAMON`` fails then any already queued buffers will remain
+queued.
+
+The ``VIDIOC_STREAMOFF`` ioctl, apart of aborting or finishing any DMA
+in progress, unlocks any user pointer buffers locked in physical memory,
+and it removes all buffers from the incoming and outgoing queues. That
+means all images captured but not dequeued yet will be lost, likewise
+all images enqueued for output but not transmitted yet. I/O returns to
+the same state as after calling
+:ref:`VIDIOC_REQBUFS` and can be restarted
+accordingly.
+
+If buffers have been queued with :ref:`VIDIOC_QBUF` and
+``VIDIOC_STREAMOFF`` is called without ever having called
+``VIDIOC_STREAMON``, then those queued buffers will also be removed from
+the incoming queue and all are returned to the same state as after
+calling :ref:`VIDIOC_REQBUFS` and can be restarted
+accordingly.
+
+Both ioctls take a pointer to an integer, the desired buffer or stream
+type. This is the same as struct
+:ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``type``.
+
+If ``VIDIOC_STREAMON`` is called when streaming is already in progress,
+or if ``VIDIOC_STREAMOFF`` is called when streaming is already stopped,
+then 0 is returned. Nothing happens in the case of ``VIDIOC_STREAMON``,
+but ``VIDIOC_STREAMOFF`` will return queued buffers to their starting
+state as mentioned above.
+
+Note that applications can be preempted for unknown periods right before
+or after the ``VIDIOC_STREAMON`` or ``VIDIOC_STREAMOFF`` calls, there is
+no notion of starting or stopping "now". Buffer timestamps can be used
+to synchronize with other events.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The buffer ``type`` is not supported, or no buffers have been
+ allocated (memory mapping) or enqueued (output) yet.
+
+EPIPE
+ The driver implements
+ :ref:`pad-level format configuration <pad-level-formats>` and the
+ pipeline configuration is invalid.
+
+ENOLINK
+ The driver implements Media Controller interface and the pipeline
+ link configuration is invalid.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL:
+
+***************************************
+ioctl VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL
+***************************************
+
+Name
+====
+
+VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL - Enumerate frame intervals
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_subdev_frame_interval_enum * argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL
+
+``argp``
+
+
+Description
+===========
+
+This ioctl lets applications enumerate available frame intervals on a
+given sub-device pad. Frame intervals only makes sense for sub-devices
+that can control the frame period on their own. This includes, for
+instance, image sensors and TV tuners.
+
+For the common use case of image sensors, the frame intervals available
+on the sub-device output pad depend on the frame format and size on the
+same pad. Applications must thus specify the desired format and size
+when enumerating frame intervals.
+
+To enumerate frame intervals applications initialize the ``index``,
+``pad``, ``which``, ``code``, ``width`` and ``height`` fields of struct
+:ref:`v4l2_subdev_frame_interval_enum <v4l2-subdev-frame-interval-enum>`
+and call the :ref:`VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL` ioctl with a pointer
+to this structure. Drivers fill the rest of the structure or return an
+EINVAL error code if one of the input fields is invalid. All frame
+intervals are enumerable by beginning at index zero and incrementing by
+one until ``EINVAL`` is returned.
+
+Available frame intervals may depend on the current 'try' formats at
+other pads of the sub-device, as well as on the current active links.
+See :ref:`VIDIOC_SUBDEV_G_FMT` for more
+information about the try formats.
+
+Sub-devices that support the frame interval enumeration ioctl should
+implemented it on a single pad only. Its behaviour when supported on
+multiple pads of the same sub-device is not defined.
+
+
+.. _v4l2-subdev-frame-interval-enum:
+
+.. flat-table:: struct v4l2_subdev_frame_interval_enum
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``index``
+
+ - Number of the format in the enumeration, set by the application.
+
+ - .. row 2
+
+ - __u32
+
+ - ``pad``
+
+ - Pad number as reported by the media controller API.
+
+ - .. row 3
+
+ - __u32
+
+ - ``code``
+
+ - The media bus format code, as defined in
+ :ref:`v4l2-mbus-format`.
+
+ - .. row 4
+
+ - __u32
+
+ - ``width``
+
+ - Frame width, in pixels.
+
+ - .. row 5
+
+ - __u32
+
+ - ``height``
+
+ - Frame height, in pixels.
+
+ - .. row 6
+
+ - struct :ref:`v4l2_fract <v4l2-fract>`
+
+ - ``interval``
+
+ - Period, in seconds, between consecutive video frames.
+
+ - .. row 7
+
+ - __u32
+
+ - ``which``
+
+ - Frame intervals to be enumerated, from enum
+ :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
+
+ - .. row 8
+
+ - __u32
+
+ - ``reserved``\ [8]
+
+ - Reserved for future extensions. Applications and drivers must set
+ the array to zero.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The struct
+ :ref:`v4l2_subdev_frame_interval_enum <v4l2-subdev-frame-interval-enum>`
+ ``pad`` references a non-existing pad, one of the ``code``,
+ ``width`` or ``height`` fields are invalid for the given pad or the
+ ``index`` field is out of bounds.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_SUBDEV_ENUM_FRAME_SIZE:
+
+***********************************
+ioctl VIDIOC_SUBDEV_ENUM_FRAME_SIZE
+***********************************
+
+Name
+====
+
+VIDIOC_SUBDEV_ENUM_FRAME_SIZE - Enumerate media bus frame sizes
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_subdev_frame_size_enum * argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_SUBDEV_ENUM_FRAME_SIZE
+
+``argp``
+
+
+Description
+===========
+
+This ioctl allows applications to enumerate all frame sizes supported by
+a sub-device on the given pad for the given media bus format. Supported
+formats can be retrieved with the
+:ref:`VIDIOC_SUBDEV_ENUM_MBUS_CODE`
+ioctl.
+
+To enumerate frame sizes applications initialize the ``pad``, ``which``
+, ``code`` and ``index`` fields of the struct
+:ref:`v4l2_subdev_mbus_code_enum <v4l2-subdev-mbus-code-enum>` and
+call the :ref:`VIDIOC_SUBDEV_ENUM_FRAME_SIZE` ioctl with a pointer to the
+structure. Drivers fill the minimum and maximum frame sizes or return an
+EINVAL error code if one of the input parameters is invalid.
+
+Sub-devices that only support discrete frame sizes (such as most
+sensors) will return one or more frame sizes with identical minimum and
+maximum values.
+
+Not all possible sizes in given [minimum, maximum] ranges need to be
+supported. For instance, a scaler that uses a fixed-point scaling ratio
+might not be able to produce every frame size between the minimum and
+maximum values. Applications must use the
+:ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` ioctl to try the
+sub-device for an exact supported frame size.
+
+Available frame sizes may depend on the current 'try' formats at other
+pads of the sub-device, as well as on the current active links and the
+current values of V4L2 controls. See
+:ref:`VIDIOC_SUBDEV_G_FMT` for more
+information about try formats.
+
+
+.. _v4l2-subdev-frame-size-enum:
+
+.. flat-table:: struct v4l2_subdev_frame_size_enum
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``index``
+
+ - Number of the format in the enumeration, set by the application.
+
+ - .. row 2
+
+ - __u32
+
+ - ``pad``
+
+ - Pad number as reported by the media controller API.
+
+ - .. row 3
+
+ - __u32
+
+ - ``code``
+
+ - The media bus format code, as defined in
+ :ref:`v4l2-mbus-format`.
+
+ - .. row 4
+
+ - __u32
+
+ - ``min_width``
+
+ - Minimum frame width, in pixels.
+
+ - .. row 5
+
+ - __u32
+
+ - ``max_width``
+
+ - Maximum frame width, in pixels.
+
+ - .. row 6
+
+ - __u32
+
+ - ``min_height``
+
+ - Minimum frame height, in pixels.
+
+ - .. row 7
+
+ - __u32
+
+ - ``max_height``
+
+ - Maximum frame height, in pixels.
+
+ - .. row 8
+
+ - __u32
+
+ - ``which``
+
+ - Frame sizes to be enumerated, from enum
+ :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
+
+ - .. row 9
+
+ - __u32
+
+ - ``reserved``\ [8]
+
+ - Reserved for future extensions. Applications and drivers must set
+ the array to zero.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The struct
+ :ref:`v4l2_subdev_frame_size_enum <v4l2-subdev-frame-size-enum>`
+ ``pad`` references a non-existing pad, the ``code`` is invalid for
+ the given pad or the ``index`` field is out of bounds.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_SUBDEV_ENUM_MBUS_CODE:
+
+**********************************
+ioctl VIDIOC_SUBDEV_ENUM_MBUS_CODE
+**********************************
+
+Name
+====
+
+VIDIOC_SUBDEV_ENUM_MBUS_CODE - Enumerate media bus formats
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_subdev_mbus_code_enum * argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_SUBDEV_ENUM_MBUS_CODE
+
+``argp``
+
+
+Description
+===========
+
+To enumerate media bus formats available at a given sub-device pad
+applications initialize the ``pad``, ``which`` and ``index`` fields of
+struct
+:ref:`v4l2_subdev_mbus_code_enum <v4l2-subdev-mbus-code-enum>` and
+call the :ref:`VIDIOC_SUBDEV_ENUM_MBUS_CODE` ioctl with a pointer to this
+structure. Drivers fill the rest of the structure or return an ``EINVAL``
+error code if either the ``pad`` or ``index`` are invalid. All media bus
+formats are enumerable by beginning at index zero and incrementing by
+one until ``EINVAL`` is returned.
+
+Available media bus formats may depend on the current 'try' formats at
+other pads of the sub-device, as well as on the current active links.
+See :ref:`VIDIOC_SUBDEV_G_FMT` for more
+information about the try formats.
+
+
+.. _v4l2-subdev-mbus-code-enum:
+
+.. flat-table:: struct v4l2_subdev_mbus_code_enum
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``pad``
+
+ - Pad number as reported by the media controller API.
+
+ - .. row 2
+
+ - __u32
+
+ - ``index``
+
+ - Number of the format in the enumeration, set by the application.
+
+ - .. row 3
+
+ - __u32
+
+ - ``code``
+
+ - The media bus format code, as defined in
+ :ref:`v4l2-mbus-format`.
+
+ - .. row 4
+
+ - __u32
+
+ - ``which``
+
+ - Media bus format codes to be enumerated, from enum
+ :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
+
+ - .. row 5
+
+ - __u32
+
+ - ``reserved``\ [8]
+
+ - Reserved for future extensions. Applications and drivers must set
+ the array to zero.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The struct
+ :ref:`v4l2_subdev_mbus_code_enum <v4l2-subdev-mbus-code-enum>`
+ ``pad`` references a non-existing pad, or the ``index`` field is out
+ of bounds.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_SUBDEV_G_CROP:
+
+************************************************
+ioctl VIDIOC_SUBDEV_G_CROP, VIDIOC_SUBDEV_S_CROP
+************************************************
+
+Name
+====
+
+VIDIOC_SUBDEV_G_CROP - VIDIOC_SUBDEV_S_CROP - Get or set the crop rectangle on a subdev pad
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_subdev_crop *argp )
+
+.. cpp:function:: int ioctl( int fd, int request, const struct v4l2_subdev_crop *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_SUBDEV_G_CROP, VIDIOC_SUBDEV_S_CROP
+
+``argp``
+
+
+Description
+===========
+
+ **Note**
+
+ This is an :ref:`obsolete` interface and may be removed
+ in the future. It is superseded by
+ :ref:`the selection API <VIDIOC_SUBDEV_G_SELECTION>`.
+
+To retrieve the current crop rectangle applications set the ``pad``
+field of a struct :ref:`v4l2_subdev_crop <v4l2-subdev-crop>` to the
+desired pad number as reported by the media API and the ``which`` field
+to ``V4L2_SUBDEV_FORMAT_ACTIVE``. They then call the
+``VIDIOC_SUBDEV_G_CROP`` ioctl with a pointer to this structure. The
+driver fills the members of the ``rect`` field or returns ``EINVAL`` error
+code if the input arguments are invalid, or if cropping is not supported
+on the given pad.
+
+To change the current crop rectangle applications set both the ``pad``
+and ``which`` fields and all members of the ``rect`` field. They then
+call the ``VIDIOC_SUBDEV_S_CROP`` ioctl with a pointer to this
+structure. The driver verifies the requested crop rectangle, adjusts it
+based on the hardware capabilities and configures the device. Upon
+return the struct :ref:`v4l2_subdev_crop <v4l2-subdev-crop>`
+contains the current format as would be returned by a
+``VIDIOC_SUBDEV_G_CROP`` call.
+
+Applications can query the device capabilities by setting the ``which``
+to ``V4L2_SUBDEV_FORMAT_TRY``. When set, 'try' crop rectangles are not
+applied to the device by the driver, but are mangled exactly as active
+crop rectangles and stored in the sub-device file handle. Two
+applications querying the same sub-device would thus not interact with
+each other.
+
+Drivers must not return an error solely because the requested crop
+rectangle doesn't match the device capabilities. They must instead
+modify the rectangle to match what the hardware can provide. The
+modified format should be as close as possible to the original request.
+
+
+.. _v4l2-subdev-crop:
+
+.. flat-table:: struct v4l2_subdev_crop
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``pad``
+
+ - Pad number as reported by the media framework.
+
+ - .. row 2
+
+ - __u32
+
+ - ``which``
+
+ - Crop rectangle to get or set, from enum
+ :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
+
+ - .. row 3
+
+ - struct :ref:`v4l2_rect <v4l2-rect>`
+
+ - ``rect``
+
+ - Crop rectangle boundaries, in pixels.
+
+ - .. row 4
+
+ - __u32
+
+ - ``reserved``\ [8]
+
+ - Reserved for future extensions. Applications and drivers must set
+ the array to zero.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EBUSY
+ The crop rectangle can't be changed because the pad is currently
+ busy. This can be caused, for instance, by an active video stream on
+ the pad. The ioctl must not be retried without performing another
+ action to fix the problem first. Only returned by
+ ``VIDIOC_SUBDEV_S_CROP``
+
+EINVAL
+ The struct :ref:`v4l2_subdev_crop <v4l2-subdev-crop>` ``pad``
+ references a non-existing pad, the ``which`` field references a
+ non-existing format, or cropping is not supported on the given
+ subdev pad.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_SUBDEV_G_FMT:
+
+**********************************************
+ioctl VIDIOC_SUBDEV_G_FMT, VIDIOC_SUBDEV_S_FMT
+**********************************************
+
+Name
+====
+
+VIDIOC_SUBDEV_G_FMT - VIDIOC_SUBDEV_S_FMT - Get or set the data format on a subdev pad
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_subdev_format *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_SUBDEV_G_FMT, VIDIOC_SUBDEV_S_FMT
+
+``argp``
+
+
+Description
+===========
+
+These ioctls are used to negotiate the frame format at specific subdev
+pads in the image pipeline.
+
+To retrieve the current format applications set the ``pad`` field of a
+struct :ref:`v4l2_subdev_format <v4l2-subdev-format>` to the desired
+pad number as reported by the media API and the ``which`` field to
+``V4L2_SUBDEV_FORMAT_ACTIVE``. When they call the
+``VIDIOC_SUBDEV_G_FMT`` ioctl with a pointer to this structure the
+driver fills the members of the ``format`` field.
+
+To change the current format applications set both the ``pad`` and
+``which`` fields and all members of the ``format`` field. When they call
+the ``VIDIOC_SUBDEV_S_FMT`` ioctl with a pointer to this structure the
+driver verifies the requested format, adjusts it based on the hardware
+capabilities and configures the device. Upon return the struct
+:ref:`v4l2_subdev_format <v4l2-subdev-format>` contains the current
+format as would be returned by a ``VIDIOC_SUBDEV_G_FMT`` call.
+
+Applications can query the device capabilities by setting the ``which``
+to ``V4L2_SUBDEV_FORMAT_TRY``. When set, 'try' formats are not applied
+to the device by the driver, but are changed exactly as active formats
+and stored in the sub-device file handle. Two applications querying the
+same sub-device would thus not interact with each other.
+
+For instance, to try a format at the output pad of a sub-device,
+applications would first set the try format at the sub-device input with
+the ``VIDIOC_SUBDEV_S_FMT`` ioctl. They would then either retrieve the
+default format at the output pad with the ``VIDIOC_SUBDEV_G_FMT`` ioctl,
+or set the desired output pad format with the ``VIDIOC_SUBDEV_S_FMT``
+ioctl and check the returned value.
+
+Try formats do not depend on active formats, but can depend on the
+current links configuration or sub-device controls value. For instance,
+a low-pass noise filter might crop pixels at the frame boundaries,
+modifying its output frame size.
+
+Drivers must not return an error solely because the requested format
+doesn't match the device capabilities. They must instead modify the
+format to match what the hardware can provide. The modified format
+should be as close as possible to the original request.
+
+
+.. _v4l2-subdev-format:
+
+.. flat-table:: struct v4l2_subdev_format
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``pad``
+
+ - Pad number as reported by the media controller API.
+
+ - .. row 2
+
+ - __u32
+
+ - ``which``
+
+ - Format to modified, from enum
+ :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
+
+ - .. row 3
+
+ - struct :ref:`v4l2_mbus_framefmt <v4l2-mbus-framefmt>`
+
+ - ``format``
+
+ - Definition of an image format, see :ref:`v4l2-mbus-framefmt` for
+ details.
+
+ - .. row 4
+
+ - __u32
+
+ - ``reserved``\ [8]
+
+ - Reserved for future extensions. Applications and drivers must set
+ the array to zero.
+
+
+
+.. _v4l2-subdev-format-whence:
+
+.. flat-table:: enum v4l2_subdev_format_whence
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - V4L2_SUBDEV_FORMAT_TRY
+
+ - 0
+
+ - Try formats, used for querying device capabilities.
+
+ - .. row 2
+
+ - V4L2_SUBDEV_FORMAT_ACTIVE
+
+ - 1
+
+ - Active formats, applied to the hardware.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EBUSY
+ The format can't be changed because the pad is currently busy. This
+ can be caused, for instance, by an active video stream on the pad.
+ The ioctl must not be retried without performing another action to
+ fix the problem first. Only returned by ``VIDIOC_SUBDEV_S_FMT``
+
+EINVAL
+ The struct :ref:`v4l2_subdev_format <v4l2-subdev-format>`
+ ``pad`` references a non-existing pad, or the ``which`` field
+ references a non-existing format.
+
+
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_SUBDEV_G_FRAME_INTERVAL:
+
+********************************************************************
+ioctl VIDIOC_SUBDEV_G_FRAME_INTERVAL, VIDIOC_SUBDEV_S_FRAME_INTERVAL
+********************************************************************
+
+Name
+====
+
+VIDIOC_SUBDEV_G_FRAME_INTERVAL - VIDIOC_SUBDEV_S_FRAME_INTERVAL - Get or set the frame interval on a subdev pad
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_subdev_frame_interval *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_SUBDEV_G_FRAME_INTERVAL,
+ VIDIOC_SUBDEV_S_FRAME_INTERVAL
+
+``argp``
+
+
+Description
+===========
+
+These ioctls are used to get and set the frame interval at specific
+subdev pads in the image pipeline. The frame interval only makes sense
+for sub-devices that can control the frame period on their own. This
+includes, for instance, image sensors and TV tuners. Sub-devices that
+don't support frame intervals must not implement these ioctls.
+
+To retrieve the current frame interval applications set the ``pad``
+field of a struct
+:ref:`v4l2_subdev_frame_interval <v4l2-subdev-frame-interval>` to
+the desired pad number as reported by the media controller API. When
+they call the ``VIDIOC_SUBDEV_G_FRAME_INTERVAL`` ioctl with a pointer to
+this structure the driver fills the members of the ``interval`` field.
+
+To change the current frame interval applications set both the ``pad``
+field and all members of the ``interval`` field. When they call the
+``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` ioctl with a pointer to this
+structure the driver verifies the requested interval, adjusts it based
+on the hardware capabilities and configures the device. Upon return the
+struct
+:ref:`v4l2_subdev_frame_interval <v4l2-subdev-frame-interval>`
+contains the current frame interval as would be returned by a
+``VIDIOC_SUBDEV_G_FRAME_INTERVAL`` call.
+
+Drivers must not return an error solely because the requested interval
+doesn't match the device capabilities. They must instead modify the
+interval to match what the hardware can provide. The modified interval
+should be as close as possible to the original request.
+
+Sub-devices that support the frame interval ioctls should implement them
+on a single pad only. Their behaviour when supported on multiple pads of
+the same sub-device is not defined.
+
+
+.. _v4l2-subdev-frame-interval:
+
+.. flat-table:: struct v4l2_subdev_frame_interval
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``pad``
+
+ - Pad number as reported by the media controller API.
+
+ - .. row 2
+
+ - struct :ref:`v4l2_fract <v4l2-fract>`
+
+ - ``interval``
+
+ - Period, in seconds, between consecutive video frames.
+
+ - .. row 3
+
+ - __u32
+
+ - ``reserved``\ [9]
+
+ - Reserved for future extensions. Applications and drivers must set
+ the array to zero.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EBUSY
+ The frame interval can't be changed because the pad is currently
+ busy. This can be caused, for instance, by an active video stream on
+ the pad. The ioctl must not be retried without performing another
+ action to fix the problem first. Only returned by
+ ``VIDIOC_SUBDEV_S_FRAME_INTERVAL``
+
+EINVAL
+ The struct
+ :ref:`v4l2_subdev_frame_interval <v4l2-subdev-frame-interval>`
+ ``pad`` references a non-existing pad, or the pad doesn't support
+ frame intervals.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_SUBDEV_G_SELECTION:
+
+**********************************************************
+ioctl VIDIOC_SUBDEV_G_SELECTION, VIDIOC_SUBDEV_S_SELECTION
+**********************************************************
+
+Name
+====
+
+VIDIOC_SUBDEV_G_SELECTION - VIDIOC_SUBDEV_S_SELECTION - Get or set selection rectangles on a subdev pad
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_subdev_selection *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_SUBDEV_G_SELECTION, VIDIOC_SUBDEV_S_SELECTION
+
+``argp``
+
+
+Description
+===========
+
+The selections are used to configure various image processing
+functionality performed by the subdevs which affect the image size. This
+currently includes cropping, scaling and composition.
+
+The selection API replaces
+:ref:`the old subdev crop API <VIDIOC_SUBDEV_G_CROP>`. All the
+function of the crop API, and more, are supported by the selections API.
+
+See :ref:`subdev` for more information on how each selection target
+affects the image processing pipeline inside the subdevice.
+
+
+Types of selection targets
+--------------------------
+
+There are two types of selection targets: actual and bounds. The actual
+targets are the targets which configure the hardware. The BOUNDS target
+will return a rectangle that contain all possible actual rectangles.
+
+
+Discovering supported features
+------------------------------
+
+To discover which targets are supported, the user can perform
+``VIDIOC_SUBDEV_G_SELECTION`` on them. Any unsupported target will
+return ``EINVAL``.
+
+Selection targets and flags are documented in
+:ref:`v4l2-selections-common`.
+
+
+.. _v4l2-subdev-selection:
+
+.. flat-table:: struct v4l2_subdev_selection
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``which``
+
+ - Active or try selection, from enum
+ :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
+
+ - .. row 2
+
+ - __u32
+
+ - ``pad``
+
+ - Pad number as reported by the media framework.
+
+ - .. row 3
+
+ - __u32
+
+ - ``target``
+
+ - Target selection rectangle. See :ref:`v4l2-selections-common`.
+
+ - .. row 4
+
+ - __u32
+
+ - ``flags``
+
+ - Flags. See :ref:`v4l2-selection-flags`.
+
+ - .. row 5
+
+ - struct :ref:`v4l2_rect <v4l2-rect>`
+
+ - ``r``
+
+ - Selection rectangle, in pixels.
+
+ - .. row 6
+
+ - __u32
+
+ - ``reserved``\ [8]
+
+ - Reserved for future extensions. Applications and drivers must set
+ the array to zero.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EBUSY
+ The selection rectangle can't be changed because the pad is
+ currently busy. This can be caused, for instance, by an active video
+ stream on the pad. The ioctl must not be retried without performing
+ another action to fix the problem first. Only returned by
+ ``VIDIOC_SUBDEV_S_SELECTION``
+
+EINVAL
+ The struct :ref:`v4l2_subdev_selection <v4l2-subdev-selection>`
+ ``pad`` references a non-existing pad, the ``which`` field
+ references a non-existing format, or the selection target is not
+ supported on the given subdev pad.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_SUBSCRIBE_EVENT:
+
+******************************************************
+ioctl VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT
+******************************************************
+
+Name
+====
+
+VIDIOC_SUBSCRIBE_EVENT - VIDIOC_UNSUBSCRIBE_EVENT - Subscribe or unsubscribe event
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_event_subscription *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT
+
+``argp``
+
+
+Description
+===========
+
+Subscribe or unsubscribe V4L2 event. Subscribed events are dequeued by
+using the :ref:`VIDIOC_DQEVENT` ioctl.
+
+
+.. _v4l2-event-subscription:
+
+.. flat-table:: struct v4l2_event_subscription
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``type``
+
+ - Type of the event, see :ref:`event-type`. Note that
+ ``V4L2_EVENT_ALL`` can be used with VIDIOC_UNSUBSCRIBE_EVENT for
+ unsubscribing all events at once.
+
+ - .. row 2
+
+ - __u32
+
+ - ``id``
+
+ - ID of the event source. If there is no ID associated with the
+ event source, then set this to 0. Whether or not an event needs an
+ ID depends on the event type.
+
+ - .. row 3
+
+ - __u32
+
+ - ``flags``
+
+ - Event flags, see :ref:`event-flags`.
+
+ - .. row 4
+
+ - __u32
+
+ - ``reserved``\ [5]
+
+ - Reserved for future extensions. Drivers and applications must set
+ the array to zero.
+
+
+
+.. _event-flags:
+
+.. flat-table:: Event Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_EVENT_SUB_FL_SEND_INITIAL``
+
+ - 0x0001
+
+ - When this event is subscribed an initial event will be sent
+ containing the current status. This only makes sense for events
+ that are triggered by a status change such as ``V4L2_EVENT_CTRL``.
+ Other events will ignore this flag.
+
+ - .. row 2
+
+ - ``V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK``
+
+ - 0x0002
+
+ - If set, then events directly caused by an ioctl will also be sent
+ to the filehandle that called that ioctl. For example, changing a
+ control using :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` will cause
+ a V4L2_EVENT_CTRL to be sent back to that same filehandle.
+ Normally such events are suppressed to prevent feedback loops
+ where an application changes a control to a one value and then
+ another, and then receives an event telling it that that control
+ has changed to the first value.
+
+ Since it can't tell whether that event was caused by another
+ application or by the :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>`
+ call it is hard to decide whether to set the control to the value
+ in the event, or ignore it.
+
+ Think carefully when you set this flag so you won't get into
+ situations like that.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
--- /dev/null
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _yuv-formats:
+
+***********
+YUV Formats
+***********
+
+YUV is the format native to TV broadcast and composite video signals. It
+separates the brightness information (Y) from the color information (U
+and V or Cb and Cr). The color information consists of red and blue
+*color difference* signals, this way the green component can be
+reconstructed by subtracting from the brightness component. See
+:ref:`colorspaces` for conversion examples. YUV was chosen because
+early television would only transmit brightness information. To add
+color in a way compatible with existing receivers a new signal carrier
+was added to transmit the color difference signals. Secondary in the YUV
+format the U and V components usually have lower resolution than the Y
+component. This is an analog video compression technique taking
+advantage of a property of the human visual system, being more sensitive
+to brightness information.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ pixfmt-packed-yuv
+ pixfmt-grey
+ pixfmt-y10
+ pixfmt-y12
+ pixfmt-y10b
+ pixfmt-y16
+ pixfmt-y16-be
+ pixfmt-y8i
+ pixfmt-y12i
+ pixfmt-uv8
+ pixfmt-yuyv
+ pixfmt-uyvy
+ pixfmt-yvyu
+ pixfmt-vyuy
+ pixfmt-y41p
+ pixfmt-yuv420
+ pixfmt-yuv420m
+ pixfmt-yuv422m
+ pixfmt-yuv444m
+ pixfmt-yuv410
+ pixfmt-yuv422p
+ pixfmt-yuv411p
+ pixfmt-nv12
+ pixfmt-nv12m
+ pixfmt-nv12mt
+ pixfmt-nv16
+ pixfmt-nv16m
+ pixfmt-nv24
+ pixfmt-m420
--- /dev/null
+# Ignore header name
+ignore define _UAPI_DVBVIDEO_H_
+
+# This is a deprecated obscure API. Just ignore things we don't know
+ignore define VIDEO_CMD_PLAY
+ignore define VIDEO_CMD_STOP
+ignore define VIDEO_CMD_FREEZE
+ignore define VIDEO_CMD_CONTINUE
+ignore define VIDEO_CMD_FREEZE_TO_BLACK
+ignore define VIDEO_CMD_STOP_TO_BLACK
+ignore define VIDEO_CMD_STOP_IMMEDIATELY
+ignore define VIDEO_PLAY_FMT_NONE
+ignore define VIDEO_PLAY_FMT_GOP
+ignore define VIDEO_VSYNC_FIELD_UNKNOWN
+ignore define VIDEO_VSYNC_FIELD_ODD
+ignore define VIDEO_VSYNC_FIELD_EVEN
+ignore define VIDEO_VSYNC_FIELD_PROGRESSIVE
+ignore define VIDEO_EVENT_SIZE_CHANGED
+ignore define VIDEO_EVENT_FRAME_RATE_CHANGED
+ignore define VIDEO_EVENT_DECODER_STOPPED
+ignore define VIDEO_EVENT_VSYNC
+ignore define VIDEO_CAP_MPEG1
+ignore define VIDEO_CAP_MPEG2
+ignore define VIDEO_CAP_SYS
+ignore define VIDEO_CAP_PROG
+ignore define VIDEO_CAP_SPU
+ignore define VIDEO_CAP_NAVI
+ignore define VIDEO_CAP_CSS
+
+# some typedefs should point to struct/enums
+replace typedef video_format_t video-format
+replace typedef video_system_t video-system
+replace typedef video_displayformat_t video-displayformat
+replace typedef video_size_t video-size
+replace typedef video_stream_source_t video-stream-source
+replace typedef video_play_state_t video-play-state
+replace typedef video_highlight_t video-highlight
+replace typedef video_spu_t video-spu
+replace typedef video_spu_palette_t video-spu-palette
+replace typedef video_navi_pack_t video-navi-pack
--- /dev/null
+# Ignore header name
+ignore define _UAPI__LINUX_VIDEODEV2_H
+
+#
+# The cross reference valitator for videodev2.h DocBook never cared
+# about enum symbols or defines. Yet, they're all (or almost all?)
+# handled inside V4L API sections. So, for now, it is safe to just
+# ignore. This should be revisited, as validating it helps to avoid
+# having something not documented at the uAPI.
+#
+
+# Those symbols should not be used by uAPI - don't document them
+ignore symbol V4L2_BUF_TYPE_PRIVATE
+ignore symbol V4L2_TUNER_DIGITAL_TV
+ignore symbol V4L2_COLORSPACE_BT878
+
+# Documented enum v4l2_field
+replace symbol V4L2_FIELD_ALTERNATE v4l2-field
+replace symbol V4L2_FIELD_ANY v4l2-field
+replace symbol V4L2_FIELD_BOTTOM v4l2-field
+replace symbol V4L2_FIELD_INTERLACED v4l2-field
+replace symbol V4L2_FIELD_INTERLACED_BT v4l2-field
+replace symbol V4L2_FIELD_INTERLACED_TB v4l2-field
+replace symbol V4L2_FIELD_NONE v4l2-field
+replace symbol V4L2_FIELD_SEQ_BT v4l2-field
+replace symbol V4L2_FIELD_SEQ_TB v4l2-field
+replace symbol V4L2_FIELD_TOP v4l2-field
+
+# Documented enum v4l2_buf_type
+replace symbol V4L2_BUF_TYPE_SDR_CAPTURE v4l2-buf-type
+replace symbol V4L2_BUF_TYPE_SDR_OUTPUT v4l2-buf-type
+replace symbol V4L2_BUF_TYPE_SLICED_VBI_CAPTURE v4l2-buf-type
+replace symbol V4L2_BUF_TYPE_SLICED_VBI_OUTPUT v4l2-buf-type
+replace symbol V4L2_BUF_TYPE_VBI_CAPTURE v4l2-buf-type
+replace symbol V4L2_BUF_TYPE_VBI_OUTPUT v4l2-buf-type
+replace symbol V4L2_BUF_TYPE_VIDEO_CAPTURE v4l2-buf-type
+replace symbol V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE v4l2-buf-type
+replace symbol V4L2_BUF_TYPE_VIDEO_OUTPUT v4l2-buf-type
+replace symbol V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE v4l2-buf-type
+replace symbol V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY v4l2-buf-type
+replace symbol V4L2_BUF_TYPE_VIDEO_OVERLAY v4l2-buf-type
+
+# Documented enum v4l2_tuner_type
+replace symbol V4L2_TUNER_ANALOG_TV v4l2-tuner-type
+replace symbol V4L2_TUNER_RADIO v4l2-tuner-type
+replace symbol V4L2_TUNER_RF v4l2-tuner-type
+replace symbol V4L2_TUNER_SDR v4l2-tuner-type
+
+# Documented enum v4l2_memory
+replace symbol V4L2_MEMORY_DMABUF v4l2-memory
+replace symbol V4L2_MEMORY_MMAP v4l2-memory
+replace symbol V4L2_MEMORY_OVERLAY v4l2-memory
+replace symbol V4L2_MEMORY_USERPTR v4l2-memory
+
+# Documented enum v4l2_colorspace
+replace symbol V4L2_COLORSPACE_470_SYSTEM_BG v4l2-colorspace
+replace symbol V4L2_COLORSPACE_470_SYSTEM_M v4l2-colorspace
+replace symbol V4L2_COLORSPACE_ADOBERGB v4l2-colorspace
+replace symbol V4L2_COLORSPACE_BT2020 v4l2-colorspace
+replace symbol V4L2_COLORSPACE_DCI_P3 v4l2-colorspace
+replace symbol V4L2_COLORSPACE_DEFAULT v4l2-colorspace
+replace symbol V4L2_COLORSPACE_JPEG v4l2-colorspace
+replace symbol V4L2_COLORSPACE_RAW v4l2-colorspace
+replace symbol V4L2_COLORSPACE_REC709 v4l2-colorspace
+replace symbol V4L2_COLORSPACE_SMPTE170M v4l2-colorspace
+replace symbol V4L2_COLORSPACE_SMPTE240M v4l2-colorspace
+replace symbol V4L2_COLORSPACE_SRGB v4l2-colorspace
+
+# Documented enum v4l2_xfer_func
+replace symbol V4L2_XFER_FUNC_709 v4l2-xfer-func
+replace symbol V4L2_XFER_FUNC_ADOBERGB v4l2-xfer-func
+replace symbol V4L2_XFER_FUNC_DCI_P3 v4l2-xfer-func
+replace symbol V4L2_XFER_FUNC_DEFAULT v4l2-xfer-func
+replace symbol V4L2_XFER_FUNC_NONE v4l2-xfer-func
+replace symbol V4L2_XFER_FUNC_SMPTE2084 v4l2-xfer-func
+replace symbol V4L2_XFER_FUNC_SMPTE240M v4l2-xfer-func
+replace symbol V4L2_XFER_FUNC_SRGB v4l2-xfer-func
+
+# Documented enum v4l2_ycbcr_encoding
+replace symbol V4L2_YCBCR_ENC_601 v4l2-ycbcr-encoding
+replace symbol V4L2_YCBCR_ENC_709 v4l2-ycbcr-encoding
+replace symbol V4L2_YCBCR_ENC_BT2020 v4l2-ycbcr-encoding
+replace symbol V4L2_YCBCR_ENC_BT2020_CONST_LUM v4l2-ycbcr-encoding
+replace symbol V4L2_YCBCR_ENC_DEFAULT v4l2-ycbcr-encoding
+replace symbol V4L2_YCBCR_ENC_SYCC v4l2-ycbcr-encoding
+replace symbol V4L2_YCBCR_ENC_XV601 v4l2-ycbcr-encoding
+replace symbol V4L2_YCBCR_ENC_XV709 v4l2-ycbcr-encoding
+
+# Is this deprecated, or just a missing reference?
+replace symbol V4L2_YCBCR_ENC_SMPTE240M v4l2-ycbcr-encoding-FIXME
+
+# Documented enum v4l2_quantization
+replace symbol V4L2_QUANTIZATION_DEFAULT v4l2-quantization
+replace symbol V4L2_QUANTIZATION_FULL_RANGE v4l2-quantization
+replace symbol V4L2_QUANTIZATION_LIM_RANGE v4l2-quantization
+
+# Documented enum v4l2_priority
+replace symbol V4L2_PRIORITY_BACKGROUND v4l2-priority
+replace symbol V4L2_PRIORITY_DEFAULT v4l2-priority
+replace symbol V4L2_PRIORITY_INTERACTIVE v4l2-priority
+replace symbol V4L2_PRIORITY_RECORD v4l2-priority
+replace symbol V4L2_PRIORITY_UNSET v4l2-priority
+
+# Documented enum v4l2_frmsizetypes
+replace symbol V4L2_FRMSIZE_TYPE_CONTINUOUS v4l2-frmsizetypes
+replace symbol V4L2_FRMSIZE_TYPE_DISCRETE v4l2-frmsizetypes
+replace symbol V4L2_FRMSIZE_TYPE_STEPWISE v4l2-frmsizetypes
+
+# Documented enum frmivaltypes
+replace symbol V4L2_FRMIVAL_TYPE_CONTINUOUS v4l2-frmivaltypes
+replace symbol V4L2_FRMIVAL_TYPE_DISCRETE v4l2-frmivaltypes
+replace symbol V4L2_FRMIVAL_TYPE_STEPWISE v4l2-frmivaltypes
+
+# Documented enum v4l2-ctrl-type
+replace symbol V4L2_CTRL_COMPOUND_TYPES vidioc_queryctrl
+
+replace symbol V4L2_CTRL_TYPE_BITMASK v4l2-ctrl-type
+replace symbol V4L2_CTRL_TYPE_BOOLEAN v4l2-ctrl-type
+replace symbol V4L2_CTRL_TYPE_BUTTON v4l2-ctrl-type
+replace symbol V4L2_CTRL_TYPE_CTRL_CLASS v4l2-ctrl-type
+replace symbol V4L2_CTRL_TYPE_INTEGER v4l2-ctrl-type
+replace symbol V4L2_CTRL_TYPE_INTEGER64 v4l2-ctrl-type
+replace symbol V4L2_CTRL_TYPE_INTEGER_MENU v4l2-ctrl-type
+replace symbol V4L2_CTRL_TYPE_MENU v4l2-ctrl-type
+replace symbol V4L2_CTRL_TYPE_STRING v4l2-ctrl-type
+replace symbol V4L2_CTRL_TYPE_U16 v4l2-ctrl-type
+replace symbol V4L2_CTRL_TYPE_U32 v4l2-ctrl-type
+replace symbol V4L2_CTRL_TYPE_U8 v4l2-ctrl-type
+
+# V4L2 capability defines
+replace define V4L2_CAP_VIDEO_CAPTURE device-capabilities
+replace define V4L2_CAP_VIDEO_CAPTURE_MPLANE device-capabilities
+replace define V4L2_CAP_VIDEO_OUTPUT device-capabilities
+replace define V4L2_CAP_VIDEO_OUTPUT_MPLANE device-capabilities
+replace define V4L2_CAP_VIDEO_M2M device-capabilities
+replace define V4L2_CAP_VIDEO_M2M_MPLANE device-capabilities
+replace define V4L2_CAP_VIDEO_OVERLAY device-capabilities
+replace define V4L2_CAP_VBI_CAPTURE device-capabilities
+replace define V4L2_CAP_VBI_OUTPUT device-capabilities
+replace define V4L2_CAP_SLICED_VBI_CAPTURE device-capabilities
+replace define V4L2_CAP_SLICED_VBI_OUTPUT device-capabilities
+replace define V4L2_CAP_RDS_CAPTURE device-capabilities
+replace define V4L2_CAP_VIDEO_OUTPUT_OVERLAY device-capabilities
+replace define V4L2_CAP_HW_FREQ_SEEK device-capabilities
+replace define V4L2_CAP_RDS_OUTPUT device-capabilities
+replace define V4L2_CAP_TUNER device-capabilities
+replace define V4L2_CAP_AUDIO device-capabilities
+replace define V4L2_CAP_RADIO device-capabilities
+replace define V4L2_CAP_MODULATOR device-capabilities
+replace define V4L2_CAP_SDR_CAPTURE device-capabilities
+replace define V4L2_CAP_EXT_PIX_FORMAT device-capabilities
+replace define V4L2_CAP_SDR_OUTPUT device-capabilities
+replace define V4L2_CAP_READWRITE device-capabilities
+replace define V4L2_CAP_ASYNCIO device-capabilities
+replace define V4L2_CAP_STREAMING device-capabilities
+replace define V4L2_CAP_DEVICE_CAPS device-capabilities
+
+# V4L2 pix flags
+replace define V4L2_PIX_FMT_PRIV_MAGIC v4l2-pix-format
+replace define V4L2_PIX_FMT_FLAG_PREMUL_ALPHA reserved-formats
+
+# V4L2 format flags
+replace define V4L2_FMT_FLAG_COMPRESSED fmtdesc-flags
+replace define V4L2_FMT_FLAG_EMULATED fmtdesc-flags
+
+# V4L2 tymecode types
+replace define V4L2_TC_TYPE_24FPS timecode-type
+replace define V4L2_TC_TYPE_25FPS timecode-type
+replace define V4L2_TC_TYPE_30FPS timecode-type
+replace define V4L2_TC_TYPE_50FPS timecode-type
+replace define V4L2_TC_TYPE_60FPS timecode-type
+
+# V4L2 tymecode flags
+replace define V4L2_TC_FLAG_DROPFRAME timecode-flags
+replace define V4L2_TC_FLAG_COLORFRAME timecode-flags
+replace define V4L2_TC_USERBITS_field timecode-flags
+replace define V4L2_TC_USERBITS_USERDEFINED timecode-flags
+replace define V4L2_TC_USERBITS_8BITCHARS timecode-flags
+
+# V4L2 JPEG markers
+replace define V4L2_JPEG_MARKER_DHT jpeg-markers
+replace define V4L2_JPEG_MARKER_DQT jpeg-markers
+replace define V4L2_JPEG_MARKER_DRI jpeg-markers
+replace define V4L2_JPEG_MARKER_COM jpeg-markers
+replace define V4L2_JPEG_MARKER_APP jpeg-markers
+
+#V4L2 buffer flags
+replace define V4L2_BUF_FLAG_MAPPED buffer-flags
+replace define V4L2_BUF_FLAG_QUEUED buffer-flags
+replace define V4L2_BUF_FLAG_DONE buffer-flags
+replace define V4L2_BUF_FLAG_ERROR buffer-flags
+replace define V4L2_BUF_FLAG_KEYFRAME buffer-flags
+replace define V4L2_BUF_FLAG_PFRAME buffer-flags
+replace define V4L2_BUF_FLAG_BFRAME buffer-flags
+replace define V4L2_BUF_FLAG_TIMECODE buffer-flags
+replace define V4L2_BUF_FLAG_PREPARED buffer-flags
+replace define V4L2_BUF_FLAG_NO_CACHE_INVALIDATE buffer-flags
+replace define V4L2_BUF_FLAG_NO_CACHE_CLEAN buffer-flags
+replace define V4L2_BUF_FLAG_TIMESTAMP_MASK buffer-flags
+replace define V4L2_BUF_FLAG_TIMESTAMP_UNKNOWN buffer-flags
+replace define V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC buffer-flags
+replace define V4L2_BUF_FLAG_TIMESTAMP_COPY buffer-flags
+replace define V4L2_BUF_FLAG_TSTAMP_SRC_MASK buffer-flags
+replace define V4L2_BUF_FLAG_TSTAMP_SRC_EOF buffer-flags
+replace define V4L2_BUF_FLAG_TSTAMP_SRC_SOE buffer-flags
+replace define V4L2_BUF_FLAG_LAST buffer-flags-FIXME
+
+# V4L2 framebuffer caps and flags
+
+replace define V4L2_FBUF_CAP_EXTERNOVERLAY framebuffer-cap
+replace define V4L2_FBUF_CAP_CHROMAKEY framebuffer-cap
+replace define V4L2_FBUF_CAP_LIST_CLIPPING framebuffer-cap
+replace define V4L2_FBUF_CAP_BITMAP_CLIPPING framebuffer-cap
+replace define V4L2_FBUF_CAP_LOCAL_ALPHA framebuffer-cap
+replace define V4L2_FBUF_CAP_GLOBAL_ALPHA framebuffer-cap
+replace define V4L2_FBUF_CAP_LOCAL_INV_ALPHA framebuffer-cap
+replace define V4L2_FBUF_CAP_SRC_CHROMAKEY framebuffer-cap
+
+replace define V4L2_FBUF_FLAG_PRIMARY framebuffer-flags
+replace define V4L2_FBUF_FLAG_OVERLAY framebuffer-flags
+replace define V4L2_FBUF_FLAG_CHROMAKEY framebuffer-flags
+replace define V4L2_FBUF_FLAG_LOCAL_ALPHA framebuffer-flags
+replace define V4L2_FBUF_FLAG_GLOBAL_ALPHA framebuffer-flags
+replace define V4L2_FBUF_FLAG_LOCAL_INV_ALPHA framebuffer-flags
+replace define V4L2_FBUF_FLAG_SRC_CHROMAKEY framebuffer-flags
+
+# Used on VIDIOC_G_PARM
+
+replace define V4L2_MODE_HIGHQUALITY parm-flags
+replace define V4L2_CAP_TIMEPERFRAME v4l2-captureparm
+
+# The V4L2_STD_foo are all defined at v4l2_std_id table
+
+replace define V4L2_STD_PAL_B v4l2-std-id
+replace define V4L2_STD_PAL_B1 v4l2-std-id
+replace define V4L2_STD_PAL_G v4l2-std-id
+replace define V4L2_STD_PAL_H v4l2-std-id
+replace define V4L2_STD_PAL_I v4l2-std-id
+replace define V4L2_STD_PAL_D v4l2-std-id
+replace define V4L2_STD_PAL_D1 v4l2-std-id
+replace define V4L2_STD_PAL_K v4l2-std-id
+replace define V4L2_STD_PAL_M v4l2-std-id
+replace define V4L2_STD_PAL_N v4l2-std-id
+replace define V4L2_STD_PAL_Nc v4l2-std-id
+replace define V4L2_STD_PAL_60 v4l2-std-id
+replace define V4L2_STD_NTSC_M v4l2-std-id
+replace define V4L2_STD_NTSC_M_JP v4l2-std-id
+replace define V4L2_STD_NTSC_443 v4l2-std-id
+replace define V4L2_STD_NTSC_M_KR v4l2-std-id
+replace define V4L2_STD_SECAM_B v4l2-std-id
+replace define V4L2_STD_SECAM_D v4l2-std-id
+replace define V4L2_STD_SECAM_G v4l2-std-id
+replace define V4L2_STD_SECAM_H v4l2-std-id
+replace define V4L2_STD_SECAM_K v4l2-std-id
+replace define V4L2_STD_SECAM_K1 v4l2-std-id
+replace define V4L2_STD_SECAM_L v4l2-std-id
+replace define V4L2_STD_SECAM_LC v4l2-std-id
+replace define V4L2_STD_ATSC_8_VSB v4l2-std-id
+replace define V4L2_STD_ATSC_16_VSB v4l2-std-id
+replace define V4L2_STD_NTSC v4l2-std-id
+replace define V4L2_STD_SECAM_DK v4l2-std-id
+replace define V4L2_STD_SECAM v4l2-std-id
+replace define V4L2_STD_PAL_BG v4l2-std-id
+replace define V4L2_STD_PAL_DK v4l2-std-id
+replace define V4L2_STD_PAL v4l2-std-id
+replace define V4L2_STD_B v4l2-std-id
+replace define V4L2_STD_G v4l2-std-id
+replace define V4L2_STD_H v4l2-std-id
+replace define V4L2_STD_L v4l2-std-id
+replace define V4L2_STD_GH v4l2-std-id
+replace define V4L2_STD_DK v4l2-std-id
+replace define V4L2_STD_BG v4l2-std-id
+replace define V4L2_STD_MN v4l2-std-id
+replace define V4L2_STD_MTS v4l2-std-id
+replace define V4L2_STD_525_60 v4l2-std-id
+replace define V4L2_STD_625_50 v4l2-std-id
+replace define V4L2_STD_ATSC v4l2-std-id
+replace define V4L2_STD_UNKNOWN v4l2-std-id
+replace define V4L2_STD_ALL v4l2-std-id
+
+# V4L2 DT BT timings definitions
+
+replace define V4L2_DV_PROGRESSIVE v4l2-dv-fixme
+replace define V4L2_DV_INTERLACED v4l2-dv-fixme
+
+replace define V4L2_DV_VSYNC_POS_POL v4l2-bt-timings
+replace define V4L2_DV_HSYNC_POS_POL v4l2-bt-timings
+
+replace define V4L2_DV_BT_STD_CEA861 dv-bt-standards
+replace define V4L2_DV_BT_STD_DMT dv-bt-standards
+replace define V4L2_DV_BT_STD_CVT dv-bt-standards
+replace define V4L2_DV_BT_STD_GTF dv-bt-standards
+
+replace define V4L2_DV_FL_REDUCED_BLANKING dv-bt-standards
+replace define V4L2_DV_FL_CAN_REDUCE_FPS dv-bt-standards
+replace define V4L2_DV_FL_REDUCED_FPS dv-bt-standards
+replace define V4L2_DV_FL_HALF_LINE dv-bt-standards
+replace define V4L2_DV_FL_IS_CE_VIDEO dv-bt-standards
+
+replace define V4L2_DV_BT_656_1120 dv-timing-types
+
+replace define V4L2_DV_BT_CAP_INTERLACED framebuffer-cap
+replace define V4L2_DV_BT_CAP_PROGRESSIVE framebuffer-cap
+replace define V4L2_DV_BT_CAP_REDUCED_BLANKING framebuffer-cap
+replace define V4L2_DV_BT_CAP_CUSTOM framebuffer-cap
+
+# V4L2 input
+
+replace define V4L2_INPUT_TYPE_TUNER input-type
+replace define V4L2_INPUT_TYPE_CAMERA input-type
+
+replace define V4L2_IN_ST_NO_POWER input-status
+replace define V4L2_IN_ST_NO_SIGNAL input-status
+replace define V4L2_IN_ST_NO_COLOR input-status
+replace define V4L2_IN_ST_HFLIP input-status
+replace define V4L2_IN_ST_VFLIP input-status
+replace define V4L2_IN_ST_NO_H_LOCK input-status
+replace define V4L2_IN_ST_COLOR_KILL input-status
+replace define V4L2_IN_ST_NO_SYNC input-status
+replace define V4L2_IN_ST_NO_EQU input-status
+replace define V4L2_IN_ST_NO_CARRIER input-status
+replace define V4L2_IN_ST_MACROVISION input-status
+replace define V4L2_IN_ST_NO_ACCESS input-status
+replace define V4L2_IN_ST_VTR input-status
+
+replace define V4L2_IN_CAP_DV_TIMINGS input-capabilities
+replace define V4L2_IN_CAP_STD input-capabilities
+replace define V4L2_IN_CAP_NATIVE_SIZE input-capabilities
+
+# V4L2 output
+
+replace define V4L2_OUTPUT_TYPE_MODULATOR output-type
+replace define V4L2_OUTPUT_TYPE_ANALOG output-type
+replace define V4L2_OUTPUT_TYPE_ANALOGVGAOVERLAY output-type
+
+replace define V4L2_OUT_CAP_DV_TIMINGS output-capabilities
+replace define V4L2_OUT_CAP_STD output-capabilities
+replace define V4L2_OUT_CAP_NATIVE_SIZE output-capabilities
+
+# V4L2 control flags
+
+replace define V4L2_CTRL_FLAG_DISABLED control-flags
+replace define V4L2_CTRL_FLAG_GRABBED control-flags
+replace define V4L2_CTRL_FLAG_READ_ONLY control-flags
+replace define V4L2_CTRL_FLAG_UPDATE control-flags
+replace define V4L2_CTRL_FLAG_INACTIVE control-flags
+replace define V4L2_CTRL_FLAG_SLIDER control-flags
+replace define V4L2_CTRL_FLAG_WRITE_ONLY control-flags
+replace define V4L2_CTRL_FLAG_VOLATILE control-flags
+replace define V4L2_CTRL_FLAG_HAS_PAYLOAD control-flags
+replace define V4L2_CTRL_FLAG_EXECUTE_ON_WRITE control-flags
+
+replace define V4L2_CTRL_FLAG_NEXT_CTRL control
+replace define V4L2_CTRL_FLAG_NEXT_COMPOUND control
+replace define V4L2_CID_PRIVATE_BASE control
+
+# V4L2 tuner
+
+replace define V4L2_TUNER_CAP_LOW tuner-capability
+replace define V4L2_TUNER_CAP_NORM tuner-capability
+replace define V4L2_TUNER_CAP_HWSEEK_BOUNDED tuner-capability
+replace define V4L2_TUNER_CAP_HWSEEK_WRAP tuner-capability
+replace define V4L2_TUNER_CAP_STEREO tuner-capability
+replace define V4L2_TUNER_CAP_LANG2 tuner-capability
+replace define V4L2_TUNER_CAP_SAP tuner-capability
+replace define V4L2_TUNER_CAP_LANG1 tuner-capability
+replace define V4L2_TUNER_CAP_RDS tuner-capability
+replace define V4L2_TUNER_CAP_RDS_BLOCK_IO tuner-capability
+replace define V4L2_TUNER_CAP_RDS_CONTROLS tuner-capability
+replace define V4L2_TUNER_CAP_FREQ_BANDS tuner-capability
+replace define V4L2_TUNER_CAP_HWSEEK_PROG_LIM tuner-capability
+replace define V4L2_TUNER_CAP_1HZ tuner-capability
+
+replace define V4L2_TUNER_SUB_MONO tuner-rxsubchans
+replace define V4L2_TUNER_SUB_STEREO tuner-rxsubchans
+replace define V4L2_TUNER_SUB_LANG2 tuner-rxsubchans
+replace define V4L2_TUNER_SUB_SAP tuner-rxsubchans
+replace define V4L2_TUNER_SUB_LANG1 tuner-rxsubchans
+replace define V4L2_TUNER_SUB_RDS tuner-rxsubchans
+
+replace define V4L2_TUNER_MODE_MONO tuner-audmode
+replace define V4L2_TUNER_MODE_STEREO tuner-audmode
+replace define V4L2_TUNER_MODE_LANG2 tuner-audmode
+replace define V4L2_TUNER_MODE_SAP tuner-audmode
+replace define V4L2_TUNER_MODE_LANG1 tuner-audmode
+replace define V4L2_TUNER_MODE_LANG1_LANG2 tuner-audmode
+
+replace define V4L2_BAND_MODULATION_VSB band-modulation
+replace define V4L2_BAND_MODULATION_FM band-modulation
+replace define V4L2_BAND_MODULATION_AM band-modulation
+
+replace define V4L2_RDS_BLOCK_MSK v4l2-rds-block
+replace define V4L2_RDS_BLOCK_A v4l2-rds-block
+replace define V4L2_RDS_BLOCK_B v4l2-rds-block
+replace define V4L2_RDS_BLOCK_C v4l2-rds-block
+replace define V4L2_RDS_BLOCK_D v4l2-rds-block
+replace define V4L2_RDS_BLOCK_C_ALT v4l2-rds-block
+replace define V4L2_RDS_BLOCK_INVALID v4l2-rds-block
+replace define V4L2_RDS_BLOCK_CORRECTED v4l2-rds-block
+replace define V4L2_RDS_BLOCK_ERROR v4l2-rds-block
+
+# V4L2 audio
+
+replace define V4L2_AUDCAP_STEREO audio-capability
+replace define V4L2_AUDCAP_AVL audio-capability
+
+replace define V4L2_AUDMODE_AVL audio-mode
+
+# MPEG
+
+replace define V4L2_ENC_IDX_FRAME_I v4l2-enc-idx
+replace define V4L2_ENC_IDX_FRAME_P v4l2-enc-idx
+replace define V4L2_ENC_IDX_FRAME_B v4l2-enc-idx
+replace define V4L2_ENC_IDX_FRAME_MASK v4l2-enc-idx
+replace define V4L2_ENC_IDX_ENTRIES v4l2-enc-idx
+
+replace define V4L2_ENC_CMD_START encoder-cmds
+replace define V4L2_ENC_CMD_STOP encoder-cmds
+replace define V4L2_ENC_CMD_PAUSE encoder-cmds
+replace define V4L2_ENC_CMD_RESUME encoder-cmds
+
+replace define V4L2_ENC_CMD_STOP_AT_GOP_END encoder-flags
+
+replace define V4L2_DEC_CMD_START decoder-cmds
+replace define V4L2_DEC_CMD_STOP decoder-cmds
+replace define V4L2_DEC_CMD_PAUSE decoder-cmds
+replace define V4L2_DEC_CMD_RESUME decoder-cmds
+
+replace define V4L2_DEC_CMD_START_MUTE_AUDIO decoder-cmds
+replace define V4L2_DEC_CMD_PAUSE_TO_BLACK decoder-cmds
+replace define V4L2_DEC_CMD_STOP_TO_BLACK decoder-cmds
+replace define V4L2_DEC_CMD_STOP_IMMEDIATELY decoder-cmds
+
+replace define V4L2_DEC_START_FMT_NONE decoder-cmds
+replace define V4L2_DEC_START_FMT_GOP decoder-cmds
+
+# V4L2 VBI
+
+replace define V4L2_VBI_UNSYNC vbifmt-flags
+replace define V4L2_VBI_INTERLACED vbifmt-flags
+
+replace define V4L2_VBI_ITU_525_F1_START v4l2-vbi-format
+replace define V4L2_VBI_ITU_525_F2_START v4l2-vbi-format
+replace define V4L2_VBI_ITU_625_F1_START v4l2-vbi-format
+replace define V4L2_VBI_ITU_625_F2_START v4l2-vbi-format
+
+
+replace define V4L2_SLICED_TELETEXT_B vbi-services
+replace define V4L2_SLICED_VPS vbi-services
+replace define V4L2_SLICED_CAPTION_525 vbi-services
+replace define V4L2_SLICED_WSS_625 vbi-services
+replace define V4L2_SLICED_VBI_525 vbi-services
+replace define V4L2_SLICED_VBI_625 vbi-services
+
+replace define V4L2_MPEG_VBI_IVTV_TELETEXT_B ITV0-Line-Identifier-Constants
+replace define V4L2_MPEG_VBI_IVTV_CAPTION_525 ITV0-Line-Identifier-Constants
+replace define V4L2_MPEG_VBI_IVTV_WSS_625 ITV0-Line-Identifier-Constants
+replace define V4L2_MPEG_VBI_IVTV_VPS ITV0-Line-Identifier-Constants
+
+replace define V4L2_MPEG_VBI_IVTV_MAGIC0 v4l2-mpeg-vbi-fmt-ivtv-magic
+replace define V4L2_MPEG_VBI_IVTV_MAGIC1 v4l2-mpeg-vbi-fmt-ivtv-magic
+
+# V4L2 events
+
+replace define V4L2_EVENT_ALL event-type
+replace define V4L2_EVENT_VSYNC event-type
+replace define V4L2_EVENT_EOS event-type
+replace define V4L2_EVENT_CTRL event-type
+replace define V4L2_EVENT_FRAME_SYNC event-type
+replace define V4L2_EVENT_SOURCE_CHANGE event-type
+replace define V4L2_EVENT_MOTION_DET event-type
+replace define V4L2_EVENT_PRIVATE_START event-type
+
+replace define V4L2_EVENT_CTRL_CH_VALUE ctrl-changes-flags
+replace define V4L2_EVENT_CTRL_CH_FLAGS ctrl-changes-flags
+replace define V4L2_EVENT_CTRL_CH_RANGE ctrl-changes-flags
+
+replace define V4L2_EVENT_SRC_CH_RESOLUTION src-changes-flags
+
+replace define V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ v4l2-event-motion-det
+
+replace define V4L2_EVENT_SUB_FL_SEND_INITIAL event-flags
+replace define V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK event-flags
+
+# V4L2 debugging
+replace define V4L2_CHIP_MATCH_BRIDGE vidioc_dbg_g_register
+replace define V4L2_CHIP_MATCH_SUBDEV vidioc_dbg_g_register
+replace define V4L2_CHIP_MATCH_HOST vidioc_dbg_g_register
+replace define V4L2_CHIP_MATCH_I2C_DRIVER vidioc_dbg_g_register
+replace define V4L2_CHIP_MATCH_I2C_ADDR vidioc_dbg_g_register
+replace define V4L2_CHIP_MATCH_AC97 vidioc_dbg_g_register
+
+replace define V4L2_CHIP_FL_READABLE vidioc_dbg_g_register
+replace define V4L2_CHIP_FL_WRITABLE vidioc_dbg_g_register
+
+# Ignore reserved ioctl and ancillary macros
+
+ignore define VIDEO_MAX_FRAME
+ignore define VIDEO_MAX_PLANES
+ignore define v4l2_fourcc
+ignore define v4l2_fourcc_be
+ignore define V4L2_FIELD_HAS_TOP
+ignore define V4L2_FIELD_HAS_BOTTOM
+ignore define V4L2_FIELD_HAS_BOTH
+ignore define V4L2_FIELD_HAS_T_OR_B
+ignore define V4L2_TYPE_IS_MULTIPLANAR
+ignore define V4L2_TYPE_IS_OUTPUT
+ignore define V4L2_TUNER_ADC
+ignore define V4L2_MAP_COLORSPACE_DEFAULT
+ignore define V4L2_MAP_XFER_FUNC_DEFAULT
+ignore define V4L2_MAP_YCBCR_ENC_DEFAULT
+ignore define V4L2_DV_BT_BLANKING_WIDTH
+ignore define V4L2_DV_BT_FRAME_WIDTH
+ignore define V4L2_DV_BT_BLANKING_HEIGHT
+ignore define V4L2_DV_BT_FRAME_HEIGHT
+ignore define V4L2_IN_CAP_CUSTOM_TIMINGS
+ignore define V4L2_CTRL_ID_MASK
+ignore define V4L2_CTRL_ID2CLASS
+ignore define V4L2_CTRL_ID2WHICH
+ignore define V4L2_CTRL_DRIVER_PRIV
+ignore define V4L2_CTRL_MAX_DIMS
+ignore define V4L2_CTRL_WHICH_CUR_VAL
+ignore define V4L2_CTRL_WHICH_DEF_VAL
+ignore define V4L2_OUT_CAP_CUSTOM_TIMINGS
+ignore define V4L2_CID_MAX_CTRLS
+
+ignore ioctl VIDIOC_RESERVED
+ignore define BASE_VIDIOC_PRIVATE
+
+# Associate ioctls with their counterparts
+replace ioctl VIDIOC_DBG_S_REGISTER vidioc_dbg_g_register
+replace ioctl VIDIOC_DQBUF vidioc_qbuf
+replace ioctl VIDIOC_S_AUDOUT vidioc_g_audout
+replace ioctl VIDIOC_S_CROP vidioc_g_crop
+replace ioctl VIDIOC_S_CTRL vidioc_g_ctrl
+replace ioctl VIDIOC_S_DV_TIMINGS vidioc_g_dv_timings
+replace ioctl VIDIOC_S_EDID vidioc_g_edid
+replace ioctl VIDIOC_S_EXT_CTRLS vidioc_g_ext_ctrls
+replace ioctl VIDIOC_S_FBUF vidioc_g_fbuf
+replace ioctl VIDIOC_S_FMT vidioc_g_fmt
+replace ioctl VIDIOC_S_FREQUENCY vidioc_g_frequency
+replace ioctl VIDIOC_S_INPUT vidioc_g_input
+replace ioctl VIDIOC_S_JPEGCOMP vidioc_g_jpegcomp
+replace ioctl VIDIOC_S_MODULATOR vidioc_g_modulator
+replace ioctl VIDIOC_S_OUTPUT vidioc_g_output
+replace ioctl VIDIOC_S_PARM vidioc_g_parm
+replace ioctl VIDIOC_S_PRIORITY vidioc_g_priority
+replace ioctl VIDIOC_S_SELECTION vidioc_g_selection
+replace ioctl VIDIOC_S_STD vidioc_g_std
+replace ioctl VIDIOC_S_AUDIO vidioc_g_audio
+replace ioctl VIDIOC_S_TUNER vidioc_g_tuner
+replace ioctl VIDIOC_TRY_DECODER_CMD vidioc_decoder_cmd
+replace ioctl VIDIOC_TRY_ENCODER_CMD vidioc_encoder_cmd
+replace ioctl VIDIOC_TRY_EXT_CTRLS vidioc_g_ext_ctrls
+replace ioctl VIDIOC_TRY_FMT vidioc_g_fmt
+replace ioctl VIDIOC_STREAMOFF vidioc_streamon
+replace ioctl VIDIOC_UNSUBSCRIBE_EVENT vidioc_subscribe_event
+replace ioctl VIDIOC_QUERY_EXT_CTRL vidioc_queryctrl
+replace ioctl VIDIOC_QUERYMENU vidioc_queryctrl
projects / cascardo / linux.git / commitdiff
