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

Last updated 25 May 2011 21:17:00