ref_image.H

Go to the documentation of this file.

/*****************************************************************
 * ref_image.H
 *****************************************************************/
#ifndef REF_IMAGE_H_IS_INCLUDED
#define REF_IMAGE_H_IS_INCLUDED

#include "std/support.H"
#include "glew/glew.H"

#include "disp/ref_img_client.H" // RefImageClient::ref_img_t
#include "disp/colors.H"         // Color namespace and utility functions
#include "geom/image.H"          // Image
#include "geom/rgba.H"           // RGBA conversions
#include "geom/texturegl.H"      // tex mem ref img
#include "geom/winsys.H"         // bits per component
#include "mlib/point2i.H"
#include "mesh/patch.H"
#include "mesh/simplex_filter.H"
#include "mesh/base_ref_image.H"

#include "gtex/util.H"

/**********************************************************************
 * CoordSystem2d
 **********************************************************************/
class CoordSystem2d {
 protected:
   uint           _width;
   uint           _height;
   uint           _max;
   double         _half_width;
   double         _half_height;
   double         _half_min_dim;

   NDCvec         _ndc_offset;

 public:
   CoordSystem2d() :
      _width(0), _height(0), _max(0),
      _half_width(0), _half_height(0),
      _half_min_dim(0) {}

   virtual ~CoordSystem2d() {}
  
   // accessors
   uint  width()        const   { return _width; }
   uint height()        const   { return _height;}
   uint    max()        const   { return _max;}

   virtual bool resize(uint new_w, uint new_h) {
      _width        = new_w;
      _height       = new_h;
      _max          = _width * _height;
      _half_width   = _width/2.0;
      _half_height  = _height/2.0;
      _half_min_dim = min(_half_width,_half_height);
      return true;
   }

   CNDCvec& ndc_offset()                { return _ndc_offset; }
   void     set_ndc_offset(CNDCvec& v)  { _ndc_offset = v; }
  
   //**** RANGE FUNCTIONS ***
   bool uint_in_range(uint id) const { return (id<_max); }
   bool pix_in_range(Cpoint2i &pix) const {
      return (pix[0]>=0 && pix[1]>=0 &&
              (uint)pix[0]<_width && (uint)pix[1]<_height);
   }
  
   //**** CONVERSION FUNCTIONS ****

   // *** PIX <--> UINT ***
   uint pix_to_uint(Cpoint2i& pix) const {
      return clamp(pix[1],0,(int)_height-1)*_width +
         clamp(pix[0],0,(int)_width-1);
   }
   Point2i uint_to_pix(uint id) const {
      return Point2i(id % _width, id / _width);
   }

   // *** PIX <--> NDC ***
   NDCpt pix_to_ndc(Cpoint2i &pix) const {
      return NDCpt((pix[0]-_half_width)/_half_min_dim,
                   (pix[1]-_half_height)/_half_min_dim);
   }
   Point2i ndc_to_pix(CNDCpt &ndc) const {
      return Point2i(int(ndc[0]*_half_min_dim + _half_width),
                     int(ndc[1]*_half_min_dim + _half_height));
   }

   // *** NDC <--> UINT ***
   NDCpt uint_to_ndc(uint id) const {
      return NDCpt((id%_width - _half_width)/_half_min_dim,
                   (id/_width - _half_height)/_half_min_dim) + _ndc_offset;
   }
   uint ndc_to_uint(CNDCpt& ndc) const {
      const int x = (int) (ndc[0]*_half_min_dim + _half_width);
      const int y = (int) (ndc[1]*_half_min_dim + _half_height);
      return clamp(y,0,(int)_height-1)*_width + clamp(x,0,(int)_width-1);
   }
};

/**********************************************************************
 * Array2d:
 **********************************************************************/
template <class T>
class Array2d : public CoordSystem2d {
 public:
   //******** MANAGERS ********
   Array2d() : CoordSystem2d(), _values(0) {}
   Array2d(const Array2d<T>& arr) : _values(0) {
      resize(arr._width, arr._height);
      for (uint i=0; i<_max; i++)
         _values[i] = arr._values[i];
   }

   //******** SETTING UP ********
   virtual ~Array2d() { delete[] _values; }

   void clear(int clear_val=0) {
      memset(_values, clear_val, _max*sizeof(T));
   }

   virtual bool resize(uint new_w, uint new_h) {
      if (new_w == _width && new_h == _height)
         return false;
      CoordSystem2d::resize(new_w, new_h);
      allocate();
      return true;
   }

   //******** ACCESSORS ********
   T& val(uint id)              const   { return _values[id];}
   T& val(CNDCpt& ndc)    const   { return val(ndc_to_uint(ndc));  }
   T& val(Cpoint2i& pix)  const   { return val(pix_to_uint(pix));  }
   T& val(int x, int y)         const   { return val(Point2i(x,y)); } 

 protected: 
   T*   _values;        // 1D array representing 2D grid of values
  
   void allocate() {
      delete [] _values;
      _values = 0;
      if (_max>0) {
         _values = new T[_max];
         assert(_values);
      }
   }
};

/**********************************************************************
 * RefImage: 
 **********************************************************************/
#define CRefImage const RefImage
class RefImage : public Array2d<GLuint> {
 protected:
   VIEWptr      _view;                  // associated VIEW
   str_ptr      _rend_str;              // e.g. RSMOOTH_SHADE

   // XXX - might be trouble-matic:
   //   since pixel data is stored in a GLuint,
   //   the only format really supported is GL_RGBA
   //   (or other 4-byte formats):
   GLenum                       _format;        // e.g. GL_RGBA
   GLenum                       _type;          // e.g. GL_UNSIGNED_BYTE
   RefImageClient::ref_img_t    _ref_img_type;  // REF_IMG_COLOR

   static  HASH _hash;  // for looking up a RefImage given a VIEW

   virtual void draw_objects(CGELlist&) const;

 public:
   //******** MANAGERS ********
   // use this to get (create or lookup) a RefImage 
   // associated with a given VIEW:
   static RefImage* lookup(CVIEWptr& v = VIEW::peek());

   // public constructor for those rare instances when you just want
   // to get your own, not tied to a view
   RefImage(CVIEWptr& v,
            Cstr_ptr &rend_str = RSMOOTH_SHADE,
            GLenum format=GL_RGBA,
            GLenum type=GL_UNSIGNED_BYTE) :
      _view(v),
      _rend_str(rend_str),
      _format(format),
      _type(type),
      _ref_img_type(RefImageClient::REF_IMG_COLOR) {}

   CVIEWptr& view() const { return _view; }

   // return an Image with same dimensions
   // as this, but formatted for RGB:
   int copy_rgb(Image& img) const;

   // read from / write to the frame buffer:
   void read_FB() { glReadPixels(0,0,_width,_height,_format,_type,_values); }
   void draw_FB() const;

   // ensure image is up-to-date:
   virtual void update();

   // set every pixel to the given rgba color:
   void fill(uchar r, uchar g, uchar b, uchar a=255U) {
      fill(build_rgba(r,g,b,a));
   }
   void fill(uint fill_color);

   // set the given pixel to the given color:
   void set(Cpoint2i& pix, uint rgba_color) { val(pix) = rgba_color; }
   void set(Cpoint2i& pix, uchar r, uchar g, uchar b, uchar a=255U) {
      set(pix, build_rgba(r,g,b,a));
   }
   void set(int x, int y, uint rgba_color) {
      set(Cpoint2i(x,y), rgba_color);
   }
   void set(int x, int y, uchar r, uchar g, uchar b, uchar a=255U) {
      set(Cpoint2i(x,y), build_rgba(r, g, b, a));
   }

   // set the color at location x,y to the given color/alpha rgba value:
   void set(int x, int y, CCOLOR& c, double alpha = 1) {
      set(x, y, Color::color_to_rgba(c, alpha));
   }
   // blend the given color into the image using opacity alpha:
   void blend(int x, int y, CCOLOR& c, double alpha) {
      set(x, y, interp(color(x, y), c, alpha), 1);
   }

   //******** CONVENIENT COLOR ACCESSORS ********

   // return the color at image location x,y (ignoring alpha):
   COLOR color(int x, int y) const {
      return Color::rgba_to_color(val(x,y));
   }
   // return the color (ignoring alpha) at given NDC location:
   COLOR color(CNDCpt& ndc) const {
      return Color::rgba_to_color(val(ndc));
   }

   // return the given component as a uint in range [0,255]:
   uint red(uint id)            const      { return rgba_to_r(val(id));  }
   uint red(CNDCpt& ndc)        const      { return rgba_to_r(val(ndc)); }
   uint red(Cpoint2i& pix)      const      { return rgba_to_r(val(pix)); }
   uint red(int x, int y)       const      { return rgba_to_r(val(x,y)); }

   uint green(uint id)          const      { return rgba_to_g(val(id));  }
   uint green(CNDCpt& ndc)      const      { return rgba_to_g(val(ndc)); }
   uint green(Cpoint2i& pix)    const      { return rgba_to_g(val(pix)); }
   uint green(int x, int y)     const      { return rgba_to_g(val(x,y)); }

   uint blue(uint id)           const      { return rgba_to_b(val(id));  }
   uint blue(CNDCpt& ndc)       const      { return rgba_to_b(val(ndc)); }
   uint blue(Cpoint2i& pix)     const      { return rgba_to_b(val(pix)); }
   uint blue(int x, int y)      const      { return rgba_to_b(val(x,y)); }

   uint alpha(uint id)          const      { return rgba_to_a(val(id));  }
   uint alpha(CNDCpt& ndc)      const      { return rgba_to_a(val(ndc)); }
   uint alpha(Cpoint2i& pix)    const      { return rgba_to_a(val(pix)); }
   uint alpha(int x, int y)     const      { return rgba_to_a(val(x,y)); }

   // return the luminance (ignoring alpha) as a uint in range
   // [0,255], where 0 is black and 255 is white:
   uint grey(uint id)       const       { return rgba_to_grey(val(id));  }
   uint grey(CNDCpt& ndc)   const       { return rgba_to_grey(val(ndc)); }
   uint grey(Cpoint2i& pix) const       { return rgba_to_grey(val(pix)); }
   uint grey(int x, int y)  const       { return rgba_to_grey(val(x,y)); }

   // return the luminance (ignoring alpha) as a double in range
   // [0,1], where 0 is black and 1 is white:
   double grey_d(uint id)       const   { return rgba_to_grey_d(val(id));  }
   double grey_d(CNDCpt& ndc)   const   { return rgba_to_grey_d(val(ndc)); }
   double grey_d(Cpoint2i& pix) const   { return rgba_to_grey_d(val(pix)); }
   double grey_d(int x, int y)  const   { return rgba_to_grey_d(val(x,y)); }

   //******** FILE I/O ********
   int read_file (char* file);
   int write_file(char* file);

   //******** SEARCH FUNCTIONS ********

   // Return true if the given value v is found in an (n x n) square
   // region around the given center location, where n = 2*rad + 1.
   // E.g., if rad == 1 the search is within a 3 x 3 region:
   bool find_val_in_box(uint v, Cpoint2i& center, uint rad=1) const;
   bool find_val_in_box(uint v, CNDCpt&   center, uint rad=1) const {
      return find_val_in_box(v, ndc_to_pix(center), rad);
   }

   bool find_val_in_box(uint v, uint mask, Cpoint2i& center, uint rad=1, int nbr=256) const;
   bool find_val_in_box(uint v, uint mask, CNDCpt&   center, uint rad=1, int nbr=256) const {
      return find_val_in_box(v, mask, ndc_to_pix(center), rad, nbr);
   }
};

/**********************************************************************
 * RefImage2:
 **********************************************************************/
#define CRefImage2 const RefImage2
class RefImage2 : public RefImage {
 protected:

   static  HASH  _hash;

   RefImage2(CVIEWptr& v, Cstr_ptr &rend_str = RSMOOTH_SHADE,
             GLenum format=GL_RGBA,
             GLenum type=GL_UNSIGNED_BYTE) : 
      RefImage(v, rend_str, format, type) {
      _ref_img_type = RefImageClient::REF_IMG_COLOR_2;
   }

 public:

   static RefImage2* lookup(CVIEWptr& v = VIEW::peek());
};


/**********************************************************************
 * IDRefImage:
 *
 *      Also known as the "ID reference image."
 *
 *      Implements an "item buffer," where each pixel encodes an
 *      object ID. Specifically, "objects" in this case are mesh
 *      faces, edges, or vertices (usually just faces). Given a pixel
 *      location, the item buffer can be used to perform O(1) picking
 *      (not counting the cost of preparing the item buffer). This
 *      technique has been described in various papers; e.g.:
 *
 *        Rodney J. Recker, David W. George, Donald P. Greenberg.
 *        Acceleration Techniques for Progressive Refinement
 *        Radiosity, 1990 Symposium on Interactive 3D Graphics, 24
 *        (2), pp. 59-66 (March 1990). Edited by Rich Riesenfeld and
 *        Carlo Séquin. ISBN 0-89791-351-5.
 *
 *      This is also described in Lee Markosian's Ph.D. thesis,
 *      "Art-based Modeling and Rendering for Computer Graphics."
 *      Brown University, May 2000.
 **********************************************************************/
#define CIDRefImage const IDRefImage
class IDRefImage : public RefImage {
 public:
   //******** MANAGERS ********
   // no public constructor -- get your hands on one this way:
   static IDRefImage* lookup(CVIEWptr& v = VIEW::peek());

   // make sure the reference image is current:
   virtual void update(); 

   //******** RGBA <---> KEY CONVERSIONS ********
   // Convert Bsimplex key value to 32-bit RGBA that can be given to
   // OpenGL, then read back from the frame buffer to reliably yield
   // the original key value:

   // At compilation time you can define REF_IMG_32_BIT if you know
   // you will run your application on a machine (and with a visual)
   // that supports 32-bit RGBA. In that case these are no-ops and we
   // can save a function call if the following are inlined. To define
   // REF_IMG_32_BIT add a line saying REF_IMG_32_BIT=yes in your
   // Makefile.local. 

   static uint key_to_rgba(uint key)    { 
      return key; 
#ifdef REF_IMG_32_BIT
      return key; 
#else
      return key_to_rgba2(key);      
#endif
   }
   static uint rgba_to_key(uint rgba)   { 
      return rgba;
#ifdef REF_IMG_32_BIT
      return rgba;
#else      
      return rgba_to_key2(rgba);
#endif
   }
   static uint key_to_rgba2(uint key);      
   static uint rgba_to_key2(uint rgba);


   //******** LOOKUP -- CONVENIENCE METHODS ********
   Bsimplex* simplex(uint id)       const {
      return Bsimplex::lookup(rgba_to_key(val(id)));
   }
   Bsimplex* simplex(CNDCpt& ndc)   const { return simplex(ndc_to_uint(ndc)); }
   Bsimplex* simplex(Cpoint2i& pix) const { return simplex(pix_to_uint(pix)); }

   Bvert* vert(uint id) const {
      Bsimplex* sim = simplex(id);
      return is_vert(sim) ? (Bvert*)sim : 0;
   }
   Bedge* edge(uint id) const {
      Bsimplex* sim = simplex(id);
      return is_edge(sim) ? (Bedge*)sim : 0;
   }
   Bface* face(uint id) const {
      Bsimplex* sim = simplex(id);
      return is_face(sim) ? (Bface*)sim : 0;
   }
   Bvert* vert(CNDCpt& ndc)         const { return vert(ndc_to_uint(ndc)); }
   Bedge* edge(CNDCpt& ndc)         const { return edge(ndc_to_uint(ndc)); }
   Bface* face(CNDCpt& ndc)         const { return face(ndc_to_uint(ndc)); }
   Patch* patch(CNDCpt& ndc)        const { return patch(simplex(ndc)); }
   Patch* face_patch(CNDCpt& ndc)   const { return face_patch(simplex(ndc));}

   Bvert* vert(Cpoint2i& pix)       const { return vert(pix_to_uint(pix)); }
   Bedge* edge(Cpoint2i& pix)       const { return edge(pix_to_uint(pix)); }
   Bface* face(Cpoint2i& pix)       const { return face(pix_to_uint(pix)); }

   //******** INTERSECTION ********

   // Do exact intersection. If a vert or an edge is hit exactly,
   // return it as the simplex.
   Bsimplex* intersect_sim(CNDCpt& ndc, Wpt& obj_pt) const {
      Bsimplex* sim = simplex(ndc);
      if (sim && sim->get_face())
         return sim->get_face()->find_intersect_sim(ndc, obj_pt);
      else return 0;
   }

   // Find the simplex that is intersected exactly (if any), but
   // return a face (either the sim itself or one that contains it):
   Bface* intersect(CNDCpt& ndc, Wpt& obj_pt) const {
      Bsimplex* sim = intersect_sim(ndc, obj_pt);
      return sim ? sim->get_face() : 0;
   }

   // Exact intersection -- return a face:
   Bface* intersect(CNDCpt& ndc) const {
      static Wpt foo;
      return intersect(ndc, foo);
   }

   // Search in a region defined by a screen point and radius.
   // Return true if some pixel corresponds to a simplex that
   // matches the search criterion. Also return (in 'hit' parameter)
   // the closest matching pixel of the reference image. This is
   // similar to find_near_simplex (below), but can also be used
   // when the search criterion accepts a null simplex:
   bool search(
      CNDCpt&           center,         // search center
      double            screen_pix_rad, // search radius in screen pixels
      CSimplexFilter&   filt,           // filter giving search criterion
      Point2i&          hit             // return value - hit point
      );

   // Similar to search() above, but returns the matching simplex
   // itself, if any. Returns 0 on failure.
   Bsimplex* find_near_simplex(
      CNDCpt& center,
      double screen_pix_rad = 1.0,
      CSimplexFilter& filt = SimplexFilter());

   // return true if the given pixel location records the ID of an
   // edge, and the edge is in the given patch, and it's a silhouette
   // edge.
   bool is_patch_sil_edge(Cpoint2i& pix, const Patch* patch) const {
      static Bedge* temp = 0;
      if (pix_in_range(pix) && (temp = edge(pix)) 
          && (temp->patch() == patch) && (temp->is_sil())) 
         return true;
      else return false;
   }
   bool is_patch_sil_edge(CNDCpt& pix, const Patch* patch) const {
      return is_patch_sil_edge(ndc_to_pix(pix), patch);
   }

   Bedge* find_neighbor(CNDCpt& p, Bedge* current, int radius = 1) const;
   ARRAY<Bedge*> find_all_neighbors(CNDCpt& p, Patch* patch, int radius = 1) const;
   ARRAY<Bedge*> find_all_neighbors(Cpoint2i& p, Patch* patch, int radius = 1) const;
   bool is_simplex_near(CNDCpt& p, const Bsimplex* simp, int radius = 1) const;
   bool is_patch_sil_edge_near(CNDCpt& ndc, const Patch* patch, int radius = 1) const;

   bool is_face_visible( CNDCpt& ndc, const Bface* bf ) const {
      Bface* f = face(ndc);
      if (!f) return false;

      if (f==bf) return true;

      static Wpt obj_pt;
      
      Bsimplex* sim = f->find_intersect_sim(ndc, obj_pt);
      return sim ? sim->on_face(bf) : false;
   }
   bool near_pix(Cpoint2i& pix, Point2i& ret, Patch* patch) {
      Point2i p;
      if (pix_in_range(pix) && face_patch(simplex(pix)) == patch)
         ret = pix;
      else if (pix_in_range(p = pix + Vec2i(-1, 0)) &&
               face_patch(simplex(p)) == patch)
         ret = p;
      else if (pix_in_range(p = pix + Vec2i( 1, 0)) &&
               face_patch(simplex(p)) == patch)
         ret = p;
      else if (pix_in_range(p = pix + Vec2i(-1,-1)) &&
               face_patch(simplex(p)) == patch)
         ret = p;
      else if (pix_in_range(p = pix + Vec2i(-1, 0)) &&
               face_patch(simplex(p)) == patch)
         ret = p;
      else if (pix_in_range(p = pix + Vec2i(-1, 1)) &&
               face_patch(simplex(p)) == patch)
         ret = p;
      else if (pix_in_range(p = pix + Vec2i( 1,-1)) &&
               face_patch(simplex(p)) == patch)
         ret = p;
      else if (pix_in_range(p = pix + Vec2i( 1, 0)) &&
               face_patch(simplex(p)) == patch)
         ret = p;
      else if (pix_in_range(p = pix + Vec2i( 1, 1)) &&
               face_patch(simplex(p)) == patch)
         ret = p;
      else
         return 0;
      return 1;
   }

   // global access to the one true ID ref image
   static void set_instance(IDRefImage * id_ref) { _instance = id_ref;      }
   static void set_instance(CVIEWptr & v)        { set_instance(lookup(v)); }
   static IDRefImage* instance()                 { return _instance;        }

   static void setup_bits(CVIEWptr&);

   //*******************************************************
   // PROTECTED
   //*******************************************************
 protected:
   IDRefImage(CVIEWptr& v);

   virtual void draw_objects(CGELlist&) const;

   Patch* patch(Bsimplex* sim) const {
      return (is_face(sim) ? ((Bface*)sim)->patch() :
              is_edge(sim) ? ((Bedge*)sim)->patch() :
              0);
   }

   Patch* face_patch(Bsimplex* sim) const {
      return (is_face(sim) ? ((Bface*)sim)->patch() : 0); 
   }


   static  HASH  _hash; // associates an IDRefImage with a VIEW

   static uint _red_bits;
   static uint _green_bits;
   static uint _blue_bits;
   static uint _alpha_bits;
   static bool _nonstandard_bits;

   // global instance 
   static IDRefImage* _instance;
};

#define CVisRefImage const VisRefImage
class VisRefImageFactory;
/**********************************************************************
 * VisRefImage:
 *
 *   Visibility reference image
 **********************************************************************/
MAKE_PTR_SUBC(VisRefImage, FRAMEobs);
class VisRefImage : public    IDRefImage,
                    protected BMESHobs,
                    protected CAMobs,
                    protected DISPobs,
                    protected EXISTobs,
                    public    FRAMEobs,
                    protected XFORMobs,
                    public    BaseVisRefImage {
 public:
   //******** MANAGERS ********
   virtual ~VisRefImage() { unobserve(); }

   //******** UPDATING ********
   bool need_update();
   virtual void update() {
      if (need_update())
         IDRefImage::update();
      _dirty = 0;
   }
   void force_dirty() { _dirty = 1; }

   //******** STATICS ********
   static void init();
   static VisRefImage* lookup(CVIEWptr& view = VIEW::peek()) {
      if (!view)
         return 0;
      if (!BaseVisRefImage::_factory)
         init();
      return (VisRefImage*)BaseVisRefImage::lookup(view);
   }

   //******** PICKING METHODS ********
   static NDCpt get_cursor() {
      if (!DEVice_2d::last) {
         err_msg( "VisRefImage::get_cursor: error: Device_2d::last is nil");
         return NDCpt();
      }
      return NDCpt(DEVice_2d::last->cur());
   }

   static Bsimplex* get_simplex(CNDCpt& cur = get_cursor(),
                                double screen_rad=1,
                                CSimplexFilter& filt = SimplexFilter()) {
      VisRefImage* vis = lookup(VIEW::peek());
      if (vis) {
         vis->update();
         return vis->find_near_simplex(cur, screen_rad, filt);
      }
      return (Bsimplex*)0;
   }

   // Return the nearest Bface within the given screen region,
   // with a preference for front-facing Bfaces:
   static Bface* get_face(CNDCpt& cur = get_cursor(), double screen_rad=1);

   // Call get_face() on each screen point in sequence:
   static Bface_list get_faces(const PIXEL_list& pix, double screen_rad=1);

   // Convenience:
   static Bface* Intersect(CNDCpt& ndc, Wpt& obj_pt) {
      VisRefImage* vis = lookup(VIEW::peek());
      if (vis) {
         vis->update();
         return vis->intersect(ndc, obj_pt);
      }
      return (Bface*)0;
   }
   static Bface* Intersect(CNDCpt& ndc) {
      Wpt foo;
      return Intersect(ndc, foo);
   }

   // 1. Search the ID image to find the nearest Bface
   //    within a radius of the given NDC screen location.
   // 2. Convert the screen location to a barycentric
   //    coordinate on the Bface.
   // 3. Return the Bface and barycentric coordinate.
   //    (Returns NULL on failure.)
   static Bface* get_face_bc(
      Wvec& bc, CNDCpt& ndc = get_cursor(), double rad=1
      );
   
   // Same as above, but also convert the Bface / barycentric
   // coordinate to an equivalent pair at the given mesh subdivision
   // level.
   static Bface* get_sub_face(
      int level, Wvec& bc, CNDCpt& ndc = get_cursor(), double rad=1
      );

   // Same as above, but also convert the Bface / barycentric
   // coordinate to an equivalent pair at the mesh edit level.
   static Bface* get_edit_face(
      Wvec& bc, CNDCpt& ndc = get_cursor(), double rad=1
      );

   static Bface* get_edit_face(CNDCpt& ndc = get_cursor(), double rad=1) {
      Wvec bc; return get_edit_face(bc, ndc, rad);
   }

   static Bface* get_ctrl_face(CNDCpt& cur = get_cursor(),
                               double screen_rad=1) {
      return ::get_ctrl_face(get_face(cur, screen_rad));
   }

   static Bedge* get_edge(CNDCpt& cur = get_cursor(),
                          double screen_rad=1) {
      return (Bedge*)get_simplex(cur, screen_rad, BedgeFilter());
   }

   static Bvert* get_vert(CNDCpt& cur = get_cursor(),
                          double screen_rad=1) {
      return (Bvert*)get_simplex(cur, screen_rad, BvertFilter());
   }

   static Patch* get_patch(CNDCpt& cur = get_cursor(),
                           double screen_rad=1) {
      // see mesh/patch.H:
      return ::get_patch(get_simplex(cur, screen_rad));
   }

   static Patch* get_ctrl_patch(CNDCpt& cur = get_cursor(),
                                double screen_rad=1) {
      // see mesh/patch.H:
      return ::get_ctrl_patch(get_simplex(cur, screen_rad));
   }

   static BMESH* get_mesh(CNDCpt& cur = get_cursor(),
                          double screen_rad=1) {
      // see mesh/bsimplex.H:
      return ::get_mesh(get_simplex(cur, screen_rad));
   }

   static BMESH* get_ctrl_mesh(CNDCpt& cur = get_cursor(),
                               double screen_rad=1) {
      // see mesh/lmesh.H
      return ::get_ctrl_mesh(get_mesh(cur, screen_rad));
   }

   //******** BaseVisRefImage METHODS ********

   virtual void      vis_update() { update(); }
   virtual Bsimplex* vis_simplex(CNDCpt& ndc) const { return simplex(ndc); }
   virtual Bface*    vis_intersect(CNDCpt& ndc, Wpt& obj_pt) const {
      return intersect(ndc, obj_pt);
   }
   virtual void debug(CNDCpt& p) const;

   //******** OBSERVER METHODS ********

   void observe  ();
   void unobserve();

   // FRAMEobs:
   virtual int  tick();

   //*******************************************************
   // PROTECTED
   //*******************************************************
 protected:
   friend class VisRefImageFactory;

   //******** DATA ********
   int          _dirty;             // flag set when change occurred
   int          _countup;

   //******** MANAGERS ********
   VisRefImage(CVIEWptr& v);

   //******** UPDATING ********
   void reset() { _dirty = 1; _countup = 0; }

   //******** IDRefImage METHODS ********
   virtual void draw_objects(CGELlist&) const;

   virtual bool resize(uint new_w, uint new_h) {
      if (!IDRefImage::resize(new_w, new_h))
         return false;
      reset();
      return true;
   }

   //******** OBSERVER METHODS ********:
   // BMESHobs:
   virtual void notify_change(BMESH*, BMESH::change_t)  { reset(); }
   virtual void notify_xform (BMESH*, CWtransf&, CMOD&) { reset(); }

   // CAMobs:
   virtual void notify(CCAMdataptr&)    { reset(); }

   // DISPobs:
   virtual void notify(CGELptr&, int)   { reset(); }

   // EXISTobs:
   virtual void notify_exist(CGELptr&, int) { reset(); }

   // XFORMobs
   virtual void notify_xform(CGEOMptr&, STATE) { reset(); }
};

/**********************************************************************
 * TexMemRefImage: 
 *
 *   A "reference image" that saves the rendered image in a texture
 *   on the graphics card instead of in main memory.
 *
 **********************************************************************/
class TexMemRefImage {
 public:
   // ******** MANAGERS ********
   
   // Use this to get (create or lookup) a TexMemRefImage 
   // associated with a given VIEW:
   static TexMemRefImage* lookup(CVIEWptr& v = VIEW::peek());

   // public constructor for those rare instances when you just want
   // to get your own, not tied to a view
   TexMemRefImage(
      CVIEWptr& v,
      RefImageClient::ref_img_t img_type=RefImageClient::REF_IMG_TEX_MEM
      );

   virtual ~TexMemRefImage() {}
   
   //******** ACCESSORS ********
   CVIEWptr& view() const { return _view; }

   // ******** UTILITIES ********

   // resize to new dimensions:
   bool resize(const Point2i& dims);

   // Ensure that the texture stored in GPU texture-memory is updated.
   void update();

   // Read from the frame buffer into a texture in GPU memory.
   void read_FB();

   // Draws the stored texture to the screen (for debugging):
   void draw_FB();

   // Return pointer to the texture
   TEXTUREglptr get_texture() const { return _texture; }

   //******** STATICS ********

   // lookup the TexMemRefImage and return a pointer to its internal texture:
   static TEXTUREglptr lookup_texture(CVIEWptr& v = VIEW::peek()) {
      TexMemRefImage* tex_mem = lookup(v);
      return tex_mem ? tex_mem->get_texture() : 0;
   }
   
   // Lookup the texture unit used by the current TexMemRefImage:
   static GLenum lookup_tex_unit(CVIEWptr& v = VIEW::peek()) {
      TEXTUREglptr tex = lookup_texture(v);
      return tex ? tex->get_tex_unit() : TexUnit::REF_IMG + GL_TEXTURE0;
   }
      

   static void activate_tex_unit(CVIEWptr& v = VIEW::peek()) {
      TEXTUREglptr tex = lookup_texture(v);
      assert(tex);
      tex->apply_texture();     // GL_ENABLE
   }

 protected:
   VIEWptr                      _view;          // associated VIEW
   RefImageClient::ref_img_t    _ref_img_type;  // REF_IMG_TEX_REF
   TEXTUREglptr                 _texture;

   static  HASH _hash;  // for looking up a TexMemRefImage given a VIEW

   virtual void draw_objects(CGELlist&) const;
};

#endif // REF_IMAGE_H_IS_INCLUDED

// end of file ref_image.H

---