Synopsis
========
-.. cpp:function:: int ioctl( int fd, int request, struct v4l2_framebuffer *argp )
+.. c:function:: int ioctl( int fd, VIDIOC_G_FBUF, struct v4l2_framebuffer *argp )
+ :name: VIDIOC_G_FBUF
-.. cpp:function:: int ioctl( int fd, int request, const struct v4l2_framebuffer *argp )
+.. c:function:: int ioctl( int fd, VIDIOC_S_FBUF, const struct v4l2_framebuffer *argp )
+ :name: VIDIOC_S_FBUF
Arguments
``fd``
File descriptor returned by :ref:`open() <func-open>`.
-``request``
- VIDIOC_G_FBUF, VIDIOC_S_FBUF
-
``argp``
always non-destructive.
To get the current parameters applications call the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`
-ioctl with a pointer to a :ref:`struct v4l2_framebuffer <v4l2-framebuffer>`
+ioctl with a pointer to a struct :c:type:`v4l2_framebuffer`
structure. The driver fills all fields of the structure or returns an
EINVAL error code when overlays are not supported.
To set the parameters for a *Video Output Overlay*, applications must
initialize the ``flags`` field of a struct
-:ref:`struct v4l2_framebuffer <v4l2-framebuffer>`. Since the framebuffer is
+struct :c:type:`v4l2_framebuffer`. Since the framebuffer is
implemented on the TV card all other parameters are determined by the
driver. When an application calls :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` with a pointer to
this structure, the driver prepares for the overlay and returns the
destructive video overlay.
-.. _v4l2-framebuffer:
-
.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}|
+.. c:type:: v4l2_framebuffer
+
.. cssclass:: longtable
.. flat-table:: struct v4l2_framebuffer
:stub-columns: 0
:widths: 1 1 1 2
-
- - .. row 1
-
- - __u32
-
- - ``capability``
-
- -
- - Overlay capability flags set by the driver, see
- :ref:`framebuffer-cap`.
-
- - .. row 2
-
- - __u32
-
- - ``flags``
-
- -
- - Overlay control flags set by application and driver, see
- :ref:`framebuffer-flags`
-
- - .. row 3
-
- - void *
-
- - ``base``
-
- -
- - Physical base address of the framebuffer, that is the address of
- the pixel in the top left corner of the framebuffer. [#f1]_
-
- - .. row 4
-
- -
- -
- -
- - This field is irrelevant to *non-destructive Video Overlays*. For
- *destructive Video Overlays* applications must provide a base
- address. The driver may accept only base addresses which are a
- multiple of two, four or eight bytes. For *Video Output Overlays*
- the driver must return a valid base address, so applications can
- find the corresponding Linux framebuffer device (see
- :ref:`osd`).
-
- - .. row 5
-
- - struct
-
- - ``fmt``
-
- -
- - Layout of the frame buffer.
-
- - .. row 6
-
- -
- - __u32
-
- - ``width``
-
- - Width of the frame buffer in pixels.
-
- - .. row 7
-
- -
- - __u32
-
- - ``height``
-
- - Height of the frame buffer in pixels.
-
- - .. row 8
-
- -
- - __u32
-
- - ``pixelformat``
-
- - The pixel format of the framebuffer.
-
- - .. row 9
-
- -
- -
- -
- - For *non-destructive Video Overlays* this field only defines a
- format for the struct :ref:`v4l2_window <v4l2-window>`
- ``chromakey`` field.
-
- - .. row 10
-
- -
- -
- -
- - For *destructive Video Overlays* applications must initialize this
- field. For *Video Output Overlays* the driver must return a valid
- format.
-
- - .. row 11
-
- -
- -
- -
- - Usually this is an RGB format (for example
- :ref:`V4L2_PIX_FMT_RGB565 <V4L2-PIX-FMT-RGB565>`) but YUV
- formats (only packed YUV formats when chroma keying is used, not
- including ``V4L2_PIX_FMT_YUYV`` and ``V4L2_PIX_FMT_UYVY``) and the
- ``V4L2_PIX_FMT_PAL8`` format are also permitted. The behavior of
- the driver when an application requests a compressed format is
- undefined. See :ref:`pixfmt` for information on pixel formats.
-
- - .. row 12
-
- -
- - enum :ref:`v4l2_field <v4l2-field>`
-
- - ``field``
-
- - Drivers and applications shall ignore this field. If applicable,
- the field order is selected with the
- :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, using the ``field``
- field of struct :ref:`v4l2_window <v4l2-window>`.
-
- - .. row 13
-
- -
- - __u32
-
- - ``bytesperline``
-
- - Distance in bytes between the leftmost pixels in two adjacent
- lines.
-
- - .. row 14
-
- - :cspan:`3`
-
- This field is irrelevant to *non-destructive Video Overlays*.
-
- For *destructive Video Overlays* both applications and drivers can
- set this field to request padding bytes at the end of each line.
- Drivers however may ignore the requested value, 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.
-
- For *Video Output Overlays* the driver must return a valid value.
-
- Video hardware may access padding bytes, therefore they must
- reside in accessible memory. Consider for example the case where
- padding bytes after the last line of an image cross a system page
- boundary. Capture 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.
-
- - .. row 15
-
- -
- - __u32
-
- - ``sizeimage``
-
- - This field is irrelevant to *non-destructive Video Overlays*. For
- *destructive Video Overlays* applications must initialize this
- field. For *Video Output Overlays* the driver must return a valid
- format.
-
- Together with ``base`` it defines the framebuffer memory
- accessible by the driver.
-
- - .. row 16
-
- -
- - enum :ref:`v4l2_colorspace <v4l2-colorspace>`
-
- - ``colorspace``
-
- - This information supplements the ``pixelformat`` and must be set
- by the driver, see :ref:`colorspaces`.
-
- - .. row 17
-
- -
- - __u32
-
- - ``priv``
-
- - Reserved. Drivers and applications must set this field to zero.
+ * - __u32
+ - ``capability``
+ -
+ - Overlay capability flags set by the driver, see
+ :ref:`framebuffer-cap`.
+ * - __u32
+ - ``flags``
+ -
+ - Overlay control flags set by application and driver, see
+ :ref:`framebuffer-flags`
+ * - void *
+ - ``base``
+ -
+ - Physical base address of the framebuffer, that is the address of
+ the pixel in the top left corner of the framebuffer. [#f1]_
+ * -
+ -
+ -
+ - This field is irrelevant to *non-destructive Video Overlays*. For
+ *destructive Video Overlays* applications must provide a base
+ address. The driver may accept only base addresses which are a
+ multiple of two, four or eight bytes. For *Video Output Overlays*
+ the driver must return a valid base address, so applications can
+ find the corresponding Linux framebuffer device (see
+ :ref:`osd`).
+ * - struct
+ - ``fmt``
+ -
+ - Layout of the frame buffer.
+ * -
+ - __u32
+ - ``width``
+ - Width of the frame buffer in pixels.
+ * -
+ - __u32
+ - ``height``
+ - Height of the frame buffer in pixels.
+ * -
+ - __u32
+ - ``pixelformat``
+ - The pixel format of the framebuffer.
+ * -
+ -
+ -
+ - For *non-destructive Video Overlays* this field only defines a
+ format for the struct :c:type:`v4l2_window`
+ ``chromakey`` field.
+ * -
+ -
+ -
+ - For *destructive Video Overlays* applications must initialize this
+ field. For *Video Output Overlays* the driver must return a valid
+ format.
+ * -
+ -
+ -
+ - Usually this is an RGB format (for example
+ :ref:`V4L2_PIX_FMT_RGB565 <V4L2-PIX-FMT-RGB565>`) but YUV
+ formats (only packed YUV formats when chroma keying is used, not
+ including ``V4L2_PIX_FMT_YUYV`` and ``V4L2_PIX_FMT_UYVY``) and the
+ ``V4L2_PIX_FMT_PAL8`` format are also permitted. The behavior of
+ the driver when an application requests a compressed format is
+ undefined. See :ref:`pixfmt` for information on pixel formats.
+ * -
+ - enum :c:type:`v4l2_field`
+ - ``field``
+ - Drivers and applications shall ignore this field. If applicable,
+ the field order is selected with the
+ :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, using the ``field``
+ field of struct :c:type:`v4l2_window`.
+ * -
+ - __u32
+ - ``bytesperline``
+ - Distance in bytes between the leftmost pixels in two adjacent
+ lines.
+ * - :cspan:`3`
+
+ This field is irrelevant to *non-destructive Video Overlays*.
+
+ For *destructive Video Overlays* both applications and drivers can
+ set this field to request padding bytes at the end of each line.
+ Drivers however may ignore the requested value, 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.
+
+ For *Video Output Overlays* the driver must return a valid value.
+
+ Video hardware may access padding bytes, therefore they must
+ reside in accessible memory. Consider for example the case where
+ padding bytes after the last line of an image cross a system page
+ boundary. Capture 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.
+ * -
+ - __u32
+ - ``sizeimage``
+ - This field is irrelevant to *non-destructive Video Overlays*. For
+ *destructive Video Overlays* applications must initialize this
+ field. For *Video Output Overlays* the driver must return a valid
+ format.
+
+ Together with ``base`` it defines the framebuffer memory
+ accessible by the driver.
+ * -
+ - enum :c:type:`v4l2_colorspace`
+ - ``colorspace``
+ - This information supplements the ``pixelformat`` and must be set
+ by the driver, see :ref:`colorspaces`.
+ * -
+ - __u32
+ - ``priv``
+ - Reserved. Drivers and applications must set this field to zero.
+.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
.. _framebuffer-cap:
-.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
-
.. flat-table:: Frame Buffer Capability Flags
:header-rows: 0
:stub-columns: 0
:widths: 3 1 4
-
- - .. row 1
-
- - ``V4L2_FBUF_CAP_EXTERNOVERLAY``
-
- - 0x0001
-
- - The device is capable of non-destructive overlays. When the driver
- clears this flag, only destructive overlays are supported. There
- are no drivers yet which support both destructive and
- non-destructive overlays. Video Output Overlays are in practice
- always non-destructive.
-
- - .. row 2
-
- - ``V4L2_FBUF_CAP_CHROMAKEY``
-
- - 0x0002
-
- - The device supports clipping by chroma-keying the images. That is,
- image pixels replace pixels in the VGA or video signal only where
- the latter assume a certain color. Chroma-keying makes no sense
- for destructive overlays.
-
- - .. row 3
-
- - ``V4L2_FBUF_CAP_LIST_CLIPPING``
-
- - 0x0004
-
- - The device supports clipping using a list of clip rectangles.
-
- - .. row 4
-
- - ``V4L2_FBUF_CAP_BITMAP_CLIPPING``
-
- - 0x0008
-
- - The device supports clipping using a bit mask.
-
- - .. row 5
-
- - ``V4L2_FBUF_CAP_LOCAL_ALPHA``
-
- - 0x0010
-
- - The device supports clipping/blending using the alpha channel of
- the framebuffer or VGA signal. Alpha blending makes no sense for
- destructive overlays.
-
- - .. row 6
-
- - ``V4L2_FBUF_CAP_GLOBAL_ALPHA``
-
- - 0x0020
-
- - The device supports alpha blending using a global alpha value.
- Alpha blending makes no sense for destructive overlays.
-
- - .. row 7
-
- - ``V4L2_FBUF_CAP_LOCAL_INV_ALPHA``
-
- - 0x0040
-
- - The device supports clipping/blending using the inverted alpha
- channel of the framebuffer or VGA signal. Alpha blending makes no
- sense for destructive overlays.
-
- - .. row 8
-
- - ``V4L2_FBUF_CAP_SRC_CHROMAKEY``
-
- - 0x0080
-
- - The device supports Source Chroma-keying. Video pixels with the
- chroma-key colors are replaced by framebuffer pixels, which is
- exactly opposite of ``V4L2_FBUF_CAP_CHROMAKEY``
+ * - ``V4L2_FBUF_CAP_EXTERNOVERLAY``
+ - 0x0001
+ - The device is capable of non-destructive overlays. When the driver
+ clears this flag, only destructive overlays are supported. There
+ are no drivers yet which support both destructive and
+ non-destructive overlays. Video Output Overlays are in practice
+ always non-destructive.
+ * - ``V4L2_FBUF_CAP_CHROMAKEY``
+ - 0x0002
+ - The device supports clipping by chroma-keying the images. That is,
+ image pixels replace pixels in the VGA or video signal only where
+ the latter assume a certain color. Chroma-keying makes no sense
+ for destructive overlays.
+ * - ``V4L2_FBUF_CAP_LIST_CLIPPING``
+ - 0x0004
+ - The device supports clipping using a list of clip rectangles.
+ * - ``V4L2_FBUF_CAP_BITMAP_CLIPPING``
+ - 0x0008
+ - The device supports clipping using a bit mask.
+ * - ``V4L2_FBUF_CAP_LOCAL_ALPHA``
+ - 0x0010
+ - The device supports clipping/blending using the alpha channel of
+ the framebuffer or VGA signal. Alpha blending makes no sense for
+ destructive overlays.
+ * - ``V4L2_FBUF_CAP_GLOBAL_ALPHA``
+ - 0x0020
+ - The device supports alpha blending using a global alpha value.
+ Alpha blending makes no sense for destructive overlays.
+ * - ``V4L2_FBUF_CAP_LOCAL_INV_ALPHA``
+ - 0x0040
+ - The device supports clipping/blending using the inverted alpha
+ channel of the framebuffer or VGA signal. Alpha blending makes no
+ sense for destructive overlays.
+ * - ``V4L2_FBUF_CAP_SRC_CHROMAKEY``
+ - 0x0080
+ - The device supports Source Chroma-keying. Video pixels with the
+ chroma-key colors are replaced by framebuffer pixels, which is
+ exactly opposite of ``V4L2_FBUF_CAP_CHROMAKEY``
+.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
.. _framebuffer-flags:
-.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
-
.. cssclass:: longtable
.. flat-table:: Frame Buffer Flags
:stub-columns: 0
:widths: 3 1 4
-
- - .. row 1
-
- - ``V4L2_FBUF_FLAG_PRIMARY``
-
- - 0x0001
-
- - The framebuffer is the primary graphics surface. In other words,
- the overlay is destructive. This flag is typically set by any
- driver that doesn't have the ``V4L2_FBUF_CAP_EXTERNOVERLAY``
- capability and it is cleared otherwise.
-
- - .. row 2
-
- - ``V4L2_FBUF_FLAG_OVERLAY``
-
- - 0x0002
-
- - If this flag is set for a video capture device, then the driver
- will set the initial overlay size to cover the full framebuffer
- size, otherwise the existing overlay size (as set by
- :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`) will be used. Only one
- video capture driver (bttv) supports this flag. The use of this
- flag for capture devices is deprecated. There is no way to detect
- which drivers support this flag, so the only reliable method of
- setting the overlay size is through
- :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. If this flag is set for a
- video output device, then the video output overlay window is
- relative to the top-left corner of the framebuffer and restricted
- to the size of the framebuffer. If it is cleared, then the video
- output overlay window is relative to the video output display.
-
- - .. row 3
-
- - ``V4L2_FBUF_FLAG_CHROMAKEY``
-
- - 0x0004
-
- - Use chroma-keying. The chroma-key color is determined by the
- ``chromakey`` field of struct :ref:`v4l2_window <v4l2-window>`
- and negotiated with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
- ioctl, see :ref:`overlay` and :ref:`osd`.
-
- - .. row 4
-
- - :cspan:`2` There are no flags to enable clipping using a list of
- clip rectangles or a bitmap. These methods are negotiated with the
- :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay`
- and :ref:`osd`.
-
- - .. row 5
-
- - ``V4L2_FBUF_FLAG_LOCAL_ALPHA``
-
- - 0x0008
-
- - Use the alpha channel of the framebuffer to clip or blend
- framebuffer pixels with video images. The blend function is:
- output = framebuffer pixel * alpha + video pixel * (1 - alpha).
- The actual alpha depth depends on the framebuffer pixel format.
-
- - .. row 6
-
- - ``V4L2_FBUF_FLAG_GLOBAL_ALPHA``
-
- - 0x0010
-
- - Use a global alpha value to blend the framebuffer with video
- images. The blend function is: output = (framebuffer pixel * alpha
- + video pixel * (255 - alpha)) / 255. The alpha value is
- determined by the ``global_alpha`` field of struct
- :ref:`v4l2_window <v4l2-window>` and negotiated with the
- :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay`
- and :ref:`osd`.
-
- - .. row 7
-
- - ``V4L2_FBUF_FLAG_LOCAL_INV_ALPHA``
-
- - 0x0020
-
- - Like ``V4L2_FBUF_FLAG_LOCAL_ALPHA``, use the alpha channel of the
- framebuffer to clip or blend framebuffer pixels with video images,
- but with an inverted alpha value. The blend function is: output =
- framebuffer pixel * (1 - alpha) + video pixel * alpha. The actual
- alpha depth depends on the framebuffer pixel format.
-
- - .. row 8
-
- - ``V4L2_FBUF_FLAG_SRC_CHROMAKEY``
-
- - 0x0040
-
- - Use source chroma-keying. The source chroma-key color is
- determined by the ``chromakey`` field of struct
- :ref:`v4l2_window <v4l2-window>` and negotiated with the
- :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay`
- and :ref:`osd`. Both chroma-keying are mutual exclusive to each
- other, so same ``chromakey`` field of struct
- :ref:`v4l2_window <v4l2-window>` is being used.
+ * - ``V4L2_FBUF_FLAG_PRIMARY``
+ - 0x0001
+ - The framebuffer is the primary graphics surface. In other words,
+ the overlay is destructive. This flag is typically set by any
+ driver that doesn't have the ``V4L2_FBUF_CAP_EXTERNOVERLAY``
+ capability and it is cleared otherwise.
+ * - ``V4L2_FBUF_FLAG_OVERLAY``
+ - 0x0002
+ - If this flag is set for a video capture device, then the driver
+ will set the initial overlay size to cover the full framebuffer
+ size, otherwise the existing overlay size (as set by
+ :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`) will be used. Only one
+ video capture driver (bttv) supports this flag. The use of this
+ flag for capture devices is deprecated. There is no way to detect
+ which drivers support this flag, so the only reliable method of
+ setting the overlay size is through
+ :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. If this flag is set for a
+ video output device, then the video output overlay window is
+ relative to the top-left corner of the framebuffer and restricted
+ to the size of the framebuffer. If it is cleared, then the video
+ output overlay window is relative to the video output display.
+ * - ``V4L2_FBUF_FLAG_CHROMAKEY``
+ - 0x0004
+ - Use chroma-keying. The chroma-key color is determined by the
+ ``chromakey`` field of struct :c:type:`v4l2_window`
+ and negotiated with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
+ ioctl, see :ref:`overlay` and :ref:`osd`.
+ * - :cspan:`2` There are no flags to enable clipping using a list of
+ clip rectangles or a bitmap. These methods are negotiated with the
+ :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay`
+ and :ref:`osd`.
+ * - ``V4L2_FBUF_FLAG_LOCAL_ALPHA``
+ - 0x0008
+ - Use the alpha channel of the framebuffer to clip or blend
+ framebuffer pixels with video images. The blend function is:
+ output = framebuffer pixel * alpha + video pixel * (1 - alpha).
+ The actual alpha depth depends on the framebuffer pixel format.
+ * - ``V4L2_FBUF_FLAG_GLOBAL_ALPHA``
+ - 0x0010
+ - Use a global alpha value to blend the framebuffer with video
+ images. The blend function is: output = (framebuffer pixel * alpha
+ + video pixel * (255 - alpha)) / 255. The alpha value is
+ determined by the ``global_alpha`` field of struct
+ :c:type:`v4l2_window` and negotiated with the
+ :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay`
+ and :ref:`osd`.
+ * - ``V4L2_FBUF_FLAG_LOCAL_INV_ALPHA``
+ - 0x0020
+ - Like ``V4L2_FBUF_FLAG_LOCAL_ALPHA``, use the alpha channel of the
+ framebuffer to clip or blend framebuffer pixels with video images,
+ but with an inverted alpha value. The blend function is: output =
+ framebuffer pixel * (1 - alpha) + video pixel * alpha. The actual
+ alpha depth depends on the framebuffer pixel format.
+ * - ``V4L2_FBUF_FLAG_SRC_CHROMAKEY``
+ - 0x0040
+ - Use source chroma-keying. The source chroma-key color is
+ determined by the ``chromakey`` field of struct
+ :c:type:`v4l2_window` and negotiated with the
+ :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay`
+ and :ref:`osd`. Both chroma-keying are mutual exclusive to each
+ other, so same ``chromakey`` field of struct
+ :c:type:`v4l2_window` is being used.
Return Value
projects / cascardo / linux.git / blobdiff