From 36d22d82aa202bb199967e9512281e9a53db42c9 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 21:33:14 +0200 Subject: Adding upstream version 115.7.0esr. Signed-off-by: Daniel Baumann --- image/SurfacePipe.h | 848 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 848 insertions(+) create mode 100644 image/SurfacePipe.h (limited to 'image/SurfacePipe.h') diff --git a/image/SurfacePipe.h b/image/SurfacePipe.h new file mode 100644 index 0000000000..7dd20276e5 --- /dev/null +++ b/image/SurfacePipe.h @@ -0,0 +1,848 @@ +/* -*- 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 + +#include + +#include "AnimationParams.h" +#include "mozilla/Likely.h" +#include "mozilla/Maybe.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 +using NextPixel = Variant; + +/** + * 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 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 + WriteState WritePixels(Func aFunc) { + Maybe result; + while ( + !(result = DoWritePixelsToRow(std::forward(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 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 + WriteState WritePixelBlocks(Func aFunc) { + Maybe result; + while (!(result = DoWritePixelBlockToRow( + std::forward(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 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 + WriteState WritePixelsToRow(Func aFunc) { + return DoWritePixelsToRow(std::forward(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 + 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(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 + 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(mRowPointer); + + // Clear the area before |aStartColumn|. + const size_t prefixLength = + std::min(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(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 + 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(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 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 + Maybe 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(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(); + } + + 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 + Maybe 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(mRowPointer); + + for (; mCol < mInputSize.width; ++mCol) { + NextPixel result = aFunc(); + if (result.template is()) { + rowPtr[mCol] = result.template as(); + continue; + } + + switch (result.template as()) { + case WriteState::NEED_MORE_DATA: + return Some(WriteState::NEED_MORE_DATA); + + case WriteState::FINISHED: + ZeroOutRestOfSurface(); + 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 + void ZeroOutRestOfSurface() { + WritePixels([] { 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 + WriteState WritePixels(Func aFunc) { + MOZ_ASSERT(mHead, "Use before configured!"); + return mHead->WritePixels(std::forward(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 + WriteState WritePixelBlocks(Func aFunc) { + MOZ_ASSERT(mHead, "Use before configured!"); + return mHead->WritePixelBlocks(std::forward(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 + WriteState WritePixelsToRow(Func aFunc) { + MOZ_ASSERT(mHead, "Use before configured!"); + return mHead->WritePixelsToRow(std::forward(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 + WriteState WriteBuffer(const PixelType* aSource) { + MOZ_ASSERT(mHead, "Use before configured!"); + return mHead->WriteBuffer(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 + WriteState WriteBuffer(const PixelType* aSource, const size_t aStartColumn, + const size_t aLength) { + MOZ_ASSERT(mHead, "Use before configured!"); + return mHead->WriteBuffer(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 TakeInvalidRect() const { + MOZ_ASSERT(mHead, "Use before configured!"); + return mHead->TakeInvalidRect(); + } + + private: + friend class SurfacePipeFactory; + friend class TestSurfacePipeFactory; + + explicit SurfacePipe(UniquePtr&& aHead) + : mHead(std::move(aHead)) {} + + SurfacePipe(const SurfacePipe&) = delete; + SurfacePipe& operator=(const SurfacePipe&) = delete; + + UniquePtr 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 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 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 mBuffer; + gfx::ReorientRowFn mReorientFn; + gfx::IntSize mSurfaceSize; +}; + +} // namespace image +} // namespace mozilla + +#endif // mozilla_image_SurfacePipe_h -- cgit v1.2.3