Documentation/DocBook/media/v4l/dev-overlay.xml - kernel/windcharger - Git at Google

   <title>Video Overlay Interface</title>
   <subtitle>Also known as Framebuffer Overlay or Previewing</subtitle>

   <para>Video overlay devices have the ability to genlock (TV-)video
 into the (VGA-)video signal of a graphics card, or to store captured
 images directly in video memory of a graphics card, typically with
 clipping. This can be considerable more efficient than capturing
 images and displaying them by other means. In the old days when only
 nuclear power plants needed cooling towers this used to be the only
 way to put live video into a window.</para>

   <para>Video overlay devices are accessed through the same character
 special files as <link linkend="capture">video capture</link> devices.
 Note the default function of a <filename>/dev/video</filename> device
 is video capturing. The overlay function is only available after
 calling the &VIDIOC-S-FMT; ioctl.</para>

     <para>The driver may support simultaneous overlay and capturing
 using the read/write and streaming I/O methods. If so, operation at
 the nominal frame rate of the video standard is not guaranteed. Frames
 may be directed away from overlay to capture, or one field may be used
 for overlay and the other for capture if the capture parameters permit
 this.</para>

   <para>Applications should use different file descriptors for
 capturing and overlay. This must be supported by all drivers capable
 of simultaneous capturing and overlay. Optionally these drivers may
 also permit capturing and overlay with a single file descriptor for
 compatibility with V4L and earlier versions of V4L2.<footnote>
 	<para>A common application of two file descriptors is the
 XFree86 <link linkend="xvideo">Xv/V4L</link> interface driver and
 a V4L2 application. While the X server controls video overlay, the
 application can take advantage of memory mapping and DMA.</para>
 	<para>In the opinion of the designers of this API, no driver
 writer taking the efforts to support simultaneous capturing and
 overlay will restrict this ability by requiring a single file
 descriptor, as in V4L and earlier versions of V4L2. Making this
 optional means applications depending on two file descriptors need
 backup routines to be compatible with all drivers, which is
 considerable more work than using two fds in applications which do
 not. Also two fd's fit the general concept of one file descriptor for
 each logical stream. Hence as a complexity trade-off drivers
 <emphasis>must</emphasis> support two file descriptors and
 <emphasis>may</emphasis> support single fd operation.</para>
       </footnote></para>

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

     <para>Devices supporting the video overlay interface set the
 <constant>V4L2_CAP_VIDEO_OVERLAY</constant> flag in the
 <structfield>capabilities</structfield> field of &v4l2-capability;
 returned by the &VIDIOC-QUERYCAP; ioctl. The overlay I/O method specified
 below must be supported. Tuners and audio inputs are optional.</para>
   </section>

   <section>
     <title>Supplemental Functions</title>

     <para>Video overlay devices shall support <link
 linkend="audio">audio input</link>, <link
 linkend="tuner">tuner</link>, <link linkend="control">controls</link>,
 <link linkend="crop">cropping and scaling</link> and <link
 linkend="streaming-par">streaming parameter</link> ioctls as needed.
 The <link linkend="video">video input</link> and <link
 linkend="standard">video standard</link> ioctls must be supported by
 all video overlay devices.</para>
   </section>

   <section>
     <title>Setup</title>

     <para>Before overlay can commence applications must program the
 driver with frame buffer parameters, namely the address and size of
 the frame buffer and the image format, for example RGB 5:6:5. The
 &VIDIOC-G-FBUF; and &VIDIOC-S-FBUF; ioctls are available to get
 and set these parameters, respectively. The
 <constant>VIDIOC_S_FBUF</constant> ioctl is privileged because it
 allows to set up DMA into physical memory, bypassing the memory
 protection mechanisms of the kernel. Only the superuser can change the
 frame buffer address and size. Users are not supposed to run TV
 applications as root or with SUID bit set. A small helper application
 with suitable privileges should query the graphics system and program
 the V4L2 driver at the appropriate time.</para>

     <para>Some devices add the video overlay to the output signal
 of the graphics card. In this case the frame buffer is not modified by
 the video device, and the frame buffer address and pixel format are
 not needed by the driver. The <constant>VIDIOC_S_FBUF</constant> ioctl
 is not privileged. An application can check for this type of device by
 calling the <constant>VIDIOC_G_FBUF</constant> ioctl.</para>

     <para>A driver may support any (or none) of five clipping/blending
 methods:<orderedlist>
 	<listitem>
 	  <para>Chroma-keying displays the overlaid image only where
 pixels in the primary graphics surface assume a certain color.</para>
 	</listitem>
 	<listitem>
 	  <para>A bitmap can be specified where each bit corresponds
 to a pixel in the overlaid image. When the bit is set, the
 corresponding video pixel is displayed, otherwise a pixel of the
 graphics surface.</para>
 	</listitem>
 	<listitem>
 	  <para>A list of clipping rectangles can be specified. In
 these regions <emphasis>no</emphasis> video is displayed, so the
 graphics surface can be seen here.</para>
 	</listitem>
 	<listitem>
 	  <para>The framebuffer has an alpha channel that can be used
 to clip or blend the framebuffer with the video.</para>
 	</listitem>
 	<listitem>
 	  <para>A global alpha value can be specified to blend the
 framebuffer contents with video images.</para>
 	</listitem>
       </orderedlist></para>

     <para>When simultaneous capturing and overlay is supported and
 the hardware prohibits different image and frame buffer formats, the
 format requested first takes precedence. The attempt to capture
 (&VIDIOC-S-FMT;) or overlay (&VIDIOC-S-FBUF;) may fail with an
 &EBUSY; or return accordingly modified parameters..</para>
   </section>

   <section>
     <title>Overlay Window</title>

     <para>The overlaid image is determined by cropping and overlay
 window parameters. The former select an area of the video picture to
 capture, the latter how images are overlaid and clipped. Cropping
 initialization at minimum requires to reset the parameters to
 defaults. An example is given in <xref linkend="crop" />.</para>

     <para>The overlay window is described by a &v4l2-window;. It
 defines the size of the image, its position over the graphics surface
 and the clipping to be applied. To get the current parameters
 applications set the <structfield>type</structfield> field of a
 &v4l2-format; to <constant>V4L2_BUF_TYPE_VIDEO_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 overlay window applications set the
 <structfield>type</structfield> field of a &v4l2-format; to
 <constant>V4L2_BUF_TYPE_VIDEO_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>The scaling factor of the overlaid image is implied by the
 width and height given in &v4l2-window; and the size of the cropping
 rectangle. For more information see <xref linkend="crop" />.</para>

     <para>When simultaneous capturing and overlay is supported and
 the hardware prohibits different image and window sizes, the size
 requested first takes precedence. The attempt to capture or overlay as
 well (&VIDIOC-S-FMT;) may fail with an &EBUSY; or return accordingly
 modified parameters.</para>

     <table pgwide="1" frame="none" id="v4l2-window">
       <title>struct <structname>v4l2_window</structname></title>
       <tgroup cols="3">
 	&cs-str;
 	<tbody valign="top">
 	  <row>
 	    <entry>&v4l2-rect;</entry>
 	    <entry><structfield>w</structfield></entry>
 	    <entry>Size and position of the window relative to the
 top, left corner of the frame buffer defined with &VIDIOC-S-FBUF;. The
 window can extend the frame buffer width and height, the
 <structfield>x</structfield> and <structfield>y</structfield>
 coordinates can be negative, and it can lie completely outside the
 frame buffer. The driver clips the window accordingly, or if that is
 not possible, modifies its size and/or position.</entry>
 	  </row>
 	  <row>
 	    <entry>&v4l2-field;</entry>
 	    <entry><structfield>field</structfield></entry>
 	    <entry>Applications set this field to determine which
 video field shall be overlaid, typically one of
 <constant>V4L2_FIELD_ANY</constant> (0),
 <constant>V4L2_FIELD_TOP</constant>,
 <constant>V4L2_FIELD_BOTTOM</constant> or
 <constant>V4L2_FIELD_INTERLACED</constant>. Drivers may have to choose
 a different field order and return the actual setting here.</entry>
 	    </row>
 	  <row>
 	    <entry>__u32</entry>
 	    <entry><structfield>chromakey</structfield></entry>
 	    <entry>When chroma-keying has been negotiated with
 &VIDIOC-S-FBUF; applications set this field to the desired pixel value
 for the chroma key. The format is the same as the pixel format of the
 framebuffer (&v4l2-framebuffer;
 <structfield>fmt.pixelformat</structfield> field), with bytes in host
 order. E.&nbsp;g. for <link
 linkend="V4L2-PIX-FMT-BGR32"><constant>V4L2_PIX_FMT_BGR24</constant></link>
 the value should be 0xRRGGBB on a little endian, 0xBBGGRR on a big
 endian host.</entry>
 	  </row>
 	  <row>
 	    <entry>&v4l2-clip; *</entry>
 	    <entry><structfield>clips</structfield></entry>
 	    <entry>When chroma-keying has <emphasis>not</emphasis>
 been negotiated and &VIDIOC-G-FBUF; indicated this capability,
 applications can set this field to point to an array of
 clipping rectangles.</entry>
 	  </row>
 	  <row>
 	    <entry></entry>
 	    <entry></entry>
 	    <entry>Like the window coordinates
 <structfield>w</structfield>, clipping rectangles are defined relative
 to the top, left corner of the frame buffer. However clipping
 rectangles must not extend the frame buffer width and height, and they
 must not overlap. If possible applications should merge adjacent
 rectangles. Whether this must create x-y or y-x bands, or the order of
 rectangles, is not defined. When clip lists are not supported the
 driver ignores this field. Its contents after calling &VIDIOC-S-FMT;
 are undefined.</entry>
 	  </row>
 	  <row>
 	    <entry>__u32</entry>
 	    <entry><structfield>clipcount</structfield></entry>
 	    <entry>When the application set the
 <structfield>clips</structfield> field, this field must contain the
 number of clipping rectangles in the list. When clip lists are not
 supported the driver ignores this field, its contents after calling
 <constant>VIDIOC_S_FMT</constant> are undefined. When clip lists are
 supported but no clipping is desired this field must be set to
 zero.</entry>
 	  </row>
 	  <row>
 	    <entry>void *</entry>
 	    <entry><structfield>bitmap</structfield></entry>
 	    <entry>When chroma-keying has
 <emphasis>not</emphasis> been negotiated and &VIDIOC-G-FBUF; indicated
 this capability, applications can set this field to point to a
 clipping bit mask.</entry>
 	  </row>
 	  <row>
 	    <entry spanname="hspan"><para>It must be of the same size
 as the window, <structfield>w.width</structfield> and
 <structfield>w.height</structfield>. Each bit corresponds to a pixel
 in the overlaid image, which is displayed only when the bit is
 <emphasis>set</emphasis>. Pixel coordinates translate to bits like:
 <programlisting>
 ((__u8 *) <structfield>bitmap</structfield>)[<structfield>w.width</structfield> * y + x / 8] &amp; (1 &lt;&lt; (x &amp; 7))</programlisting></para><para>where <structfield>0</structfield> &le; x &lt;
 <structfield>w.width</structfield> and <structfield>0</structfield> &le;
 y &lt;<structfield>w.height</structfield>.<footnote>
 		  <para>Should we require
 	      <structfield>w.width</structfield> to be a multiple of
 	      eight?</para>
 		</footnote></para><para>When a clipping
 bit mask is not supported the driver ignores this field, its contents
 after calling &VIDIOC-S-FMT; are undefined. When a bit mask is supported
 but no clipping is desired this field must be set to
 <constant>NULL</constant>.</para><para>Applications need not create a
 clip list or bit mask. When they pass both, or despite negotiating
 chroma-keying, the results are undefined. Regardless of the chosen
 method, the clipping abilities of the hardware may be limited in
 quantity or quality. The results when these limits are exceeded are
 undefined.<footnote>
 		  <para>When the image is written into frame buffer
 memory it will be undesirable if the driver clips out less pixels
 than expected, because the application and graphics system are not
 aware these regions need to be refreshed. The driver should clip out
 more pixels or not write the image at all.</para>
 		</footnote></para></entry>
 	  </row>
 	  <row>
 	    <entry>__u8</entry>
 	    <entry><structfield>global_alpha</structfield></entry>
 	    <entry>The global alpha value used to blend the
 framebuffer with video images, if global alpha blending has been
 negotiated (<constant>V4L2_FBUF_FLAG_GLOBAL_ALPHA</constant>, see
 &VIDIOC-S-FBUF;, <xref linkend="framebuffer-flags" />).</entry>
 	  </row>
 	  <row>
 	    <entry></entry>
 	    <entry></entry>
 	    <entry>Note this field was added in Linux 2.6.23, extending the structure. However
 the <link linkend="vidioc-g-fmt">VIDIOC_G/S/TRY_FMT</link> ioctls,
 which take a pointer to a <link
 linkend="v4l2-format">v4l2_format</link> parent structure with padding
 bytes at the end, are not affected.</entry>
 	  </row>
 	</tbody>
       </tgroup>
     </table>

     <table pgwide="1" frame="none" id="v4l2-clip">
       <title>struct <structname>v4l2_clip</structname><footnote>
 	  <para>The X Window system defines "regions" which are
 vectors of struct BoxRec { short x1, y1, x2, y2; } with width = x2 -
 x1 and height = y2 - y1, so one cannot pass X11 clip lists
 directly.</para>
 	</footnote></title>
       <tgroup cols="3">
 	&cs-str;
 	<tbody valign="top">
 	  <row>
 	    <entry>&v4l2-rect;</entry>
 	    <entry><structfield>c</structfield></entry>
 	    <entry>Coordinates of the clipping rectangle, relative to
 the top, left corner of the frame buffer. Only window pixels
 <emphasis>outside</emphasis> all clipping rectangles are
 displayed.</entry>
 	  </row>
 	  <row>
 	    <entry>&v4l2-clip; *</entry>
 	    <entry><structfield>next</structfield></entry>
 	    <entry>Pointer to the next clipping rectangle, NULL when
 this is the last rectangle. Drivers ignore this field, it cannot be
 used to pass a linked list of clipping rectangles.</entry>
 	  </row>
 	</tbody>
       </tgroup>
     </table>

     <!-- NB for easier reading this table is duplicated
     in the vidioc-cropcap chapter.-->

     <table pgwide="1" frame="none" id="v4l2-rect">
       <title>struct <structname>v4l2_rect</structname></title>
       <tgroup cols="3">
 	&cs-str;
 	<tbody valign="top">
 	  <row>
 	    <entry>__s32</entry>
 	    <entry><structfield>left</structfield></entry>
 	    <entry>Horizontal offset of the top, left corner of the
 rectangle, in pixels.</entry>
 	  </row>
 	  <row>
 	    <entry>__s32</entry>
 	    <entry><structfield>top</structfield></entry>
 	    <entry>Vertical offset of the top, left corner of the
 rectangle, in pixels. Offsets increase to the right and down.</entry>
 	  </row>
 	  <row>
 	    <entry>__s32</entry>
 	    <entry><structfield>width</structfield></entry>
 	    <entry>Width of the rectangle, in pixels.</entry>
 	  </row>
 	  <row>
 	    <entry>__s32</entry>
 	    <entry><structfield>height</structfield></entry>
 	    <entry>Height of the rectangle, in pixels. Width and
 height cannot be negative, the fields are signed for hysterical
 reasons. <!-- video4linux-list@redhat.com on 22 Oct 2002 subject
 "Re:[V4L][patches!] Re:v4l2/kernel-2.5" --></entry>
 	  </row>
 	</tbody>
       </tgroup>
     </table>
   </section>

   <section>
     <title>Enabling Overlay</title>

     <para>To start or stop the frame buffer overlay applications call
 the &VIDIOC-OVERLAY; ioctl.</para>
   </section>
	<title>Video Overlay Interface</title>
	<subtitle>Also known as Framebuffer Overlay or Previewing</subtitle>

	<para>Video overlay devices have the ability to genlock (TV-)video
	into the (VGA-)video signal of a graphics card, or to store captured
	images directly in video memory of a graphics card, typically with
	clipping. This can be considerable more efficient than capturing
	images and displaying them by other means. In the old days when only
	nuclear power plants needed cooling towers this used to be the only
	way to put live video into a window.</para>

	<para>Video overlay devices are accessed through the same character
	special files as <link linkend="capture">video capture</link> devices.
	Note the default function of a <filename>/dev/video</filename> device
	is video capturing. The overlay function is only available after
	calling the &VIDIOC-S-FMT; ioctl.</para>

	<para>The driver may support simultaneous overlay and capturing
	using the read/write and streaming I/O methods. If so, operation at
	the nominal frame rate of the video standard is not guaranteed. Frames
	may be directed away from overlay to capture, or one field may be used
	for overlay and the other for capture if the capture parameters permit
	this.</para>

	<para>Applications should use different file descriptors for
	capturing and overlay. This must be supported by all drivers capable
	of simultaneous capturing and overlay. Optionally these drivers may
	also permit capturing and overlay with a single file descriptor for
	compatibility with V4L and earlier versions of V4L2.<footnote>
	<para>A common application of two file descriptors is the
	XFree86 <link linkend="xvideo">Xv/V4L</link> interface driver and
	a V4L2 application. While the X server controls video overlay, the
	application can take advantage of memory mapping and DMA.</para>
	<para>In the opinion of the designers of this API, no driver
	writer taking the efforts to support simultaneous capturing and
	overlay will restrict this ability by requiring a single file
	descriptor, as in V4L and earlier versions of V4L2. Making this
	optional means applications depending on two file descriptors need
	backup routines to be compatible with all drivers, which is
	considerable more work than using two fds in applications which do
	not. Also two fd's fit the general concept of one file descriptor for
	each logical stream. Hence as a complexity trade-off drivers
	<emphasis>must</emphasis> support two file descriptors and
	<emphasis>may</emphasis> support single fd operation.</para>
	</footnote></para>

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

	<para>Devices supporting the video overlay interface set the
	<constant>V4L2_CAP_VIDEO_OVERLAY</constant> flag in the
	<structfield>capabilities</structfield> field of &v4l2-capability;
	returned by the &VIDIOC-QUERYCAP; ioctl. The overlay I/O method specified
	below must be supported. Tuners and audio inputs are optional.</para>
	</section>

	<section>
	<title>Supplemental Functions</title>

	<para>Video overlay devices shall support <link
	linkend="audio">audio input</link>, <link
	linkend="tuner">tuner</link>, <link linkend="control">controls</link>,
	<link linkend="crop">cropping and scaling</link> and <link
	linkend="streaming-par">streaming parameter</link> ioctls as needed.
	The <link linkend="video">video input</link> and <link
	linkend="standard">video standard</link> ioctls must be supported by
	all video overlay devices.</para>
	</section>

	<section>
	<title>Setup</title>

	<para>Before overlay can commence applications must program the
	driver with frame buffer parameters, namely the address and size of
	the frame buffer and the image format, for example RGB 5:6:5. The
	&VIDIOC-G-FBUF; and &VIDIOC-S-FBUF; ioctls are available to get
	and set these parameters, respectively. The
	<constant>VIDIOC_S_FBUF</constant> ioctl is privileged because it
	allows to set up DMA into physical memory, bypassing the memory
	protection mechanisms of the kernel. Only the superuser can change the
	frame buffer address and size. Users are not supposed to run TV
	applications as root or with SUID bit set. A small helper application
	with suitable privileges should query the graphics system and program
	the V4L2 driver at the appropriate time.</para>

	<para>Some devices add the video overlay to the output signal
	of the graphics card. In this case the frame buffer is not modified by
	the video device, and the frame buffer address and pixel format are
	not needed by the driver. The <constant>VIDIOC_S_FBUF</constant> ioctl
	is not privileged. An application can check for this type of device by
	calling the <constant>VIDIOC_G_FBUF</constant> ioctl.</para>

	<para>A driver may support any (or none) of five clipping/blending
	methods:<orderedlist>
	<listitem>
	<para>Chroma-keying displays the overlaid image only where
	pixels in the primary graphics surface assume a certain color.</para>
	</listitem>
	<listitem>
	<para>A bitmap can be specified where each bit corresponds
	to a pixel in the overlaid image. When the bit is set, the
	corresponding video pixel is displayed, otherwise a pixel of the
	graphics surface.</para>
	</listitem>
	<listitem>
	<para>A list of clipping rectangles can be specified. In
	these regions <emphasis>no</emphasis> video is displayed, so the
	graphics surface can be seen here.</para>
	</listitem>
	<listitem>
	<para>The framebuffer has an alpha channel that can be used
	to clip or blend the framebuffer with the video.</para>
	</listitem>
	<listitem>
	<para>A global alpha value can be specified to blend the
	framebuffer contents with video images.</para>
	</listitem>
	</orderedlist></para>

	<para>When simultaneous capturing and overlay is supported and
	the hardware prohibits different image and frame buffer formats, the
	format requested first takes precedence. The attempt to capture
	(&VIDIOC-S-FMT;) or overlay (&VIDIOC-S-FBUF;) may fail with an
	&EBUSY; or return accordingly modified parameters..</para>
	</section>

	<section>
	<title>Overlay Window</title>

	<para>The overlaid image is determined by cropping and overlay
	window parameters. The former select an area of the video picture to
	capture, the latter how images are overlaid and clipped. Cropping
	initialization at minimum requires to reset the parameters to
	defaults. An example is given in <xref linkend="crop" />.</para>

	<para>The overlay window is described by a &v4l2-window;. It
	defines the size of the image, its position over the graphics surface
	and the clipping to be applied. To get the current parameters
	applications set the <structfield>type</structfield> field of a
	&v4l2-format; to <constant>V4L2_BUF_TYPE_VIDEO_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 overlay window applications set the
	<structfield>type</structfield> field of a &v4l2-format; to
	<constant>V4L2_BUF_TYPE_VIDEO_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>The scaling factor of the overlaid image is implied by the
	width and height given in &v4l2-window; and the size of the cropping
	rectangle. For more information see <xref linkend="crop" />.</para>

	<para>When simultaneous capturing and overlay is supported and
	the hardware prohibits different image and window sizes, the size
	requested first takes precedence. The attempt to capture or overlay as
	well (&VIDIOC-S-FMT;) may fail with an &EBUSY; or return accordingly
	modified parameters.</para>

	<table pgwide="1" frame="none" id="v4l2-window">
	<title>struct <structname>v4l2_window</structname></title>
	<tgroup cols="3">
	&cs-str;
	<tbody valign="top">
	<row>
	<entry>&v4l2-rect;</entry>
	<entry><structfield>w</structfield></entry>
	<entry>Size and position of the window relative to the
	top, left corner of the frame buffer defined with &VIDIOC-S-FBUF;. The
	window can extend the frame buffer width and height, the
	<structfield>x</structfield> and <structfield>y</structfield>
	coordinates can be negative, and it can lie completely outside the
	frame buffer. The driver clips the window accordingly, or if that is
	not possible, modifies its size and/or position.</entry>
	</row>
	<row>
	<entry>&v4l2-field;</entry>
	<entry><structfield>field</structfield></entry>
	<entry>Applications set this field to determine which
	video field shall be overlaid, typically one of
	<constant>V4L2_FIELD_ANY</constant> (0),
	<constant>V4L2_FIELD_TOP</constant>,
	<constant>V4L2_FIELD_BOTTOM</constant> or
	<constant>V4L2_FIELD_INTERLACED</constant>. Drivers may have to choose
	a different field order and return the actual setting here.</entry>
	</row>
	<row>
	<entry>__u32</entry>
	<entry><structfield>chromakey</structfield></entry>
	<entry>When chroma-keying has been negotiated with
	&VIDIOC-S-FBUF; applications set this field to the desired pixel value
	for the chroma key. The format is the same as the pixel format of the
	framebuffer (&v4l2-framebuffer;
	<structfield>fmt.pixelformat</structfield> field), with bytes in host
	order. E. g. for <link
	linkend="V4L2-PIX-FMT-BGR32"><constant>V4L2_PIX_FMT_BGR24</constant></link>
	the value should be 0xRRGGBB on a little endian, 0xBBGGRR on a big
	endian host.</entry>
	</row>
	<row>
	<entry>&v4l2-clip; *</entry>
	<entry><structfield>clips</structfield></entry>
	<entry>When chroma-keying has <emphasis>not</emphasis>
	been negotiated and &VIDIOC-G-FBUF; indicated this capability,
	applications can set this field to point to an array of
	clipping rectangles.</entry>
	</row>
	<row>
	<entry></entry>
	<entry></entry>
	<entry>Like the window coordinates
	<structfield>w</structfield>, clipping rectangles are defined relative
	to the top, left corner of the frame buffer. However clipping
	rectangles must not extend the frame buffer width and height, and they
	must not overlap. If possible applications should merge adjacent
	rectangles. Whether this must create x-y or y-x bands, or the order of
	rectangles, is not defined. When clip lists are not supported the
	driver ignores this field. Its contents after calling &VIDIOC-S-FMT;
	are undefined.</entry>
	</row>
	<row>
	<entry>__u32</entry>
	<entry><structfield>clipcount</structfield></entry>
	<entry>When the application set the
	<structfield>clips</structfield> field, this field must contain the
	number of clipping rectangles in the list. When clip lists are not
	supported the driver ignores this field, its contents after calling
	<constant>VIDIOC_S_FMT</constant> are undefined. When clip lists are
	supported but no clipping is desired this field must be set to
	zero.</entry>
	</row>
	<row>
	<entry>void *</entry>
	<entry><structfield>bitmap</structfield></entry>
	<entry>When chroma-keying has
	<emphasis>not</emphasis> been negotiated and &VIDIOC-G-FBUF; indicated
	this capability, applications can set this field to point to a
	clipping bit mask.</entry>
	</row>
	<row>
	<entry spanname="hspan"><para>It must be of the same size
	as the window, <structfield>w.width</structfield> and
	<structfield>w.height</structfield>. Each bit corresponds to a pixel
	in the overlaid image, which is displayed only when the bit is
	<emphasis>set</emphasis>. Pixel coordinates translate to bits like:
	<programlisting>
	((__u8 ) <structfield>bitmap</structfield>)[<structfield>w.width</structfield> y + x / 8] & (1 << (x & 7))</programlisting></para><para>where <structfield>0</structfield> ≤ x <
	<structfield>w.width</structfield> and <structfield>0</structfield> ≤
	y <<structfield>w.height</structfield>.<footnote>
	<para>Should we require
	<structfield>w.width</structfield> to be a multiple of
	eight?</para>
	</footnote></para><para>When a clipping
	bit mask is not supported the driver ignores this field, its contents
	after calling &VIDIOC-S-FMT; are undefined. When a bit mask is supported
	but no clipping is desired this field must be set to
	<constant>NULL</constant>.</para><para>Applications need not create a
	clip list or bit mask. When they pass both, or despite negotiating
	chroma-keying, the results are undefined. Regardless of the chosen
	method, the clipping abilities of the hardware may be limited in
	quantity or quality. The results when these limits are exceeded are
	undefined.<footnote>
	<para>When the image is written into frame buffer
	memory it will be undesirable if the driver clips out less pixels
	than expected, because the application and graphics system are not
	aware these regions need to be refreshed. The driver should clip out
	more pixels or not write the image at all.</para>
	</footnote></para></entry>
	</row>
	<row>
	<entry>__u8</entry>
	<entry><structfield>global_alpha</structfield></entry>
	<entry>The global alpha value used to blend the
	framebuffer with video images, if global alpha blending has been
	negotiated (<constant>V4L2_FBUF_FLAG_GLOBAL_ALPHA</constant>, see
	&VIDIOC-S-FBUF;, <xref linkend="framebuffer-flags" />).</entry>
	</row>
	<row>
	<entry></entry>
	<entry></entry>
	<entry>Note this field was added in Linux 2.6.23, extending the structure. However
	the <link linkend="vidioc-g-fmt">VIDIOC_G/S/TRY_FMT</link> ioctls,
	which take a pointer to a <link
	linkend="v4l2-format">v4l2_format</link> parent structure with padding
	bytes at the end, are not affected.</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<table pgwide="1" frame="none" id="v4l2-clip">
	<title>struct <structname>v4l2_clip</structname><footnote>
	<para>The X Window system defines "regions" which are
	vectors of struct BoxRec { short x1, y1, x2, y2; } with width = x2 -
	x1 and height = y2 - y1, so one cannot pass X11 clip lists
	directly.</para>
	</footnote></title>
	<tgroup cols="3">
	&cs-str;
	<tbody valign="top">
	<row>
	<entry>&v4l2-rect;</entry>
	<entry><structfield>c</structfield></entry>
	<entry>Coordinates of the clipping rectangle, relative to
	the top, left corner of the frame buffer. Only window pixels
	<emphasis>outside</emphasis> all clipping rectangles are
	displayed.</entry>
	</row>
	<row>
	<entry>&v4l2-clip; *</entry>
	<entry><structfield>next</structfield></entry>
	<entry>Pointer to the next clipping rectangle, NULL when
	this is the last rectangle. Drivers ignore this field, it cannot be
	used to pass a linked list of clipping rectangles.</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<!-- NB for easier reading this table is duplicated
	in the vidioc-cropcap chapter.-->

	<table pgwide="1" frame="none" id="v4l2-rect">
	<title>struct <structname>v4l2_rect</structname></title>
	<tgroup cols="3">
	&cs-str;
	<tbody valign="top">
	<row>
	<entry>__s32</entry>
	<entry><structfield>left</structfield></entry>
	<entry>Horizontal offset of the top, left corner of the
	rectangle, in pixels.</entry>
	</row>
	<row>
	<entry>__s32</entry>
	<entry><structfield>top</structfield></entry>
	<entry>Vertical offset of the top, left corner of the
	rectangle, in pixels. Offsets increase to the right and down.</entry>
	</row>
	<row>
	<entry>__s32</entry>
	<entry><structfield>width</structfield></entry>
	<entry>Width of the rectangle, in pixels.</entry>
	</row>
	<row>
	<entry>__s32</entry>
	<entry><structfield>height</structfield></entry>
	<entry>Height of the rectangle, in pixels. Width and
	height cannot be negative, the fields are signed for hysterical
	reasons. <!-- video4linux-list@redhat.com on 22 Oct 2002 subject
	"Re:[V4L][patches!] Re:v4l2/kernel-2.5" --></entry>
	</row>
	</tbody>
	</tgroup>
	</table>
	</section>

	<section>
	<title>Enabling Overlay</title>

	<para>To start or stop the frame buffer overlay applications call
	the &VIDIOC-OVERLAY; ioctl.</para>
	</section>