^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) .. c:namespace:: V4L
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) .. _VIDIOC_G_FMT:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) ************************************************
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) ************************************************
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) Name
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) ====
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) VIDIOC_G_FMT - VIDIOC_S_FMT - VIDIOC_TRY_FMT - Get or set the data format, try a format
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) Synopsis
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) ========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) .. c:macro:: VIDIOC_G_FMT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) ``int ioctl(int fd, VIDIOC_G_FMT, struct v4l2_format *argp)``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) .. c:macro:: VIDIOC_S_FMT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) ``int ioctl(int fd, VIDIOC_S_FMT, struct v4l2_format *argp)``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) .. c:macro:: VIDIOC_TRY_FMT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) ``int ioctl(int fd, VIDIOC_TRY_FMT, struct v4l2_format *argp)``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) Arguments
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) =========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) ``fd``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) File descriptor returned by :c:func:`open()`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) ``argp``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) Pointer to struct :c:type:`v4l2_format`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) Description
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) ===========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) These ioctls are used to negotiate the format of data (typically image
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) format) exchanged between driver and application.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) To query the current parameters applications set the ``type`` field of a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) struct :c:type:`v4l2_format` to the respective buffer (stream)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) type. For example video capture devices use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``. When the application calls the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl with a pointer to this structure the driver fills
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) the respective member of the ``fmt`` union. In case of video capture
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) devices that is either the struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) :c:type:`v4l2_pix_format` ``pix`` or the struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) :c:type:`v4l2_pix_format_mplane` ``pix_mp``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) member. When the requested buffer type is not supported drivers return
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) an ``EINVAL`` error code.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) To change the current format parameters applications initialize the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) ``type`` field and all fields of the respective ``fmt`` union member.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) For details see the documentation of the various devices types in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) :ref:`devices`. Good practice is to query the current parameters
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) first, and to modify only those parameters not suitable for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) application. When the application calls the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) a pointer to a struct :c:type:`v4l2_format` structure the driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) checks and adjusts the parameters against hardware abilities. Drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) should not return an error code unless the ``type`` field is invalid,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) this is a mechanism to fathom device capabilities and to approach
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) parameters acceptable for both the application and driver. On success
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) the driver may program the hardware, allocate resources and generally
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) prepare for data exchange. Finally the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl returns
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) the current format parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. Very simple,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) inflexible devices may even ignore all input and always return the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) default parameters. However all V4L2 devices exchanging data with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) application must implement the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) ioctl. When the requested buffer type is not supported drivers return an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) EINVAL error code on a :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` attempt. When I/O is already in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) progress or the resource is not available for other reasons drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) return the ``EBUSY`` error code.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) The :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl is equivalent to :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` with one
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) exception: it does not change driver state. It can also be called at any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) time, never returning ``EBUSY``. This function is provided to negotiate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) parameters, to learn about hardware limitations, without disabling I/O
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) or possibly time consuming hardware preparations. Although strongly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) recommended drivers are not required to implement this ioctl.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) The format as returned by :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` must be identical to what
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` returns for the same input or output.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) .. c:type:: v4l2_format
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) .. tabularcolumns:: |p{1.2cm}|p{4.6cm}|p{3.0cm}|p{8.6cm}|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) .. flat-table:: struct v4l2_format
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) :header-rows: 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) :stub-columns: 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) * - __u32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) - ``type``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) - Type of the data stream, see :c:type:`v4l2_buf_type`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) * - union {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) - ``fmt``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) * - struct :c:type:`v4l2_pix_format`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) - ``pix``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) - Definition of an image format, see :ref:`pixfmt`, used by video
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) capture and output devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) * - struct :c:type:`v4l2_pix_format_mplane`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) - ``pix_mp``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) - Definition of an image format, see :ref:`pixfmt`, used by video
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) capture and output devices that support the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) :ref:`multi-planar version of the API <planar-apis>`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) * - struct :c:type:`v4l2_window`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) - ``win``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) - Definition of an overlaid image, see :ref:`overlay`, used by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) video overlay devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) * - struct :c:type:`v4l2_vbi_format`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) - ``vbi``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) - Raw VBI capture or output parameters. This is discussed in more
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) detail in :ref:`raw-vbi`. Used by raw VBI capture and output
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) * - struct :c:type:`v4l2_sliced_vbi_format`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) - ``sliced``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) - Sliced VBI capture or output parameters. See :ref:`sliced` for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) details. Used by sliced VBI capture and output devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) * - struct :c:type:`v4l2_sdr_format`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) - ``sdr``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) - Definition of a data format, see :ref:`pixfmt`, used by SDR
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) capture and output devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) * - struct :c:type:`v4l2_meta_format`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) - ``meta``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) - Definition of a metadata format, see :ref:`meta-formats`, used by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) metadata capture devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) * - __u8
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) - ``raw_data``\ [200]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) - Place holder for future extensions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) * - }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) -
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) Return Value
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) On success 0 is returned, on error -1 and the ``errno`` variable is set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) appropriately. The generic error codes are described at the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) :ref:`Generic Error Codes <gen-errors>` chapter.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) EINVAL
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) The struct :c:type:`v4l2_format` ``type`` field is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) invalid or the requested buffer type not supported.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) EBUSY
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) The device is busy and cannot change the format. This could be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) because or the device is streaming or buffers are allocated or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) queued to the driver. Relevant for :ref:`VIDIOC_S_FMT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) <VIDIOC_G_FMT>` only.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags