Documentation/userspace-api/media/v4l/selection-api-configuration.rst

Source file repositories/reference/linux-study-clean/Documentation/userspace-api/media/v4l/selection-api-configuration.rst

File Facts

System
Linux kernel
Corpus path
Documentation/userspace-api/media/v4l/selection-api-configuration.rst
Extension
.rst
Size
6692 bytes
Lines
139
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

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

*************
Configuration
*************

Applications can use the :ref:`selection API <VIDIOC_G_SELECTION>` to
select an area in a video signal or a buffer, and to query for default
settings and hardware limits.

Video hardware can have various cropping, composing and scaling
limitations. It may only scale up or down, support only discrete scaling
factors, or have different scaling abilities in the horizontal and
vertical directions. Also it may not support scaling at all. At the same
time the cropping/composing rectangles may have to be aligned, and both
the source and the sink may have arbitrary upper and lower size limits.
Therefore, as usual, drivers are expected to adjust the requested
parameters and return the actual values selected. An application can
control the rounding behaviour using
:ref:`constraint flags <v4l2-selection-flags>`.


Configuration of video capture
==============================

See figure :ref:`sel-targets-capture` for examples of the selection
targets available for a video capture device. It is recommended to
configure the cropping targets before to the composing targets.

The range of coordinates of the top left corner, width and height of
areas that can be sampled is given by the ``V4L2_SEL_TGT_CROP_BOUNDS``
target. It is recommended for the driver developers to put the top/left
corner at position ``(0,0)``. The rectangle's coordinates are expressed
in pixels.

The top left corner, width and height of the source rectangle, that is
the area actually sampled, is given by the ``V4L2_SEL_TGT_CROP`` target.
It uses the same coordinate system as ``V4L2_SEL_TGT_CROP_BOUNDS``. The
active cropping area must lie completely inside the capture boundaries.
The driver may further adjust the requested size and/or position
according to hardware limitations.

Each capture device has a default source rectangle, given by the
``V4L2_SEL_TGT_CROP_DEFAULT`` target. This rectangle shall cover what the
driver writer considers the complete picture. Drivers shall set the
active crop rectangle to the default when the driver is first loaded,
but not later.

The composing targets refer to a memory buffer. The limits of composing
coordinates are obtained using ``V4L2_SEL_TGT_COMPOSE_BOUNDS``. All
coordinates are expressed in pixels. The rectangle's top/left corner
must be located at position ``(0,0)``. The width and height are equal to
the image size set by :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`.

The part of a buffer into which the image is inserted by the hardware is
controlled by the ``V4L2_SEL_TGT_COMPOSE`` target. The rectangle's
coordinates are also expressed in the same coordinate system as the
bounds rectangle. The composing rectangle must lie completely inside
bounds rectangle. The driver must adjust the composing rectangle to fit
to the bounding limits. Moreover, the driver can perform other
adjustments according to hardware limitations. The application can
control rounding behaviour using
:ref:`constraint flags <v4l2-selection-flags>`.

For capture devices the default composing rectangle is queried using
``V4L2_SEL_TGT_COMPOSE_DEFAULT``. It is usually equal to the bounding
rectangle.

The part of a buffer that is modified by the hardware is given by

Annotation

Implementation Notes