Add the ability to decode a subset to SkCodec.

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 40 matching lines @@
     /**
      *  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.
      */
     SkISize getScaledDimensions(float desiredScale) const {
         return this->onGetScaledDimensions(desiredScale);
     }
 
     /**
+     *  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);
+    }
+
+    /**
      *  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.
      */
     enum Result {
@@ skipping 50 matching lines @@
          *  This is the default. It will be used if no Options struct is used.
          */
         kNo_ZeroInitialized,
     };
 
     /**
      *  Additional options to pass to getPixels.
      */
     struct Options {
         Options()
-            : fZeroInitialized(kNo_ZeroInitialized) {}
+            : fZeroInitialized(kNo_ZeroInitialized)
+        {
+            fSubset.setEmpty();
+        }
 
         ZeroInitialized fZeroInitialized;
+        /**
+         *  If not empty, represents a subset of the original image to decode.
+         *
+         *  Must intersect with the bounds returned by getInfo().
+         *
+         *  If the EncodedFormat is kWEBP_SkEncodedFormat (the only one which
+         *  currently supports subsets), the top and left values must be even.
+         */
+        SkIRect         fSubset;

[scroggo, 2015/07/21 14:53:45]

This might be better as a pointer, where NULL means do not use a subset, and
non-NULL means to use a subset. That way we do not have to initialize/check
empty when it's not used. Thoughts?

[msarett, 2015/07/21 15:19:37]

I would lean towards using a pointer, but I don't feel strongly.

I could see how we might erroneously decide that an empty subset indicates we
should do a no-op decode.

[emmaleer, 2015/07/21 15:24:55]

I think making it a pointer makes more sense. Because why would you want to
create the SkIRect at all if you aren't going to use it? 

     };
 
     /**
      *  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.
      *
@@ skipping 77 matching lines @@
         // By default, scaling is not supported.
         return this->getInfo().dimensions();
     }
 
     virtual SkEncodedFormat onGetEncodedFormat() const = 0;
 
     virtual Result onGetPixels(const SkImageInfo& info,
                                void* pixels, size_t rowBytes, const Options&,
                                SkPMColor ctable[], int* ctableCount) = 0;
 
+    virtual bool onGetValidSubset(SkIRect* /* desiredSubset */) const {
+        // By default, subsets are not supported.
+        return false;
+    }
+
     /**
      *  Override if your codec supports scanline decoding.
      *
      *  @param dstInfo Info of the destination. If the dimensions do not match
      *      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.
@@ skipping 40 matching lines @@
     SkStream* stream() {
         return fStream.get();
     }
 
 private:
     const SkImageInfo       fInfo;
     SkAutoTDelete<SkStream> fStream;
     bool                    fNeedsRewind;
 };
 #endif // SkCodec_DEFINED