155 lines · plain
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later2.. c:namespace:: V4L3 4.. _VIDIOC_G_FMT:5 6************************************************7ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT8************************************************9 10Name11====12 13VIDIOC_G_FMT - VIDIOC_S_FMT - VIDIOC_TRY_FMT - Get or set the data format, try a format14 15Synopsis16========17 18.. c:macro:: VIDIOC_G_FMT19 20``int ioctl(int fd, VIDIOC_G_FMT, struct v4l2_format *argp)``21 22.. c:macro:: VIDIOC_S_FMT23 24``int ioctl(int fd, VIDIOC_S_FMT, struct v4l2_format *argp)``25 26.. c:macro:: VIDIOC_TRY_FMT27 28``int ioctl(int fd, VIDIOC_TRY_FMT, struct v4l2_format *argp)``29 30Arguments31=========32 33``fd``34 File descriptor returned by :c:func:`open()`.35 36``argp``37 Pointer to struct :c:type:`v4l2_format`.38 39Description40===========41 42These ioctls are used to negotiate the format of data (typically image43format) exchanged between driver and application.44 45To query the current parameters applications set the ``type`` field of a46struct :c:type:`v4l2_format` to the respective buffer (stream)47type. For example video capture devices use48``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or49``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``. When the application calls the50:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl with a pointer to this structure the driver fills51the respective member of the ``fmt`` union. In case of video capture52devices that is either the struct53:c:type:`v4l2_pix_format` ``pix`` or the struct54:c:type:`v4l2_pix_format_mplane` ``pix_mp``55member. When the requested buffer type is not supported drivers return56an ``EINVAL`` error code.57 58To change the current format parameters applications initialize the59``type`` field and all fields of the respective ``fmt`` union member.60For details see the documentation of the various devices types in61:ref:`devices`. Good practice is to query the current parameters62first, and to modify only those parameters not suitable for the63application. When the application calls the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with64a pointer to a struct :c:type:`v4l2_format` structure the driver65checks and adjusts the parameters against hardware abilities. Drivers66should not return an error code unless the ``type`` field is invalid,67this is a mechanism to fathom device capabilities and to approach68parameters acceptable for both the application and driver. On success69the driver may program the hardware, allocate resources and generally70prepare for data exchange. Finally the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl returns71the current format parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. Very simple,72inflexible devices may even ignore all input and always return the73default parameters. However all V4L2 devices exchanging data with the74application must implement the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`75ioctl. When the requested buffer type is not supported drivers return an76EINVAL error code on a :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` attempt. When I/O is already in77progress or the resource is not available for other reasons drivers78return the ``EBUSY`` error code.79 80The :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl is equivalent to :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` with one81exception: it does not change driver state. It can also be called at any82time, never returning ``EBUSY``. This function is provided to negotiate83parameters, to learn about hardware limitations, without disabling I/O84or possibly time consuming hardware preparations. Although strongly85recommended drivers are not required to implement this ioctl.86 87The format as returned by :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` must be identical to what88:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` returns for the same input or output.89 90.. c:type:: v4l2_format91 92.. tabularcolumns:: |p{7.4cm}|p{4.4cm}|p{5.5cm}|93 94.. flat-table:: struct v4l2_format95 :header-rows: 096 :stub-columns: 097 98 * - __u3299 - ``type``100 - Type of the data stream, see :c:type:`v4l2_buf_type`.101 * - union {102 - ``fmt``103 * - struct :c:type:`v4l2_pix_format`104 - ``pix``105 - Definition of an image format, see :ref:`pixfmt`, used by video106 capture and output devices.107 * - struct :c:type:`v4l2_pix_format_mplane`108 - ``pix_mp``109 - Definition of an image format, see :ref:`pixfmt`, used by video110 capture and output devices that support the111 :ref:`multi-planar version of the API <planar-apis>`.112 * - struct :c:type:`v4l2_window`113 - ``win``114 - Definition of an overlaid image, see :ref:`overlay`, used by115 video overlay devices.116 * - struct :c:type:`v4l2_vbi_format`117 - ``vbi``118 - Raw VBI capture or output parameters. This is discussed in more119 detail in :ref:`raw-vbi`. Used by raw VBI capture and output120 devices.121 * - struct :c:type:`v4l2_sliced_vbi_format`122 - ``sliced``123 - Sliced VBI capture or output parameters. See :ref:`sliced` for124 details. Used by sliced VBI capture and output devices.125 * - struct :c:type:`v4l2_sdr_format`126 - ``sdr``127 - Definition of a data format, see :ref:`pixfmt`, used by SDR128 capture and output devices.129 * - struct :c:type:`v4l2_meta_format`130 - ``meta``131 - Definition of a metadata format, see :ref:`meta-formats`, used by132 metadata capture devices.133 * - __u8134 - ``raw_data``\ [200]135 - Place holder for future extensions.136 * - }137 -138 139Return Value140============141 142On success 0 is returned, on error -1 and the ``errno`` variable is set143appropriately. The generic error codes are described at the144:ref:`Generic Error Codes <gen-errors>` chapter.145 146EINVAL147 The struct :c:type:`v4l2_format` ``type`` field is148 invalid or the requested buffer type not supported.149 150EBUSY151 The device is busy and cannot change the format. This could be152 because or the device is streaming or buffers are allocated or153 queued to the driver. Relevant for :ref:`VIDIOC_S_FMT154 <VIDIOC_G_FMT>` only.155