[media] DocBook: Move all media docbook stuff into its own directory

This patch addresses several issues pointed by Randy Dunlap
<rdunlap@xenotime.net> at changeset ece722c:

- In the generated index.html file, "media" is listed first, but it
  should be listed in alphabetical order, not first.

- The generated files are (hidden) in .tmpmedia/

- The link from the top-level index.html file to "media" is to
  media/index.html, but the file is actually in .tmpmedia/media/index.html

- Please build docs with and without using "O=builddir" and test that.

- Would it be possible for media to have its own Makefile instead of
  merging into this one?

Due to the way cleandocs target works, I had to rename the media DocBook
to media_api, otherwise cleandocs would remove the /media directory.

Thanks-to: Randy Dunlap <rdunlap@xenotime.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>

1 files changed, 164 insertions, 0 deletions

diff --git a/Documentation/DocBook/media/v4l/dev-osd.xml b/Documentation/DocBook/media/v4l/dev-osd.xml
new file mode 100644
index 0000000..c9a68a2
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/dev-osd.xml
@@ -0,0 +1,164 @@
+  <title>Video Output Overlay Interface</title>
+  <subtitle>Also known as On-Screen Display (OSD)</subtitle>
+
+  <note>
+    <title>Experimental</title>
+
+    <para>This is an <link linkend="experimental">experimental</link>
+interface and may change in the future.</para>
+  </note>
+
+  <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
+previously programmed clipping list or bitmap.</para>
+
+    <para>To program the source rectangle applications set the
+<structfield>type</structfield> field of a &v4l2-format; to
+<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant>, initialize
+the <structfield>win</structfield> substructure and call the
+&VIDIOC-S-FMT; ioctl. The driver adjusts the parameters against
+hardware limits and returns the actual parameters as
+<constant>VIDIOC_G_FMT</constant> does. Like
+<constant>VIDIOC_S_FMT</constant>, the &VIDIOC-TRY-FMT; ioctl can be
+used to learn about driver capabilities without actually changing
+driver state. Unlike <constant>VIDIOC_S_FMT</constant> this also works
+after the overlay has been enabled.</para>
+
+    <para>A &v4l2-crop; defines the size and position of the target
+rectangle. The scaling factor of the overlay is implied by the width
+and height given in &v4l2-window; and &v4l2-crop;. The cropping API
+applies to <wordasword>Video Output</wordasword> and <wordasword>Video
+Output Overlay</wordasword> devices in the same way as to
+<wordasword>Video Capture</wordasword> and <wordasword>Video
+Overlay</wordasword> devices, merely reversing the direction of the
+data flow. For more information see <xref linkend="crop" />.</para>
+  </section>
+
+  <section>
+    <title>Enabling Overlay</title>
+
+    <para>There is no V4L2 ioctl to enable or disable the overlay,
+however the framebuffer interface of the driver may support the
+<constant>FBIOBLANK</constant> ioctl.</para>
+  </section>
+
+  <!--
+Local Variables:
+mode: sgml
+sgml-parent-document: "v4l2.sgml"
+indent-tabs-mode: nil
+End:
+  -->