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