dev-osd.xml 6.0 KB

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