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