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