sd/source/ui/slidesorter/cache/SlsBitmapCache.hxx

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: SlsBitmapCache.hxx,v $
  10  * $Revision: 1.6 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31 #ifndef SD_SLIDESORTER_BITMAP_CACHE_HXX
  32 #define SD_SLIDESORTER_BITMAP_CACHE_HXX
  33
  34 class SdrPage;
  35
  36 #include <vcl/bitmapex.hxx>
  37 #include <osl/mutex.hxx>
  38 #include <memory>
  39 #include <boost/shared_ptr.hpp>
  40 #include <hash_map>
  41
  42 namespace sd { namespace slidesorter { namespace cache {
  43
  44 class BitmapReplacement;
  45 class CacheCompactor;
  46 class BitmapCompressor;
  47
  48 /** This low level cache is the actual bitmap container.  It supports a
  49     precious flag for every preview bitmap and keeps track of total sizes
  50     for all previews with as well as those without the flag.  The precious
  51     flag is used by compaction algorithms to determine which previews may be
  52     compressed or even discarded and which have to remain in their original
  53     form.  The precious flag is usually set for the visible previews.
  54 */
  55 class BitmapCache
  56 {
  57 public:
  58     /** The key for looking up preview bitmaps is a pointer to an SdrPage
  59         object.  The prior use of PageObjectViewObjectContact objects (which
  60         ultimatly use them) turned out to be less suitable because their
  61         life time is shorter then that of the page objects.  Frequent
  62         destruction and re-creation of the preview bitmaps was the result.
  63     */
  64     typedef const SdrPage* CacheKey;
  65     class CacheEntry;
  66     class CacheBitmapContainer;
  67     typedef ::std::vector<CacheKey> CacheIndex;
  68
  69     /** Create a new cache for bitmap objects.
  70         @param nMaximalNormalCacheSize
  71             When a size larger then zero is given then that size is used.
  72             Otherwise the default value from the configuration is used.
  73             When that does not exist either then a internal default value is
  74             used.
  75     */
  76     BitmapCache (const sal_Int32 nMaximalNormalCacheSize = 0);
  77
  78     /** The destructor clears the cache and relases all bitmaps still in it.
  79     */
  80     ~BitmapCache (void);
  81
  82     /** Remove all preview bitmaps from the cache.  After this call the
  83         cache is empty.
  84     */
  85     void Clear (void);
  86
  87     /** Returns <TRUE/> when there is no preview bitmap in the cache.
  88     */
  89     bool IsEmpty (void) const;
  90
  91     /** Return <TRUE/> when the cache is full, i.e. the cache compactor had
  92         to be run.
  93     */
  94     bool IsFull (void) const;
  95
  96     /** Return the memory size that is occupied by all non-precious bitmaps
  97         in the cache.
  98     */
  99     sal_Int32 GetSize (void);
 100
 101     /** Return <TRUE/> when a preview bitmap exists for the given key.
 102     */
 103     bool HasBitmap (const CacheKey& rKey);
 104
 105     /** Return <TRUE/> when a preview bitmap exists for the given key and
 106         when it is up-to-date.
 107     */
 108     bool BitmapIsUpToDate (const CacheKey& rKey);
 109
 110     /** Return the preview bitmap for the given contact object.
 111     */
 112     ::boost::shared_ptr<BitmapEx> GetBitmap (const CacheKey& rKey);
 113
 114     /** Release the reference to the preview bitmap that is associated with
 115         the given key.
 116     */
 117     void ReleaseBitmap (const CacheKey& rKey);
 118
 119     /** Mark the specified preview bitmap as not being up-to-date anymore.
 120     */
 121     void InvalidateBitmap (const CacheKey& rKey);
 122
 123     /** Mark all preview bitmaps as not being up-to-date anymore.
 124     */
 125     void InvalidateCache (void);
 126
 127     /** Add or replace a bitmap for the given key.
 128     */
 129     void SetBitmap (
 130         const CacheKey& rKey,
 131         const ::boost::shared_ptr<BitmapEx>& rpPreview,
 132         bool bIsPrecious);
 133
 134     /** Return whether the specified preview bitmap has been marked as
 135         precious.
 136     */
 137     bool IsPrecious (const CacheKey& rKey);
 138
 139     /** Mark the specified preview bitmap as precious, i.e. that it must not
 140         be compressed or otherwise removed from the cache.
 141     */
 142     void SetPrecious (const CacheKey& rKey, bool bIsPrecious);
 143
 144     /** Calculate the cache size.  This should rarely be necessary because
 145         the cache size is tracked with each modification of preview
 146         bitmaps.
 147     */
 148     void ReCalculateTotalCacheSize (void);
 149
 150     /** Use the previews in the given cache to initialize missing previews.
 151     */
 152     void Recycle (const BitmapCache& rCache);
 153
 154     /** Return a list of sorted cache keys that represent an index into (a
 155         part of) the cache.  The entries of the index are sorted according
 156         to last access times with the least recently access time first.
 157         @param bIncludePrecious
 158             When this flag is <TRUE/> entries with the precious flag set are
 159             included in the index.  When the flag is <FALSE/> these entries
 160             are ommited.
 161         @param bIncludeNoPreview
 162             When this flag is <TRUE/> entries with that have no preview
 163             bitmaps are included in the index.  When the flag is <FALSE/> these entries
 164             are ommited.
 165     */
 166     ::std::auto_ptr<CacheIndex> GetCacheIndex (
 167         bool bIncludePrecious,
 168         bool bIncludeNoPreview) const;
 169
 170     /** Compress the specified preview bitmap with the given bitmap
 171         compressor.  A reference to the compressor is stored for later
 172         decompression.
 173     */
 174     void Compress (
 175         const CacheKey& rKey,
 176         const ::boost::shared_ptr<BitmapCompressor>& rpCompressor);
 177
 178 private:
 179     mutable ::osl::Mutex maMutex;
 180
 181     ::std::auto_ptr<CacheBitmapContainer> mpBitmapContainer;
 182
 183     /** Total size of bytes that are occupied by bitmaps in the cache for
 184         whom the slides are currently not inside the visible area.
 185     */
 186     sal_Int32 mnNormalCacheSize;
 187
 188     /** Total size of bytes that are occupied by bitmaps in the cache for
 189         whom the slides are currently visible.
 190     */
 191     sal_Int32 mnPreciousCacheSize;
 192
 193     /** At the moment the access time is not an actual time or date value
 194         but a counter that is increased with every access.  It thus defines
 195         the same ordering as a true time.
 196     */
 197     sal_Int32 mnCurrentAccessTime;
 198
 199     /** The maximal cache size for the off-screen preview bitmaps.  When
 200         mnNormalCacheSize grows larger than this value then the
 201         mpCacheCompactor member is used to reduce the cache size.
 202     */
 203     sal_Int32 mnMaximalNormalCacheSize;
 204
 205     /** The cache compactor is used to reduce the number of bytes used by
 206         off-screen preview bitmaps.
 207     */
 208     ::std::auto_ptr<CacheCompactor> mpCacheCompactor;
 209
 210     /** This flag stores if the cache is or recently was full, i.e. the
 211         cache compactor has or had to be run in order to reduce the cache
 212         size to the allowed value.
 213     */
 214     bool mbIsFull;
 215
 216     /** Update mnNormalCacheSize or mnPreciousCacheSize according to the
 217         precious flag of the specified preview bitmap and the specified
 218         operation.
 219     */
 220     enum CacheOperation { ADD, REMOVE };
 221     void UpdateCacheSize (const CacheEntry& rKey, CacheOperation eOperation);
 222 };
 223
 224
 225
 226 } } } // end of namespace ::sd::slidesorter::cache
 227
 228 #endif