diff options
Diffstat (limited to 'packages/noncvs/windows/extra/Gem/dev/plugins')
7 files changed, 942 insertions, 0 deletions
diff --git a/packages/noncvs/windows/extra/Gem/dev/plugins/PluginFactory.h b/packages/noncvs/windows/extra/Gem/dev/plugins/PluginFactory.h new file mode 100644 index 00000000..5755748e --- /dev/null +++ b/packages/noncvs/windows/extra/Gem/dev/plugins/PluginFactory.h @@ -0,0 +1,105 @@ +#ifndef _INCLUDE__GEM_PLUGINS_PLUGINFACTORY_H_ +#define _INCLUDE__GEM_PLUGINS_PLUGINFACTORY_H_ + +#include "Gem/ExportDef.h" + + +#include <map> +#include <vector> +#include <string> + +#include <typeinfo> +#include <iostream> + +namespace gem { + + class GEM_EXTERN BasePluginFactory { + public: + int doLoadPlugins(std::string basename, std::string path); + protected: + BasePluginFactory(); + virtual ~BasePluginFactory(void); + + std::vector<std::string>get(void); + void*get(std::string); + void set(std::string, void*); + + private: + class Pimpl; + Pimpl*m_pimpl; + }; + + template<class Class> + class GEM_EXPORT PluginFactory : public BasePluginFactory { + public: + + /** + * constructor function type (without arguments) + */ + typedef Class*(ctor_t)(void); + + /** + * register a a constructor associated with a given ID + */ + static void registerClass(std::string id, ctor_t*c); + /** + * get an instance of class constructed by the constructor associated with the given ID + */ + static Class*getInstance(std::string id); + + /** + * get a list of all IDs currently registered with this factory + */ + static std::vector<std::string>getIDs(void); + + /** + * load more plugins + */ + static int loadPlugins(std::string basename, std::string path=std::string("")); + + private: + static PluginFactory<Class>*s_factory; + static PluginFactory<Class>*getPluginFactory(); + + void doRegisterClass(std::string id, ctor_t*c); + Class*doGetInstance(std::string id); + std::vector<std::string>doGetIDs(void); + }; + + + namespace PluginFactoryRegistrar { + /** + * creates a new ChildClass and returns it as a (pointer to) an instance of BaseClass + */ + template<class ChildClass, class BaseClass> + static BaseClass* allocator(void); + + /** + * registers a ChildClass with a certain ID in the BaseClass factory + * + * example: + * static gem::PluginFactoryRegistrar<Child, Base, std::string > basefac_childreg("childID"); // register Child as 'childID' + * Base*instance=gem::PluginFactory<Base>::getInstance("childID"); // returns an instance of Child + */ + template<class ChildClass, class BaseClass> + struct registrar { + registrar(std::string ID); + }; + + /** + * registers a dummy constructor with a default ID + */ + template<class BaseClass> + struct dummy { + dummy(void); + }; + }; + +/* include the actual implementation */ +#include "PluginFactoryTimple.h" + + +}; // namespace gem + + +#endif /* _INCLUDE__GEM_PLUGINS_PLUGINFACTORY_H_ */ diff --git a/packages/noncvs/windows/extra/Gem/dev/plugins/PluginFactoryTimple.h b/packages/noncvs/windows/extra/Gem/dev/plugins/PluginFactoryTimple.h new file mode 100644 index 00000000..a82762d1 --- /dev/null +++ b/packages/noncvs/windows/extra/Gem/dev/plugins/PluginFactoryTimple.h @@ -0,0 +1,134 @@ + +/*----------------------------------------------------------------- +LOG + GEM - Graphics Environment for Multimedia + + - template implementation for PluginFactory + + Copyright (c) 2010-2011 IOhannes m zmölnig. forum::für::umläute. IEM. zmoelnig@iem.at + For information on usage and redistribution, and for a DISCLAIMER OF ALL + WARRANTIES, see the file, "GEM.LICENSE.TERMS" in this distribution. + +-----------------------------------------------------------------*/ + +#ifndef _INCLUDE__GEM_PLUGINS_PLUGINFACTORY_H_ +# error you must not include PluginFactory Implementation directly! include PluginFactory.h instead +#endif + +/* on M$VC (at least v2007) we must not define the template-implementation in the plugins + * if we want to use the same implementation in both host and application + * + * on gcc (at least on linux) we have to provide the implementation + */ +#if defined _MSC_VER && !defined GEM_INTERNAL +# define OMIT_PLUGINFACTORY_TEMPLATE_IMPLEMENATION +#endif + +#ifndef OMIT_PLUGINFACTORY_TEMPLATE_IMPLEMENATION + +/* Implementation of templated PluginFactory */ +/* actually this should be done in a cpp file rather than a header-file, + * but since virtually no compiler can handle this it is done here... + */ + + +/* ********************************************************************* */ +/* Implementation of PluginFactory<Class> */ + +template<class Class> + PluginFactory<Class>* PluginFactory<Class>::s_factory=NULL; + +template<class Class> + PluginFactory<Class>* PluginFactory<Class>::getPluginFactory(void) { + if(NULL==s_factory) { + s_factory=new PluginFactory<Class>; + } + //std::cerr << "factory @ " << (void*)s_factory << " --> " << typeid(s_factory).name() << std::endl; + return s_factory; +} + +template<class Class> + void PluginFactory<Class>::doRegisterClass(std::string id, ctor_t*c) { + set(id, (void*)c); +} + +template<class Class> + Class*PluginFactory<Class>::doGetInstance(std::string id) { + ctor_t*ctor=(ctor_t*)get(id); + if(ctor) + return ctor(); + else + return NULL; +} + +template<class Class> +void PluginFactory<Class>::registerClass(std::string id, ctor_t*c) { + PluginFactory<Class>*fac=getPluginFactory(); + if(NULL==fac) { + std::cerr << "unable to get a factory!" << std::endl; + } + // std::cerr << "factory @ " << (void*)fac << std::endl; + fac->doRegisterClass(id, c); +} + +template<class Class> +Class*PluginFactory<Class>::getInstance(std::string id) { + PluginFactory<Class>*fac=getPluginFactory(); + if(NULL==fac) { + return NULL; + } + return(fac->doGetInstance(id)); +} + +template<class Class> + int PluginFactory<Class>::loadPlugins(std::string basename, std::string path) { + PluginFactory<Class>*fac=getPluginFactory(); + if(NULL==fac) { + return 0; + } + return fac->doLoadPlugins(basename, path); +} + +template<class Class> + std::vector<std::string>PluginFactory<Class>::doGetIDs() { + return get(); +} + +template<class Class> + std::vector<std::string>PluginFactory<Class>::getIDs() { + std::vector<std::string>result; + PluginFactory<Class>*fac=getPluginFactory(); + if(fac) { + return fac->doGetIDs(); + } + return result; +} + +#endif /* !OMIT_PLUGINFACTORY_TEMPLATE_IMPLEMENATION */ + +/* ********************************************************************* */ +/* Implementation of PluginFactoryRegistrar<ChildClass, BaseClass> */ + +namespace PluginFactoryRegistrar { + template<class ChildClass, class BaseClass> + BaseClass* allocator() { + ChildClass* res0 = new ChildClass(); + BaseClass* res1 = dynamic_cast<BaseClass*>(res0); + if(NULL==res1) { + delete res0; + } + return res1; + } + + template<class ChildClass, class BaseClass> + registrar<ChildClass, BaseClass> :: registrar(std::string id) { + PluginFactory<BaseClass>::registerClass(id, allocator<ChildClass, BaseClass>); + } + template<class BaseClass> + dummy<BaseClass> :: dummy() { + std::string id; // default ID + PluginFactory<BaseClass>::registerClass(id, NULL); + } + +}; + diff --git a/packages/noncvs/windows/extra/Gem/dev/plugins/film.h b/packages/noncvs/windows/extra/Gem/dev/plugins/film.h new file mode 100644 index 00000000..313c796a --- /dev/null +++ b/packages/noncvs/windows/extra/Gem/dev/plugins/film.h @@ -0,0 +1,173 @@ +/* ----------------------------------------------------------------- + +GEM - Graphics Environment for Multimedia + +Load an digital video (like AVI, Mpeg, Quicktime) into a pix block +(OS independant parent-class) + +Copyright (c) 1997-1999 Mark Danks. mark@danks.org +Copyright (c) Günther Geiger. geiger@epy.co.at +Copyright (c) 2001-2011 IOhannes m zmölnig. forum::für::umläute. IEM. zmoelnig@iem.at +For information on usage and redistribution, and for a DISCLAIMER OF ALL +WARRANTIES, see the file, "GEM.LICENSE.TERMS" in this distribution. + +-----------------------------------------------------------------*/ + +#ifndef _INCLUDE__GEM_PLUGINS_FILM_H_ +#define _INCLUDE__GEM_PLUGINS_FILM_H_ + +#include "Gem/ExportDef.h" +#include "Gem/GemGL.h" +#include <string> + +/*----------------------------------------------------------------- + ------------------------------------------------------------------- + CLASS + film + + parent class for the system- and library-dependent film-loader classes + + KEYWORDS + pix film movie + + DESCRIPTION + + -----------------------------------------------------------------*/ + +class pixBlock; +namespace gem { + class Properties; +} +namespace gem { namespace plugins { +class GEM_EXTERN film +{ + public: + + ////////// + // returns an instance wrapping all plugins or NULL + // if NULL is returned, you might still try your luck with manually accessing the + // PluginFactory + static film*getInstance(void); + + ///////// + // dtor must be virtual + virtual ~film(void); + + ////////// + // open a movie up + /* open the film "filename" (think better about URIs ?) + * + * try to open the film with the requested properties + * + * about properties: + * requestprops: are properties that can change the behaviour of how the + * film is opened; examples are "colorspace" (e.g. GL_RGBA) or + * "streaming" (rather than random frame access) + * the backend need not implement any of the properties + * + * resultprops: give feedback about the opened film + * if the film could not be opened, the content is undefined + * if the film was successfully opened, following properties should be set + * if a property can not be determined (e.g. variable fps), it should be set unset + * + * + * discussion: should the colourspace be only a hint or should we force it + * (evt. by converting the actual cs by hand to the desired one) + * more discussion: i guess the cs should really be forced somehow by [pix_film] + * now i don't know, whether the cs-conversion should be done by [pix_film] itself or + * rather by the film*-classes. + * but i guess film* makes more sense, because then, [pix_film] doesn't have to know + * anything about the internal cs of the decoder + */ + /* returns TRUE if loading was successfull, FALSE otherwise */ + virtual bool open(const std::string, + const gem::Properties&requestprops) = 0; + + /* some error codes */ + enum errCode { SUCCESS = 0, + FAILURE = 1, + DONTKNOW= 2 }; + + ////////// + // Change which image to display + /* this is the second core function of this class: + * most decoding-libraries can set the frame-number on a random-access basis. + * some cannot, then this might do nothing + * you could also switch between various tracks of a file (if the format supports it) + * specifying trackNum as -1 means "same track as before" + */ + virtual errCode changeImage(int imgNum, int trackNum=-1) = 0; + + ////////// + // get the next frame + /* this is the core-function of this class !!!! + * when called it returns the current frame in the *pixBlock structure + * dev: you can use "m_image" for this (and "return &m_image;") + * if the image cannot be read, returns 0 + * dev: you probably want to set the whole meta-information + * (xsize,ysize,csize,format) over again + * if you are smart and the colour-space is fine, just point + * if this is a "new" frame (e.g. freshly decoded), + * pixblock.newimage should be set to 1 + */ + virtual pixBlock* getFrame(void) = 0; + + ////////// + // close the movie file + /* close the file and clean up temporary things */ + virtual void close(void) = 0; + + + //////// + // returns true if instance can be used in thread + virtual bool isThreadable(void) = 0; + + /** + * list all properties the currently opened film supports + * if no film is opened, this returns generic backend properties + * which can be different from media specific properties + * after calling, "readable" will hold a list of all properties that can be read + * and "writeable" will hold a list of all properties that can be set + * if the enumeration fails, this returns <code>false</code> + */ + + virtual bool enumProperties(gem::Properties&readable, + gem::Properties&writeable) = 0; + + /** + * set a number of properties (as defined by "props") + * the "props" may hold properties not supported by the currently opened media, + * which is legal; in this case the superfluous properties are simply ignored + * this function MAY modify the props; + * namely one-shot properties should be removed from the props + * + * examples: "colorspace" GL_RGBA + * "auto" 1 + */ + virtual void setProperties(gem::Properties&props) = 0; + + /** + * get the current value of the given properties from the media + * if props holds properties that can not be read for the media, they are set to UNSET + * + * "width" (width of each frame in pixels) + * "height" (height of each frame in pixels) + * "fps" (frames per second) + * "frames" (framecount) + */ + virtual void getProperties(gem::Properties&props) = 0; +}; + +};}; // namespace gem::plugins + + +/** + * \fn REGISTER_FILMFACTORY(const char *id, Class filmClass) + * registers a new class "filmClass" with the film-factory + * + * \param id a symbolic (const char*) ID for the given class + * \param filmClass a class derived from "film" + */ +#define REGISTER_FILMFACTORY(id, TYP) static gem::PluginFactoryRegistrar::registrar<TYP, gem::plugins::film> fac_film_ ## TYP (id) + +#endif // for header file diff --git a/packages/noncvs/windows/extra/Gem/dev/plugins/imageloader.h b/packages/noncvs/windows/extra/Gem/dev/plugins/imageloader.h new file mode 100644 index 00000000..111ad822 --- /dev/null +++ b/packages/noncvs/windows/extra/Gem/dev/plugins/imageloader.h @@ -0,0 +1,75 @@ +/* ----------------------------------------------------------------- + +GEM - Graphics Environment for Multimedia + +Load an image and return the frame(OS independant interface) + +Copyright (c) 2011-2011 IOhannes m zmölnig. forum::für::umläute. IEM. zmoelnig@iem.at +For information on usage and redistribution, and for a DISCLAIMER OF ALL +WARRANTIES, see the file, "GEM.LICENSE.TERMS" in this distribution. + +-----------------------------------------------------------------*/ + +#ifndef _INCLUDE__GEM_PLUGINS_IMAGELOADER_H_ +#define _INCLUDE__GEM_PLUGINS_IMAGELOADER_H_ + +#include "Gem/Image.h" +#include "Gem/Properties.h" + +#include <string> + +/*----------------------------------------------------------------- + ------------------------------------------------------------------- + CLASS + imageloader + + interface for the system- and library-dependent imageloader classes + + KEYWORDS + pix load an image + + DESCRIPTION + + -----------------------------------------------------------------*/ +namespace gem { namespace plugins { + class GEM_EXTERN imageloader + { + public: + + ////////// + // returns an instance wrapping all plugins or NULL + // if NULL is returned, you might still try your luck with manually accessing the + // PluginFactory + static imageloader*getInstance(void); + + //////// + // dtor must be virtual + virtual ~imageloader(void); + + /* read a image + * + * props can be filled by the loader with additional information on the image + * e.g. EXIF tags,... + */ + /* returns TRUE if loading was successfull, FALSE otherwise */ + virtual bool load(std::string filename, + imageStruct&result, + gem::Properties&props) = 0; + + /* returns TRUE if this object can be used from within a thread */ + virtual bool isThreadable(void) = 0; + }; + + };}; // namespace gem + + +/** + * \fn REGISTER_IMAGELOADERFACTORY(const char *id, Class imageloaderClass) + * registers a new class "imageloaderClass" with the imageloader-factory + * + * \param id a symbolic (const char*) ID for the given class + * \param imageloaderClass a class derived from "imageloader" + */ +#define REGISTER_IMAGELOADERFACTORY(id, TYP) static gem::PluginFactoryRegistrar::registrar<TYP, gem::plugins::imageloader> fac_imageloader_ ## TYP (id) + +#endif // for header file diff --git a/packages/noncvs/windows/extra/Gem/dev/plugins/imagesaver.h b/packages/noncvs/windows/extra/Gem/dev/plugins/imagesaver.h new file mode 100644 index 00000000..dfb45ae9 --- /dev/null +++ b/packages/noncvs/windows/extra/Gem/dev/plugins/imagesaver.h @@ -0,0 +1,126 @@ +/* ----------------------------------------------------------------- + +GEM - Graphics Environment for Multimedia + +Load an image and return the frame(OS independant interface) + +Copyright (c) 2011-2011 IOhannes m zmölnig. forum::für::umläute. IEM. zmoelnig@iem.at +For information on usage and redistribution, and for a DISCLAIMER OF ALL +WARRANTIES, see the file, "GEM.LICENSE.TERMS" in this distribution. + +-----------------------------------------------------------------*/ + +#ifndef _INCLUDE__GEM_PLUGINS_IMAGESAVER_H_ +#define _INCLUDE__GEM_PLUGINS_IMAGESAVER_H_ + +#include "Gem/Image.h" +#include "Gem/Properties.h" + +#include <string> + + +/*----------------------------------------------------------------- + ------------------------------------------------------------------- + CLASS + imagesaver + + interface for the system- and library-dependent imagesaver classes + + KEYWORDS + save a pix to disk + + DESCRIPTION + + -----------------------------------------------------------------*/ +namespace gem { namespace plugins { + class GEM_EXTERN imagesaver + { + public: + + ////////// + // returns an instance wrapping all plugins or NULL + // if NULL is returned, you might still try your luck with manually accessing the + // PluginFactory + static imagesaver*getInstance(void); + + //////// + // dtor must be virtual + virtual ~imagesaver(void); + + /* save the image 'img' under the filename 'filename', respecting as many 'props' as possible + * + * returns TRUE if saving was successfull, FALSE otherwise */ + virtual bool save(const imageStruct&img, const std::string&filename, const std::string&mimetype, const gem::Properties&props) = 0; + + /* estimate how 'well' we could save the 'img' + * this is used to rate the different backends for a given image + * + * e.g. if the user requests saving of an image as <filename>, virtually all backends will have a way to to as requested + * however, if filename was "bla.jpg", a TIFF-backend might save as a TIFF-image with a .jpg extension, + * which is probably not what the user expected (esp. if there _is_ a JPEG-backend, which for whatever reasons + * would only have been called after the TIFF-backend) + * + * the solution is quite simple: each backend is first asked, how well it could save a given image according to properties + * the backend that returns the highest value, will be chosen first; if it fails to save the image + * (returning FALSE in the save() function), the backend with the next higher rating will be chosen and so on + * + * + * mimetype and properties are the main factors for rating; + * 'mimetype' (string): mimetype of the image; e.g. 'image/jpeg' means 'write the image as JPEG' + * if not empty, the mimetype will override all other ways to set the output format (like filename) + * even though we only expect mimetypes of type 'image/*', the prefix ('image/') is mandatory + * a predefined properties (for legacy reasons) is: + * 'quality' (float) : for lossy formats, this is the quality (in percent) + * + * expected return values: + * <=0: 'USE ME IF YOU MUST (but rather not)' + * 0 is returned, if the backend expects to be able to save the given image under the given + * filename to disk, but it will ignore all properties (including the mimetype!) and will + * ignore all file extensions + * it is hoped that '0' is never the winner (for any feasible format) + * example: saves a TIFF-image as /tmp/foo.doc + * 100: 'YES' + * 100 is returned, if the plugin knows how to handle the given 'mimetype' property + * if 'mimetype' is empty and the plugin has performed an heuristic based on the filename + * to determine that the user wants a format that is provided by this very plugin, it can return 100 as well. + * however, if 'mimetype' and file extension contradict each other, 'mimetype' wins! + * 100+: 'YES, ABSOLUTELY' + * every additional property that can be applied, gains an extra point + * example: both the JPG and the JPEG2K backend provide saving of jpegs, but only JPG can set the quality + * the user requests: filename=img.jpg,mimetype='image/jpeg',quality=20 + * JPG returns 101, whereas JPEG2K returns 100, so JPG wins and writes + * 0..50: the backend knows how to handle some of the properties (but it has no clue about the output format requested + * example: filename=img.tif,mimetype='image/tiff',quality=20 + * JPG knows how to handle the 'quality' property, but not the 'mimetype', so it scores 1 point + * TIFF knows how to handle the 'mimetype' but not the 'quality', so it scores 100 points + */ + virtual float estimateSave( const imageStruct&img, const std::string&filename, const std::string&mimetype, const gem::Properties&props) = 0; + + /** + * get writing capabilities of this backend (informative) + * + * list all (known) mimetypes and properties this backend supports for writing + * both can be empty, if they are not known when requested + * if only some properties/mimetypes are explicitely known (but it is likely that more are supported), + * it is generally better, to list the few rather than nothing + */ + virtual void getWriteCapabilities(std::vector<std::string>&mimetypes, gem::Properties&props) = 0; + + /* returns TRUE, if it is save to use this backend from multple threads + */ + virtual bool isThreadable(void) = 0; + }; + + }; }; // namespace gem + + +/** + * \fn REGISTER_IMAGESAVERFACTORY(const char *id, Class imagesaverClass) + * registers a new class "imagesaverClass" with the imagesaver-factory + * + * \param id a symbolic (const char*) ID for the given class + * \param imagesaverClass a class derived from "imagesaver" + */ +#define REGISTER_IMAGESAVERFACTORY(id, TYP) static gem::PluginFactoryRegistrar::registrar<TYP, gem::plugins::imagesaver> fac_imagesaver_ ## TYP (id) + +#endif // for header file diff --git a/packages/noncvs/windows/extra/Gem/dev/plugins/record.h b/packages/noncvs/windows/extra/Gem/dev/plugins/record.h new file mode 100644 index 00000000..8b317539 --- /dev/null +++ b/packages/noncvs/windows/extra/Gem/dev/plugins/record.h @@ -0,0 +1,108 @@ +/* ----------------------------------------------------------------- + +GEM - Graphics Environment for Multimedia + +Load an digital video (like AVI, Mpeg, Quicktime) into a pix block +(OS independant interface) + +Copyright (c) 2010-2011 IOhannes m zmölnig. forum::für::umläute. IEM. zmoelnig@iem.at +For information on usage and redistribution, and for a DISCLAIMER OF ALL +WARRANTIES, see the file, "GEM.LICENSE.TERMS" in this distribution. + +-----------------------------------------------------------------*/ + +#ifndef _INCLUDE__GEM_PLUGINS_RECORD_H_ +#define _INCLUDE__GEM_PLUGINS_RECORD_H_ + +#include "Gem/Image.h" +#include "Gem/Properties.h" +#include <string> + + +/*----------------------------------------------------------------- + ------------------------------------------------------------------- + CLASS + record + + parent class for the system- and library-dependent record-loader classes + + KEYWORDS + pix record movie + + DESCRIPTION + + -----------------------------------------------------------------*/ +namespace gem { namespace plugins { + class GEM_EXTERN record +{ +public: + + ////////// + // returns an instance wrapping all plugins or NULL + // if NULL is returned, you might still try your luck with manually accessing the + // PluginFactory + static record*getInstance(void); + + ///////// + // dtor must be virtual + virtual ~record(void); + + /** + * get a list of supported codecs (short-form names, e.g. "mjpa") + */ + virtual std::vector<std::string>getCodecs(void) = 0; + /** + * get a human readable description of the given codec (e.g. "Motion Jpeg A") + */ + virtual const std::string getCodecDescription(const std::string codecname) = 0; + /** + * set the current codec + */ + virtual bool setCodec(const std::string name) = 0; + + /** + * list all properties the currently selected codec supports + * if the enumeration fails, this returns <code>false</code> + */ + virtual bool enumProperties(gem::Properties&props) = 0; + + ////////// + // popup a dialog to set the codec interactively (interesting on os-x and w32) + // just return FALSE if you don't support dialogs + virtual bool dialog(void) = 0; + + ////////// + // start recording + /* + * returns TRUE if opening was successfull, FALSE otherwise + */ + virtual bool start(const std::string filename, gem::Properties&props) = 0; + + ////////// + // record a frame + virtual bool write(imageStruct*) = 0; + + ////////// + // stop recording + virtual void stop (void) = 0; + + }; +}; }; + + + +/* + * factory code: + * to use these macros, you have to include "plugins/PluginFactory.h" + */ + +/** + * \fn REGISTER_RECORDFACTORY(const char *id, Class recordClass) + * registers a new class "recordClass" with the record-factory + * + * \param id a symbolic (const char*) ID for the given class + * \param recordClass a class derived from "record" + */ +#define REGISTER_RECORDFACTORY(id, TYP) static gem::PluginFactoryRegistrar::registrar<TYP, gem::plugins::record> fac_record_ ## TYP (id) + +#endif // for header file diff --git a/packages/noncvs/windows/extra/Gem/dev/plugins/video.h b/packages/noncvs/windows/extra/Gem/dev/plugins/video.h new file mode 100644 index 00000000..1b15f9ac --- /dev/null +++ b/packages/noncvs/windows/extra/Gem/dev/plugins/video.h @@ -0,0 +1,221 @@ +/*----------------------------------------------------------------- + +GEM - Graphics Environment for Multimedia + +Base Class for Video Capture Plugins + +Copyright (c) 2010-2011 IOhannes m zmölnig. forum::für::umläute. IEM. zmoelnig@iem.at +For information on usage and redistribution, and for a DISCLAIMER OF ALL +WARRANTIES, see the file, "GEM.LICENSE.TERMS" in this distribution. + +-----------------------------------------------------------------*/ + +#ifndef _INCLUDE__GEM_PLUGINS_VIDEO_H_ +#define _INCLUDE__GEM_PLUGINS_VIDEO_H_ + +#include "Gem/Properties.h" +#include <vector> +#include <string> + +/*----------------------------------------------------------------- + ------------------------------------------------------------------- + CLASS + video + + a OS-indendent interface for grabbing video-frames + + KEYWORDS + pix, capture + + -----------------------------------------------------------------*/ +struct pixBlock; +namespace gem { namespace plugins { + class GEM_EXTERN video { + public: + + ////////// + // returns an instance wrapping all plugins or NULL + // if NULL is returned, you might still try your luck with manually accessing the + // PluginFactory + static video*getInstance(void); + + //////// + // dtor must be virtual + virtual ~video(void); + + ////////////////////// + // device settings + + /** + * enumerate known devices + * \return a list of device names (if they can be enumerated) + */ + virtual std::vector<std::string>enumerate(void) = 0; + + /** + * set the device to be opened next time + * the ID provided should match an index in the list returned by enumerate() + * after the device has been set, the caller(!) has to restart + * (close() the current handle, try open() with the new settings) + * the default implementation (which you normally shouldn't need to override) + * will simply set m_devicenum and clear m_devicename + */ + virtual bool setDevice(int ID) = 0; + + /** + * set the device to be opened next time + * the list returned by enumerate() provides a set of valid names to use here + * depending on the backend, other names might be possible as well (e.g. IP-cameras) + * after the device has been set, the caller(!) has to restart + * (close() the current handle, try open() with the new settings) + * the default implementation (which you normally shouldn't need to override) + * will simply set m_devicename and clear m_devicenum + */ + virtual bool setDevice(const std::string) = 0; + + + //! open the device (calls openDevice()) + virtual bool open(gem::Properties&props) = 0; + //! start the transmission (calls startTransfer()) + virtual bool start(void) = 0; + + /** + * get the next frame (called when rendering) + * grab the next frame from the device + * if no new frame is available, this should set the "newimage" flag to false + * \return the new frame or NULL on error + */ + virtual pixBlock *getFrame(void) = 0; + + /** + * release a frame (after use) + * this gets called once for each frame retrieved via getFrame() + * if you are using DMA or the like, now is the time to release the ressource + */ + virtual void releaseFrame(void) = 0; + + + //! stop the transmission (calls stopTransfer()) + virtual bool stop(void) = 0; + //! close the device (calls closeDevice()) + virtual void close(void) = 0; + + /** + * reset the backend, possibly re-enumerating devices + * returns TRUE if reset was successfull + */ + virtual bool reset(void) = 0; + + + /** + * list all properties the currently opened device supports + * after calling, "readable" will hold a list of all properties that can be read + * and "writeable" will hold a list of all properties that can be set + * if the enumeration fails, this returns <code>false</code> + * + * the backend has to provide the names for the properties + * these are defined by default, and need not be enumerated! + * "width" "dimen" message (float) + * "height" "dimen" message (float) + * "leftmargin" ("dimen" message) (float) + * "rightmargin" ("dimen" message) (float) + * "toptmargin" ("dimen" message) (float) + * "bottommargin" ("dimen" message) (float) + * "channel" "channel" message (float) + * "frequency" "channel" message (float) + * "norm" "norm" message (string) + * "quality" "quality" message (float) + */ + virtual bool enumProperties(gem::Properties&readable, + gem::Properties&writeable) = 0; + + /** + * set a number of properties (as defined by "props") + * the "props" may hold properties not supported by the currently opened device, + * which is legal; in this case the superfluous properties are simply ignored + * this function MAY modify the props; + * namely one-shot properties (e.g. "do-white-balance-now") + * should be removed from the props + */ + virtual void setProperties(gem::Properties&props) = 0; + + /** + * get the current value of the given properties from the device + * if props holds properties that can not be read from the device, they are set to UNSET + */ + virtual void getProperties(gem::Properties&props) = 0; + + + /** + * call a system-specific configuration dialog + * if your system provides a GUI for configuring the device, here is the time to open it + * of several dialogs are available (for different properties), the user can specify which one + * they want with the string list + * if the list is empty, provide sane defaults (e.g. ALL dialogs) + * if the system does not support dialogs, return FALSE + * if the system does support dialogs and the user has specified which one they want, + * return TRUE if at least one dialog could be handled + */ + virtual bool dialog(std::vector<std::string>names=std::vector<std::string>()) = 0; + /** + * enumerate list of possible dialogs (if any) + */ + virtual std::vector<std::string>dialogs(void) = 0; + + + + + + /** + * returns TRUE if the object can be used in a thread or FALSE otherwise + * if a backend implements threading itself, it should return FALSE + * in order to prevent double threading + */ + virtual bool isThreadable(void) = 0; + + + /** turn on/off "asynchronous"-grabbing + * default is "true" + * "asynchronous" means, that the device is constantly grabbing, and grabFrame() returns the current frame + * non-"continous" means, that the device will only issue a new grab when a frame has read + * (thus potentially reducing the CPU-load to what is needed, at the cost of slightly outdated images + * returns: the old state + */ + virtual bool grabAsynchronous(bool) = 0; + + /** + * Set the preferred colorspace (of the frames returned by getFrame() + * \return FALSE if the colorspace cannot be set (e.g. while grabbing is active) + */ + virtual bool setColor(int) = 0; + + + // meta information about the plugin + + // for pix_video: query whether this backend provides access to this class of devices + // (e.g. "dv") + virtual bool provides(const std::string) = 0; + // get a list of all provided devices + virtual std::vector<std::string>provides(void) = 0; + + // get's the name of the backend (e.g. "v4l") + virtual const std::string getName(void) = 0; + }; + };}; // namespace + +/* + * factory code: + * to use these macros, you have to include "plugins/PluginFactory.h" + */ + + +/** + * \fn REGISTER_VIDEOFACTORY(const char *id, Class videoClass) + * registers a new class "videoClass" with the video-factory + * + * \param id a symbolic (const char*) ID for the given class + * \param videoClass a class derived from "video" + */ +#define REGISTER_VIDEOFACTORY(id, TYP) static gem::PluginFactoryRegistrar::registrar<TYP, gem::plugins::video> fac_video_ ## TYP (id) + +#endif // for header file |