Add subsetting to SkScaledCodec

include/codec/SkCodec.h

 /*
  * Copyright 2015 Google Inc.
  *
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
  */
 
 #ifndef SkCodec_DEFINED
 #define SkCodec_DEFINED
 
@@ skipping 37 matching lines @@
      */
     const SkImageInfo& getInfo() const { return fSrcInfo; }
 
     /**
      *  Return a size that approximately supports the desired scale factor.
      *  The codec may not be able to scale efficiently to the exact scale
      *  factor requested, so return a size that approximates that scale.
      *  The returned value is the codec's suggestion for the closest valid
      *  scale that it can natively support
      */
-    SkISize getScaledDimensions(float desiredScale) const {
-        // Negative and zero scales are errors.
-        SkASSERT(desiredScale > 0.0f);
-        if (desiredScale <= 0.0f) {
-            return SkISize::Make(0, 0);
-        }
-
-        // Upscaling is not supported. Return the original size if the client
-        // requests an upscale.
-        if (desiredScale >= 1.0f) {
-            return this->getInfo().dimensions();
-        }
-        return this->onGetScaledDimensions(desiredScale);
-    }
+    SkISize getScaledDimensions(float desiredScale) const;
 
     /**
      *  Return (via desiredSubset) a subset which can decoded from this codec,
      *  or false if this codec cannot decode subsets or anything similar to
      *  desiredSubset.
      *
      *  @param desiredSubset In/out parameter. As input, a desired subset of
      *      the original bounds (as specified by getInfo). If true is returned,
      *      desiredSubset may have been modified to a subset which is
      *      supported. Although a particular change may have been made to
      *      desiredSubset to create something supported, it is possible other
      *      changes could result in a valid subset.
      *      If false is returned, desiredSubset's value is undefined.
      *  @return true if this codec supports decoding desiredSubset (as
      *      returned, potentially modified)
      */
-    bool getValidSubset(SkIRect* desiredSubset) const {
-        return this->onGetValidSubset(desiredSubset);
-    }
+    bool getValidSubset(SkIRect* desiredSubset) const;
 
     /**
      *  Format of the encoded data.
      */
     SkEncodedFormat getEncodedFormat() const { return this->onGetEncodedFormat(); }
 
     /**
      *  Used to describe the result of a call to getPixels().
      *
      *  Result is the union of possible results from subclasses.
@@ skipping 55 matching lines @@
         kNo_ZeroInitialized,
     };
 
     /**
      *  Additional options to pass to getPixels.
      */
     struct Options {
         Options()
             : fZeroInitialized(kNo_ZeroInitialized)
             , fSubset(NULL)
+            , fScaledDimensions(SkISize::Make(0, 0))
+            , fScaledSubset(SkIRect::MakeEmpty())
         {}
 
         ZeroInitialized fZeroInitialized;
+
         /**
-         *  If not NULL, represents a subset of the original image to decode.
+         *  fSubset represents a subset of the original image to decode.
+         *  It must be within the bounds returned by getInfo().
+         *  If the EncodedFormat is kWEBP_SkEncodedFormat, the top and left
+         *  values must be even.
+         *  If fSubset is NULL, we are not performing a subset decode.
          *
-         *  Must be within the bounds returned by getInfo().
+         *  fScaledDimensions and fScaledSubset are used together to help
+         *  specify a scaled subset decode.  Both should be specified for a
+         *  scaled subset decode, and both should be zeroed otherwise.
          *
-         *  If the EncodedFormat is kWEBP_SkEncodedFormat (the only one which
-         *  currently supports subsets), the top and left values must be even.
+         *  If fScaledDimensions and fScaledSubset are zeroed, we are not
+         *  performing a scaled subset decode:
+         *      (1) If fSubset is non-NULL, we are performing an unscaled
+         *          subset decode, and the subset dimensions must match the
+         *          dstInfo dimensions.
+         *      (2) If fSubset is NULL and the dstInfo dimensions do not
+         *          match the original dimensions, we are performing a
+         *          scaled decode.
+         *      (3) If fSubset is NULL and the dstInfo dimensions match the
+         *          original dimensions, we are performing an unscaled, full
+         *          image decode.
+         *
+         *  If both are non-NULL we are performing a scaled subset decode:
+         *      fSubset must be non-NULL.
+         *      fScaledSubset must be within the bounds of fScaledDimensions.
+         *      The dimensions of fScaledSubset must match the dimensions
+         *      specified by dstInfo.
+         *
+         *  Usage:
+         *      Call getScaledSubsetDimensions() with the desired fSubset of
+         *      the original image and the desired scale.  The function will
+         *      populate the options object with valid values of
+         *      fScaledDimensions and fScaledSubset that can be decoded
+         *      efficiently.
          */
         SkIRect*        fSubset;
+        SkISize         fScaledDimensions;
+        SkIRect         fScaledSubset;
     };
 
     /**
+     *  @param desiredScale The requested scale factor.
+     *  @param options      In/out parameter.
+     *                      options->fSubset (in/out) specifies the
+     *                      requested subset in terms of the original image
+     *                      dimensions.  This may be modified to a subset
+     *                      that can be decoded more efficiently.
+     *                      options->fScaledDimensions is an output and
+     *                      specifies the best scaled (full image) output
+     *                      dimensions that can be achieved for the
+     *                      desiredScale.
+     *                      options->fScaledSubset is an output and specifies
+     *                      the fSubset in terms of fScaledDimensions.
+     *
+     *  The codec may not be able to scale and subset efficiently to the exact
+     *  scale and subset requested, so fScaledDimensions and fScaledSubset may
+     *  be approximate.  These output values are the codec's suggestion for
+     *  the closest valid scaled subset that it can support.
+     *
+     *  @return true if fScaledDimensions and fScaledSubset have been
+     *               successfully set to values that the codec supports.
+     *          false otherwise.
+     */
+    bool getScaledSubsetDimensions(float desiredScale, Options* options) const;
+
+    /**
      *  Decode into the given pixels, a block of memory of size at
      *  least (info.fHeight - 1) * rowBytes + (info.fWidth *
      *  bytesPerPixel)
      *
      *  Repeated calls to this function should give the same results,
      *  allowing the PixelRef to be immutable.
      *
      *  @param info A description of the format (config, size)
      *         expected by the caller.  This can simply be identical
      *         to the info returned by getInfo().
@@ skipping 58 matching lines @@
      *      those of getInfo, this implies a scale.
      *  @param options Contains decoding options, including if memory is zero
      *      initialized.
      *  @param ctable A pointer to a color table.  When dstInfo.colorType() is
      *      kIndex8, this should be non-NULL and have enough storage for 256
      *      colors.  The color table will be populated after decoding the palette.
      *  @param ctableCount A pointer to the size of the color table.  When
      *      dstInfo.colorType() is kIndex8, this should be non-NULL.  It will
      *      be modified to the true size of the color table (<= 256) after
      *      decoding the palette.
+     *  @param subsetLeft The left offset at which to begin decoding each
+     *      scanline.  This enables partial scanline decodes.
+     *  @param subsetWidth The number of pixels to decode in each scanline row.
      *  @return Enum representing success or reason for failure.
      */
     Result startScanlineDecode(const SkImageInfo& dstInfo, const SkCodec::Options* options,
-                 SkPMColor ctable[], int* ctableCount);
+                 SkPMColor ctable[], int* ctableCount, int subsetLeft, int subsetWidth);
+
+    /**
+     *  Simplified version of startScanlineDecode() that does not enable partial
+     *  scanline decoding.
+     */
+    Result startScanlineDecode(const SkImageInfo& dstInfo, const SkCodec::Options* options,
+            SkPMColor ctable[], int* ctableCount);
 
     /**
      *  Simplified version of startScanlineDecode() that asserts that info is NOT
-     *  kIndex8_SkColorType and uses the default Options.
+     *  kIndex8_SkColorType, uses the default Options, and does not enable
+     *  partial scanline decoding.
      */
     Result startScanlineDecode(const SkImageInfo& dstInfo);
 
     /**
      *  Write the next countLines scanlines into dst.
      *
      *  Not valid to call before calling startScanlineDecode().
      *
      *  @param dst Must be non-null, and large enough to hold countLines
      *      scanlines of size rowBytes.
@@ skipping 114 matching lines @@
     int outputScanline(int inputScanline) const;
 
 protected:
     SkCodec(const SkImageInfo&, SkStream*);
 
     virtual SkISize onGetScaledDimensions(float /* desiredScale */) const {
         // By default, scaling is not supported.
         return this->getInfo().dimensions();
     }
 
+    virtual bool onGetValidSubset(SkIRect* /* desiredSubset */) const {
+        // By default, subsets are not supported.
+        return false;
+    }
+
+    virtual bool onGetScaledSubsetDimensions(float desiredScale, Options* options) const {
+        // By default, scaled subsetting is not supported.
+        return false;
+    }
+
     // FIXME: What to do about subsets??
     /**
      *  Subclasses should override if they support dimensions other than the
      *  srcInfo's.
      */
     virtual bool onDimensionsSupported(const SkISize&) {
         return false;
     }
 
     virtual SkEncodedFormat onGetEncodedFormat() const = 0;
 
     /**
      * @param rowsDecoded When the encoded image stream is incomplete, this function
      *                    will return kIncompleteInput and rowsDecoded will be set to
      *                    the number of scanlines that were successfully decoded.
      *                    This will allow getPixels() to fill the uninitialized memory.
      */
     virtual Result onGetPixels(const SkImageInfo& info,
                                void* pixels, size_t rowBytes, const Options&,
                                SkPMColor ctable[], int* ctableCount,
                                int* rowsDecoded) = 0;
 
-    virtual bool onGetValidSubset(SkIRect* /* desiredSubset */) const {
-        // By default, subsets are not supported.
-        return false;
-    }
-
     virtual bool onReallyHasAlpha() const { return false; }
 
     /**
      *  If the stream was previously read, attempt to rewind.
      *
      *  If the stream needed to be rewound, call onRewind.
      *  @returns true if the codec is at the right position and can be used.
      *      false if there was a failure to rewind.
      *
      *  This is called by getPixels() and start(). Subclasses may call if they
@@ skipping 84 matching lines @@
      *  on success.
      *
      *  This must return true for a size returned from getScaledDimensions.
      */
     bool dimensionsSupported(const SkISize& dim) {
         return dim == fSrcInfo.dimensions() || this->onDimensionsSupported(dim);
     }
 
     // Methods for scanline decoding.
     virtual SkCodec::Result onStartScanlineDecode(const SkImageInfo& dstInfo,
-            const SkCodec::Options& options, SkPMColor ctable[], int* ctableCount) {
+            const SkCodec::Options& options, SkPMColor ctable[], int* ctableCount, int subsetLeft,
+            int subsetWidth) {
         return kUnimplemented;
     }
 
     // Naive default version just calls onGetScanlines on temp memory.
     virtual bool onSkipScanlines(int countLines) {
         // FIXME (msarett): Make this a pure virtual and always override this.
         SkAutoMalloc storage(fDstInfo.minRowBytes());
 
         // Note that we pass 0 to rowBytes so we continue to use the same memory.
         // Also note that while getScanlines checks that rowBytes is big enough,
@@ skipping 28 matching lines @@
      *  May create a sampler, if one is not currently being used. Otherwise, does
      *  not affect ownership.
      *
      *  Only valid during scanline decoding.
      */
     virtual SkSampler* getSampler(bool createIfNecessary) { return nullptr; }
 
     friend class SkScaledCodec;
 };
 #endif // SkCodec_DEFINED