Documentation/userspace-api/media/v4l/vidioc-g-selection.rst

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

File Facts

System
Linux kernel
Corpus path
Documentation/userspace-api/media/v4l/vidioc-g-selection.rst
Extension
.rst
Size
6561 bytes
Lines
191
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

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

Annotation

Implementation Notes