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