Bug 523950 - Part 7. Add AnimatedFrameBuffer to manage storage and decoding of frames in an animation. r=tnikkel
authorAndrew Osmond <aosmond@mozilla.com>
Wed, 28 Feb 2018 13:34:52 -0500
changeset 458239 209a5b6b89b9f3f97c383203417809a862d156cd
parent 458238 e96c578f2a9e45e702d472bd735d3afd0036d8ed
child 458240 8170b0d61fc800d62f7662d87d4ac2edbe47ad46
push id8799
push usermtabara@mozilla.com
push dateThu, 01 Mar 2018 16:46:23 +0000
treeherdermozilla-beta@15334014dc67 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewerstnikkel
bugs523950
milestone60.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 523950 - Part 7. Add AnimatedFrameBuffer to manage storage and decoding of frames in an animation. r=tnikkel
image/AnimationFrameBuffer.cpp
image/AnimationFrameBuffer.h
image/moz.build
new file mode 100644
--- /dev/null
+++ b/image/AnimationFrameBuffer.cpp
@@ -0,0 +1,292 @@
+/* -*- 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/. */
+
+#include "AnimationFrameBuffer.h"
+#include "mozilla/Move.h"             // for Move
+
+namespace mozilla {
+namespace image {
+
+AnimationFrameBuffer::AnimationFrameBuffer()
+  : mThreshold(0)
+  , mBatch(0)
+  , mPending(0)
+  , mAdvance(0)
+  , mInsertIndex(0)
+  , mGetIndex(0)
+  , mSizeKnown(false)
+{ }
+
+void
+AnimationFrameBuffer::Initialize(size_t aThreshold,
+                                 size_t aBatch,
+                                 size_t aStartFrame)
+{
+  MOZ_ASSERT(mThreshold == 0);
+  MOZ_ASSERT(mBatch == 0);
+  MOZ_ASSERT(mPending == 0);
+  MOZ_ASSERT(mAdvance == 0);
+  MOZ_ASSERT(mFrames.IsEmpty());
+
+  mThreshold = aThreshold;
+  mBatch = aBatch;
+  mAdvance = aStartFrame;
+
+  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;
+  }
+
+  // To simplify the code, we have the assumption that the threshold for
+  // entering discard-after-display mode is at least twice the batch size (since
+  // that is the most frames-pending-decode we will request) + 1 for the current
+  // frame. That way the redecoded frames being inserted will never risk
+  // overlapping the frames we will discard due to the animation progressing.
+  // That may cause us to use a little more memory than we want but that is an
+  // acceptable tradeoff for simplicity.
+  size_t minThreshold = 2 * mBatch + 1;
+  if (mThreshold < minThreshold) {
+    mThreshold = minThreshold;
+  }
+
+  // The maximum number of frames we should ever have decoded at one time is
+  // twice the batch. That is a good as number as any to start our decoding at.
+  mPending = mBatch * 2;
+}
+
+bool
+AnimationFrameBuffer::Insert(RawAccessFrameRef&& aFrame)
+{
+  // We should only insert new frames if we actually asked for them.
+  MOZ_ASSERT(mPending > 0);
+
+  if (mSizeKnown) {
+    // We only insert after the size is known if we are repeating the animation
+    // and we did not keep all of the frames. Replace whatever is there
+    // (probably an empty frame) with the new frame.
+    MOZ_ASSERT(MayDiscard());
+    MOZ_ASSERT(mInsertIndex < mFrames.Length());
+
+    if (mInsertIndex > 0) {
+      MOZ_ASSERT(!mFrames[mInsertIndex]);
+      mFrames[mInsertIndex] = Move(aFrame);
+    }
+  } else {
+    if (mInsertIndex == mFrames.Length()) {
+      // We are still on the first pass of the animation decoding, so this is
+      // the first time we have seen this frame.
+      mFrames.AppendElement(Move(aFrame));
+    } else if (mInsertIndex > 0) {
+      // We were forced to restart an animation before we decoded the last
+      // frame. Thus we might need to insert, even on a "first pass."
+      MOZ_ASSERT(mInsertIndex < mFrames.Length());
+      MOZ_ASSERT(!mFrames[mInsertIndex]);
+      mFrames[mInsertIndex] = Move(aFrame);
+    }
+
+    if (mInsertIndex == mThreshold) {
+      // We just tripped over the threshold, and on the first pass of the
+      // decoding; this is our chance to do any clearing of already displayed
+      // frames. After this, we only need to release as we advance.
+      MOZ_ASSERT(MayDiscard());
+      MOZ_ASSERT(mGetIndex < mInsertIndex);
+      for (size_t i = 1; i < mGetIndex; ++i) {
+        RawAccessFrameRef discard = Move(mFrames[i]);
+      }
+    }
+  }
+
+  MOZ_ASSERT(mFrames[mInsertIndex]);
+  ++mInsertIndex;
+
+  // Ensure we only request more decoded frames if we actually need them. If we
+  // need to advance to a certain point in the animation on behalf of the owner,
+  // then do so. This ensures we keep decoding. If the batch size is really
+  // small (i.e. 1), it is possible advancing will request the decoder to
+  // "restart", but we haven't told it to stop yet. Note that we skip the first
+  // insert because we actually start "advanced" to the first frame anyways.
+  bool continueDecoding = --mPending > 0;
+  if (mAdvance > 0 && mInsertIndex > 1) {
+    continueDecoding |= AdvanceInternal();
+    --mAdvance;
+  }
+  return continueDecoding;
+}
+
+bool
+AnimationFrameBuffer::MarkComplete()
+{
+  // We reached the end of the animation, the next frame we get, if we get
+  // another, will be the first frame again.
+  MOZ_ASSERT(mInsertIndex == mFrames.Length());
+  mInsertIndex = 0;
+
+  // Since we only request advancing when we want to resume at a certain point
+  // in the animation, we should never exceed the number of frames.
+  MOZ_ASSERT(mAdvance == 0);
+
+  if (!mSizeKnown) {
+    // We just received the last frame in the animation. Compact the frame array
+    // because we know we won't need to grow beyond here.
+    mSizeKnown = true;
+    mFrames.Compact();
+
+    if (!MayDiscard()) {
+      // If we did not meet the threshold, then we know we want to keep all of the
+      // frames. If we also hit the last frame, we don't want to ask for more.
+      mPending = 0;
+    }
+  }
+
+  return mPending > 0;
+}
+
+DrawableFrameRef
+AnimationFrameBuffer::Get(size_t aFrame)
+{
+  // We should not have asked for a frame if we never inserted.
+  if (mFrames.IsEmpty()) {
+    MOZ_ASSERT_UNREACHABLE("Calling Get() when we have no frames");
+    return DrawableFrameRef();
+  }
+
+  // If we don't have that frame, return an empty frame ref.
+  if (aFrame >= mFrames.Length()) {
+    return DrawableFrameRef();
+  }
+
+  // We've got the requested frame because we are not discarding frames. While
+  // we typically should have not run out of frames since we ask for more before
+  // we want them, it is possible the decoder is behind.
+  if (!mFrames[aFrame]) {
+    MOZ_ASSERT(MayDiscard());
+    return DrawableFrameRef();
+  }
+
+  // If we are advancing on behalf of the animation, we don't expect it to be
+  // getting any frames (besides the first) until we get the desired frame.
+  MOZ_ASSERT(aFrame == 0 || mAdvance == 0);
+  return mFrames[aFrame]->DrawableRef();
+}
+
+bool
+AnimationFrameBuffer::AdvanceTo(size_t aExpectedFrame)
+{
+  // The owner should only be advancing once it has reached the requested frame
+  // in the animation.
+  MOZ_ASSERT(mAdvance == 0);
+  bool restartDecoder = AdvanceInternal();
+  // Advancing should always be successful, as it should only happen after the
+  // owner has accessed the next (now current) frame.
+  MOZ_ASSERT(mGetIndex == aExpectedFrame);
+  return restartDecoder;
+}
+
+bool
+AnimationFrameBuffer::AdvanceInternal()
+{
+  // We should not have advanced if we never inserted.
+  if (mFrames.IsEmpty()) {
+    MOZ_ASSERT_UNREACHABLE("Calling Advance() when we have no frames");
+    return false;
+  }
+
+  // We only want to change the current frame index if we have advanced. This
+  // means either a higher frame index, or going back to the beginning.
+  size_t framesLength = mFrames.Length();
+  // We should never have advanced beyond the frame buffer.
+  MOZ_ASSERT(mGetIndex < framesLength);
+  // We should never advance if the current frame is null -- it needs to know
+  // the timeout from it at least to know when to advance.
+  MOZ_ASSERT(mFrames[mGetIndex]);
+  if (++mGetIndex == framesLength) {
+    MOZ_ASSERT(mSizeKnown);
+    mGetIndex = 0;
+  }
+  // The owner should have already accessed the next frame, so it should also
+  // be available.
+  MOZ_ASSERT(mFrames[mGetIndex]);
+
+  // If we moved forward, that means we can remove the previous frame, assuming
+  // that frame is not the first frame. If we looped and are back at the first
+  // frame, we can remove the last frame.
+  if (MayDiscard()) {
+    RawAccessFrameRef discard;
+    if (mGetIndex > 1) {
+      discard = Move(mFrames[mGetIndex - 1]);
+    } else if (mGetIndex == 0) {
+      MOZ_ASSERT(mSizeKnown && framesLength > 1);
+      discard = Move(mFrames[framesLength - 1]);
+    }
+  }
+
+  if (!mSizeKnown || MayDiscard()) {
+    // Calculate how many frames we have requested ahead of the current frame.
+    size_t buffered = mPending;
+    if (mGetIndex > mInsertIndex) {
+      // It wrapped around and we are decoding the beginning again before the
+      // the display has finished the loop.
+      MOZ_ASSERT(mSizeKnown);
+      buffered += mInsertIndex + framesLength - mGetIndex - 1;
+    } else {
+      buffered += mInsertIndex - mGetIndex - 1;
+    }
+
+    if (buffered < mBatch) {
+      // If we have fewer frames than the batch size, then ask for more. If we
+      // do not have any pending, then we know that there is no active decoding.
+      mPending += mBatch;
+      return mPending == mBatch;
+    }
+  }
+
+  return false;
+}
+
+bool
+AnimationFrameBuffer::Reset()
+{
+  // The animation needs to start back at the beginning.
+  mGetIndex = 0;
+  mAdvance = 0;
+
+  if (!MayDiscard()) {
+    // If we haven't crossed the threshold, then we know by definition we have
+    // not discarded any frames. If we previously requested more frames, but
+    // it would have been more than we would have buffered otherwise, we can
+    // stop the decoding after one more frame.
+    if (mPending > 1 && mInsertIndex - 1 >= mBatch * 2) {
+      MOZ_ASSERT(!mSizeKnown);
+      mPending = 1;
+    }
+
+    // Either the decoder is still running, or we have enough frames already.
+    // No need for us to restart it.
+    return false;
+  }
+
+  // If we are over the threshold, then we know we will have missing frames in
+  // our buffer. The easiest thing to do is to drop everything but the first
+  // frame and go back to the initial state.
+  bool restartDecoder = mPending == 0;
+  mInsertIndex = 0;
+  mPending = 2 * mBatch;
+
+  // Discard all frames besides the first, because the decoder always expects
+  // that when it re-inserts a frame, it is not present. (It doesn't re-insert
+  // the first frame.)
+  for (size_t i = 1; i < mFrames.Length(); ++i) {
+    RawAccessFrameRef discard = Move(mFrames[i]);
+  }
+
+  return restartDecoder;
+}
+
+} // namespace image
+} // namespace mozilla
new file mode 100644
--- /dev/null
+++ b/image/AnimationFrameBuffer.h
@@ -0,0 +1,195 @@
+/* -*- 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/. */
+
+#ifndef mozilla_image_AnimationFrameBuffer_h
+#define mozilla_image_AnimationFrameBuffer_h
+
+#include "ISurfaceProvider.h"
+
+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.
+ *
+ * Based upon its given configuration parameters, it will retain up to a
+ * certain number of frames in the buffer before deciding to discard previous
+ * frames, and relying upon the decoder to recreate older frames when the
+ * animation loops. It will also request that the decoder stop producing more
+ * frames when the display of the frames are far behind -- this allows other
+ * tasks and images which require decoding to take execution priority.
+ *
+ * The desire is that smaller animated images should be kept completely in
+ * memory while larger animated images should only keep a certain number of
+ * frames to minimize our memory footprint at the cost of CPU.
+ */
+class AnimationFrameBuffer final
+{
+public:
+  AnimationFrameBuffer();
+
+  /**
+   * Configure the frame buffer with a particular threshold and batch size. Note
+   * that the frame buffer may adjust the given values.
+   *
+   * @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      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.
+   */
+  void Initialize(size_t aThreshold, size_t aBatch, size_t aStartFrame);
+
+  /**
+   * 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.
+   */
+  DrawableFrameRef Get(size_t aFrame);
+
+  /**
+   * Inserts a frame into the frame buffer. If it has yet to fully decode the
+   * animated image yet, then it will append the frame to its internal buffer.
+   * If it has been fully decoded, it will replace the next frame in its buffer
+   * with the given frame.
+   *
+   * Once we have a sufficient number of frames buffered relative to the
+   * currently displayed frame, it will return false to indicate the caller
+   * should stop decoding.
+   *
+   * @param aFrame      The frame to insert into the buffer.
+   *
+   * @returns True if the decoder should decode another frame.
+   */
+  bool Insert(RawAccessFrameRef&& aFrame);
+
+  /**
+   * 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.
+   */
+  bool MarkComplete();
+
+  /**
+   * 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);
+
+  /**
+   * Resets the currently displayed frame of the frame buffer to the beginning.
+   * If the buffer is discarding old frames, it will actually discard all frames
+   * besides the first.
+   *
+   * @returns True if the caller should restart the decoder.
+   */
+  bool Reset();
+
+  /**
+   * @returns True if frames post-advance may be discarded and redecoded on
+   *          demand, else false.
+   */
+  bool MayDiscard() const { return mFrames.Length() > mThreshold; }
+
+  /**
+   * @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 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; }
+
+  /**
+   * @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. May contain empty indices.
+   */
+  const nsTArray<RawAccessFrameRef>& Frames() const { return mFrames; }
+
+private:
+  bool AdvanceInternal();
+
+  /// The frames of this animation, in order, but may have holes if discarding.
+  nsTArray<RawAccessFrameRef> mFrames;
+
+  // The maximum number of frames we can have before discarding.
+  size_t mThreshold;
+
+  // The minimum number of frames that we want buffered ahead of the display.
+  size_t mBatch;
+
+  // The number of frames to decode before we stop.
+  size_t mPending;
+
+  // The number of frames we need to auto-advance to synchronize with the caller.
+  size_t mAdvance;
+
+  // The mFrames index in which to insert the next decoded frame.
+  size_t mInsertIndex;
+
+  // The mFrames index that we have advanced to.
+  size_t mGetIndex;
+
+  // True if the total number of frames is known.
+  bool mSizeKnown;
+};
+
+} // namespace image
+} // namespace mozilla
+
+#endif // mozilla_image_AnimationFrameBuffer_h
--- a/image/moz.build
+++ b/image/moz.build
@@ -49,16 +49,17 @@ EXPORTS += [
     'imgRequest.h',
     'imgRequestProxy.h',
     'IProgressObserver.h',
     'Orientation.h',
     'SurfaceCacheUtils.h',
 ]
 
 UNIFIED_SOURCES += [
+    'AnimationFrameBuffer.cpp',
     'AnimationSurfaceProvider.cpp',
     'ClippedImage.cpp',
     'DecodedSurfaceProvider.cpp',
     'DecodePool.cpp',
     'Decoder.cpp',
     'DecoderFactory.cpp',
     'DynamicImage.cpp',
     'FrameAnimator.cpp',