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 SkImageGenerator_DEFINED
9#define SkImageGenerator_DEFINED
10
11#include "include/core/SkBitmap.h"
12#include "include/core/SkColor.h"
13#include "include/core/SkImage.h"
14#include "include/core/SkImageInfo.h"
15#include "include/core/SkYUVAPixmaps.h"
16
17class GrRecordingContext;
18class GrSurfaceProxyView;
19class GrSamplerState;
20class SkBitmap;
21class SkData;
22class SkMatrix;
23class SkPaint;
24class SkPicture;
25
26enum class GrImageTexGenPolicy : int;
27
28class SK_API SkImageGenerator {
29public:
30    /**
31     *  The PixelRef which takes ownership of this SkImageGenerator
32     *  will call the image generator's destructor.
33     */
34    virtual ~SkImageGenerator() { }
35
36    uint32_t uniqueID() const { return fUniqueID; }
37
38    /**
39     *  Return a ref to the encoded (i.e. compressed) representation
40     *  of this data.
41     *
42     *  If non-NULL is returned, the caller is responsible for calling
43     *  unref() on the data when it is finished.
44     */
45    sk_sp<SkData> refEncodedData() {
46        return this->onRefEncodedData();
47    }
48
49    /**
50     *  Return the ImageInfo associated with this generator.
51     */
52    const SkImageInfo& getInfo() const { return fInfo; }
53
54    /**
55     *  Can this generator be used to produce images that will be drawable to the specified context
56     *  (or to CPU, if context is nullptr)?
57     */
58    bool isValid(GrRecordingContext* context) const {
59        return this->onIsValid(context);
60    }
61
62    /**
63     *  Decode into the given pixels, a block of memory of size at
64     *  least (info.fHeight - 1) * rowBytes + (info.fWidth *
65     *  bytesPerPixel)
66     *
67     *  Repeated calls to this function should give the same results,
68     *  allowing the PixelRef to be immutable.
69     *
70     *  @param info A description of the format
71     *         expected by the caller.  This can simply be identical
72     *         to the info returned by getInfo().
73     *
74     *         This contract also allows the caller to specify
75     *         different output-configs, which the implementation can
76     *         decide to support or not.
77     *
78     *         A size that does not match getInfo() implies a request
79     *         to scale. If the generator cannot perform this scale,
80     *         it will return false.
81     *
82     *  @return true on success.
83     */
84    bool getPixels(const SkImageInfo& info, void* pixels, size_t rowBytes);
85
86    bool getPixels(const SkPixmap& pm) {
87        return this->getPixels(pm.info(), pm.writable_addr(), pm.rowBytes());
88    }
89
90    /**
91     *  If decoding to YUV is supported, this returns true. Otherwise, this
92     *  returns false and the caller will ignore output parameter yuvaPixmapInfo.
93     *
94     * @param  supportedDataTypes Indicates the data type/planar config combinations that are
95     *                            supported by the caller. If the generator supports decoding to
96     *                            YUV(A), but not as a type in supportedDataTypes, this method
97     *                            returns false.
98     *  @param yuvaPixmapInfo Output parameter that specifies the planar configuration, subsampling,
99     *                        orientation, chroma siting, plane color types, and row bytes.
100     */
101    bool queryYUVAInfo(const SkYUVAPixmapInfo::SupportedDataTypes& supportedDataTypes,
102                       SkYUVAPixmapInfo* yuvaPixmapInfo) const;
103
104    /**
105     *  Returns true on success and false on failure.
106     *  This always attempts to perform a full decode. To get the planar
107     *  configuration without decoding use queryYUVAInfo().
108     *
109     *  @param yuvaPixmaps  Contains preallocated pixmaps configured according to a successful call
110     *                      to queryYUVAInfo().
111     */
112    bool getYUVAPlanes(const SkYUVAPixmaps& yuvaPixmaps);
113
114#if SK_SUPPORT_GPU
115    /**
116     *  If the generator can natively/efficiently return its pixels as a GPU image (backed by a
117     *  texture) this will return that image. If not, this will return NULL.
118     *
119     *  This routine also supports retrieving only a subset of the pixels. That subset is specified
120     *  by the following rectangle:
121     *
122     *      subset = SkIRect::MakeXYWH(origin.x(), origin.y(), info.width(), info.height())
123     *
124     *  If subset is not contained inside the generator's bounds, this returns false.
125     *
126     *      whole = SkIRect::MakeWH(getInfo().width(), getInfo().height())
127     *      if (!whole.contains(subset)) {
128     *          return false;
129     *      }
130     *
131     *  Regarding the GrRecordingContext parameter:
132     *
133     *  It must be non-NULL. The generator should only succeed if:
134     *  - its internal context is the same
135     *  - it can somehow convert its texture into one that is valid for the provided context.
136     *
137     *  If the willNeedMipMaps flag is true, the generator should try to create a TextureProxy that
138     *  at least has the mip levels allocated and the base layer filled in. If this is not possible,
139     *  the generator is allowed to return a non mipped proxy, but this will have some additional
140     *  overhead in later allocating mips and copying of the base layer.
141     *
142     *  GrImageTexGenPolicy determines whether or not a new texture must be created (and its budget
143     *  status) or whether this may (but is not required to) return a pre-existing texture that is
144     *  retained by the generator (kDraw).
145     */
146    GrSurfaceProxyView generateTexture(GrRecordingContext*, const SkImageInfo& info,
147                                       const SkIPoint& origin, GrMipmapped, GrImageTexGenPolicy);
148
149#endif
150
151    /**
152     *  If the default image decoder system can interpret the specified (encoded) data, then
153     *  this returns a new ImageGenerator for it. Otherwise this returns NULL. Either way
154     *  the caller is still responsible for managing their ownership of the data.
155     */
156    static std::unique_ptr<SkImageGenerator> MakeFromEncoded(sk_sp<SkData>);
157
158    /** Return a new image generator backed by the specified picture.  If the size is empty or
159     *  the picture is NULL, this returns NULL.
160     *  The optional matrix and paint arguments are passed to drawPicture() at rasterization
161     *  time.
162     */
163    static std::unique_ptr<SkImageGenerator> MakeFromPicture(const SkISize&, sk_sp<SkPicture>,
164                                                             const SkMatrix*, const SkPaint*,
165                                                             SkImage::BitDepth,
166                                                             sk_sp<SkColorSpace>);
167
168protected:
169    static constexpr int kNeedNewImageUniqueID = 0;
170
171    SkImageGenerator(const SkImageInfo& info, uint32_t uniqueId = kNeedNewImageUniqueID);
172
173    virtual sk_sp<SkData> onRefEncodedData() { return nullptr; }
174    struct Options {};
175    virtual bool onGetPixels(const SkImageInfo&, void*, size_t, const Options&) { return false; }
176    virtual bool onIsValid(GrRecordingContext*) const { return true; }
177    virtual bool onQueryYUVAInfo(const SkYUVAPixmapInfo::SupportedDataTypes&,
178                                 SkYUVAPixmapInfo*) const { return false; }
179    virtual bool onGetYUVAPlanes(const SkYUVAPixmaps&) { return false; }
180#if SK_SUPPORT_GPU
181    // returns nullptr
182    virtual GrSurfaceProxyView onGenerateTexture(GrRecordingContext*, const SkImageInfo&,
183                                                 const SkIPoint&, GrMipmapped, GrImageTexGenPolicy);
184#endif
185
186private:
187    const SkImageInfo fInfo;
188    const uint32_t fUniqueID;
189
190    friend class SkImage_Lazy;
191
192    // This is our default impl, which may be different on different platforms.
193    // It is called from NewFromEncoded() after it has checked for any runtime factory.
194    // The SkData will never be NULL, as that will have been checked by NewFromEncoded.
195    static std::unique_ptr<SkImageGenerator> MakeFromEncodedImpl(sk_sp<SkData>);
196
197    SkImageGenerator(SkImageGenerator&&) = delete;
198    SkImageGenerator(const SkImageGenerator&) = delete;
199    SkImageGenerator& operator=(SkImageGenerator&&) = delete;
200    SkImageGenerator& operator=(const SkImageGenerator&) = delete;
201};
202
203#endif  // SkImageGenerator_DEFINED
204