Orange Pi5 kernel

^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) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   3) .. _overlay:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   4) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   5) ***********************
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   6) Video Overlay Interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   7) ***********************
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   8) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   9) **Also known as Framebuffer Overlay or Previewing.**
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  10) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  11) Video overlay devices have the ability to genlock (TV-)video into the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  12) (VGA-)video signal of a graphics card, or to store captured images
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  13) directly in video memory of a graphics card, typically with clipping.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  14) This can be considerable more efficient than capturing images and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  15) displaying them by other means. In the old days when only nuclear power
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  16) plants needed cooling towers this used to be the only way to put live
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  17) video into a window.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  18) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  19) Video overlay devices are accessed through the same character special
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  20) files as :ref:`video capture <capture>` devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  21) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  22) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  23) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  24)    The default function of a ``/dev/video`` device is video
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  25)    capturing. The overlay function is only available after calling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  26)    the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  27) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  28) The driver may support simultaneous overlay and capturing using the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  29) read/write and streaming I/O methods. If so, operation at the nominal
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  30) frame rate of the video standard is not guaranteed. Frames may be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  31) directed away from overlay to capture, or one field may be used for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  32) overlay and the other for capture if the capture parameters permit this.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  33) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  34) Applications should use different file descriptors for capturing and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  35) overlay. This must be supported by all drivers capable of simultaneous
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  36) capturing and overlay. Optionally these drivers may also permit
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  37) capturing and overlay with a single file descriptor for compatibility
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  38) with V4L and earlier versions of V4L2. [#f1]_
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  39) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  40) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  41) Querying Capabilities
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  42) =====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  43) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  44) Devices supporting the video overlay interface set the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  45) ``V4L2_CAP_VIDEO_OVERLAY`` flag in the ``capabilities`` field of struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  46) :c:type:`v4l2_capability` returned by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  47) :ref:`VIDIOC_QUERYCAP` ioctl. The overlay I/O
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  48) method specified below must be supported. Tuners and audio inputs are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  49) optional.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  50) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  51) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  52) Supplemental Functions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  53) ======================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  54) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  55) Video overlay devices shall support :ref:`audio input <audio>`,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  56) :ref:`tuner`, :ref:`controls <control>`,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  57) :ref:`cropping and scaling <crop>` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  58) :ref:`streaming parameter <streaming-par>` ioctls as needed. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  59) :ref:`video input <video>` and :ref:`video standard <standard>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  60) ioctls must be supported by all video overlay devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  61) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  62) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  63) Setup
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  64) =====
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  65) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  66) Before overlay can commence applications must program the driver with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  67) frame buffer parameters, namely the address and size of the frame buffer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  68) and the image format, for example RGB 5:6:5. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  69) :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  70) :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctls are available to get and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  71) set these parameters, respectively. The :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctl is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  72) privileged because it allows to set up DMA into physical memory,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  73) bypassing the memory protection mechanisms of the kernel. Only the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  74) superuser can change the frame buffer address and size. Users are not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  75) supposed to run TV applications as root or with SUID bit set. A small
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  76) helper application with suitable privileges should query the graphics
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  77) system and program the V4L2 driver at the appropriate time.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  78) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  79) Some devices add the video overlay to the output signal of the graphics
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  80) card. In this case the frame buffer is not modified by the video device,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  81) and the frame buffer address and pixel format are not needed by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  82) driver. The :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctl is not privileged. An application
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  83) can check for this type of device by calling the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  84) ioctl.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  85) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  86) A driver may support any (or none) of five clipping/blending methods:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  87) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  88) 1. Chroma-keying displays the overlaid image only where pixels in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  89)    primary graphics surface assume a certain color.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  90) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  91) 2. A bitmap can be specified where each bit corresponds to a pixel in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  92)    the overlaid image. When the bit is set, the corresponding video
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  93)    pixel is displayed, otherwise a pixel of the graphics surface.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  94) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  95) 3. A list of clipping rectangles can be specified. In these regions *no*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  96)    video is displayed, so the graphics surface can be seen here.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  97) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  98) 4. The framebuffer has an alpha channel that can be used to clip or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  99)    blend the framebuffer with the video.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) 5. A global alpha value can be specified to blend the framebuffer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102)    contents with video images.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) When simultaneous capturing and overlay is supported and the hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) prohibits different image and frame buffer formats, the format requested
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) first takes precedence. The attempt to capture
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) (:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`) or overlay
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) (:ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`) may fail with an ``EBUSY`` error
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) code or return accordingly modified parameters..
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) Overlay Window
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) ==============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) The overlaid image is determined by cropping and overlay window
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) parameters. The former select an area of the video picture to capture,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) the latter how images are overlaid and clipped. Cropping initialization
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) at minimum requires to reset the parameters to defaults. An example is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) given in :ref:`crop`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) The overlay window is described by a struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) :c:type:`v4l2_window`. It defines the size of the image,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) its position over the graphics surface and the clipping to be applied.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) To get the current parameters applications set the ``type`` field of a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) struct :c:type:`v4l2_format` to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) ``V4L2_BUF_TYPE_VIDEO_OVERLAY`` and call the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl. The driver fills the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) struct :c:type:`v4l2_window` substructure named ``win``. It is not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) possible to retrieve a previously programmed clipping list or bitmap.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) To program the overlay window applications set the ``type`` field of a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) struct :c:type:`v4l2_format` to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) ``V4L2_BUF_TYPE_VIDEO_OVERLAY``, initialize the ``win`` substructure and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. The driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) adjusts the parameters against hardware limits and returns the actual
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. Like :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl can be used to learn
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) about driver capabilities without actually changing driver state. Unlike
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` this also works after the overlay has been enabled.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) The scaling factor of the overlaid image is implied by the width and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) height given in struct :c:type:`v4l2_window` and the size
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) of the cropping rectangle. For more information see :ref:`crop`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) When simultaneous capturing and overlay is supported and the hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) prohibits different image and window sizes, the size requested first
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) takes precedence. The attempt to capture or overlay as well
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) (:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`) may fail with an ``EBUSY`` error
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) code or return accordingly modified parameters.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) .. c:type:: v4l2_window
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) struct v4l2_window
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) ------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) ``struct v4l2_rect w``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158)     Size and position of the window relative to the top, left corner of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159)     the frame buffer defined with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160)     :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`. The window can extend the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161)     frame buffer width and height, the ``x`` and ``y`` coordinates can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162)     be negative, and it can lie completely outside the frame buffer. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163)     driver clips the window accordingly, or if that is not possible,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164)     modifies its size and/or position.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) ``enum v4l2_field field``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167)     Applications set this field to determine which video field shall be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168)     overlaid, typically one of ``V4L2_FIELD_ANY`` (0),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169)     ``V4L2_FIELD_TOP``, ``V4L2_FIELD_BOTTOM`` or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170)     ``V4L2_FIELD_INTERLACED``. Drivers may have to choose a different
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171)     field order and return the actual setting here.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) ``__u32 chromakey``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174)     When chroma-keying has been negotiated with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175)     :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` applications set this field
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176)     to the desired pixel value for the chroma key. The format is the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177)     same as the pixel format of the framebuffer (struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178)     :c:type:`v4l2_framebuffer` ``fmt.pixelformat``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179)     field), with bytes in host order. E. g. for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180)     :ref:`V4L2_PIX_FMT_BGR24 <V4L2-PIX-FMT-BGR32>` the value should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181)     be 0xRRGGBB on a little endian, 0xBBGGRR on a big endian host.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) ``struct v4l2_clip * clips``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184)     When chroma-keying has *not* been negotiated and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185)     :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` indicated this capability,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186)     applications can set this field to point to an array of clipping
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187)     rectangles.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189)     Like the window coordinates w, clipping rectangles are defined
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190)     relative to the top, left corner of the frame buffer. However
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191)     clipping rectangles must not extend the frame buffer width and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192)     height, and they must not overlap. If possible applications
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193)     should merge adjacent rectangles. Whether this must create
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194)     x-y or y-x bands, or the order of rectangles, is not defined. When
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195)     clip lists are not supported the driver ignores this field. Its
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196)     contents after calling :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197)     are undefined.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) ``__u32 clipcount``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200)     When the application set the ``clips`` field, this field must
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201)     contain the number of clipping rectangles in the list. When clip
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202)     lists are not supported the driver ignores this field, its contents
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203)     after calling :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` are undefined. When clip lists are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204)     supported but no clipping is desired this field must be set to zero.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) ``void * bitmap``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207)     When chroma-keying has *not* been negotiated and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208)     :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` indicated this capability,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209)     applications can set this field to point to a clipping bit mask.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) It must be of the same size as the window, ``w.width`` and ``w.height``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) Each bit corresponds to a pixel in the overlaid image, which is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) displayed only when the bit is *set*. Pixel coordinates translate to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) bits like:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219)     ((__u8 *) bitmap)[w.width * y + x / 8] & (1 << (x & 7))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) where ``0`` ≤ x < ``w.width`` and ``0`` ≤ y <``w.height``. [#f2]_
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) When a clipping bit mask is not supported the driver ignores this field,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) its contents after calling :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) undefined. When a bit mask is supported but no clipping is desired this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) field must be set to ``NULL``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) Applications need not create a clip list or bit mask. When they pass
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) both, or despite negotiating chroma-keying, the results are undefined.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) Regardless of the chosen method, the clipping abilities of the hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) may be limited in quantity or quality. The results when these limits are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) exceeded are undefined. [#f3]_
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) ``__u8 global_alpha``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235)     The global alpha value used to blend the framebuffer with video
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236)     images, if global alpha blending has been negotiated
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237)     (``V4L2_FBUF_FLAG_GLOBAL_ALPHA``, see
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238)     :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239)     :ref:`framebuffer-flags`).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243)    This field was added in Linux 2.6.23, extending the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244)    structure. However the :ref:`VIDIOC_[G|S|TRY]_FMT <VIDIOC_G_FMT>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245)    ioctls, which take a pointer to a :c:type:`v4l2_format`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246)    parent structure with padding bytes at the end, are not affected.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) .. c:type:: v4l2_clip
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) struct v4l2_clip [#f4]_
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) -----------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) ``struct v4l2_rect c``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255)     Coordinates of the clipping rectangle, relative to the top, left
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256)     corner of the frame buffer. Only window pixels *outside* all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257)     clipping rectangles are displayed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) ``struct v4l2_clip * next``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260)     Pointer to the next clipping rectangle, ``NULL`` when this is the last
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261)     rectangle. Drivers ignore this field, it cannot be used to pass a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262)     linked list of clipping rectangles.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) .. c:type:: v4l2_rect
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) struct v4l2_rect
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) ----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) ``__s32 left``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271)     Horizontal offset of the top, left corner of the rectangle, in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272)     pixels.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) ``__s32 top``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275)     Vertical offset of the top, left corner of the rectangle, in pixels.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276)     Offsets increase to the right and down.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) ``__u32 width``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279)     Width of the rectangle, in pixels.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) ``__u32 height``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282)     Height of the rectangle, in pixels.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) Enabling Overlay
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) ================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) To start or stop the frame buffer overlay applications call the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) :ref:`VIDIOC_OVERLAY` ioctl.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) .. [#f1]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292)    A common application of two file descriptors is the XFree86
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293)    :ref:`Xv/V4L <xvideo>` interface driver and a V4L2 application.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294)    While the X server controls video overlay, the application can take
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295)    advantage of memory mapping and DMA.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297)    In the opinion of the designers of this API, no driver writer taking
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298)    the efforts to support simultaneous capturing and overlay will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299)    restrict this ability by requiring a single file descriptor, as in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300)    V4L and earlier versions of V4L2. Making this optional means
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301)    applications depending on two file descriptors need backup routines
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302)    to be compatible with all drivers, which is considerable more work
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303)    than using two fds in applications which do not. Also two fd's fit
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304)    the general concept of one file descriptor for each logical stream.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305)    Hence as a complexity trade-off drivers *must* support two file
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306)    descriptors and *may* support single fd operation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) .. [#f2]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309)    Should we require ``w.width`` to be a multiple of eight?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311) .. [#f3]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312)    When the image is written into frame buffer memory it will be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313)    undesirable if the driver clips out less pixels than expected,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314)    because the application and graphics system are not aware these
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315)    regions need to be refreshed. The driver should clip out more pixels
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316)    or not write the image at all.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) .. [#f4]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319)    The X Window system defines "regions" which are vectors of ``struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320)    BoxRec { short x1, y1, x2, y2; }`` with ``width = x2 - x1`` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321)    ``height = y2 - y1``, so one cannot pass X11 clip lists directly.