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