Fawkes API Fawkes Development Version
vision_master.cpp
1
2/***************************************************************************
3 * vision_master.cpp - FireVision Vision Master
4 *
5 * Created: Wed May 30 10:52:08 2007
6 * Copyright 2006-2009 Tim Niemueller [www.niemueller.de]
7 *
8 ****************************************************************************/
9
10/* This program is free software; you can redistribute it and/or modify
11 * it under the terms of the GNU General Public License as published by
12 * the Free Software Foundation; either version 2 of the License, or
13 * (at your option) any later version. A runtime exception applies to
14 * this software (see LICENSE.GPL_WRE file mentioned below for details).
15 *
16 * This program is distributed in the hope that it will be useful,
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 * GNU Library General Public License for more details.
20 *
21 * Read the full text in the LICENSE.GPL_WRE file in the doc directory.
22 */
23
24#include <fvutils/base/vision_master.h>
25
26using namespace fawkes;
27
28namespace firevision {
29
30/** @class VisionMaster <fvutils/base/vision_master.h>
31 * Vision Master.
32 * The vision master shall be the entry point for vision plugins. It shall
33 * allow for requesting cameras that are opened in a central place such that
34 * the very same camera can be used in multiple plugins.
35 *
36 * It shall also be responsible for the central timing of all vision threads.
37 *
38 * @author Tim Niemueller
39 *
40 * @fn Camera * VisionMaster::register_for_camera(const char *camera_string, Thread *thread, colorspace_t cspace=YUV422_PLANAR) = 0
41 * Register thread for camera.
42 * This will register a relation between the given thread and the camera identified
43 * by the camera string. If the requested camera has not been opened before this
44 * is done and the camera is started. If that fails for whatever reason an exception
45 * is thrown. In that case the thread is not registered with the vision master.
46 * If the camera is available the thread is registered with the vision master. From
47 * then on it is woken up whenever new image data is available and it will wait for
48 * the thread to finished computation on that very image. It is a critical error
49 * that can not be recovered if the thread fails for whatever reason. If there is
50 * a critical error condition in the vision thread it must not stop execution
51 * but just the computation.
52 * @param camera_string camera that can be used by CameraFactory to open a
53 * camera.
54 * @param thread thread to register for this camera
55 * @param cspace the colorspace in which the images should be provided for the
56 * camera. Note that using images in different formats at the same time can cause
57 * a severe performance penalty. The default is to produce YUV422_PLANAR images,
58 * which is used in the FireVision framework as main image format.
59 * @return a pointer to the requested camera. Note that this may not be
60 * of the C++ type that you may expect for the requested camera, but it may
61 * have layers of indirection. For example when opening a USB camera you could
62 * get a shared memory camera to share the camera (image) with multiple threads.
63 * Note that using CS_UNKNOWN shall have the similar result as using
64 * register_for_raw_camera().
65 *
66 * @fn Camera * VisionMaster::register_for_raw_camera(const char *camera_string, Thread *thread)
67 * Register thread for camera.
68 * This will register a relation between the given thread and the camera identified
69 * by the camera string similar to register_for_camera(). However, unlike
70 * register_for_camera() this method will provide access to the raw camera
71 * implementation, without possibly proxies. Once you gathered the camera, you
72 * can dynamically cast it to the expected camera type (or use the template method
73 * instead. Raw access to a camera is only granted for a single thread.
74 * Note that you may not call capture() or dispose() on the camera, this will
75 * still be done by the vision master, as the camera may be used by other
76 * threads that registered for the camera with register_for_camera().
77 * @param camera_string camera that can be used by CameraFactory to open a
78 * camera.
79 * @param thread thread to register for this camera
80 * @return raw camera instance, which can by dynamically casted to the expected type.
81 *
82 * @fn void VisionMaster::unregister_thread(Thread *thread) = 0
83 * Unregister a thread.
84 * The thread is unregistered and it is removed from the internal structures. The
85 * thread is no longer called for new image material that can be processed.
86 *
87 * If the unregistered thread was the last thread accessing the camera, it shall
88 * be held open for a specified time, such that if the thread is just being
89 * restarted the camera does not have to be re-opened. The time to wait is
90 * defined by the implementation.
91 * @param thread thread to unregister
92 *
93 * @fn CameraControl * VisionMaster::acquire_camctrl(const char *cam_string)
94 * Retrieve a CameraControl for the specified camera string.
95 * This control (if available) can be used to control certain aspects of the Camera.
96 * The \p cam_string argument either is the string that has been used to register
97 * for a particular camera, or it is a string denoting a camera control by itself.
98 * In the former case the vision master will look if the camera has been registered,
99 * and then checks if the camera provides a camera control. If so the control is
100 * returned. Note that it might implement multiple different camera controls. If
101 * you want a specific camera control use one of the template methods to get a
102 * correctly typed and verified control. If no camera that matches the \p cam_string
103 * is found, the vision master will try to instantiate a new camera control using
104 * the \p cam_string as argument to the CameraControlFactory.
105 * @param cam_string Camera argument string, see method description for details
106 * @return a pointer to the requested CameraControl.
107 * @throws Exception no camera was found matching the \p cam_string and the factory
108 * could not instantiate a camera control with the given string.
109 *
110 * @fn CameraControl * VisionMaster::acquire_camctrl(const char *cam_string, const std::type_info &typeinf)
111 * Retrieve a CameraControl for the specified camera string and type info.
112 * This utility method is used by the template methods to instantiate the cameras
113 * with a specified intended type.
114 * @param cam_string Camera argument string, see method description for details
115 * @param typeinf type info for intended camera control type
116 * @return a pointer to the requested CameraControl.
117 * @throws Exception no camera was found matching the \p cam_string and the factory
118 * could not instantiate a camera control with the given string.
119 *
120 * @fn void VisionMaster::release_camctrl(CameraControl *cc)
121 * Release a camera control.
122 * This has to be called when you are done with the camera control. This will
123 * release the control and it is no longer valid. The vision master might collect
124 * the memory that has been used for the control.
125 * @param cc camera control instance to release
126 */
127
128/** Virtual empty destructor. */
130{
131}
132
133} // end namespace firevision
virtual ~VisionMaster()
Virtual empty destructor.
Fawkes library namespace.