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
14class SkData;
15class SkStreamRewindable;
16
17/**
18 *  An implementation of SkImageGenerator that calls into
19 *  SkImageDecoder.
20 */
21namespace 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 {
49        Options()
50            : fSampleSize(1)
51            , fDitherImage(true)
52            , fUseRequestedColorType(false)
53            , fRequestedColorType()
54            , fRequireUnpremul(false) { }
55        Options(int sampleSize, bool dither)
56            : fSampleSize(sampleSize)
57            , fDitherImage(dither)
58            , fUseRequestedColorType(false)
59            , fRequestedColorType()
60            , fRequireUnpremul(false) { }
61        Options(int sampleSize, bool dither, SkColorType colorType)
62            : fSampleSize(sampleSize)
63            , fDitherImage(dither)
64            , fUseRequestedColorType(true)
65            , fRequestedColorType(colorType)
66            , fRequireUnpremul(false) { }
67         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