1 /*
2  * Copyright 2013 Google Inc.
3  *
4  * Use of this source code is governed by a BSD-style license that can be
5  * found in the LICENSE file.
6  */
7 
8 #ifndef SkDecodingImageGenerator_DEFINED
9 #define SkDecodingImageGenerator_DEFINED
10 
11 #include "SkBitmap.h"
12 #include "SkImageGenerator.h"
13 
14 class SkData;
15 class SkStreamRewindable;
16 
17 /**
18  *  An implementation of SkImageGenerator that calls into
19  *  SkImageDecoder.
20  */
21 namespace SkDecodingImageGenerator {
22     /**
23      *  These options will be passed on to the image decoder.  The
24      *  defaults are sensible.
25      *
26      *  @param fSampleSize If set to > 1, tells the decoder to return a
27      *         smaller than original bitmap, sampling 1 pixel for
28      *         every size pixels. e.g. if sample size is set to 3,
29      *         then the returned bitmap will be 1/3 as wide and high,
30      *         and will contain 1/9 as many pixels as the original.
31      *         Note: this is a hint, and the codec may choose to
32      *         ignore this, or only approximate the sample size.
33      *
34      *  @param fDitherImage Set to true if the the decoder should try to
35      *         dither the resulting image when decoding to a smaller
36      *         color-space.  The default is true.
37      *
38      *  @param fRequestedColorType If not given, then use whichever
39      *         config the decoder wants.  Else try to use this color
40      *         type.  If the decoder won't support this color type,
41      *         SkDecodingImageGenerator::Create will return
42      *         NULL. kIndex_8_SkColorType is not supported.
43      *
44      *  @param fRequireUnpremul If true, the decoder will attempt to
45      *         decode without premultiplying the alpha. If it cannot,
46      *         the pixels will be set to NULL.
47      */
48     struct Options {
OptionsOptions49         Options()
50             : fSampleSize(1)
51             , fDitherImage(true)
52             , fUseRequestedColorType(false)
53             , fRequestedColorType()
54             , fRequireUnpremul(false) { }
OptionsOptions55         Options(int sampleSize, bool dither)
56             : fSampleSize(sampleSize)
57             , fDitherImage(dither)
58             , fUseRequestedColorType(false)
59             , fRequestedColorType()
60             , fRequireUnpremul(false) { }
OptionsOptions61         Options(int sampleSize, bool dither, SkColorType colorType)
62             : fSampleSize(sampleSize)
63             , fDitherImage(dither)
64             , fUseRequestedColorType(true)
65             , fRequestedColorType(colorType)
66             , fRequireUnpremul(false) { }
OptionsOptions67          Options(int sampleSize, bool dither, SkColorType colorType,
68                  bool requireUnpremul)
69             : fSampleSize(sampleSize)
70             , fDitherImage(dither)
71             , fUseRequestedColorType(true)
72             , fRequestedColorType(colorType)
73             , fRequireUnpremul(requireUnpremul) { }
74         const int         fSampleSize;
75         const bool        fDitherImage;
76         const bool        fUseRequestedColorType;
77         const SkColorType fRequestedColorType;
78         const bool        fRequireUnpremul;
79     };
80 
81     /**
82      *  These two functions return a SkImageGenerator that calls into
83      *  SkImageDecoder.  They return NULL on failure.
84      *
85      *  The SkData version of this function is preferred.  If the stream
86      *  has an underlying SkData (such as a SkMemoryStream) pass that in.
87      *
88      *  This object, if non-NULL, takes ownership of stream and deletes stream
89      *  upon deletion. If NULL is returned, stream is deleted immediately.
90      *
91      *  @param Options (see above)
92      *
93      *  @return NULL on failure, a new SkImageGenerator on success.
94      */
95     SkImageGenerator* Create(SkStreamRewindable* stream,
96                              const Options& opt);
97 
98     /**
99      *  @param data Contains the encoded image data that will be used by
100      *         the SkDecodingImageGenerator.  Will be ref()ed by the
101      *         SkImageGenerator constructor and and unref()ed on deletion.
102      */
103     SkImageGenerator* Create(SkData* data, const Options& opt);
104 };
105 
106 //  // Example of most basic use case:
107 //
108 //  bool install_data(SkData* data, SkBitmap* dst) {
109 //     return SkInstallDiscardablePixelRef(
110 //         SkDecodingImageGenerator::Create(
111 //             data, SkDecodingImageGenerator::Options()), dst, NULL);
112 //  }
113 //  bool install_stream(SkStreamRewindable* stream, SkBitmap* dst) {
114 //     return SkInstallDiscardablePixelRef(
115 //         SkDecodingImageGenerator::Create(
116 //             stream, SkDecodingImageGenerator::Options()), dst, NULL);
117 //  }
118 
119 #endif  // SkDecodingImageGenerator_DEFINED
120