1*4882a593Smuzhiyun.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2*4882a593Smuzhiyun.. c:namespace:: V4L 3*4882a593Smuzhiyun 4*4882a593Smuzhiyun.. _VIDIOC_SUBDEV_G_SELECTION: 5*4882a593Smuzhiyun 6*4882a593Smuzhiyun********************************************************** 7*4882a593Smuzhiyunioctl VIDIOC_SUBDEV_G_SELECTION, VIDIOC_SUBDEV_S_SELECTION 8*4882a593Smuzhiyun********************************************************** 9*4882a593Smuzhiyun 10*4882a593SmuzhiyunName 11*4882a593Smuzhiyun==== 12*4882a593Smuzhiyun 13*4882a593SmuzhiyunVIDIOC_SUBDEV_G_SELECTION - VIDIOC_SUBDEV_S_SELECTION - Get or set selection rectangles on a subdev pad 14*4882a593Smuzhiyun 15*4882a593SmuzhiyunSynopsis 16*4882a593Smuzhiyun======== 17*4882a593Smuzhiyun 18*4882a593Smuzhiyun.. c:macro:: VIDIOC_SUBDEV_G_SELECTION 19*4882a593Smuzhiyun 20*4882a593Smuzhiyun``int ioctl(int fd, VIDIOC_SUBDEV_G_SELECTION, struct v4l2_subdev_selection *argp)`` 21*4882a593Smuzhiyun 22*4882a593Smuzhiyun.. c:macro:: VIDIOC_SUBDEV_S_SELECTION 23*4882a593Smuzhiyun 24*4882a593Smuzhiyun``int ioctl(int fd, VIDIOC_SUBDEV_S_SELECTION, struct v4l2_subdev_selection *argp)`` 25*4882a593Smuzhiyun 26*4882a593SmuzhiyunArguments 27*4882a593Smuzhiyun========= 28*4882a593Smuzhiyun 29*4882a593Smuzhiyun``fd`` 30*4882a593Smuzhiyun File descriptor returned by :c:func:`open()`. 31*4882a593Smuzhiyun 32*4882a593Smuzhiyun``argp`` 33*4882a593Smuzhiyun Pointer to struct :c:type:`v4l2_subdev_selection`. 34*4882a593Smuzhiyun 35*4882a593SmuzhiyunDescription 36*4882a593Smuzhiyun=========== 37*4882a593Smuzhiyun 38*4882a593SmuzhiyunThe selections are used to configure various image processing 39*4882a593Smuzhiyunfunctionality performed by the subdevs which affect the image size. This 40*4882a593Smuzhiyuncurrently includes cropping, scaling and composition. 41*4882a593Smuzhiyun 42*4882a593SmuzhiyunThe selection API replaces 43*4882a593Smuzhiyun:ref:`the old subdev crop API <VIDIOC_SUBDEV_G_CROP>`. All the 44*4882a593Smuzhiyunfunction of the crop API, and more, are supported by the selections API. 45*4882a593Smuzhiyun 46*4882a593SmuzhiyunSee :ref:`subdev` for more information on how each selection target 47*4882a593Smuzhiyunaffects the image processing pipeline inside the subdevice. 48*4882a593Smuzhiyun 49*4882a593SmuzhiyunIf the subdev device node has been registered in read-only mode, calls to 50*4882a593Smuzhiyun``VIDIOC_SUBDEV_S_SELECTION`` are only valid if the ``which`` field is set to 51*4882a593Smuzhiyun``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno 52*4882a593Smuzhiyunvariable is set to ``-EPERM``. 53*4882a593Smuzhiyun 54*4882a593SmuzhiyunTypes of selection targets 55*4882a593Smuzhiyun-------------------------- 56*4882a593Smuzhiyun 57*4882a593SmuzhiyunThere are two types of selection targets: actual and bounds. The actual 58*4882a593Smuzhiyuntargets are the targets which configure the hardware. The BOUNDS target 59*4882a593Smuzhiyunwill return a rectangle that contain all possible actual rectangles. 60*4882a593Smuzhiyun 61*4882a593SmuzhiyunDiscovering supported features 62*4882a593Smuzhiyun------------------------------ 63*4882a593Smuzhiyun 64*4882a593SmuzhiyunTo discover which targets are supported, the user can perform 65*4882a593Smuzhiyun``VIDIOC_SUBDEV_G_SELECTION`` on them. Any unsupported target will 66*4882a593Smuzhiyunreturn ``EINVAL``. 67*4882a593Smuzhiyun 68*4882a593SmuzhiyunSelection targets and flags are documented in 69*4882a593Smuzhiyun:ref:`v4l2-selections-common`. 70*4882a593Smuzhiyun 71*4882a593Smuzhiyun.. c:type:: v4l2_subdev_selection 72*4882a593Smuzhiyun 73*4882a593Smuzhiyun.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| 74*4882a593Smuzhiyun 75*4882a593Smuzhiyun.. flat-table:: struct v4l2_subdev_selection 76*4882a593Smuzhiyun :header-rows: 0 77*4882a593Smuzhiyun :stub-columns: 0 78*4882a593Smuzhiyun :widths: 1 1 2 79*4882a593Smuzhiyun 80*4882a593Smuzhiyun * - __u32 81*4882a593Smuzhiyun - ``which`` 82*4882a593Smuzhiyun - Active or try selection, from enum 83*4882a593Smuzhiyun :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`. 84*4882a593Smuzhiyun * - __u32 85*4882a593Smuzhiyun - ``pad`` 86*4882a593Smuzhiyun - Pad number as reported by the media framework. 87*4882a593Smuzhiyun * - __u32 88*4882a593Smuzhiyun - ``target`` 89*4882a593Smuzhiyun - Target selection rectangle. See :ref:`v4l2-selections-common`. 90*4882a593Smuzhiyun * - __u32 91*4882a593Smuzhiyun - ``flags`` 92*4882a593Smuzhiyun - Flags. See :ref:`v4l2-selection-flags`. 93*4882a593Smuzhiyun * - struct :c:type:`v4l2_rect` 94*4882a593Smuzhiyun - ``r`` 95*4882a593Smuzhiyun - Selection rectangle, in pixels. 96*4882a593Smuzhiyun * - __u32 97*4882a593Smuzhiyun - ``reserved``\ [8] 98*4882a593Smuzhiyun - Reserved for future extensions. Applications and drivers must set 99*4882a593Smuzhiyun the array to zero. 100*4882a593Smuzhiyun 101*4882a593SmuzhiyunReturn Value 102*4882a593Smuzhiyun============ 103*4882a593Smuzhiyun 104*4882a593SmuzhiyunOn success 0 is returned, on error -1 and the ``errno`` variable is set 105*4882a593Smuzhiyunappropriately. The generic error codes are described at the 106*4882a593Smuzhiyun:ref:`Generic Error Codes <gen-errors>` chapter. 107*4882a593Smuzhiyun 108*4882a593SmuzhiyunEBUSY 109*4882a593Smuzhiyun The selection rectangle can't be changed because the pad is 110*4882a593Smuzhiyun currently busy. This can be caused, for instance, by an active video 111*4882a593Smuzhiyun stream on the pad. The ioctl must not be retried without performing 112*4882a593Smuzhiyun another action to fix the problem first. Only returned by 113*4882a593Smuzhiyun ``VIDIOC_SUBDEV_S_SELECTION`` 114*4882a593Smuzhiyun 115*4882a593SmuzhiyunEINVAL 116*4882a593Smuzhiyun The struct :c:type:`v4l2_subdev_selection` 117*4882a593Smuzhiyun ``pad`` references a non-existing pad, the ``which`` field 118*4882a593Smuzhiyun references a non-existing format, or the selection target is not 119*4882a593Smuzhiyun supported on the given subdev pad. 120*4882a593Smuzhiyun 121*4882a593SmuzhiyunEPERM 122*4882a593Smuzhiyun The ``VIDIOC_SUBDEV_S_SELECTION`` ioctl has been called on a read-only 123*4882a593Smuzhiyun subdevice and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``. 124