Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst

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