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