<commit_before>  <title>Video Output Overlay Interface</title>
  <subtitle>Also known as On-Screen Display (OSD)</subtitle>

  <para>Some video output devices can overlay a framebuffer image onto
the outgoing video signal. Applications can set up such an overlay
using this interface, which borrows structures and ioctls of the <link
linkend="overlay">Video Overlay</link> interface.</para>

  <para>The OSD function is accessible through the same character
special file as the <link linkend="capture">Video Output</link> function.
Note the default function of such a <filename>/dev/video</filename> device
is video capturing or output. The OSD function is only available after
calling the &VIDIOC-S-FMT; ioctl.</para>

  <section>
    <title>Querying Capabilities</title>

    <para>Devices supporting the <wordasword>Video Output
Overlay</wordasword> interface set the
<constant>V4L2_CAP_VIDEO_OUTPUT_OVERLAY</constant> flag in the
<structfield>capabilities</structfield> field of &v4l2-capability;
returned by the &VIDIOC-QUERYCAP; ioctl.</para>
  </section>

  <section>
    <title>Framebuffer</title>

    <para>Contrary to the <wordasword>Video Overlay</wordasword>
interface the framebuffer is normally implemented on the TV card and
not the graphics card. On Linux it is accessible as a framebuffer
device (<filename>/dev/fbN</filename>). Given a V4L2 device,
applications can find the corresponding framebuffer device by calling
the &VIDIOC-G-FBUF; ioctl. It returns, amongst other information, the
physical address of the framebuffer in the
<structfield>base</structfield> field of &v4l2-framebuffer;. The
framebuffer device ioctl <constant>FBIOGET_FSCREENINFO</constant>
returns the same address in the <structfield>smem_start</structfield>
field of struct <structname>fb_fix_screeninfo</structname>. The
<constant>FBIOGET_FSCREENINFO</constant> ioctl and struct
<structname>fb_fix_screeninfo</structname> are defined in the
<filename>linux/fb.h</filename> header file.</para>

    <para>The width and height of the framebuffer depends on the
current video standard. A V4L2 driver may reject attempts to change
the video standard (or any other ioctl which would imply a framebuffer
size change) with an &EBUSY; until all applications closed the
framebuffer device.</para>

    <example>
      <title>Finding a framebuffer device for OSD</title>

      <programlisting>
#include &lt;linux/fb.h&gt;

&v4l2-framebuffer; fbuf;
unsigned int i;
int fb_fd;

if (-1 == ioctl (fd, VIDIOC_G_FBUF, &amp;fbuf)) {
	perror ("VIDIOC_G_FBUF");
	exit (EXIT_FAILURE);
}

for (i = 0; i &gt; 30; ++i) {
	char dev_name[16];
	struct fb_fix_screeninfo si;

	snprintf (dev_name, sizeof (dev_name), "/dev/fb%u", i);

	fb_fd = open (dev_name, O_RDWR);
	if (-1 == fb_fd) {
		switch (errno) {
		case ENOENT: /* no such file */
		case ENXIO:  /* no driver */
			continue;

		default:
			perror ("open");
			exit (EXIT_FAILURE);
		}
	}

	if (0 == ioctl (fb_fd, FBIOGET_FSCREENINFO, &amp;si)) {
		if (si.smem_start == (unsigned long) fbuf.base)
			break;
	} else {
		/* Apparently not a framebuffer device. */
	}

	close (fb_fd);
	fb_fd = -1;
}

/* fb_fd is the file descriptor of the framebuffer device
   for the video output overlay, or -1 if no device was found. */
</programlisting>
    </example>
  </section>

  <section>
    <title>Overlay Window and Scaling</title>

    <para>The overlay is controlled by source and target rectangles.
The source rectangle selects a subsection of the framebuffer image to
be overlaid, the target rectangle an area in the outgoing video signal
where the image will appear. Drivers may or may not support scaling,
and arbitrary sizes and positions of these rectangles. Further drivers
may support any (or none) of the clipping/blending methods defined for
the <link linkend="overlay">Video Overlay</link> interface.</para>

    <para>A &v4l2-window; defines the size of the source rectangle,
its position in the framebuffer and the clipping/blending method to be
used for the overlay. To get the current parameters applications set
the <structfield>type</structfield> field of a &v4l2-format; to
<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant> and call the
&VIDIOC-G-FMT; ioctl. The driver fills the
<structname>v4l2_window</structname> substructure named
<structfield>win</structfield>. It is not possible to retrieve a<commit_msg>[media] DocBook: fix incorrect code example<commit_after>  <title>Video Output Overlay Interface</title>
  <subtitle>Also known as On-Screen Display (OSD)</subtitle>

  <para>Some video output devices can overlay a framebuffer image onto
the outgoing video signal. Applications can set up such an overlay
using this interface, which borrows structures and ioctls of the <link
linkend="overlay">Video Overlay</link> interface.</para>

  <para>The OSD function is accessible through the same character
special file as the <link linkend="capture">Video Output</link> function.
Note the default function of such a <filename>/dev/video</filename> device
is video capturing or output. The OSD function is only available after
calling the &VIDIOC-S-FMT; ioctl.</para>

  <section>
    <title>Querying Capabilities</title>

    <para>Devices supporting the <wordasword>Video Output
Overlay</wordasword> interface set the
<constant>V4L2_CAP_VIDEO_OUTPUT_OVERLAY</constant> flag in the
<structfield>capabilities</structfield> field of &v4l2-capability;
returned by the &VIDIOC-QUERYCAP; ioctl.</para>
  </section>

  <section>
    <title>Framebuffer</title>

    <para>Contrary to the <wordasword>Video Overlay</wordasword>
interface the framebuffer is normally implemented on the TV card and
not the graphics card. On Linux it is accessible as a framebuffer
device (<filename>/dev/fbN</filename>). Given a V4L2 device,
applications can find the corresponding framebuffer device by calling
the &VIDIOC-G-FBUF; ioctl. It returns, amongst other information, the
physical address of the framebuffer in the
<structfield>base</structfield> field of &v4l2-framebuffer;. The
framebuffer device ioctl <constant>FBIOGET_FSCREENINFO</constant>
returns the same address in the <structfield>smem_start</structfield>
field of struct <structname>fb_fix_screeninfo</structname>. The
<constant>FBIOGET_FSCREENINFO</constant> ioctl and struct
<structname>fb_fix_screeninfo</structname> are defined in the
<filename>linux/fb.h</filename> header file.</para>

    <para>The width and height of the framebuffer depends on the
current video standard. A V4L2 driver may reject attempts to change
the video standard (or any other ioctl which would imply a framebuffer
size change) with an &EBUSY; until all applications closed the
framebuffer device.</para>

    <example>
      <title>Finding a framebuffer device for OSD</title>

      <programlisting>
#include &lt;linux/fb.h&gt;

&v4l2-framebuffer; fbuf;
unsigned int i;
int fb_fd;

if (-1 == ioctl(fd, VIDIOC_G_FBUF, &amp;fbuf)) {
	perror("VIDIOC_G_FBUF");
	exit(EXIT_FAILURE);
}

for (i = 0; i &lt; 30; i++) {
	char dev_name[16];
	struct fb_fix_screeninfo si;

	snprintf(dev_name, sizeof(dev_name), "/dev/fb%u", i);

	fb_fd = open(dev_name, O_RDWR);
	if (-1 == fb_fd) {
		switch (errno) {
		case ENOENT: /* no such file */
		case ENXIO:  /* no driver */
			continue;

		default:
			perror("open");
			exit(EXIT_FAILURE);
		}
	}

	if (0 == ioctl(fb_fd, FBIOGET_FSCREENINFO, &amp;si)) {
		if (si.smem_start == (unsigned long)fbuf.base)
			break;
	} else {
		/* Apparently not a framebuffer device. */
	}

	close(fb_fd);
	fb_fd = -1;
}

/* fb_fd is the file descriptor of the framebuffer device
   for the video output overlay, or -1 if no device was found. */
</programlisting>
    </example>
  </section>

  <section>
    <title>Overlay Window and Scaling</title>

    <para>The overlay is controlled by source and target rectangles.
The source rectangle selects a subsection of the framebuffer image to
be overlaid, the target rectangle an area in the outgoing video signal
where the image will appear. Drivers may or may not support scaling,
and arbitrary sizes and positions of these rectangles. Further drivers
may support any (or none) of the clipping/blending methods defined for
the <link linkend="overlay">Video Overlay</link> interface.</para>

    <para>A &v4l2-window; defines the size of the source rectangle,
its position in the framebuffer and the clipping/blending method to be
used for the overlay. To get the current parameters applications set
the <structfield>type</structfield> field of a &v4l2-format; to
<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant> and call the
&VIDIOC-G-FMT; ioctl. The driver fills the
<structname>v4l2_window</structname> substructure named
<structfield>win</structfield>. It is not possible to retrieve a
{'fraction_non_alphanumeric': 0.09392518018533348, 'fraction_numerical': 0.00686420318041414, 'mean_word_length': 4.77792465300727, 'pattern_counts': {'":': 0, '<': 151, '<?xml version=': 0, '>': 151, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2878739', 'n_tokens_mistral': 2783, 'n_tokens_neox': 2677, 'n_words': 997}