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