Mercurial > vloopback

comparison vloopback.html @ 0:5f21a4dddc0c

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Initial checkin
author KennethLavrsen
date Sun, 01 Apr 2007 05:22:43 +0000
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:5f21a4dddc0c
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>