code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _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
========

.. c:macro:: VIDIOC_G_CTRL

``int ioctl(int fd, VIDIOC_G_CTRL, struct v4l2_control *argp)``

.. c:macro:: VIDIOC_S_CTRL

``int ioctl(int fd, VIDIOC_S_CTRL, struct v4l2_control *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer to struct :c:type:`v4l2_control`.

Description
===========

To get the current value of a control applications initialize the ``id``
field of a struct :c:type:`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 :c:type:`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.

.. c:type:: v4l2_control

.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|

.. flat-table:: struct v4l2_control
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2

    * - __u32
      - ``id``
      - Identifies the control, set by the application.
    * - __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 :c:type:`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 :c:type:`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.

    Or if there is an attempt to set an inactive control and the driver is
    not capable of caching the new value until the control is active again.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _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
========

.. c:macro:: VIDIOC_G_DV_TIMINGS

``int ioctl(int fd, VIDIOC_G_DV_TIMINGS, struct v4l2_dv_timings *argp)``

.. c:macro:: VIDIOC_S_DV_TIMINGS

``int ioctl(int fd, VIDIOC_S_DV_TIMINGS, struct v4l2_dv_timings *argp)``

.. c:macro:: VIDIOC_SUBDEV_G_DV_TIMINGS

``int ioctl(int fd, VIDIOC_SUBDEV_G_DV_TIMINGS, struct v4l2_dv_timings *argp)``

.. c:macro:: VIDIOC_SUBDEV_S_DV_TIMINGS

``int ioctl(int fd, VIDIOC_SUBDEV_S_DV_TIMINGS, struct v4l2_dv_timings *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer to struct :c:type:`v4l2_dv_timings`.

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
:c:type:`v4l2_dv_timings`. These ioctls take a
pointer to the struct :c:type:`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.

Calling ``VIDIOC_SUBDEV_S_DV_TIMINGS`` on a subdev device node that has been
registered in read-only mode is not allowed. An error is returned and the errno
variable is set to ``-EPERM``.

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.

EPERM
    ``VIDIOC_SUBDEV_S_DV_TIMINGS`` has been called on a read-only subdevice.

.. c:type:: v4l2_bt_timings

.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|

.. cssclass:: longtable

.. flat-table:: struct v4l2_bt_timings
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2

    * - __u32
      - ``width``
      - Width of the active video in pixels.
    * - __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.
    * - __u32
      - ``interlaced``
      - Progressive (``V4L2_DV_PROGRESSIVE``) or interlaced (``V4L2_DV_INTERLACED``).
    * - __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.
    * - __u64
      - ``pixelclock``
      - Pixel clock in Hz. Ex. 74.25MHz->74250000
    * - __u32
      - ``hfrontporch``
      - Horizontal front porch in pixels
    * - __u32
      - ``hsync``
      - Horizontal sync length in pixels
    * - __u32
      - ``hbackporch``
      - Horizontal back porch in pixels
    * - __u32
      - ``vfrontporch``
      - Vertical front porch in lines. For interlaced formats this refers
	to the odd field (aka field 1).
    * - __u32
      - ``vsync``
      - Vertical sync length in lines. For interlaced formats this refers
	to the odd field (aka field 1).
    * - __u32
      - ``vbackporch``
      - Vertical back porch in lines. For interlaced formats this refers
	to the odd field (aka field 1).
    * - __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.
    * - __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.
    * - __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.
    * - __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.
    * - __u32
      - ``flags``
      - Several flags giving more information about the format. See
	:ref:`dv-bt-flags` for a description of the flags.
    * - struct :c:type:`v4l2_fract`
      - ``picture_aspect``
      - The picture aspect if the pixels are not square. Only valid if the
        ``V4L2_DV_FL_HAS_PICTURE_ASPECT`` flag is set.
    * - __u8
      - ``cea861_vic``
      - The Video Identification Code according to the CEA-861 standard.
        Only valid if the ``V4L2_DV_FL_HAS_CEA861_VIC`` flag is set.
    * - __u8
      - ``hdmi_vic``
      - The Video Identification Code according to the HDMI standard.
        Only valid if the ``V4L2_DV_FL_HAS_HDMI_VIC`` flag is set.
    * - __u8
      - ``reserved[46]``
      - Reserved for future extensions. Drivers and applications must set
	the array to zero.

.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{7.0cm}|p{3.1cm}|

.. c:type:: v4l2_dv_timings

.. flat-table:: struct v4l2_dv_timings
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2

    * - __u32
      - ``type``
      - Type of DV timings as listed in :ref:`dv-timing-types`.
    * - union {
      - (anonymous)
    * - struct :c:type:`v4l2_bt_timings`
      - ``bt``
      - Timings defined by BT.656/1120 specifications
    * - __u32
      - ``reserved``\ [32]
      -
    * - }
      -

.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|

.. _dv-timing-types:

.. flat-table:: DV Timing types
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2

    * - Timing type
      - value
      - Description
    * -
      -
      -
    * - ``V4L2_DV_BT_656_1120``
      - 0
      - BT.656/1120 timings

.. tabularcolumns:: |p{6.5cm}|p{11.0cm}|

.. cssclass:: longtable

.. _dv-bt-standards:

.. flat-table:: DV BT Timing standards
    :header-rows:  0
    :stub-columns: 0

    * - Timing standard
      - Description
    * - ``V4L2_DV_BT_STD_CEA861``
      - The timings follow the CEA-861 Digital TV Profile standard
    * - ``V4L2_DV_BT_STD_DMT``
      - The timings follow the VESA Discrete Monitor Timings standard
    * - ``V4L2_DV_BT_STD_CVT``
      - The timings follow the VESA Coordinated Video Timings standard
    * - ``V4L2_DV_BT_STD_GTF``
      - The timings follow the VESA Generalized Timings Formula standard
    * - ``V4L2_DV_BT_STD_SDI``
      - The timings follow the SDI Timings standard.
	There are no horizontal syncs/porches at all in this format.
	Total blanking timings must be set in hsync or vsync fields only.

.. tabularcolumns:: |p{7.7cm}|p{9.8cm}|

.. cssclass:: longtable

.. _dv-bt-flags:

.. flat-table:: DV BT Timing flags
    :header-rows:  0
    :stub-columns: 0

    * - Flag
      - Description
    * - ``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.
    * - ``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.
    * - ``V4L2_DV_FL_REDUCED_FPS``
      - CEA-861 specific: only valid for video transmitters or video
        receivers that have the ``V4L2_DV_FL_CAN_DETECT_REDUCED_FPS``
	set. This flag is cleared otherwise. 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 for a transmitter, 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 be cleared.

	If a video receiver detects that the format uses a reduced framerate,
	then it will set this flag to signal this to the application.
    * - ``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.
    * - ``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.
    * - ``V4L2_DV_FL_FIRST_FIELD_EXTRA_LINE``
      - Some formats like SMPTE-125M have an interlaced signal with a odd
	total height. For these formats, if this flag is set, the first
	field has the extra line. Else, it is the second field.
    * - ``V4L2_DV_FL_HAS_PICTURE_ASPECT``
      - If set, then the picture_aspect field is valid. Otherwise assume that
        the pixels are square, so the picture aspect ratio is the same as the
	width to height ratio.
    * - ``V4L2_DV_FL_HAS_CEA861_VIC``
      - If set, then the cea861_vic field is valid and contains the Video
        Identification Code as per the CEA-861 standard.
    * - ``V4L2_DV_FL_HAS_HDMI_VIC``
      - If set, then the hdmi_vic field is valid and contains the Video
        Identification Code as per the HDMI standard (HDMI Vendor Specific
	InfoFrame).
    * - ``V4L2_DV_FL_CAN_DETECT_REDUCED_FPS``
      - CEA-861 specific: only valid for video receivers, the flag is
        cleared by transmitters.
        If set, then the hardware can detect the difference between
	regular framerates and framerates reduced by 1000/1001. E.g.:
	60 vs 59.94 Hz, 30 vs 29.97 Hz or 24 vs 23.976 Hz.

repo_name: angery/linux


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _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
========

.. c:macro:: VIDIOC_G_EDID

``int ioctl(int fd, VIDIOC_G_EDID, struct v4l2_edid *argp)``

.. c:macro:: VIDIOC_S_EDID

``int ioctl(int fd, VIDIOC_S_EDID, struct v4l2_edid *argp)``

.. c:macro:: VIDIOC_SUBDEV_G_EDID

``int ioctl(int fd, VIDIOC_SUBDEV_G_EDID, struct v4l2_edid *argp)``

.. c:macro:: VIDIOC_SUBDEV_S_EDID

``int ioctl(int fd, VIDIOC_SUBDEV_S_EDID, struct v4l2_edid *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
   Pointer to struct :c:type:`v4l2_edid`.

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::

   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.

.. c:type:: v4l2_edid

.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|

.. flat-table:: struct v4l2_edid
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2

    * - __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.
    * - __u32
      - ``start_block``
      - Read the EDID from starting with this block. Must be 0 when
	setting the EDID.
    * - __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.
    * - __u32
      - ``reserved``\ [5]
      - Reserved for future extensions. Applications and drivers must set
	the array to zero.
    * - __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.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _VIDIOC_G_ENC_INDEX:

************************
ioctl VIDIOC_G_ENC_INDEX
************************

Name
====

VIDIOC_G_ENC_INDEX - Get meta data about a compressed video stream

Synopsis
========

.. c:macro:: VIDIOC_G_ENC_INDEX

``int ioctl(int fd, VIDIOC_G_ENC_INDEX, struct v4l2_enc_idx *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer to struct :c:type:`v4l2_enc_idx`.

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 :c:type:`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.

.. tabularcolumns:: |p{4.2cm}|p{6.2cm}|p{6.9cm}|

.. c:type:: v4l2_enc_idx

.. flat-table:: struct v4l2_enc_idx
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 3 8

    * - __u32
      - ``entries``
      - The number of entries the driver stored in the ``entry`` array.
    * - __u32
      - ``entries_cap``
      - The number of entries the driver can buffer. Must be greater than
	zero.
    * - __u32
      - ``reserved``\ [4]
      - Reserved for future extensions. Drivers must set the
	array to zero.
    * - struct :c:type:`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``.

.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|

.. c:type:: v4l2_enc_idx_entry

.. flat-table:: struct v4l2_enc_idx_entry
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2

    * - __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.
    * - __u64
      - ``pts``
      - The 33 bit *Presentation Time Stamp* of this picture as defined in
	:ref:`mpeg2part1`.
    * - __u32
      - ``length``
      - The length of this picture in bytes.
    * - __u32
      - ``flags``
      - Flags containing the coding type of this picture, see
	:ref:`enc-idx-flags`.
    * - __u32
      - ``reserved``\ [2]
      - Reserved for future extensions. Drivers must set the array to
	zero.

.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}|

.. _enc-idx-flags:

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

    * - ``V4L2_ENC_IDX_FRAME_I``
      - 0x00
      - This is an Intra-coded picture.
    * - ``V4L2_ENC_IDX_FRAME_P``
      - 0x01
      - This is a Predictive-coded picture.
    * - ``V4L2_ENC_IDX_FRAME_B``
      - 0x02
      - This is a Bidirectionally predictive-coded picture.
    * - ``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.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _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
========

.. c:macro:: VIDIOC_G_EXT_CTRLS

``int ioctl(int fd, VIDIOC_G_EXT_CTRLS, struct v4l2_ext_controls *argp)``

.. c:macro:: VIDIOC_S_EXT_CTRLS

``int ioctl(int fd, VIDIOC_S_EXT_CTRLS, struct v4l2_ext_controls *argp)``

.. c:macro:: VIDIOC_TRY_EXT_CTRLS

``int ioctl(int fd, VIDIOC_TRY_EXT_CTRLS, struct v4l2_ext_controls *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer to struct :c:type:`v4l2_ext_controls`.

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
:c:type:`v4l2_ext_controls`, and initialize the
struct :c:type:`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
:c:type:`v4l2_ext_control` and call the
:ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctl. String 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 :c:type:`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
:c:type:`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
:c:type:`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.

If ``request_fd`` is set to a not-yet-queued :ref:`request <media-request-api>`
file descriptor and ``which`` is set to ``V4L2_CTRL_WHICH_REQUEST_VAL``,
then the controls are not applied immediately when calling
:ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`, but instead are applied by
the driver for the buffer associated with the same request.
If the device does not support requests, then ``EACCES`` will be returned.
If requests are supported but an invalid request file descriptor is given,
then ``EINVAL`` will be returned.

An attempt to call :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` for a
request that has already been queued will result in an ``EBUSY`` error.

If ``request_fd`` is specified and ``which`` is set to
``V4L2_CTRL_WHICH_REQUEST_VAL`` during a call to
:ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`, then it will return the
values of the controls at the time of request completion.
If the request is not yet completed, then this will result in an
``EACCES`` 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.

.. tabularcolumns:: |p{6.8cm}|p{4.0cm}|p{6.5cm}|

.. c:type:: v4l2_ext_control

.. raw:: latex

   \footnotesize

.. cssclass:: longtable

.. flat-table:: struct v4l2_ext_control
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2

    * - __u32
      - ``id``
      - Identifies the control, set by the application.
    * - __u32
      - ``size``
      - The total size in bytes of the payload of this control.
    * - :cspan:`2` The ``size`` field is normally 0, but for pointer
	controls this should be set to the size of the memory that contains
	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::

	   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.
    * - __u32
      - ``reserved2``\ [1]
      - Reserved for future extensions. Drivers and applications must set
	the array to zero.
    * - union {
      - (anonymous)
    * - __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.
    * - __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.
    * - char *
      - ``string``
      - A pointer to a string. Valid if this control is of type
	``V4L2_CTRL_TYPE_STRING``.
    * - __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``.
    * - __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``.
    * - __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``.
    * - struct :c:type:`v4l2_area` *
      - ``p_area``
      - A pointer to a struct :c:type:`v4l2_area`. Valid if this control is
        of type ``V4L2_CTRL_TYPE_AREA``.
    * - struct :c:type:`v4l2_ctrl_h264_sps` *
      - ``p_h264_sps``
      - A pointer to a struct :c:type:`v4l2_ctrl_h264_sps`. Valid if this control is
        of type ``V4L2_CTRL_TYPE_H264_SPS``.
    * - struct :c:type:`v4l2_ctrl_h264_pps` *
      - ``p_h264_pps``
      - A pointer to a struct :c:type:`v4l2_ctrl_h264_pps`. Valid if this control is
        of type ``V4L2_CTRL_TYPE_H264_PPS``.
    * - struct :c:type:`v4l2_ctrl_h264_scaling_matrix` *
      - ``p_h264_scaling_matrix``
      - A pointer to a struct :c:type:`v4l2_ctrl_h264_scaling_matrix`. Valid if this control is
        of type ``V4L2_CTRL_TYPE_H264_SCALING_MATRIX``.
    * - struct :c:type:`v4l2_ctrl_h264_pred_weights` *
      - ``p_h264_pred_weights``
      - A pointer to a struct :c:type:`v4l2_ctrl_h264_pred_weights`. Valid if this control is
        of type ``V4L2_CTRL_TYPE_H264_PRED_WEIGHTS``.
    * - struct :c:type:`v4l2_ctrl_h264_slice_params` *
      - ``p_h264_slice_params``
      - A pointer to a struct :c:type:`v4l2_ctrl_h264_slice_params`. Valid if this control is
        of type ``V4L2_CTRL_TYPE_H264_SLICE_PARAMS``.
    * - struct :c:type:`v4l2_ctrl_h264_decode_params` *
      - ``p_h264_decode_params``
      - A pointer to a struct :c:type:`v4l2_ctrl_h264_decode_params`. Valid if this control is
        of type ``V4L2_CTRL_TYPE_H264_DECODE_PARAMS``.
    * - struct :c:type:`v4l2_ctrl_fwht_params` *
      - ``p_fwht_params``
      - A pointer to a struct :c:type:`v4l2_ctrl_fwht_params`. Valid if this control is
        of type ``V4L2_CTRL_TYPE_FWHT_PARAMS``.
    * - struct :c:type:`v4l2_ctrl_vp8_frame` *
      - ``p_vp8_frame``
      - A pointer to a struct :c:type:`v4l2_ctrl_vp8_frame`. Valid if this control is
        of type ``V4L2_CTRL_TYPE_VP8_FRAME``.
    * - struct :c:type:`v4l2_ctrl_mpeg2_sequence` *
      - ``p_mpeg2_sequence``
      - A pointer to a struct :c:type:`v4l2_ctrl_mpeg2_sequence`. Valid if this control is
        of type ``V4L2_CTRL_TYPE_MPEG2_SEQUENCE``.
    * - struct :c:type:`v4l2_ctrl_mpeg2_picture` *
      - ``p_mpeg2_picture``
      - A pointer to a struct :c:type:`v4l2_ctrl_mpeg2_picture`. Valid if this control is
        of type ``V4L2_CTRL_TYPE_MPEG2_PICTURE``.
    * - struct :c:type:`v4l2_ctrl_mpeg2_quantisation` *
      - ``p_mpeg2_quantisation``
      - A pointer to a struct :c:type:`v4l2_ctrl_mpeg2_quantisation`. Valid if this control is
        of type ``V4L2_CTRL_TYPE_MPEG2_QUANTISATION``.
    * - struct :c:type:`v4l2_ctrl_vp9_compressed_hdr` *
      - ``p_vp9_compressed_hdr_probs``
      - A pointer to a struct :c:type:`v4l2_ctrl_vp9_compressed_hdr`. Valid if this
        control is of type ``V4L2_CTRL_TYPE_VP9_COMPRESSED_HDR``.
    * - struct :c:type:`v4l2_ctrl_vp9_frame` *
      - ``p_vp9_frame``
      - A pointer to a struct :c:type:`v4l2_ctrl_vp9_frame`. Valid if this
        control is of type ``V4L2_CTRL_TYPE_VP9_FRAME``.
    * - struct :c:type:`v4l2_ctrl_hdr10_cll_info` *
      - ``p_hdr10_cll``
      - A pointer to a struct :c:type:`v4l2_ctrl_hdr10_cll_info`. Valid if this control is
        of type ``V4L2_CTRL_TYPE_HDR10_CLL_INFO``.
    * - struct :c:type:`v4l2_ctrl_hdr10_mastering_display` *
      - ``p_hdr10_mastering``
      - A pointer to a struct :c:type:`v4l2_ctrl_hdr10_mastering_display`. Valid if this control is
        of type ``V4L2_CTRL_TYPE_HDR10_MASTERING_DISPLAY``.
    * - struct :c:type:`v4l2_ctrl_hevc_sps` *
      - ``p_hevc_sps``
      - A pointer to a struct :c:type:`v4l2_ctrl_hevc_sps`. Valid if this
        control is of type ``V4L2_CTRL_TYPE_HEVC_SPS``.
    * - struct :c:type:`v4l2_ctrl_hevc_pps` *
      - ``p_hevc_pps``
      - A pointer to a struct :c:type:`v4l2_ctrl_hevc_pps`. Valid if this
        control is of type ``V4L2_CTRL_TYPE_HEVC_PPS``.
    * - struct :c:type:`v4l2_ctrl_hevc_slice_params` *
      - ``p_hevc_slice_params``
      - A pointer to a struct :c:type:`v4l2_ctrl_hevc_slice_params`. Valid if this
        control is of type ``V4L2_CTRL_TYPE_HEVC_SLICE_PARAMS``.
    * - struct :c:type:`v4l2_ctrl_hevc_scaling_matrix` *
      - ``p_hevc_scaling_matrix``
      - A pointer to a struct :c:type:`v4l2_ctrl_hevc_scaling_matrix`. Valid if this
        control is of type ``V4L2_CTRL_TYPE_HEVC_SCALING_MATRIX``.
    * - struct :c:type:`v4l2_ctrl_hevc_decode_params` *
      - ``p_hevc_decode_params``
      - A pointer to a struct :c:type:`v4l2_ctrl_hevc_decode_params`. Valid if this
        control is of type ``V4L2_CTRL_TYPE_HEVC_DECODE_PARAMS``.
    * - 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.
    * - }
      -

.. raw:: latex

   \normalsize

.. tabularcolumns:: |p{4.0cm}|p{2.5cm}|p{10.8cm}|

.. c:type:: v4l2_ext_controls

.. cssclass:: longtable

.. flat-table:: struct v4l2_ext_controls
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2

    * - union {
      - (anonymous)
    * - __u32
      - ``which``
      - Which value of the control to get/set/try.
    * - :cspan:`2` ``V4L2_CTRL_WHICH_CUR_VAL`` will return the current value of
	the control, ``V4L2_CTRL_WHICH_DEF_VAL`` will return the default
	value of the control and ``V4L2_CTRL_WHICH_REQUEST_VAL`` indicates that
	these controls have to be retrieved from a request or tried/set for
	a request. In the latter case the ``request_fd`` field contains the
	file descriptor of the request that should be used. If the device
	does not support requests, then ``EACCES`` will be returned.

	When using ``V4L2_CTRL_WHICH_DEF_VAL`` be aware 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 ``which`` to ``V4L2_CTRL_WHICH_CUR_VAL`` and calling
	:ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` with a count of 0.
	If that fails, then the driver does not support ``V4L2_CTRL_WHICH_CUR_VAL``.
    * - __u32
      - ``ctrl_class``
      - Deprecated name kept for backwards compatibility. Use ``which`` instead.
    * - }
      -
    * - __u32
      - ``count``
      - The number of controls in the controls array. May also be zero.
    * - __u32
      - ``error_idx``
      - Index of the failing control. Set by the driver in case of an error.
    * - :cspan:`2` 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>`.
    * - __s32
      - ``request_fd``
      - File descriptor of the request to be used by this operation. Only
	valid if ``which`` is set to ``V4L2_CTRL_WHICH_REQUEST_VAL``.
	If the device does not support requests, then ``EACCES`` will be returned.
	If requests are supported but an invalid request file descriptor is
	given, then ``EINVAL`` will be returned.
    * - __u32
      - ``reserved``\ [1]
      - Reserved for future extensions.

	Drivers and applications must set the array to zero.
    * - struct :c:type:`v4l2_ext_control` *
      - ``controls``
      - Pointer to an array of ``count`` v4l2_ext_control structures.

	Ignored if ``count`` equals zero.

.. tabularcolumns:: |p{7.3cm}|p{2.0cm}|p{8.0cm}|

.. cssclass:: longtable

.. _ctrl-class:

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

    * - ``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.
    * - ``V4L2_CTRL_CLASS_CODEC``
      - 0x990000
      - The class containing stateful codec controls. These controls are
	described in :ref:`codec-controls`.
    * - ``V4L2_CTRL_CLASS_CAMERA``
      - 0x9a0000
      - The class containing camera controls. These controls are described
	in :ref:`camera-controls`.
    * - ``V4L2_CTRL_CLASS_FM_TX``
      - 0x9b0000
      - The class containing FM Transmitter (FM TX) controls. These
	controls are described in :ref:`fm-tx-controls`.
    * - ``V4L2_CTRL_CLASS_FLASH``
      - 0x9c0000
      - The class containing flash device controls. These controls are
	described in :ref:`flash-controls`.
    * - ``V4L2_CTRL_CLASS_JPEG``
      - 0x9d0000
      - The class containing JPEG compression controls. These controls are
	described in :ref:`jpeg-controls`.
    * - ``V4L2_CTRL_CLASS_IMAGE_SOURCE``
      - 0x9e0000
      - The class containing image source controls. These controls are
	described in :ref:`image-source-controls`.
    * - ``V4L2_CTRL_CLASS_IMAGE_PROC``
      - 0x9f0000
      - The class containing image processing controls. These controls are
	described in :ref:`image-process-controls`.
    * - ``V4L2_CTRL_CLASS_FM_RX``
      - 0xa10000
      - The class containing FM Receiver (FM RX) controls. These controls
	are described in :ref:`fm-rx-controls`.
    * - ``V4L2_CTRL_CLASS_RF_TUNER``
      - 0xa20000
      - The class containing RF tuner controls. These controls are
	described in :ref:`rf-tuner-controls`.
    * - ``V4L2_CTRL_CLASS_DETECT``
      - 0xa30000
      - The class containing motion or object detection controls. These controls
        are described in :ref:`detect-controls`.
    * - ``V4L2_CTRL_CLASS_CODEC_STATELESS``
      - 0xa40000
      - The class containing stateless codec controls. These controls are
	described in :ref:`codec-stateless-controls`.
    * - ``V4L2_CTRL_CLASS_COLORIMETRY``
      - 0xa50000
      - The class containing colorimetry controls. These controls are
	described in :ref:`colorimetry-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 :c:type:`v4l2_ext_control` ``id`` is
    invalid, or the struct :c:type:`v4l2_ext_controls`
    ``which`` is invalid, or the struct
    :c:type:`v4l2_ext_control` ``value`` was
    inappropriate (e.g. the given menu index is not supported by the
    driver), or the ``which`` field was set to ``V4L2_CTRL_WHICH_REQUEST_VAL``
    but the given ``request_fd`` was invalid or ``V4L2_CTRL_WHICH_REQUEST_VAL``
    is not supported by the kernel.
    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 :c:type:`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, or (if the ``which`` field was set to
    ``V4L2_CTRL_WHICH_REQUEST_VAL``) the request was queued but not yet
    completed.

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, or to get a control from a request that has not yet been
    completed.

    Or the ``which`` field was set to ``V4L2_CTRL_WHICH_REQUEST_VAL`` but the
    device does not support requests.

    Or if there is an attempt to set an inactive control and the driver is
    not capable of caching the new value until the control is active again.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _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
========

.. c:macro:: VIDIOC_G_FBUF

``int ioctl(int fd, VIDIOC_G_FBUF, struct v4l2_framebuffer *argp)``

.. c:macro:: VIDIOC_S_FBUF

``int ioctl(int fd, VIDIOC_S_FBUF, const struct v4l2_framebuffer *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer to struct :c:type:`v4l2_framebuffer`.

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 struct :c:type:`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
:c:type:`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.

.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{6.6cm}|

.. c:type:: v4l2_framebuffer

.. cssclass:: longtable

.. flat-table:: struct v4l2_framebuffer
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 1 2

    * - __u32
      - ``capability``
      -
      - Overlay capability flags set by the driver, see
	:ref:`framebuffer-cap`.
    * - __u32
      - ``flags``
      -
      - Overlay control flags set by application and driver, see
	:ref:`framebuffer-flags`
    * - void *
      - ``base``
      -
      - Physical base address of the framebuffer, that is the address of
	the pixel in the top left corner of the framebuffer. [#f1]_
    * -
      -
      -
      - 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`).
    * - struct
      - ``fmt``
      -
      - Layout of the frame buffer.
    * -
      - __u32
      - ``width``
      - Width of the frame buffer in pixels.
    * -
      - __u32
      - ``height``
      - Height of the frame buffer in pixels.
    * -
      - __u32
      - ``pixelformat``
      - The pixel format of the framebuffer.
    * -
      -
      -
      - For *non-destructive Video Overlays* this field only defines a
	format for the struct :c:type:`v4l2_window`
	``chromakey`` field.
    * -
      -
      -
      - For *destructive Video Overlays* applications must initialize this
	field. For *Video Output Overlays* the driver must return a valid
	format.
    * -
      -
      -
      - 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.
    * -
      - enum :c:type:`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 :c:type:`v4l2_window`.
    * -
      - __u32
      - ``bytesperline``
      - Distance in bytes between the leftmost pixels in two adjacent
	lines.
    * - :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.
    * -
      - __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.
    * -
      - enum :c:type:`v4l2_colorspace`
      - ``colorspace``
      - This information supplements the ``pixelformat`` and must be set
	by the driver, see :ref:`colorspaces`.
    * -
      - __u32
      - ``priv``
      - Reserved. Drivers and applications must set this field to zero.

.. tabularcolumns:: |p{7.4cm}|p{1.6cm}|p{8.3cm}|

.. _framebuffer-cap:

.. flat-table:: Frame Buffer Capability Flags
    :header-rows:  0
    :stub-columns: 0
    :widths:       3 1 4

    * - ``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.
    * - ``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.
    * - ``V4L2_FBUF_CAP_LIST_CLIPPING``
      - 0x0004
      - The device supports clipping using a list of clip rectangles.
    * - ``V4L2_FBUF_CAP_BITMAP_CLIPPING``
      - 0x0008
      - The device supports clipping using a bit mask.
    * - ``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.
    * - ``V4L2_FBUF_CAP_GLOBAL_ALPHA``
      - 0x0020
      - The device supports alpha blending using a global alpha value.
	Alpha blending makes no sense for destructive overlays.
    * - ``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.
    * - ``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``

.. tabularcolumns:: |p{7.4cm}|p{1.6cm}|p{8.3cm}|

.. _framebuffer-flags:

.. cssclass:: longtable

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

    * - ``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.
    * - ``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.
    * - ``V4L2_FBUF_FLAG_CHROMAKEY``
      - 0x0004
      - Use chroma-keying. The chroma-key color is determined by the
	``chromakey`` field of struct :c:type:`v4l2_window`
	and negotiated with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
	ioctl, see :ref:`overlay` and :ref:`osd`.
    * - :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`.
    * - ``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.
    * - ``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
	:c:type:`v4l2_window` and negotiated with the
	:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay`
	and :ref:`osd`.
    * - ``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.
    * - ``V4L2_FBUF_FLAG_SRC_CHROMAKEY``
      - 0x0040
      - Use source chroma-keying. The source chroma-key color is
	determined by the ``chromakey`` field of struct
	:c:type:`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
	:c:type:`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.

.. [#f1]
   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>`__.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _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
========

.. c:macro:: VIDIOC_G_FMT

``int ioctl(int fd, VIDIOC_G_FMT, struct v4l2_format *argp)``

.. c:macro:: VIDIOC_S_FMT

``int ioctl(int fd, VIDIOC_S_FMT, struct v4l2_format *argp)``

.. c:macro:: VIDIOC_TRY_FMT

``int ioctl(int fd, VIDIOC_TRY_FMT, struct v4l2_format *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer to struct :c:type:`v4l2_format`.

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 :c:type:`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
:c:type:`v4l2_pix_format` ``pix`` or the struct
:c:type:`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 struct :c:type:`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.

.. c:type:: v4l2_format

.. tabularcolumns::  |p{7.4cm}|p{4.4cm}|p{5.5cm}|

.. flat-table:: struct v4l2_format
    :header-rows:  0
    :stub-columns: 0

    * - __u32
      - ``type``
      - Type of the data stream, see :c:type:`v4l2_buf_type`.
    * - union {
      - ``fmt``
    * - struct :c:type:`v4l2_pix_format`
      - ``pix``
      - Definition of an image format, see :ref:`pixfmt`, used by video
	capture and output devices.
    * - struct :c:type:`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>`.
    * - struct :c:type:`v4l2_window`
      - ``win``
      - Definition of an overlaid image, see :ref:`overlay`, used by
	video overlay devices.
    * - struct :c:type:`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.
    * - struct :c:type:`v4l2_sliced_vbi_format`
      - ``sliced``
      - Sliced VBI capture or output parameters. See :ref:`sliced` for
	details. Used by sliced VBI capture and output devices.
    * - struct :c:type:`v4l2_sdr_format`
      - ``sdr``
      - Definition of a data format, see :ref:`pixfmt`, used by SDR
	capture and output devices.
    * - struct :c:type:`v4l2_meta_format`
      - ``meta``
      - Definition of a metadata format, see :ref:`meta-formats`, used by
	metadata capture devices.
    * - __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 :c:type:`v4l2_format` ``type`` field is
    invalid or the requested buffer type not supported.

EBUSY
    The device is busy and cannot change the format. This could be
    because or the device is streaming or buffers are allocated or
    queued to the driver. Relevant for :ref:`VIDIOC_S_FMT
    <VIDIOC_G_FMT>` only.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _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
========

.. c:macro:: VIDIOC_G_FREQUENCY

``int ioctl(int fd, VIDIOC_G_FREQUENCY, struct v4l2_frequency *argp)``

.. c:macro:: VIDIOC_S_FREQUENCY

``int ioctl(int fd, VIDIOC_S_FREQUENCY, const struct v4l2_frequency *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer to struct :c:type:`v4l2_frequency`.

Description
===========

To get the current tuner or modulator radio frequency applications set
the ``tuner`` field of a struct
:c:type:`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 :c:type:`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.

.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|

.. c:type:: v4l2_frequency

.. flat-table:: struct v4l2_frequency
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2

    * - __u32
      - ``tuner``
      - The tuner or modulator index number. This is the same value as in
	the struct :c:type:`v4l2_input` ``tuner`` field and
	the struct :c:type:`v4l2_tuner` ``index`` field, or
	the struct :c:type:`v4l2_output` ``modulator`` field
	and the struct :c:type:`v4l2_modulator` ``index``
	field.
    * - __u32
      - ``type``
      - The tuner type. This is the same value as in the struct
	:c:type:`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 :c:type:`v4l2_tuner_type`
    * - __u32
      - ``frequency``
      - Tuning frequency in units of 62.5 kHz, or if the struct
	:c:type:`v4l2_tuner` or struct
	:c:type:`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.
    * - __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.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _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
========

.. c:macro:: VIDIOC_G_INPUT

``int ioctl(int fd, VIDIOC_G_INPUT, int *argp)``

.. c:macro:: VIDIOC_S_INPUT

``int ioctl(int fd, VIDIOC_S_INPUT, int *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer an integer with input index.

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
:c:type:`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.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _VIDIOC_G_JPEGCOMP:

******************************************
ioctl VIDIOC_G_JPEGCOMP, VIDIOC_S_JPEGCOMP
******************************************

Name
====

VIDIOC_G_JPEGCOMP - VIDIOC_S_JPEGCOMP

Synopsis
========

.. c:macro:: VIDIOC_G_JPEGCOMP

``int ioctl(int fd, VIDIOC_G_JPEGCOMP, v4l2_jpegcompression *argp)``

.. c:macro:: VIDIOC_S_JPEGCOMP

``int ioctl(int fd, VIDIOC_S_JPEGCOMP, const v4l2_jpegcompression *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer to struct :c:type:`v4l2_jpegcompression`.

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.

.. tabularcolumns:: |p{1.2cm}|p{3.0cm}|p{13.1cm}|

.. c:type:: v4l2_jpegcompression

.. flat-table:: struct v4l2_jpegcompression
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2

    * - 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.
    * - int
      - ``APPn``
      -
    * - int
      - ``APP_len``
      -
    * - char
      - ``APP_data``\ [60]
      -
    * - int
      - ``COM_len``
      -
    * - char
      - ``COM_data``\ [60]
      -
    * - __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.

.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}|

.. _jpeg-markers:

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

    * - ``V4L2_JPEG_MARKER_DHT``
      - (1<<3)
      - Define Huffman Tables
    * - ``V4L2_JPEG_MARKER_DQT``
      - (1<<4)
      - Define Quantization Tables
    * - ``V4L2_JPEG_MARKER_DRI``
      - (1<<5)
      - Define Restart Interval
    * - ``V4L2_JPEG_MARKER_COM``
      - (1<<6)
      - Comment segment
    * - ``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.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _VIDIOC_G_MODULATOR:

********************************************
ioctl VIDIOC_G_MODULATOR, VIDIOC_S_MODULATOR
********************************************

Name
====

VIDIOC_G_MODULATOR - VIDIOC_S_MODULATOR - Get or set modulator attributes

Synopsis
========

.. c:macro:: VIDIOC_G_MODULATOR

``int ioctl(int fd, VIDIOC_G_MODULATOR, struct v4l2_modulator *argp)``

.. c:macro:: VIDIOC_S_MODULATOR

``int ioctl(int fd, VIDIOC_S_MODULATOR, const struct v4l2_modulator *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer to struct :c:type:`v4l2_modulator`.

Description
===========

To query the attributes of a modulator applications initialize the
``index`` field and zero out the ``reserved`` array of a struct
:c:type:`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.

.. tabularcolumns:: |p{2.9cm}|p{2.9cm}|p{5.8cm}|p{2.9cm}|p{2.4cm}|

.. c:type:: v4l2_modulator

.. flat-table:: struct v4l2_modulator
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2 1 1

    * - __u32
      - ``index``
      - Identifies the modulator, set by the application.
    * - __u8
      - ``name``\ [32]
      - Name of the modulator, a NUL-terminated ASCII string.

	This information is intended for the user.
    * - __u32
      - ``capability``
      - Modulator capability flags. No flags are defined for this field,
	the tuner flags in struct :c:type:`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.
    * - __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.
    * - __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.
    * - __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.
    * - __u32
      - ``type``
      - :cspan:`2` Type of the modulator, see :c:type:`v4l2_tuner_type`.
    * - __u32
      - ``reserved``\ [3]
      - Reserved for future extensions.

	Drivers and applications must set the array to zero.

.. tabularcolumns:: |p{6.0cm}|p{2.0cm}|p{9.3cm}|

.. cssclass:: longtable

.. _modulator-txsubchans:

.. flat-table:: Modulator Audio Transmission Flags
    :header-rows:  0
    :stub-columns: 0
    :widths:       3 1 4

    * - ``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``.
    * - ``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.
    * - ``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.
    * - ``V4L2_TUNER_SUB_LANG2``
      - 0x0004
      - Same effect as ``V4L2_TUNER_SUB_SAP``.
    * - ``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.
    * - ``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 :c:type:`v4l2_modulator` ``index`` is
    out of bounds.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _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
========

.. c:macro:: VIDIOC_G_OUTPUT

``int ioctl(int fd, VIDIOC_G_OUTPUT, int *argp)``

.. c:macro:: VIDIOC_S_OUTPUT

``int ioctl(int fd, VIDIOC_S_OUTPUT, int *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer to an integer with output index.

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
:c:type:`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. 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.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _VIDIOC_G_PARM:

**********************************
ioctl VIDIOC_G_PARM, VIDIOC_S_PARM
**********************************

Name
====

VIDIOC_G_PARM - VIDIOC_S_PARM - Get or set streaming parameters

Synopsis
========

.. c:macro:: VIDIOC_G_PARM

``int ioctl(int fd, VIDIOC_G_PARM, v4l2_streamparm *argp)``

.. c:macro:: VIDIOC_S_PARM

``int ioctl(int fd, VIDIOC_S_PARM, v4l2_streamparm *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer to struct :c:type:`v4l2_streamparm`.

Description
===========

Applications can request a different frame interval. The capture or
output device will be reconfigured to support the requested frame
interval if possible. Optionally drivers may choose to skip or
repeat frames to achieve the requested frame interval.

For stateful encoders (see :ref:`encoder`) this represents the
frame interval that is typically embedded in the encoded video stream.

Changing the frame interval shall never change the format. Changing the
format, on the other hand, may change the frame interval.

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 :c: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 :c:type:`v4l2_streamparm` which contains a
union holding separate parameters for input and output devices.

.. tabularcolumns:: |p{3.7cm}|p{3.5cm}|p{10.1cm}|

.. c:type:: v4l2_streamparm

.. flat-table:: struct v4l2_streamparm
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2

    * - __u32
      - ``type``
      - The buffer (stream) type, same as struct
	:c:type:`v4l2_format` ``type``, set by the
	application. See :c:type:`v4l2_buf_type`.
    * - union {
      - ``parm``
    * - struct :c:type:`v4l2_captureparm`
      - ``capture``
      - Parameters for capture devices, used when ``type`` is
	``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or
	``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``.
    * - struct :c:type:`v4l2_outputparm`
      - ``output``
      - Parameters for output devices, used when ``type`` is
	``V4L2_BUF_TYPE_VIDEO_OUTPUT`` or ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``.
    * - __u8
      - ``raw_data``\ [200]
      - A place holder for future extensions.
    * - }

.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|

.. c:type:: v4l2_captureparm

.. flat-table:: struct v4l2_captureparm
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2

    * - __u32
      - ``capability``
      - See :ref:`parm-caps`.
    * - __u32
      - ``capturemode``
      - Set by drivers and applications, see :ref:`parm-flags`.
    * - struct :c:type:`v4l2_fract`
      - ``timeperframe``
      - This is the desired period between successive frames captured by
	the driver, in seconds.
    * - :cspan:`2`

	This will configure the speed at which the video source (e.g. a sensor)
	generates video frames. If the speed is fixed, then the driver may
	choose to skip or repeat frames in order to achieve the requested
	frame rate.

	For stateful encoders (see :ref:`encoder`) this represents the
	frame interval that is typically embedded in the encoded video stream.

	Applications store here the desired frame period, drivers return
	the actual frame period.

	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.
    * - __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`.
    * - __u32
      - ``readbuffers``
      - Applications set this field to the desired number of buffers used
	internally by the driver in :c: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`.
    * - __u32
      - ``reserved``\ [4]
      - Reserved for future extensions. Drivers and applications must set
	the array to zero.

.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|

.. c:type:: v4l2_outputparm

.. flat-table:: struct v4l2_outputparm
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2

    * - __u32
      - ``capability``
      - See :ref:`parm-caps`.
    * - __u32
      - ``outputmode``
      - Set by drivers and applications, see :ref:`parm-flags`.
    * - struct :c:type:`v4l2_fract`
      - ``timeperframe``
      - This is the desired period between successive frames output by the
	driver, in seconds.
    * - :cspan:`2`

	The field is intended to repeat frames on the driver side in
	:c:func:`write()` mode (in streaming mode timestamps
	can be used to throttle the output), saving I/O bandwidth.

	For stateful encoders (see :ref:`encoder`) this represents the
	frame interval that is typically embedded in the encoded video stream
	and it provides a hint to the encoder of the speed at which raw
	frames are queued up to the encoder.

	Applications store here the desired frame period, drivers return
	the actual frame period.

	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.
    * - __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`.
    * - __u32
      - ``writebuffers``
      - Applications set this field to the desired number of buffers used
	internally by the driver in :c: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`.
    * - __u32
      - ``reserved``\ [4]
      - Reserved for future extensions. Drivers and applications must set
	the array to zero.

.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}|

.. _parm-caps:

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

    * - ``V4L2_CAP_TIMEPERFRAME``
      - 0x1000
      - The frame period can be modified by setting the ``timeperframe``
	field.

.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}|

.. _parm-flags:

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

    * - ``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 :c: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.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _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
========

.. c:macro:: VIDIOC_G_PRIORITY

``int ioctl(int fd, VIDIOC_G_PRIORITY, enum v4l2_priority *argp)``

.. c:macro:: VIDIOC_S_PRIORITY

``int ioctl(int fd, VIDIOC_S_PRIORITY, const enum v4l2_priority *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer to an enum :c:type:`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.

.. c:type:: v4l2_priority

.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}|

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

    * - ``V4L2_PRIORITY_UNSET``
      - 0
      -
    * - ``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.
    * - ``V4L2_PRIORITY_INTERACTIVE``
      - 2
      -
    * - ``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.
    * - ``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.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _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
========

.. c:macro:: VIDIOC_G_SELECTION

``int ioctl(int fd, VIDIOC_G_SELECTION, struct v4l2_selection *argp)``

.. c:macro:: VIDIOC_S_SELECTION

``int ioctl(int fd, VIDIOC_S_SELECTION, struct v4l2_selection *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer to struct :c:type:`v4l2_selection`.

Description
===========

The ioctls are used to query and configure selection rectangles.

To query the cropping (composing) rectangle set struct
:c:type:`v4l2_selection` ``type`` field to the
respective buffer type. The next step is setting the
value of struct :c:type:`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
:c:type:`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 :c:type:`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
:c:type:`v4l2_selection` ``type`` field to the
respective buffer type. The next step is setting the
value of struct :c:type:`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 :c:type:`v4l2_rect` ``r`` rectangle need
to be set to the desired active area. Field struct
:c:type:`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 :c:type:`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
   :c:type:`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 :c:type:`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:

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

    Size adjustments with constraint flags.

    Behaviour of rectangle adjustment for different constraint flags.

.. c:type:: v4l2_selection

.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|

.. flat-table:: struct v4l2_selection
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2

    * - __u32
      - ``type``
      - Type of the buffer (from enum
	:c:type:`v4l2_buf_type`).
    * - __u32
      - ``target``
      - Used to select between
	:ref:`cropping and composing rectangles <v4l2-selections-common>`.
    * - __u32
      - ``flags``
      - Flags controlling the selection rectangle adjustments, refer to
	:ref:`selection flags <v4l2-selection-flags>`.
    * - struct :c:type:`v4l2_rect`
      - ``r``
      - The selection rectangle.
    * - __u32
      - ``reserved[9]``
      - Reserved fields for future use. Drivers and applications must zero
	this array.

.. note::
   Unfortunately in the case of multiplanar buffer types
   (``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``)
   this API was messed up with regards to how the :c:type:`v4l2_selection` ``type`` field
   should be filled in. Some drivers only accepted the ``_MPLANE`` buffer type while
   other drivers only accepted a non-multiplanar buffer type (i.e. without the
   ``_MPLANE`` at the end).

   Starting with kernel 4.13 both variations are allowed.

Return Value
============

On success 0 is returned, on 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 :c:type:`v4l2_rect`
    ``r`` rectangle to satisfy all constraints given in the ``flags``
    argument.

ENODATA
    Selection is not supported for this input or output.

EBUSY
    It is not possible to apply change of the selection rectangle at the
    moment. Usually because streaming is in progress.