mirror of
https://github.com/edk2-porting/linux-next.git
synced 2024-12-22 12:14:01 +08:00
54f38fcae5
Since 2017, there is an space reserved for userspace API,
created by changeset 1d596dee38 ("docs: Create a user-space API guide").
As the media subsystem was one of the first subsystems to use
Sphinx, until this patch, we were keeping things on a separate
place.
Let's just use the new location, as having all uAPI altogether
will likely make things easier for developers.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
363 lines
14 KiB
ReStructuredText
363 lines
14 KiB
ReStructuredText
.. 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/userspace-api/media/fdl-appendix.rst.
|
|
..
|
|
.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
|
|
|
|
.. _VIDIOC_G_FBUF:
|
|
|
|
**********************************
|
|
ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF
|
|
**********************************
|
|
|
|
Name
|
|
====
|
|
|
|
VIDIOC_G_FBUF - VIDIOC_S_FBUF - Get or set frame buffer overlay parameters
|
|
|
|
|
|
Synopsis
|
|
========
|
|
|
|
.. c:function:: int ioctl( int fd, VIDIOC_G_FBUF, struct v4l2_framebuffer *argp )
|
|
:name: VIDIOC_G_FBUF
|
|
|
|
.. 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>`.
|
|
|
|
``argp``
|
|
Pointer to struct :c:type:`v4l2_framebuffer`.
|
|
|
|
|
|
Description
|
|
===========
|
|
|
|
Applications can use the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` and :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctl
|
|
to get and set the framebuffer parameters for a
|
|
:ref:`Video Overlay <overlay>` or :ref:`Video Output Overlay <osd>`
|
|
(OSD). The type of overlay is implied by the device type (capture or
|
|
output device) and can be determined with the
|
|
:ref:`VIDIOC_QUERYCAP` ioctl. One ``/dev/videoN``
|
|
device must not support both kinds of overlay.
|
|
|
|
The V4L2 API distinguishes destructive and non-destructive overlays. A
|
|
destructive overlay copies captured video images into the video memory
|
|
of a graphics card. A non-destructive overlay blends video images into a
|
|
VGA signal or graphics into a video signal. *Video Output Overlays* are
|
|
always non-destructive.
|
|
|
|
To get the current parameters applications call the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`
|
|
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
|
|
: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
|
|
framebuffer parameters as :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` does, or it returns an error
|
|
code.
|
|
|
|
To set the parameters for a *non-destructive Video Overlay*,
|
|
applications must initialize the ``flags`` field, the ``fmt``
|
|
substructure, and call :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`. Again the driver prepares for
|
|
the overlay and returns the framebuffer parameters as :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`
|
|
does, or it returns an error code.
|
|
|
|
For a *destructive Video Overlay* applications must additionally provide
|
|
a ``base`` address. Setting up a DMA to a random memory location can
|
|
jeopardize the system security, its stability or even damage the
|
|
hardware, therefore only the superuser can set the parameters for a
|
|
destructive video overlay.
|
|
|
|
|
|
.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}|
|
|
|
|
.. c:type:: v4l2_framebuffer
|
|
|
|
.. cssclass:: longtable
|
|
|
|
.. flat-table:: struct v4l2_framebuffer
|
|
:header-rows: 0
|
|
:stub-columns: 0
|
|
:widths: 1 1 1 2
|
|
|
|
* - __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:
|
|
|
|
.. flat-table:: Frame Buffer Capability Flags
|
|
:header-rows: 0
|
|
:stub-columns: 0
|
|
:widths: 3 1 4
|
|
|
|
* - ``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:
|
|
|
|
.. cssclass:: longtable
|
|
|
|
.. flat-table:: Frame Buffer Flags
|
|
:header-rows: 0
|
|
:stub-columns: 0
|
|
:widths: 3 1 4
|
|
|
|
* - ``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
|
|
============
|
|
|
|
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.
|
|
|
|
EPERM
|
|
:ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` can only be called by a privileged user to
|
|
negotiate the parameters for a destructive overlay.
|
|
|
|
EINVAL
|
|
The :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` parameters are unsuitable.
|
|
|
|
.. [#f1]
|
|
A physical base address may not suit all platforms. GK notes in
|
|
theory we should pass something like PCI device + memory region +
|
|
offset instead. If you encounter problems please discuss on the
|
|
linux-media mailing list:
|
|
`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__.
|