Renderable.h

Go to the documentation of this file.

//------------------------------------------------------------------------
//C++ 
//                   ________    ____   ___ 
//                  |        \  /    | /  /
//                  +---+     \/     |/  /
//                  +--+|  |\    /|     < 
//                  |  ||  | \  / |  |\  \ 
//                  |      |  \/  |  | \  \ 
//                   \_____|      |__|  \__\
//                       Copyright  2002 
//                      Joe Michael Kniss
//               "All Your Base are Belong to Us"
//-------------------------------------------------------------------------

#ifndef __RENDERABLE_002_DOT_H
#define __RENDERABLE_002_DOT_H

#include <list>
#include <vector>
#include <eventGutz.h>
#include <smartptr.h>
#include <graphicsGutz.h>

////////////////////////////////////////////////////////////////////////////
/// a unique identifier for this species of object, needed 
///  mostly for GL style picking, since we need to know what
///  kind of object was picked, so we can forward mouse/key 
///  events to it
const unsigned int RENDERABLE_NAME = 80081355;
////////////////////////////////////////////////////////////////////////////

////////////////////////////////////////////////////////////////////////////
/// Renderable.
///
///  This is the base class, and a new effect/renderer should sub-class from it.
///
///  Please note: this object contains a gutz::Manip smart pointer, when it
///  is constructed (by default) it creates a new manipulator (_manip).  USE IT! 
///  It is generally assumed that you might want to interact with your object
///  this is why we create one for you.  If you just want to interact with 
///  your object with the least amout of effort, call setManipEventsDefault()
///  and follow the notes on GL picking (below).  If you don't override the
///  mouse() and move() functions then events are automatically forwarded to your
///  Manip.  Apply your manip (using OpenGL) like this:
/// \code
///    glPushMatrix();
///    {
///       glMultMatrixf(_manip->getWorldTransform().m);
///       /* ... draw stuff ...*/
///    }
///    glPopMatrix();
/// \endcode 
///  I usually add the "{}" around a glPush/Pop to keep the code neat and the state 
///  clear.  Don't forget, if you want interaction using openGL, you have to push 
///  2 specific unsigned int "names" on the gl-name-stack.
///
/// NOTE on GL picking (gl interaction): \n
///   There are 2 strict rules for GL style picking of renderables.  \n
///   1) push the #RENDERABLE_NAME on the gl name stack first \n
///   2) push your (Renderable*) pointer onto the stack as an unsigned int \n
///   Like this:
/// \code
///   glPushName(RENDERABLE_NAME);
///   glPushName((unsigned int)(Renderable *)this);
/// \endcode
///   Item 2 is actually a little tricky.  You should ALWAYS cast to 
///   Renderable* before casting to unsigned int.
///   This is VERY important if the type you are setting up is polymorphic;
///   the "this" pointer may be incorrect when we cast to "Renderable*" in
///   the UI.  If you cast to "Renderable*" first, any ambiguity is resolved
///   and you get the right position in the class for the cast-back in the UI
///
///   There is a third rule, but it is obvious:\n
///   3) Pop all names that you pushed onto the stack back off when you are
///   done rendering. \n
///   Like this:
/// \code 
///   glPopName();
///   glPopName();  /// plus one pop for each additional name you added
/// \endcode
///   After you are done with items 1 & 2, you can push as much onto the 
///   stack as you like (within reason), just be sure you pop it all back off
///   (item 3). \n
///
///  Here is what your draw function might look like if you are using OpenGL,
///   you want interaction, and you are using the _manip for the transformation:
/// \code
///  void draw(const gutz::RenderEvent &re)
///  {
///    glPushName(RENDERABLE_NAME); 
///    glPushName((unsigned int)(Renderable *)this);
///    glPushMatrix();
///    {
///       glMultMatrixf(_manip->getWorldTransform().m);
///       /* ... draw your geometry ...*/
///    }
///    glPopMatrix();
///    glPopName();  ///DONT FORGET THESE!!!
///    glPopName();
///  }
/// \endcode
///
/// Why is this object "Counted", see gutz::Counted and gutz::SmartPtr for 
///   details on what this means. \n
/// This object really needs to be counted, since it is usualy the primary
///   interface to renderable objects for any framework that uses them.
///   This may be problematic in situations with polymorphisim in the
///   hierarchy's derivation.  Oh well, need to deal with this somehow, I think
///   that this kind of baddness will be rare if you can sepparate the 
///   appearance from the behavior/data associated with a renderable object. \n
/// NOTE: Please be carefull, you need to make very sure that if a 
///   renderable pushes its name on the glName stack for GL style picking,
///   it better have a smartptr to it somewhere, or the object that created
///   it needs to do the reference counting, since the user interface is 
///   probably going to keep a smartptr to it too.  This can lead to trouble
///   if the user interface's smart pointer calls delete on the object because
///   it has no references, or the objects owner deletes it.  This is the 
///   classic smart pointer problem; bad things occur when we create objects
///   on the stack, or we create objects that have automatic deletion, like
///   non-smart pointer member variables. See gutz::SmartPtr & gutz::Counted
///
/// See also: gutz::RenderEvent, gutz::MouseEvent, gutz::MouseMoveEvent
/////////////////////////////////////////////////////////////////////////////

class Renderable : public gutz::Counted {
public:
   ~Renderable(){};

   ///////////////////////////////////////////////////////////////////////////
   ///@name DRAW!
   ///  This is the draw function.  Calling it renders the object. Pure virtual,
   ///    you must override this function in a subclass.  
   ///@{
   virtual void draw(const gutz::RenderEvent &rs) = 0;
   ///@}
   ///////////////////////////////////////////////////////////////////////////
   
   ///////////////////////////////////////////////////////////////////////////
   ///@name Draw on/off.
   ///@{
   bool isOn() const     { return _on; }
   void setOn(bool yes)  { _on = yes;  }
   ///@}
   ///////////////////////////////////////////////////////////////////////////

   ///////////////////////////////////////////////////////////////////////////
   ///@name Delete. 
   ///  Does this object need to be removed from a render list?
   ///  This means that the object is finished and anyone with a smart pointer
   ///  to it needs to delete the smart pointer and stop using the renderable.
   ///@{
   bool   needsDelete() const { return _deleteMe; }
   void   setDelete(bool yes) { _deleteMe = yes; if(yes) setOn(false);  }
   ///@}
   ///////////////////////////////////////////////////////////////////////////

   ///////////////////////////////////////////////////////////////////////////
   ///@name   Interaction Functions
   ///  Return true if the event was for you. By default interaction is
   ///    forwarded to your protected manipulator (_manip).  To use it
   ///    just apply it in your draw function.  However, if you don't
   ///    add any events or call setManipEventsDefault(), you won't have
   ///    any interaction.  Override these functions in your base class
   ///    to implement custom behaviors.
   //@{
   virtual  bool key(unsigned char k, int x, int y)    { return false; }
   virtual  bool mouse(const gutz::MouseEvent &me)     { return _manip->mouse(me); }
   virtual  bool move(const gutz::MouseMoveEvent &mme) { return _manip->move(mme); }
   //@}
   ///////////////////////////////////////////////////////////////////////////

   ///////////////////////////////////////////////////////////////////////////
   ///@name Selected
   ///   Is this object currently selected?
   ///@{
   virtual void setSelected(bool yes)      {_selected = yes;}
   bool isSelected() const                 {return _selected;}
   ///@}
   ///////////////////////////////////////////////////////////////////////////

   ///////////////////////////////////////////////////////////////////////////
   ///@name Manipulator Interface
   ///@{
   gutz::Manip  *getManip() const { return _manip.getPtr(); }
   void          setManip(gutz::Manip *const m) { _manip = m; }
   /// you have to call this to enable default interaction, OR
   ///   customize the manipulators events yourself.
   void          setManipEventsDefault()
   {
      _manip->mapEvent(gutz::GUTZ_LEFT_MOUSE, new gutz::RotateManipEvent(1.0f));
      _manip->mapEvent(gutz::GUTZ_MIDDLE_MOUSE, new gutz::TransZManipEvent(1.0f));
      _manip->mapEvent(gutz::GUTZ_RIGHT_MOUSE, new gutz::TransXYManipEvent(1.0f));
#if 0
      _manip->mapEvent(gutz::OBJ_CENT_ROT,  gutz::GUTZ_LEFT_MOUSE,   1.0f);
      _manip->mapEvent(gutz::OBJ_STRANS_XY, gutz::GUTZ_RIGHT_MOUSE,  1.0f);
      _manip->mapEvent(gutz::OBJ_STRANS_XZ, gutz::GUTZ_MIDDLE_MOUSE, 1.0f);
#endif
   }
   ///@}
   ///////////////////////////////////////////////////////////////////////////

protected:
   ///////////////////////////////////////////////////////////////////////////
   /// since this is a base class/interface it cannot be publicly
   /// created.  Only derived classes can construct this guy.
   Renderable()
      : _on(true), 
        _selected(false), 
        _deleteMe(false), 
        _manip(new gutz::Manip()) 
   {}
   ///////////////////////////////////////////////////////////////////////////

   ///////////////////////////////////////////////////////////////////////////
   ///@name copy/assign
   ///@{
   Renderable(const Renderable &r)
      : _on(r._on),
        _selected(false),
        _manip(new gutz::Manip())
   {
      if(r._manip)
         *_manip = *(r._manip);
   }
   Renderable &operator=(const Renderable &r)
   {
      _on = r._on;
      if(r._manip)
         *_manip = *(r._manip);
      return *this;
   }
   ///@}
   ///////////////////////////////////////////////////////////////////////////

   bool     _on;       ///<is this renderable currently "render-able"?
   bool     _selected; ///<is this renderable selected?
   bool     _deleteMe; ///<does this object need to be deleted?

   /// You get a manipulator free, no charge
   gutz::ManipSP _manip;

private:
};

typedef gutz::SmartPtr<Renderable>          RenderableSP;

///////////////////////////////////////////////////////////////////////////
///@name Lists/Vectors of renderables typedefined, for ease of use
//@{

typedef std::list<RenderableSP>             RenderableList; 
typedef std::list<RenderableSP>::iterator   RenderableListIter;

typedef std::vector<RenderableSP>           RenderableVec; 
typedef std::vector<RenderableSP>::iterator RenderableVecIter;
//@}
///////////////////////////////////////////////////////////////////////////


#endif

---

Send questions, comments, and bug reports to: