Option for SkCodec to treat dst as all zeroes.

include/core/SkImageGenerator.h

Index: include/core/SkImageGenerator.h
diff --git a/include/core/SkImageGenerator.h b/include/core/SkImageGenerator.h
index 5de9d3d85ace1d64a1cf2b7a3e3c1b412b6a2b68..a5440bd3b4d88011bb70dee991a28c2c1c61771c 100644
--- a/include/core/SkImageGenerator.h
+++ b/include/core/SkImageGenerator.h
@@ -15,6 +15,8 @@ class SkBitmap;
 class SkData;
 class SkImageGenerator;
 
+//#define SK_SUPPORT_LEGACY_OPTIONLESS_GET_PIXELS

[djsollen, 2015/03/06 20:41:56]

remove this

[scroggo, 2015/03/06 20:54:25]

I don't think we have an official position, but typically we place this in the
header where it's meaningful.

+
 /**
  *  Takes ownership of SkImageGenerator.  If this method fails for
  *  whatever reason, it will return false and immediatetely delete
@@ -117,6 +119,34 @@ public:
     };
 
     /**
+     *  Whether or not the memory passed to getPixels is zero initialized.
+     */
+    enum ZeroInitialized {
+        /**
+         *  The memory passed to getPixels is zero initialized. The SkCodec
+         *  may take advantage of this by skipping writing zeroes.
+         */
+        kYes_ZeroInitialized,
+        /**
+         *  The memory passed to getPixels has not been initialized to zero,
+         *  so the SkCodec must write all zeroes to memory.
+         *
+         *  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) {}
+
+        ZeroInitialized fZeroInitialized;

[djsollen, 2015/03/06 20:41:57]

I could go either way, but why not bool fZeroInitializedMemory?  What does the
enum get you?

[scroggo, 2015/03/06 20:54:25]

I'm fine with adding Memory to the name.
Clarity. When I look at a caller of SkSwizzler::Create, e.g. in SkPngCodec:

  SkSwizzler::CreateSwizzler(sc, colors, requestedInfo,dst, rowBytes, false)

it's not obvious what "false" means. However, if it's written as:

  SkSwizzler::CreateSwizzler(sc, colors, requestedInfo,dst, rowBytes,
                             kNo_ZeroInitialized)

it's obvious what the caller wanted (maybe it should be
kNot_ZeroInitialized[Memory]? and then kIs_ZeroInitialized[Memory] to match?).
It also means we don't have to remember whether the bool meant zero initialized
or the opposite.

This is another instance where nothing has been codified, but in a very
unscientific survey, reed@ likes this convention (enum instead of bool for API),
and others have supported it as well.

[djsollen, 2015/03/06 21:14:48]

The API as it stands is fine with me.

+    };
+
+    /**
      *  Decode into the given pixels, a block of memory of size at
      *  least (info.fHeight - 1) * rowBytes + (info.fWidth *
      *  bytesPerPixel)
@@ -145,11 +175,12 @@ public:
      *
      *  @return Result kSuccess, or another value explaining the type of failure.
      */
-    Result getPixels(const SkImageInfo& info, void* pixels, size_t rowBytes,
+    Result getPixels(const SkImageInfo& info, void* pixels, size_t rowBytes, const Options*,
                      SkPMColor ctable[], int* ctableCount);
 
     /**
-     *  Simplified version of getPixels() that asserts that info is NOT kIndex8_SkColorType.
+     *  Simplified version of getPixels() that asserts that info is NOT kIndex8_SkColorType and
+     *  uses the default Options.
      */
     Result getPixels(const SkImageInfo& info, void* pixels, size_t rowBytes);
 
@@ -177,9 +208,14 @@ public:
 protected:
     virtual SkData* onRefEncodedData();
     virtual bool onGetInfo(SkImageInfo* info);
+#ifdef SK_SUPPORT_LEGACY_OPTIONLESS_GET_PIXELS
     virtual Result onGetPixels(const SkImageInfo& info,
                                void* pixels, size_t rowBytes,
                                SkPMColor ctable[], int* ctableCount);
+#endif
+    virtual Result onGetPixels(const SkImageInfo& info,
+                               void* pixels, size_t rowBytes, const Options&,
+                               SkPMColor ctable[], int* ctableCount);
     virtual bool onGetYUV8Planes(SkISize sizes[3], void* planes[3], size_t rowBytes[3]);
     virtual bool onGetYUV8Planes(SkISize sizes[3], void* planes[3], size_t rowBytes[3],
                                  SkYUVColorSpace* colorSpace);