LoRenderBuffer.H

Go to the documentation of this file.
00001 /**
00002    \file  Robots/LoBot/ui/LoRenderBuffer.H
00003    \brief An OpenGL framebuffer object.
00004 
00005    This file defines a class that uses parts of OpenGL's framebuffer
00006    object API to implement an off-screen rendering buffer for the
00007    Robolocust UI. All rendering takes place in this off-screen buffer and
00008    is then transferred to the screen. This architecture allows us to
00009    easily implement screen captures for later encoding as an MPEG so that
00010    users can obtain a record of a particular run/experiment of the robot.
00011 */
00012 
00013 // //////////////////////////////////////////////////////////////////// //
00014 // The iLab Neuromorphic Vision C++ Toolkit - Copyright (C) 2000-2005   //
00015 // by the University of Southern California (USC) and the iLab at USC.  //
00016 // See http://iLab.usc.edu for information about this project.          //
00017 // //////////////////////////////////////////////////////////////////// //
00018 // Major portions of the iLab Neuromorphic Vision Toolkit are protected //
00019 // under the U.S. patent ``Computation of Intrinsic Perceptual Saliency //
00020 // in Visual Environments, and Applications'' by Christof Koch and      //
00021 // Laurent Itti, California Institute of Technology, 2001 (patent       //
00022 // pending; application number 09/912,225 filed July 23, 2001; see      //
00023 // http://pair.uspto.gov/cgi-bin/final/home.pl for current status).     //
00024 // //////////////////////////////////////////////////////////////////// //
00025 // This file is part of the iLab Neuromorphic Vision C++ Toolkit.       //
00026 //                                                                      //
00027 // The iLab Neuromorphic Vision C++ Toolkit is free software; you can   //
00028 // redistribute it and/or modify it under the terms of the GNU General  //
00029 // Public License as published by the Free Software Foundation; either  //
00030 // version 2 of the License, or (at your option) any later version.     //
00031 //                                                                      //
00032 // The iLab Neuromorphic Vision C++ Toolkit is distributed in the hope  //
00033 // that it will be useful, but WITHOUT ANY WARRANTY; without even the   //
00034 // implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR      //
00035 // PURPOSE.  See the GNU General Public License for more details.       //
00036 //                                                                      //
00037 // You should have received a copy of the GNU General Public License    //
00038 // along with the iLab Neuromorphic Vision C++ Toolkit; if not, write   //
00039 // to the Free Software Foundation, Inc., 59 Temple Place, Suite 330,   //
00040 // Boston, MA 02111-1307 USA.                                           //
00041 // //////////////////////////////////////////////////////////////////// //
00042 //
00043 // Primary maintainer for this file: mviswana usc edu
00044 // $HeadURL: svn://isvn.usc.edu/software/invt/trunk/saliency/src/Robots/LoBot/ui/LoRenderBuffer.H $
00045 // $Id: LoRenderBuffer.H 13838 2010-08-27 20:42:20Z mviswana $
00046 //
00047 
00048 #ifndef LOBOT_RENDER_BUFFER_DOT_H
00049 #define LOBOT_RENDER_BUFFER_DOT_H
00050 
00051 //----------------------------- NAMESPACE -------------------------------
00052 
00053 namespace lobot {
00054 
00055 //------------------------- CLASS DEFINITION ----------------------------
00056 
00057 /**
00058    \class lobot::RenderBuffer
00059    \brief An encapsulation of an OpenGL framebuffer object.
00060 
00061    This class implements an off-screen rendering buffer using OpenGL's
00062    FBO API. Instead of rendering directly to the OpenGL (on-screen) back
00063    buffer, the Robolocust main window first renders to this off-screen
00064    buffer and then copies the contents of the off-screen render buffer to
00065    the on-screen back buffer.
00066 
00067    If available, this class will use the OpenGL blitting API to copy the
00068    off-screen buffer to the on-screen buffer so that this operation takes
00069    place within the GL driver via DMA. However, if blitting is not
00070    supported, then it will fall back to reading the pixels from the
00071    off-screen buffer into main memory and then drawing them to the back
00072    buffer.
00073 
00074    Furthermore, this class takes care of the details of dealing with the
00075    OpenGL FBO API regardless of whether it is part of the GL core is
00076    available as an extension.
00077 
00078    This somewhat indirect and convoluted architecture allows us to easily
00079    implement screen captures.
00080 */
00081 class RenderBuffer {
00082    /// When rendering to an off-screen buffer, we need to know the size
00083    /// of the drawing area (just as we would for an on-screen buffer).
00084    const int m_width, m_height ;
00085 
00086    /// We cache the contents of the off-screen buffer so as to avoid
00087    /// copying more than absolutely required.
00088    //@{
00089    const int m_size ;
00090    unsigned char* m_cache ;
00091    //@}
00092 
00093    /// A flag to indicate whether the internal cache of the off-screen
00094    /// buffer's contents maintained by this object is in a state that can
00095    /// be retrieved by clients or not.
00096    mutable bool m_dirty ;
00097 
00098    /// The off-screen buffer is identified by the following IDs supplied
00099    /// by OpenGL.
00100    ///
00101    /// DEVNOTE: fbo = framebuffer object
00102    ///          rbo = renderbuffer object
00103    unsigned int m_fbo, m_rbo ;
00104 
00105 public:
00106    /// Initialization: when clients create an off-screen render buffer,
00107    /// they should specify its dimensions. Usually, these dimensions
00108    /// would equal those of the UI window.
00109    RenderBuffer(int width, int height) ;
00110 
00111    /// Setup off-screen rendering: before performing regular rendering,
00112    /// clients should call this method so that rendering can be
00113    /// redirected to the off-screen buffer.
00114    void setup() ;
00115 
00116    /// Retrieve the off-screen buffer's pixels: clients can use this
00117    /// method after rendering is done to get the results of the rendering
00118    /// process that ended up in the off-screen buffer.
00119    ///
00120    /// This function returns a pointer to the internal pixel data buffer.
00121    /// Clients should not store this pointer for later use, delete it, or
00122    /// write to the buffer it points to. Instead, they should only copy
00123    /// the contents of the data buffer returned by this function.
00124    ///
00125    /// The size of the buffer will be W*H*4, where W and H are the width
00126    /// and height respectively of the off-screen buffer. These two
00127    /// parameters would have been specified by the client during
00128    /// instantiation of the lobot::RenderBuffer object.
00129    ///
00130    /// The off-screen buffer's pixels are stored in the GL_BGRA format.
00131    /// The pixel data type is GL_UNSIGNED_BYTE.
00132    ///
00133    /// NOTE: If the OpenGL driver is missing support for framebuffer
00134    /// objects, the pixel data returned by this function could be
00135    /// corrupt, i.e., contain random garbage. This would usually occur
00136    /// when the Robolocust window is wholly or partially obscured by
00137    /// another window.
00138    const unsigned char* pixels() const ;
00139 
00140    /// Helper function to return the size (in bytes) of the off-screen
00141    /// buffer's pixel data array.
00142    int size() const {return m_size ;}
00143 
00144    /// Helper functions to return the dimensions of the off-screen
00145    /// buffer.
00146    ///
00147    /// NOTE: In general, a client should not really need to use these
00148    /// functions because they ought to already know this information and
00149    /// would have passed the width and height to the lobot::RenderBuffer
00150    /// constructor.
00151    //@{
00152    int width()  const {return m_width  ;}
00153    int height() const {return m_height ;}
00154    //@}
00155 
00156    /// Copy contents of off-screen buffer to on-screen buffer.
00157    void to_screen() ;
00158 
00159 private:
00160    /// Helper function to release OpenGL resources.
00161    void clean_up() ;
00162 
00163 public:
00164    /// Clean-up.
00165    ~RenderBuffer() ;
00166 } ;
00167 
00168 //-----------------------------------------------------------------------
00169 
00170 } // end of namespace encapsulating this file's definitions
00171 
00172 #endif
00173 
00174 /* So things look consistent in everyone's emacs... */
00175 /* Local Variables: */
00176 /* indent-tabs-mode: nil */
00177 /* End: */
Generated on Sun May 8 08:41:31 2011 for iLab Neuromorphic Vision Toolkit by  doxygen 1.6.3