0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: V4L
0003
0004 .. _VIDIOC_SUBDEV_G_SELECTION:
0005
0006 **********************************************************
0007 ioctl VIDIOC_SUBDEV_G_SELECTION, VIDIOC_SUBDEV_S_SELECTION
0008 **********************************************************
0009
0010 Name
0011 ====
0012
0013 VIDIOC_SUBDEV_G_SELECTION - VIDIOC_SUBDEV_S_SELECTION - Get or set selection rectangles on a subdev pad
0014
0015 Synopsis
0016 ========
0017
0018 .. c:macro:: VIDIOC_SUBDEV_G_SELECTION
0019
0020 ``int ioctl(int fd, VIDIOC_SUBDEV_G_SELECTION, struct v4l2_subdev_selection *argp)``
0021
0022 .. c:macro:: VIDIOC_SUBDEV_S_SELECTION
0023
0024 ``int ioctl(int fd, VIDIOC_SUBDEV_S_SELECTION, struct v4l2_subdev_selection *argp)``
0025
0026 Arguments
0027 =========
0028
0029 ``fd``
0030 File descriptor returned by :c:func:`open()`.
0031
0032 ``argp``
0033 Pointer to struct :c:type:`v4l2_subdev_selection`.
0034
0035 Description
0036 ===========
0037
0038 The selections are used to configure various image processing
0039 functionality performed by the subdevs which affect the image size. This
0040 currently includes cropping, scaling and composition.
0041
0042 The selection API replaces
0043 :ref:`the old subdev crop API <VIDIOC_SUBDEV_G_CROP>`. All the
0044 function of the crop API, and more, are supported by the selections API.
0045
0046 See :ref:`subdev` for more information on how each selection target
0047 affects the image processing pipeline inside the subdevice.
0048
0049 If the subdev device node has been registered in read-only mode, calls to
0050 ``VIDIOC_SUBDEV_S_SELECTION`` are only valid if the ``which`` field is set to
0051 ``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
0052 variable is set to ``-EPERM``.
0053
0054 Types of selection targets
0055 --------------------------
0056
0057 There are two types of selection targets: actual and bounds. The actual
0058 targets are the targets which configure the hardware. The BOUNDS target
0059 will return a rectangle that contain all possible actual rectangles.
0060
0061 Discovering supported features
0062 ------------------------------
0063
0064 To discover which targets are supported, the user can perform
0065 ``VIDIOC_SUBDEV_G_SELECTION`` on them. Any unsupported target will
0066 return ``EINVAL``.
0067
0068 Selection targets and flags are documented in
0069 :ref:`v4l2-selections-common`.
0070
0071 .. c:type:: v4l2_subdev_selection
0072
0073 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
0074
0075 .. flat-table:: struct v4l2_subdev_selection
0076 :header-rows: 0
0077 :stub-columns: 0
0078 :widths: 1 1 2
0079
0080 * - __u32
0081 - ``which``
0082 - Active or try selection, from enum
0083 :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
0084 * - __u32
0085 - ``pad``
0086 - Pad number as reported by the media framework.
0087 * - __u32
0088 - ``target``
0089 - Target selection rectangle. See :ref:`v4l2-selections-common`.
0090 * - __u32
0091 - ``flags``
0092 - Flags. See :ref:`v4l2-selection-flags`.
0093 * - struct :c:type:`v4l2_rect`
0094 - ``r``
0095 - Selection rectangle, in pixels.
0096 * - __u32
0097 - ``reserved``\ [8]
0098 - Reserved for future extensions. Applications and drivers must set
0099 the array to zero.
0100
0101 Return Value
0102 ============
0103
0104 On success 0 is returned, on error -1 and the ``errno`` variable is set
0105 appropriately. The generic error codes are described at the
0106 :ref:`Generic Error Codes <gen-errors>` chapter.
0107
0108 EBUSY
0109 The selection rectangle can't be changed because the pad is
0110 currently busy. This can be caused, for instance, by an active video
0111 stream on the pad. The ioctl must not be retried without performing
0112 another action to fix the problem first. Only returned by
0113 ``VIDIOC_SUBDEV_S_SELECTION``
0114
0115 EINVAL
0116 The struct :c:type:`v4l2_subdev_selection`
0117 ``pad`` references a non-existing pad, the ``which`` field
0118 references a non-existing format, or the selection target is not
0119 supported on the given subdev pad.
0120
0121 EPERM
0122 The ``VIDIOC_SUBDEV_S_SELECTION`` ioctl has been called on a read-only
0123 subdevice and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.
