summaryrefslogtreecommitdiffstats
path: root/Documentation/media/uapi/v4l/vidioc-g-fmt.rst
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/media/uapi/v4l/vidioc-g-fmt.rst')
-rw-r--r--Documentation/media/uapi/v4l/vidioc-g-fmt.rst161
1 files changed, 0 insertions, 161 deletions
diff --git a/Documentation/media/uapi/v4l/vidioc-g-fmt.rst b/Documentation/media/uapi/v4l/vidioc-g-fmt.rst
deleted file mode 100644
index 1e69bfc46e8d..000000000000
--- a/Documentation/media/uapi/v4l/vidioc-g-fmt.rst
+++ /dev/null
@@ -1,161 +0,0 @@
-.. Permission is granted to copy, distribute and/or modify this
-.. document under the terms of the GNU Free Documentation License,
-.. Version 1.1 or any later version published by the Free Software
-.. Foundation, with no Invariant Sections, no Front-Cover Texts
-.. and no Back-Cover Texts. A copy of the license is included at
-.. Documentation/media/uapi/fdl-appendix.rst.
-..
-.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
-
-.. _VIDIOC_G_FMT:
-
-************************************************
-ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT
-************************************************
-
-Name
-====
-
-VIDIOC_G_FMT - VIDIOC_S_FMT - VIDIOC_TRY_FMT - Get or set the data format, try a format
-
-
-Synopsis
-========
-
-.. c:function:: int ioctl( int fd, VIDIOC_G_FMT, struct v4l2_format *argp )
- :name: VIDIOC_G_FMT
-
-.. c:function:: int ioctl( int fd, VIDIOC_S_FMT, struct v4l2_format *argp )
- :name: VIDIOC_S_FMT
-
-.. c:function:: int ioctl( int fd, VIDIOC_TRY_FMT, struct v4l2_format *argp )
- :name: VIDIOC_TRY_FMT
-
-Arguments
-=========
-
-``fd``
- File descriptor returned by :ref:`open() <func-open>`.
-
-``argp``
- Pointer to struct :c:type:`v4l2_format`.
-
-
-Description
-===========
-
-These ioctls are used to negotiate the format of data (typically image
-format) exchanged between driver and application.
-
-To query the current parameters applications set the ``type`` field of a
-struct :c:type:`v4l2_format` to the respective buffer (stream)
-type. For example video capture devices use
-``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or
-``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``. When the application calls the
-:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl with a pointer to this structure the driver fills
-the respective member of the ``fmt`` union. In case of video capture
-devices that is either the struct
-:c:type:`v4l2_pix_format` ``pix`` or the struct
-:c:type:`v4l2_pix_format_mplane` ``pix_mp``
-member. When the requested buffer type is not supported drivers return
-an ``EINVAL`` error code.
-
-To change the current format parameters applications initialize the
-``type`` field and all fields of the respective ``fmt`` union member.
-For details see the documentation of the various devices types in
-:ref:`devices`. Good practice is to query the current parameters
-first, and to modify only those parameters not suitable for the
-application. When the application calls the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with
-a pointer to a struct :c:type:`v4l2_format` structure the driver
-checks and adjusts the parameters against hardware abilities. Drivers
-should not return an error code unless the ``type`` field is invalid,
-this is a mechanism to fathom device capabilities and to approach
-parameters acceptable for both the application and driver. On success
-the driver may program the hardware, allocate resources and generally
-prepare for data exchange. Finally the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl returns
-the current format parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. Very simple,
-inflexible devices may even ignore all input and always return the
-default parameters. However all V4L2 devices exchanging data with the
-application must implement the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
-ioctl. When the requested buffer type is not supported drivers return an
-EINVAL error code on a :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` attempt. When I/O is already in
-progress or the resource is not available for other reasons drivers
-return the ``EBUSY`` error code.
-
-The :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl is equivalent to :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` with one
-exception: it does not change driver state. It can also be called at any
-time, never returning ``EBUSY``. This function is provided to negotiate
-parameters, to learn about hardware limitations, without disabling I/O
-or possibly time consuming hardware preparations. Although strongly
-recommended drivers are not required to implement this ioctl.
-
-The format as returned by :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` must be identical to what
-:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` returns for the same input or output.
-
-
-.. c:type:: v4l2_format
-
-.. tabularcolumns:: |p{1.2cm}|p{4.6cm}|p{3.0cm}|p{8.6cm}|
-
-.. flat-table:: struct v4l2_format
- :header-rows: 0
- :stub-columns: 0
-
- * - __u32
- - ``type``
- - Type of the data stream, see :c:type:`v4l2_buf_type`.
- * - union {
- - ``fmt``
- * - struct :c:type:`v4l2_pix_format`
- - ``pix``
- - Definition of an image format, see :ref:`pixfmt`, used by video
- capture and output devices.
- * - struct :c:type:`v4l2_pix_format_mplane`
- - ``pix_mp``
- - Definition of an image format, see :ref:`pixfmt`, used by video
- capture and output devices that support the
- :ref:`multi-planar version of the API <planar-apis>`.
- * - struct :c:type:`v4l2_window`
- - ``win``
- - Definition of an overlaid image, see :ref:`overlay`, used by
- video overlay devices.
- * - struct :c:type:`v4l2_vbi_format`
- - ``vbi``
- - Raw VBI capture or output parameters. This is discussed in more
- detail in :ref:`raw-vbi`. Used by raw VBI capture and output
- devices.
- * - struct :c:type:`v4l2_sliced_vbi_format`
- - ``sliced``
- - Sliced VBI capture or output parameters. See :ref:`sliced` for
- details. Used by sliced VBI capture and output devices.
- * - struct :c:type:`v4l2_sdr_format`
- - ``sdr``
- - Definition of a data format, see :ref:`pixfmt`, used by SDR
- capture and output devices.
- * - struct :c:type:`v4l2_meta_format`
- - ``meta``
- - Definition of a metadata format, see :ref:`meta-formats`, used by
- metadata capture devices.
- * - __u8
- - ``raw_data``\ [200]
- - Place holder for future extensions.
- * - }
- -
-
-
-Return Value
-============
-
-On success 0 is returned, on error -1 and the ``errno`` variable is set
-appropriately. The generic error codes are described at the
-:ref:`Generic Error Codes <gen-errors>` chapter.
-
-EINVAL
- The struct :c:type:`v4l2_format` ``type`` field is
- invalid or the requested buffer type not supported.
-
-EBUSY
- The device is busy and cannot change the format. This could be
- because or the device is streaming or buffers are allocated or
- queued to the driver. Relevant for :ref:`VIDIOC_S_FMT
- <VIDIOC_G_FMT>` only.