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

   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 Name
  10 ====
  11
  12 VIDIOC_SUBDEV_G_SELECTION - VIDIOC_SUBDEV_S_SELECTION - Get or set selection rectangles on a subdev pad
  13
  14
  15 Synopsis
  16 ========
  17
  18 .. cpp:function:: int ioctl( int fd, int request, struct v4l2_subdev_selection *argp )
  19
  20
  21 Arguments
  22 =========
  23
  24 ``fd``
  25     File descriptor returned by :ref:`open() <func-open>`.
  26
  27 ``request``
  28     VIDIOC_SUBDEV_G_SELECTION, VIDIOC_SUBDEV_S_SELECTION
  29
  30 ``argp``
  31
  32
  33 Description
  34 ===========
  35
  36 The selections are used to configure various image processing
  37 functionality performed by the subdevs which affect the image size. This
  38 currently includes cropping, scaling and composition.
  39
  40 The selection API replaces
  41 :ref:`the old subdev crop API <VIDIOC_SUBDEV_G_CROP>`. All the
  42 function of the crop API, and more, are supported by the selections API.
  43
  44 See :ref:`subdev` for more information on how each selection target
  45 affects the image processing pipeline inside the subdevice.
  46
  47
  48 Types of selection targets
  49 --------------------------
  50
  51 There are two types of selection targets: actual and bounds. The actual
  52 targets are the targets which configure the hardware. The BOUNDS target
  53 will return a rectangle that contain all possible actual rectangles.
  54
  55
  56 Discovering supported features
  57 ------------------------------
  58
  59 To discover which targets are supported, the user can perform
  60 ``VIDIOC_SUBDEV_G_SELECTION`` on them. Any unsupported target will
  61 return ``EINVAL``.
  62
  63 Selection targets and flags are documented in
  64 :ref:`v4l2-selections-common`.
  65
  66
  67 .. _v4l2-subdev-selection:
  68
  69 .. flat-table:: struct v4l2_subdev_selection
  70     :header-rows:  0
  71     :stub-columns: 0
  72     :widths:       1 1 2
  73
  74
  75     -  .. row 1
  76
  77        -  __u32
  78
  79        -  ``which``
  80
  81        -  Active or try selection, from enum
  82           :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
  83
  84     -  .. row 2
  85
  86        -  __u32
  87
  88        -  ``pad``
  89
  90        -  Pad number as reported by the media framework.
  91
  92     -  .. row 3
  93
  94        -  __u32
  95
  96        -  ``target``
  97
  98        -  Target selection rectangle. See :ref:`v4l2-selections-common`.
  99
 100     -  .. row 4
 101
 102        -  __u32
 103
 104        -  ``flags``
 105
 106        -  Flags. See :ref:`v4l2-selection-flags`.
 107
 108     -  .. row 5
 109
 110        -  struct :ref:`v4l2_rect <v4l2-rect>`
 111
 112        -  ``r``
 113
 114        -  Selection rectangle, in pixels.
 115
 116     -  .. row 6
 117
 118        -  __u32
 119
 120        -  ``reserved``\ [8]
 121
 122        -  Reserved for future extensions. Applications and drivers must set
 123           the array to zero.
 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.