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