Fawkes API
Fawkes Development Version
|
00001 00002 /*************************************************************************** 00003 * vision_master.cpp - FireVision Vision Master 00004 * 00005 * Created: Wed May 30 10:52:08 2007 00006 * Copyright 2006-2009 Tim Niemueller [www.niemueller.de] 00007 * 00008 ****************************************************************************/ 00009 00010 /* This program is free software; you can redistribute it and/or modify 00011 * it under the terms of the GNU General Public License as published by 00012 * the Free Software Foundation; either version 2 of the License, or 00013 * (at your option) any later version. A runtime exception applies to 00014 * this software (see LICENSE.GPL_WRE file mentioned below for details). 00015 * 00016 * This program is distributed in the hope that it will be useful, 00017 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00018 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00019 * GNU Library General Public License for more details. 00020 * 00021 * Read the full text in the LICENSE.GPL_WRE file in the doc directory. 00022 */ 00023 00024 #include <fvutils/base/vision_master.h> 00025 00026 using namespace fawkes; 00027 00028 namespace firevision { 00029 #if 0 /* just to make Emacs auto-indent happy */ 00030 } 00031 #endif 00032 00033 /** @class VisionMaster <fvutils/base/vision_master.h> 00034 * Vision Master. 00035 * The vision master shall be the entry point for vision plugins. It shall 00036 * allow for requesting cameras that are opened in a central place such that 00037 * the very same camera can be used in multiple plugins. 00038 * 00039 * It shall also be responsible for the central timing of all vision threads. 00040 * 00041 * @author Tim Niemueller 00042 * 00043 * @fn Camera * VisionMaster::register_for_camera(const char *camera_string, Thread *thread, colorspace_t cspace=YUV422_PLANAR) = 0 00044 * Register thread for camera. 00045 * This will register a relation between the given thread and the camera identified 00046 * by the camera string. If the requested camera has not been opened before this 00047 * is done and the camera is started. If that fails for whatever reason an exception 00048 * is thrown. In that case the thread is not registered with the vision master. 00049 * If the camera is available the thread is registered with the vision master. From 00050 * then on it is woken up whenever new image data is available and it will wait for 00051 * the thread to finished computation on that very image. It is a critical error 00052 * that can not be recovered if the thread fails for whatever reason. If there is 00053 * a critical error condition in the vision thread it must not stop execution 00054 * but just the computation. 00055 * @param camera_string camera that can be used by CameraFactory to open a 00056 * camera. 00057 * @param thread thread to register for this camera 00058 * @param cspace the colorspace in which the images should be provided for the 00059 * camera. Note that using images in different formats at the same time can cause 00060 * a severe performance penalty. The default is to produce YUV422_PLANAR images, 00061 * which is used in the FireVision framework as main image format. 00062 * @return a pointer to the requested camera. Note that this may not be 00063 * of the C++ type that you may expect for the requested camera, but it may 00064 * have layers of indirection. For example when opening a USB camera you could 00065 * get a shared memory camera to share the camera (image) with multiple threads. 00066 * Note that using CS_UNKNOWN shall have the similar result as using 00067 * register_for_raw_camera(). 00068 * 00069 * @fn Camera * VisionMaster::register_for_raw_camera(const char *camera_string, Thread *thread) 00070 * Register thread for camera. 00071 * This will register a relation between the given thread and the camera identified 00072 * by the camera string similar to register_for_camera(). However, unlike 00073 * register_for_camera() this method will provide access to the raw camera 00074 * implementation, without possibly proxies. Once you gathered the camera, you 00075 * can dynamically cast it to the expected camera type (or use the template method 00076 * instead. Raw access to a camera is only granted for a single thread. 00077 * Note that you may not call capture() or dispose() on the camera, this will 00078 * still be done by the vision master, as the camera may be used by other 00079 * threads that registered for the camera with register_for_camera(). 00080 * @param camera_string camera that can be used by CameraFactory to open a 00081 * camera. 00082 * @param thread thread to register for this camera 00083 * @return raw camera instance, which can by dynamically casted to the expected type. 00084 * 00085 * @fn void VisionMaster::unregister_thread(Thread *thread) = 0 00086 * Unregister a thread. 00087 * The thread is unregistered and it is removed from the internal structures. The 00088 * thread is no longer called for new image material that can be processed. 00089 * 00090 * If the unregistered thread was the last thread accessing the camera, it shall 00091 * be held open for a specified time, such that if the thread is just being 00092 * restarted the camera does not have to be re-opened. The time to wait is 00093 * defined by the implementation. 00094 * @param thread thread to unregister 00095 * 00096 * @fn CameraControl * VisionMaster::acquire_camctrl(const char *cam_string) 00097 * Retrieve a CameraControl for the specified camera string. 00098 * This control (if available) can be used to control certain aspects of the Camera. 00099 * The \p cam_string argument either is the string that has been used to register 00100 * for a particular camera, or it is a string denoting a camera control by itself. 00101 * In the former case the vision master will look if the camera has been registered, 00102 * and then checks if the camera provides a camera control. If so the control is 00103 * returned. Note that it might implement multiple different camera controls. If 00104 * you want a specific camera control use one of the template methods to get a 00105 * correctly typed and verified control. If no camera that matches the \p cam_string 00106 * is found, the vision master will try to instantiate a new camera control using 00107 * the \p cam_string as argument to the CameraControlFactory. 00108 * @param cam_string Camera argument string, see method description for details 00109 * @return a pointer to the requested CameraControl. 00110 * @throws Exception no camera was found matching the \p cam_string and the factory 00111 * could not instantiate a camera control with the given string. 00112 * 00113 * @fn CameraControl * VisionMaster::acquire_camctrl(const char *cam_string, const std::type_info &typeinf) 00114 * Retrieve a CameraControl for the specified camera string and type info. 00115 * This utility method is used by the template methods to instantiate the cameras 00116 * with a specified intended type. 00117 * @param cam_string Camera argument string, see method description for details 00118 * @param typeinf type info for intended camera control type 00119 * @return a pointer to the requested CameraControl. 00120 * @throws Exception no camera was found matching the \p cam_string and the factory 00121 * could not instantiate a camera control with the given string. 00122 * 00123 * @fn void VisionMaster::release_camctrl(CameraControl *cc) 00124 * Release a camera control. 00125 * This has to be called when you are done with the camera control. This will 00126 * release the control and it is no longer valid. The vision master might collect 00127 * the memory that has been used for the control. 00128 * @param cc camera control instance to release 00129 */ 00130 00131 /** Virtual empty destructor. */ 00132 VisionMaster::~VisionMaster() 00133 { 00134 } 00135 00136 } // end namespace firevision