126 lines · plain
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later2.. c:namespace:: V4L3 4.. _VIDIOC_SUBDEV_G_SELECTION:5 6**********************************************************7ioctl VIDIOC_SUBDEV_G_SELECTION, VIDIOC_SUBDEV_S_SELECTION8**********************************************************9 10Name11====12 13VIDIOC_SUBDEV_G_SELECTION - VIDIOC_SUBDEV_S_SELECTION - Get or set selection rectangles on a subdev pad14 15Synopsis16========17 18.. c:macro:: VIDIOC_SUBDEV_G_SELECTION19 20``int ioctl(int fd, VIDIOC_SUBDEV_G_SELECTION, struct v4l2_subdev_selection *argp)``21 22.. c:macro:: VIDIOC_SUBDEV_S_SELECTION23 24``int ioctl(int fd, VIDIOC_SUBDEV_S_SELECTION, struct v4l2_subdev_selection *argp)``25 26Arguments27=========28 29``fd``30 File descriptor returned by :c:func:`open()`.31 32``argp``33 Pointer to struct :c:type:`v4l2_subdev_selection`.34 35Description36===========37 38The selections are used to configure various image processing39functionality performed by the subdevs which affect the image size. This40currently includes cropping, scaling and composition.41 42The selection API replaces43:ref:`the old subdev crop API <VIDIOC_SUBDEV_G_CROP>`. All the44function of the crop API, and more, are supported by the selections API.45 46See :ref:`subdev` for more information on how each selection target47affects the image processing pipeline inside the subdevice.48 49If the subdev device node has been registered in read-only mode, calls to50``VIDIOC_SUBDEV_S_SELECTION`` are only valid if the ``which`` field is set to51``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno52variable is set to ``-EPERM``.53 54Types of selection targets55--------------------------56 57There are two types of selection targets: actual and bounds. The actual58targets are the targets which configure the hardware. The BOUNDS target59will return a rectangle that contain all possible actual rectangles.60 61Discovering supported features62------------------------------63 64To discover which targets are supported, the user can perform65``VIDIOC_SUBDEV_G_SELECTION`` on them. Any unsupported target will66return ``EINVAL``.67 68Selection targets and flags are documented in69:ref:`v4l2-selections-common`.70 71.. c:type:: v4l2_subdev_selection72 73.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|74 75.. flat-table:: struct v4l2_subdev_selection76 :header-rows: 077 :stub-columns: 078 :widths: 1 1 279 80 * - __u3281 - ``which``82 - Active or try selection, from enum83 :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.84 * - __u3285 - ``pad``86 - Pad number as reported by the media framework.87 * - __u3288 - ``target``89 - Target selection rectangle. See :ref:`v4l2-selections-common`.90 * - __u3291 - ``flags``92 - Flags. See :ref:`v4l2-selection-flags`.93 * - struct :c:type:`v4l2_rect`94 - ``r``95 - Selection rectangle, in pixels.96 * - __u3297 - ``stream``98 - Stream identifier.99 * - __u32100 - ``reserved``\ [7]101 - Reserved for future extensions. Applications and drivers must set102 the array to zero.103 104Return Value105============106 107On success 0 is returned, on error -1 and the ``errno`` variable is set108appropriately. The generic error codes are described at the109:ref:`Generic Error Codes <gen-errors>` chapter.110 111EBUSY112 The selection rectangle can't be changed because the pad is113 currently busy. This can be caused, for instance, by an active video114 stream on the pad. The ioctl must not be retried without performing115 another action to fix the problem first. Only returned by116 ``VIDIOC_SUBDEV_S_SELECTION``117 118EINVAL119 The struct :c:type:`v4l2_subdev_selection` ``pad`` references a120 non-existing pad, the ``which`` field has an unsupported value, or the121 selection target is not supported on the given subdev pad.122 123EPERM124 The ``VIDIOC_SUBDEV_S_SELECTION`` ioctl has been called on a read-only125 subdevice and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.126