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 #include <linux/fs.h> 00057 #include <linux/kernel.h> 00058 #include <linux/videodev.h> 00059 00060 #include "v4lframe.h" 00061 00062 //========================================================================== 00063 // Definitions 00064 //========================================================================== 00065 00066 #ifndef VIDEO_PALETTE_JPEG 00067 #define VIDEO_PALETTE_JPEG 21 00068 #endif 00069 00070 // Standard device for fg_open() 00071 #define FG_DEFAULT_DEVICE "/dev/video0" 00072 00073 // Normal capture size 00074 #define FG_DEFAULT_WIDTH 640 00075 #define FG_DEFAULT_HEIGHT 480 00076 00077 // Percentage of a ushort 00078 #define FG_PERCENT(n) ((n)*65535/100) 00079 #define FG_50PC FG_PERCENT(50) 00080 00081 // Default input sources 00082 #define FG_SOURCE_TV 0 00083 #define FG_SOURCE_COMPOSITE 1 00084 #define FG_SOURCE_SVIDEO 2 00085 00086 00087 //-------------------------------------------------------------------------- 00088 // 00089 // Type: FRAMEGRABBER 00090 // 00091 // Description: Represents all information about a frame grabber 00092 // device. Returned by fg_open(), and used as the first 00093 // parameter for all other fg_*() calls. 00094 // 00095 //-------------------------------------------------------------------------- 00096 typedef struct 00097 { 00098 char* device; // Device name, eg. "/dev/video" 00099 int fd; // File handle for open device 00100 struct video_capability caps; // Capabilities 00101 struct video_channel* sources; // Input sources (eg. TV, SVideo) 00102 int source; // Currently selected source 00103 struct video_tuner tuner; // TV or Radio tuner 00104 struct video_window window; // Capture window 00105 struct video_picture picture; // Picture controls (eg. bright) 00106 struct video_mmap mmap; // Memory-mapped info 00107 struct video_buffer fbuffer; // Frame buffer 00108 struct video_mbuf mbuf; // Memory buffer #frames, offsets 00109 void* mb_map; // Memory-mapped buffer 00110 int cur_frame; // Currently capuring frame no. 00111 int max_buffer; // Maximum number of frames to buffer 00112 00113 } FRAMEGRABBER; 00114 00115 00116 00117 //========================================================================== 00118 // Prototypes 00119 //========================================================================== 00120 00121 00122 //-------------------------------------------------------------------------- 00123 // 00124 // Function: fg_open 00125 // 00126 // Description: Opens and initialises the frame grabber device with 00127 // some reasonable default values, and queries for all 00128 // capabilities. 00129 // 00130 // Parameters: char* dev Device name to open, eg. "/dev/video2" 00131 // or NULL for "/dev/video". 00132 // 00133 // Returns: FRAMEGRABBER* The open framegrabber device, or 00134 // NULL in the case of an error. 00135 // 00136 //-------------------------------------------------------------------------- 00137 00138 FRAMEGRABBER* fg_open( const char *dev ); 00139 00140 int fg_enable_capture( FRAMEGRABBER* fg, int flag ); 00141 00142 //-------------------------------------------------------------------------- 00143 // 00144 // Function: fg_close 00145 // 00146 // Description: Closes an open framegrabber device, and releases all 00147 // memory allocated to it. 00148 // 00149 //-------------------------------------------------------------------------- 00150 00151 void fg_close( FRAMEGRABBER* fg ); 00152 00153 00154 //-------------------------------------------------------------------------- 00155 // 00156 // Function: fg_grab 00157 // 00158 // Description: Reads a frame from the capture device, allocating 00159 // a new FRAME instance and returning it. 00160 // Note that this is a *blocking* read, and thus will 00161 // wait until the next frame is ready. 00162 // The caller is responsible for doing a frame_release() 00163 // when done with the frame (to free memory). 00164 // 00165 // Returns: FRAME* The most recently captured frame 00166 // NULL On error 00167 // 00168 // Notes: This function blocks! 00169 // 00170 //-------------------------------------------------------------------------- 00171 00172 FRAME* fg_grab( FRAMEGRABBER* fg ); 00173 00174 int fg_read(FRAMEGRABBER * fg, FRAME * fr); 00175 00176 //-------------------------------------------------------------------------- 00177 // 00178 // Function: fg_grab_frame 00179 // 00180 // Description: Reads a frame from the capture device, using the 00181 // existing frame storage as passed in. Returns the 00182 // same instance, with the contents of the last frame. 00183 // Note that this is a *blocking* read, and thus will 00184 // wait until the next frame is ready. 00185 // 00186 // Parameters: FRAME* An existing frame 00187 // 00188 // Returns: FRAME* The most recently captured frame 00189 // NULL On error 00190 // 00191 // Notes: This function blocks! 00192 // The size *must* be correct! 00193 // 00194 //-------------------------------------------------------------------------- 00195 00196 FRAME* fg_grab_frame( FRAMEGRABBER* fg, FRAME* fr ); 00197 00198 00199 //-------------------------------------------------------------------------- 00200 // 00201 // Function: fg_set_source 00202 // 00203 // Description: Specifies the number of the video source to be used 00204 // for the input signal. For example, tuner, composite 00205 // or S/Video signal. 00206 // 00207 // Parameters: int src Source id (eg. FG_SOURCE_SVIDEO) 00208 // 00209 // Returns: 0 On success 00210 // -1 Failure 00211 // 00212 //-------------------------------------------------------------------------- 00213 00214 int fg_set_source( FRAMEGRABBER* fg, int src ); 00215 00216 00217 //-------------------------------------------------------------------------- 00218 // 00219 // Function: fg_set_source_norm 00220 // 00221 // Description: Specifies the video signal norm (eg. PAL, NTSC, SECAM) 00222 // for the current input source. 00223 // 00224 // Parameters: int norm Signal norm (eg. VIDEO_MODE_PAL) 00225 // 00226 // Returns: 0 On success 00227 // -1 Failure 00228 // 00229 //-------------------------------------------------------------------------- 00230 00231 int fg_set_source_norm( FRAMEGRABBER* fg, int norm ); 00232 00233 00234 //-------------------------------------------------------------------------- 00235 // 00236 // Function: fg_get_source_count 00237 // 00238 // Description: Returns the number of input sources available. 00239 // 00240 // Returns: >0 Sources (can be used in fg_set_source) 00241 // 00242 //-------------------------------------------------------------------------- 00243 00244 int fg_get_source_count( FRAMEGRABBER* fg ); 00245 00246 00247 //-------------------------------------------------------------------------- 00248 // 00249 // Function: fg_get_source_name 00250 // 00251 // Description: Returns a user-friendly name corresponding to the 00252 // supplied channel number. 00253 // 00254 // Parameters: int src Source id (eg. FG_SOURCE_TV) 00255 // 00256 // Returns: char* Name, like "Television" 00257 // 00258 //-------------------------------------------------------------------------- 00259 00260 char* fg_get_source_name( FRAMEGRABBER* fg, int src ); 00261 00262 00263 //-------------------------------------------------------------------------- 00264 // 00265 // Function: fg_set_channel 00266 // 00267 // Description: Sets the TV tuner to the specified frequency. 00268 // 00269 // Parameters: float freq Tuner frequency, in MHz 00270 // 00271 // Returns: 0 Success, tuned in 00272 // -1 Failure 00273 // 00274 //-------------------------------------------------------------------------- 00275 00276 int fg_set_channel( FRAMEGRABBER* fg, float freq ); 00277 00278 00279 //-------------------------------------------------------------------------- 00280 // 00281 // Function: fg_get_channel 00282 // 00283 // Description: Queries the current frequency of the TV tuner. 00284 // 00285 // Returns: float The frequency in MHz 00286 // 00287 //-------------------------------------------------------------------------- 00288 00289 float fg_get_channel( FRAMEGRABBER* fg ); 00290 00291 00292 //-------------------------------------------------------------------------- 00293 // 00294 // Function: fg_set_format 00295 // 00296 // Description: Specifies the capture format to use. Must be one of 00297 // the VIDEO_PALETTE_* flags. 00298 // 00299 // Notes: Currently only RGB32 and RGB24 are properly supported. 00300 // 00301 // Returns: 0 Success 00302 // 00303 //-------------------------------------------------------------------------- 00304 00305 int fg_set_format( FRAMEGRABBER* fg, int fmt ); 00306 00307 //-------------------------------------------------------------------------- 00308 // 00309 // Function: fg_set_capture_window 00310 // 00311 // Description: Specifies a sub-window of the input source to capture. 00312 // 00313 // Parameters: int x } 00314 // int y } A window that is smaller than 00315 // int width } or equal to the capture window 00316 // int height } 00317 // 00318 // Returns: 0 Success 00319 // -1 Failure 00320 // 00321 //-------------------------------------------------------------------------- 00322 00323 int fg_set_capture_window( FRAMEGRABBER* fg, 00324 int x, int y, int width, int height ); 00325 00326 00327 //-------------------------------------------------------------------------- 00328 // 00329 // Function: fg_set_brightness 00330 // 00331 // Description: Sets the picture brightness to the specified value. 00332 // 00333 // Parameters: int br Brightness (integer value) 00334 // 00335 // Returns: 0 Success 00336 // -1 Failure 00337 // 00338 //-------------------------------------------------------------------------- 00339 00340 int fg_set_brightness( FRAMEGRABBER* fg, int br ); 00341 00342 00343 //-------------------------------------------------------------------------- 00344 // 00345 // Function: fg_set_contrast 00346 // 00347 // Description: Sets the picture contrast to the specified value. 00348 // 00349 // Parameters: int ct Contrast (integer value) 00350 // 00351 // Returns: 0 Success 00352 // -1 Failure 00353 // 00354 //-------------------------------------------------------------------------- 00355 00356 int fg_set_contrast( FRAMEGRABBER* fg, int ct ); 00357 00358 int fg_set_hue( FRAMEGRABBER* fg, int hue ); 00359 int fg_set_colour( FRAMEGRABBER* fg, int clr ); 00360 00361 //-------------------------------------------------------------------------- 00362 // 00363 // Function: fg_new_compatible_frame 00364 // 00365 // Description: Returns a newly allocated frame that is compatible with 00366 // the current frame grabber settings; that is, the window 00367 // width and height, and the capture format. This frame 00368 // must be deleted by the caller with frame_release(). 00369 // 00370 // Returns: FRAME* A new frame 00371 // 00372 //-------------------------------------------------------------------------- 00373 00374 FRAME* fg_new_compatible_frame( FRAMEGRABBER* fg ); 00375 00376 00377 //-------------------------------------------------------------------------- 00378 // 00379 // Function: fg_dump_info 00380 // 00381 // Description: Dumps to the console on stdout all the status 00382 // information available for the framegrabber. 00383 // 00384 //-------------------------------------------------------------------------- 00385 00386 void fg_dump_info( FRAMEGRABBER* fg ); 00387 00388 00389 //========================================================================== 00390 00391 #ifdef __cplusplus 00392 } 00393 #endif 00394 00395 #endif /* __CAPTURE__H_ */