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: 24867 $
 * $Author: rjongbloed $
 * $Date: 2010-11-10 01:29:17 -0600 (Wed, 10 Nov 2010) $
 */


#ifndef PTLIB_PVIDEOIO_H
#define PTLIB_PVIDEOIO_H

#ifdef P_USE_PRAGMA
#pragma interface
#endif
#include <ptbuildopts.h>

#if P_VIDEO

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

class PColourConverter;


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

  public:
    enum ResizeMode
    {
      eScale,
      eCropCentre,
      eCropTopLeft,
      eMaxResizeMode
    };
    friend ostream & operator<<(ostream & strm, ResizeMode mode);

    enum StandardSizes {
      SQCIFWidth = 128,  SQCIFHeight = 96,
      QCIFWidth  = 176,  QCIFHeight  = 144,
      CIFWidth   = 352,  CIFHeight   = 288,
      CIF4Width  = 704,  CIF4Height  = 576,
      CIF16Width = 1408, CIF16Height = 1152,
      i480Width  = 640,  i480Height  = 480,
      p720Width  = 960,  p720Height  = 720,
      i1080Width = 1920, i1080Height = 1080,
      HDTVWidth  = 1920, HDTVHeight  = 1080,
      MaxWidth   = 1920, MaxHeight   = 1152
    };

    PVideoFrameInfo();
    PVideoFrameInfo(
      unsigned        frameWidth,
      unsigned        frameHeight,
      const PString & colourFormat = "YUV420P",
      unsigned        frameRate = 15,
      ResizeMode      resizeMode = eScale
    );

    virtual void PrintOn(
      ostream & strm   // Stream to print the object into.
    ) const;

    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 SetFrameSar(unsigned width, unsigned height);

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

    virtual unsigned GetSarWidth() const;

    virtual unsigned GetSarHeight() 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  
    );

    bool Parse(
      const PString & str   
    );

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

    static PString AsString(
      unsigned width,     
      unsigned height     
    );

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


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

 public:

    typedef enum {
      ControlPan,
      ControlTilt,
      ControlZoom
    } InputControlType;

    static PString AsString(const InputControlType & type);

    InputControlType type;
    long             min;
    long             max;
    long             step;
    long             def;
    long             flags;
    long             current;
};


class PVideoInputControl : public PVideoControlInfo
{
    PCLASSINFO(PVideoInputControl, PVideoControlInfo);

public:
  ~PVideoInputControl();

  virtual PBoolean Pan(long value, bool absolute = false );
  virtual PBoolean Tilt(long value, bool absolute = false);
  virtual PBoolean Zoom(long value, bool absolute = false);

  long GetPan();
  long GetTilt();
  long GetZoom();

  void Reset();
  void SetCurrentPosition(const InputControlType ctype, long current);

  typedef std::list<PVideoControlInfo> InputDeviceControls;

protected:
  PBoolean GetVideoControlInfo(const InputControlType ctype, PVideoControlInfo & control);
  PBoolean GetDefaultPosition(const InputControlType ctype, long & def);
  PBoolean GetCurrentPosition(const InputControlType ctype, long & current);

  std::list<PVideoControlInfo> m_info;
  PMutex ccmutex;

};

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

 public:

   typedef enum {
        InteractKey,    
        InteractMouse,    
        InteractNavigate,  
    InteractRTSP,    
    InteractOther    
     } InputInteractType;

   static PString AsString(const InputInteractType & type);

  InputInteractType type;
};


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 PStringArray 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 = true  
    );

    virtual PBoolean Open(
      const PString & deviceName,   
      PBoolean startImmediate = true    
    ) = 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; }
    
  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;
};


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

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

    static PStringArray GetDriverNames(
      PPluginManager * pluginMgr = NULL   
    );

    static PStringArray 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 = true,         
      PPluginManager * pluginMgr = NULL   
    );

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

    virtual PBoolean Close() { return true; }

    virtual PBoolean Start() { return true; }

    virtual PBoolean Stop() { return true; }

    virtual PBoolean CanCaptureVideo() const;

    virtual PBoolean SetFrameData(
      unsigned x,
      unsigned y,
      unsigned width,
      unsigned height,
      const BYTE * data,
      PBoolean endFrame = true
    ) = 0;
    virtual PBoolean SetFrameData(
      unsigned x,
      unsigned y,
      unsigned width,
      unsigned height,
      const BYTE * data,
      PBoolean endFrame,
      unsigned flags
    );
    virtual PBoolean SetFrameData(
      unsigned x,
      unsigned y,
      unsigned width,
      unsigned height,
      unsigned sarwidth,
      unsigned sarheight,
      const BYTE * data,
      PBoolean endFrame,
      unsigned flags,
      const void * mark
    );

    virtual PBoolean DisableDecode();

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

    virtual bool SetPosition(
      int x,  // X position of device surface
      int y   // Y position of device surface
    );
};


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 = true
    );

    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 = true    
    );

    virtual PBoolean IsOpen();

    virtual PBoolean Close();

    virtual PStringArray 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 PStringArray GetDriverNames(
      PPluginManager * pluginMgr = NULL   
    );

    static PStringArray 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 = true,         
      PPluginManager * pluginMgr = NULL   
    );

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

  typedef struct {
     std::list<PVideoFrameInfo> framesizes;
     std::list<PVideoControlInfo> controls;
     std::list<PVideoInteractionInfo> interactions;
  } Capabilities;

    virtual bool GetDeviceCapabilities(
      Capabilities * capabilities          
    ) const { return GetDeviceCapabilities(GetDeviceName(), 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 PVideoInputControl * GetVideoInputControls();

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

    virtual PBoolean Close(
    ) { return true; }

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

    virtual PBoolean GetFrame(
      PBYTEArray & frame
    );

    virtual PBoolean GetFrameData(
      BYTE * buffer,                 
      PINDEX * bytesReturned,        
      unsigned int & flags           
    );
    virtual PBoolean GetFrameData(
      BYTE * buffer,                 
      PINDEX * bytesReturned = NULL  
    ) = 0;

    virtual PBoolean GetFrameDataNoDelay(
      BYTE * buffer,                 
      PINDEX * bytesReturned,       
      unsigned int & flags           
    );
    virtual PBoolean GetFrameDataNoDelay(
      BYTE * buffer,                 
      PINDEX * bytesReturned = NULL  
    ) = 0;

    virtual bool FlowControl(const void * flowData);

    virtual bool SetCaptureMode(unsigned mode);

    virtual int GetCaptureMode() const;
};


//
// 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 PStringArray 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)

PPLUGIN_STATIC_LOAD(FakeVideo, PVideoInputDevice);

#ifdef P_APPSHARE
  PPLUGIN_STATIC_LOAD(Application, PVideoInputDevice);
#endif

#if P_FFVDEV
  PPLUGIN_STATIC_LOAD(FFMPEG, PVideoInputDevice);
#endif

#if P_VIDFILE
  PPLUGIN_STATIC_LOAD(YUVFile, PVideoInputDevice);
#endif

#ifdef P_DIRECTSHOW
  PPLUGIN_STATIC_LOAD(DirectShow, PVideoInputDevice);
#endif


//
// 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 PStringArray 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)

#if _WIN32
  PPLUGIN_STATIC_LOAD(Window, PVideoOutputDevice);
#endif

#if P_SDL
  PPLUGIN_STATIC_LOAD(SDL, PVideoOutputDevice);
#endif


//
// 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   // PTLIB_PVIDEOIO_H

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

---