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

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 #ifndef INCLUDED_SD_SOURCE_UI_SLIDESORTER_CACHE_SLSBITMAPCACHE_HXX
  21 #define INCLUDED_SD_SOURCE_UI_SLIDESORTER_CACHE_SLSBITMAPCACHE_HXX
  22
  23 class SdrPage;
  24
  25 #include <vcl/bitmapex.hxx>
  26 #include <osl/mutex.hxx>
  27 #include <boost/shared_ptr.hpp>
  28 #include <boost/scoped_ptr.hpp>
  29
  30 namespace sd { namespace slidesorter { namespace cache {
  31
  32 class CacheCompactor;
  33 class BitmapCompressor;
  34
  35 /** This low level cache is the actual bitmap container.  It supports a
  36     precious flag for every preview bitmap and keeps track of total sizes
  37     for all previews with/without this flag.  The precious flag is used by
  38     compaction algorithms to determine which previews may be compressed or
  39     even discarded and which have to remain in their original form.  The
  40     precious flag is usually set for the visible previews.
  41
  42     Additionally to the actual preview there is an optional marked preview.
  43     This is used for slides excluded from the slide show which have a preview
  44     that shows a mark (some sort of bitmap overlay) to that effect.
  45 */
  46 class BitmapCache
  47 {
  48 public:
  49     /** The key for looking up preview bitmaps is a pointer to an SdrPage
  50         object.  The prior use of PageObjectViewObjectContact objects (which
  51         ultimatly use them) turned out to be less suitable because their
  52         life time is shorter then that of the page objects.  Frequent
  53         destruction and re-creation of the preview bitmaps was the result.
  54     */
  55     typedef const SdrPage* CacheKey;
  56     class CacheEntry;
  57     class CacheBitmapContainer;
  58     typedef ::std::vector<CacheKey> CacheIndex;
  59
  60     /** Create a new cache for bitmap objects.
  61         @param nMaximalNormalCacheSize
  62             When a size larger then zero is given then that size is used.
  63             Otherwise the default value from the configuration is used.
  64             When that does not exist either then a internal default value is
  65             used.
  66     */
  67     BitmapCache (const sal_Int32 nMaximalNormalCacheSize = 0);
  68
  69     /** The destructor clears the cache and relases all bitmaps still in it.
  70     */
  71     ~BitmapCache();
  72
  73     /** Remove all preview bitmaps from the cache.  After this call the
  74         cache is empty.
  75     */
  76     void Clear();
  77
  78     /** Return <TRUE/> when the cache is full, i.e. the cache compactor had
  79         to be run.
  80     */
  81     bool IsFull() const { return mbIsFull;}
  82
  83     /** Return the memory size that is occupied by all non-precious bitmaps
  84         in the cache.
  85     */
  86     sal_Int32 GetSize() { return mnNormalCacheSize;}
  87
  88     /** Return <TRUE/> when a preview bitmap exists for the given key.
  89     */
  90     bool HasBitmap (const CacheKey& rKey);
  91
  92     /** Return <TRUE/> when a preview bitmap exists for the given key and
  93         when it is up-to-date.
  94     */
  95     bool BitmapIsUpToDate (const CacheKey& rKey);
  96
  97     /** Return the preview bitmap for the given contact object.
  98     */
  99     Bitmap GetBitmap (const CacheKey& rKey);
 100
 101     /** Return the marked preview bitmap for the given contact object.
 102     */
 103     Bitmap GetMarkedBitmap (const CacheKey& rKey);
 104
 105     /** Release the reference to the preview bitmap that is associated with
 106         the given key.
 107     */
 108     void ReleaseBitmap (const CacheKey& rKey);
 109
 110     /** Mark the specified preview bitmap as not being up-to-date
 111         anymore.
 112         @return
 113             When the key references a page in the cache then
 114             return <TRUE/>.  When the key is not known then <FALSE/>
 115             is returned.
 116     */
 117     bool InvalidateBitmap (const CacheKey& rKey);
 118
 119     /** Mark all preview bitmaps as not being up-to-date anymore.
 120     */
 121     void InvalidateCache();
 122
 123     /** Add or replace a bitmap for the given key.
 124     */
 125     void SetBitmap (
 126         const CacheKey& rKey,
 127         const Bitmap& rPreview,
 128         bool bIsPrecious);
 129
 130     /** Add or replace a marked bitmap for the given key.
 131     */
 132     void SetMarkedBitmap (
 133         const CacheKey& rKey,
 134         const Bitmap& rPreview);
 135
 136     /** Mark the specified preview bitmap as precious, i.e. that it must not
 137         be compressed or otherwise removed from the cache.
 138     */
 139     void SetPrecious (const CacheKey& rKey, bool bIsPrecious);
 140
 141     /** Calculate the cache size.  This should rarely be necessary because
 142         the cache size is tracked with each modification of preview
 143         bitmaps.
 144     */
 145     void ReCalculateTotalCacheSize();
 146
 147     /** Use the previews in the given cache to initialize missing previews.
 148     */
 149     void Recycle (const BitmapCache& rCache);
 150
 151     /** Return a list of sorted cache keys that represent an index into (a
 152         part of) the cache.  The entries of the index are sorted according
 153         to last access times with the least recently access time first.
 154         @param bIncludePrecious
 155             When this flag is <TRUE/> entries with the precious flag set are
 156             included in the index.  When the flag is <FALSE/> these entries
 157             are omitted.
 158         @param bIncludeNoPreview
 159             When this flag is <TRUE/> entries with that have no preview
 160             bitmaps are included in the index.  When the flag is <FALSE/> these entries
 161             are omitted.
 162     */
 163     ::std::unique_ptr<CacheIndex> GetCacheIndex (
 164         bool bIncludePrecious,
 165         bool bIncludeNoPreview) const;
 166
 167     /** Compress the specified preview bitmap with the given bitmap
 168         compressor.  A reference to the compressor is stored for later
 169         decompression.
 170     */
 171     void Compress (
 172         const CacheKey& rKey,
 173         const ::boost::shared_ptr<BitmapCompressor>& rpCompressor);
 174
 175 private:
 176     mutable ::osl::Mutex maMutex;
 177
 178     ::boost::scoped_ptr<CacheBitmapContainer> mpBitmapContainer;
 179
 180     /** Total size of bytes that are occupied by bitmaps in the cache for
 181         whom the slides are currently not inside the visible area.
 182     */
 183     sal_Int32 mnNormalCacheSize;
 184
 185     /** Total size of bytes that are occupied by bitmaps in the cache for
 186         whom the slides are currently visible.
 187     */
 188     sal_Int32 mnPreciousCacheSize;
 189
 190     /** At the moment the access time is not an actual time or date value
 191         but a counter that is increased with every access.  It thus defines
 192         the same ordering as a true time.
 193     */
 194     sal_Int32 mnCurrentAccessTime;
 195
 196     /** The maximal cache size for the off-screen preview bitmaps.  When
 197         mnNormalCacheSize grows larger than this value then the
 198         mpCacheCompactor member is used to reduce the cache size.
 199     */
 200     sal_Int32 mnMaximalNormalCacheSize;
 201
 202     /** The cache compactor is used to reduce the number of bytes used by
 203         off-screen preview bitmaps.
 204     */
 205     ::std::unique_ptr<CacheCompactor> mpCacheCompactor;
 206
 207     /** This flag stores if the cache is or recently was full, i.e. the
 208         cache compactor has or had to be run in order to reduce the cache
 209         size to the allowed value.
 210     */
 211     bool mbIsFull;
 212
 213     /** Update mnNormalCacheSize or mnPreciousCacheSize according to the
 214         precious flag of the specified preview bitmap and the specified
 215         operation.
 216     */
 217     enum CacheOperation { ADD, REMOVE };
 218     void UpdateCacheSize (const CacheEntry& rKey, CacheOperation eOperation);
 219 };
 220
 221 } } } // end of namespace ::sd::slidesorter::cache
 222
 223 #endif
 224
 225 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */