|
0
|
1 <HTML>
|
|
|
2 <HEAD>
|
|
|
3 <TITLE>
|
|
|
4 Video4Linux loopback API
|
|
|
5 </TITLE>
|
|
|
6 <H1>
|
|
|
7 Video4Linux loopback API
|
|
|
8 </H1>
|
|
|
9 </HEAD>
|
|
|
10 <BODY bgcolor="white">
|
|
|
11 <P>
|
|
|
12 Author: Jeroen Vreeken (pe1rxq@amsat.org)<BR>
|
|
|
13 Version: 0.90<BR>
|
|
|
14 Date: 31-01-2001<BR>
|
|
|
15 </P>
|
|
|
16 <P>
|
|
|
17 <H2>
|
|
|
18 Introduction:
|
|
|
19 </H2>
|
|
|
20 This document describes the API for the Video4Linux loopback driver.
|
|
|
21 The driver implements a video pipe using two video4linux devices.
|
|
|
22 The first device is used by the program supplying the data,
|
|
|
23 from now on this program will be refered to with <I>'pusher'</I>.<BR>
|
|
|
24 The second device acts as if it were a normall video4linux device,
|
|
|
25 it should be usable by any application that honours the video4linux
|
|
|
26 specifications. This application will from now on be refered to as
|
|
|
27 <I>'client'</I>.<BR>
|
|
|
28 The calls and ioctls mentioned in this document refer to those
|
|
|
29 as described in the Video4Linux API.
|
|
|
30 <BR>
|
|
|
31 The loopback device has two operating modes:
|
|
|
32 <UL>
|
|
|
33 <LI>
|
|
|
34 A simple one-copy mode in which <I>pusher</I> specifies the
|
|
|
35 size of the images and the used palette and uses write to
|
|
|
36 push its images to the pipe.<BR>
|
|
|
37 This mode is mostly for feeding fixed size images without any
|
|
|
38 knowledge about <I>client</I>.
|
|
|
39 </LI>
|
|
|
40 <LI>
|
|
|
41 A zero-copy mode in which <I>pusher</I> regularly polls the
|
|
|
42 device if <I>client</I> does an ioctl.<BR>
|
|
|
43 In this mode <I>pusher</I> has almost complete control over the
|
|
|
44 devices behaviour and it will be mainly used to implement
|
|
|
45 complex multiple tuner/channel/size configurations.
|
|
|
46 With this mode it should be possible to use the Xvideo
|
|
|
47 extensions as normal video4linux capture devices.
|
|
|
48 </LI>
|
|
|
49 </UL>
|
|
|
50 </P>
|
|
|
51 <P align=left>
|
|
|
52 <H2>
|
|
|
53 Locating a free pipe
|
|
|
54 </H2>
|
|
|
55 In order to find an unused pipe <I>pusher</I> will have to scan
|
|
|
56 the contents of /proc/video/vloopback/<BR>
|
|
|
57 Each pipe will have its own entry in the form of <I>vloopback0</I> to
|
|
|
58 <I>vloopbackN</I>, N being the total number of available pipes-1.<BR>
|
|
|
59 There will also be a general <I>vloopbacks</I> file which will contain
|
|
|
60 information on all entries.
|
|
|
61 <BR>
|
|
|
62 Each of these files will have references to the input and output
|
|
|
63 video device and will also indicate if either of them is currently
|
|
|
64 in use.<BR>
|
|
|
65 <BR>
|
|
|
66 Once <I>pusher</I> has found a free pipe it can claim it by simply
|
|
|
67 opening the input device.
|
|
|
68 </P>
|
|
|
69 <P align=left>
|
|
|
70 <H2>
|
|
|
71 One-copy mode
|
|
|
72 </H2>
|
|
|
73 In this mode <I>pusher</I> only has to provide images using the
|
|
|
74 <B>write()</B> call,
|
|
|
75 the driver will handle the communication with <I>client</I> or
|
|
|
76 will drop the images if the output is unused.
|
|
|
77 To <I>client</I> the device will closely resemble a webcam driver.<BR>
|
|
|
78 <BR>
|
|
|
79 In order to use it <I>pusher</I> will open the input device.
|
|
|
80 Before writing it will first have to set the palette it is going to use
|
|
|
81 by calling <B>VIDIOCSPICT</B>, and the size by calling
|
|
|
82 <B>VIDIOCSWIN</B>.
|
|
|
83 After this it can call <B>write()</B> for each frame it wants to send
|
|
|
84 to the pipe.<BR>
|
|
|
85 <BR>
|
|
|
86 When there is no application using the device the driver will simply
|
|
|
87 drop the frames which will result in a 'no-copy' situation while
|
|
|
88 writing to an unused pipe.<BR>
|
|
|
89 <I>Note: when client is using read() instead of mmap() the driver will
|
|
|
90 actually use a double copy.</I>
|
|
|
91 </P>
|
|
|
92 <P align=left>
|
|
|
93 <H2>
|
|
|
94 Zero-copy mode
|
|
|
95 </H2>
|
|
|
96 In this mode the driver will forward nearly all ioctls to
|
|
|
97 <I>pusher</I>.<BR>
|
|
|
98 <BR>
|
|
|
99 To initiate this mode <I>pusher</I> will have to call <B>mmap()</B>
|
|
|
100 with the size of the requested buffer.
|
|
|
101 The driver will allocate memory for this buffer and <I>pusher</I> will
|
|
|
102 gain access to it.<BR>
|
|
|
103 <I>Note: as the allocated memory might be in use by client, pusher is
|
|
|
104 NOT allowed to touch it under any circumstances with the only exeption
|
|
|
105 being between <B>VIDIOCMCAPTURE</B> and <B>VIDIOCSYNC</B>.</I><BR>
|
|
|
106 <BR>
|
|
|
107 <B>
|
|
|
108 Handling ioctls
|
|
|
109 </B><BR>
|
|
|
110 <BR>
|
|
|
111 When <I>client</I> has issued an ioctl <I>pusher</I> will receive a
|
|
|
112 <B>SIGIO</B> signal.
|
|
|
113 Pusher may check to see if it is comming from vloopback by calling
|
|
|
114 <B>poll()</B> first.
|
|
|
115 It then has to respond by calling <B>read()</B>
|
|
|
116 with a large enough buffer for the largest possible ioctl data
|
|
|
117 structure plus <B>sizeof(unsigned long int)</B>. <I>(The largest ioctl data structure is 280 bytes
|
|
|
118 in linux kernel 2.4.0-test10pre1, a buffer of 1024 bytes is recommended)
|
|
|
119 </I><BR>
|
|
|
120 The first bytes of this buffer will be the ioctl number.
|
|
|
121 This number is an unsigned long int, the remaining data is the data supplied by <I>client</I>.
|
|
|
122 <I>Pusher</I> will now have to handle this ioctl.<BR>
|
|
|
123 <BR>
|
|
|
124 If it is an ioctl requesting data <I>pusher</I> will answer it by
|
|
|
125 calling the ioctl with the requested data.<BR>
|
|
|
126 If it is an ioctl setting data <I>pusher</I> will call the ioctl with
|
|
|
127 the exact same data to accept it.<BR>
|
|
|
128 <BR>
|
|
|
129 <B>
|
|
|
130 Handling read
|
|
|
131 </B><BR>
|
|
|
132 <BR>
|
|
|
133 <I>Pusher</I> will not need to handle any read requests because the
|
|
|
134 kernel module will fake an mmap and sync call for it.<BR>
|
|
|
135 <BR>
|
|
|
136 <B>
|
|
|
137 Starting and stopping capture
|
|
|
138 </B><BR>
|
|
|
139 <BR>
|
|
|
140 The first time <B>VIDIOCMCAPTURE</B> is called <I>pusher</I> should
|
|
|
141 initialize capture and start capturing of the requested frames into
|
|
|
142 the mmapped buffer.<BR>
|
|
|
143 When <I>client</I> closes its device an 'ioctl' 0 will be send with
|
|
|
144 no data, <I>pusher</I> will tell the hardware to stop.
|
|
|
145 <BR>
|
|
|
146 </P>
|
|
|
147 </BODY>
|
|
|
148 </HTML> |
