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