v4lcapture.h
00001 //========================================================================== 00002 // 00003 // Project: libfg - Frame Grabber interface for Linux 00004 // 00005 // Module: Capture client interface 00006 // 00007 // Description: Provides a high-level C interface for controlling frame 00008 // grabber and TV tuner cards. Uses the Video 4 Linux API 00009 // (currently v1) and thus supports any V4L supported 00010 // device. 00011 // 00012 // Author: Gavin Baker <gavinb@antonym.org> 00013 // 00014 // Homepage: http://www.antonym.org/libfg 00015 // 00016 //-------------------------------------------------------------------------- 00017 // 00018 // libfg - Frame Grabber interface for Linux 00019 // Copyright (c) 2002 Gavin Baker 00020 // 00021 // This library is free software; you can redistribute it and/or 00022 // modify it under the terms of the GNU Lesser General Public 00023 // License as published by the Free Software Foundation; either 00024 // version 2.1 of the License, or (at your option) any later version. 00025 // 00026 // This library is distributed in the hope that it will be useful, 00027 // but WITHOUT ANY WARRANTY; without even the implied warranty of 00028 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 00029 // Lesser General Public License for more details. 00030 // 00031 // You should have received a copy of the GNU Lesser General Public 00032 // License along with this library; if not, write to the Free Software 00033 // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 00034 // or obtain a copy from the GNU website at http://www.gnu.org/ 00035 // 00036 //========================================================================== 00037 00038 #ifndef __V4LCAPTURE__H_ 00039 #define __V4LCAPTURE__H_ 00040 00041 00042 #ifdef __cplusplus 00043 extern "C" 00044 { 00045 #endif 00046 00047 00048 #include <stdio.h> 00049 #include <fcntl.h> 00050 #include <stdlib.h> 00051 #include <unistd.h> 00052 00053 #include <sys/mman.h> 00054 #include <sys/ioctl.h> 00055 00056 #if !defined (sun) 00057 #include <linux/fs.h> 00058 #include <linux/kernel.h> 00059 #endif 00060 #include <sys/types.h> 00061 #include <linux/videodev.h> 00062 00063 #include "v4lframe.h" 00064 00065 //========================================================================== 00066 // Definitions 00067 //========================================================================== 00068 00069 #ifndef VIDEO_PALETTE_JPEG 00070 #define VIDEO_PALETTE_JPEG 21 00071 #endif 00072 00073 // Standard device for fg_open() 00074 #define FG_DEFAULT_DEVICE "/dev/video0" 00075 00076 // Normal capture size 00077 #define FG_DEFAULT_WIDTH 640 00078 #define FG_DEFAULT_HEIGHT 480 00079 00080 // Percentage of a ushort 00081 #define FG_PERCENT(n) ((n)*65535/100) 00082 #define FG_50PC FG_PERCENT(50) 00083 00084 // Default input sources 00085 #define FG_SOURCE_TV 0 00086 #define FG_SOURCE_COMPOSITE 1 00087 #define FG_SOURCE_SVIDEO 2 00088 00089 00090 //-------------------------------------------------------------------------- 00091 // 00092 // Type: FRAMEGRABBER 00093 // 00094 // Description: Represents all information about a frame grabber 00095 // device. Returned by fg_open(), and used as the first 00096 // parameter for all other fg_*() calls. 00097 // 00098 //-------------------------------------------------------------------------- 00099 typedef struct 00100 { 00101 char* device; // Device name, eg. "/dev/video" 00102 int fd; // File handle for open device 00103 struct video_capability caps; // Capabilities 00104 struct video_channel* sources; // Input sources (eg. TV, SVideo) 00105 int source; // Currently selected source 00106 struct video_tuner tuner; // TV or Radio tuner 00107 struct video_window window; // Capture window 00108 struct video_picture picture; // Picture controls (eg. bright) 00109 struct video_mmap mmap; // Memory-mapped info 00110 struct video_buffer fbuffer; // Frame buffer 00111 struct video_mbuf mbuf; // Memory buffer #frames, offsets 00112 void* mb_map; // Memory-mapped buffer 00113 int cur_frame; // Currently capuring frame no. 00114 int max_buffer; // Maximum number of frames to buffer 00115 00116 } FRAMEGRABBER; 00117 00118 00119 00120 //========================================================================== 00121 // Prototypes 00122 //========================================================================== 00123 00124 00125 //-------------------------------------------------------------------------- 00126 // 00127 // Function: fg_open 00128 // 00129 // Description: Opens and initialises the frame grabber device with 00130 // some reasonable default values, and queries for all 00131 // capabilities. 00132 // 00133 // Parameters: char* dev Device name to open, eg. "/dev/video2" 00134 // or NULL for "/dev/video". 00135 // 00136 // Returns: FRAMEGRABBER* The open framegrabber device, or 00137 // NULL in the case of an error. 00138 // 00139 //-------------------------------------------------------------------------- 00140 00141 FRAMEGRABBER* fg_open( const char *dev ); 00142 00143 int fg_enable_capture( FRAMEGRABBER* fg, int flag ); 00144 00145 //-------------------------------------------------------------------------- 00146 // 00147 // Function: fg_close 00148 // 00149 // Description: Closes an open framegrabber device, and releases all 00150 // memory allocated to it. 00151 // 00152 //-------------------------------------------------------------------------- 00153 00154 void fg_close( FRAMEGRABBER* fg ); 00155 00156 00157 //-------------------------------------------------------------------------- 00158 // 00159 // Function: fg_grab 00160 // 00161 // Description: Reads a frame from the capture device, allocating 00162 // a new FRAME instance and returning it. 00163 // Note that this is a *blocking* read, and thus will 00164 // wait until the next frame is ready. 00165 // The caller is responsible for doing a frame_release() 00166 // when done with the frame (to free memory). 00167 // 00168 // Returns: FRAME* The most recently captured frame 00169 // NULL On error 00170 // 00171 // Notes: This function blocks! 00172 // 00173 //-------------------------------------------------------------------------- 00174 00175 FRAME* fg_grab( FRAMEGRABBER* fg ); 00176 00177 int fg_read(FRAMEGRABBER * fg, FRAME * fr); 00178 00179 //-------------------------------------------------------------------------- 00180 // 00181 // Function: fg_grab_frame 00182 // 00183 // Description: Reads a frame from the capture device, using the 00184 // existing frame storage as passed in. Returns the 00185 // same instance, with the contents of the last frame. 00186 // Note that this is a *blocking* read, and thus will 00187 // wait until the next frame is ready. 00188 // 00189 // Parameters: FRAME* An existing frame 00190 // 00191 // Returns: FRAME* The most recently captured frame 00192 // NULL On error 00193 // 00194 // Notes: This function blocks! 00195 // The size *must* be correct! 00196 // 00197 //-------------------------------------------------------------------------- 00198 00199 FRAME* fg_grab_frame( FRAMEGRABBER* fg, FRAME* fr ); 00200 00201 00202 //-------------------------------------------------------------------------- 00203 // 00204 // Function: fg_set_source 00205 // 00206 // Description: Specifies the number of the video source to be used 00207 // for the input signal. For example, tuner, composite 00208 // or S/Video signal. 00209 // 00210 // Parameters: int src Source id (eg. FG_SOURCE_SVIDEO) 00211 // 00212 // Returns: 0 On success 00213 // -1 Failure 00214 // 00215 //-------------------------------------------------------------------------- 00216 00217 int fg_set_source( FRAMEGRABBER* fg, int src ); 00218 00219 00220 //-------------------------------------------------------------------------- 00221 // 00222 // Function: fg_set_source_norm 00223 // 00224 // Description: Specifies the video signal norm (eg. PAL, NTSC, SECAM) 00225 // for the current input source. 00226 // 00227 // Parameters: int norm Signal norm (eg. VIDEO_MODE_PAL) 00228 // 00229 // Returns: 0 On success 00230 // -1 Failure 00231 // 00232 //-------------------------------------------------------------------------- 00233 00234 int fg_set_source_norm( FRAMEGRABBER* fg, int norm ); 00235 00236 00237 //-------------------------------------------------------------------------- 00238 // 00239 // Function: fg_get_source_count 00240 // 00241 // Description: Returns the number of input sources available. 00242 // 00243 // Returns: >0 Sources (can be used in fg_set_source) 00244 // 00245 //-------------------------------------------------------------------------- 00246 00247 int fg_get_source_count( FRAMEGRABBER* fg ); 00248 00249 00250 //-------------------------------------------------------------------------- 00251 // 00252 // Function: fg_get_source_name 00253 // 00254 // Description: Returns a user-friendly name corresponding to the 00255 // supplied channel number. 00256 // 00257 // Parameters: int src Source id (eg. FG_SOURCE_TV) 00258 // 00259 // Returns: char* Name, like "Television" 00260 // 00261 //-------------------------------------------------------------------------- 00262 00263 char* fg_get_source_name( FRAMEGRABBER* fg, int src ); 00264 00265 00266 //-------------------------------------------------------------------------- 00267 // 00268 // Function: fg_set_channel 00269 // 00270 // Description: Sets the TV tuner to the specified frequency. 00271 // 00272 // Parameters: float freq Tuner frequency, in MHz 00273 // 00274 // Returns: 0 Success, tuned in 00275 // -1 Failure 00276 // 00277 //-------------------------------------------------------------------------- 00278 00279 int fg_set_channel( FRAMEGRABBER* fg, float freq ); 00280 00281 00282 //-------------------------------------------------------------------------- 00283 // 00284 // Function: fg_get_channel 00285 // 00286 // Description: Queries the current frequency of the TV tuner. 00287 // 00288 // Returns: float The frequency in MHz 00289 // 00290 //-------------------------------------------------------------------------- 00291 00292 float fg_get_channel( FRAMEGRABBER* fg ); 00293 00294 00295 //-------------------------------------------------------------------------- 00296 // 00297 // Function: fg_set_format 00298 // 00299 // Description: Specifies the capture format to use. Must be one of 00300 // the VIDEO_PALETTE_* flags. 00301 // 00302 // Notes: Currently only RGB32 and RGB24 are properly supported. 00303 // 00304 // Returns: 0 Success 00305 // 00306 //-------------------------------------------------------------------------- 00307 00308 int fg_set_format( FRAMEGRABBER* fg, int fmt ); 00309 00310 //-------------------------------------------------------------------------- 00311 // 00312 // Function: fg_set_capture_window 00313 // 00314 // Description: Specifies a sub-window of the input source to capture. 00315 // 00316 // Parameters: int x } 00317 // int y } A window that is smaller than 00318 // int width } or equal to the capture window 00319 // int height } 00320 // 00321 // Returns: 0 Success 00322 // -1 Failure 00323 // 00324 //-------------------------------------------------------------------------- 00325 00326 int fg_set_capture_window( FRAMEGRABBER* fg, 00327 int x, int y, int width, int height ); 00328 00329 00330 //-------------------------------------------------------------------------- 00331 // 00332 // Function: fg_set_brightness 00333 // 00334 // Description: Sets the picture brightness to the specified value. 00335 // 00336 // Parameters: int br Brightness (integer value) 00337 // 00338 // Returns: 0 Success 00339 // -1 Failure 00340 // 00341 //-------------------------------------------------------------------------- 00342 00343 int fg_set_brightness( FRAMEGRABBER* fg, int br ); 00344 00345 00346 //-------------------------------------------------------------------------- 00347 // 00348 // Function: fg_set_contrast 00349 // 00350 // Description: Sets the picture contrast to the specified value. 00351 // 00352 // Parameters: int ct Contrast (integer value) 00353 // 00354 // Returns: 0 Success 00355 // -1 Failure 00356 // 00357 //-------------------------------------------------------------------------- 00358 00359 int fg_set_contrast( FRAMEGRABBER* fg, int ct ); 00360 00361 int fg_set_hue( FRAMEGRABBER* fg, int hue ); 00362 int fg_set_colour( FRAMEGRABBER* fg, int clr ); 00363 00364 //-------------------------------------------------------------------------- 00365 // 00366 // Function: fg_new_compatible_frame 00367 // 00368 // Description: Returns a newly allocated frame that is compatible with 00369 // the current frame grabber settings; that is, the window 00370 // width and height, and the capture format. This frame 00371 // must be deleted by the caller with frame_release(). 00372 // 00373 // Returns: FRAME* A new frame 00374 // 00375 //-------------------------------------------------------------------------- 00376 00377 FRAME* fg_new_compatible_frame( FRAMEGRABBER* fg ); 00378 00379 00380 //-------------------------------------------------------------------------- 00381 // 00382 // Function: fg_dump_info 00383 // 00384 // Description: Dumps to the console on stdout all the status 00385 // information available for the framegrabber. 00386 // 00387 //-------------------------------------------------------------------------- 00388 00389 void fg_dump_info( FRAMEGRABBER* fg ); 00390 00391 00392 //========================================================================== 00393 00394 #ifdef __cplusplus 00395 } 00396 #endif 00397 00398 #endif /* __CAPTURE__H_ */