CachingDisplayData.h

Go to the documentation of this file.

//# CachingDisplayData.h: base class for auto-caching DisplayData objects
//# Copyright (C) 1999,2000,2001,2002,2003
//# Associated Universities, Inc. Washington DC, USA.
//#
//# This library is free software; you can redistribute it and/or modify it
//# under the terms of the GNU Library General Public License as published by
//# the Free Software Foundation; either version 2 of the License, or (at your
//# option) any later version.
//#
//# This library is distributed in the hope that it will be useful, but WITHOUT
//# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
//# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
//# License for more details.
//#
//# You should have received a copy of the GNU Library General Public License
//# along with this library; if not, write to the Free Software Foundation,
//# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
//#
//# Correspondence concerning AIPS++ should be addressed as follows:
//#        Internet email: aips2-request@nrao.edu.
//#        Postal address: AIPS++ Project Office
//#                        National Radio Astronomy Observatory
//#                        520 Edgemont Road
//#                        Charlottesville, VA 22903-2475 USA
//#
//# $Id$

#ifndef TRIALDISPLAY_CACHINGDISPLAYDATA_H
#define TRIALDISPLAY_CACHINGDISPLAYDATA_H

#include <casa/aips.h>
#include <list>
#include <display/DisplayDatas/DisplayData.h>

namespace casa { //# NAMESPACE CASA - BEGIN

        class WorldCanvas;
        class WorldCanvasHolder;
        class AttributeBuffer;
        class CachingDisplayMethod;

// <summary>
// Base class for auto-caching DisplayData objects.
// </summary>

// <use visibility=export>

// <reviewed reviewer="" data="" tests="" demos="">
// </reviewed>

// <prerequisite>
// <li> <linkto class=DisplayData> DisplayData </linkto>
// </prerequisite>

// <etymology>
// "CachingDisplayData" is an implementation of a <linkto
// class=DisplayData> DisplayData </linkto> which provides automatic
// caching of individual depictions of the data.
// </etymology>

// <synopsis>
// This class adds to the interface defined in <linkto
// class=DisplayData>DisplayData </linkto>.  It adds an "automagic"
// caching system, which takes care of managing a set of individual
// drawings made by the DisplayData, and using previously generated
// drawing commands where applicable.  For example, the user might be
// playing a movie of several frames in a DisplayData.  The automagic
// caching will ensure that after one complete loop, while parameters
// affecting the display of the data do not change, all subsequent
// drawings will be made from a cache of drawing commands.
// Furthermore, provided the cache is large enough, the user may alter
// parameters, view some more frames, then return the parameters to
// their original state, and there may still be older cached drawings
// which can be used.
//
// The automagic caching also handles the case where a single
// DisplayData is registered on more than one <linkto
// class=WorldCanvasHolder>WorldCanvasHolder </linkto>.  Thus a
// miniature view of the data could be shown in one window, and an
// expanded view in another, with full automagic caching available on
// both.
//
// This is a base class.  Derived classes must implement the
// <src>newDisplayMethod</src> method, which is called to construct a
// new <linkto class=CachingDisplayMethod> CachingDisplayMethod
// </linkto> when the cache cannot satisfy the current drawing
// request.  The method <src>optionsAsAttributes</src> should also be
// implemented: when a new CachingDisplayMethod is constructed, the
// return value of this method will be used to tag the parameters used
// in the drawing itself.  Finally, the method
// <src>cachingAttributes</src> can be over-ridden, and should
// return any additional <linkto class=Attribute> Attributes </linkto>
// which should be considered in searches of the cache.
// </synopsis>

// <motivation>
// Most DisplayData classes will offer more than one view of the data.
// Caching is therefore desirable to improve display speed for
// re-display of individual views of the data.  It is nice to keep the
// caching in one place, hence this class.
// </motivation>

        class CachingDisplayData : public DisplayData {

        public:

                // Constructor.
                CachingDisplayData();

                // Destructor.
                virtual ~CachingDisplayData();

                // Install the default options for this DisplayData.
                virtual void setDefaultOptions();

                // Apply options stored in <src>rec</src> to the DisplayData.  A
                // return value of <src>true</src> means a refresh is needed.
                // <src>recOut</src> contains any fields which were implicitly
                // changed as a result of the call to this function.  The options
                // handled by this class are:
                // <li> <src>cachesize</src>: an integer specifying the maximum
                // number of views which can be stored in the cache.  The default
                // value can be specified by the <src>display.cachesize</src>
                // variable in the user's <src>.aipsrc</src> file, and in lieu
                // of that, will be 256.  If <src>cachesize</src> is lowered by
                // a call to this method, the cache will be shrunk in size, with
                // the oldest drawings being removed first. </li>
                virtual casacore::Bool setOptions(casacore::Record &rec, casacore::Record &recOut);

                // Retrieve the current and default options and parameter types.
                virtual casacore::Record getOptions( bool scrub=false ) const;

                // Refresh event handler which is called indirectly by the
                // WorldCanvas, via the WorldCanvasHolder.  This function will take
                // care of calling <src>newDisplayMethod</src> when necessary, and
                // otherwise using an existing (previously cached) draw list.
                virtual void refreshEH(const WCRefreshEvent &ev);

                // <group>
                virtual void notifyRegister(WorldCanvasHolder *wcHolder) ;
                virtual void notifyUnregister(WorldCanvasHolder& wcHolder,
                                              casacore::Bool ignoreRefresh = false) ;
                // </group>

                // Purges cache, to avoid reusing images with the
                // wrong colormap, then calls base class version.
                virtual void setColormap(Colormap *cmap, casacore::Float weight);

                // Empty cache completely.
                virtual void purgeCache();

                // Empty cache of all DMs for a given WCH.
                virtual void purgeCache(const WorldCanvasHolder& wch);



        protected:

                // Create a new (Caching)DisplayMethod for drawing on the given
                // WorldCanvas when the AttributeBuffers are suitably matched to the
                // current state of this DisplayData and of the WorldCanvas/Holder.
                virtual CachingDisplayMethod *newDisplayMethod(WorldCanvas *worldCanvas,
                        AttributeBuffer *wchAttributes,
                        AttributeBuffer *ddAttributes,
                        CachingDisplayData *dd) = 0;

                // Return the current options of this DisplayData as an
                // AttributeBuffer.  The caller must delete the returned buffer.
                virtual AttributeBuffer optionsAsAttributes();

                // Return any additional Attributes to consider when searching the
                // cache.  I guess I might put things like Colormap setup in here,
                // since we need a way to handle the Colormap size being altered,
                // and later returned to its original size/location in the
                // PCColorTable, etc.
                /*
                virtual AttributeBuffer cachingAttributes();
                */

                // Turn caching on/off.
                virtual void setCaching(const casacore::Bool caching);

                // (Required) copy constructor.
                CachingDisplayData(const CachingDisplayData &other);

                // (Required) copy assignment.
                void operator=(const CachingDisplayData &other);


                // The default is false.  Derived DDs (such as WedgeDD) can set it true
                // so that the colormap on the PixelCanvas before the DD draws is
                // restored to it afterward.  The 'colormap fiddling' mouse tools can
                // (unfortunately) only operate on the PC's current colormap; this
                // kludge is an attempt to assure that the 'right' one is left there.
                casacore::Bool restorePCColormap_;

        private:

                // Caching state.
                casacore::Bool itsCachingState;

                // Default and actual maximum length of element list.
                casacore::Int itsDefaultMaximumCacheSize, itsOptionsMaximumCacheSize;

                // casacore::List containing the CachingDisplayMethods for this
                // CachingDisplayData.
                std::list<void *> itsElementList;

                // Clear out cache entries beyond end of list.
                void trimCache();

                // Install the default options for this DisplayData.
                void installDefaultOptions();

        };


} //# NAMESPACE CASA - END

#endif