1.. -*- coding: utf-8; mode: rst -*- 2 3.. _VIDIOC_SUBDEV_G_SELECTION: 4 5********************************************************** 6ioctl VIDIOC_SUBDEV_G_SELECTION, VIDIOC_SUBDEV_S_SELECTION 7********************************************************** 8 9Name 10==== 11 12VIDIOC_SUBDEV_G_SELECTION - VIDIOC_SUBDEV_S_SELECTION - Get or set selection rectangles on a subdev pad 13 14 15Synopsis 16======== 17 18.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_G_SELECTION, struct v4l2_subdev_selection *argp ) 19 :name: VIDIOC_SUBDEV_G_SELECTION 20 21.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_S_SELECTION, struct v4l2_subdev_selection *argp ) 22 :name: VIDIOC_SUBDEV_S_SELECTION 23 24 25Arguments 26========= 27 28``fd`` 29 File descriptor returned by :ref:`open() <func-open>`. 30 31``argp`` 32 Pointer to struct :c:type:`v4l2_subdev_selection`. 33 34 35Description 36=========== 37 38The selections are used to configure various image processing 39functionality performed by the subdevs which affect the image size. This 40currently includes cropping, scaling and composition. 41 42The selection API replaces 43:ref:`the old subdev crop API <VIDIOC_SUBDEV_G_CROP>`. All the 44function of the crop API, and more, are supported by the selections API. 45 46See :ref:`subdev` for more information on how each selection target 47affects the image processing pipeline inside the subdevice. 48 49 50Types of selection targets 51-------------------------- 52 53There are two types of selection targets: actual and bounds. The actual 54targets are the targets which configure the hardware. The BOUNDS target 55will return a rectangle that contain all possible actual rectangles. 56 57 58Discovering supported features 59------------------------------ 60 61To discover which targets are supported, the user can perform 62``VIDIOC_SUBDEV_G_SELECTION`` on them. Any unsupported target will 63return ``EINVAL``. 64 65Selection targets and flags are documented in 66:ref:`v4l2-selections-common`. 67 68 69.. c:type:: v4l2_subdev_selection 70 71.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| 72 73.. flat-table:: struct v4l2_subdev_selection 74 :header-rows: 0 75 :stub-columns: 0 76 :widths: 1 1 2 77 78 * - __u32 79 - ``which`` 80 - Active or try selection, from enum 81 :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`. 82 * - __u32 83 - ``pad`` 84 - Pad number as reported by the media framework. 85 * - __u32 86 - ``target`` 87 - Target selection rectangle. See :ref:`v4l2-selections-common`. 88 * - __u32 89 - ``flags`` 90 - Flags. See :ref:`v4l2-selection-flags`. 91 * - struct :c:type:`v4l2_rect` 92 - ``r`` 93 - Selection rectangle, in pixels. 94 * - __u32 95 - ``reserved``\ [8] 96 - Reserved for future extensions. Applications and drivers must set 97 the array to zero. 98 99 100Return Value 101============ 102 103On success 0 is returned, on error -1 and the ``errno`` variable is set 104appropriately. The generic error codes are described at the 105:ref:`Generic Error Codes <gen-errors>` chapter. 106 107EBUSY 108 The selection rectangle can't be changed because the pad is 109 currently busy. This can be caused, for instance, by an active video 110 stream on the pad. The ioctl must not be retried without performing 111 another action to fix the problem first. Only returned by 112 ``VIDIOC_SUBDEV_S_SELECTION`` 113 114EINVAL 115 The struct :c:type:`v4l2_subdev_selection` 116 ``pad`` references a non-existing pad, the ``which`` field 117 references a non-existing format, or the selection target is not 118 supported on the given subdev pad. 119