1.. Permission is granted to copy, distribute and/or modify this
2.. document under the terms of the GNU Free Documentation License,
3.. Version 1.1 or any later version published by the Free Software
4.. Foundation, with no Invariant Sections, no Front-Cover Texts
5.. and no Back-Cover Texts. A copy of the license is included at
6.. Documentation/userspace-api/media/fdl-appendix.rst.
7..
8.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
9
10.. _osd:
11
12******************************
13Video Output Overlay Interface
14******************************
15
16**Also known as On-Screen Display (OSD)**
17
18Some video output devices can overlay a framebuffer image onto the
19outgoing video signal. Applications can set up such an overlay using
20this interface, which borrows structures and ioctls of the
21:ref:`Video Overlay <overlay>` interface.
22
23The OSD function is accessible through the same character special file
24as the :ref:`Video Output <capture>` function.
25
26.. note::
27
28   The default function of such a ``/dev/video`` device is video
29   capturing or output. The OSD function is only available after calling
30   the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
31
32
33Querying Capabilities
34=====================
35
36Devices supporting the *Video Output Overlay* interface set the
37``V4L2_CAP_VIDEO_OUTPUT_OVERLAY`` flag in the ``capabilities`` field of
38struct :c:type:`v4l2_capability` returned by the
39:ref:`VIDIOC_QUERYCAP` ioctl.
40
41
42Framebuffer
43===========
44
45Contrary to the *Video Overlay* interface the framebuffer is normally
46implemented on the TV card and not the graphics card. On Linux it is
47accessible as a framebuffer device (``/dev/fbN``). Given a V4L2 device,
48applications can find the corresponding framebuffer device by calling
49the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` ioctl. It returns, amongst
50other information, the physical address of the framebuffer in the
51``base`` field of struct :c:type:`v4l2_framebuffer`.
52The framebuffer device ioctl ``FBIOGET_FSCREENINFO`` returns the same
53address in the ``smem_start`` field of struct
54struct :c:type:`fb_fix_screeninfo`. The ``FBIOGET_FSCREENINFO``
55ioctl and struct :c:type:`fb_fix_screeninfo` are defined in
56the ``linux/fb.h`` header file.
57
58The width and height of the framebuffer depends on the current video
59standard. A V4L2 driver may reject attempts to change the video standard
60(or any other ioctl which would imply a framebuffer size change) with an
61``EBUSY`` error code until all applications closed the framebuffer device.
62
63Example: Finding a framebuffer device for OSD
64---------------------------------------------
65
66.. code-block:: c
67
68    #include <linux/fb.h>
69
70    struct v4l2_framebuffer fbuf;
71    unsigned int i;
72    int fb_fd;
73
74    if (-1 == ioctl(fd, VIDIOC_G_FBUF, &fbuf)) {
75	perror("VIDIOC_G_FBUF");
76	exit(EXIT_FAILURE);
77    }
78
79    for (i = 0; i < 30; i++) {
80	char dev_name[16];
81	struct fb_fix_screeninfo si;
82
83	snprintf(dev_name, sizeof(dev_name), "/dev/fb%u", i);
84
85	fb_fd = open(dev_name, O_RDWR);
86	if (-1 == fb_fd) {
87	    switch (errno) {
88	    case ENOENT: /* no such file */
89	    case ENXIO:  /* no driver */
90		continue;
91
92	    default:
93		perror("open");
94		exit(EXIT_FAILURE);
95	    }
96	}
97
98	if (0 == ioctl(fb_fd, FBIOGET_FSCREENINFO, &si)) {
99	    if (si.smem_start == (unsigned long)fbuf.base)
100		break;
101	} else {
102	    /* Apparently not a framebuffer device. */
103	}
104
105	close(fb_fd);
106	fb_fd = -1;
107    }
108
109    /* fb_fd is the file descriptor of the framebuffer device
110       for the video output overlay, or -1 if no device was found. */
111
112
113Overlay Window and Scaling
114==========================
115
116The overlay is controlled by source and target rectangles. The source
117rectangle selects a subsection of the framebuffer image to be overlaid,
118the target rectangle an area in the outgoing video signal where the
119image will appear. Drivers may or may not support scaling, and arbitrary
120sizes and positions of these rectangles. Further drivers may support any
121(or none) of the clipping/blending methods defined for the
122:ref:`Video Overlay <overlay>` interface.
123
124A struct :c:type:`v4l2_window` defines the size of the
125source rectangle, its position in the framebuffer and the
126clipping/blending method to be used for the overlay. To get the current
127parameters applications set the ``type`` field of a struct
128:c:type:`v4l2_format` to
129``V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY`` and call the
130:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl. The driver fills the
131struct :c:type:`v4l2_window` substructure named ``win``. It is not
132possible to retrieve a previously programmed clipping list or bitmap.
133
134To program the source rectangle applications set the ``type`` field of a
135struct :c:type:`v4l2_format` to
136``V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY``, initialize the ``win``
137substructure and call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
138The driver adjusts the parameters against hardware limits and returns
139the actual parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. Like :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`,
140the :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl can be used to learn
141about driver capabilities without actually changing driver state. Unlike
142:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` this also works after the overlay has been enabled.
143
144A struct :c:type:`v4l2_crop` defines the size and position
145of the target rectangle. The scaling factor of the overlay is implied by
146the width and height given in struct :c:type:`v4l2_window`
147and struct :c:type:`v4l2_crop`. The cropping API applies to
148*Video Output* and *Video Output Overlay* devices in the same way as to
149*Video Capture* and *Video Overlay* devices, merely reversing the
150direction of the data flow. For more information see :ref:`crop`.
151
152
153Enabling Overlay
154================
155
156There is no V4L2 ioctl to enable or disable the overlay, however the
157framebuffer interface of the driver may support the ``FBIOBLANK`` ioctl.
158