tor-browser

SurfacePipe.h (33095B)

---

/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* vim: set ts=8 sts=2 et sw=2 tw=80: */
/* 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/. */

/**
* A SurfacePipe is a pipeline that consists of a series of SurfaceFilters
* terminating in a SurfaceSink. Each SurfaceFilter transforms the image data in
* some way before the SurfaceSink ultimately writes it to the surface. This
* design allows for each transformation to be tested independently, for the
* transformations to be combined as needed to meet the needs of different
* situations, and for all image decoders to share the same code for these
* transformations.
*
* Writing to the SurfacePipe is done using lambdas that act as generator
* functions. Because the SurfacePipe machinery controls where the writes take
* place, a bug in an image decoder cannot cause a buffer overflow of the
* underlying surface.
*/

#ifndef mozilla_image_SurfacePipe_h
#define mozilla_image_SurfacePipe_h

#include <stdint.h>

#include <utility>

#include "AnimationParams.h"
#include "mozilla/Likely.h"
#include "mozilla/Maybe.h"

#include "mozilla/UniquePtr.h"
#include "mozilla/Variant.h"
#include "mozilla/gfx/2D.h"
#include "mozilla/gfx/Swizzle.h"
#include "nsDebug.h"
#include "Orientation.h"

namespace mozilla {
namespace image {

class Decoder;

/**
* An invalid rect for a surface. Results are given both in the space of the
* input image (i.e., before any SurfaceFilters are applied) and in the space
* of the output surface (after all SurfaceFilters).
*/
struct SurfaceInvalidRect {
 OrientedIntRect
     mInputSpaceRect;  /// The invalid rect in pre-SurfacePipe space.
 OrientedIntRect
     mOutputSpaceRect;  /// The invalid rect in post-SurfacePipe space.
};

/**
* An enum used to allow the lambdas passed to WritePixels() to communicate
* their state to the caller.
*/
enum class WriteState : uint8_t {
 NEED_MORE_DATA,  /// The lambda ran out of data.

 FINISHED,  /// The lambda is done writing to the surface; future writes
            /// will fail.

 FAILURE  /// The lambda encountered an error. The caller may recover
          /// if possible and continue to write. (This never indicates
          /// an error in the SurfacePipe machinery itself; it's only
          /// generated by the lambdas.)
};

/**
* A template alias used to make the return value of WritePixels() lambdas
* (which may return either a pixel value or a WriteState) easier to specify.
*/
template <typename PixelType>
using NextPixel = Variant<PixelType, WriteState>;

/**
* SurfaceFilter is the abstract superclass of SurfacePipe pipeline stages.  It
* implements the the code that actually writes to the surface - WritePixels()
* and the other Write*() methods - which are non-virtual for efficiency.
*
* SurfaceFilter's API is nonpublic; only SurfacePipe and other SurfaceFilters
* should use it. Non-SurfacePipe code should use the methods on SurfacePipe.
*
* To implement a SurfaceFilter, it's necessary to subclass SurfaceFilter and
* implement, at a minimum, the pure virtual methods. It's also necessary to
* define a Config struct with a Filter typedef member that identifies the
* matching SurfaceFilter class, and a Configure() template method. See an
* existing SurfaceFilter subclass, such as RemoveFrameRectFilter, for an
* example of how the Configure() method must be implemented. It takes a list of
* Config structs, passes the tail of the list to the next filter in the chain's
* Configure() method, and then uses the head of the list to configure itself. A
* SurfaceFilter's Configure() method must also call
* SurfaceFilter::ConfigureFilter() to provide the Write*() methods with the
* information they need to do their jobs.
*/
class SurfaceFilter {
public:
 SurfaceFilter() : mRowPointer(nullptr), mCol(0), mPixelSize(0) {}

 virtual ~SurfaceFilter() {}

 /**
  * Reset this surface to the first row. It's legal for this filter to throw
  * away any previously written data at this point, as all rows must be written
  * to on every pass.
  *
  * @return a pointer to the buffer for the first row.
  */
 uint8_t* ResetToFirstRow() {
   mCol = 0;
   mRowPointer = DoResetToFirstRow();
   return mRowPointer;
 }

 /**
  * Called by WritePixels() to advance this filter to the next row.
  *
  * @return a pointer to the buffer for the next row, or nullptr to indicate
  *         that we've finished the entire surface.
  */
 uint8_t* AdvanceRow() {
   mCol = 0;
   mRowPointer = DoAdvanceRow();
   return mRowPointer;
 }

 /**
  * Called by WriteBuffer() to advance this filter to the next row, if the
  * supplied row is a full row.
  *
  * @return a pointer to the buffer for the next row, or nullptr to indicate
  *         that we've finished the entire surface.
  */
 uint8_t* AdvanceRow(const uint8_t* aInputRow) {
   mCol = 0;
   mRowPointer = DoAdvanceRowFromBuffer(aInputRow);
   return mRowPointer;
 }

 /// @return a pointer to the buffer for the current row.
 uint8_t* CurrentRowPointer() const { return mRowPointer; }

 /// @return true if we've finished writing to the surface.
 bool IsSurfaceFinished() const { return mRowPointer == nullptr; }

 /// @return the input size this filter expects.
 gfx::IntSize InputSize() const { return mInputSize; }

 /**
  * Write pixels to the surface one at a time by repeatedly calling a lambda
  * that yields pixels. WritePixels() is completely memory safe.
  *
  * Writing continues until every pixel in the surface has been written to
  * (i.e., IsSurfaceFinished() returns true) or the lambda returns a WriteState
  * which WritePixels() will return to the caller.
  *
  * The template parameter PixelType must be uint8_t (for paletted surfaces) or
  * uint32_t (for BGRA/BGRX surfaces) and must be in agreement with the pixel
  * size passed to ConfigureFilter().
  *
  * XXX(seth): We'll remove all support for paletted surfaces in bug 1247520,
  * which means we can remove the PixelType template parameter from this
  * method.
  *
  * @param aFunc A lambda that functions as a generator, yielding the next
  *              pixel in the surface each time it's called. The lambda must
  *              return a NextPixel<PixelType> value.
  *
  * @return A WriteState value indicating the lambda generator's state.
  *         WritePixels() itself will return WriteState::FINISHED if writing
  *         has finished, regardless of the lambda's internal state.
  */
 template <typename PixelType, typename Func>
 WriteState WritePixels(Func aFunc) {
   Maybe<WriteState> result;
   while (
       !(result = DoWritePixelsToRow<PixelType>(std::forward<Func>(aFunc)))) {
   }

   return *result;
 }

 /**
  * Write pixels to the surface by calling a lambda which may write as many
  * pixels as there is remaining to complete the row. It is not completely
  * memory safe as it trusts the underlying decoder not to overrun the given
  * buffer, however it is an acceptable tradeoff for performance.
  *
  * Writing continues until every pixel in the surface has been written to
  * (i.e., IsSurfaceFinished() returns true) or the lambda returns a WriteState
  * which WritePixelBlocks() will return to the caller.
  *
  * The template parameter PixelType must be uint8_t (for paletted surfaces) or
  * uint32_t (for BGRA/BGRX surfaces) and must be in agreement with the pixel
  * size passed to ConfigureFilter().
  *
  * XXX(seth): We'll remove all support for paletted surfaces in bug 1247520,
  * which means we can remove the PixelType template parameter from this
  * method.
  *
  * @param aFunc A lambda that functions as a generator, yielding at most the
  *              maximum number of pixels requested. The lambda must accept a
  *              pointer argument to the first pixel to write, a maximum
  *              number of pixels to write as part of the block, and return a
  *              NextPixel<PixelType> value.
  *
  * @return A WriteState value indicating the lambda generator's state.
  *         WritePixelBlocks() itself will return WriteState::FINISHED if
  *         writing has finished, regardless of the lambda's internal state.
  */
 template <typename PixelType, typename Func>
 WriteState WritePixelBlocks(Func aFunc) {
   Maybe<WriteState> result;
   while (!(result = DoWritePixelBlockToRow<PixelType>(
                std::forward<Func>(aFunc)))) {
   }

   return *result;
 }

 /**
  * A variant of WritePixels() that writes a single row of pixels to the
  * surface one at a time by repeatedly calling a lambda that yields pixels.
  * WritePixelsToRow() is completely memory safe.
  *
  * Writing continues until every pixel in the row has been written to. If the
  * surface is complete at that pointer, WriteState::FINISHED is returned;
  * otherwise, WritePixelsToRow() returns WriteState::NEED_MORE_DATA. The
  * lambda can terminate writing early by returning a WriteState itself, which
  * WritePixelsToRow() will return to the caller.
  *
  * The template parameter PixelType must be uint8_t (for paletted surfaces) or
  * uint32_t (for BGRA/BGRX surfaces) and must be in agreement with the pixel
  * size passed to ConfigureFilter().
  *
  * XXX(seth): We'll remove all support for paletted surfaces in bug 1247520,
  * which means we can remove the PixelType template parameter from this
  * method.
  *
  * @param aFunc A lambda that functions as a generator, yielding the next
  *              pixel in the surface each time it's called. The lambda must
  *              return a NextPixel<PixelType> value.
  *
  * @return A WriteState value indicating the lambda generator's state.
  *         WritePixels() itself will return WriteState::FINISHED if writing
  *         the entire surface has finished, or WriteState::NEED_MORE_DATA if
  *         writing the row has finished, regardless of the lambda's internal
  *         state.
  */
 template <typename PixelType, typename Func>
 WriteState WritePixelsToRow(Func aFunc) {
   return DoWritePixelsToRow<PixelType>(std::forward<Func>(aFunc))
       .valueOr(WriteState::NEED_MORE_DATA);
 }

 /**
  * Write a row to the surface by copying from a buffer. This is bounds checked
  * and memory safe with respect to the surface, but care must still be taken
  * by the caller not to overread the source buffer. This variant of
  * WriteBuffer() requires a source buffer which contains |mInputSize.width|
  * pixels.
  *
  * The template parameter PixelType must be uint8_t (for paletted surfaces) or
  * uint32_t (for BGRA/BGRX surfaces) and must be in agreement with the pixel
  * size passed to ConfigureFilter().
  *
  * XXX(seth): We'll remove all support for paletted surfaces in bug 1247520,
  * which means we can remove the PixelType template parameter from this
  * method.
  *
  * @param aSource A buffer to copy from. This buffer must be
  *                |mInputSize.width| pixels wide,  which means
  *                |mInputSize.width * sizeof(PixelType)| bytes. May not be
  *                null.
  *
  * @return WriteState::FINISHED if the entire surface has been written to.
  *         Otherwise, returns WriteState::NEED_MORE_DATA. If a null |aSource|
  *         value is passed, returns WriteState::FAILURE.
  */
 template <typename PixelType>
 WriteState WriteBuffer(const PixelType* aSource) {
   MOZ_ASSERT(mPixelSize == 1 || mPixelSize == 4);
   MOZ_ASSERT_IF(mPixelSize == 1, sizeof(PixelType) == sizeof(uint8_t));
   MOZ_ASSERT_IF(mPixelSize == 4, sizeof(PixelType) == sizeof(uint32_t));

   if (IsSurfaceFinished()) {
     return WriteState::FINISHED;  // Already done.
   }

   if (MOZ_UNLIKELY(!aSource)) {
     NS_WARNING("Passed a null pointer to WriteBuffer");
     return WriteState::FAILURE;
   }

   AdvanceRow(reinterpret_cast<const uint8_t*>(aSource));
   return IsSurfaceFinished() ? WriteState::FINISHED
                              : WriteState::NEED_MORE_DATA;
 }

 /**
  * Write a row to the surface by copying from a buffer. This is bounds checked
  * and memory safe with respect to the surface, but care must still be taken
  * by the caller not to overread the source buffer. This variant of
  * WriteBuffer() reads at most @aLength pixels from the buffer and writes them
  * to the row starting at @aStartColumn. Any pixels in columns before
  * @aStartColumn or after the pixels copied from the buffer are cleared.
  *
  * Bounds checking failures produce warnings in debug builds because although
  * the bounds checking maintains safety, this kind of failure could indicate a
  * bug in the calling code.
  *
  * The template parameter PixelType must be uint8_t (for paletted surfaces) or
  * uint32_t (for BGRA/BGRX surfaces) and must be in agreement with the pixel
  * size passed to ConfigureFilter().
  *
  * XXX(seth): We'll remove all support for paletted surfaces in bug 1247520,
  * which means we can remove the PixelType template parameter from this
  * method.
  *
  * @param aSource A buffer to copy from. This buffer must be @aLength pixels
  *                wide, which means |aLength * sizeof(PixelType)| bytes. May
  *                not be null.
  * @param aStartColumn The column to start writing to in the row. Columns
  *                     before this are cleared.
  * @param aLength The number of bytes, at most, which may be copied from
  *                @aSource. Fewer bytes may be copied in practice due to
  *                bounds checking.
  *
  * @return WriteState::FINISHED if the entire surface has been written to.
  *         Otherwise, returns WriteState::NEED_MORE_DATA. If a null |aSource|
  *         value is passed, returns WriteState::FAILURE.
  */
 template <typename PixelType>
 WriteState WriteBuffer(const PixelType* aSource, const size_t aStartColumn,
                        const size_t aLength) {
   MOZ_ASSERT(mPixelSize == 1 || mPixelSize == 4);
   MOZ_ASSERT_IF(mPixelSize == 1, sizeof(PixelType) == sizeof(uint8_t));
   MOZ_ASSERT_IF(mPixelSize == 4, sizeof(PixelType) == sizeof(uint32_t));

   if (IsSurfaceFinished()) {
     return WriteState::FINISHED;  // Already done.
   }

   if (MOZ_UNLIKELY(!aSource)) {
     NS_WARNING("Passed a null pointer to WriteBuffer");
     return WriteState::FAILURE;
   }

   PixelType* dest = reinterpret_cast<PixelType*>(mRowPointer);

   // Clear the area before |aStartColumn|.
   const size_t prefixLength =
       std::min<size_t>(mInputSize.width, aStartColumn);
   if (MOZ_UNLIKELY(prefixLength != aStartColumn)) {
     NS_WARNING("Provided starting column is out-of-bounds in WriteBuffer");
   }

   memset(dest, 0, mInputSize.width * sizeof(PixelType));
   dest += prefixLength;

   // Write |aLength| pixels from |aSource| into the row, with bounds checking.
   const size_t bufferLength =
       std::min<size_t>(mInputSize.width - prefixLength, aLength);
   if (MOZ_UNLIKELY(bufferLength != aLength)) {
     NS_WARNING("Provided buffer length is out-of-bounds in WriteBuffer");
   }

   memcpy(dest, aSource, bufferLength * sizeof(PixelType));
   dest += bufferLength;

   // Clear the rest of the row.
   const size_t suffixLength =
       mInputSize.width - (prefixLength + bufferLength);
   memset(dest, 0, suffixLength * sizeof(PixelType));

   AdvanceRow();

   return IsSurfaceFinished() ? WriteState::FINISHED
                              : WriteState::NEED_MORE_DATA;
 }

 /**
  * Write an empty row to the surface. If some pixels have already been written
  * to this row, they'll be discarded.
  *
  * @return WriteState::FINISHED if the entire surface has been written to.
  *         Otherwise, returns WriteState::NEED_MORE_DATA.
  */
 WriteState WriteEmptyRow() {
   if (IsSurfaceFinished()) {
     return WriteState::FINISHED;  // Already done.
   }

   memset(mRowPointer, 0, mInputSize.width * mPixelSize);
   AdvanceRow();

   return IsSurfaceFinished() ? WriteState::FINISHED
                              : WriteState::NEED_MORE_DATA;
 }

 /**
  * Write a row to the surface by calling a lambda that uses a pointer to
  * directly write to the row. This is unsafe because SurfaceFilter can't
  * provide any bounds checking; that's up to the lambda itself. For this
  * reason, the other Write*() methods should be preferred whenever it's
  * possible to use them; WriteUnsafeComputedRow() should be used only when
  * it's absolutely necessary to avoid extra copies or other performance
  * penalties.
  *
  * This method should never be exposed to SurfacePipe consumers; it's strictly
  * for use in SurfaceFilters. If external code needs this method, it should
  * probably be turned into a SurfaceFilter.
  *
  * The template parameter PixelType must be uint8_t (for paletted surfaces) or
  * uint32_t (for BGRA/BGRX surfaces) and must be in agreement with the pixel
  * size passed to ConfigureFilter().
  *
  * XXX(seth): We'll remove all support for paletted surfaces in bug 1247520,
  * which means we can remove the PixelType template parameter from this
  * method.
  *
  * @param aFunc A lambda that writes directly to the row.
  *
  * @return WriteState::FINISHED if the entire surface has been written to.
  *         Otherwise, returns WriteState::NEED_MORE_DATA.
  */
 template <typename PixelType, typename Func>
 WriteState WriteUnsafeComputedRow(Func aFunc) {
   MOZ_ASSERT(mPixelSize == 1 || mPixelSize == 4);
   MOZ_ASSERT_IF(mPixelSize == 1, sizeof(PixelType) == sizeof(uint8_t));
   MOZ_ASSERT_IF(mPixelSize == 4, sizeof(PixelType) == sizeof(uint32_t));

   if (IsSurfaceFinished()) {
     return WriteState::FINISHED;  // Already done.
   }

   // Call the provided lambda with a pointer to the buffer for the current
   // row. This is unsafe because we can't do any bounds checking; the lambda
   // itself has to be responsible for that.
   PixelType* rowPtr = reinterpret_cast<PixelType*>(mRowPointer);
   aFunc(rowPtr, mInputSize.width);
   AdvanceRow();

   return IsSurfaceFinished() ? WriteState::FINISHED
                              : WriteState::NEED_MORE_DATA;
 }

 //////////////////////////////////////////////////////////////////////////////
 // Methods Subclasses Should Override
 //////////////////////////////////////////////////////////////////////////////

 /**
  * @return a SurfaceInvalidRect representing the region of the surface that
  *         has been written to since the last time TakeInvalidRect() was
  *         called, or Nothing() if the region is empty (i.e. nothing has been
  *         written).
  */
 virtual Maybe<SurfaceInvalidRect> TakeInvalidRect() = 0;

protected:
 /**
  * Called by ResetToFirstRow() to actually perform the reset. It's legal to
  * throw away any previously written data at this point, as all rows must be
  * written to on every pass.
  */
 virtual uint8_t* DoResetToFirstRow() = 0;

 /**
  * Called by AdvanceRow() to actually advance this filter to the next row.
  *
  * @param aInputRow The input row supplied by the decoder.
  *
  * @return a pointer to the buffer for the next row, or nullptr to indicate
  *         that we've finished the entire surface.
  */
 virtual uint8_t* DoAdvanceRowFromBuffer(const uint8_t* aInputRow) = 0;

 /**
  * Called by AdvanceRow() to actually advance this filter to the next row.
  *
  * @return a pointer to the buffer for the next row, or nullptr to indicate
  *         that we've finished the entire surface.
  */
 virtual uint8_t* DoAdvanceRow() = 0;

 //////////////////////////////////////////////////////////////////////////////
 // Methods For Internal Use By Subclasses
 //////////////////////////////////////////////////////////////////////////////

 /**
  * Called by subclasses' Configure() methods to initialize the configuration
  * of this filter. After the filter is configured, calls ResetToFirstRow().
  *
  * @param aInputSize The input size of this filter, in pixels. The previous
  *                   filter in the chain will expect to write into rows
  *                   |aInputSize.width| pixels wide.
  * @param aPixelSize How large, in bytes, each pixel in the surface is. This
  *                   should be either 1 for paletted images or 4 for BGRA/BGRX
  *                   images.
  */
 void ConfigureFilter(gfx::IntSize aInputSize, uint8_t aPixelSize) {
   mInputSize = aInputSize;
   mPixelSize = aPixelSize;

   ResetToFirstRow();
 }

 /**
  * Called by subclasses' DoAdvanceRowFromBuffer() methods to copy a decoder
  * supplied row buffer into its internal row pointer. Ideally filters at the
  * top of the filter pipeline are able to consume the decoder row buffer
  * directly without the extra copy prior to performing its transformation.
  *
  * @param aInputRow The input row supplied by the decoder.
  */
 void CopyInputRow(const uint8_t* aInputRow) {
   MOZ_ASSERT(aInputRow);
   MOZ_ASSERT(mCol == 0);
   memcpy(mRowPointer, aInputRow, mPixelSize * mInputSize.width);
 }

private:
 /**
  * An internal method used to implement WritePixelBlocks. This method writes
  * up to the number of pixels necessary to complete the row and returns Some()
  * if we either finished the entire surface or the lambda returned a
  * WriteState indicating that we should return to the caller. If the row was
  * successfully written without either of those things happening, it returns
  * Nothing(), allowing WritePixelBlocks() to iterate to fill as many rows as
  * possible.
  */
 template <typename PixelType, typename Func>
 Maybe<WriteState> DoWritePixelBlockToRow(Func aFunc) {
   MOZ_ASSERT(mPixelSize == 1 || mPixelSize == 4);
   MOZ_ASSERT_IF(mPixelSize == 1, sizeof(PixelType) == sizeof(uint8_t));
   MOZ_ASSERT_IF(mPixelSize == 4, sizeof(PixelType) == sizeof(uint32_t));

   if (IsSurfaceFinished()) {
     return Some(WriteState::FINISHED);  // We're already done.
   }

   PixelType* rowPtr = reinterpret_cast<PixelType*>(mRowPointer);
   int32_t remainder = mInputSize.width - mCol;
   auto [written, result] = aFunc(&rowPtr[mCol], remainder);
   if (written == remainder) {
     MOZ_ASSERT(result.isNothing());
     mCol = mInputSize.width;
     AdvanceRow();  // We've finished the row.
     return IsSurfaceFinished() ? Some(WriteState::FINISHED) : Nothing();
   }

   MOZ_ASSERT(written >= 0 && written < remainder);
   MOZ_ASSERT(result.isSome());

   mCol += written;
   if (*result == WriteState::FINISHED) {
     ZeroOutRestOfSurface<PixelType>();
   }

   return result;
 }

 /**
  * An internal method used to implement both WritePixels() and
  * WritePixelsToRow(). Those methods differ only in their behavior after a row
  * is successfully written - WritePixels() continues to write another row,
  * while WritePixelsToRow() returns to the caller. This method writes a single
  * row and returns Some() if we either finished the entire surface or the
  * lambda returned a WriteState indicating that we should return to the
  * caller. If the row was successfully written without either of those things
  * happening, it returns Nothing(), allowing WritePixels() and
  * WritePixelsToRow() to implement their respective behaviors.
  */
 template <typename PixelType, typename Func>
 Maybe<WriteState> DoWritePixelsToRow(Func aFunc) {
   MOZ_ASSERT(mPixelSize == 1 || mPixelSize == 4);
   MOZ_ASSERT_IF(mPixelSize == 1, sizeof(PixelType) == sizeof(uint8_t));
   MOZ_ASSERT_IF(mPixelSize == 4, sizeof(PixelType) == sizeof(uint32_t));

   if (IsSurfaceFinished()) {
     return Some(WriteState::FINISHED);  // We're already done.
   }

   PixelType* rowPtr = reinterpret_cast<PixelType*>(mRowPointer);

   for (; mCol < mInputSize.width; ++mCol) {
     NextPixel<PixelType> result = aFunc();
     if (result.template is<PixelType>()) {
       rowPtr[mCol] = result.template as<PixelType>();
       continue;
     }

     switch (result.template as<WriteState>()) {
       case WriteState::NEED_MORE_DATA:
         return Some(WriteState::NEED_MORE_DATA);

       case WriteState::FINISHED:
         ZeroOutRestOfSurface<PixelType>();
         return Some(WriteState::FINISHED);

       case WriteState::FAILURE:
         // Note that we don't need to record this anywhere, because this
         // indicates an error in aFunc, and there's nothing wrong with our
         // machinery. The caller can recover as needed and continue writing to
         // the row.
         return Some(WriteState::FAILURE);
     }
   }

   AdvanceRow();  // We've finished the row.

   return IsSurfaceFinished() ? Some(WriteState::FINISHED) : Nothing();
 }

 template <typename PixelType>
 void ZeroOutRestOfSurface() {
   WritePixels<PixelType>([] { return AsVariant(PixelType(0)); });
 }

 gfx::IntSize mInputSize;  /// The size of the input this filter expects.
 uint8_t* mRowPointer;     /// Pointer to the current row or null if finished.
 int32_t mCol;             /// The current column we're writing to. (0-indexed)
 uint8_t mPixelSize;  /// How large each pixel in the surface is, in bytes.
};

/**
* SurfacePipe is the public API that decoders should use to interact with a
* SurfaceFilter pipeline.
*/
class SurfacePipe {
public:
 SurfacePipe() {}

 SurfacePipe(SurfacePipe&& aOther) : mHead(std::move(aOther.mHead)) {}

 ~SurfacePipe() {}

 SurfacePipe& operator=(SurfacePipe&& aOther) {
   MOZ_ASSERT(this != &aOther);
   mHead = std::move(aOther.mHead);
   return *this;
 }

 /// Begins a new pass, seeking to the first row of the surface.
 void ResetToFirstRow() {
   MOZ_ASSERT(mHead, "Use before configured!");
   mHead->ResetToFirstRow();
 }

 /**
  * Write pixels to the surface one at a time by repeatedly calling a lambda
  * that yields pixels. WritePixels() is completely memory safe.
  *
  * @see SurfaceFilter::WritePixels() for the canonical documentation.
  */
 template <typename PixelType, typename Func>
 WriteState WritePixels(Func aFunc) {
   MOZ_ASSERT(mHead, "Use before configured!");
   return mHead->WritePixels<PixelType>(std::forward<Func>(aFunc));
 }

 /**
  * A variant of WritePixels() that writes up to a single row of pixels to the
  * surface in blocks by repeatedly calling a lambda that yields up to the
  * requested number of pixels.
  *
  * @see SurfaceFilter::WritePixelBlocks() for the canonical documentation.
  */
 template <typename PixelType, typename Func>
 WriteState WritePixelBlocks(Func aFunc) {
   MOZ_ASSERT(mHead, "Use before configured!");
   return mHead->WritePixelBlocks<PixelType>(std::forward<Func>(aFunc));
 }

 /**
  * A variant of WritePixels() that writes a single row of pixels to the
  * surface one at a time by repeatedly calling a lambda that yields pixels.
  * WritePixelsToRow() is completely memory safe.
  *
  * @see SurfaceFilter::WritePixelsToRow() for the canonical documentation.
  */
 template <typename PixelType, typename Func>
 WriteState WritePixelsToRow(Func aFunc) {
   MOZ_ASSERT(mHead, "Use before configured!");
   return mHead->WritePixelsToRow<PixelType>(std::forward<Func>(aFunc));
 }

 /**
  * Write a row to the surface by copying from a buffer. This is bounds checked
  * and memory safe with respect to the surface, but care must still be taken
  * by the caller not to overread the source buffer. This variant of
  * WriteBuffer() requires a source buffer which contains |mInputSize.width|
  * pixels.
  *
  * @see SurfaceFilter::WriteBuffer() for the canonical documentation.
  */
 template <typename PixelType>
 WriteState WriteBuffer(const PixelType* aSource) {
   MOZ_ASSERT(mHead, "Use before configured!");
   return mHead->WriteBuffer<PixelType>(aSource);
 }

 /**
  * Write a row to the surface by copying from a buffer. This is bounds checked
  * and memory safe with respect to the surface, but care must still be taken
  * by the caller not to overread the source buffer. This variant of
  * WriteBuffer() reads at most @aLength pixels from the buffer and writes them
  * to the row starting at @aStartColumn. Any pixels in columns before
  * @aStartColumn or after the pixels copied from the buffer are cleared.
  *
  * @see SurfaceFilter::WriteBuffer() for the canonical documentation.
  */
 template <typename PixelType>
 WriteState WriteBuffer(const PixelType* aSource, const size_t aStartColumn,
                        const size_t aLength) {
   MOZ_ASSERT(mHead, "Use before configured!");
   return mHead->WriteBuffer<PixelType>(aSource, aStartColumn, aLength);
 }

 /**
  * Write an empty row to the surface. If some pixels have already been written
  * to this row, they'll be discarded.
  *
  * @see SurfaceFilter::WriteEmptyRow() for the canonical documentation.
  */
 WriteState WriteEmptyRow() {
   MOZ_ASSERT(mHead, "Use before configured!");
   return mHead->WriteEmptyRow();
 }

 /// @return true if we've finished writing to the surface.
 bool IsSurfaceFinished() const { return mHead->IsSurfaceFinished(); }

 /// @see SurfaceFilter::TakeInvalidRect() for the canonical documentation.
 Maybe<SurfaceInvalidRect> TakeInvalidRect() const {
   MOZ_ASSERT(mHead, "Use before configured!");
   return mHead->TakeInvalidRect();
 }

private:
 friend class SurfacePipeFactory;
 friend class TestSurfacePipeFactory;

 explicit SurfacePipe(UniquePtr<SurfaceFilter>&& aHead)
     : mHead(std::move(aHead)) {}

 SurfacePipe(const SurfacePipe&) = delete;
 SurfacePipe& operator=(const SurfacePipe&) = delete;

 UniquePtr<SurfaceFilter> mHead;  /// The first filter in the chain.
};

/**
* AbstractSurfaceSink contains shared implementation for both SurfaceSink and
* ReorientSurfaceSink.
*/
class AbstractSurfaceSink : public SurfaceFilter {
public:
 AbstractSurfaceSink()
     : mImageData(nullptr),
       mImageDataLength(0),
       mRow(0),
       mFlipVertically(false) {}

 Maybe<SurfaceInvalidRect> TakeInvalidRect() final;

protected:
 uint8_t* DoResetToFirstRow() final;
 virtual uint8_t* GetRowPointer() const = 0;

 OrientedIntRect
     mInvalidRect;     /// The region of the surface that has been written
                       /// to since the last call to TakeInvalidRect().
 uint8_t* mImageData;  /// A pointer to the beginning of the surface data.
 uint32_t mImageDataLength;  /// The length of the surface data.
 uint32_t mRow;              /// The row to which we're writing. (0-indexed)
 bool mFlipVertically;       /// If true, write the rows from top to bottom.
};

class SurfaceSink;

/// A configuration struct for SurfaceSink.
struct SurfaceConfig {
 using Filter = SurfaceSink;
 Decoder* mDecoder;           /// Which Decoder to use to allocate the surface.
 gfx::IntSize mOutputSize;    /// The size of the surface.
 gfx::SurfaceFormat mFormat;  /// The surface format (BGRA or BGRX).
 bool mFlipVertically;        /// If true, write the rows from bottom to top.
 Maybe<AnimationParams> mAnimParams;  /// Given for animated images.
};

/**
* A sink for surfaces. It handles the allocation of the surface and protects
* against buffer overflow. This sink should be used for most images.
*
* Sinks must always be at the end of the SurfaceFilter chain.
*/
class SurfaceSink final : public AbstractSurfaceSink {
public:
 nsresult Configure(const SurfaceConfig& aConfig);

protected:
 uint8_t* DoAdvanceRowFromBuffer(const uint8_t* aInputRow) final;
 uint8_t* DoAdvanceRow() final;
 uint8_t* GetRowPointer() const final;
};

class ReorientSurfaceSink;

/// A configuration struct for ReorientSurfaceSink.
struct ReorientSurfaceConfig {
 using Filter = ReorientSurfaceSink;
 Decoder* mDecoder;  /// Which Decoder to use to allocate the surface.
 OrientedIntSize mOutputSize;  /// The size of the surface.
 gfx::SurfaceFormat mFormat;   /// The surface format (BGRA or BGRX).
 Orientation mOrientation;     /// The desired orientation of the surface data.
};

/**
* A sink for surfaces. It handles the allocation of the surface and protects
* against buffer overflow. This sink should be used for images which have a
* non-identity orientation which we want to apply during decoding.
*
* Sinks must always be at the end of the SurfaceFilter chain.
*/
class ReorientSurfaceSink final : public AbstractSurfaceSink {
public:
 nsresult Configure(const ReorientSurfaceConfig& aConfig);

protected:
 uint8_t* DoAdvanceRowFromBuffer(const uint8_t* aInputRow) final;
 uint8_t* DoAdvanceRow() final;
 uint8_t* GetRowPointer() const final;

 UniquePtr<uint8_t[]> mBuffer;
 gfx::ReorientRowFn mReorientFn;
 gfx::IntSize mSurfaceSize;
};

}  // namespace image
}  // namespace mozilla

#endif  // mozilla_image_SurfacePipe_h