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_ */

Last updated 12 September 2005 21:38:45