SkImage.h revision 759373a9fe73a7883d007254193084a541714b40 
1/*
2 * Copyright 2012 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 SkImage_DEFINED
9#define SkImage_DEFINED
10
11#include "SkFilterQuality.h"
12#include "SkImageInfo.h"
13#include "SkImageEncoder.h"
14#include "SkRefCnt.h"
15#include "SkScalar.h"
16#include "SkShader.h"
17
18class SkData;
19class SkCanvas;
20class SkColorTable;
21class SkImageGenerator;
22class SkPaint;
23class SkString;
24class SkSurface;
25class SkSurfaceProps;
26class GrContext;
27class GrTexture;
28
29/**
30 *  SkImage is an abstraction for drawing a rectagle of pixels, though the
31 *  particular type of image could be actually storing its data on the GPU, or
32 *  as drawing commands (picture or PDF or otherwise), ready to be played back
33 *  into another canvas.
34 *
35 *  The content of SkImage is always immutable, though the actual storage may
36 *  change, if for example that image can be re-created via encoded data or
37 *  other means.
38 *
39 *  SkImage always has a non-zero dimensions. If there is a request to create a new image, either
40 *  directly or via SkSurface, and either of the requested dimensions are zero, then NULL will be
41 *  returned.
42 */
43class SK_API SkImage : public SkRefCnt {
44public:
45    typedef SkImageInfo Info;
46    typedef void* ReleaseContext;
47
48    static SkImage* NewRasterCopy(const Info&, const void* pixels, size_t rowBytes,
49                                  SkColorTable* ctable = NULL);
50    static SkImage* NewRasterData(const Info&, SkData* pixels, size_t rowBytes);
51
52    typedef void (*RasterReleaseProc)(const void* pixels, ReleaseContext);
53
54    /**
55     *  Return a new Image referencing the specified pixels. These must remain valid and unchanged
56     *  until the specified release-proc is called, indicating that Skia no longer has a reference
57     *  to the pixels.
58     *
59     *  Returns NULL if the requested Info is unsupported.
60     */
61    static SkImage* NewFromRaster(const Info&, const void* pixels, size_t rowBytes,
62                                  RasterReleaseProc, ReleaseContext);
63
64    /**
65     *  Construct a new SkImage based on the given ImageGenerator.
66     *  This function will always take ownership of the passed
67     *  ImageGenerator.  Returns NULL on error.
68     *
69     *  If a subset is specified, it must be contained within the generator's bounds.
70     */
71    static SkImage* NewFromGenerator(SkImageGenerator*, const SkIRect* subset = NULL);
72
73    /**
74     *  Construct a new SkImage based on the specified encoded data. Returns NULL on failure,
75     *  which can mean that the format of the encoded data was not recognized/supported.
76     *
77     *  If a subset is specified, it must be contained within the encoded data's bounds.
78     *
79     *  Regardless of success or failure, the caller is responsible for managing their ownership
80     *  of the data.
81     */
82    static SkImage* NewFromEncoded(SkData* encoded, const SkIRect* subset = NULL);
83
84    /**
85     *  Create a new image from the specified descriptor. Note - the caller is responsible for
86     *  managing the lifetime of the underlying platform texture.
87     *
88     *  Will return NULL if the specified descriptor is unsupported.
89     */
90    static SkImage* NewFromTexture(GrContext* ctx, const GrBackendTextureDesc& desc) {
91        return NewFromTexture(ctx, desc, kPremul_SkAlphaType, NULL, NULL);
92    }
93
94    static SkImage* NewFromTexture(GrContext* ctx, const GrBackendTextureDesc& de, SkAlphaType at) {
95        return NewFromTexture(ctx, de, at, NULL, NULL);
96    }
97
98    typedef void (*TextureReleaseProc)(ReleaseContext);
99
100    /**
101     *  Create a new image from the specified descriptor. The underlying platform texture must stay
102     *  valid and unaltered until the specified release-proc is invoked, indicating that Skia
103     *  nolonger is holding a reference to it.
104     *
105     *  Will return NULL if the specified descriptor is unsupported.
106     */
107    static SkImage* NewFromTexture(GrContext*, const GrBackendTextureDesc&, SkAlphaType,
108                                   TextureReleaseProc, ReleaseContext);
109
110    /**
111     *  Create a new image from the specified descriptor. Note - Skia will delete or recycle the
112     *  texture when the image is released.
113     *
114     *  Will return NULL if the specified descriptor is unsupported.
115     */
116    static SkImage* NewFromAdoptedTexture(GrContext*, const GrBackendTextureDesc&,
117                                          SkAlphaType = kPremul_SkAlphaType);
118
119    /**
120     *  Create a new image by copying the pixels from the specified descriptor. No reference is
121     *  kept to the original platform texture.
122     *
123     *  Will return NULL if the specified descriptor is unsupported.
124     */
125    static SkImage* NewFromTextureCopy(GrContext*, const GrBackendTextureDesc&,
126                                       SkAlphaType = kPremul_SkAlphaType);
127
128    /**
129     *  Create a new image by copying the pixels from the specified y, u, v textures. The data
130     *  from the textures is immediately ingested into the image and the textures can be modified or
131     *  deleted after the function returns. The image will have the dimensions of the y texture.
132     */
133    static SkImage* NewFromYUVTexturesCopy(GrContext*, SkYUVColorSpace,
134                                           const GrBackendObject yuvTextureHandles[3],
135                                           const SkISize yuvSizes[3],
136                                           GrSurfaceOrigin);
137
138    int width() const { return fWidth; }
139    int height() const { return fHeight; }
140    uint32_t uniqueID() const { return fUniqueID; }
141    virtual bool isOpaque() const { return false; }
142
143    virtual SkShader* newShader(SkShader::TileMode,
144                                SkShader::TileMode,
145                                const SkMatrix* localMatrix = NULL) const;
146
147    /**
148     *  If the image has direct access to its pixels (i.e. they are in local
149     *  RAM) return the (const) address of those pixels, and if not null, return
150     *  the ImageInfo and rowBytes. The returned address is only valid while
151     *  the image object is in scope.
152     *
153     *  On failure, returns NULL and the info and rowBytes parameters are
154     *  ignored.
155     */
156    const void* peekPixels(SkImageInfo* info, size_t* rowBytes) const;
157
158    /**
159     *  If the image has direct access to its pixels (i.e. they are in local
160     *  RAM) return the (const) address of those pixels, and if not null, return
161     *  true, and if pixmap is not NULL, set it to point into the image.
162     *
163     *  On failure, return false and ignore the pixmap parameter.
164     */
165    bool peekPixels(SkPixmap* pixmap) const;
166
167    // DEPRECATED
168    GrTexture* getTexture() const;
169
170    /**
171     *  Returns true if the image is texture backed.
172     */
173    bool isTextureBacked() const;
174
175    /**
176     *  Retrieves the backend API handle of the texture. If flushPendingGrContextIO then the
177     *  GrContext will issue to the backend API any deferred IO operations on the texture before
178     *  returning.
179     */
180    GrBackendObject getTextureHandle(bool flushPendingGrContextIO) const;
181
182    /**
183     *  Copy the pixels from the image into the specified buffer (pixels + rowBytes),
184     *  converting them into the requested format (dstInfo). The image pixels are read
185     *  starting at the specified (srcX,srcY) location.
186     *
187     *  The specified ImageInfo and (srcX,srcY) offset specifies a source rectangle
188     *
189     *      srcR.setXYWH(srcX, srcY, dstInfo.width(), dstInfo.height());
190     *
191     *  srcR is intersected with the bounds of the image. If this intersection is not empty,
192     *  then we have two sets of pixels (of equal size). Replace the dst pixels with the
193     *  corresponding src pixels, performing any colortype/alphatype transformations needed
194     *  (in the case where the src and dst have different colortypes or alphatypes).
195     *
196     *  This call can fail, returning false, for several reasons:
197     *  - If srcR does not intersect the image bounds.
198     *  - If the requested colortype/alphatype cannot be converted from the image's types.
199     */
200    bool readPixels(const SkImageInfo& dstInfo, void* dstPixels, size_t dstRowBytes,
201                    int srcX, int srcY) const;
202
203    bool readPixels(const SkPixmap& dst, int srcX, int srcY) const;
204
205    /**
206     *  Encode the image's pixels and return the result as a new SkData, which
207     *  the caller must manage (i.e. call unref() when they are done).
208     *
209     *  If the image type cannot be encoded, or the requested encoder type is
210     *  not supported, this will return NULL.
211     */
212    SkData* encode(SkImageEncoder::Type, int quality) const;
213
214    SkData* encode() const {
215        return this->encode(SkImageEncoder::kPNG_Type, 100);
216    }
217
218    /**
219     *  If the image already has its contents in encoded form (e.g. PNG or JPEG), return a ref
220     *  to that data (which the caller must call unref() on). The caller is responsible for calling
221     *  unref on the data when they are done.
222     *
223     *  If the image does not already has its contents in encoded form, return NULL.
224     *
225     *  Note: to force the image to return its contents as encoded data, try calling encode(...).
226     */
227    SkData* refEncoded() const;
228
229    /**
230     *  Return a new surface that is compatible with this image's internal representation
231     *  (e.g. raster or gpu).
232     *
233     *  If no surfaceprops are specified, the image will attempt to match the props of when it
234     *  was created (if it came from a surface).
235     */
236    SkSurface* newSurface(const SkImageInfo&, const SkSurfaceProps* = NULL) const;
237
238    const char* toString(SkString*) const;
239
240    /**
241     *  Return an image that is a rescale of this image (using newWidth, newHeight).
242     *
243     *  If subset is NULL, then the entire original image is used as the src for the scaling.
244     *  If subset is not NULL, then it specifies subset of src-pixels used for scaling. If
245     *  subset extends beyond the bounds of the original image, then NULL is returned.
246     *
247     *  Notes:
248     *  - newWidth and newHeight must be > 0 or NULL will be returned.
249     *
250     *  - it is legal for the returned image to be the same instance as the src image
251     *    (if the new dimensions == the src dimensions and subset is NULL or == src dimensions).
252     *
253     *  - it is legal for the "scaled" image to have changed its SkAlphaType from unpremul
254     *    to premul (as required by the impl). The image should draw (nearly) identically,
255     *    since during drawing we will "apply the alpha" to the pixels. Future optimizations
256     *    may take away this caveat, preserving unpremul.
257     */
258    SkImage* newImage(int newWidth, int newHeight, const SkIRect* subset = NULL,
259                      SkFilterQuality = kNone_SkFilterQuality) const;
260
261protected:
262    SkImage(int width, int height) :
263        fWidth(width),
264        fHeight(height),
265        fUniqueID(NextUniqueID()) {
266
267        SkASSERT(width > 0);
268        SkASSERT(height > 0);
269    }
270
271private:
272    const int       fWidth;
273    const int       fHeight;
274    const uint32_t  fUniqueID;
275
276    static uint32_t NextUniqueID();
277
278    typedef SkRefCnt INHERITED;
279};
280
281#endif
282