vision_master.cpp

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

Generated on Tue Feb 22 13:31:16 2011 for Fawkes API by  doxygen 1.4.7