Change SkDecodingImageGenerator API

src/images/SkDecodingImageGenerator.h

 /*
  * Copyright 2013 Google Inc.
  *
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
  */
 
 #ifndef SkDecodingImageGenerator_DEFINED
 #define SkDecodingImageGenerator_DEFINED
 
-#include "SkDiscardableMemory.h"
-#include "SkImageGenerator.h"
-#include "SkImageInfo.h"
+#include "SkBitmap.h"
 
-class SkBitmap;
+class SkData;
+class SkImageGenerator;
 class SkStreamRewindable;
 
 /**
- * Calls into SkImageDecoder::DecodeMemoryToTarget to implement a
- * SkImageGenerator
+ *  These options will be passed on to the image decoder.  The
+ *  defaults are sensible.
+ *
+ *  @param fSampleSize If set to > 1, tells the decoder to return a
+ *         smaller than original bitmap, sampling 1 pixel for
+ *         every size pixels. e.g. if sample size is set to 3,
+ *         then the returned bitmap will be 1/3 as wide and high,
+ *         and will contain 1/9 as many pixels as the original.
+ *         Note: this is a hint, and the codec may choose to
+ *         ignore this, or only approximate the sample size.
+ *
+ *  @param fDitherImage Set to true if the the decoder should try to
+ *         dither the resulting image when decoding to a smaller
+ *         color-space.  The default is true.
+ *
+ *  @param fRequestedConfig If SkBitmap::kNo_Config, then use
+ *         whichever config the decoder wants.  Else try to use this
+ *         config.  If the decoder won't support this config,
+ *         SkNewDecodingImageGenerator will return NULL.
  */
-class SkDecodingImageGenerator : public SkImageGenerator {
-public:
-    /*
-     *  The constructor will take a reference to the SkData.  The
-     *  destructor will unref() it.
-     */
-    explicit SkDecodingImageGenerator(SkData* data);
+struct SK_API SkDecoderOptions {

[reed1, 2013/12/17 17:38:52]

Do these need to appear anywhere w/o the generator? If not, can we make this a
nested struct inside the generator? That is slightly clearer for name spacing.

[hal.canary, 2013/12/17 21:00:22]

okay.  I'll have to move the generator definition back to the header.

+    SkDecoderOptions()
+        : fSampleSize(1)
+        , fDitherImage(true)
+        , fRequestedConfig(SkBitmap::kNo_Config) { }
+    SkDecoderOptions(int sampleSize, bool dither, SkBitmap::Config config)
+        : fSampleSize(sampleSize)
+        , fDitherImage(dither)
+        , fRequestedConfig(config) { }
+    const int              fSampleSize;
+    const bool             fDitherImage;
+    const SkBitmap::Config fRequestedConfig;

[reed1, 2013/12/17 17:38:52]

1. Can we replace config with SkColorType
2. Can we use SkImageInfo instead of samplesize?

[hal.canary, 2013/12/17 21:00:22]

1. Yes.  Done.

2. No: the samplesize is interpreted differently by each decoder - sometimes
they round up, and sometimes they round down after a divide.  There is no way
for the caller to know how that will happen.

+};
 
-    /*
-     *  The SkData version of this constructor is preferred.  If the
-     *  stream has an underlying SkData (such as a SkMemoryStream)
-     *  pass that in.
-     *
-     *  This object will unref the stream when done.  Since streams
-     *  have internal state (position), the caller should not pass a
-     *  shared stream in.  Pass either a new duplicated stream in or
-     *  transfer ownership of the stream.  In the latter case, be sure
-     *  that there are no other consumers of the stream who will
-     *  modify the stream's position.  This constructor asserts
-     *  stream->unique().
-     *
-     *  For example:
-     *    SkStreamRewindable* stream;
-     *    ...
-     *    SkImageGenerator* gen
-     *        = SkNEW_ARGS(SkDecodingImageGenerator,
-     *                     (stream->duplicate()));
-     *    ...
-     *    SkDELETE(gen);
-     */
-    explicit SkDecodingImageGenerator(SkStreamRewindable* stream);
+/**
+ *  These two functions return a SkImageGenerator that calls into
+ *  SkImageDecoder.  They return NULL on failure.
+ *
+ *  The SkData version of this function is preferred.  If the stream
+ *  has an underlying SkData (such as a SkMemoryStream) pass that in.
+ *
+ *  This object will unref the stream when done or on failure.  Since
+ *  streams have internal state (position), the caller should not pass
+ *  a shared stream in.  Pass either a new duplicated stream in or
+ *  transfer ownership of the stream.  This factory asserts
+ *  stream->unique().
+ *
+ *  For example:
+ *    SkStreamRewindable* stream;
+ *    ...
+ *    SkImageGenerator* gen
+ *        = SkNewDecodingImageGenerator(
+ *            stream->duplicate(), SkDecoderOptions());
+ *    ...
+ *    SkDELETE(gen);
+ *
+ *  @param SkDecoderOptions (see above)
+ *
+ *  @return NULL on failure, a new SkImageGenerator on success.
+ */
+SK_API SkImageGenerator* SkNewDecodingImageGenerator(SkStreamRewindable* stream,
+                                                     const SkDecoderOptions& opt);
 
-    virtual ~SkDecodingImageGenerator();
+/**
+ *  @param data Contains the encoded image data that will be used by
+ *         the SkDecodingImageGenerator.  Will be ref()ed by the
+ *         SkImageGenerator constructor and and unref()ed on deletion.
+ */
+SK_API SkImageGenerator* SkNewDecodingImageGenerator(SkData* data,
+                                                     const SkDecoderOptions& opt);
 
-    virtual SkData* refEncodedData() SK_OVERRIDE;
+//  // Example of most basic use case:
+//
+//  bool install_data(SkData* data, SkBitmap* dst) {
+//     return SkInstallDiscardablePixelRef(
+//         SkNewDecodingImageGenerator(data, SkDecoderOptions()), dst, NULL);
+//  }
+//  bool install_stream(SkStreamRewindable* stream, SkBitmap* dst) {
+//     return SkInstallDiscardablePixelRef(
+//         SkNewDecodingImageGenerator(stream, SkDecoderOptions()), dst, NULL);
+//  }
 
-    virtual bool getInfo(SkImageInfo* info) SK_OVERRIDE;
-
-    virtual bool getPixels(const SkImageInfo& info,
-                           void* pixels,
-                           size_t rowBytes) SK_OVERRIDE;
-
-    /**
-     *  Install the SkData into the destination bitmap, using a new
-     *  SkDiscardablePixelRef and a new SkDecodingImageGenerator.
-     *
-     *  @param data Contains the encoded image data that will be used
-     *  by the SkDecodingImageGenerator.  Will be ref()ed.
-     *
-     *  @param destination Upon success, this bitmap will be
-     *  configured and have a pixelref installed.
-     *
-     *  @param factory If not NULL, this object will be used as a
-     *  source of discardable memory when decoding.  If NULL, then
-     *  SkDiscardableMemory::Create() will be called.
-     *
-     *  @return true iff successful.
-     */
-    static bool Install(SkData* data, SkBitmap* destination,
-                        SkDiscardableMemory::Factory* factory = NULL);
-    /**
-     *  Install the stream into the destination bitmap, using a new
-     *  SkDiscardablePixelRef and a new SkDecodingImageGenerator.
-     *
-     *  The SkData version of this function is preferred.  If the
-     *  stream has an underlying SkData (such as a SkMemoryStream)
-     *  pass that in.
-     *
-     *  @param stream The source of encoded data that will be passed
-     *  to the decoder.  The installed SkDecodingImageGenerator will
-     *  unref the stream when done.  If false is returned, this
-     *  function will perform the unref.  Since streams have internal
-     *  state (position), the caller should not pass a shared stream
-     *  in.  Pass either a new duplicated stream in or transfer
-     *  ownership of the stream.  In the latter case, be sure that
-     *  there are no other consumers of the stream who will modify the
-     *  stream's position.  This function will fail if
-     *  (!stream->unique()).
-     *
-     *  @param destination Upon success, this bitmap will be
-     *  configured and have a pixelref installed.
-     *
-     *  @param factory If not NULL, this object will be used as a
-     *  source of discardable memory when decoding.  If NULL, then
-     *  SkDiscardableMemory::Create() will be called.
-     *
-     *  @return true iff successful.
-     */
-    static bool Install(SkStreamRewindable* stream, SkBitmap* destination,
-                        SkDiscardableMemory::Factory* factory = NULL);
-
-private:
-    SkData*             fData;
-    SkStreamRewindable* fStream;
-    SkImageInfo         fInfo;
-    bool                fHasInfo;
-    bool                fDoCopyTo;
-};
 #endif  // SkDecodingImageGenerator_DEFINED