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