summaryrefslogtreecommitdiffstats
path: root/image/SurfacePipe.h
diff options
context:
space:
mode:
Diffstat (limited to 'image/SurfacePipe.h')
-rw-r--r--image/SurfacePipe.h850
1 files changed, 850 insertions, 0 deletions
diff --git a/image/SurfacePipe.h b/image/SurfacePipe.h
new file mode 100644
index 0000000000..0c3533c9f9
--- /dev/null
+++ b/image/SurfacePipe.h
@@ -0,0 +1,850 @@
+/* -*- 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/Tuple.h"
+#include "mozilla/UniquePtr.h"
+#include "mozilla/Unused.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;
+ int32_t written;
+ Maybe<WriteState> result;
+ Tie(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
generated by cgit v1.2.3 (git 2.39.1) at 2024-12-01 05:44:11 +0000