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  * $Revision: 19514 $
00027  * $Author: rjongbloed $
00028  * $Date: 2008-02-14 07:48:16 +0000 (Thu, 14 Feb 2008) $
00029  */
00030 
00031 
00032 #ifndef _PVIDEOIO
00033 #define _PVIDEOIO
00034 
00035 #ifdef P_USE_PRAGMA
00036 #pragma interface
00037 #endif
00038 
00039 #ifndef _PTLIB_H
00040 #include <ptlib.h>
00041 #endif
00042 
00043 #if P_VIDEO
00044 
00045 #include <ptlib/plugin.h>
00046 #include <ptlib/pluginmgr.h>
00047 #include <list>
00048 
00049 class PColourConverter;
00050 
00051 
00052 class PVideoFrameInfo : public PObject
00053 {
00054   PCLASSINFO(PVideoFrameInfo, PObject);
00055 
00056   public:
00057       PVideoFrameInfo();
00058 
00059     enum ResizeMode
00060     {
00061         eScale,
00062         eCropCentre,
00063         eCropTopLeft,
00064         eMaxResizeMode
00065     };
00066 
00067     enum StandardSizes {
00068       SQCIFWidth = 128,  SQCIFHeight = 96,
00069       QCIFWidth  = 176,  QCIFHeight  = 144,
00070       CIFWidth   = 352,  CIFHeight   = 288,
00071       CIF4Width  = 704,  CIF4Height  = 576,
00072       CIF16Width = 1408, CIF16Height = 1152,
00073       HDTVWidth  = 1920, HDTVHeight  = 1080,
00074       MaxWidth   = 1920, MaxHeight   = 1152
00075     };
00076 
00082     virtual PBoolean SetFrameSize(
00083       unsigned width,   
00084       unsigned height   
00085     );
00086 
00092     virtual PBoolean GetFrameSize(
00093       unsigned & width,
00094       unsigned & height
00095     ) const;
00096 
00101     virtual unsigned GetFrameWidth() const;
00102 
00107     virtual unsigned GetFrameHeight() const;
00108 
00114     virtual PBoolean SetFrameRate(
00115       unsigned rate  
00116     );
00117 
00122     virtual unsigned GetFrameRate() const;
00123 
00129     virtual PBoolean SetColourFormat(
00130       const PString & colourFormat // New colour format for device.
00131     );
00132 
00137     virtual const PString & GetColourFormat() const;
00138 
00141     void SetResizeMode(
00142       ResizeMode mode
00143     ) { if (resizeMode < eMaxResizeMode) resizeMode = mode; }
00144 
00147     ResizeMode GetResizeMode() const { return resizeMode; }
00148 
00151     PINDEX CalculateFrameBytes() const { return CalculateFrameBytes(frameWidth, frameHeight, colourFormat); }
00152     static PINDEX CalculateFrameBytes(
00153       unsigned width,               
00154       unsigned height,              
00155       const PString & colourFormat  
00156     );
00157 
00160     static PBoolean ParseSize(
00161       const PString & str,  
00162       unsigned & width,     
00163       unsigned & height     
00164     );
00165 
00166   protected:
00167     unsigned   frameWidth;
00168     unsigned   frameHeight;
00169     unsigned   frameRate;
00170     PString    colourFormat;
00171     ResizeMode resizeMode;
00172 };
00173 
00174 
00203 class PVideoDevice : public PVideoFrameInfo
00204 {
00205   PCLASSINFO(PVideoDevice, PVideoFrameInfo);
00206 
00207   protected:
00210     PVideoDevice();
00211 
00212 
00213   public:
00216     virtual ~PVideoDevice();
00217 
00218     enum VideoFormat {
00219       PAL,
00220       NTSC,
00221       SECAM,
00222       Auto,
00223       NumVideoFormats
00224     };
00225 
00228     const PString & GetDeviceName() const
00229       { return deviceName; }
00230 
00233     virtual PStringArray GetDeviceNames() const = 0;
00234 
00235     struct OpenArgs {
00236       OpenArgs();
00237 
00238       PPluginManager * pluginMgr;
00239       PString     driverName;
00240       PString     deviceName;
00241       VideoFormat videoFormat;
00242       int         channelNumber;
00243       PString     colourFormat;
00244       bool        convertFormat;
00245       unsigned    rate;
00246       unsigned    width;
00247       unsigned    height;
00248       bool        convertSize;
00249       ResizeMode  resizeMode;
00250       bool        flip;
00251       int         brightness;
00252       int         whiteness;
00253       int         contrast;
00254       int         colour;
00255       int         hue;
00256     };
00257 
00260     virtual PBoolean OpenFull(
00261       const OpenArgs & args,      
00262       PBoolean startImmediate = PTrue  
00263     );
00264 
00267     virtual PBoolean Open(
00268       const PString & deviceName,   
00269       PBoolean startImmediate = PTrue    
00270     ) = 0;
00271 
00274     virtual PBoolean IsOpen() = 0;
00275 
00278     virtual PBoolean Close() = 0;
00279 
00282     virtual PBoolean Start() = 0;
00283 
00286     virtual PBoolean Stop() = 0;
00287 
00288 
00289 #if PTRACING
00290     friend ostream & operator<<(ostream &, VideoFormat);
00291 #endif
00292 
00298     virtual PBoolean SetVideoFormat(
00299       VideoFormat videoFormat   
00300     );
00301 
00306     virtual VideoFormat GetVideoFormat() const;
00307 
00312     virtual int GetNumChannels();
00313 
00321     virtual PBoolean SetChannel(
00322       int channelNumber  
00323     );
00324 
00329     virtual int GetChannel() const;
00330 
00337     virtual PBoolean SetColourFormatConverter(
00338       const PString & colourFormat // New colour format for device.
00339     );
00340 
00344     virtual PBoolean GetVFlipState();
00345 
00349     virtual PBoolean SetVFlipState(
00350       PBoolean newVFlipState    
00351     );
00352 
00358     virtual PBoolean GetFrameSizeLimits(
00359       unsigned & minWidth,   
00360       unsigned & minHeight,  
00361       unsigned & maxWidth,   
00362       unsigned & maxHeight   
00363     ) ;
00364 
00365 
00371     virtual PBoolean SetFrameSizeConverter(
00372       unsigned width,  
00373       unsigned height, 
00374       ResizeMode resizeMode = eMaxResizeMode 
00375     );
00376 
00382     virtual PBoolean SetFrameSizeConverter(
00383       unsigned width,                   
00384       unsigned height,                  
00385           PBoolean  /*bScaleNotCrop*/           
00386           )  { return SetFrameSizeConverter(width,height,eScale); }
00387 
00388 
00397     virtual PBoolean SetFrameSize(
00398       unsigned width,   
00399       unsigned height   
00400     );
00401 
00407     virtual PBoolean GetFrameSize(
00408       unsigned & width,
00409       unsigned & height
00410     ) const;
00411 
00417     virtual PINDEX GetMaxFrameBytes() = 0;
00418 
00419     
00422     int GetLastError() const { return lastError; }
00423 
00424 
00427     virtual PBoolean CanCaptureVideo() const = 0;
00428 
00431     virtual int GetBrightness();
00432 
00435     virtual PBoolean SetBrightness(unsigned newBrightness);
00436 
00437 
00440     virtual int GetWhiteness();
00441 
00444     virtual PBoolean SetWhiteness(unsigned newWhiteness);
00445 
00446 
00449     virtual int GetColour();
00450 
00453     virtual PBoolean SetColour(unsigned newColour);
00454 
00455 
00458     virtual int GetContrast();
00459 
00462     virtual PBoolean SetContrast(unsigned newContrast);
00463 
00464 
00467     virtual int GetHue();
00468 
00471     virtual PBoolean SetHue(unsigned newHue);
00472     
00473     
00476     virtual PBoolean GetParameters(
00477       int *whiteness,
00478       int *brightness,
00479       int *colour,
00480       int *contrast,
00481       int *hue
00482     );
00483 
00484     
00487     virtual PBoolean SetVideoChannelFormat (
00488       int channelNumber, 
00489       VideoFormat videoFormat
00490     );
00491 
00492 
00496     void SetPreferredColourFormat(const PString & colourFmt) { preferredColourFormat = colourFmt; }
00497 
00501     const PString & GetPreferredColourFormat() { return preferredColourFormat; }
00502     
00503   protected:
00504     PINDEX GetMaxFrameBytesConverted(PINDEX rawFrameBytes) const;
00505 
00506     PString      deviceName;
00507     int          lastError;
00508     VideoFormat  videoFormat;
00509     int          channelNumber;
00510     // Preferred native colour format from video input device, empty == no preference
00511     PString      preferredColourFormat;
00512     PBoolean         nativeVerticalFlip;
00513 
00514     PColourConverter * converter;
00515     PBYTEArray         frameStore;
00516 
00517     int          frameBrightness; // 16 bit entity, -1 is no value
00518     int          frameWhiteness;
00519     int          frameContrast;
00520     int          frameColour;
00521     int          frameHue;
00522 };
00523 
00524 
00527 class PVideoOutputDevice : public PVideoDevice
00528 {
00529   PCLASSINFO(PVideoOutputDevice, PVideoDevice);
00530 
00531   public:
00534     PVideoOutputDevice();
00535     
00538     virtual ~PVideoOutputDevice() { Close(); };      
00539 
00542     static PStringArray GetDriverNames(
00543       PPluginManager * pluginMgr = NULL   
00544     );
00545 
00552     static PStringArray GetDriversDeviceNames(
00553       const PString & driverName,         
00554       PPluginManager * pluginMgr = NULL   
00555     );
00556 
00559     static PVideoOutputDevice * CreateDevice(
00560       const PString & driverName,         
00561       PPluginManager * pluginMgr = NULL   
00562     );
00563 
00564     /* Create the matching video output device that corresponds to the device name.
00565 
00566        This is typically used with the return values from GetDriversDeviceNames().
00567      */
00568     static PVideoOutputDevice *CreateDeviceByName(
00569       const PString & deviceName,         
00570       const PString & driverName = PString::Empty(),  
00571       PPluginManager * pluginMgr = NULL   
00572     );
00573 
00579     static PVideoOutputDevice *CreateOpenedDevice(
00580       const PString & driverName,         
00581       const PString & deviceName,         
00582       PBoolean startImmediate = PTrue,         
00583       PPluginManager * pluginMgr = NULL   
00584     );
00585 
00588     static PVideoOutputDevice *CreateOpenedDevice(
00589       const OpenArgs & args,              
00590       PBoolean startImmediate = PTrue          
00591     );
00592 
00595     virtual PBoolean Close() { return PTrue; }
00596 
00599     virtual PBoolean Start() { return PTrue; }
00600 
00603     virtual PBoolean Stop() { return PTrue; }
00604 
00607     virtual PBoolean CanCaptureVideo() const;
00608 
00611     virtual PBoolean SetFrameData(
00612       unsigned x,
00613       unsigned y,
00614       unsigned width,
00615       unsigned height,
00616       const BYTE * data,
00617       PBoolean endFrame = PTrue
00618     ) = 0;
00619     virtual PBoolean SetFrameData(
00620       unsigned x,
00621       unsigned y,
00622       unsigned width,
00623       unsigned height,
00624       const BYTE * data,
00625       PBoolean endFrame,
00626       unsigned flags
00627     );
00628 
00635     virtual PBoolean GetPosition(
00636       int & x,  // X position of device surface
00637       int & y   // Y position of device surface
00638     ) const;
00639 };
00640 
00641 
00644 class PVideoOutputDeviceRGB : public PVideoOutputDevice
00645 {
00646   PCLASSINFO(PVideoOutputDeviceRGB, PVideoOutputDevice);
00647 
00648   public:
00651     PVideoOutputDeviceRGB();
00652 
00663     virtual PBoolean SetColourFormat(
00664       const PString & colourFormat // New colour format for device.
00665     );
00666 
00675     virtual PBoolean SetFrameSize(
00676       unsigned width,   
00677       unsigned height   
00678     );
00679 
00685     virtual PINDEX GetMaxFrameBytes();
00686 
00689     virtual PBoolean SetFrameData(
00690       unsigned x,
00691       unsigned y,
00692       unsigned width,
00693       unsigned height,
00694       const BYTE * data,
00695       PBoolean endFrame = PTrue
00696     );
00697 
00700     virtual PBoolean FrameComplete() = 0;
00701 
00702   protected:
00703     PMutex     mutex;
00704     PINDEX     bytesPerPixel;
00705     PINDEX     scanLineWidth;
00706     bool       swappedRedAndBlue;
00707 };
00708 
00709 
00710 #ifdef SHOULD_BE_MOVED_TO_PLUGIN
00711 
00714 class PVideoOutputDevicePPM : public PVideoOutputDeviceRGB
00715 {
00716   PCLASSINFO(PVideoOutputDevicePPM, PVideoOutputDeviceRGB);
00717 
00718   public:
00721     PVideoOutputDevicePPM();
00722 
00725     virtual PBoolean Open(
00726       const PString & deviceName,   
00727       PBoolean startImmediate = PTrue    
00728     );
00729 
00732     virtual PBoolean IsOpen();
00733 
00736     virtual PBoolean Close();
00737 
00740     virtual PStringArray GetDeviceNames() const;
00741 
00744     virtual PBoolean EndFrame();
00745 
00746   protected:
00747     unsigned   frameNumber;
00748 };
00749 
00750 #endif // SHOULD_BE_MOVED_TO_PLUGIN
00751 
00752 
00755 class PVideoInputDevice : public PVideoDevice
00756 {
00757   PCLASSINFO(PVideoInputDevice, PVideoDevice);
00758 
00759   public:
00762     //PVideoInputDevice();
00763 
00766     ~PVideoInputDevice() { Close(); }
00767 
00770     static PStringArray GetDriverNames(
00771       PPluginManager * pluginMgr = NULL   
00772     );
00773 
00780     static PStringArray GetDriversDeviceNames(
00781       const PString & driverName,         
00782       PPluginManager * pluginMgr = NULL   
00783     );
00784 
00787     static PVideoInputDevice *CreateDevice(
00788       const PString & driverName,         
00789       PPluginManager * pluginMgr = NULL   
00790     );
00791 
00792     /* Create the matching video input device that corresponds to the device name.
00793        So, for "fake" return a device that will generate fake video.
00794        For "Phillips 680 webcam" (eg) will return appropriate grabber.
00795        Note that Phillips will return the appropriate grabber also.
00796 
00797        This is typically used with the return values from GetDriversDeviceNames().
00798      */
00799     static PVideoInputDevice *CreateDeviceByName(
00800       const PString & deviceName,         
00801       const PString & driverName = PString::Empty(),  
00802       PPluginManager * pluginMgr = NULL   
00803     );
00804 
00810     static PVideoInputDevice *CreateOpenedDevice(
00811       const PString & driverName,         
00812       const PString & deviceName,         
00813       PBoolean startImmediate = PTrue,         
00814       PPluginManager * pluginMgr = NULL   
00815     );
00816 
00819     static PVideoInputDevice *CreateOpenedDevice(
00820       const OpenArgs & args,              
00821       PBoolean startImmediate = PTrue          
00822     );
00823 
00824     typedef std::list<PVideoFrameInfo> Capabilities;
00825 
00828     static PBoolean GetDeviceCapabilities(
00829       const PString & deviceName,           
00830       Capabilities * capabilities,          
00831       PPluginManager * pluginMgr = NULL     
00832     );
00833 
00836     static PBoolean GetDeviceCapabilities(
00837       const PString & deviceName,           
00838       const PString & driverName,           
00839       Capabilities * caps,                  
00840       PPluginManager * pluginMgr = NULL     
00841     );
00842 
00845     virtual PBoolean Open(
00846       const PString & deviceName,   
00847       PBoolean startImmediate = PTrue    
00848     ) = 0;
00849 
00850     virtual PBoolean Close(
00851     ) { return PTrue; }
00852 
00855     virtual PBoolean CanCaptureVideo() const;
00856  
00859     virtual PBoolean IsCapturing() = 0;
00860 
00863     virtual PBoolean GetFrame(
00864       PBYTEArray & frame
00865     );
00866 
00869     virtual PBoolean GetFrameData(
00870       BYTE * buffer,                 
00871       PINDEX * bytesReturned,        
00872       unsigned int & flags           
00873     );
00874     virtual PBoolean GetFrameData(
00875       BYTE * buffer,                 
00876       PINDEX * bytesReturned = NULL  
00877     ) = 0;
00878 
00881     virtual PBoolean GetFrameDataNoDelay(
00882       BYTE * buffer,                 
00883       PINDEX * bytesReturned,       
00884       unsigned int & flags           
00885     );
00886     virtual PBoolean GetFrameDataNoDelay(
00887       BYTE * buffer,                 
00888       PINDEX * bytesReturned = NULL  
00889     ) = 0;
00890 
00893     virtual PBoolean TestAllFormats() = 0;
00894 };
00895 
00896 
00898 //
00899 // declare macros and structures needed for video input plugins
00900 //
00901 
00902 template <class className> class PVideoInputPluginServiceDescriptor : public PDevicePluginServiceDescriptor
00903 {
00904   public:
00905     virtual PObject *    CreateInstance(int /*userData*/) const { return new className; }
00906     virtual PStringArray GetDeviceNames(int /*userData*/) const { return className::GetInputDeviceNames(); }
00907     virtual bool         GetDeviceCapabilities(const PString & deviceName, void * caps) const
00908       { return className::GetDeviceCapabilities(deviceName, (PVideoInputDevice::Capabilities *)caps); }
00909 };
00910 
00911 #define PCREATE_VIDINPUT_PLUGIN(name) \
00912   static PVideoInputPluginServiceDescriptor<PVideoInputDevice_##name> PVideoInputDevice_##name##_descriptor; \
00913   PCREATE_PLUGIN(name, PVideoInputDevice, &PVideoInputDevice_##name##_descriptor)
00914 
00916 //
00917 // declare macros and structures needed for video output plugins
00918 //
00919 
00920 template <class className> class PVideoOutputPluginServiceDescriptor : public PDevicePluginServiceDescriptor
00921 {
00922   public:
00923     virtual PObject *    CreateInstance(int /*userData*/) const { return new className; }
00924     virtual PStringArray GetDeviceNames(int /*userData*/) const { return className::GetOutputDeviceNames(); }
00925 };
00926 
00927 #define PCREATE_VIDOUTPUT_PLUGIN(name) \
00928   static PVideoOutputPluginServiceDescriptor<PVideoOutputDevice_##name> PVideoOutputDevice_##name##_descriptor; \
00929   PCREATE_PLUGIN(name, PVideoOutputDevice, &PVideoOutputDevice_##name##_descriptor)
00930 
00932 //
00933 // declare classes needed for access to simple video font
00934 //
00935 
00936 class PVideoFont : public PObject
00937 {
00938   PCLASSINFO(PVideoFont, PObject);
00939   public:
00940     enum {
00941       MAX_L_HEIGHT = 11
00942     };
00943     struct LetterData {
00944       char ascii;
00945       const char *line[MAX_L_HEIGHT];
00946     };
00947 
00948     static const LetterData * GetLetterData(char ascii);
00949 };
00950 
00951 #endif // P_VIDEO
00952 
00953 #endif   // _PVIDEOIO
00954 
00955 // End Of File ///////////////////////////////////////////////////////////////

Generated on Wed May 7 00:47:56 2008 for PTLib by  doxygen 1.5.1