Quelle SurfaceCache.h Sprache: C

/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */

/**
* SurfaceCache is a service for caching temporary surfaces and decoded image
* data in imagelib.
*/

#ifndef mozilla_image_SurfaceCache_h
#define mozilla_image_SurfaceCache_h

#include "mozilla/HashFunctions.h"    // for HashGeneric and AddToHash
#include "mozilla/Maybe.h"            // for Maybe
#include "mozilla/MemoryReporting.h"  // for MallocSizeOf
#include "mozilla/NotNull.h"
#include "mozilla/SVGImageContext.h"  // for SVGImageContext
#include "mozilla/gfx/2D.h"           // for SourceSurface
#include "mozilla/gfx/Point.h"        // for mozilla::gfx::IntSize
#include "gfx2DGlue.h"
#include "gfxPoint.h"  // for gfxSize
#include "nsCOMPtr.h"  // for already_AddRefed
#include "ImageRegion.h"
#include "PlaybackType.h"
#include "SurfaceFlags.h"

namespace mozilla {
namespace image {

class ImageResource;
class ISurfaceProvider;
class LookupResult;
class SurfaceCacheImpl;
struct SurfaceMemoryCounter;

/*
* ImageKey contains the information we need to look up all SurfaceCache entries
* for a particular image.
*/
using ImageKey = ImageResource*;

/*
* SurfaceKey contains the information we need to look up a specific
* SurfaceCache entry. Together with an ImageKey, this uniquely identifies the
* surface.
*
* Callers should construct a SurfaceKey using the appropriate helper function
* for their image type - either RasterSurfaceKey or VectorSurfaceKey.
*/
class SurfaceKey {
  typedef gfx::IntSize IntSize;

public:
  bool operator==(const SurfaceKey& aOther) const {
    return aOther.mSize == mSize && aOther.mRegion == mRegion &&
           aOther.mSVGContext == mSVGContext && aOther.mPlayback == mPlayback &&
           aOther.mFlags == mFlags;
  }

  PLDHashNumber Hash() const {
    PLDHashNumber hash = HashGeneric(mSize.width, mSize.height);
    hash = AddToHash(hash, mRegion.map(HashIIR).valueOr(0));
    hash = AddToHash(hash, HashSIC(mSVGContext));
    hash = AddToHash(hash, uint8_t(mPlayback), uint32_t(mFlags));
    return hash;
  }

  SurfaceKey CloneWithSize(const IntSize& aSize) const {
    return SurfaceKey(aSize, mRegion, mSVGContext, mPlayback, mFlags);
  }

  const IntSize& Size() const { return mSize; }
  const Maybe<ImageIntRegion>& Region() const { return mRegion; }
  const SVGImageContext& SVGContext() const { return mSVGContext; }
  PlaybackType Playback() const { return mPlayback; }
  SurfaceFlags Flags() const { return mFlags; }

private:
  SurfaceKey(const IntSize& aSize, const Maybe<ImageIntRegion>& aRegion,
             const SVGImageContext& aSVGContext, PlaybackType aPlayback,
             SurfaceFlags aFlags)
      : mSize(aSize),
        mRegion(aRegion),
        mSVGContext(aSVGContext),
        mPlayback(aPlayback),
        mFlags(aFlags) {}

  static PLDHashNumber HashIIR(const ImageIntRegion& aIIR) {
    return aIIR.Hash();
  }

  static PLDHashNumber HashSIC(const SVGImageContext& aSIC) {
    return aSIC.Hash();
  }

  friend SurfaceKey RasterSurfaceKey(const IntSize&, SurfaceFlags,
                                     PlaybackType);
  friend SurfaceKey VectorSurfaceKey(const IntSize&, const SVGImageContext&);
  friend SurfaceKey VectorSurfaceKey(const IntSize&,
                                     const Maybe<ImageIntRegion>&,
                                     const SVGImageContext&, SurfaceFlags,
                                     PlaybackType);

  IntSize mSize;
  Maybe<ImageIntRegion> mRegion;
  SVGImageContext mSVGContext;
  PlaybackType mPlayback;
  SurfaceFlags mFlags;
};

inline SurfaceKey RasterSurfaceKey(const gfx::IntSize& aSize,
                                   SurfaceFlags aFlags,
                                   PlaybackType aPlayback) {
  return SurfaceKey(aSize, Nothing(), SVGImageContext(), aPlayback, aFlags);
}

inline SurfaceKey VectorSurfaceKey(const gfx::IntSize& aSize,
                                   const Maybe<ImageIntRegion>& aRegion,
                                   const SVGImageContext& aSVGContext,
                                   SurfaceFlags aFlags,
                                   PlaybackType aPlayback) {
  return SurfaceKey(aSize, aRegion, aSVGContext, aPlayback, aFlags);
}

inline SurfaceKey VectorSurfaceKey(const gfx::IntSize& aSize,
                                   const SVGImageContext& aSVGContext) {
  // We don't care about aFlags for VectorImage because none of the flags we
  // have right now influence VectorImage's rendering. If we add a new flag that
  // *does* affect how a VectorImage renders, we'll have to change this.
  // Similarly, we don't accept a PlaybackType parameter because we don't
  // currently cache frames of animated SVG images.
  return SurfaceKey(aSize, Nothing(), aSVGContext, PlaybackType::eStatic,
                    DefaultSurfaceFlags());
}

/**
* AvailabilityState is used to track whether an ISurfaceProvider has a surface
* available or is just a placeholder.
*
* To ensure that availability changes are atomic (and especially that internal
* SurfaceCache code doesn't have to deal with asynchronous availability
* changes), an ISurfaceProvider which starts as a placeholder can only reveal
* the fact that it now has a surface available via a call to
* SurfaceCache::SurfaceAvailable().
*
* It also tracks whether or not there are "explicit" users of this surface
* which will not accept substitutes. This is used by SurfaceCache when pruning
* unnecessary surfaces from the cache.
*/
class AvailabilityState {
public:
  static AvailabilityState StartAvailable() { return AvailabilityState(true); }
  static AvailabilityState StartAsPlaceholder() {
    return AvailabilityState(false);
  }

  bool IsAvailable() const { return mIsAvailable; }
  bool IsPlaceholder() const { return !mIsAvailable; }
  bool CannotSubstitute() const { return mCannotSubstitute; }

  void SetCannotSubstitute() { mCannotSubstitute = true; }

private:
  friend class SurfaceCacheImpl;

  explicit AvailabilityState(bool aIsAvailable)
      : mIsAvailable(aIsAvailable), mCannotSubstitute(false) {}

  void SetAvailable() { mIsAvailable = true; }

  bool mIsAvailable : 1;
  bool mCannotSubstitute : 1;
};

enum class InsertOutcome : uint8_t {
  SUCCESS,                 // Success (but see Insert documentation).
  FAILURE,                 // Couldn't insert (e.g., for capacity reasons).
  FAILURE_ALREADY_PRESENT  // A surface with the same key is already present.
};

/**
* SurfaceCache is an ImageLib-global service that allows caching of decoded
* image surfaces, temporary surfaces (e.g. for caching rotated or clipped
* versions of images), or dynamically generated surfaces (e.g. for animations).
* SurfaceCache entries normally expire from the cache automatically if they go
* too long without being accessed.
*
* Because SurfaceCache must support both normal surfaces and dynamically
* generated surfaces, it does not actually hold surfaces directly. Instead, it
* holds ISurfaceProvider objects which can provide access to a surface when
* requested; SurfaceCache doesn't care about the details of how this is
* accomplished.
*
* Sometime it's useful to temporarily prevent entries from expiring from the
* cache. This is most often because losing the data could harm the user
* experience (for example, we often don't want to allow surfaces that are
* currently visible to expire) or because it's not possible to rematerialize
* the surface. SurfaceCache supports this through the use of image locking; see
* the comments for Insert() and LockImage() for more details.
*
* Any image which stores surfaces in the SurfaceCache *must* ensure that it
* calls RemoveImage() before it is destroyed. See the comments for
* RemoveImage() for more details.
*/
struct SurfaceCache {
  typedef gfx::IntSize IntSize;

  /**
   * Initialize static data. Called during imagelib module initialization.
   */
  static void Initialize();

  /**
   * Release static data. Called during imagelib module shutdown.
   */
  static void Shutdown();

  /**
   * Looks up the requested cache entry and returns a drawable reference to its
   * associated surface.
   *
   * If the image associated with the cache entry is locked, then the entry will
   * be locked before it is returned.
   *
   * If a matching ISurfaceProvider was found in the cache, but SurfaceCache
   * couldn't obtain a surface from it (e.g. because it had stored its surface
   * in a volatile buffer which was discarded by the OS) then it is
   * automatically removed from the cache and an empty LookupResult is returned.
   * Note that this will never happen to ISurfaceProviders associated with a
   * locked image; SurfaceCache tells such ISurfaceProviders to keep a strong
   * references to their data internally.
   *
   * @param aImageKey       Key data identifying which image the cache entry
   *                        belongs to.
   * @param aSurfaceKey     Key data which uniquely identifies the requested
   *                        cache entry.
   * @return                a LookupResult which will contain a DrawableSurface
   *                        if the cache entry was found.
   */
  static LookupResult Lookup(const ImageKey aImageKey,
                             const SurfaceKey& aSurfaceKey, bool aMarkUsed);

  /**
   * Looks up the best matching cache entry and returns a drawable reference to
   * its associated surface.
   *
   * The result may vary from the requested cache entry only in terms of size.
   *
   * @param aImageKey       Key data identifying which image the cache entry
   *                        belongs to.
   * @param aSurfaceKey     Key data which uniquely identifies the requested
   *                        cache entry.
   * @return                a LookupResult which will contain a DrawableSurface
   *                        if a cache entry similar to the one the caller
   *                        requested could be found. Callers can use
   *                        LookupResult::IsExactMatch() to check whether the
   *                        returned surface exactly matches @aSurfaceKey.
   */
  static LookupResult LookupBestMatch(const ImageKey aImageKey,
                                      const SurfaceKey& aSurfaceKey,
                                      bool aMarkUsed);

  /**
   * Insert an ISurfaceProvider into the cache. If an entry with the same
   * ImageKey and SurfaceKey is already in the cache, Insert returns
   * FAILURE_ALREADY_PRESENT. If a matching placeholder is already present, it
   * is replaced.
   *
   * Cache entries will never expire as long as they remain locked, but if they
   * become unlocked, they can expire either because the SurfaceCache runs out
   * of capacity or because they've gone too long without being used.  When it
   * is first inserted, a cache entry is locked if its associated image is
   * locked.  When that image is later unlocked, the cache entry becomes
   * unlocked too. To become locked again at that point, two things must happen:
   * the image must become locked again (via LockImage()), and the cache entry
   * must be touched again (via one of the Lookup() functions).
   *
   * All of this means that a very particular procedure has to be followed for
   * cache entries which cannot be rematerialized. First, they must be inserted
   * *after* the image is locked with LockImage(); if you use the other order,
   * the cache entry might expire before LockImage() gets called or before the
   * entry is touched again by Lookup(). Second, the image they are associated
   * with must never be unlocked.
   *
   * If a cache entry cannot be rematerialized, it may be important to know
   * whether it was inserted into the cache successfully. Insert() returns
   * FAILURE if it failed to insert the cache entry, which could happen because
   * of capacity reasons, or because it was already freed by the OS. If the
   * cache entry isn't associated with a locked image, checking for SUCCESS or
   * FAILURE is useless: the entry might expire immediately after being
   * inserted, even though Insert() returned SUCCESS. Thus, many callers do not
   * need to check the result of Insert() at all.
   *
   * @param aProvider    The new cache entry to insert into the cache.
   * @return SUCCESS if the cache entry was inserted successfully. (But see
   *           above for more information about when you should check this.)
   *         FAILURE if the cache entry could not be inserted, e.g. for capacity
   *           reasons. (But see above for more information about when you
   *           should check this.)
   *         FAILURE_ALREADY_PRESENT if an entry with the same ImageKey and
   *           SurfaceKey already exists in the cache.
   */
  static InsertOutcome Insert(NotNull<ISurfaceProvider*> aProvider);

  /**
   * Mark the cache entry @aProvider as having an available surface. This turns
   * a placeholder cache entry into a normal cache entry. The cache entry
   * becomes locked if the associated image is locked; otherwise, it starts in
   * the unlocked state.
   *
   * If the cache entry containing @aProvider has already been evicted from the
   * surface cache, this function has no effect.
   *
   * It's illegal to call this function if @aProvider is not a placeholder; by
   * definition, non-placeholder ISurfaceProviders should have a surface
   * available already.
   *
   * @param aProvider       The cache entry that now has a surface available.
   */
  static void SurfaceAvailable(NotNull<ISurfaceProvider*> aProvider);

  /**
   * Checks if a surface of a given size could possibly be stored in the cache.
   * If CanHold() returns false, Insert() will always fail to insert the
   * surface, but the inverse is not true: Insert() may take more information
   * into account than just image size when deciding whether to cache the
   * surface, so Insert() may still fail even if CanHold() returns true.
   *
   * Use CanHold() to avoid the need to create a temporary surface when we know
   * for sure the cache can't hold it.
   *
   * @param aSize  The dimensions of a surface in pixels.
   * @param aBytesPerPixel  How many bytes each pixel of the surface requires.
   *                        Defaults to 4, which is appropriate for RGBA or RGBX
   *                        images.
   *
   * @return false if the surface cache can't hold a surface of that size.
   */
  static bool CanHold(const IntSize& aSize, uint32_t aBytesPerPixel = 4);
  static bool CanHold(size_t aSize);

  /**
   * Locks an image. Any of the image's cache entries which are either inserted
   * or accessed while the image is locked will not expire.
   *
   * Locking an image does not automatically lock that image's existing cache
   * entries. A call to LockImage() guarantees that entries which are inserted
   * afterward will not expire before the next call to UnlockImage() or
   * UnlockSurfaces() for that image. Cache entries that are accessed via
   * Lookup() or LookupBestMatch() after a LockImage() call will also not expire
   * until the next UnlockImage() or UnlockSurfaces() call for that image. Any
   * other cache entries owned by the image may expire at any time.
   *
   * All of an image's cache entries are removed by RemoveImage(), whether the
   * image is locked or not.
   *
   * It's safe to call LockImage() on an image that's already locked; this has
   * no effect.
   *
   * You must always unlock any image you lock. You may do this explicitly by
   * calling UnlockImage(), or implicitly by calling RemoveImage(). Since you're
   * required to call RemoveImage() when you destroy an image, this doesn't
   * impose any additional requirements, but it's preferable to call
   * UnlockImage() earlier if it's possible.
   *
   * @param aImageKey    The image to lock.
   */
  static void LockImage(const ImageKey aImageKey);

  /**
   * Unlocks an image, allowing any of its cache entries to expire at any time.
   *
   * It's OK to call UnlockImage() on an image that's already unlocked; this has
   * no effect.
   *
   * @param aImageKey    The image to unlock.
   */
  static void UnlockImage(const ImageKey aImageKey);

  /**
   * Unlocks the existing cache entries of an image, allowing them to expire at
   * any time.
   *
   * This does not unlock the image itself, so accessing the cache entries via
   * Lookup() or LookupBestMatch() will lock them again, and prevent them from
   * expiring.
   *
   * This is intended to be used in situations where it's no longer clear that
   * all of the cache entries owned by an image are needed. Calling
   * UnlockSurfaces() and then taking some action that will cause Lookup() to
   * touch any cache entries that are still useful will permit the remaining
   * entries to expire from the cache.
   *
   * If the image is unlocked, this has no effect.
   *
   * @param aImageKey    The image which should have its existing cache entries
   *                     unlocked.
   */
  static void UnlockEntries(const ImageKey aImageKey);

  /**
   * Removes all cache entries (including placeholders) associated with the
   * given image from the cache.  If the image is locked, it is automatically
   * unlocked.
   *
   * This MUST be called, at a minimum, when an Image which could be storing
   * entries in the surface cache is destroyed. If another image were allocated
   * at the same address it could result in subtle, difficult-to-reproduce bugs.
   *
   * @param aImageKey  The image which should be removed from the cache.
   */
  static void RemoveImage(const ImageKey aImageKey);

  /**
   * Attempts to remove cache entries (including placeholders) associated with
   * the given image from the cache, assuming there is an equivalent entry that
   * it is able substitute that entry with. Note that this only applies if the
   * image is in factor of 2 mode. If it is not, this operation does nothing.
   *
   * @param aImageKey  The image whose cache which should be pruned.
   */
  static void PruneImage(const ImageKey aImageKey);

  /**
   * Removes all rasterized cache entries (including placeholders) associated
   * with the given image from the cache and marks their surface providers as
   * dirty and should not be drawn again. Any blob recordings are left in th
   * cache but marked as dirty and must be regenerated.
   *
   * @param aImageKey  The image whose cache which should be regenerated.
   *
   * @returns true if any surface providers were present in the cache, else
   * false.
   */
  static bool InvalidateImage(const ImageKey aImageKey);

  /**
   * Evicts all evictable entries from the cache.
   *
   * All entries are evictable except for entries associated with locked images.
   * Non-evictable entries can only be removed by RemoveImage().
   */
  static void DiscardAll();

  /**
   * Calls Reset on the ISurfaceProvider (which is currently only implemented
   * for AnimationSurfaceProvider). This is needed because we need to call Reset
   * on AnimationSurfaceProvider while they are in placeholder status and there
   * is no way to access a surface cache entry from outside of the surface cache
   * when it's in placeholder status.
   */
  static void ResetAnimation(const ImageKey aImageKey,
                             const SurfaceKey& aSurfaceKey);

  /**
   * Collects an accounting of the surfaces contained in the SurfaceCache for
   * the given image, along with their size and various other metadata.
   *
   * This is intended for use with memory reporting.
   *
   * @param aImageKey     The image to report memory usage for.
   * @param aCounters     An array into which the report for each surface will
   *                      be written.
   * @param aMallocSizeOf A fallback malloc memory reporting function.
   */
  static void CollectSizeOfSurfaces(const ImageKey aImageKey,
                                    nsTArray<SurfaceMemoryCounter>& aCounters,
                                    MallocSizeOf aMallocSizeOf);

  /**
   * @return maximum capacity of the SurfaceCache in bytes. This is only exposed
   * for use by tests; normal code should use CanHold() instead.
   */
  static size_t MaximumCapacity();

  /**
   * @return true if the given size is valid.
   */
  static bool IsLegalSize(const IntSize& aSize);

  /**
   * @return clamped size for the given vector image size to rasterize at.
   */
  static IntSize ClampVectorSize(const IntSize& aSize);

  /**
   * @return clamped size for the given image and size to rasterize at.
   */
  static IntSize ClampSize(const ImageKey aImageKey, const IntSize& aSize);

  /**
   * Release image on main thread.
   * The function uses SurfaceCache to release pending releasing images quickly.
   */
  static void ReleaseImageOnMainThread(already_AddRefed<image::Image> aImage,
                                       bool aAlwaysProxy = false);

  /**
   * Clear all pending releasing images.
   */
  static void ClearReleasingImages();

private:
  virtual ~SurfaceCache() = 0;  // Forbid instantiation.
};

}  // namespace image
}  // namespace mozilla

#endif  // mozilla_image_SurfaceCache_h

quality100%

¤ Dauer der Verarbeitung: 0.17 Sekunden (vorverarbeitet) ¤

Wurzel

Suchen

Beweissystem der NASA

Beweissystem Isabelle

NIST Cobol Testsuite

Cephes Mathematical Library

Wiener Entwicklungsmethode

Haftungshinweis

Die Informationen auf dieser Webseite wurden nach bestem Wissen sorgfältig zusammengestellt. Es wird jedoch weder Vollständigkeit, noch Richtigkeit, noch Qualität der bereit gestellten Informationen zugesichert.

Bemerkung:

Die farbliche Syntaxdarstellung ist noch experimentell.