v4lcapture.h
1//==========================================================================
2//
3// Project: libfg - Frame Grabber interface for Linux
4//
5// Module: Capture client interface
6//
7// Description: Provides a high-level C interface for controlling frame
8// grabber and TV tuner cards. Uses the Video 4 Linux API
9// (currently v1) and thus supports any V4L supported
10// device.
11//
12// Author: Gavin Baker <gavinb@antonym.org>
13//
14// Homepage: http://www.antonym.org/libfg
15//
16//--------------------------------------------------------------------------
17//
18// libfg - Frame Grabber interface for Linux
19// Copyright (c) 2002 Gavin Baker
20//
21// This library is free software; you can redistribute it and/or
22// modify it under the terms of the GNU Lesser General Public
23// License as published by the Free Software Foundation; either
24// version 2.1 of the License, or (at your option) any later version.
25//
26// This library is distributed in the hope that it will be useful,
27// but WITHOUT ANY WARRANTY; without even the implied warranty of
28// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
29// Lesser General Public License for more details.
30//
31// You should have received a copy of the GNU Lesser General Public
32// License along with this library; if not, write to the Free Software
33// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
34// or obtain a copy from the GNU website at http://www.gnu.org/
35//
36//==========================================================================
37
38#ifndef __V4LCAPTURE__H_
39#define __V4LCAPTURE__H_
40
41
42#ifdef __cplusplus
43extern "C"
44{
45#endif
46
47
48#include <stdio.h>
49#include <fcntl.h>
50#include <stdlib.h>
51#include <unistd.h>
52
53#include <sys/mman.h>
54#include <sys/ioctl.h>
55
56#if !defined (sun)
57 #include <linux/fs.h>
58 #include <linux/kernel.h>
59#endif
60#include <sys/types.h>
61#include <linux/videodev.h>
62
63#include "v4lframe.h"
64
65//==========================================================================
66// Definitions
67//==========================================================================
68
69#ifndef VIDEO_PALETTE_JPEG
70#define VIDEO_PALETTE_JPEG 21
71#endif
72
73// Standard device for fg_open()
74#define FG_DEFAULT_DEVICE "/dev/video0"
75
76// Normal capture size
77#define FG_DEFAULT_WIDTH 640
78#define FG_DEFAULT_HEIGHT 480
79
80// Percentage of a ushort
81#define FG_PERCENT(n) ((n)*65535/100)
82#define FG_50PC FG_PERCENT(50)
83
84// Default input sources
85#define FG_SOURCE_TV 0
86#define FG_SOURCE_COMPOSITE 1
87#define FG_SOURCE_SVIDEO 2
88
89
90//--------------------------------------------------------------------------
91//
92// Type: FRAMEGRABBER
93//
94// Description: Represents all information about a frame grabber
95// device. Returned by fg_open(), and used as the first
96// parameter for all other fg_*() calls.
97//
98//--------------------------------------------------------------------------
99typedef struct
100{
101 char* device; // Device name, eg. "/dev/video"
102 int fd; // File handle for open device
103 struct video_capability caps; // Capabilities
104 struct video_channel* sources; // Input sources (eg. TV, SVideo)
105 int source; // Currently selected source
106 struct video_tuner tuner; // TV or Radio tuner
107 struct video_window window; // Capture window
108 struct video_picture picture; // Picture controls (eg. bright)
109 struct video_mmap mmap; // Memory-mapped info
110 struct video_buffer fbuffer; // Frame buffer
111 struct video_mbuf mbuf; // Memory buffer #frames, offsets
112 void* mb_map; // Memory-mapped buffer
113 int cur_frame; // Currently capuring frame no.
114 int max_buffer; // Maximum number of frames to buffer
115
117
118
119
120//==========================================================================
121// Prototypes
122//==========================================================================
123
124
125//--------------------------------------------------------------------------
126//
127// Function: fg_open
128//
129// Description: Opens and initialises the frame grabber device with
130// some reasonable default values, and queries for all
131// capabilities.
132//
133// Parameters: char* dev Device name to open, eg. "/dev/video2"
134// or NULL for "/dev/video".
135//
136// Returns: FRAMEGRABBER* The open framegrabber device, or
137// NULL in the case of an error.
138//
139//--------------------------------------------------------------------------
140
141FRAMEGRABBER* fg_open( const char *dev );
142
143int fg_enable_capture( FRAMEGRABBER* fg, int flag );
144
145//--------------------------------------------------------------------------
146//
147// Function: fg_close
148//
149// Description: Closes an open framegrabber device, and releases all
150// memory allocated to it.
151//
152//--------------------------------------------------------------------------
153
154void fg_close( FRAMEGRABBER* fg );
155
156
157//--------------------------------------------------------------------------
158//
159// Function: fg_grab
160//
161// Description: Reads a frame from the capture device, allocating
162// a new FRAME instance and returning it.
163// Note that this is a *blocking* read, and thus will
164// wait until the next frame is ready.
165// The caller is responsible for doing a frame_release()
166// when done with the frame (to free memory).
167//
168// Returns: FRAME* The most recently captured frame
169// NULL On error
170//
171// Notes: This function blocks!
172//
173//--------------------------------------------------------------------------
174
175FRAME* fg_grab( FRAMEGRABBER* fg );
176
177int fg_read(FRAMEGRABBER * fg, FRAME * fr);
178
179//--------------------------------------------------------------------------
180//
181// Function: fg_grab_frame
182//
183// Description: Reads a frame from the capture device, using the
184// existing frame storage as passed in. Returns the
185// same instance, with the contents of the last frame.
186// Note that this is a *blocking* read, and thus will
187// wait until the next frame is ready.
188//
189// Parameters: FRAME* An existing frame
190//
191// Returns: FRAME* The most recently captured frame
192// NULL On error
193//
194// Notes: This function blocks!
195// The size *must* be correct!
196//
197//--------------------------------------------------------------------------
198
199FRAME* fg_grab_frame( FRAMEGRABBER* fg, FRAME* fr );
200
201
202//--------------------------------------------------------------------------
203//
204// Function: fg_set_source
205//
206// Description: Specifies the number of the video source to be used
207// for the input signal. For example, tuner, composite
208// or S/Video signal.
209//
210// Parameters: int src Source id (eg. FG_SOURCE_SVIDEO)
211//
212// Returns: 0 On success
213// -1 Failure
214//
215//--------------------------------------------------------------------------
216
217int fg_set_source( FRAMEGRABBER* fg, int src );
218
219
220//--------------------------------------------------------------------------
221//
222// Function: fg_set_source_norm
223//
224// Description: Specifies the video signal norm (eg. PAL, NTSC, SECAM)
225// for the current input source.
226//
227// Parameters: int norm Signal norm (eg. VIDEO_MODE_PAL)
228//
229// Returns: 0 On success
230// -1 Failure
231//
232//--------------------------------------------------------------------------
233
234int fg_set_source_norm( FRAMEGRABBER* fg, int norm );
235
236
237//--------------------------------------------------------------------------
238//
239// Function: fg_get_source_count
240//
241// Description: Returns the number of input sources available.
242//
243// Returns: >0 Sources (can be used in fg_set_source)
244//
245//--------------------------------------------------------------------------
246
247int fg_get_source_count( FRAMEGRABBER* fg );
248
249
250//--------------------------------------------------------------------------
251//
252// Function: fg_get_source_name
253//
254// Description: Returns a user-friendly name corresponding to the
255// supplied channel number.
256//
257// Parameters: int src Source id (eg. FG_SOURCE_TV)
258//
259// Returns: char* Name, like "Television"
260//
261//--------------------------------------------------------------------------
262
263char* fg_get_source_name( FRAMEGRABBER* fg, int src );
264
265
266//--------------------------------------------------------------------------
267//
268// Function: fg_set_channel
269//
270// Description: Sets the TV tuner to the specified frequency.
271//
272// Parameters: float freq Tuner frequency, in MHz
273//
274// Returns: 0 Success, tuned in
275// -1 Failure
276//
277//--------------------------------------------------------------------------
278
279int fg_set_channel( FRAMEGRABBER* fg, float freq );
280
281
282//--------------------------------------------------------------------------
283//
284// Function: fg_get_channel
285//
286// Description: Queries the current frequency of the TV tuner.
287//
288// Returns: float The frequency in MHz
289//
290//--------------------------------------------------------------------------
291
292float fg_get_channel( FRAMEGRABBER* fg );
293
294
295//--------------------------------------------------------------------------
296//
297// Function: fg_set_format
298//
299// Description: Specifies the capture format to use. Must be one of
300// the VIDEO_PALETTE_* flags.
301//
302// Notes: Currently only RGB32 and RGB24 are properly supported.
303//
304// Returns: 0 Success
305//
306//--------------------------------------------------------------------------
307
308int fg_set_format( FRAMEGRABBER* fg, int fmt );
309
310//--------------------------------------------------------------------------
311//
312// Function: fg_set_capture_window
313//
314// Description: Specifies a sub-window of the input source to capture.
315//
316// Parameters: int x }
317// int y } A window that is smaller than
318// int width } or equal to the capture window
319// int height }
320//
321// Returns: 0 Success
322// -1 Failure
323//
324//--------------------------------------------------------------------------
325
326int fg_set_capture_window( FRAMEGRABBER* fg,
327 int x, int y, int width, int height );
328
329
330//--------------------------------------------------------------------------
331//
332// Function: fg_set_brightness
333//
334// Description: Sets the picture brightness to the specified value.
335//
336// Parameters: int br Brightness (integer value)
337//
338// Returns: 0 Success
339// -1 Failure
340//
341//--------------------------------------------------------------------------
342
343int fg_set_brightness( FRAMEGRABBER* fg, int br );
344
345
346//--------------------------------------------------------------------------
347//
348// Function: fg_set_contrast
349//
350// Description: Sets the picture contrast to the specified value.
351//
352// Parameters: int ct Contrast (integer value)
353//
354// Returns: 0 Success
355// -1 Failure
356//
357//--------------------------------------------------------------------------
358
359int fg_set_contrast( FRAMEGRABBER* fg, int ct );
360
361int fg_set_hue( FRAMEGRABBER* fg, int hue );
362int fg_set_colour( FRAMEGRABBER* fg, int clr );
363
364//--------------------------------------------------------------------------
365//
366// Function: fg_new_compatible_frame
367//
368// Description: Returns a newly allocated frame that is compatible with
369// the current frame grabber settings; that is, the window
370// width and height, and the capture format. This frame
371// must be deleted by the caller with frame_release().
372//
373// Returns: FRAME* A new frame
374//
375//--------------------------------------------------------------------------
376
377FRAME* fg_new_compatible_frame( FRAMEGRABBER* fg );
378
379
380//--------------------------------------------------------------------------
381//
382// Function: fg_dump_info
383//
384// Description: Dumps to the console on stdout all the status
385// information available for the framegrabber.
386//
387//--------------------------------------------------------------------------
388
389void fg_dump_info( FRAMEGRABBER* fg );
390
391
392//==========================================================================
393
394#ifdef __cplusplus
395}
396#endif
397
398#endif /* __CAPTURE__H_ */
Definition v4lcapture.h:100
Definition v4lframe.h:64