Documentation/userspace-api/media/v4l/vidioc-subdev-g-selection.rst

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