Debian Codegraph @

Documentation/userspace-api/media/v4l/dev-osd.rst

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