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