^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) .. c:namespace:: V4L
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) .. _VIDIOC_G_FBUF:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) **********************************
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) **********************************
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) Name
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) ====
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) VIDIOC_G_FBUF - VIDIOC_S_FBUF - Get or set frame buffer overlay parameters
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) Synopsis
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) ========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) .. c:macro:: VIDIOC_G_FBUF
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) ``int ioctl(int fd, VIDIOC_G_FBUF, struct v4l2_framebuffer *argp)``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) .. c:macro:: VIDIOC_S_FBUF
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) ``int ioctl(int fd, VIDIOC_S_FBUF, const struct v4l2_framebuffer *argp)``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) Arguments
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) =========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) ``fd``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) File descriptor returned by :c:func:`open()`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) ``argp``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) Pointer to struct :c:type:`v4l2_framebuffer`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) Description
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) ===========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) Applications can use the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` and :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctl
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) to get and set the framebuffer parameters for a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) :ref:`Video Overlay <overlay>` or :ref:`Video Output Overlay <osd>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) (OSD). The type of overlay is implied by the device type (capture or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) output device) and can be determined with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) :ref:`VIDIOC_QUERYCAP` ioctl. One ``/dev/videoN``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) device must not support both kinds of overlay.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) The V4L2 API distinguishes destructive and non-destructive overlays. A
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) destructive overlay copies captured video images into the video memory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) of a graphics card. A non-destructive overlay blends video images into a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) VGA signal or graphics into a video signal. *Video Output Overlays* are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) always non-destructive.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) To get the current parameters applications call the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) ioctl with a pointer to a struct :c:type:`v4l2_framebuffer`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) structure. The driver fills all fields of the structure or returns an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) EINVAL error code when overlays are not supported.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) To set the parameters for a *Video Output Overlay*, applications must
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) initialize the ``flags`` field of a struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) :c:type:`v4l2_framebuffer`. Since the framebuffer is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) implemented on the TV card all other parameters are determined by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) driver. When an application calls :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` with a pointer to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) this structure, the driver prepares for the overlay and returns the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) framebuffer parameters as :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` does, or it returns an error
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) code.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) To set the parameters for a *non-destructive Video Overlay*,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) applications must initialize the ``flags`` field, the ``fmt``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) substructure, and call :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`. Again the driver prepares for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) the overlay and returns the framebuffer parameters as :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) does, or it returns an error code.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) For a *destructive Video Overlay* applications must additionally provide
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) a ``base`` address. Setting up a DMA to a random memory location can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) jeopardize the system security, its stability or even damage the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) hardware, therefore only the superuser can set the parameters for a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) destructive video overlay.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) .. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) .. c:type:: v4l2_framebuffer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) .. cssclass:: longtable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) .. flat-table:: struct v4l2_framebuffer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) :header-rows: 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) :stub-columns: 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) :widths: 1 1 1 2
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) * - __u32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) - ``capability``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) -
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) - Overlay capability flags set by the driver, see
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) :ref:`framebuffer-cap`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) * - __u32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) - ``flags``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) -
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) - Overlay control flags set by application and driver, see
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) :ref:`framebuffer-flags`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) * - void *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) - ``base``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) -
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) - Physical base address of the framebuffer, that is the address of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) the pixel in the top left corner of the framebuffer. [#f1]_
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) * -
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) -
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) -
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) - This field is irrelevant to *non-destructive Video Overlays*. For
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) *destructive Video Overlays* applications must provide a base
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) address. The driver may accept only base addresses which are a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) multiple of two, four or eight bytes. For *Video Output Overlays*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) the driver must return a valid base address, so applications can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) find the corresponding Linux framebuffer device (see
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) :ref:`osd`).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) * - struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) - ``fmt``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) -
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) - Layout of the frame buffer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) * -
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) - __u32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) - ``width``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) - Width of the frame buffer in pixels.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) * -
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) - __u32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) - ``height``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) - Height of the frame buffer in pixels.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) * -
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) - __u32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) - ``pixelformat``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) - The pixel format of the framebuffer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) * -
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) -
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) -
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) - For *non-destructive Video Overlays* this field only defines a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) format for the struct :c:type:`v4l2_window`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) ``chromakey`` field.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) * -
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) -
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) -
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) - For *destructive Video Overlays* applications must initialize this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) field. For *Video Output Overlays* the driver must return a valid
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) format.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) * -
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) -
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) -
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) - Usually this is an RGB format (for example
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) :ref:`V4L2_PIX_FMT_RGB565 <V4L2-PIX-FMT-RGB565>`) but YUV
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) formats (only packed YUV formats when chroma keying is used, not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) including ``V4L2_PIX_FMT_YUYV`` and ``V4L2_PIX_FMT_UYVY``) and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) ``V4L2_PIX_FMT_PAL8`` format are also permitted. The behavior of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) the driver when an application requests a compressed format is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) undefined. See :ref:`pixfmt` for information on pixel formats.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) * -
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) - enum :c:type:`v4l2_field`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) - ``field``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) - Drivers and applications shall ignore this field. If applicable,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) the field order is selected with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, using the ``field``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) field of struct :c:type:`v4l2_window`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) * -
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) - __u32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) - ``bytesperline``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) - Distance in bytes between the leftmost pixels in two adjacent
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) lines.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) * - :cspan:`3`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) This field is irrelevant to *non-destructive Video Overlays*.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) For *destructive Video Overlays* both applications and drivers can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) set this field to request padding bytes at the end of each line.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) Drivers however may ignore the requested value, returning
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) ``width`` times bytes-per-pixel or a larger value required by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) hardware. That implies applications can just set this field to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) zero to get a reasonable default.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) For *Video Output Overlays* the driver must return a valid value.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) Video hardware may access padding bytes, therefore they must
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) reside in accessible memory. Consider for example the case where
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) padding bytes after the last line of an image cross a system page
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) boundary. Capture devices may write padding bytes, the value is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) undefined. Output devices ignore the contents of padding bytes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) When the image format is planar the ``bytesperline`` value applies
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) to the first plane and is divided by the same factor as the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) ``width`` field for the other planes. For example the Cb and Cr
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) planes of a YUV 4:2:0 image have half as many padding bytes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) following each line as the Y plane. To avoid ambiguities drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) must return a ``bytesperline`` value rounded up to a multiple of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) the scale factor.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) * -
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) - __u32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) - ``sizeimage``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) - This field is irrelevant to *non-destructive Video Overlays*. For
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) *destructive Video Overlays* applications must initialize this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) field. For *Video Output Overlays* the driver must return a valid
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) format.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) Together with ``base`` it defines the framebuffer memory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) accessible by the driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) * -
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) - enum :c:type:`v4l2_colorspace`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) - ``colorspace``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) - This information supplements the ``pixelformat`` and must be set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) by the driver, see :ref:`colorspaces`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) * -
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) - __u32
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) - ``priv``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) - Reserved. Drivers and applications must set this field to zero.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) .. _framebuffer-cap:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) .. flat-table:: Frame Buffer Capability Flags
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) :header-rows: 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) :stub-columns: 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) :widths: 3 1 4
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) * - ``V4L2_FBUF_CAP_EXTERNOVERLAY``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) - 0x0001
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) - The device is capable of non-destructive overlays. When the driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) clears this flag, only destructive overlays are supported. There
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) are no drivers yet which support both destructive and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) non-destructive overlays. Video Output Overlays are in practice
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) always non-destructive.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) * - ``V4L2_FBUF_CAP_CHROMAKEY``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) - 0x0002
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) - The device supports clipping by chroma-keying the images. That is,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) image pixels replace pixels in the VGA or video signal only where
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) the latter assume a certain color. Chroma-keying makes no sense
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) for destructive overlays.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) * - ``V4L2_FBUF_CAP_LIST_CLIPPING``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) - 0x0004
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) - The device supports clipping using a list of clip rectangles.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) * - ``V4L2_FBUF_CAP_BITMAP_CLIPPING``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) - 0x0008
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) - The device supports clipping using a bit mask.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) * - ``V4L2_FBUF_CAP_LOCAL_ALPHA``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) - 0x0010
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) - The device supports clipping/blending using the alpha channel of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) the framebuffer or VGA signal. Alpha blending makes no sense for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) destructive overlays.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) * - ``V4L2_FBUF_CAP_GLOBAL_ALPHA``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) - 0x0020
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) - The device supports alpha blending using a global alpha value.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) Alpha blending makes no sense for destructive overlays.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) * - ``V4L2_FBUF_CAP_LOCAL_INV_ALPHA``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) - 0x0040
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) - The device supports clipping/blending using the inverted alpha
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) channel of the framebuffer or VGA signal. Alpha blending makes no
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) sense for destructive overlays.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) * - ``V4L2_FBUF_CAP_SRC_CHROMAKEY``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) - 0x0080
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) - The device supports Source Chroma-keying. Video pixels with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) chroma-key colors are replaced by framebuffer pixels, which is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) exactly opposite of ``V4L2_FBUF_CAP_CHROMAKEY``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) .. _framebuffer-flags:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) .. cssclass:: longtable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) .. flat-table:: Frame Buffer Flags
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) :header-rows: 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) :stub-columns: 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) :widths: 3 1 4
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) * - ``V4L2_FBUF_FLAG_PRIMARY``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) - 0x0001
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) - The framebuffer is the primary graphics surface. In other words,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) the overlay is destructive. This flag is typically set by any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) driver that doesn't have the ``V4L2_FBUF_CAP_EXTERNOVERLAY``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) capability and it is cleared otherwise.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) * - ``V4L2_FBUF_FLAG_OVERLAY``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) - 0x0002
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) - If this flag is set for a video capture device, then the driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) will set the initial overlay size to cover the full framebuffer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) size, otherwise the existing overlay size (as set by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`) will be used. Only one
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) video capture driver (bttv) supports this flag. The use of this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) flag for capture devices is deprecated. There is no way to detect
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) which drivers support this flag, so the only reliable method of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) setting the overlay size is through
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. If this flag is set for a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) video output device, then the video output overlay window is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) relative to the top-left corner of the framebuffer and restricted
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) to the size of the framebuffer. If it is cleared, then the video
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) output overlay window is relative to the video output display.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) * - ``V4L2_FBUF_FLAG_CHROMAKEY``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) - 0x0004
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) - Use chroma-keying. The chroma-key color is determined by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) ``chromakey`` field of struct :c:type:`v4l2_window`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) and negotiated with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) ioctl, see :ref:`overlay` and :ref:`osd`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) * - :cspan:`2` There are no flags to enable clipping using a list of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297) clip rectangles or a bitmap. These methods are negotiated with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) and :ref:`osd`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) * - ``V4L2_FBUF_FLAG_LOCAL_ALPHA``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) - 0x0008
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) - Use the alpha channel of the framebuffer to clip or blend
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) framebuffer pixels with video images. The blend function is:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) output = framebuffer pixel * alpha + video pixel * (1 - alpha).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) The actual alpha depth depends on the framebuffer pixel format.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) * - ``V4L2_FBUF_FLAG_GLOBAL_ALPHA``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) - 0x0010
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) - Use a global alpha value to blend the framebuffer with video
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) images. The blend function is: output = (framebuffer pixel * alpha
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) + video pixel * (255 - alpha)) / 255. The alpha value is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311) determined by the ``global_alpha`` field of struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312) :c:type:`v4l2_window` and negotiated with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313) :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) and :ref:`osd`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315) * - ``V4L2_FBUF_FLAG_LOCAL_INV_ALPHA``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316) - 0x0020
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317) - Like ``V4L2_FBUF_FLAG_LOCAL_ALPHA``, use the alpha channel of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) framebuffer to clip or blend framebuffer pixels with video images,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) but with an inverted alpha value. The blend function is: output =
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) framebuffer pixel * (1 - alpha) + video pixel * alpha. The actual
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) alpha depth depends on the framebuffer pixel format.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) * - ``V4L2_FBUF_FLAG_SRC_CHROMAKEY``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) - 0x0040
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) - Use source chroma-keying. The source chroma-key color is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) determined by the ``chromakey`` field of struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326) :c:type:`v4l2_window` and negotiated with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328) and :ref:`osd`. Both chroma-keying are mutual exclusive to each
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) other, so same ``chromakey`` field of struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) :c:type:`v4l2_window` is being used.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) Return Value
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335) On success 0 is returned, on error -1 and the ``errno`` variable is set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) appropriately. The generic error codes are described at the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337) :ref:`Generic Error Codes <gen-errors>` chapter.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339) EPERM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` can only be called by a privileged user to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341) negotiate the parameters for a destructive overlay.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343) EINVAL
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344) The :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` parameters are unsuitable.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346) .. [#f1]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347) A physical base address may not suit all platforms. GK notes in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348) theory we should pass something like PCI device + memory region +
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349) offset instead. If you encounter problems please discuss on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350) linux-media mailing list:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351) `https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags