1059b1c5bSMauro Carvalho Chehab.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2407e84cdSMauro Carvalho Chehab.. c:namespace:: V4L 354f38fcaSMauro Carvalho Chehab 454f38fcaSMauro Carvalho Chehab.. _VIDIOC_G_FMT: 554f38fcaSMauro Carvalho Chehab 654f38fcaSMauro Carvalho Chehab************************************************ 754f38fcaSMauro Carvalho Chehabioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT 854f38fcaSMauro Carvalho Chehab************************************************ 954f38fcaSMauro Carvalho Chehab 1054f38fcaSMauro Carvalho ChehabName 1154f38fcaSMauro Carvalho Chehab==== 1254f38fcaSMauro Carvalho Chehab 1354f38fcaSMauro Carvalho ChehabVIDIOC_G_FMT - VIDIOC_S_FMT - VIDIOC_TRY_FMT - Get or set the data format, try a format 1454f38fcaSMauro Carvalho Chehab 1554f38fcaSMauro Carvalho ChehabSynopsis 1654f38fcaSMauro Carvalho Chehab======== 1754f38fcaSMauro Carvalho Chehab 18407e84cdSMauro Carvalho Chehab.. c:macro:: VIDIOC_G_FMT 1954f38fcaSMauro Carvalho Chehab 20407e84cdSMauro Carvalho Chehab``int ioctl(int fd, VIDIOC_G_FMT, struct v4l2_format *argp)`` 2154f38fcaSMauro Carvalho Chehab 22407e84cdSMauro Carvalho Chehab.. c:macro:: VIDIOC_S_FMT 23407e84cdSMauro Carvalho Chehab 24407e84cdSMauro Carvalho Chehab``int ioctl(int fd, VIDIOC_S_FMT, struct v4l2_format *argp)`` 25407e84cdSMauro Carvalho Chehab 26407e84cdSMauro Carvalho Chehab.. c:macro:: VIDIOC_TRY_FMT 27407e84cdSMauro Carvalho Chehab 28407e84cdSMauro Carvalho Chehab``int ioctl(int fd, VIDIOC_TRY_FMT, struct v4l2_format *argp)`` 2954f38fcaSMauro Carvalho Chehab 3054f38fcaSMauro Carvalho ChehabArguments 3154f38fcaSMauro Carvalho Chehab========= 3254f38fcaSMauro Carvalho Chehab 3354f38fcaSMauro Carvalho Chehab``fd`` 34407e84cdSMauro Carvalho Chehab File descriptor returned by :c:func:`open()`. 3554f38fcaSMauro Carvalho Chehab 3654f38fcaSMauro Carvalho Chehab``argp`` 3754f38fcaSMauro Carvalho Chehab Pointer to struct :c:type:`v4l2_format`. 3854f38fcaSMauro Carvalho Chehab 3954f38fcaSMauro Carvalho ChehabDescription 4054f38fcaSMauro Carvalho Chehab=========== 4154f38fcaSMauro Carvalho Chehab 4254f38fcaSMauro Carvalho ChehabThese ioctls are used to negotiate the format of data (typically image 4354f38fcaSMauro Carvalho Chehabformat) exchanged between driver and application. 4454f38fcaSMauro Carvalho Chehab 4554f38fcaSMauro Carvalho ChehabTo query the current parameters applications set the ``type`` field of a 4654f38fcaSMauro Carvalho Chehabstruct :c:type:`v4l2_format` to the respective buffer (stream) 4754f38fcaSMauro Carvalho Chehabtype. For example video capture devices use 4854f38fcaSMauro Carvalho Chehab``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or 4954f38fcaSMauro Carvalho Chehab``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``. When the application calls the 5054f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl with a pointer to this structure the driver fills 5154f38fcaSMauro Carvalho Chehabthe respective member of the ``fmt`` union. In case of video capture 5254f38fcaSMauro Carvalho Chehabdevices that is either the struct 5354f38fcaSMauro Carvalho Chehab:c:type:`v4l2_pix_format` ``pix`` or the struct 5454f38fcaSMauro Carvalho Chehab:c:type:`v4l2_pix_format_mplane` ``pix_mp`` 5554f38fcaSMauro Carvalho Chehabmember. When the requested buffer type is not supported drivers return 5654f38fcaSMauro Carvalho Chehaban ``EINVAL`` error code. 5754f38fcaSMauro Carvalho Chehab 5854f38fcaSMauro Carvalho ChehabTo change the current format parameters applications initialize the 5954f38fcaSMauro Carvalho Chehab``type`` field and all fields of the respective ``fmt`` union member. 6054f38fcaSMauro Carvalho ChehabFor details see the documentation of the various devices types in 6154f38fcaSMauro Carvalho Chehab:ref:`devices`. Good practice is to query the current parameters 6254f38fcaSMauro Carvalho Chehabfirst, and to modify only those parameters not suitable for the 6354f38fcaSMauro Carvalho Chehabapplication. When the application calls the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with 6454f38fcaSMauro Carvalho Chehaba pointer to a struct :c:type:`v4l2_format` structure the driver 6554f38fcaSMauro Carvalho Chehabchecks and adjusts the parameters against hardware abilities. Drivers 6654f38fcaSMauro Carvalho Chehabshould not return an error code unless the ``type`` field is invalid, 6754f38fcaSMauro Carvalho Chehabthis is a mechanism to fathom device capabilities and to approach 6854f38fcaSMauro Carvalho Chehabparameters acceptable for both the application and driver. On success 6954f38fcaSMauro Carvalho Chehabthe driver may program the hardware, allocate resources and generally 7054f38fcaSMauro Carvalho Chehabprepare for data exchange. Finally the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl returns 7154f38fcaSMauro Carvalho Chehabthe current format parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. Very simple, 7254f38fcaSMauro Carvalho Chehabinflexible devices may even ignore all input and always return the 7354f38fcaSMauro Carvalho Chehabdefault parameters. However all V4L2 devices exchanging data with the 7454f38fcaSMauro Carvalho Chehabapplication must implement the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` 7554f38fcaSMauro Carvalho Chehabioctl. When the requested buffer type is not supported drivers return an 7654f38fcaSMauro Carvalho ChehabEINVAL error code on a :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` attempt. When I/O is already in 7754f38fcaSMauro Carvalho Chehabprogress or the resource is not available for other reasons drivers 7854f38fcaSMauro Carvalho Chehabreturn the ``EBUSY`` error code. 7954f38fcaSMauro Carvalho Chehab 8054f38fcaSMauro Carvalho ChehabThe :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl is equivalent to :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` with one 8154f38fcaSMauro Carvalho Chehabexception: it does not change driver state. It can also be called at any 8254f38fcaSMauro Carvalho Chehabtime, never returning ``EBUSY``. This function is provided to negotiate 8354f38fcaSMauro Carvalho Chehabparameters, to learn about hardware limitations, without disabling I/O 8454f38fcaSMauro Carvalho Chehabor possibly time consuming hardware preparations. Although strongly 8554f38fcaSMauro Carvalho Chehabrecommended drivers are not required to implement this ioctl. 8654f38fcaSMauro Carvalho Chehab 8754f38fcaSMauro Carvalho ChehabThe format as returned by :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` must be identical to what 8854f38fcaSMauro Carvalho Chehab:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` returns for the same input or output. 8954f38fcaSMauro Carvalho Chehab 9054f38fcaSMauro Carvalho Chehab.. c:type:: v4l2_format 9154f38fcaSMauro Carvalho Chehab 92*fea13a69SMauro Carvalho Chehab.. tabularcolumns:: |p{7.4cm}|p{4.4cm}|p{5.5cm}| 9354f38fcaSMauro Carvalho Chehab 9454f38fcaSMauro Carvalho Chehab.. flat-table:: struct v4l2_format 9554f38fcaSMauro Carvalho Chehab :header-rows: 0 9654f38fcaSMauro Carvalho Chehab :stub-columns: 0 9754f38fcaSMauro Carvalho Chehab 9854f38fcaSMauro Carvalho Chehab * - __u32 9954f38fcaSMauro Carvalho Chehab - ``type`` 10054f38fcaSMauro Carvalho Chehab - Type of the data stream, see :c:type:`v4l2_buf_type`. 10154f38fcaSMauro Carvalho Chehab * - union { 10254f38fcaSMauro Carvalho Chehab - ``fmt`` 10354f38fcaSMauro Carvalho Chehab * - struct :c:type:`v4l2_pix_format` 10454f38fcaSMauro Carvalho Chehab - ``pix`` 10554f38fcaSMauro Carvalho Chehab - Definition of an image format, see :ref:`pixfmt`, used by video 10654f38fcaSMauro Carvalho Chehab capture and output devices. 10754f38fcaSMauro Carvalho Chehab * - struct :c:type:`v4l2_pix_format_mplane` 10854f38fcaSMauro Carvalho Chehab - ``pix_mp`` 10954f38fcaSMauro Carvalho Chehab - Definition of an image format, see :ref:`pixfmt`, used by video 11054f38fcaSMauro Carvalho Chehab capture and output devices that support the 11154f38fcaSMauro Carvalho Chehab :ref:`multi-planar version of the API <planar-apis>`. 11254f38fcaSMauro Carvalho Chehab * - struct :c:type:`v4l2_window` 11354f38fcaSMauro Carvalho Chehab - ``win`` 11454f38fcaSMauro Carvalho Chehab - Definition of an overlaid image, see :ref:`overlay`, used by 11554f38fcaSMauro Carvalho Chehab video overlay devices. 11654f38fcaSMauro Carvalho Chehab * - struct :c:type:`v4l2_vbi_format` 11754f38fcaSMauro Carvalho Chehab - ``vbi`` 11854f38fcaSMauro Carvalho Chehab - Raw VBI capture or output parameters. This is discussed in more 11954f38fcaSMauro Carvalho Chehab detail in :ref:`raw-vbi`. Used by raw VBI capture and output 12054f38fcaSMauro Carvalho Chehab devices. 12154f38fcaSMauro Carvalho Chehab * - struct :c:type:`v4l2_sliced_vbi_format` 12254f38fcaSMauro Carvalho Chehab - ``sliced`` 12354f38fcaSMauro Carvalho Chehab - Sliced VBI capture or output parameters. See :ref:`sliced` for 12454f38fcaSMauro Carvalho Chehab details. Used by sliced VBI capture and output devices. 12554f38fcaSMauro Carvalho Chehab * - struct :c:type:`v4l2_sdr_format` 12654f38fcaSMauro Carvalho Chehab - ``sdr`` 12754f38fcaSMauro Carvalho Chehab - Definition of a data format, see :ref:`pixfmt`, used by SDR 12854f38fcaSMauro Carvalho Chehab capture and output devices. 12954f38fcaSMauro Carvalho Chehab * - struct :c:type:`v4l2_meta_format` 13054f38fcaSMauro Carvalho Chehab - ``meta`` 13154f38fcaSMauro Carvalho Chehab - Definition of a metadata format, see :ref:`meta-formats`, used by 13254f38fcaSMauro Carvalho Chehab metadata capture devices. 13354f38fcaSMauro Carvalho Chehab * - __u8 13454f38fcaSMauro Carvalho Chehab - ``raw_data``\ [200] 13554f38fcaSMauro Carvalho Chehab - Place holder for future extensions. 13654f38fcaSMauro Carvalho Chehab * - } 13754f38fcaSMauro Carvalho Chehab - 13854f38fcaSMauro Carvalho Chehab 13954f38fcaSMauro Carvalho ChehabReturn Value 14054f38fcaSMauro Carvalho Chehab============ 14154f38fcaSMauro Carvalho Chehab 14254f38fcaSMauro Carvalho ChehabOn success 0 is returned, on error -1 and the ``errno`` variable is set 14354f38fcaSMauro Carvalho Chehabappropriately. The generic error codes are described at the 14454f38fcaSMauro Carvalho Chehab:ref:`Generic Error Codes <gen-errors>` chapter. 14554f38fcaSMauro Carvalho Chehab 14654f38fcaSMauro Carvalho ChehabEINVAL 14754f38fcaSMauro Carvalho Chehab The struct :c:type:`v4l2_format` ``type`` field is 14854f38fcaSMauro Carvalho Chehab invalid or the requested buffer type not supported. 14954f38fcaSMauro Carvalho Chehab 15054f38fcaSMauro Carvalho ChehabEBUSY 15154f38fcaSMauro Carvalho Chehab The device is busy and cannot change the format. This could be 15254f38fcaSMauro Carvalho Chehab because or the device is streaming or buffers are allocated or 15354f38fcaSMauro Carvalho Chehab queued to the driver. Relevant for :ref:`VIDIOC_S_FMT 15454f38fcaSMauro Carvalho Chehab <VIDIOC_G_FMT>` only. 155