← Back to branch summary

~ubuntu-branches/ubuntu/trusty/linux-armadaxp/trusty

« back to all changes in this revision

Viewing changes to Documentation/DocBook/v4l/dev-overlay.xml

  • Committer: Package Import Robot
  • Author(s): Michael Casadevall, Bryan Wu, Dann Frazier, Michael Casadeall
  • Date: 2012-03-10 15:00:54 UTC
  • mfrom: (1.1.1)
  • Revision ID: package-import@ubuntu.com-20120310150054-flugb39zon8vvgwe
Tags: 3.2.0-1600.1
[ Bryan Wu ]
* UBUNTU: import debian/debian.env and debian.armadaxp

[ Dann Frazier ]
* ARM: Armada XP: remove trailing '/' in dirnames in mvRules.mk

[ Michael Casadeall ]
* tools: add some tools for Marvell Armada XP processor
* kernel: timer tick hacking from Marvell
* kernel: Sheeva Errata: add delay on Sheeva when powering down
* net: add Marvell NFP netfilter
* net: socket and skb modifications made by Marvell
* miscdevice: add minor IDs for some Marvell Armada drivers
* fs: introduce memory pool for splice()
* video: EDID detection updates from Marvell Armada XP patchset
* video: backlight: add Marvell Dove LCD backlight driver
* video: display: add THS8200 display driver
* video: framebuffer: add Marvell Dove and Armada XP processor onchip LCD controller driver
* usbtest: add Interrupt transfer testing by Marvell Armada XP code
* usb: ehci: add support for Marvell EHCI controler
* tty/serial: 8250: add support for Marvell Armada XP processor and DeviceTree work
* rtc: add support for Marvell Armada XP onchip RTC controller
* net: pppoe: add Marvell ethernet NFP hook in PPPoE networking driver
* mtd: nand: add support for Marvell Armada XP Nand Flash Controller
* mtd: maps: add Marvell Armada XP specific map driver
* mmc: add support for Marvell Armada XP MMC/SD host controller
* i2c: add support for Marvell Armada XP onchip i2c bus controller
* hwmon: add Kconfig option for Armada XP onchip thermal sensor driver
* dmaengine: add Net DMA support for splice and update Marvell XOR DMA engine driver
* ata: add support for Marvell Armada XP SATA controller and update some quirks
* ARM: add Marvell Armada XP machine to mach-types
* ARM: oprofile: add support for Marvell PJ4B core
* ARM: mm: more ARMv6 switches for Marvell Armada XP
* ARM: remove static declaration to allow compilation
* ARM: alignment access fault trick
* ARM: mm: skip some fault fixing when run on NONE SMP ARMv6 mode during early abort event
* ARM: mm: add Marvell Sheeva CPU Architecture for PJ4B
* ARM: introduce optimized copy operation for Marvell Armada XP
* ARM: SAUCE: hardware breakpoint trick for Marvell Armada XP
* ARM: big endian and little endian tricks for Marvell Armada XP
* ARM: SAUCE: Add Marvell Armada XP build rules to arch/arm/kernel/Makefile
* ARM: vfp: add special handling for Marvell Armada XP
* ARM: add support for Marvell U-Boot
* ARM: add mv_controller_num for ARM PCI drivers
* ARM: add support for local PMUs, general SMP tweaks and cache flushing
* ARM: add Marvell device identifies in glue-proc.h
* ARM: add IPC driver support for Marvell platforms
* ARM: add DMA mapping for Marvell platforms
* ARM: add Sheeva errata and PJ4B code for booting
* ARM: update Kconfig and Makefile to include Marvell Armada XP platforms
* ARM: Armada XP: import LSP from Marvell for Armada XP 3.2 kernel enablement

Show diffs side-by-side

added added

removed removed

Lines of Context:
Documentation/DocBook/v4l/dev-overlay.xml
1
 
  <title>Video Overlay Interface</title>
2
 
  <subtitle>Also known as Framebuffer Overlay or Previewing</subtitle>
3
 
 
4
 
  <para>Video overlay devices have the ability to genlock (TV-)video
5
 
into the (VGA-)video signal of a graphics card, or to store captured
6
 
images directly in video memory of a graphics card, typically with
7
 
clipping. This can be considerable more efficient than capturing
8
 
images and displaying them by other means. In the old days when only
9
 
nuclear power plants needed cooling towers this used to be the only
10
 
way to put live video into a window.</para>
11
 
 
12
 
  <para>Video overlay devices are accessed through the same character
13
 
special files as <link linkend="capture">video capture</link> devices.
14
 
Note the default function of a <filename>/dev/video</filename> device
15
 
is video capturing. The overlay function is only available after
16
 
calling the &VIDIOC-S-FMT; ioctl.</para>
17
 
 
18
 
    <para>The driver may support simultaneous overlay and capturing
19
 
using the read/write and streaming I/O methods. If so, operation at
20
 
the nominal frame rate of the video standard is not guaranteed. Frames
21
 
may be directed away from overlay to capture, or one field may be used
22
 
for overlay and the other for capture if the capture parameters permit
23
 
this.</para>
24
 
 
25
 
  <para>Applications should use different file descriptors for
26
 
capturing and overlay. This must be supported by all drivers capable
27
 
of simultaneous capturing and overlay. Optionally these drivers may
28
 
also permit capturing and overlay with a single file descriptor for
29
 
compatibility with V4L and earlier versions of V4L2.<footnote>
30
 
        <para>A common application of two file descriptors is the
31
 
XFree86 <link linkend="xvideo">Xv/V4L</link> interface driver and
32
 
a V4L2 application. While the X server controls video overlay, the
33
 
application can take advantage of memory mapping and DMA.</para>
34
 
        <para>In the opinion of the designers of this API, no driver
35
 
writer taking the efforts to support simultaneous capturing and
36
 
overlay will restrict this ability by requiring a single file
37
 
descriptor, as in V4L and earlier versions of V4L2. Making this
38
 
optional means applications depending on two file descriptors need
39
 
backup routines to be compatible with all drivers, which is
40
 
considerable more work than using two fds in applications which do
41
 
not. Also two fd's fit the general concept of one file descriptor for
42
 
each logical stream. Hence as a complexity trade-off drivers
43
 
<emphasis>must</emphasis> support two file descriptors and
44
 
<emphasis>may</emphasis> support single fd operation.</para>
45
 
      </footnote></para>
46
 
 
47
 
  <section>
48
 
    <title>Querying Capabilities</title>
49
 
 
50
 
    <para>Devices supporting the video overlay interface set the
51
 
<constant>V4L2_CAP_VIDEO_OVERLAY</constant> flag in the
52
 
<structfield>capabilities</structfield> field of &v4l2-capability;
53
 
returned by the &VIDIOC-QUERYCAP; ioctl. The overlay I/O method specified
54
 
below must be supported. Tuners and audio inputs are optional.</para>
55
 
  </section>
56
 
 
57
 
  <section>
58
 
    <title>Supplemental Functions</title>
59
 
 
60
 
    <para>Video overlay devices shall support <link
61
 
linkend="audio">audio input</link>, <link
62
 
linkend="tuner">tuner</link>, <link linkend="control">controls</link>,
63
 
<link linkend="crop">cropping and scaling</link> and <link
64
 
linkend="streaming-par">streaming parameter</link> ioctls as needed.
65
 
The <link linkend="video">video input</link> and <link
66
 
linkend="standard">video standard</link> ioctls must be supported by
67
 
all video overlay devices.</para>
68
 
  </section>
69
 
 
70
 
  <section>
71
 
    <title>Setup</title>
72
 
 
73
 
    <para>Before overlay can commence applications must program the
74
 
driver with frame buffer parameters, namely the address and size of
75
 
the frame buffer and the image format, for example RGB 5:6:5. The
76
 
&VIDIOC-G-FBUF; and &VIDIOC-S-FBUF; ioctls are available to get
77
 
and set these parameters, respectively. The
78
 
<constant>VIDIOC_S_FBUF</constant> ioctl is privileged because it
79
 
allows to set up DMA into physical memory, bypassing the memory
80
 
protection mechanisms of the kernel. Only the superuser can change the
81
 
frame buffer address and size. Users are not supposed to run TV
82
 
applications as root or with SUID bit set. A small helper application
83
 
with suitable privileges should query the graphics system and program
84
 
the V4L2 driver at the appropriate time.</para>
85
 
 
86
 
    <para>Some devices add the video overlay to the output signal
87
 
of the graphics card. In this case the frame buffer is not modified by
88
 
the video device, and the frame buffer address and pixel format are
89
 
not needed by the driver. The <constant>VIDIOC_S_FBUF</constant> ioctl
90
 
is not privileged. An application can check for this type of device by
91
 
calling the <constant>VIDIOC_G_FBUF</constant> ioctl.</para>
92
 
 
93
 
    <para>A driver may support any (or none) of five clipping/blending
94
 
methods:<orderedlist>
95
 
        <listitem>
96
 
          <para>Chroma-keying displays the overlaid image only where
97
 
pixels in the primary graphics surface assume a certain color.</para>
98
 
        </listitem>
99
 
        <listitem>
100
 
          <para>A bitmap can be specified where each bit corresponds
101
 
to a pixel in the overlaid image. When the bit is set, the
102
 
corresponding video pixel is displayed, otherwise a pixel of the
103
 
graphics surface.</para>
104
 
        </listitem>
105
 
        <listitem>
106
 
          <para>A list of clipping rectangles can be specified. In
107
 
these regions <emphasis>no</emphasis> video is displayed, so the
108
 
graphics surface can be seen here.</para>
109
 
        </listitem>
110
 
        <listitem>
111
 
          <para>The framebuffer has an alpha channel that can be used
112
 
to clip or blend the framebuffer with the video.</para>
113
 
        </listitem>
114
 
        <listitem>
115
 
          <para>A global alpha value can be specified to blend the
116
 
framebuffer contents with video images.</para>
117
 
        </listitem>
118
 
      </orderedlist></para>
119
 
 
120
 
    <para>When simultaneous capturing and overlay is supported and
121
 
the hardware prohibits different image and frame buffer formats, the
122
 
format requested first takes precedence. The attempt to capture
123
 
(&VIDIOC-S-FMT;) or overlay (&VIDIOC-S-FBUF;) may fail with an
124
 
&EBUSY; or return accordingly modified parameters..</para>
125
 
  </section>
126
 
 
127
 
  <section>
128
 
    <title>Overlay Window</title>
129
 
 
130
 
    <para>The overlaid image is determined by cropping and overlay
131
 
window parameters. The former select an area of the video picture to
132
 
capture, the latter how images are overlaid and clipped. Cropping
133
 
initialization at minimum requires to reset the parameters to
134
 
defaults. An example is given in <xref linkend="crop" />.</para>
135
 
 
136
 
    <para>The overlay window is described by a &v4l2-window;. It
137
 
defines the size of the image, its position over the graphics surface
138
 
and the clipping to be applied. To get the current parameters
139
 
applications set the <structfield>type</structfield> field of a
140
 
&v4l2-format; to <constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant> and
141
 
call the &VIDIOC-G-FMT; ioctl. The driver fills the
142
 
<structname>v4l2_window</structname> substructure named
143
 
<structfield>win</structfield>. It is not possible to retrieve a
144
 
previously programmed clipping list or bitmap.</para>
145
 
 
146
 
    <para>To program the overlay window applications set the
147
 
<structfield>type</structfield> field of a &v4l2-format; to
148
 
<constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>, initialize the
149
 
<structfield>win</structfield> substructure and call the
150
 
&VIDIOC-S-FMT; ioctl. The driver adjusts the parameters against
151
 
hardware limits and returns the actual parameters as
152
 
<constant>VIDIOC_G_FMT</constant> does. Like
153
 
<constant>VIDIOC_S_FMT</constant>, the &VIDIOC-TRY-FMT; ioctl can be
154
 
used to learn about driver capabilities without actually changing
155
 
driver state. Unlike <constant>VIDIOC_S_FMT</constant> this also works
156
 
after the overlay has been enabled.</para>
157
 
 
158
 
    <para>The scaling factor of the overlaid image is implied by the
159
 
width and height given in &v4l2-window; and the size of the cropping
160
 
rectangle. For more information see <xref linkend="crop" />.</para>
161
 
 
162
 
    <para>When simultaneous capturing and overlay is supported and
163
 
the hardware prohibits different image and window sizes, the size
164
 
requested first takes precedence. The attempt to capture or overlay as
165
 
well (&VIDIOC-S-FMT;) may fail with an &EBUSY; or return accordingly
166
 
modified parameters.</para>
167
 
 
168
 
    <table pgwide="1" frame="none" id="v4l2-window">
169
 
      <title>struct <structname>v4l2_window</structname></title>
170
 
      <tgroup cols="3">
171
 
        &cs-str;
172
 
        <tbody valign="top">
173
 
          <row>
174
 
            <entry>&v4l2-rect;</entry>
175
 
            <entry><structfield>w</structfield></entry>
176
 
            <entry>Size and position of the window relative to the
177
 
top, left corner of the frame buffer defined with &VIDIOC-S-FBUF;. The
178
 
window can extend the frame buffer width and height, the
179
 
<structfield>x</structfield> and <structfield>y</structfield>
180
 
coordinates can be negative, and it can lie completely outside the
181
 
frame buffer. The driver clips the window accordingly, or if that is
182
 
not possible, modifies its size and/or position.</entry>
183
 
          </row>
184
 
          <row>
185
 
            <entry>&v4l2-field;</entry>
186
 
            <entry><structfield>field</structfield></entry>
187
 
            <entry>Applications set this field to determine which
188
 
video field shall be overlaid, typically one of
189
 
<constant>V4L2_FIELD_ANY</constant> (0),
190
 
<constant>V4L2_FIELD_TOP</constant>,
191
 
<constant>V4L2_FIELD_BOTTOM</constant> or
192
 
<constant>V4L2_FIELD_INTERLACED</constant>. Drivers may have to choose
193
 
a different field order and return the actual setting here.</entry>
194
 
            </row>
195
 
          <row>
196
 
            <entry>__u32</entry>
197
 
            <entry><structfield>chromakey</structfield></entry>
198
 
            <entry>When chroma-keying has been negotiated with
199
 
&VIDIOC-S-FBUF; applications set this field to the desired pixel value
200
 
for the chroma key. The format is the same as the pixel format of the
201
 
framebuffer (&v4l2-framebuffer;
202
 
<structfield>fmt.pixelformat</structfield> field), with bytes in host
203
 
order. E.&nbsp;g. for <link
204
 
linkend="V4L2-PIX-FMT-BGR32"><constant>V4L2_PIX_FMT_BGR24</constant></link>
205
 
the value should be 0xRRGGBB on a little endian, 0xBBGGRR on a big
206
 
endian host.</entry>
207
 
          </row>
208
 
          <row>
209
 
            <entry>&v4l2-clip; *</entry>
210
 
            <entry><structfield>clips</structfield></entry>
211
 
            <entry>When chroma-keying has <emphasis>not</emphasis>
212
 
been negotiated and &VIDIOC-G-FBUF; indicated this capability,
213
 
applications can set this field to point to an array of
214
 
clipping rectangles.</entry>
215
 
          </row>
216
 
          <row>
217
 
            <entry></entry>
218
 
            <entry></entry>
219
 
            <entry>Like the window coordinates
220
 
<structfield>w</structfield>, clipping rectangles are defined relative
221
 
to the top, left corner of the frame buffer. However clipping
222
 
rectangles must not extend the frame buffer width and height, and they
223
 
must not overlap. If possible applications should merge adjacent
224
 
rectangles. Whether this must create x-y or y-x bands, or the order of
225
 
rectangles, is not defined. When clip lists are not supported the
226
 
driver ignores this field. Its contents after calling &VIDIOC-S-FMT;
227
 
are undefined.</entry>
228
 
          </row>
229
 
          <row>
230
 
            <entry>__u32</entry>
231
 
            <entry><structfield>clipcount</structfield></entry>
232
 
            <entry>When the application set the
233
 
<structfield>clips</structfield> field, this field must contain the
234
 
number of clipping rectangles in the list. When clip lists are not
235
 
supported the driver ignores this field, its contents after calling
236
 
<constant>VIDIOC_S_FMT</constant> are undefined. When clip lists are
237
 
supported but no clipping is desired this field must be set to
238
 
zero.</entry>
239
 
          </row>
240
 
          <row>
241
 
            <entry>void *</entry>
242
 
            <entry><structfield>bitmap</structfield></entry>
243
 
            <entry>When chroma-keying has
244
 
<emphasis>not</emphasis> been negotiated and &VIDIOC-G-FBUF; indicated
245
 
this capability, applications can set this field to point to a
246
 
clipping bit mask.</entry>
247
 
          </row>
248
 
          <row>
249
 
            <entry spanname="hspan"><para>It must be of the same size
250
 
as the window, <structfield>w.width</structfield> and
251
 
<structfield>w.height</structfield>. Each bit corresponds to a pixel
252
 
in the overlaid image, which is displayed only when the bit is
253
 
<emphasis>set</emphasis>. Pixel coordinates translate to bits like:
254
 
<programlisting>
255
 
((__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;
256
 
<structfield>w.width</structfield> and <structfield>0</structfield> &le;
257
 
y &lt;<structfield>w.height</structfield>.<footnote>
258
 
                  <para>Should we require
259
 
              <structfield>w.width</structfield> to be a multiple of
260
 
              eight?</para>
261
 
                </footnote></para><para>When a clipping
262
 
bit mask is not supported the driver ignores this field, its contents
263
 
after calling &VIDIOC-S-FMT; are undefined. When a bit mask is supported
264
 
but no clipping is desired this field must be set to
265
 
<constant>NULL</constant>.</para><para>Applications need not create a
266
 
clip list or bit mask. When they pass both, or despite negotiating
267
 
chroma-keying, the results are undefined. Regardless of the chosen
268
 
method, the clipping abilities of the hardware may be limited in
269
 
quantity or quality. The results when these limits are exceeded are
270
 
undefined.<footnote>
271
 
                  <para>When the image is written into frame buffer
272
 
memory it will be undesirable if the driver clips out less pixels
273
 
than expected, because the application and graphics system are not
274
 
aware these regions need to be refreshed. The driver should clip out
275
 
more pixels or not write the image at all.</para>
276
 
                </footnote></para></entry>
277
 
          </row>
278
 
          <row>
279
 
            <entry>__u8</entry>
280
 
            <entry><structfield>global_alpha</structfield></entry>
281
 
            <entry>The global alpha value used to blend the
282
 
framebuffer with video images, if global alpha blending has been
283
 
negotiated (<constant>V4L2_FBUF_FLAG_GLOBAL_ALPHA</constant>, see
284
 
&VIDIOC-S-FBUF;, <xref linkend="framebuffer-flags" />).</entry>
285
 
          </row>
286
 
          <row>
287
 
            <entry></entry>
288
 
            <entry></entry>
289
 
            <entry>Note this field was added in Linux 2.6.23, extending the structure. However
290
 
the <link linkend="vidioc-g-fmt">VIDIOC_G/S/TRY_FMT</link> ioctls,
291
 
which take a pointer to a <link
292
 
linkend="v4l2-format">v4l2_format</link> parent structure with padding
293
 
bytes at the end, are not affected.</entry>
294
 
          </row>
295
 
        </tbody>
296
 
      </tgroup>
297
 
    </table>
298
 
 
299
 
    <table pgwide="1" frame="none" id="v4l2-clip">
300
 
      <title>struct <structname>v4l2_clip</structname><footnote>
301
 
          <para>The X Window system defines "regions" which are
302
 
vectors of struct BoxRec { short x1, y1, x2, y2; } with width = x2 -
303
 
x1 and height = y2 - y1, so one cannot pass X11 clip lists
304
 
directly.</para>
305
 
        </footnote></title>
306
 
      <tgroup cols="3">
307
 
        &cs-str;
308
 
        <tbody valign="top">
309
 
          <row>
310
 
            <entry>&v4l2-rect;</entry>
311
 
            <entry><structfield>c</structfield></entry>
312
 
            <entry>Coordinates of the clipping rectangle, relative to
313
 
the top, left corner of the frame buffer. Only window pixels
314
 
<emphasis>outside</emphasis> all clipping rectangles are
315
 
displayed.</entry>
316
 
          </row>
317
 
          <row>
318
 
            <entry>&v4l2-clip; *</entry>
319
 
            <entry><structfield>next</structfield></entry>
320
 
            <entry>Pointer to the next clipping rectangle, NULL when
321
 
this is the last rectangle. Drivers ignore this field, it cannot be
322
 
used to pass a linked list of clipping rectangles.</entry>
323
 
          </row>
324
 
        </tbody>
325
 
      </tgroup>
326
 
    </table>
327
 
 
328
 
    <!-- NB for easier reading this table is duplicated
329
 
    in the vidioc-cropcap chapter.-->
330
 
 
331
 
    <table pgwide="1" frame="none" id="v4l2-rect">
332
 
      <title>struct <structname>v4l2_rect</structname></title>
333
 
      <tgroup cols="3">
334
 
        &cs-str;
335
 
        <tbody valign="top">
336
 
          <row>
337
 
            <entry>__s32</entry>
338
 
            <entry><structfield>left</structfield></entry>
339
 
            <entry>Horizontal offset of the top, left corner of the
340
 
rectangle, in pixels.</entry>
341
 
          </row>
342
 
          <row>
343
 
            <entry>__s32</entry>
344
 
            <entry><structfield>top</structfield></entry>
345
 
            <entry>Vertical offset of the top, left corner of the
346
 
rectangle, in pixels. Offsets increase to the right and down.</entry>
347
 
          </row>
348
 
          <row>
349
 
            <entry>__s32</entry>
350
 
            <entry><structfield>width</structfield></entry>
351
 
            <entry>Width of the rectangle, in pixels.</entry>
352
 
          </row>
353
 
          <row>
354
 
            <entry>__s32</entry>
355
 
            <entry><structfield>height</structfield></entry>
356
 
            <entry>Height of the rectangle, in pixels. Width and
357
 
height cannot be negative, the fields are signed for hysterical
358
 
reasons. <!-- video4linux-list@redhat.com on 22 Oct 2002 subject
359
 
"Re:[V4L][patches!] Re:v4l2/kernel-2.5" --></entry>
360
 
          </row>
361
 
        </tbody>
362
 
      </tgroup>
363
 
    </table>
364
 
  </section>
365
 
 
366
 
  <section>
367
 
    <title>Enabling Overlay</title>
368
 
 
369
 
    <para>To start or stop the frame buffer overlay applications call
370
 
the &VIDIOC-OVERLAY; ioctl.</para>
371
 
  </section>
372
 
 
373
 
  <!--
374
 
Local Variables:
375
 
mode: sgml
376
 
sgml-parent-document: "v4l2.sgml"
377
 
indent-tabs-mode: nil
378
 
End:
379
 
  -->