videoio.h

Go to the documentation of this file.
00001 /*
00002  * videoio.h
00003  *
00004  * Classes to support streaming video input (grabbing) and output.
00005  *
00006  * Portable Windows Library
00007  *
00008  * Copyright (c) 1993-2000 Equivalence Pty. Ltd.
00009  *
00010  * The contents of this file are subject to the Mozilla Public License
00011  * Version 1.0 (the "License"); you may not use this file except in
00012  * compliance with the License. You may obtain a copy of the License at
00013  * http://www.mozilla.org/MPL/
00014  *
00015  * Software distributed under the License is distributed on an "AS IS"
00016  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
00017  * the License for the specific language governing rights and limitations
00018  * under the License.
00019  *
00020  * The Original Code is Portable Windows Library.
00021  *
00022  * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
00023  *
00024  * Contributor(s): Mark Cooke (mpc@star.sr.bham.ac.uk)
00025  *
00026  * $Log: videoio.h,v $
00027  * Revision 1.43  2005/11/25 03:43:47  csoutheren
00028  * Fixed function argument comments to be compatible with Doxygen
00029  *
00030  * Revision 1.42  2005/08/09 09:08:09  rjongbloed
00031  * Merged new video code from branch back to the trunk.
00032  *
00033  * Revision 1.41.4.1  2005/07/17 09:27:04  rjongbloed
00034  * Major revisions of the PWLib video subsystem including:
00035  *   removal of F suffix on colour formats for vertical flipping, all done with existing bool
00036  *   working through use of RGB and BGR formats so now consistent
00037  *   cleaning up the plug in system to use virtuals instead of pointers to functions.
00038  *   rewrite of SDL to be a plug in compatible video output device.
00039  *   extensive enhancement of video test program
00040  *
00041  * Revision 1.41  2005/01/04 07:44:03  csoutheren
00042  * More changes to implement the new configuration methodology, and also to
00043  * attack the global static problem
00044  *
00045  * Revision 1.40  2004/04/18 12:49:22  csoutheren
00046  * Patches to video code thanks to Guilhem Tardy (hope I get it right this time :)
00047  *
00048  * Revision 1.39  2004/01/18 14:23:30  dereksmithies
00049  * Add new function to make opening of video input devices easier.
00050  *
00051  * Revision 1.38  2004/01/02 23:30:18  rjongbloed
00052  * Removed extraneous static function for getting input device names that has been deprecated during the plug ins addition.
00053  *
00054  * Revision 1.37  2003/12/14 10:01:02  rjongbloed
00055  * Resolved issue with name space conflict os static and virtual forms of GetDeviceNames() function.
00056  *
00057  * Revision 1.36  2003/12/03 03:47:56  dereksmithies
00058  * Add fix so video output devices compile and run correctly.
00059  * Thanks to Craig Southeren.
00060  *
00061  * Revision 1.35  2003/11/19 04:29:02  csoutheren
00062  * Changed to support video output plugins
00063  *
00064  * Revision 1.34  2003/11/18 10:39:06  csoutheren
00065  * Fixed warnings regarding calling virtual Close in destructors
00066  *
00067  * Revision 1.33  2003/11/18 06:46:15  csoutheren
00068  * Changed to support video input plugins
00069  *
00070  * Revision 1.32  2003/09/17 05:41:59  csoutheren
00071  * Removed recursive includes
00072  *
00073  * Revision 1.31  2003/09/17 01:18:02  csoutheren
00074  * Removed recursive include file system and removed all references
00075  * to deprecated coooperative threading support
00076  *
00077  * Revision 1.30  2003/03/17 08:10:00  robertj
00078  * Fixed GNU warning
00079  *
00080  * Revision 1.29  2003/03/17 07:51:07  robertj
00081  * Added OpenFull() function to open with all video parameters in one go.
00082  * Made sure vflip variable is set in converter even if converter has not
00083  *   been set yet, should not depend on the order of functions!
00084  * Removed canCaptureVideo variable as this is really a virtual function to
00085  *   distinguish PVideoOutputDevice from PVideoInputDevice, it is not dynamic.
00086  * Made significant enhancements to PVideoOutputDevice class.
00087  * Added PVideoOutputDevice descendants for NULL and PPM files.
00088  *
00089  * Revision 1.28  2002/09/16 01:08:59  robertj
00090  * Added #define so can select if #pragma interface/implementation is used on
00091  *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
00092  *
00093  * Revision 1.27  2002/04/12 08:25:12  robertj
00094  * Added text string output for tracing video format.
00095  *
00096  * Revision 1.26  2002/04/05 06:41:54  rogerh
00097  * Apply video changes from Damien Sandras <dsandras@seconix.com>.
00098  * The Video Channel and Format are no longer set in Open(). Instead
00099  * call the new SetVideoChannelFormat() method. This makes video capture
00100  * and GnomeMeeting more stable with certain Linux video capture devices.
00101  *
00102  * Revision 1.25  2002/02/20 02:37:26  dereks
00103  * Initial release of Firewire camera support for linux.
00104  * Many thanks to Ryutaroh Matsumoto <ryutaroh@rmatsumoto.org>.
00105  *
00106  * Revision 1.24  2002/01/16 07:51:06  robertj
00107  * MSVC compatibilty changes
00108  *
00109  * Revision 1.23  2002/01/16 03:51:20  dereks
00110  * Move flip methods in PVideoInputDevice  to  PVideoDevice
00111  *
00112  * Revision 1.22  2002/01/14 02:59:54  robertj
00113  * Added preferred colour format selection, thanks Walter Whitlock
00114  *
00115  * Revision 1.21  2002/01/04 04:11:45  dereks
00116  * Add video flip code from Walter Whitlock, which flips code at the grabber.
00117  *
00118  * Revision 1.20  2001/11/28 00:07:32  dereks
00119  * Locking added to PVideoChannel, allowing reader/writer to be changed mid call
00120  * Enabled adjustment of the video frame rate
00121  * New fictitous image, a blank grey area
00122  *
00123  * Revision 1.19  2001/08/06 06:12:45  rogerh
00124  * Fix comments
00125  *
00126  * Revision 1.18  2001/08/03 04:21:51  dereks
00127  * Add colour/size conversion for YUV422->YUV411P
00128  * Add Get/Set Brightness,Contrast,Hue,Colour for PVideoDevice,  and
00129  * Linux PVideoInputDevice.
00130  * Add lots of PTRACE statement for debugging colour conversion.
00131  * Add support for Sony Vaio laptop under linux. Requires 2.4.7 kernel.
00132  *
00133  * Revision 1.17  2001/05/22 23:38:45  robertj
00134  * Fixed bug in PVideoOutputDevice, removed redundent SetFrameSize.
00135  *
00136  * Revision 1.16  2001/05/22 12:49:32  robertj
00137  * Did some seriously wierd rewrite of platform headers to eliminate the
00138  *   stupid GNU compiler warning about braces not matching.
00139  *
00140  * Revision 1.15  2001/03/20 02:21:57  robertj
00141  * More enhancements from Mark Cooke
00142  *
00143  * Revision 1.14  2001/03/08 23:04:19  robertj
00144  * Fixed up some documentation.
00145  *
00146  * Revision 1.13  2001/03/08 08:31:34  robertj
00147  * Numerous enhancements to the video grabbing code including resizing
00148  *   infrastructure to converters. Thanks a LOT, Mark Cooke.
00149  *
00150  * Revision 1.12  2001/03/07 01:42:59  dereks
00151  * miscellaneous video fixes. Works on linux now. Add debug statements
00152  * (at PTRACE level of 1)
00153  *
00154  * Revision 1.11  2001/03/06 23:34:20  robertj
00155  * Added static function to get input device names.
00156  * Moved some inline virtuals to non-inline.
00157  *
00158  * Revision 1.10  2001/03/03 05:06:31  robertj
00159  * Major upgrade of video conversion and grabbing classes.
00160  *
00161  * Revision 1.9  2001/02/28 01:47:14  robertj
00162  * Removed function from ancestor and is not very useful, thanks Thorsten Westheider.
00163  *
00164  * Revision 1.8  2000/12/19 22:20:26  dereks
00165  * Add video channel classes to connect to the PwLib PVideoInputDevice class.
00166  * Add PFakeVideoInput class to generate test images for video.
00167  *
00168  * Revision 1.7  2000/11/09 00:20:38  robertj
00169  * Added qcif size constants
00170  *
00171  * Revision 1.6  2000/07/30 03:41:31  robertj
00172  * Added more colour formats to video device enum.
00173  *
00174  * Revision 1.5  2000/07/26 03:50:49  robertj
00175  * Added last error variable to video device.
00176  *
00177  * Revision 1.4  2000/07/26 02:13:46  robertj
00178  * Added some more "common" bounds checking to video device.
00179  *
00180  * Revision 1.3  2000/07/25 13:38:25  robertj
00181  * Added frame rate parameter to video frame grabber.
00182  *
00183  * Revision 1.2  2000/07/25 13:14:05  robertj
00184  * Got the video capture stuff going!
00185  *
00186  * Revision 1.1  2000/07/15 09:47:34  robertj
00187  * Added video I/O device classes.
00188  *
00189  */
00190 
00191 
00192 #ifndef _PVIDEOIO
00193 #define _PVIDEOIO
00194 
00195 #ifdef P_USE_PRAGMA
00196 #pragma interface
00197 #endif
00198 
00199 class PColourConverter;
00200 
00231 class PVideoDevice : public PObject
00232 {
00233   PCLASSINFO(PVideoDevice, PObject);
00234 
00235   protected:
00238     PVideoDevice();
00239 
00240 
00241   public:
00244     virtual ~PVideoDevice();
00245 
00246     enum VideoFormat {
00247       PAL,
00248       NTSC,
00249       SECAM,
00250       Auto,
00251       NumVideoFormats
00252     };
00253 
00254     enum StandardSizes {
00255       CIF16Width = 1408,
00256       CIF16Height = 1152,
00257       CIF4Width = 704,
00258       CIF4Height = 576,
00259       CIFWidth = 352,
00260       CIFHeight = 288,
00261       QCIFWidth = 176,
00262       QCIFHeight = 144,
00263       SQCIFWidth = 144,
00264       SQCIFHeight = 96,
00265     };
00266 
00269     const PString & GetDeviceName() const
00270       { return deviceName; }
00271 
00274     virtual PStringList GetDeviceNames() const = 0;
00275 
00276     struct OpenArgs {
00277       OpenArgs()
00278         : deviceName("#1"),
00279           videoFormat(Auto),
00280           channelNumber(0),
00281           colourFormat("YUV420P"),
00282           convertFormat(TRUE),
00283           rate(0),
00284           width(CIFWidth),
00285           height(CIFHeight),
00286           convertSize(TRUE),
00287           scaleSize(FALSE),
00288           flip(FALSE),
00289           brightness(-1),
00290           whiteness(-1),
00291           contrast(-1),
00292           colour(-1),
00293           hue(-1)
00294         { }
00295       PString     deviceName;
00296       VideoFormat videoFormat;
00297       int         channelNumber;
00298       PString     colourFormat;
00299       bool        convertFormat;
00300       unsigned    rate;
00301       unsigned    width;
00302       unsigned    height;
00303       bool        convertSize;
00304       bool        scaleSize;
00305       bool        flip;
00306       int         brightness;
00307       int         whiteness;
00308       int         contrast;
00309       int         colour;
00310       int         hue;
00311     };
00312 
00315     virtual BOOL OpenFull(
00316       const OpenArgs & args,      
00317       BOOL startImmediate = TRUE  
00318     );
00319 
00322     virtual BOOL Open(
00323       const PString & deviceName,   
00324       BOOL startImmediate = TRUE    
00325     ) = 0;
00326 
00329     virtual BOOL IsOpen() = 0;
00330 
00333     virtual BOOL Close() = 0;
00334 
00337     virtual BOOL Start() = 0;
00338 
00341     virtual BOOL Stop() = 0;
00342 
00343 
00344 #if PTRACING
00345     friend ostream & operator<<(ostream &, VideoFormat);
00346 #endif
00347 
00353     virtual BOOL SetVideoFormat(
00354       VideoFormat videoFormat   
00355     );
00356 
00361     virtual VideoFormat GetVideoFormat() const;
00362 
00367     virtual int GetNumChannels();
00368 
00376     virtual BOOL SetChannel(
00377       int channelNumber  
00378     );
00379 
00384     virtual int GetChannel() const;
00385 
00392     virtual BOOL SetColourFormatConverter(
00393       const PString & colourFormat // New colour format for device.
00394     );
00395 
00406     virtual BOOL SetColourFormat(
00407       const PString & colourFormat // New colour format for device.
00408     );
00409 
00414     const PString & GetColourFormat() const;
00415 
00419     virtual BOOL GetVFlipState();
00420 
00424     virtual BOOL SetVFlipState(
00425       BOOL newVFlipState    
00426     );
00427 
00433     virtual BOOL SetFrameRate(
00434       unsigned rate  
00435     );
00436 
00441     virtual unsigned GetFrameRate() const;
00442 
00448     virtual BOOL GetFrameSizeLimits(
00449       unsigned & minWidth,   
00450       unsigned & minHeight,  
00451       unsigned & maxWidth,   
00452       unsigned & maxHeight   
00453     ) ;
00454 
00455 
00461     virtual BOOL SetFrameSizeConverter(
00462       unsigned width,        
00463       unsigned height,       
00464       BOOL     bScaleNotCrop 
00465     );
00466 
00475     virtual BOOL SetFrameSize(
00476       unsigned width,   
00477       unsigned height   
00478     );
00479 
00485     virtual BOOL GetFrameSize(
00486       unsigned & width,
00487       unsigned & height
00488     );
00489 
00494     virtual unsigned GetFrameWidth() const;
00495 
00500     virtual unsigned GetFrameHeight() const;
00501 
00507     virtual PINDEX GetMaxFrameBytes() = 0;
00508 
00511     static unsigned CalculateFrameBytes( 
00512       unsigned width,
00513       unsigned height,
00514       const PString & colourFormat
00515     );
00516 
00517     
00520     int GetLastError() const { return lastError; }
00521 
00522 
00525     virtual BOOL CanCaptureVideo() const = 0;
00526 
00529     virtual int GetBrightness();
00530 
00533     virtual BOOL SetBrightness(unsigned newBrightness);
00534 
00535 
00538     virtual int GetWhiteness();
00539 
00542     virtual BOOL SetWhiteness(unsigned newWhiteness);
00543 
00544 
00547     virtual int GetColour();
00548 
00551     virtual BOOL SetColour(unsigned newColour);
00552 
00553 
00556     virtual int GetContrast();
00557 
00560     virtual BOOL SetContrast(unsigned newContrast);
00561 
00562 
00565     virtual int GetHue();
00566 
00569     virtual BOOL SetHue(unsigned newHue);
00570     
00571     
00574     virtual BOOL GetParameters(
00575       int *whiteness,
00576       int *brightness,
00577       int *colour,
00578       int *contrast,
00579       int *hue
00580     );
00581 
00582     
00585     virtual BOOL SetVideoChannelFormat (
00586       int channelNumber, 
00587       VideoFormat videoFormat
00588     );
00589 
00590 
00594     void SetPreferredColourFormat(const PString & colourFmt) { preferredColourFormat = colourFmt; }
00595 
00599     const PString & GetPreferredColourFormat() { return preferredColourFormat; }
00600 
00601   protected:
00602     PINDEX GetMaxFrameBytesConverted(PINDEX rawFrameBytes) const;
00603 
00604     PString      deviceName;
00605     int          lastError;
00606     VideoFormat  videoFormat;
00607     int          channelNumber;
00608     PString      colourFormat;
00609     // Preferred native colour format from video input device, empty == no preference
00610     PString      preferredColourFormat;
00611     unsigned     frameRate;
00612     unsigned     frameWidth;
00613     unsigned     frameHeight;
00614     BOOL         nativeVerticalFlip;
00615 
00616     PColourConverter * converter;
00617  
00618     int          frameBrightness; // 16 bit entity, -1 is no value
00619     int          frameWhiteness;
00620     int          frameContrast;
00621     int          frameColour;
00622     int          frameHue;
00623 
00624     PTime        previousFrameTime; // Time of the last frame.
00625     int          msBetweenFrames;   // msBetween subsequent frames. 
00626     int          frameTimeError;    // determines  when this frame should happen.
00627 };
00628 
00629 
00632 class PVideoOutputDevice : public PVideoDevice
00633 {
00634   PCLASSINFO(PVideoOutputDevice, PVideoDevice);
00635 
00636   public:
00639     PVideoOutputDevice();
00640     
00643     virtual ~PVideoOutputDevice() { Close(); };      
00644 
00647     static PStringList GetDriverNames(
00648       PPluginManager * pluginMgr = NULL   
00649     );
00650 
00657     static PStringList GetDriversDeviceNames(
00658       const PString & driverName,         
00659       PPluginManager * pluginMgr = NULL   
00660     );
00661 
00664     static PVideoOutputDevice * CreateDevice(
00665       const PString & driverName,         
00666       PPluginManager * pluginMgr = NULL   
00667     );
00668 
00669     /* Create the matching video output device that corresponds to the device name.
00670 
00671        This is typically used with the return values from GetDriversDeviceNames().
00672      */
00673     static PVideoOutputDevice *CreateDeviceByName(
00674       const PString & deviceName,         
00675       PPluginManager * pluginMgr = NULL   
00676     );
00677 
00683     static PVideoOutputDevice *CreateOpenedDevice(
00684       const PString & driverName,         
00685       const PString & deviceName,         
00686       BOOL startImmediate = TRUE,         
00687       PPluginManager * pluginMgr = NULL   
00688     );
00689 
00692     virtual BOOL Close() { return TRUE; }
00693 
00696     virtual BOOL Start() { return TRUE; }
00697 
00700     virtual BOOL Stop() { return TRUE; }
00701 
00704     virtual BOOL CanCaptureVideo() const;
00705 
00708     virtual BOOL SetFrameData(
00709       unsigned x,
00710       unsigned y,
00711       unsigned width,
00712       unsigned height,
00713       const BYTE * data,
00714       BOOL endFrame = TRUE
00715     ) = 0;
00716 };
00717 
00718 
00721 class PVideoOutputDeviceRGB : public PVideoOutputDevice
00722 {
00723   PCLASSINFO(PVideoOutputDeviceRGB, PVideoOutputDevice);
00724 
00725   public:
00728     PVideoOutputDeviceRGB();
00729 
00740     virtual BOOL SetColourFormat(
00741       const PString & colourFormat // New colour format for device.
00742     );
00743 
00752     virtual BOOL SetFrameSize(
00753       unsigned width,   
00754       unsigned height   
00755     );
00756 
00762     virtual PINDEX GetMaxFrameBytes();
00763 
00766     virtual BOOL SetFrameData(
00767       unsigned x,
00768       unsigned y,
00769       unsigned width,
00770       unsigned height,
00771       const BYTE * data,
00772       BOOL endFrame = TRUE
00773     );
00774 
00777     virtual BOOL FrameComplete() = 0;
00778 
00779   protected:
00780     PMutex     mutex;
00781     PBYTEArray frameStore;
00782     PINDEX     bytesPerPixel;
00783     PINDEX     scanLineWidth;
00784     bool       swappedRedAndBlue;
00785 };
00786 
00787 
00788 #ifdef SHOULD_BE_MOVED_TO_PLUGIN
00789 
00792 class PVideoOutputDevicePPM : public PVideoOutputDeviceRGB
00793 {
00794   PCLASSINFO(PVideoOutputDevicePPM, PVideoOutputDeviceRGB);
00795 
00796   public:
00799     PVideoOutputDevicePPM();
00800 
00803     virtual BOOL Open(
00804       const PString & deviceName,   
00805       BOOL startImmediate = TRUE    
00806     );
00807 
00810     virtual BOOL IsOpen();
00811 
00814     virtual BOOL Close();
00815 
00818     virtual PStringList GetDeviceNames() const;
00819 
00822     virtual BOOL EndFrame();
00823 
00824   protected:
00825     unsigned   frameNumber;
00826 };
00827 
00828 #endif // SHOULD_BE_MOVED_TO_PLUGIN
00829 
00830 
00833 class PVideoInputDevice : public PVideoDevice
00834 {
00835   PCLASSINFO(PVideoInputDevice, PVideoDevice);
00836 
00837   public:
00840     //PVideoInputDevice();
00841 
00844     ~PVideoInputDevice() { Close(); }
00845 
00848     static PStringList GetDriverNames(
00849       PPluginManager * pluginMgr = NULL   
00850     );
00851 
00858     static PStringList GetDriversDeviceNames(
00859       const PString & driverName,         
00860       PPluginManager * pluginMgr = NULL   
00861     );
00862 
00865     static PVideoInputDevice *CreateDevice(
00866       const PString & driverName,         
00867       PPluginManager * pluginMgr = NULL   
00868     );
00869 
00870     /* Create the matching video input device that corresponds to the device name.
00871        So, for "fake" return a device that will generate fake video.
00872        For "Phillips 680 webcam" (eg) will return appropriate grabber.
00873        Note that Phillips will return the appropriate grabber also.
00874 
00875        This is typically used with the return values from GetDriversDeviceNames().
00876      */
00877     static PVideoInputDevice *CreateDeviceByName(
00878       const PString & deviceName,         
00879       PPluginManager * pluginMgr = NULL   
00880     );
00881 
00887     static PVideoInputDevice *CreateOpenedDevice(
00888       const PString & driverName,         
00889       const PString & deviceName,         
00890       BOOL startImmediate = TRUE,         
00891       PPluginManager * pluginMgr = NULL   
00892     );
00893 
00896     virtual BOOL Open(
00897       const PString & deviceName,   
00898       BOOL startImmediate = TRUE    
00899     ) = 0;
00900 
00901     virtual BOOL Close(
00902     ) { return TRUE; }
00903 
00906     virtual BOOL CanCaptureVideo() const;
00907  
00910     virtual BOOL IsCapturing() = 0;
00911 
00914     virtual BOOL GetFrame(
00915       PBYTEArray & frame
00916     );
00917 
00920     virtual BOOL GetFrameData(
00921       BYTE * buffer,                 
00922       PINDEX * bytesReturned = NULL  
00923     ) = 0;
00924 
00927     virtual BOOL GetFrameDataNoDelay(
00928       BYTE * buffer,                 
00929       PINDEX * bytesReturned = NULL  
00930     ) = 0;
00931 
00934     virtual BOOL TestAllFormats() = 0;
00935 };
00936 
00937 
00939 //
00940 // declare macros and structures needed for video input plugins
00941 //
00942 
00943 template <class className> class PVideoInputPluginServiceDescriptor : public PDevicePluginServiceDescriptor
00944 {
00945   public:
00946     virtual PObject *   CreateInstance(int /*userData*/) const { return new className; }
00947     virtual PStringList GetDeviceNames(int /*userData*/) const { return className::GetInputDeviceNames(); }
00948 };
00949 
00950 #define PCREATE_VIDINPUT_PLUGIN(name) \
00951   static PVideoInputPluginServiceDescriptor<PVideoInputDevice_##name> PVideoInputDevice_##name##_descriptor; \
00952   PCREATE_PLUGIN(name, PVideoInputDevice, &PVideoInputDevice_##name##_descriptor)
00953 
00955 //
00956 // declare macros and structures needed for video output plugins
00957 //
00958 
00959 template <class className> class PVideoOutputPluginServiceDescriptor : public PDevicePluginServiceDescriptor
00960 {
00961   public:
00962     virtual PObject *   CreateInstance(int /*userData*/) const { return new className; }
00963     virtual PStringList GetDeviceNames(int /*userData*/) const { return className::GetOutputDeviceNames(); }
00964 };
00965 
00966 #define PCREATE_VIDOUTPUT_PLUGIN(name) \
00967   static PVideoOutputPluginServiceDescriptor<PVideoOutputDevice_##name> PVideoOutputDevice_##name##_descriptor; \
00968   PCREATE_PLUGIN(name, PVideoOutputDevice, &PVideoOutputDevice_##name##_descriptor)
00969 
00970 #endif   // _PVIDEOIO
00971 
00972 // End Of File ///////////////////////////////////////////////////////////////

Generated on Fri Sep 21 14:40:11 2007 for PWLib by  doxygen 1.5.3