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

   1 .. Permission is granted to copy, distribute and/or modify this
   2 .. document under the terms of the GNU Free Documentation License,
   3 .. Version 1.1 or any later version published by the Free Software
   4 .. Foundation, with no Invariant Sections, no Front-Cover Texts
   5 .. and no Back-Cover Texts. A copy of the license is included at
   6 .. Documentation/userspace-api/media/fdl-appendix.rst.
   7 ..
   8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
   9
  10 .. _VIDIOC_SUBDEV_G_FMT:
  11
  12 **********************************************
  13 ioctl VIDIOC_SUBDEV_G_FMT, VIDIOC_SUBDEV_S_FMT
  14 **********************************************
  15
  16 Name
  17 ====
  18
  19 VIDIOC_SUBDEV_G_FMT - VIDIOC_SUBDEV_S_FMT - Get or set the data format on a subdev pad
  20
  21
  22 Synopsis
  23 ========
  24
  25 .. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_G_FMT, struct v4l2_subdev_format *argp )
  26     :name: VIDIOC_SUBDEV_G_FMT
  27
  28 .. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_S_FMT, struct v4l2_subdev_format *argp )
  29     :name: VIDIOC_SUBDEV_S_FMT
  30
  31
  32 Arguments
  33 =========
  34
  35 ``fd``
  36     File descriptor returned by :ref:`open() <func-open>`.
  37
  38 ``argp``
  39     Pointer to struct :c:type:`v4l2_subdev_format`.
  40
  41
  42 Description
  43 ===========
  44
  45 These ioctls are used to negotiate the frame format at specific subdev
  46 pads in the image pipeline.
  47
  48 To retrieve the current format applications set the ``pad`` field of a
  49 struct :c:type:`v4l2_subdev_format` to the desired
  50 pad number as reported by the media API and the ``which`` field to
  51 ``V4L2_SUBDEV_FORMAT_ACTIVE``. When they call the
  52 ``VIDIOC_SUBDEV_G_FMT`` ioctl with a pointer to this structure the
  53 driver fills the members of the ``format`` field.
  54
  55 To change the current format applications set both the ``pad`` and
  56 ``which`` fields and all members of the ``format`` field. When they call
  57 the ``VIDIOC_SUBDEV_S_FMT`` ioctl with a pointer to this structure the
  58 driver verifies the requested format, adjusts it based on the hardware
  59 capabilities and configures the device. Upon return the struct
  60 :c:type:`v4l2_subdev_format` contains the current
  61 format as would be returned by a ``VIDIOC_SUBDEV_G_FMT`` call.
  62
  63 Applications can query the device capabilities by setting the ``which``
  64 to ``V4L2_SUBDEV_FORMAT_TRY``. When set, 'try' formats are not applied
  65 to the device by the driver, but are changed exactly as active formats
  66 and stored in the sub-device file handle. Two applications querying the
  67 same sub-device would thus not interact with each other.
  68
  69 For instance, to try a format at the output pad of a sub-device,
  70 applications would first set the try format at the sub-device input with
  71 the ``VIDIOC_SUBDEV_S_FMT`` ioctl. They would then either retrieve the
  72 default format at the output pad with the ``VIDIOC_SUBDEV_G_FMT`` ioctl,
  73 or set the desired output pad format with the ``VIDIOC_SUBDEV_S_FMT``
  74 ioctl and check the returned value.
  75
  76 Try formats do not depend on active formats, but can depend on the
  77 current links configuration or sub-device controls value. For instance,
  78 a low-pass noise filter might crop pixels at the frame boundaries,
  79 modifying its output frame size.
  80
  81 If the subdev device node has been registered in read-only mode, calls to
  82 ``VIDIOC_SUBDEV_S_FMT`` are only valid if the ``which`` field is set to
  83 ``V4L2_SUBDEV_FORMAT_TRY``, otherwise an error is returned and the errno
  84 variable is set to ``-EPERM``.
  85
  86 Drivers must not return an error solely because the requested format
  87 doesn't match the device capabilities. They must instead modify the
  88 format to match what the hardware can provide. The modified format
  89 should be as close as possible to the original request.
  90
  91
  92 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
  93
  94 .. c:type:: v4l2_subdev_format
  95
  96 .. flat-table:: struct v4l2_subdev_format
  97     :header-rows:  0
  98     :stub-columns: 0
  99     :widths:       1 1 2
 100
 101     * - __u32
 102       - ``pad``
 103       - Pad number as reported by the media controller API.
 104     * - __u32
 105       - ``which``
 106       - Format to modified, from enum
 107         :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
 108     * - struct :c:type:`v4l2_mbus_framefmt`
 109       - ``format``
 110       - Definition of an image format, see :c:type:`v4l2_mbus_framefmt` for
 111         details.
 112     * - __u32
 113       - ``reserved``\ [8]
 114       - Reserved for future extensions. Applications and drivers must set
 115         the array to zero.
 116
 117
 118
 119 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 120
 121 .. _v4l2-subdev-format-whence:
 122
 123 .. flat-table:: enum v4l2_subdev_format_whence
 124     :header-rows:  0
 125     :stub-columns: 0
 126     :widths:       3 1 4
 127
 128     * - V4L2_SUBDEV_FORMAT_TRY
 129       - 0
 130       - Try formats, used for querying device capabilities.
 131     * - V4L2_SUBDEV_FORMAT_ACTIVE
 132       - 1
 133       - Active formats, applied to the hardware.
 134
 135
 136 Return Value
 137 ============
 138
 139 On success 0 is returned, on error -1 and the ``errno`` variable is set
 140 appropriately. The generic error codes are described at the
 141 :ref:`Generic Error Codes <gen-errors>` chapter.
 142
 143 EBUSY
 144     The format can't be changed because the pad is currently busy. This
 145     can be caused, for instance, by an active video stream on the pad.
 146     The ioctl must not be retried without performing another action to
 147     fix the problem first. Only returned by ``VIDIOC_SUBDEV_S_FMT``
 148
 149 EINVAL
 150     The struct :c:type:`v4l2_subdev_format`
 151     ``pad`` references a non-existing pad, or the ``which`` field
 152     references a non-existing format.
 153
 154 EPERM
 155     The ``VIDIOC_SUBDEV_S_FMT`` ioctl has been called on a read-only subdevice
 156     and the ``which`` field is set to ``V4L2_SUBDEV_FORMAT_ACTIVE``.
 157
 158 ============
 159
 160 On success 0 is returned, on error -1 and the ``errno`` variable is set
 161 appropriately. The generic error codes are described at the
 162 :ref:`Generic Error Codes <gen-errors>` chapter.