1
2/*
3 * Copyright 2008 The Android Open Source Project
4 *
5 * Use of this source code is governed by a BSD-style license that can be
6 * found in the LICENSE file.
7 */
8
9
10#ifndef SkPixelRef_DEFINED
11#define SkPixelRef_DEFINED
12
13#include "SkBitmap.h"
14#include "SkRefCnt.h"
15#include "SkString.h"
16#include "SkFlattenable.h"
17#include "SkTDArray.h"
18
19//#define SK_SUPPORT_LEGACY_PIXELREF_CONSTRUCTOR
20
21#ifdef SK_DEBUG
22    /**
23     *  Defining SK_IGNORE_PIXELREF_SETPRELOCKED will force all pixelref
24     *  subclasses to correctly handle lock/unlock pixels. For performance
25     *  reasons, simple malloc-based subclasses call setPreLocked() to skip
26     *  the overhead of implementing these calls.
27     *
28     *  This build-flag disables that optimization, to add in debugging our
29     *  call-sites, to ensure that they correctly balance their calls of
30     *  lock and unlock.
31     */
32//    #define SK_IGNORE_PIXELREF_SETPRELOCKED
33#endif
34
35class SkColorTable;
36class SkData;
37struct SkIRect;
38class SkMutex;
39
40class GrTexture;
41
42/** \class SkPixelRef
43
44    This class is the smart container for pixel memory, and is used with
45    SkBitmap. A pixelref is installed into a bitmap, and then the bitmap can
46    access the actual pixel memory by calling lockPixels/unlockPixels.
47
48    This class can be shared/accessed between multiple threads.
49*/
50class SK_API SkPixelRef : public SkFlattenable {
51public:
52    SK_DECLARE_INST_COUNT(SkPixelRef)
53
54#ifdef SK_SUPPORT_LEGACY_PIXELREF_CONSTRUCTOR
55    // DEPRECATED -- use a constructor that takes SkImageInfo
56    explicit SkPixelRef(SkBaseMutex* mutex = NULL);
57#endif
58
59    explicit SkPixelRef(const SkImageInfo&);
60    SkPixelRef(const SkImageInfo&, SkBaseMutex* mutex);
61    virtual ~SkPixelRef();
62
63    const SkImageInfo& info() const {
64        return fInfo;
65    }
66
67    /** Return the pixel memory returned from lockPixels, or null if the
68        lockCount is 0.
69    */
70    void* pixels() const { return fPixels; }
71
72    /** Return the current colorTable (if any) if pixels are locked, or null.
73    */
74    SkColorTable* colorTable() const { return fColorTable; }
75
76    /**
77     *  Returns true if the lockcount > 0
78     */
79    bool isLocked() const { return fLockCount > 0; }
80
81    SkDEBUGCODE(int getLockCount() const { return fLockCount; })
82
83    /** Call to access the pixel memory, which is returned. Balance with a call
84        to unlockPixels().
85    */
86    void lockPixels();
87    /** Call to balanace a previous call to lockPixels(). Returns the pixels
88        (or null) after the unlock. NOTE: lock calls can be nested, but the
89        matching number of unlock calls must be made in order to free the
90        memory (if the subclass implements caching/deferred-decoding.)
91    */
92    void unlockPixels();
93
94    /**
95     *  Some bitmaps can return a copy of their pixels for lockPixels(), but
96     *  that copy, if modified, will not be pushed back. These bitmaps should
97     *  not be used as targets for a raster device/canvas (since all pixels
98     *  modifications will be lost when unlockPixels() is called.)
99     */
100    bool lockPixelsAreWritable() const;
101
102    /** Returns a non-zero, unique value corresponding to the pixels in this
103        pixelref. Each time the pixels are changed (and notifyPixelsChanged is
104        called), a different generation ID will be returned.
105    */
106    uint32_t getGenerationID() const;
107
108    /** Call this if you have changed the contents of the pixels. This will in-
109        turn cause a different generation ID value to be returned from
110        getGenerationID().
111    */
112    void notifyPixelsChanged();
113
114    /** Returns true if this pixelref is marked as immutable, meaning that the
115        contents of its pixels will not change for the lifetime of the pixelref.
116    */
117    bool isImmutable() const { return fIsImmutable; }
118
119    /** Marks this pixelref is immutable, meaning that the contents of its
120        pixels will not change for the lifetime of the pixelref. This state can
121        be set on a pixelref, but it cannot be cleared once it is set.
122    */
123    void setImmutable();
124
125    /** Return the optional URI string associated with this pixelref. May be
126        null.
127    */
128    const char* getURI() const { return fURI.size() ? fURI.c_str() : NULL; }
129
130    /** Copy a URI string to this pixelref, or clear the URI if the uri is null
131     */
132    void setURI(const char uri[]) {
133        fURI.set(uri);
134    }
135
136    /** Copy a URI string to this pixelref
137     */
138    void setURI(const char uri[], size_t len) {
139        fURI.set(uri, len);
140    }
141
142    /** Assign a URI string to this pixelref.
143    */
144    void setURI(const SkString& uri) { fURI = uri; }
145
146    /**
147     *  If the pixelRef has an encoded (i.e. compressed) representation,
148     *  return a ref to its data. If the pixelRef
149     *  is uncompressed or otherwise does not have this form, return NULL.
150     *
151     *  If non-null is returned, the caller is responsible for calling unref()
152     *  on the data when it is finished.
153     */
154    SkData* refEncodedData() {
155        return this->onRefEncodedData();
156    }
157
158    /**
159     *  Experimental -- tells the caller if it is worth it to call decodeInto().
160     *  Just an optimization at this point, to avoid checking the cache first.
161     *  We may remove/change this call in the future.
162     */
163    bool implementsDecodeInto() {
164        return this->onImplementsDecodeInto();
165    }
166
167    /**
168     *  Return a decoded instance of this pixelRef in bitmap. If this cannot be
169     *  done, return false and the bitmap parameter is ignored/unchanged.
170     *
171     *  pow2 is the requeste power-of-two downscale that the caller needs. This
172     *  can be ignored, and the "original" size can be returned, but if the
173     *  underlying codec can efficiently return a smaller size, that should be
174     *  done. Some examples:
175     *
176     *  To request the "base" version (original scale), pass 0 for pow2
177     *  To request 1/2 scale version (1/2 width, 1/2 height), pass 1 for pow2
178     *  To request 1/4 scale version (1/4 width, 1/4 height), pass 2 for pow2
179     *  ...
180     *
181     *  If this returns true, then bitmap must be "locked" such that
182     *  bitmap->getPixels() will return the correct address.
183     */
184    bool decodeInto(int pow2, SkBitmap* bitmap) {
185        SkASSERT(pow2 >= 0);
186        return this->onDecodeInto(pow2, bitmap);
187    }
188
189    /** Are we really wrapping a texture instead of a bitmap?
190     */
191    virtual GrTexture* getTexture() { return NULL; }
192
193    bool readPixels(SkBitmap* dst, const SkIRect* subset = NULL);
194
195    /**
196     *  Makes a deep copy of this PixelRef, respecting the requested config.
197     *  @param config Desired config.
198     *  @param subset Subset of this PixelRef to copy. Must be fully contained within the bounds of
199     *         of this PixelRef.
200     *  @return A new SkPixelRef, or NULL if either there is an error (e.g. the destination could
201     *          not be created with the given config), or this PixelRef does not support deep
202     *          copies.
203     */
204    virtual SkPixelRef* deepCopy(SkBitmap::Config config, const SkIRect* subset = NULL) {
205        return NULL;
206    }
207
208#ifdef SK_BUILD_FOR_ANDROID
209    /**
210     *  Acquire a "global" ref on this object.
211     *  The default implementation just calls ref(), but subclasses can override
212     *  this method to implement additional behavior.
213     */
214    virtual void globalRef(void* data=NULL);
215
216    /**
217     *  Release a "global" ref on this object.
218     *  The default implementation just calls unref(), but subclasses can override
219     *  this method to implement additional behavior.
220     */
221    virtual void globalUnref();
222#endif
223
224    SK_DEFINE_FLATTENABLE_TYPE(SkPixelRef)
225
226    // Register a listener that may be called the next time our generation ID changes.
227    //
228    // We'll only call the listener if we're confident that we are the only SkPixelRef with this
229    // generation ID.  If our generation ID changes and we decide not to call the listener, we'll
230    // never call it: you must add a new listener for each generation ID change.  We also won't call
231    // the listener when we're certain no one knows what our generation ID is.
232    //
233    // This can be used to invalidate caches keyed by SkPixelRef generation ID.
234    struct GenIDChangeListener {
235        virtual ~GenIDChangeListener() {}
236        virtual void onChange() = 0;
237    };
238
239    // Takes ownership of listener.
240    void addGenIDChangeListener(GenIDChangeListener* listener);
241
242protected:
243    /** Called when the lockCount goes from 0 to 1. The caller will have already
244        acquire a mutex for thread safety, so this method need not do that.
245    */
246    virtual void* onLockPixels(SkColorTable**) = 0;
247
248    /**
249     *  Called when the lock count goes from 1 to 0. The caller will have
250     *  already acquire a mutex for thread safety, so this method need not do
251     *  that.
252     *
253     *  If the previous call to onLockPixels failed (i.e. returned NULL), then
254     *  the onUnlockPixels will NOT be called.
255     */
256    virtual void onUnlockPixels() = 0;
257
258    /** Default impl returns true */
259    virtual bool onLockPixelsAreWritable() const;
260
261    // returns false;
262    virtual bool onImplementsDecodeInto();
263    // returns false;
264    virtual bool onDecodeInto(int pow2, SkBitmap* bitmap);
265
266    /**
267     *  For pixelrefs that don't have access to their raw pixels, they may be
268     *  able to make a copy of them (e.g. if the pixels are on the GPU).
269     *
270     *  The base class implementation returns false;
271     */
272    virtual bool onReadPixels(SkBitmap* dst, const SkIRect* subsetOrNull);
273
274    // default impl returns NULL.
275    virtual SkData* onRefEncodedData();
276
277    /**
278     *  Returns the size (in bytes) of the internally allocated memory.
279     *  This should be implemented in all serializable SkPixelRef derived classes.
280     *  SkBitmap::fPixelRefOffset + SkBitmap::getSafeSize() should never overflow this value,
281     *  otherwise the rendering code may attempt to read memory out of bounds.
282     *
283     *  @return default impl returns 0.
284     */
285    virtual size_t getAllocatedSizeInBytes() const;
286
287    /** Return the mutex associated with this pixelref. This value is assigned
288        in the constructor, and cannot change during the lifetime of the object.
289    */
290    SkBaseMutex* mutex() const { return fMutex; }
291
292    // serialization
293    SkPixelRef(SkFlattenableReadBuffer&, SkBaseMutex*);
294    virtual void flatten(SkFlattenableWriteBuffer&) const SK_OVERRIDE;
295
296    // only call from constructor. Flags this to always be locked, removing
297    // the need to grab the mutex and call onLockPixels/onUnlockPixels.
298    // Performance tweak to avoid those calls (esp. in multi-thread use case).
299    void setPreLocked(void* pixels, SkColorTable* ctable);
300
301private:
302    SkBaseMutex*    fMutex; // must remain in scope for the life of this object
303    // FIXME: fInfo should be const once we remove old constructor that does
304    // not set it.
305    SkImageInfo     fInfo;
306
307    void*           fPixels;
308    SkColorTable*   fColorTable;    // we do not track ownership, subclass does
309    int             fLockCount;
310
311    mutable uint32_t fGenerationID;
312    mutable bool     fUniqueGenerationID;
313
314    SkTDArray<GenIDChangeListener*> fGenIDChangeListeners;  // pointers are owned
315
316    SkString    fURI;
317
318    // can go from false to true, but never from true to false
319    bool    fIsImmutable;
320    // only ever set in constructor, const after that
321    bool    fPreLocked;
322
323    void needsNewGenID();
324    void callGenIDChangeListeners();
325
326    void setMutex(SkBaseMutex* mutex);
327
328    // When copying a bitmap to another with the same shape and config, we can safely
329    // clone the pixelref generation ID too, which makes them equivalent under caching.
330    friend class SkBitmap;  // only for cloneGenID
331    void cloneGenID(const SkPixelRef&);
332
333    typedef SkFlattenable INHERITED;
334};
335
336#endif
337