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 <memory>
  28
  29 namespace sd { namespace slidesorter { namespace cache {
  30
  31 class CacheCompactor;
  32 class BitmapCompressor;
  33
  34 /** This low level cache is the actual bitmap container.  It supports a
  35     precious flag for every preview bitmap and keeps track of total sizes
  36     for all previews with/without this flag.  The precious flag is used by
  37     compaction algorithms to determine which previews may be compressed or
  38     even discarded and which have to remain in their original form.  The
  39     precious flag is usually set for the visible previews.
  40
  41     Additionally to the actual preview there is an optional marked preview.
  42     This is used for slides excluded from the slide show which have a preview
  43     that shows a mark (some sort of bitmap overlay) to that effect.
  44 */
  45 class BitmapCache
  46 {
  47 public:
  48     /** The key for looking up preview bitmaps is a pointer to an SdrPage
  49         object.  The prior use of PageObjectViewObjectContact objects (which
  50         ultimately use them) turned out to be less suitable because their
  51         life time is shorter then that of the page objects.  Frequent
  52         destruction and re-creation of the preview bitmaps was the result.
  53     */
  54     typedef const SdrPage* CacheKey;
  55     class CacheEntry;
  56     class CacheBitmapContainer;
  57     typedef ::std::vector<CacheKey> CacheIndex;
  58
  59     /** Create a new cache for bitmap objects.
  60         The default value from the configuration is used.
  61         When that does not exist then a internal default value is
  62         used.
  63     */
  64     explicit BitmapCache ();
  65
  66     /** The destructor clears the cache and releases all bitmaps still in it.
  67     */
  68     ~BitmapCache();
  69
  70     /** Remove all preview bitmaps from the cache.  After this call the
  71         cache is empty.
  72     */
  73     void Clear();
  74
  75     /** Return <TRUE/> when the cache is full, i.e. the cache compactor had
  76         to be run.
  77     */
  78     bool IsFull() const { return mbIsFull;}
  79
  80     /** Return the memory size that is occupied by all non-precious bitmaps
  81         in the cache.
  82     */
  83     sal_Int32 GetSize() { return mnNormalCacheSize;}
  84
  85     /** Return <TRUE/> when a preview bitmap exists for the given key.
  86     */
  87     bool HasBitmap (const CacheKey& rKey);
  88
  89     /** Return <TRUE/> when a preview bitmap exists for the given key and
  90         when it is up-to-date.
  91     */
  92     bool BitmapIsUpToDate (const CacheKey& rKey);
  93
  94     /** Return the preview bitmap for the given contact object.
  95     */
  96     BitmapEx GetBitmap (const CacheKey& rKey);
  97
  98     /** Return the marked preview bitmap for the given contact object.
  99     */
 100     BitmapEx GetMarkedBitmap (const CacheKey& rKey);
 101
 102     /** Release the reference to the preview bitmap that is associated with
 103         the given key.
 104     */
 105     void ReleaseBitmap (const CacheKey& rKey);
 106
 107     /** Mark the specified preview bitmap as not being up-to-date
 108         anymore.
 109         @return
 110             When the key references a page in the cache then
 111             return <TRUE/>.  When the key is not known then <FALSE/>
 112             is returned.
 113     */
 114     bool InvalidateBitmap (const CacheKey& rKey);
 115
 116     /** Mark all preview bitmaps as not being up-to-date anymore.
 117     */
 118     void InvalidateCache();
 119
 120     /** Add or replace a bitmap for the given key.
 121     */
 122     void SetBitmap (
 123         const CacheKey& rKey,
 124         const BitmapEx& rPreview,
 125         bool bIsPrecious);
 126
 127     /** Add or replace a marked bitmap for the given key.
 128     */
 129     void SetMarkedBitmap (
 130         const CacheKey& rKey,
 131         const BitmapEx& rPreview);
 132
 133     /** Mark the specified preview bitmap as precious, i.e. that it must not
 134         be compressed or otherwise removed from the cache.
 135     */
 136     void SetPrecious (const CacheKey& rKey, bool bIsPrecious);
 137
 138     /** Calculate the cache size.  This should rarely be necessary because
 139         the cache size is tracked with each modification of preview
 140         bitmaps.
 141     */
 142     void ReCalculateTotalCacheSize();
 143
 144     /** Use the previews in the given cache to initialize missing previews.
 145     */
 146     void Recycle (const BitmapCache& rCache);
 147
 148     /** Return a list of sorted cache keys that represent an index into (a
 149         part of) the cache.  The entries of the index are sorted according
 150         to last access times with the least recently access time first.
 151         Entries with the precious flag set are omitted.
 152         Entries with that have no preview bitmaps are omitted.
 153     */
 154     ::std::unique_ptr<CacheIndex> GetCacheIndex () const;
 155
 156     /** Compress the specified preview bitmap with the given bitmap
 157         compressor.  A reference to the compressor is stored for later
 158         decompression.
 159     */
 160     void Compress (
 161         const CacheKey& rKey,
 162         const std::shared_ptr<BitmapCompressor>& rpCompressor);
 163
 164 private:
 165     mutable ::osl::Mutex maMutex;
 166
 167     std::unique_ptr<CacheBitmapContainer> mpBitmapContainer;
 168
 169     /** Total size of bytes that are occupied by bitmaps in the cache for
 170         whom the slides are currently not inside the visible area.
 171     */
 172     sal_Int32 mnNormalCacheSize;
 173
 174     /** Total size of bytes that are occupied by bitmaps in the cache for
 175         whom the slides are currently visible.
 176     */
 177     sal_Int32 mnPreciousCacheSize;
 178
 179     /** At the moment the access time is not an actual time or date value
 180         but a counter that is increased with every access.  It thus defines
 181         the same ordering as a true time.
 182     */
 183     sal_Int32 mnCurrentAccessTime;
 184
 185     /** The maximal cache size for the off-screen preview bitmaps.  When
 186         mnNormalCacheSize grows larger than this value then the
 187         mpCacheCompactor member is used to reduce the cache size.
 188     */
 189     sal_Int32 mnMaximalNormalCacheSize;
 190
 191     /** The cache compactor is used to reduce the number of bytes used by
 192         off-screen preview bitmaps.
 193     */
 194     ::std::unique_ptr<CacheCompactor> mpCacheCompactor;
 195
 196     /** This flag stores if the cache is or recently was full, i.e. the
 197         cache compactor has or had to be run in order to reduce the cache
 198         size to the allowed value.
 199     */
 200     bool mbIsFull;
 201
 202     /** Update mnNormalCacheSize or mnPreciousCacheSize according to the
 203         precious flag of the specified preview bitmap and the specified
 204         operation.
 205     */
 206     enum CacheOperation { ADD, REMOVE };
 207     void UpdateCacheSize (const CacheEntry& rKey, CacheOperation eOperation);
 208 };
 209
 210 } } } // end of namespace ::sd::slidesorter::cache
 211
 212 #endif
 213
 214 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */