Fawkes API  Fawkes Development Version
camera.cpp
00001 
00002 /***************************************************************************
00003  *  camera.cpp - Abstract class defining a camera
00004  *
00005  *  Created: Wed Jan 17 14:48:17 2007
00006  *  Copyright  2005-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 <fvcams/camera.h>
00025 
00026 #include <core/exception.h>
00027 #include <core/exceptions/software.h>
00028 
00029 namespace firevision {
00030 #if 0 /* just to make Emacs auto-indent happy */
00031 }
00032 #endif
00033 
00034 /** @class Camera <fvcams/camera.h>
00035  * Camera interface for image aquiring devices in FireVision.
00036  *
00037  * In general cameras shall initiate a continuous flow of images and shall
00038  * be optimized for real-time image processing (25 Hz).
00039  *
00040  * @fn void Camera::open() = 0
00041  * Open the camera.
00042  * The camera is opened, but image transfer not yet started. This can be used
00043  * to detect general problems with the camera while delaying the real transfer
00044  * startup until it is needed.
00045  *
00046  * @fn void Camera::start()
00047  * Start image transfer from the camera.
00048  * For many cameras opening the camera and starting transmission of images are
00049  * two tasks. This method will simply initiate the transfer after the camera
00050  * as been opened. And exception shall be thrown if the camera has not been
00051  * opened.
00052  *
00053  * @fn void Camera::stop()
00054  * Stop image transfer from the camera.
00055  * This will stop the image transfer initiated with start(). This can be used
00056  * to start and stop the image transfer at will without opening and closing
00057  * operations inbetween.
00058  *
00059  * @fn void Camera::close()
00060  * Close camera.
00061  * This closes the camera device. The camera must have been stopped before
00062  * calling close().
00063  *
00064  * @fn void Camera::capture()
00065  * Capture an image.
00066  * Although cameras shall operate with a continuous image flow where possible
00067  * sometimes capturing an image means copying a buffer or advancing a buffer
00068  * list pointer. This shall be done in this method. For a camera-using
00069  * application it is mandatory to call capture() just before accessing the
00070  * image buffer.
00071  *
00072  * @fn void Camera::flush()
00073  * Flush image queue.
00074  * Some cameras may have an image buffer queue. With this it can happen that
00075  * if the processing of an image took longer than desired it is needed to flush
00076  * this buffer queue.
00077  *
00078  * @fn bool Camera::ready()
00079  * Camera is ready for taking pictures.
00080  * The camera has been opened and started correctly and may now provide images.
00081  * @return true, if the camera is ready, false otherwise
00082  *
00083  * @fn void Camera::print_info()
00084  * Print out camera information.
00085  * Shall print out camera information and current setup information on stdout.
00086  *
00087  * @fn unsigned char * Camera::buffer()
00088  * Get access to current image buffer.
00089  * This will return a pointer to the current buffer. The buffer contains an
00090  * image of the given colorspace, width and height.
00091  * @return pointer to image buffer
00092  *
00093  * @fn void Camera::dispose_buffer()
00094  * Dispose current buffer.
00095  * Some cameras need disposal of the current buffer (for example to free space
00096  * in a queue to retrieve the next image). This is done with this method. It
00097  * has to be called after all work has been done on the image as desired. After
00098  * dispose_buffer() has been called no further access may happen to the image
00099  * buffer or undesired behavior may happen.
00100  *
00101  * @fn unsigned int Camera::buffer_size()
00102  * Size of buffer.
00103  * Gets the size in bytes of the buffer returned by buffer().
00104  * @return size of buffer in bytes
00105  *
00106  * @fn colorspace_t Camera::colorspace()
00107  * Colorspace of returned image.
00108  * @return colorspace of image returned by buffer()
00109  *
00110  * @fn unsigned int Camera::pixel_width()
00111  * Width of image in pixels.
00112  * @return width of image in pixels
00113  *
00114  * @fn unsigned int Camera::pixel_height()
00115  * Height of image in pixels.
00116  * @return height of image in pixels
00117  *
00118  * @fn void Camera::set_image_number(unsigned int n)
00119  * Set image number to retrieve.
00120  * If a camera is able to retrieve several images this method can be used to
00121  * select the image to be retrieved with the next call to capture().
00122  * @param n image number to set
00123  *
00124  */
00125 
00126 /** Virtual empty destructor. */
00127 Camera::~Camera()
00128 {
00129 }
00130 
00131 /** Get the Time of the last successfully captured image.
00132  * Returns a Time representing the time when the last image was captured
00133  * successfully. Note that calling this function is only valid after capture()
00134  * and before dispose_buffer() has been called -- it is only valid when an image
00135  * is currently available.
00136  * @return Time of the currently processed image. The pointer shall be valid at
00137  * least until the next call to dispose_buffer().
00138  * @throw NotImplementedException thrown if Camera does not support time stamping
00139  */
00140 fawkes::Time *
00141 Camera::capture_time()
00142 {
00143   throw fawkes::NotImplementedException("Timestamping not supported by this camera");
00144 }
00145 
00146 } // end namespace firevision