Source code
Revision control
Copy as Markdown
Other Tools
/* -*- 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
#ifndef mozilla_image_AnimationFrameBuffer_h
#define mozilla_image_AnimationFrameBuffer_h
#include "ISurfaceProvider.h"
#include <deque>
namespace mozilla {
namespace image {
/**
* An AnimationFrameBuffer owns the frames outputted by an animated image
* decoder as well as directing its owner on how to drive the decoder,
* whether to produce more or to stop.
*
* This should be subclassed by the different types of queues, depending on
* what behaviour is desired.
*/
class AnimationFrameBuffer {
public:
enum class InsertStatus : uint8_t {
YIELD, // No more frames required at this time.
CONTINUE, // Continue decoding more frames.
DISCARD_YIELD, // Crossed threshold, switch to discarding structure
// and stop decoding more frames.
DISCARD_CONTINUE // Crossed threshold, switch to discarding structure
// and continue decoding more frames.
};
/**
* @param aBatch Number of frames we request to be decoded each time it
* decides we need more.
*
* @param aStartFrame The starting frame for the animation. The frame buffer
* will auto-advance (and thus keep the decoding pipeline
* going) until it has reached this frame. Useful when the
* animation was progressing, but the surface was
* discarded, and we had to redecode.
*/
AnimationFrameBuffer(size_t aBatch, size_t aStartFrame)
: mSize(0),
mBatch(aBatch),
mGetIndex(0),
mAdvance(aStartFrame),
mPending(0),
mSizeKnown(false),
mMayDiscard(false),
mRedecodeError(false),
mRecycling(false) {
if (mBatch > SIZE_MAX / 4) {
// Batch size is so big, we will just end up decoding the whole animation.
mBatch = SIZE_MAX / 4;
} else if (mBatch < 1) {
// Never permit a batch size smaller than 1. We always want to be asking
// for at least one frame to start.
mBatch = 1;
}
}
AnimationFrameBuffer(const AnimationFrameBuffer& aOther)
: mSize(aOther.mSize),
mBatch(aOther.mBatch),
mGetIndex(aOther.mGetIndex),
mAdvance(aOther.mAdvance),
mPending(aOther.mPending),
mSizeKnown(aOther.mSizeKnown),
mMayDiscard(aOther.mMayDiscard),
mRedecodeError(aOther.mRedecodeError),
mRecycling(aOther.mRecycling) {}
virtual ~AnimationFrameBuffer() {}
/**
* @returns True if frames post-advance may be discarded and redecoded on
* demand, else false.
*/
bool MayDiscard() const { return mMayDiscard; }
/**
* @returns True if frames post-advance may be reused after displaying, else
* false. Implies MayDiscard().
*/
bool IsRecycling() const {
MOZ_ASSERT_IF(mRecycling, mMayDiscard);
return mRecycling;
}
/**
* @returns True if the frame buffer was ever marked as complete. This implies
* that the total number of frames is known and may be gotten from
* Frames().Length().
*/
bool SizeKnown() const { return mSizeKnown; }
/**
* @returns The total number of frames in the animation. If SizeKnown() is
* true, then this is a constant, else it is just the total number of
* frames we have decoded thus far.
*/
size_t Size() const { return mSize; }
/**
* @returns The first frame refresh area. This is used instead of the dirty
* rect for the last frame when transitioning back to the first frame.
*/
const gfx::IntRect& FirstFrameRefreshArea() const {
return mFirstFrameRefreshArea;
}
/**
* @returns True if encountered an error during redecode which should cause
* the caller to stop inserting frames.
*/
bool HasRedecodeError() const { return mRedecodeError; }
/**
* @returns The current frame index we have advanced to.
*/
size_t Displayed() const { return mGetIndex; }
/**
* @returns Outstanding frames desired from the decoder.
*/
size_t PendingDecode() const { return mPending; }
/**
* @returns Outstanding frames to advance internally.
*/
size_t PendingAdvance() const { return mAdvance; }
/**
* @returns Number of frames we request to be decoded each time it decides we
* need more.
*/
size_t Batch() const { return mBatch; }
/**
* Resets the currently displayed frame of the frame buffer to the beginning.
*
* @returns True if the caller should restart the decoder.
*/
bool Reset() {
mGetIndex = 0;
mAdvance = 0;
return ResetInternal();
}
/**
* Advance the currently displayed frame of the frame buffer. If it reaches
* the end, it will loop back to the beginning. It should not be called unless
* a call to Get has returned a valid frame for the next frame index.
*
* As we advance, the number of frames we have buffered ahead of the current
* will shrink. Once that becomes too few, we will request a batch-sized set
* of frames to be decoded from the decoder.
*
* @param aExpectedFrame The frame we expect to have advanced to. This is
* used for confirmation purposes (e.g. asserts).
*
* @returns True if the caller should restart the decoder.
*/
bool AdvanceTo(size_t aExpectedFrame) {
MOZ_ASSERT(mAdvance == 0);
if (++mGetIndex == mSize && mSizeKnown) {
mGetIndex = 0;
}
MOZ_ASSERT(mGetIndex == aExpectedFrame);
bool hasPending = mPending > 0;
AdvanceInternal();
// Restart the decoder if we transitioned from no pending frames being
// decoded, to some pending frames to be decoded.
return !hasPending && mPending > 0;
}
/**
* Inserts a frame into the frame buffer.
*
* Once we have a sufficient number of frames buffered relative to the
* currently displayed frame, it will return YIELD to indicate the caller
* should stop decoding. Otherwise it will return CONTINUE.
*
* If we cross the threshold, it will return DISCARD_YIELD or DISCARD_CONTINUE
* to indicate that the caller should switch to a new queue type.
*
* @param aFrame The frame to insert into the buffer.
*
* @returns True if the decoder should decode another frame.
*/
InsertStatus Insert(RefPtr<imgFrame>&& aFrame) {
MOZ_ASSERT(mPending > 0);
MOZ_ASSERT(aFrame);
--mPending;
bool retain = InsertInternal(std::move(aFrame));
if (mAdvance > 0 && mSize > 1) {
--mAdvance;
++mGetIndex;
AdvanceInternal();
}
if (!retain) {
return mPending > 0 ? InsertStatus::DISCARD_CONTINUE
: InsertStatus::DISCARD_YIELD;
}
return mPending > 0 ? InsertStatus::CONTINUE : InsertStatus::YIELD;
}
/**
* Access a specific frame from the frame buffer. It should generally access
* frames in sequential order, increasing in tandem with AdvanceTo calls. The
* first frame may be accessed at any time. The access order should start with
* the same value as that given in Initialize (aStartFrame).
*
* @param aFrame The frame index to access.
*
* @returns The frame, if available.
*/
virtual imgFrame* Get(size_t aFrame, bool aForDisplay) = 0;
/**
* @returns True if the first frame of the animation (not of the queue) is
* available/finished, else false.
*/
virtual bool IsFirstFrameFinished() const = 0;
/**
* @returns True if the last inserted frame matches the given frame, else
* false.
*/
virtual bool IsLastInsertedFrame(imgFrame* aFrame) const = 0;
/**
* This should be called after the last frame has been inserted. If the buffer
* is discarding old frames, it may request more frames to be decoded. In this
* case that means the decoder should start again from the beginning. This
* return value should be used in preference to that of the Insert call.
*
* @returns True if the decoder should decode another frame.
*/
virtual bool MarkComplete(const gfx::IntRect& aFirstFrameRefreshArea) = 0;
typedef ISurfaceProvider::AddSizeOfCbData AddSizeOfCbData;
typedef ISurfaceProvider::AddSizeOfCb AddSizeOfCb;
/**
* Accumulate the total cost of all the frames in the buffer.
*/
virtual void AddSizeOfExcludingThis(MallocSizeOf aMallocSizeOf,
const AddSizeOfCb& aCallback) = 0;
/**
* Request a recycled frame buffer, and if available, set aRecycleRect to be
* the dirty rect between the contents of the recycled frame, and the restore
* frame (e.g. what we composite on top of) for the next frame to be created.
*
* @returns The frame to be recycled, if available.
*/
virtual RawAccessFrameRef RecycleFrame(gfx::IntRect& aRecycleRect) {
MOZ_ASSERT(!mRecycling);
return RawAccessFrameRef();
}
protected:
/**
* Perform the actual insertion of the given frame into the underlying buffer
* representation. mGetIndex shall be the index of the frame we are inserting,
* and mSize and mPending have already been adjusted as needed.
*
* @returns True if the caller should continue as normal, false if the discard
* threshold was crossed and we should change queue types.
*/
virtual bool InsertInternal(RefPtr<imgFrame>&& aFrame) = 0;
/**
* Advance from the current frame to the immediately adjacent next frame.
* mGetIndex shall be the the index of the new current frame after advancing.
* mPending may be adjusted to request more frames.
*/
virtual void AdvanceInternal() = 0;
/**
* Discard any frames as necessary for the reset. mPending may be adjusted to
* request more frames.
*
* @returns True if the caller should resume decoding new frames, else false.
*/
virtual bool ResetInternal() = 0;
/// The first frame refresh area. This is used instead of the dirty rect for
/// the last frame when transitioning back to the first frame.
gfx::IntRect mFirstFrameRefreshArea;
// The total number of frames in the animation. If mSizeKnown is true, it is
// the actual total regardless of how many frames are available, otherwise it
// is the total number of inserted frames.
size_t mSize;
// The minimum number of frames that we want buffered ahead of the display.
size_t mBatch;
// The sequential index of the frame we have advanced to.
size_t mGetIndex;
// The number of frames we need to auto-advance to synchronize with the
// caller.
size_t mAdvance;
// The number of frames to decode before we stop.
size_t mPending;
// True if the total number of frames for the animation is known.
bool mSizeKnown;
// True if this buffer may discard frames.
bool mMayDiscard;
// True if we encountered an error while redecoding.
bool mRedecodeError;
// True if this buffer is recycling frames.
bool mRecycling;
};
/**
* An AnimationFrameRetainedBuffer will retain all of the frames inserted into
* it. Once it crosses its maximum number of frames, it will recommend
* conversion to a discarding queue.
*/
class AnimationFrameRetainedBuffer final : public AnimationFrameBuffer {
public:
/**
* @param aThreshold Maximum number of frames that may be stored in the frame
* buffer before it may discard already displayed frames.
* Once exceeded, it will discard the previous frame to the
* current frame whenever Advance is called. It always
* retains the first frame.
*
* @param aBatch See AnimationFrameBuffer::AnimationFrameBuffer.
*
* @param aStartFrame See AnimationFrameBuffer::AnimationFrameBuffer.
*/
AnimationFrameRetainedBuffer(size_t aThreshold, size_t aBatch,
size_t aCurrentFrame);
/**
* @returns Maximum number of frames before we start discarding previous
* frames post-advance.
*/
size_t Threshold() const { return mThreshold; }
/**
* @returns The frames of this animation, in order. Each element will always
* contain a valid frame.
*/
const nsTArray<RefPtr<imgFrame>>& Frames() const { return mFrames; }
imgFrame* Get(size_t aFrame, bool aForDisplay) override;
bool IsFirstFrameFinished() const override;
bool IsLastInsertedFrame(imgFrame* aFrame) const override;
bool MarkComplete(const gfx::IntRect& aFirstFrameRefreshArea) override;
void AddSizeOfExcludingThis(MallocSizeOf aMallocSizeOf,
const AddSizeOfCb& aCallback) override;
private:
friend class AnimationFrameDiscardingQueue;
friend class AnimationFrameRecyclingQueue;
bool InsertInternal(RefPtr<imgFrame>&& aFrame) override;
void AdvanceInternal() override;
bool ResetInternal() override;
// The frames of this animation, in order.
nsTArray<RefPtr<imgFrame>> mFrames;
// The maximum number of frames we can have before discarding.
size_t mThreshold;
};
/**
* An AnimationFrameDiscardingQueue will only retain up to mBatch * 2 frames.
* When the animation advances, it will discard the old current frame.
*/
class AnimationFrameDiscardingQueue : public AnimationFrameBuffer {
public:
explicit AnimationFrameDiscardingQueue(AnimationFrameRetainedBuffer&& aQueue);
imgFrame* Get(size_t aFrame, bool aForDisplay) final;
bool IsFirstFrameFinished() const final;
bool IsLastInsertedFrame(imgFrame* aFrame) const final;
bool MarkComplete(const gfx::IntRect& aFirstFrameRefreshArea) override;
void AddSizeOfExcludingThis(MallocSizeOf aMallocSizeOf,
const AddSizeOfCb& aCallback) override;
const std::deque<RefPtr<imgFrame>>& Display() const { return mDisplay; }
const imgFrame* FirstFrame() const { return mFirstFrame; }
size_t PendingInsert() const { return mInsertIndex; }
protected:
bool InsertInternal(RefPtr<imgFrame>&& aFrame) override;
void AdvanceInternal() override;
bool ResetInternal() override;
/// The sequential index of the frame we inserting next.
size_t mInsertIndex;
/// Queue storing frames to be displayed by the animator. The first frame in
/// the queue is the currently displayed frame.
std::deque<RefPtr<imgFrame>> mDisplay;
/// The first frame which is never discarded, and preferentially reused.
RefPtr<imgFrame> mFirstFrame;
};
/**
* An AnimationFrameRecyclingQueue will only retain up to mBatch * 2 frames.
* When the animation advances, it will place the old current frame into a
* recycling queue to be reused for a future allocation. This only works for
* animated images where we decoded full sized frames into their own buffers,
* so that the buffers are all identically sized and contain the complete frame
* data.
*/
class AnimationFrameRecyclingQueue final
: public AnimationFrameDiscardingQueue {
public:
explicit AnimationFrameRecyclingQueue(AnimationFrameRetainedBuffer&& aQueue);
void AddSizeOfExcludingThis(MallocSizeOf aMallocSizeOf,
const AddSizeOfCb& aCallback) override;
RawAccessFrameRef RecycleFrame(gfx::IntRect& aRecycleRect) override;
struct RecycleEntry {
explicit RecycleEntry(const gfx::IntRect& aDirtyRect)
: mDirtyRect(aDirtyRect) {}
RecycleEntry(RecycleEntry&& aOther)
: mFrame(std::move(aOther.mFrame)), mDirtyRect(aOther.mDirtyRect) {}
RecycleEntry& operator=(RecycleEntry&& aOther) {
mFrame = std::move(aOther.mFrame);
mDirtyRect = aOther.mDirtyRect;
return *this;
}
RecycleEntry(const RecycleEntry& aOther) = delete;
RecycleEntry& operator=(const RecycleEntry& aOther) = delete;
RefPtr<imgFrame> mFrame; // The frame containing the buffer to recycle.
gfx::IntRect mDirtyRect; // The dirty rect of the frame itself.
};
const std::deque<RecycleEntry>& Recycle() const { return mRecycle; }
protected:
void AdvanceInternal() override;
bool ResetInternal() override;
/// Queue storing frames to be recycled by the decoder to produce its future
/// frames. May contain up to mBatch frames, where the last frame in the queue
/// is adjacent to the first frame in the mDisplay queue.
std::deque<RecycleEntry> mRecycle;
/// Force recycled frames to use the first frame refresh area as their dirty
/// rect. This is used when we are recycling frames from the end of an
/// animation to produce frames at the beginning of an animation.
bool mForceUseFirstFrameRefreshArea;
};
} // namespace image
} // namespace mozilla
#endif // mozilla_image_AnimationFrameBuffer_h