CachingDisplayData.h

Go to the documentation of this file.
00001 //# CachingDisplayData.h: base class for auto-caching DisplayData objects
00002 //# Copyright (C) 1999,2000,2001,2002,2003
00003 //# Associated Universities, Inc. Washington DC, USA.
00004 //#
00005 //# This library is free software; you can redistribute it and/or modify it
00006 //# under the terms of the GNU Library General Public License as published by
00007 //# the Free Software Foundation; either version 2 of the License, or (at your
00008 //# option) any later version.
00009 //#
00010 //# This library is distributed in the hope that it will be useful, but WITHOUT
00011 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
00012 //# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
00013 //# License for more details.
00014 //#
00015 //# You should have received a copy of the GNU Library General Public License
00016 //# along with this library; if not, write to the Free Software Foundation,
00017 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
00018 //#
00019 //# Correspondence concerning AIPS++ should be addressed as follows:
00020 //#        Internet email: aips2-request@nrao.edu.
00021 //#        Postal address: AIPS++ Project Office
00022 //#                        National Radio Astronomy Observatory
00023 //#                        520 Edgemont Road
00024 //#                        Charlottesville, VA 22903-2475 USA
00025 //#
00026 //# $Id$
00027 
00028 #ifndef TRIALDISPLAY_CACHINGDISPLAYDATA_H
00029 #define TRIALDISPLAY_CACHINGDISPLAYDATA_H
00030 
00031 #include <casa/aips.h>
00032 #include <casa/Containers/List.h>
00033 #include <display/DisplayDatas/DisplayData.h>
00034 
00035 namespace casa { //# NAMESPACE CASA - BEGIN
00036 
00037         class WorldCanvas;
00038         class WorldCanvasHolder;
00039         class AttributeBuffer;
00040         class CachingDisplayMethod;
00041 
00042 // <summary>
00043 // Base class for auto-caching DisplayData objects.
00044 // </summary>
00045 
00046 // <use visibility=export>
00047 
00048 // <reviewed reviewer="" data="" tests="" demos="">
00049 // </reviewed>
00050 
00051 // <prerequisite>
00052 // <li> <linkto class=DisplayData> DisplayData </linkto>
00053 // </prerequisite>
00054 
00055 // <etymology>
00056 // "CachingDisplayData" is an implementation of a <linkto
00057 // class=DisplayData> DisplayData </linkto> which provides automatic
00058 // caching of individual depictions of the data.
00059 // </etymology>
00060 
00061 // <synopsis>
00062 // This class adds to the interface defined in <linkto
00063 // class=DisplayData>DisplayData </linkto>.  It adds an "automagic"
00064 // caching system, which takes care of managing a set of individual
00065 // drawings made by the DisplayData, and using previously generated
00066 // drawing commands where applicable.  For example, the user might be
00067 // playing a movie of several frames in a DisplayData.  The automagic
00068 // caching will ensure that after one complete loop, while parameters
00069 // affecting the display of the data do not change, all subsequent
00070 // drawings will be made from a cache of drawing commands.
00071 // Furthermore, provided the cache is large enough, the user may alter
00072 // parameters, view some more frames, then return the parameters to
00073 // their original state, and there may still be older cached drawings
00074 // which can be used.
00075 //
00076 // The automagic caching also handles the case where a single
00077 // DisplayData is registered on more than one <linkto
00078 // class=WorldCanvasHolder>WorldCanvasHolder </linkto>.  Thus a
00079 // miniature view of the data could be shown in one window, and an
00080 // expanded view in another, with full automagic caching available on
00081 // both.
00082 //
00083 // This is a base class.  Derived classes must implement the
00084 // <src>newDisplayMethod</src> method, which is called to construct a
00085 // new <linkto class=CachingDisplayMethod> CachingDisplayMethod
00086 // </linkto> when the cache cannot satisfy the current drawing
00087 // request.  The method <src>optionsAsAttributes</src> should also be
00088 // implemented: when a new CachingDisplayMethod is constructed, the
00089 // return value of this method will be used to tag the parameters used
00090 // in the drawing itself.  Finally, the method
00091 // <src>cachingAttributes</src> can be over-ridden, and should
00092 // return any additional <linkto class=Attribute> Attributes </linkto>
00093 // which should be considered in searches of the cache.
00094 // </synopsis>
00095 
00096 // <motivation>
00097 // Most DisplayData classes will offer more than one view of the data.
00098 // Caching is therefore desirable to improve display speed for
00099 // re-display of individual views of the data.  It is nice to keep the
00100 // caching in one place, hence this class.
00101 // </motivation>
00102 
00103         class CachingDisplayData : public DisplayData {
00104 
00105         public:
00106 
00107                 // Constructor.
00108                 CachingDisplayData();
00109 
00110                 // Destructor.
00111                 virtual ~CachingDisplayData();
00112 
00113                 // Install the default options for this DisplayData.
00114                 virtual void setDefaultOptions();
00115 
00116                 // Apply options stored in <src>rec</src> to the DisplayData.  A
00117                 // return value of <src>True</src> means a refresh is needed.
00118                 // <src>recOut</src> contains any fields which were implicitly
00119                 // changed as a result of the call to this function.  The options
00120                 // handled by this class are:
00121                 // <li> <src>cachesize</src>: an integer specifying the maximum
00122                 // number of views which can be stored in the cache.  The default
00123                 // value can be specified by the <src>display.cachesize</src>
00124                 // variable in the user's <src>.aipsrc</src> file, and in lieu
00125                 // of that, will be 256.  If <src>cachesize</src> is lowered by
00126                 // a call to this method, the cache will be shrunk in size, with
00127                 // the oldest drawings being removed first. </li>
00128                 virtual Bool setOptions(Record &rec, Record &recOut);
00129 
00130                 // Retrieve the current and default options and parameter types.
00131                 virtual Record getOptions( bool scrub=false ) const;
00132 
00133                 // Refresh event handler which is called indirectly by the
00134                 // WorldCanvas, via the WorldCanvasHolder.  This function will take
00135                 // care of calling <src>newDisplayMethod</src> when necessary, and
00136                 // otherwise using an existing (previously cached) draw list.
00137                 virtual void refreshEH(const WCRefreshEvent &ev);
00138 
00139                 // <group>
00140                 virtual void notifyRegister(WorldCanvasHolder *wcHolder) ;
00141                 virtual void notifyUnregister(WorldCanvasHolder& wcHolder,
00142                                               Bool ignoreRefresh = False) ;
00143                 // </group>
00144 
00145                 // Purges cache, to avoid reusing images with the
00146                 // wrong colormap, then calls base class version.
00147                 virtual void setColormap(Colormap *cmap, Float weight);
00148 
00149                 // Empty cache completely.
00150                 virtual void purgeCache();
00151 
00152                 // Empty cache of all DMs for a given WCH.
00153                 virtual void purgeCache(const WorldCanvasHolder& wch);
00154 
00155 
00156 
00157         protected:
00158 
00159                 // Create a new (Caching)DisplayMethod for drawing on the given
00160                 // WorldCanvas when the AttributeBuffers are suitably matched to the
00161                 // current state of this DisplayData and of the WorldCanvas/Holder.
00162                 virtual CachingDisplayMethod *newDisplayMethod(WorldCanvas *worldCanvas,
00163                         AttributeBuffer *wchAttributes,
00164                         AttributeBuffer *ddAttributes,
00165                         CachingDisplayData *dd) = 0;
00166 
00167                 // Return the current options of this DisplayData as an
00168                 // AttributeBuffer.  The caller must delete the returned buffer.
00169                 virtual AttributeBuffer optionsAsAttributes();
00170 
00171                 // Return any additional Attributes to consider when searching the
00172                 // cache.  I guess I might put things like Colormap setup in here,
00173                 // since we need a way to handle the Colormap size being altered,
00174                 // and later returned to its original size/location in the
00175                 // PCColorTable, etc.
00176                 /*
00177                 virtual AttributeBuffer cachingAttributes();
00178                 */
00179 
00180                 // Turn caching on/off.
00181                 virtual void setCaching(const Bool caching);
00182 
00183                 // (Required) copy constructor.
00184                 CachingDisplayData(const CachingDisplayData &other);
00185 
00186                 // (Required) copy assignment.
00187                 void operator=(const CachingDisplayData &other);
00188 
00189 
00190                 // The default is False.  Derived DDs (such as WedgeDD) can set it True
00191                 // so that the colormap on the PixelCanvas before the DD draws is
00192                 // restored to it afterward.  The 'colormap fiddling' mouse tools can
00193                 // (unfortunately) only operate on the PC's current colormap; this
00194                 // kludge is an attempt to assure that the 'right' one is left there.
00195                 Bool restorePCColormap_;
00196 
00197         private:
00198 
00199                 // Caching state.
00200                 Bool itsCachingState;
00201 
00202                 // Default and actual maximum length of element list.
00203                 Int itsDefaultMaximumCacheSize, itsOptionsMaximumCacheSize;
00204 
00205                 // List containing the CachingDisplayMethods for this
00206                 // CachingDisplayData.
00207                 List<void *> itsElementList;
00208 
00209                 // Iterator for itsElementList.
00210                 ListIter<void *> *itsElementListIter;
00211 
00212                 // Clear out cache entries beyond end of list.
00213                 void trimCache();
00214 
00215                 // Install the default options for this DisplayData.
00216                 void installDefaultOptions();
00217 
00218         };
00219 
00220 
00221 } //# NAMESPACE CASA - END
00222 
00223 #endif
00224 
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 31 Aug 2016 for casa by  doxygen 1.6.1