diff options
Diffstat (limited to 'Documentation/media/uapi/v4l/vidioc-g-fmt.rst')
| -rw-r--r-- | Documentation/media/uapi/v4l/vidioc-g-fmt.rst | 153 |
1 files changed, 57 insertions, 96 deletions
diff --git a/Documentation/media/uapi/v4l/vidioc-g-fmt.rst b/Documentation/media/uapi/v4l/vidioc-g-fmt.rst index ee6f11978fd6..b853e48312e2 100644 --- a/Documentation/media/uapi/v4l/vidioc-g-fmt.rst +++ b/Documentation/media/uapi/v4l/vidioc-g-fmt.rst @@ -15,8 +15,14 @@ VIDIOC_G_FMT - VIDIOC_S_FMT - VIDIOC_TRY_FMT - Get or set the data format, try a Synopsis ======== -.. cpp:function:: int ioctl( int fd, int request, struct v4l2_format *argp ) +.. 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 ========= @@ -24,9 +30,6 @@ Arguments ``fd`` File descriptor returned by :ref:`open() <func-open>`. -``request`` - VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT - ``argp`` @@ -37,15 +40,15 @@ 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 :ref:`struct v4l2_format <v4l2-format>` to the respective buffer (stream) +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 -:ref:`v4l2_pix_format <v4l2-pix-format>` ``pix`` or the struct -:ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` ``pix_mp`` +: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. @@ -55,7 +58,7 @@ 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 :ref:`struct v4l2_format <v4l2-format>` structure the driver +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 @@ -82,98 +85,56 @@ The format as returned by :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` must be identical :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` returns for the same input or output. -.. _v4l2-format: +.. c:type:: v4l2_format + +.. tabularcolumns:: |p{1.2cm}|p{4.3cm}|p{3.0cm}|p{9.0cm}| .. flat-table:: struct v4l2_format :header-rows: 0 :stub-columns: 0 - - - .. row 1 - - - __u32 - - - ``type`` - - - - - Type of the data stream, see :ref:`v4l2-buf-type`. - - - .. row 2 - - - union - - - ``fmt`` - - - .. row 3 - - - - - struct :ref:`v4l2_pix_format <v4l2-pix-format>` - - - ``pix`` - - - Definition of an image format, see :ref:`pixfmt`, used by video - capture and output devices. - - - .. row 4 - - - - - struct :ref:`v4l2_pix_format_mplane <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>`. - - - .. row 5 - - - - - struct :ref:`v4l2_window <v4l2-window>` - - - ``win`` - - - Definition of an overlaid image, see :ref:`overlay`, used by - video overlay devices. - - - .. row 6 - - - - - struct :ref:`v4l2_vbi_format <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. - - - .. row 7 - - - - - struct :ref:`v4l2_sliced_vbi_format <v4l2-sliced-vbi-format>` - - - ``sliced`` - - - Sliced VBI capture or output parameters. See :ref:`sliced` for - details. Used by sliced VBI capture and output devices. - - - .. row 8 - - - - - struct :ref:`v4l2_sdr_format <v4l2-sdr-format>` - - - ``sdr`` - - - Definition of a data format, see :ref:`pixfmt`, used by SDR - capture and output devices. - - - .. row 9 - - - - - __u8 - - - ``raw_data``\ [200] - - - Place holder for future extensions. + * - __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. + * - + - __u8 + - ``raw_data``\ [200] + - Place holder for future extensions. Return Value @@ -184,5 +145,5 @@ appropriately. The generic error codes are described at the :ref:`Generic Error Codes <gen-errors>` chapter. EINVAL - The struct :ref:`v4l2_format <v4l2-format>` ``type`` field is + The struct :c:type:`v4l2_format` ``type`` field is invalid or the requested buffer type not supported. |