Markus Heiser | 5377d91 | 2016-06-30 15:18:56 +0200 | [diff] [blame^] | 1 | .. -*- coding: utf-8; mode: rst -*- |
| 2 | |
| 3 | .. _vidioc-subdev-g-selection: |
| 4 | |
| 5 | ********************************************************** |
| 6 | ioctl VIDIOC_SUBDEV_G_SELECTION, VIDIOC_SUBDEV_S_SELECTION |
| 7 | ********************************************************** |
| 8 | |
| 9 | *man VIDIOC_SUBDEV_G_SELECTION(2)* |
| 10 | |
| 11 | VIDIOC_SUBDEV_S_SELECTION |
| 12 | Get or set selection rectangles on a subdev pad |
| 13 | |
| 14 | |
| 15 | Synopsis |
| 16 | ======== |
| 17 | |
| 18 | .. c:function:: int ioctl( int fd, int request, struct v4l2_subdev_selection *argp ) |
| 19 | |
| 20 | Arguments |
| 21 | ========= |
| 22 | |
| 23 | ``fd`` |
| 24 | File descriptor returned by :ref:`open() <func-open>`. |
| 25 | |
| 26 | ``request`` |
| 27 | VIDIOC_SUBDEV_G_SELECTION, VIDIOC_SUBDEV_S_SELECTION |
| 28 | |
| 29 | ``argp`` |
| 30 | |
| 31 | |
| 32 | Description |
| 33 | =========== |
| 34 | |
| 35 | The selections are used to configure various image processing |
| 36 | functionality performed by the subdevs which affect the image size. This |
| 37 | currently includes cropping, scaling and composition. |
| 38 | |
| 39 | The selection API replaces |
| 40 | :ref:`the old subdev crop API <vidioc-subdev-g-crop>`. All the |
| 41 | function of the crop API, and more, are supported by the selections API. |
| 42 | |
| 43 | See :ref:`subdev` for more information on how each selection target |
| 44 | affects the image processing pipeline inside the subdevice. |
| 45 | |
| 46 | |
| 47 | Types of selection targets |
| 48 | -------------------------- |
| 49 | |
| 50 | There are two types of selection targets: actual and bounds. The actual |
| 51 | targets are the targets which configure the hardware. The BOUNDS target |
| 52 | will return a rectangle that contain all possible actual rectangles. |
| 53 | |
| 54 | |
| 55 | Discovering supported features |
| 56 | ------------------------------ |
| 57 | |
| 58 | To discover which targets are supported, the user can perform |
| 59 | ``VIDIOC_SUBDEV_G_SELECTION`` on them. Any unsupported target will |
| 60 | return ``EINVAL``. |
| 61 | |
| 62 | Selection targets and flags are documented in |
| 63 | :ref:`v4l2-selections-common`. |
| 64 | |
| 65 | |
| 66 | .. _v4l2-subdev-selection: |
| 67 | |
| 68 | .. flat-table:: struct v4l2_subdev_selection |
| 69 | :header-rows: 0 |
| 70 | :stub-columns: 0 |
| 71 | :widths: 1 1 2 |
| 72 | |
| 73 | |
| 74 | - .. row 1 |
| 75 | |
| 76 | - __u32 |
| 77 | |
| 78 | - ``which`` |
| 79 | |
| 80 | - Active or try selection, from enum |
| 81 | :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`. |
| 82 | |
| 83 | - .. row 2 |
| 84 | |
| 85 | - __u32 |
| 86 | |
| 87 | - ``pad`` |
| 88 | |
| 89 | - Pad number as reported by the media framework. |
| 90 | |
| 91 | - .. row 3 |
| 92 | |
| 93 | - __u32 |
| 94 | |
| 95 | - ``target`` |
| 96 | |
| 97 | - Target selection rectangle. See :ref:`v4l2-selections-common`. |
| 98 | |
| 99 | - .. row 4 |
| 100 | |
| 101 | - __u32 |
| 102 | |
| 103 | - ``flags`` |
| 104 | |
| 105 | - Flags. See :ref:`v4l2-selection-flags`. |
| 106 | |
| 107 | - .. row 5 |
| 108 | |
| 109 | - struct :ref:`v4l2_rect <v4l2-rect>` |
| 110 | |
| 111 | - ``r`` |
| 112 | |
| 113 | - Selection rectangle, in pixels. |
| 114 | |
| 115 | - .. row 6 |
| 116 | |
| 117 | - __u32 |
| 118 | |
| 119 | - ``reserved``\ [8] |
| 120 | |
| 121 | - Reserved for future extensions. Applications and drivers must set |
| 122 | the array to zero. |
| 123 | |
| 124 | |
| 125 | |
| 126 | Return Value |
| 127 | ============ |
| 128 | |
| 129 | On success 0 is returned, on error -1 and the ``errno`` variable is set |
| 130 | appropriately. The generic error codes are described at the |
| 131 | :ref:`Generic Error Codes <gen-errors>` chapter. |
| 132 | |
| 133 | EBUSY |
| 134 | The selection rectangle can't be changed because the pad is |
| 135 | currently busy. This can be caused, for instance, by an active video |
| 136 | stream on the pad. The ioctl must not be retried without performing |
| 137 | another action to fix the problem first. Only returned by |
| 138 | ``VIDIOC_SUBDEV_S_SELECTION`` |
| 139 | |
| 140 | EINVAL |
| 141 | The struct :ref:`v4l2_subdev_selection <v4l2-subdev-selection>` |
| 142 | ``pad`` references a non-existing pad, the ``which`` field |
| 143 | references a non-existing format, or the selection target is not |
| 144 | supported on the given subdev pad. |
| 145 | |
| 146 | |
| 147 | .. ------------------------------------------------------------------------------ |
| 148 | .. This file was automatically converted from DocBook-XML with the dbxml |
| 149 | .. library (https://github.com/return42/sphkerneldoc). The origin XML comes |
| 150 | .. from the linux kernel, refer to: |
| 151 | .. |
| 152 | .. * https://github.com/torvalds/linux/tree/master/Documentation/DocBook |
| 153 | .. ------------------------------------------------------------------------------ |