videoio.h

Go to the documentation of this file.

/*
 * videoio.h
 *
 * Classes to support streaming video input (grabbing) and output.
 *
 * Portable Windows Library
 *
 * Copyright (c) 1993-2000 Equivalence Pty. Ltd.
 *
 * The contents of this file are subject to the Mozilla Public License
 * Version 1.0 (the "License"); you may not use this file except in
 * compliance with the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS"
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 * the License for the specific language governing rights and limitations
 * under the License.
 *
 * The Original Code is Portable Windows Library.
 *
 * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
 *
 * Contributor(s): Mark Cooke (mpc@star.sr.bham.ac.uk)
 *
 * $Revision: 19032 $
 * $Author: rjongbloed $
 * $Date: 2007-12-03 11:08:47 +0000 (Mon, 03 Dec 2007) $
 */


#ifndef _PVIDEOIO
#define _PVIDEOIO

#ifdef P_USE_PRAGMA
#pragma interface
#endif

#ifndef _PTLIB_H
#include <ptlib.h>
#endif

#if P_VIDEO

#include <ptlib/plugin.h>
#include <ptlib/pluginmgr.h>
#include <list>

class PColourConverter;


class PVideoFrameInfo : public PObject
{
  PCLASSINFO(PVideoFrameInfo, PObject);

  public:
      PVideoFrameInfo();

    enum ResizeMode
    {
        eScale,
        eCropCentre,
        eCropTopLeft,
        eMaxResizeMode
    };

    enum StandardSizes {
      SQCIFWidth = 128,  SQCIFHeight = 96,
      QCIFWidth  = 176,  QCIFHeight  = 144,
      CIFWidth   = 352,  CIFHeight   = 288,
      CIF4Width  = 704,  CIF4Height  = 576,
      CIF16Width = 1408, CIF16Height = 1152,
      HDTVWidth  = 1920, HDTVHeight  = 1080,
    };

    virtual PBoolean SetFrameSize(
      unsigned width,   
      unsigned height   
    );

    virtual PBoolean GetFrameSize(
      unsigned & width,
      unsigned & height
    ) const;

    virtual unsigned GetFrameWidth() const;

    virtual unsigned GetFrameHeight() const;

    virtual PBoolean SetFrameRate(
      unsigned rate  
    );

    virtual unsigned GetFrameRate() const;

    virtual PBoolean SetColourFormat(
      const PString & colourFormat // New colour format for device.
    );

    virtual const PString & GetColourFormat() const;

    void SetResizeMode(
      ResizeMode mode
    ) { if (resizeMode < eMaxResizeMode) resizeMode = mode; }

    ResizeMode GetResizeMode() const { return resizeMode; }

    PINDEX CalculateFrameBytes() const { return CalculateFrameBytes(frameWidth, frameHeight, colourFormat); }
    static PINDEX CalculateFrameBytes(
      unsigned width,               
      unsigned height,              
      const PString & colourFormat  
    );

    static PBoolean ParseSize(
      const PString & str,  
      unsigned & width,     
      unsigned & height     
    );

  protected:
    unsigned   frameWidth;
    unsigned   frameHeight;
    unsigned   frameRate;
    PString    colourFormat;
    ResizeMode resizeMode;
};


class PVideoDevice : public PVideoFrameInfo
{
  PCLASSINFO(PVideoDevice, PVideoFrameInfo);

  protected:
    PVideoDevice();


  public:
    virtual ~PVideoDevice();

    enum VideoFormat {
      PAL,
      NTSC,
      SECAM,
      Auto,
      NumVideoFormats
    };

    const PString & GetDeviceName() const
      { return deviceName; }

    virtual PStringList GetDeviceNames() const = 0;

    struct OpenArgs {
      OpenArgs();

      PPluginManager * pluginMgr;
      PString     driverName;
      PString     deviceName;
      VideoFormat videoFormat;
      int         channelNumber;
      PString     colourFormat;
      bool        convertFormat;
      unsigned    rate;
      unsigned    width;
      unsigned    height;
      bool        convertSize;
      ResizeMode  resizeMode;
      bool        flip;
      int         brightness;
      int         whiteness;
      int         contrast;
      int         colour;
      int         hue;
    };

    virtual PBoolean OpenFull(
      const OpenArgs & args,      
      PBoolean startImmediate = PTrue  
    );

    virtual PBoolean Open(
      const PString & deviceName,   
      PBoolean startImmediate = PTrue    
    ) = 0;

    virtual PBoolean IsOpen() = 0;

    virtual PBoolean Close() = 0;

    virtual PBoolean Start() = 0;

    virtual PBoolean Stop() = 0;


#if PTRACING
    friend ostream & operator<<(ostream &, VideoFormat);
#endif

    virtual PBoolean SetVideoFormat(
      VideoFormat videoFormat   
    );

    virtual VideoFormat GetVideoFormat() const;

    virtual int GetNumChannels();

    virtual PBoolean SetChannel(
      int channelNumber  
    );

    virtual int GetChannel() const;

    virtual PBoolean SetColourFormatConverter(
      const PString & colourFormat // New colour format for device.
    );

    virtual PBoolean GetVFlipState();

    virtual PBoolean SetVFlipState(
      PBoolean newVFlipState    
    );

    virtual PBoolean GetFrameSizeLimits(
      unsigned & minWidth,   
      unsigned & minHeight,  
      unsigned & maxWidth,   
      unsigned & maxHeight   
    ) ;


    virtual PBoolean SetFrameSizeConverter(
      unsigned width,  
      unsigned height, 
      ResizeMode resizeMode = eMaxResizeMode 
    );

    virtual PBoolean SetFrameSizeConverter(
      unsigned width,                   
      unsigned height,                  
          PBoolean  /*bScaleNotCrop*/           
          )  { return SetFrameSizeConverter(width,height,eScale); }


    virtual PBoolean SetFrameSize(
      unsigned width,   
      unsigned height   
    );

    virtual PBoolean GetFrameSize(
      unsigned & width,
      unsigned & height
    ) const;

    virtual PINDEX GetMaxFrameBytes() = 0;

    
    int GetLastError() const { return lastError; }


    virtual PBoolean CanCaptureVideo() const = 0;

    virtual int GetBrightness();

    virtual PBoolean SetBrightness(unsigned newBrightness);


    virtual int GetWhiteness();

    virtual PBoolean SetWhiteness(unsigned newWhiteness);


    virtual int GetColour();

    virtual PBoolean SetColour(unsigned newColour);


    virtual int GetContrast();

    virtual PBoolean SetContrast(unsigned newContrast);


    virtual int GetHue();

    virtual PBoolean SetHue(unsigned newHue);
    
    
    virtual PBoolean GetParameters(
      int *whiteness,
      int *brightness,
      int *colour,
      int *contrast,
      int *hue
    );

    
    virtual PBoolean SetVideoChannelFormat (
      int channelNumber, 
      VideoFormat videoFormat
    );


    void SetPreferredColourFormat(const PString & colourFmt) { preferredColourFormat = colourFmt; }

    const PString & GetPreferredColourFormat() { return preferredColourFormat; }
    
    int GetNumberOfFrames () { return numberOfFrames; }
    
  protected:
    PINDEX GetMaxFrameBytesConverted(PINDEX rawFrameBytes) const;

    PString      deviceName;
    int          lastError;
    VideoFormat  videoFormat;
    int          channelNumber;
    // Preferred native colour format from video input device, empty == no preference
    PString      preferredColourFormat;
    PBoolean         nativeVerticalFlip;

    PColourConverter * converter;
    PBYTEArray         frameStore;

    int          frameBrightness; // 16 bit entity, -1 is no value
    int          frameWhiteness;
    int          frameContrast;
    int          frameColour;
    int          frameHue;
    int          numberOfFrames;
};


class PVideoOutputDevice : public PVideoDevice
{
  PCLASSINFO(PVideoOutputDevice, PVideoDevice);

  public:
    PVideoOutputDevice();
    
    virtual ~PVideoOutputDevice() { Close(); };      

    static PStringList GetDriverNames(
      PPluginManager * pluginMgr = NULL   
    );

    static PStringList GetDriversDeviceNames(
      const PString & driverName,         
      PPluginManager * pluginMgr = NULL   
    );

    static PVideoOutputDevice * CreateDevice(
      const PString & driverName,         
      PPluginManager * pluginMgr = NULL   
    );

    /* Create the matching video output device that corresponds to the device name.

       This is typically used with the return values from GetDriversDeviceNames().
     */
    static PVideoOutputDevice *CreateDeviceByName(
      const PString & deviceName,         
      const PString & driverName = PString::Empty(),  
      PPluginManager * pluginMgr = NULL   
    );

    static PVideoOutputDevice *CreateOpenedDevice(
      const PString & driverName,         
      const PString & deviceName,         
      PBoolean startImmediate = PTrue,         
      PPluginManager * pluginMgr = NULL   
    );

    static PVideoOutputDevice *CreateOpenedDevice(
      const OpenArgs & args,              
      PBoolean startImmediate = PTrue          
    );

    virtual PBoolean Close() { return PTrue; }

    virtual PBoolean Start() { return PTrue; }

    virtual PBoolean Stop() { return PTrue; }

    virtual PBoolean CanCaptureVideo() const;

    virtual PBoolean SetFrameData(
      unsigned x,
      unsigned y,
      unsigned width,
      unsigned height,
      const BYTE * data,
      PBoolean endFrame = PTrue
    ) = 0;

    virtual PBoolean GetPosition(
      int & x,  // X position of device surface
      int & y   // Y position of device surface
    ) const;
};


class PVideoOutputDeviceRGB : public PVideoOutputDevice
{
  PCLASSINFO(PVideoOutputDeviceRGB, PVideoOutputDevice);

  public:
    PVideoOutputDeviceRGB();

    virtual PBoolean SetColourFormat(
      const PString & colourFormat // New colour format for device.
    );

    virtual PBoolean SetFrameSize(
      unsigned width,   
      unsigned height   
    );

    virtual PINDEX GetMaxFrameBytes();

    virtual PBoolean SetFrameData(
      unsigned x,
      unsigned y,
      unsigned width,
      unsigned height,
      const BYTE * data,
      PBoolean endFrame = PTrue
    );

    virtual PBoolean FrameComplete() = 0;

  protected:
    PMutex     mutex;
    PINDEX     bytesPerPixel;
    PINDEX     scanLineWidth;
    bool       swappedRedAndBlue;
};


#ifdef SHOULD_BE_MOVED_TO_PLUGIN

class PVideoOutputDevicePPM : public PVideoOutputDeviceRGB
{
  PCLASSINFO(PVideoOutputDevicePPM, PVideoOutputDeviceRGB);

  public:
    PVideoOutputDevicePPM();

    virtual PBoolean Open(
      const PString & deviceName,   
      PBoolean startImmediate = PTrue    
    );

    virtual PBoolean IsOpen();

    virtual PBoolean Close();

    virtual PStringList GetDeviceNames() const;

    virtual PBoolean EndFrame();

  protected:
    unsigned   frameNumber;
};

#endif // SHOULD_BE_MOVED_TO_PLUGIN


class PVideoInputDevice : public PVideoDevice
{
  PCLASSINFO(PVideoInputDevice, PVideoDevice);

  public:
    //PVideoInputDevice();

    ~PVideoInputDevice() { Close(); }

    static PStringList GetDriverNames(
      PPluginManager * pluginMgr = NULL   
    );

    static PStringList GetDriversDeviceNames(
      const PString & driverName,         
      PPluginManager * pluginMgr = NULL   
    );

    static PVideoInputDevice *CreateDevice(
      const PString & driverName,         
      PPluginManager * pluginMgr = NULL   
    );

    /* Create the matching video input device that corresponds to the device name.
       So, for "fake" return a device that will generate fake video.
       For "Phillips 680 webcam" (eg) will return appropriate grabber.
       Note that Phillips will return the appropriate grabber also.

       This is typically used with the return values from GetDriversDeviceNames().
     */
    static PVideoInputDevice *CreateDeviceByName(
      const PString & deviceName,         
      const PString & driverName = PString::Empty(),  
      PPluginManager * pluginMgr = NULL   
    );

    static PVideoInputDevice *CreateOpenedDevice(
      const PString & driverName,         
      const PString & deviceName,         
      PBoolean startImmediate = PTrue,         
      PPluginManager * pluginMgr = NULL   
    );

    static PVideoInputDevice *CreateOpenedDevice(
      const OpenArgs & args,              
      PBoolean startImmediate = PTrue          
    );

    typedef std::list<PVideoFrameInfo> Capabilities;

    static PBoolean GetDeviceCapabilities(
      const PString & deviceName,           
      Capabilities * capabilities,          
      PPluginManager * pluginMgr = NULL     
    );

    static PBoolean GetDeviceCapabilities(
      const PString & deviceName,           
      const PString & driverName,           
      Capabilities * caps,                  
      PPluginManager * pluginMgr = NULL     
    );

    virtual PBoolean Open(
      const PString & deviceName,   
      PBoolean startImmediate = PTrue    
    ) = 0;

    virtual PBoolean Close(
    ) { return PTrue; }

    virtual PBoolean CanCaptureVideo() const;
 
    virtual PBoolean IsCapturing() = 0;

    virtual PBoolean GetFrame(
      PBYTEArray & frame
    );

    virtual PBoolean GetFrameData(
      BYTE * buffer,                 
      PINDEX * bytesReturned = NULL  
    ) = 0;

    virtual PBoolean GetFrameDataNoDelay(
      BYTE * buffer,                 
      PINDEX * bytesReturned = NULL  
    ) = 0;

    virtual PBoolean TestAllFormats() = 0;
};


//
// declare macros and structures needed for video input plugins
//

template <class className> class PVideoInputPluginServiceDescriptor : public PDevicePluginServiceDescriptor
{
  public:
    virtual PObject *   CreateInstance(int /*userData*/) const { return new className; }
    virtual PStringList GetDeviceNames(int /*userData*/) const { return className::GetInputDeviceNames(); }
    virtual bool GetDeviceCapabilities(const PString & deviceName, void * caps) const
      { return className::GetDeviceCapabilities(deviceName, (PVideoInputDevice::Capabilities *)caps); }
};

#define PCREATE_VIDINPUT_PLUGIN(name) \
  static PVideoInputPluginServiceDescriptor<PVideoInputDevice_##name> PVideoInputDevice_##name##_descriptor; \
  PCREATE_PLUGIN(name, PVideoInputDevice, &PVideoInputDevice_##name##_descriptor)

//
// declare macros and structures needed for video output plugins
//

template <class className> class PVideoOutputPluginServiceDescriptor : public PDevicePluginServiceDescriptor
{
  public:
    virtual PObject *   CreateInstance(int /*userData*/) const { return new className; }
    virtual PStringList GetDeviceNames(int /*userData*/) const { return className::GetOutputDeviceNames(); }
};

#define PCREATE_VIDOUTPUT_PLUGIN(name) \
  static PVideoOutputPluginServiceDescriptor<PVideoOutputDevice_##name> PVideoOutputDevice_##name##_descriptor; \
  PCREATE_PLUGIN(name, PVideoOutputDevice, &PVideoOutputDevice_##name##_descriptor)

//
// declare classes needed for access to simple video font
//

class PVideoFont : public PObject
{
  PCLASSINFO(PVideoFont, PObject);
  public:
    enum {
      MAX_L_HEIGHT = 11
    };
    struct LetterData {
      char ascii;
      const char *line[MAX_L_HEIGHT];
    };

    static const LetterData * GetLetterData(char ascii);
};

#endif // P_VIDEO

#endif   // _PVIDEOIO

// End Of File ///////////////////////////////////////////////////////////////

---