VIDIOC_G_FBUF·VIDIOC_S_FBUF ioctl

목적, 호출 형식과 인자

`VIDIOC_G_FBUF`와 `VIDIOC_S_FBUF`는 Video Overlay 또는 Video Output Overlay(OSD)의 framebuffer 매개변수를 조회하거나 설정합니다. 두 명령은 `struct v4l2_framebuffer`를 사용하며, 설정 명령의 포인터는 `const`입니다.

`fd`는 `open()`이 반환한 파일 디스크립터이고 `argp`는 `v4l2_framebuffer` 구조체를 가리킵니다.

.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _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:macro:: VIDIOC_G_FBUF

``int ioctl(int fd, VIDIOC_G_FBUF, struct v4l2_framebuffer *argp)``

.. c:macro:: VIDIOC_S_FBUF

``int ioctl(int fd, VIDIOC_S_FBUF, const struct v4l2_framebuffer *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer to struct :c:type:`v4l2_framebuffer`.

overlay 유형과 조회·설정 절차

overlay가 캡처용 Video Overlay인지 출력용 Video Output Overlay인지 여부는 장치 유형에 따라 정해지며 `VIDIOC_QUERYCAP`으로 확인합니다. 하나의 `/dev/videoN` 장치가 두 overlay 유형을 동시에 지원해서는 안 됩니다.

destructive overlay는 캡처 영상을 그래픽 카드 비디오 메모리에 복사합니다. non-destructive overlay는 비디오 영상을 VGA 신호에 합성하거나 그래픽을 비디오 신호에 합성합니다. Video Output Overlay는 항상 non-destructive입니다.

destructive overlay 지원은 제거되었습니다. 현대 GPU와 CPU에서는 필요하지 않고 원래부터 매우 위험한 기능이었기 때문입니다. 아래 capability와 flag에는 하위 호환성 및 개념 설명을 위한 관련 표식이 남아 있습니다.

현재 매개변수는 `v4l2_framebuffer` 포인터로 `VIDIOC_G_FBUF`를 호출해 읽습니다. 드라이버는 모든 필드를 채우며 overlay를 지원하지 않으면 `EINVAL`을 반환합니다.

Video Output Overlay를 설정할 때 애플리케이션은 `flags`만 초기화합니다. framebuffer가 TV 카드에 구현되므로 나머지 값은 드라이버가 결정합니다. `VIDIOC_S_FBUF` 성공 시 드라이버는 overlay를 준비하고 G_FBUF와 같은 방식으로 결과 매개변수를 돌려줍니다.

Video Capture Overlay를 설정할 때는 `flags`와 `fmt` 하위 구조체를 초기화합니다. 드라이버는 overlay를 준비한 뒤 조회와 같은 결과를 반환하거나 오류를 반환합니다.

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.

Destructive overlay support has been removed: with modern GPUs and CPUs
this is no longer needed, and it was always a very dangerous feature.

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 *Video Capture 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.

struct v4l2_framebuffer

`base`는 `VIDIOC_S_FBUF` 입력으로 더 이상 지원되지 않으며 커널이 항상 NULL로 만듭니다. Video Output Overlay 조회에서는 대응하는 Linux framebuffer 장치를 찾을 수 있도록 유효한 주소를 반환하지만 Video Capture Overlay에서는 항상 NULL입니다.

non-destructive Video Overlay에서 `pixelformat`은 `v4l2_window.chromakey` 필드의 형식만 정의합니다. Video Output Overlay에서는 드라이버가 반드시 유효한 format을 반환해야 합니다.

보통 RGB 형식, 예를 들어 `V4L2_PIX_FMT_RGB565`를 사용합니다. YUV도 허용되지만 chroma keying 시에는 packed YUV만 가능하고 `V4L2_PIX_FMT_YUYV`와 `V4L2_PIX_FMT_UYVY`는 제외됩니다. `V4L2_PIX_FMT_PAL8`도 허용됩니다. 압축 format을 요청했을 때의 동작은 정의되지 않습니다.

`fmt.field`는 무시합니다. field 순서가 필요하면 `VIDIOC_S_FMT`에서 `v4l2_window.field`를 사용해 선택합니다.

`bytesperline`은 non-destructive Video Overlay에는 무관하지만 Video Output Overlay에서는 유효해야 합니다. 하드웨어가 padding byte에도 접근할 수 있으므로 마지막 행 뒤 padding이 시스템 page 경계를 넘는 경우까지 접근 가능한 메모리에 있어야 합니다.

캡처 장치는 padding byte를 쓸 수 있고 그 값은 정의되지 않습니다. 출력 장치는 padding 내용 자체를 무시합니다.

planar 형식에서는 `bytesperline`이 첫 plane에 적용되고 다른 plane은 `width`와 같은 비율로 나눕니다. YUV 4:2:0의 Cb·Cr plane은 Y plane의 절반만큼 행 뒤 padding을 가지며, 모호함을 피하려고 드라이버는 scale factor의 배수로 올림한 `bytesperline`을 반환해야 합니다.

`sizeimage`는 non-destructive Video Overlay에는 무관하고 Video Output Overlay에서는 유효해야 합니다. `base`와 함께 드라이버가 접근 가능한 framebuffer 메모리 범위를 정의합니다. `colorspace`는 드라이버가 설정합니다.

.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{6.6cm}|

.. 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.
	For :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` this field is no longer supported
	and the kernel will always set this to NULL.
	For *Video Output Overlays*
	the driver will return a valid base address, so applications can
	find the corresponding Linux framebuffer device (see
	:ref:`osd`). For *Video Capture Overlays* this field will always be
	NULL.
    * - 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 *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 *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 *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.

Frame Buffer Capability Flags

아직 destructive와 non-destructive overlay를 둘 다 지원하는 드라이버는 없으며 Video Output Overlay는 실제로 항상 non-destructive입니다. chroma-keying과 alpha blending은 destructive overlay에는 의미가 없습니다.

`SRC_CHROMAKEY`는 일반 `CHROMAKEY`와 반대입니다. 일반 방식은 대상 신호가 key 색일 때 영상이 그 자리를 대체하고, source 방식은 source 영상이 key 색일 때 framebuffer가 그 자리를 대체합니다.

.. tabularcolumns:: |p{7.4cm}|p{1.6cm}|p{8.3cm}|

.. _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.
        Note that this is no longer supported.
    * - ``V4L2_FBUF_CAP_BITMAP_CLIPPING``
      - 0x0008
      - The device supports clipping using a bit mask.
        Note that this is no longer supported.
    * - ``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``

Frame Buffer Flags

`PRIMARY`는 보통 `V4L2_FBUF_CAP_EXTERNOVERLAY`가 없는 드라이버가 설정하고 그 capability가 있으면 clear합니다.

capture 장치에서 `OVERLAY`가 설정되면 초기 overlay 크기를 framebuffer 전체로 잡고, clear이면 `VIDIOC_S_FMT`으로 정한 기존 크기를 사용합니다. 이 기능은 bttv 하나만 지원하며 폐기 예정이고 지원 여부를 탐지할 방법도 없으므로, 신뢰할 수 있는 크기 설정 방법은 `VIDIOC_S_FMT`뿐입니다.

output 장치에서 `OVERLAY`가 설정되면 overlay window는 framebuffer 좌상단 기준이고 framebuffer 크기로 제한됩니다. clear이면 video output display 기준입니다.

`CHROMAKEY`의 색은 `v4l2_window.chromakey`이고 `VIDIOC_S_FMT`으로 협상합니다. clip rectangle 목록이나 bitmap clipping을 켜는 flag는 없으며 이 방법들도 `VIDIOC_S_FMT`으로 협상합니다.

local alpha 혼합식은 `output = framebuffer pixel * alpha + video pixel * (1 - alpha)`입니다. 실제 alpha bit 깊이는 framebuffer pixel format에 따라 달라집니다.

global alpha 혼합식은 `output = (framebuffer pixel * alpha + video pixel * (255 - alpha)) / 255`입니다. alpha 값은 `v4l2_window.global_alpha`에서 가져와 `VIDIOC_S_FMT`으로 협상합니다.

inverted local alpha 혼합식은 `output = framebuffer pixel * (1 - alpha) + video pixel * alpha`입니다. 일반 local alpha와 같은 channel을 사용하되 alpha의 역할을 뒤집습니다.

source chroma-key 색도 `v4l2_window.chromakey`로 협상합니다. 일반 chroma-keying과 source chroma-keying은 상호 배타적이므로 같은 `chromakey` 필드를 공유합니다.

.. tabularcolumns:: |p{7.4cm}|p{1.6cm}|p{8.3cm}|

.. _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.

반환값과 오류

성공하면 0을 반환합니다. 오류가 발생하면 -1을 반환하고 `errno`를 설정하며, 아래 전용 오류 외에도 Generic Error Codes 장의 공통 오류가 적용됩니다.

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.