Documentation/userspace-api/media/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/userspace-api/media/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 If the subdev device node has been registered in read-only mode, calls to
  57 ``VIDIOC_SUBDEV_S_SELECTION`` are only valid if the ``which`` field is set to
  58 ``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
  59 variable is set to ``-EPERM``.
  60
  61 Types of selection targets
  62 --------------------------
  63
  64 There are two types of selection targets: actual and bounds. The actual
  65 targets are the targets which configure the hardware. The BOUNDS target
  66 will return a rectangle that contain all possible actual rectangles.
  67
  68
  69 Discovering supported features
  70 ------------------------------
  71
  72 To discover which targets are supported, the user can perform
  73 ``VIDIOC_SUBDEV_G_SELECTION`` on them. Any unsupported target will
  74 return ``EINVAL``.
  75
  76 Selection targets and flags are documented in
  77 :ref:`v4l2-selections-common`.
  78
  79
  80 .. c:type:: v4l2_subdev_selection
  81
  82 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  83
  84 .. flat-table:: struct v4l2_subdev_selection
  85     :header-rows:  0
  86     :stub-columns: 0
  87     :widths:       1 1 2
  88
  89     * - __u32
  90       - ``which``
  91       - Active or try selection, from enum
  92         :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
  93     * - __u32
  94       - ``pad``
  95       - Pad number as reported by the media framework.
  96     * - __u32
  97       - ``target``
  98       - Target selection rectangle. See :ref:`v4l2-selections-common`.
  99     * - __u32
 100       - ``flags``
 101       - Flags. See :ref:`v4l2-selection-flags`.
 102     * - struct :c:type:`v4l2_rect`
 103       - ``r``
 104       - Selection rectangle, in pixels.
 105     * - __u32
 106       - ``reserved``\ [8]
 107       - Reserved for future extensions. Applications and drivers must set
 108         the array to zero.
 109
 110
 111 Return Value
 112 ============
 113
 114 On success 0 is returned, on error -1 and the ``errno`` variable is set
 115 appropriately. The generic error codes are described at the
 116 :ref:`Generic Error Codes <gen-errors>` chapter.
 117
 118 EBUSY
 119     The selection rectangle can't be changed because the pad is
 120     currently busy. This can be caused, for instance, by an active video
 121     stream on the pad. The ioctl must not be retried without performing
 122     another action to fix the problem first. Only returned by
 123     ``VIDIOC_SUBDEV_S_SELECTION``
 124
 125 EINVAL
 126     The struct :c:type:`v4l2_subdev_selection`
 127     ``pad`` references a non-existing pad, the ``which`` field
 128     references a non-existing format, or the selection target is not
 129     supported on the given subdev pad.
 130
 131 EPERM
 132     The ``VIDIOC_SUBDEV_S_SELECTION`` ioctl has been called on a read-only
 133     subdevice and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.