diff options
Diffstat (limited to 'Documentation/media/uapi/v4l/pixfmt-v4l2.rst')
| -rw-r--r-- | Documentation/media/uapi/v4l/pixfmt-v4l2.rst | 138 |
1 files changed, 138 insertions, 0 deletions
diff --git a/Documentation/media/uapi/v4l/pixfmt-v4l2.rst b/Documentation/media/uapi/v4l/pixfmt-v4l2.rst new file mode 100644 index 000000000000..2ee164c25637 --- /dev/null +++ b/Documentation/media/uapi/v4l/pixfmt-v4l2.rst @@ -0,0 +1,138 @@ +.. -*- coding: utf-8; mode: rst -*- + +****************************** +Single-planar format structure +****************************** + +.. tabularcolumns:: |p{4.0cm}|p{2.5cm}|p{11.0cm}| + +.. c:type:: v4l2_pix_format + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_pix_format + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u32 + - ``width`` + - Image width in pixels. + * - __u32 + - ``height`` + - Image height in pixels. If ``field`` is one of ``V4L2_FIELD_TOP``, + ``V4L2_FIELD_BOTTOM`` or ``V4L2_FIELD_ALTERNATE`` then height + refers to the number of lines in the field, otherwise it refers to + the number of lines in the frame (which is twice the field height + for interlaced formats). + * - :cspan:`2` Applications set these fields to request an image + size, drivers return the closest possible values. In case of + planar formats the ``width`` and ``height`` applies to the largest + plane. To avoid ambiguities drivers must return values rounded up + to a multiple of the scale factor of any smaller planes. For + example when the image format is YUV 4:2:0, ``width`` and + ``height`` must be multiples of two. + * - __u32 + - ``pixelformat`` + - The pixel format or type of compression, set by the application. + This is a little endian + :ref:`four character code <v4l2-fourcc>`. V4L2 defines standard + RGB formats in :ref:`rgb-formats`, YUV formats in + :ref:`yuv-formats`, and reserved codes in + :ref:`reserved-formats` + * - enum :c:type::`v4l2_field` + - ``field`` + - Video images are typically interlaced. Applications can request to + capture or output only the top or bottom field, or both fields + interlaced or sequentially stored in one buffer or alternating in + separate buffers. Drivers return the actual field order selected. + For more details on fields see :ref:`field-order`. + * - __u32 + - ``bytesperline`` + - Distance in bytes between the leftmost pixels in two adjacent + lines. + * - :cspan:`2` + + Both applications and drivers can set this field to request + padding bytes at the end of each line. Drivers however may ignore + the value requested by the application, returning ``width`` times + bytes per pixel or a larger value required by the hardware. That + implies applications can just set this field to zero to get a + reasonable default. + + Video hardware may access padding bytes, therefore they must + reside in accessible memory. Consider cases where padding bytes + after the last line of an image cross a system page boundary. + Input devices may write padding bytes, the value is undefined. + Output devices ignore the contents of padding bytes. + + When the image format is planar the ``bytesperline`` value applies + to the first plane and is divided by the same factor as the + ``width`` field for the other planes. For example the Cb and Cr + planes of a YUV 4:2:0 image have half as many padding bytes + following each line as the Y plane. To avoid ambiguities drivers + must return a ``bytesperline`` value rounded up to a multiple of + the scale factor. + + For compressed formats the ``bytesperline`` value makes no sense. + Applications and drivers must set this to 0 in that case. + * - __u32 + - ``sizeimage`` + - Size in bytes of the buffer to hold a complete image, set by the + driver. Usually this is ``bytesperline`` times ``height``. When + the image consists of variable length compressed data this is the + maximum number of bytes required to hold an image. + * - enum :c:type:`v4l2_colorspace` + - ``colorspace`` + - This information supplements the ``pixelformat`` and must be set + by the driver for capture streams and by the application for + output streams, see :ref:`colorspaces`. + * - __u32 + - ``priv`` + - This field indicates whether the remaining fields of the + struct :c:type:`v4l2_pix_format`, also called the + extended fields, are valid. When set to + ``V4L2_PIX_FMT_PRIV_MAGIC``, it indicates that the extended fields + have been correctly initialized. When set to any other value it + indicates that the extended fields contain undefined values. + + Applications that wish to use the pixel format extended fields + must first ensure that the feature is supported by querying the + device for the :ref:`V4L2_CAP_EXT_PIX_FORMAT <querycap>` + capability. If the capability isn't set the pixel format extended + fields are not supported and using the extended fields will lead + to undefined results. + + To use the extended fields, applications must set the ``priv`` + field to ``V4L2_PIX_FMT_PRIV_MAGIC``, initialize all the extended + fields and zero the unused bytes of the + struct :c:type:`v4l2_format` ``raw_data`` field. + + When the ``priv`` field isn't set to ``V4L2_PIX_FMT_PRIV_MAGIC`` + drivers must act as if all the extended fields were set to zero. + On return drivers must set the ``priv`` field to + ``V4L2_PIX_FMT_PRIV_MAGIC`` and all the extended fields to + applicable values. + * - __u32 + - ``flags`` + - Flags set by the application or driver, see :ref:`format-flags`. + * - enum :c:type:`v4l2_ycbcr_encoding` + - ``ycbcr_enc`` + - This information supplements the ``colorspace`` and must be set by + the driver for capture streams and by the application for output + streams, see :ref:`colorspaces`. + * - enum :c:type:`v4l2_hsv_encoding` + - ``hsv_enc`` + - This information supplements the ``colorspace`` and must be set by + the driver for capture streams and by the application for output + streams, see :ref:`colorspaces`. + * - enum :c:type:`v4l2_quantization` + - ``quantization`` + - This information supplements the ``colorspace`` and must be set by + the driver for capture streams and by the application for output + streams, see :ref:`colorspaces`. + * - enum :c:type:`v4l2_xfer_func` + - ``xfer_func`` + - This information supplements the ``colorspace`` and must be set by + the driver for capture streams and by the application for output + streams, see :ref:`colorspaces`. |