1 2/* 3 * Copyright 2010 The Android Open Source Project 4 * 5 * Use of this source code is governed by a BSD-style license that can be 6 * found in the LICENSE file. 7 */ 8 9 10#ifndef SkDevice_DEFINED 11#define SkDevice_DEFINED 12 13#include "SkRefCnt.h" 14#include "SkBitmap.h" 15#include "SkCanvas.h" 16#include "SkColor.h" 17#include "SkDeviceProperties.h" 18 19class SkClipStack; 20class SkDraw; 21struct SkIRect; 22class SkMatrix; 23class SkMetaData; 24class SkRegion; 25 26// This is an opaque class, not interpreted by skia 27class SkGpuRenderTarget; 28 29class SK_API SkDevice : public SkRefCnt { 30public: 31 SK_DECLARE_INST_COUNT(SkDevice) 32 33 /** 34 * Construct a new device with the specified bitmap as its backend. It is 35 * valid for the bitmap to have no pixels associated with it. In that case, 36 * any drawing to this device will have no effect. 37 */ 38 SkDevice(const SkBitmap& bitmap); 39 40 /** 41 * Construct a new device with the specified bitmap as its backend. It is 42 * valid for the bitmap to have no pixels associated with it. In that case, 43 * any drawing to this device will have no effect. 44 */ 45 SkDevice(const SkBitmap& bitmap, const SkDeviceProperties& deviceProperties); 46 47 /** 48 * Create a new raster device and have the pixels be automatically 49 * allocated. The rowBytes of the device will be computed automatically 50 * based on the config and the width. 51 * 52 * @param config The desired config for the pixels. If the request cannot 53 * be met, the closest matching support config will be used. 54 * @param width width (in pixels) of the device 55 * @param height height (in pixels) of the device 56 * @param isOpaque Set to true if it is known that all of the pixels will 57 * be drawn to opaquely. Used as an accelerator when drawing 58 * these pixels to another device. 59 */ 60 SkDevice(SkBitmap::Config config, int width, int height, bool isOpaque = false); 61 62 /** 63 * Create a new raster device and have the pixels be automatically 64 * allocated. The rowBytes of the device will be computed automatically 65 * based on the config and the width. 66 * 67 * @param config The desired config for the pixels. If the request cannot 68 * be met, the closest matching support config will be used. 69 * @param width width (in pixels) of the device 70 * @param height height (in pixels) of the device 71 * @param isOpaque Set to true if it is known that all of the pixels will 72 * be drawn to opaquely. Used as an accelerator when drawing 73 * these pixels to another device. 74 * @param deviceProperties Properties which affect compositing. 75 */ 76 SkDevice(SkBitmap::Config config, int width, int height, bool isOpaque, 77 const SkDeviceProperties& deviceProperties); 78 79 virtual ~SkDevice(); 80 81 /** 82 * Creates a device that is of the same type as this device (e.g. SW-raster, 83 * GPU, or PDF). The backing store for this device is created automatically 84 * (e.g. offscreen pixels or FBO or whatever is appropriate). 85 * 86 * @param width width of the device to create 87 * @param height height of the device to create 88 * @param isOpaque performance hint, set to true if you know that you will 89 * draw into this device such that all of the pixels will 90 * be opaque. 91 */ 92 SkDevice* createCompatibleDevice(SkBitmap::Config config, 93 int width, int height, 94 bool isOpaque); 95 96 SkMetaData& getMetaData(); 97 98 enum Capabilities { 99 kGL_Capability = 0x1, //!< mask indicating GL support 100 kVector_Capability = 0x2, //!< mask indicating a vector representation 101 kAll_Capabilities = 0x3 102 }; 103 virtual uint32_t getDeviceCapabilities() { return 0; } 104 105 /** Return the width of the device (in pixels). 106 */ 107 virtual int width() const { return fBitmap.width(); } 108 /** Return the height of the device (in pixels). 109 */ 110 virtual int height() const { return fBitmap.height(); } 111 112 /** Return the image properties of the device. */ 113 virtual const SkDeviceProperties& getDeviceProperties() const { 114 //Currently, all the properties are leaky. 115 return fLeakyProperties; 116 } 117 118 /** 119 * Return the bounds of the device in the coordinate space of the root 120 * canvas. The root device will have its top-left at 0,0, but other devices 121 * such as those associated with saveLayer may have a non-zero origin. 122 */ 123 void getGlobalBounds(SkIRect* bounds) const; 124 125 /** Returns true if the device's bitmap's config treats every pixels as 126 implicitly opaque. 127 */ 128 bool isOpaque() const { return fBitmap.isOpaque(); } 129 130 /** Return the bitmap config of the device's pixels 131 */ 132 SkBitmap::Config config() const { return fBitmap.getConfig(); } 133 134 /** Return the bitmap associated with this device. Call this each time you need 135 to access the bitmap, as it notifies the subclass to perform any flushing 136 etc. before you examine the pixels. 137 @param changePixels set to true if the caller plans to change the pixels 138 @return the device's bitmap 139 */ 140 const SkBitmap& accessBitmap(bool changePixels); 141 142 /** 143 * DEPRECATED: This will be made protected once WebKit stops using it. 144 * Instead use Canvas' writePixels method. 145 * 146 * Similar to draw sprite, this method will copy the pixels in bitmap onto 147 * the device, with the top/left corner specified by (x, y). The pixel 148 * values in the device are completely replaced: there is no blending. 149 * 150 * Currently if bitmap is backed by a texture this is a no-op. This may be 151 * relaxed in the future. 152 * 153 * If the bitmap has config kARGB_8888_Config then the config8888 param 154 * will determines how the pixel valuess are intepreted. If the bitmap is 155 * not kARGB_8888_Config then this parameter is ignored. 156 */ 157 virtual void writePixels(const SkBitmap& bitmap, int x, int y, 158 SkCanvas::Config8888 config8888 = SkCanvas::kNative_Premul_Config8888); 159 160 /** 161 * Return the device's associated gpu render target, or NULL. 162 */ 163 virtual SkGpuRenderTarget* accessRenderTarget() { return NULL; } 164 165 166 /** 167 * Return the device's origin: its offset in device coordinates from 168 * the default origin in its canvas' matrix/clip 169 */ 170 const SkIPoint& getOrigin() const { return fOrigin; } 171 172 /** 173 * onAttachToCanvas is invoked whenever a device is installed in a canvas 174 * (i.e., setDevice, saveLayer (for the new device created by the save), 175 * and SkCanvas' SkDevice & SkBitmap -taking ctors). It allows the 176 * devices to prepare for drawing (e.g., locking their pixels, etc.) 177 */ 178 virtual void onAttachToCanvas(SkCanvas* canvas) { 179 SkASSERT(!fAttachedToCanvas); 180 this->lockPixels(); 181#ifdef SK_DEBUG 182 fAttachedToCanvas = true; 183#endif 184 }; 185 186 /** 187 * onDetachFromCanvas notifies a device that it will no longer be drawn to. 188 * It gives the device a chance to clean up (e.g., unlock its pixels). It 189 * is invoked from setDevice (for the displaced device), restore and 190 * possibly from SkCanvas' dtor. 191 */ 192 virtual void onDetachFromCanvas() { 193 SkASSERT(fAttachedToCanvas); 194 this->unlockPixels(); 195#ifdef SK_DEBUG 196 fAttachedToCanvas = false; 197#endif 198 }; 199 200protected: 201 enum Usage { 202 kGeneral_Usage, 203 kSaveLayer_Usage // <! internal use only 204 }; 205 206 struct TextFlags { 207 uint32_t fFlags; // SkPaint::getFlags() 208 SkPaint::Hinting fHinting; 209 }; 210 211 /** 212 * Device may filter the text flags for drawing text here. If it wants to 213 * make a change to the specified values, it should write them into the 214 * textflags parameter (output) and return true. If the paint is fine as 215 * is, then ignore the textflags parameter and return false. 216 * 217 * The baseclass SkDevice filters based on its depth and blitters. 218 */ 219 virtual bool filterTextFlags(const SkPaint& paint, TextFlags*); 220 221 /** 222 * 223 * DEPRECATED: This will be removed in a future change. Device subclasses 224 * should use the matrix and clip from the SkDraw passed to draw functions. 225 * 226 * Called with the correct matrix and clip before this device is drawn 227 * to using those settings. If your subclass overrides this, be sure to 228 * call through to the base class as well. 229 * 230 * The clipstack is another view of the clip. It records the actual 231 * geometry that went into building the region. It is present for devices 232 * that want to parse it, but is not required: the region is a complete 233 * picture of the current clip. (i.e. if you regionize all of the geometry 234 * in the clipstack, you will arrive at an equivalent region to the one 235 * passed in). 236 */ 237 virtual void setMatrixClip(const SkMatrix&, const SkRegion&, 238 const SkClipStack&); 239 240 /** Clears the entire device to the specified color (including alpha). 241 * Ignores the clip. 242 */ 243 virtual void clear(SkColor color); 244 245 /** 246 * Deprecated name for clear. 247 */ 248 void eraseColor(SkColor eraseColor) { this->clear(eraseColor); } 249 250 /** These are called inside the per-device-layer loop for each draw call. 251 When these are called, we have already applied any saveLayer operations, 252 and are handling any looping from the paint, and any effects from the 253 DrawFilter. 254 */ 255 virtual void drawPaint(const SkDraw&, const SkPaint& paint); 256 virtual void drawPoints(const SkDraw&, SkCanvas::PointMode mode, size_t count, 257 const SkPoint[], const SkPaint& paint); 258 virtual void drawRect(const SkDraw&, const SkRect& r, 259 const SkPaint& paint); 260 virtual void drawOval(const SkDraw&, const SkRect& oval, 261 const SkPaint& paint); 262 /** 263 * If pathIsMutable, then the implementation is allowed to cast path to a 264 * non-const pointer and modify it in place (as an optimization). Canvas 265 * may do this to implement helpers such as drawOval, by placing a temp 266 * path on the stack to hold the representation of the oval. 267 * 268 * If prePathMatrix is not null, it should logically be applied before any 269 * stroking or other effects. If there are no effects on the paint that 270 * affect the geometry/rasterization, then the pre matrix can just be 271 * pre-concated with the current matrix. 272 */ 273 virtual void drawPath(const SkDraw&, const SkPath& path, 274 const SkPaint& paint, 275 const SkMatrix* prePathMatrix = NULL, 276 bool pathIsMutable = false); 277 virtual void drawBitmap(const SkDraw&, const SkBitmap& bitmap, 278 const SkIRect* srcRectOrNull, 279 const SkMatrix& matrix, const SkPaint& paint); 280 virtual void drawSprite(const SkDraw&, const SkBitmap& bitmap, 281 int x, int y, const SkPaint& paint); 282 283 /** 284 * The default impl. will create a bitmap-shader from the bitmap, 285 * and call drawRect with it. 286 */ 287 virtual void drawBitmapRect(const SkDraw&, const SkBitmap&, 288 const SkRect* srcOrNull, const SkRect& dst, 289 const SkPaint& paint); 290 291 /** 292 * Does not handle text decoration. 293 * Decorations (underline and stike-thru) will be handled by SkCanvas. 294 */ 295 virtual void drawText(const SkDraw&, const void* text, size_t len, 296 SkScalar x, SkScalar y, const SkPaint& paint); 297 virtual void drawPosText(const SkDraw&, const void* text, size_t len, 298 const SkScalar pos[], SkScalar constY, 299 int scalarsPerPos, const SkPaint& paint); 300 virtual void drawTextOnPath(const SkDraw&, const void* text, size_t len, 301 const SkPath& path, const SkMatrix* matrix, 302 const SkPaint& paint); 303#ifdef SK_BUILD_FOR_ANDROID 304 virtual void drawPosTextOnPath(const SkDraw& draw, const void* text, size_t len, 305 const SkPoint pos[], const SkPaint& paint, 306 const SkPath& path, const SkMatrix* matrix); 307#endif 308 virtual void drawVertices(const SkDraw&, SkCanvas::VertexMode, int vertexCount, 309 const SkPoint verts[], const SkPoint texs[], 310 const SkColor colors[], SkXfermode* xmode, 311 const uint16_t indices[], int indexCount, 312 const SkPaint& paint); 313 /** The SkDevice passed will be an SkDevice which was returned by a call to 314 onCreateCompatibleDevice on this device with kSaveLayer_Usage. 315 */ 316 virtual void drawDevice(const SkDraw&, SkDevice*, int x, int y, 317 const SkPaint&); 318 319 /** 320 * On success (returns true), copy the device pixels into the bitmap. 321 * On failure, the bitmap parameter is left unchanged and false is 322 * returned. 323 * 324 * The device's pixels are converted to the bitmap's config. The only 325 * supported config is kARGB_8888_Config, though this is likely to be 326 * relaxed in the future. The meaning of config kARGB_8888_Config is 327 * modified by the enum param config8888. The default value interprets 328 * kARGB_8888_Config as SkPMColor 329 * 330 * If the bitmap has pixels already allocated, the device pixels will be 331 * written there. If not, bitmap->allocPixels() will be called 332 * automatically. If the bitmap is backed by a texture readPixels will 333 * fail. 334 * 335 * The actual pixels written is the intersection of the device's bounds, 336 * and the rectangle formed by the bitmap's width,height and the specified 337 * x,y. If bitmap pixels extend outside of that intersection, they will not 338 * be modified. 339 * 340 * Other failure conditions: 341 * * If the device is not a raster device (e.g. PDF) then readPixels will 342 * fail. 343 * * If bitmap is texture-backed then readPixels will fail. (This may be 344 * relaxed in the future.) 345 */ 346 bool readPixels(SkBitmap* bitmap, 347 int x, int y, 348 SkCanvas::Config8888 config8888); 349 350 /////////////////////////////////////////////////////////////////////////// 351 352 /** Update as needed the pixel value in the bitmap, so that the caller can 353 access the pixels directly. Note: only the pixels field should be 354 altered. The config/width/height/rowbytes must remain unchanged. 355 @param bitmap The device's bitmap 356 @return Echo the bitmap parameter, or an alternate (shadow) bitmap 357 maintained by the subclass. 358 */ 359 virtual const SkBitmap& onAccessBitmap(SkBitmap*); 360 361 SkPixelRef* getPixelRef() const { return fBitmap.pixelRef(); } 362 // just for subclasses, to assign a custom pixelref 363 SkPixelRef* setPixelRef(SkPixelRef* pr, size_t offset) { 364 fBitmap.setPixelRef(pr, offset); 365 return pr; 366 } 367 368 /** 369 * Implements readPixels API. The caller will ensure that: 370 * 1. bitmap has pixel config kARGB_8888_Config. 371 * 2. bitmap has pixels. 372 * 3. The rectangle (x, y, x + bitmap->width(), y + bitmap->height()) is 373 * contained in the device bounds. 374 */ 375 virtual bool onReadPixels(const SkBitmap& bitmap, 376 int x, int y, 377 SkCanvas::Config8888 config8888); 378 379 /** Called when this device is installed into a Canvas. Balanaced by a call 380 to unlockPixels() when the device is removed from a Canvas. 381 */ 382 virtual void lockPixels(); 383 virtual void unlockPixels(); 384 385 /** 386 * Returns true if the device allows processing of this imagefilter. If 387 * false is returned, then the filter is ignored. This may happen for 388 * some subclasses that do not support pixel manipulations after drawing 389 * has occurred (e.g. printing). The default implementation returns true. 390 */ 391 virtual bool allowImageFilter(SkImageFilter*); 392 393 /** 394 * Override and return true for filters that the device can handle 395 * intrinsically. Doing so means that SkCanvas will pass-through this 396 * filter to drawSprite and drawDevice (and potentially filterImage). 397 * Returning false means the SkCanvas will have apply the filter itself, 398 * and just pass the resulting image to the device. 399 */ 400 virtual bool canHandleImageFilter(SkImageFilter*); 401 402 /** 403 * Related (but not required) to canHandleImageFilter, this method returns 404 * true if the device could apply the filter to the src bitmap and return 405 * the result (and updates offset as needed). 406 * If the device does not recognize or support this filter, 407 * it just returns false and leaves result and offset unchanged. 408 */ 409 virtual bool filterImage(SkImageFilter*, const SkBitmap&, const SkMatrix&, 410 SkBitmap* result, SkIPoint* offset); 411 412 // This is equal kBGRA_Premul_Config8888 or kRGBA_Premul_Config8888 if 413 // either is identical to kNative_Premul_Config8888. Otherwise, -1. 414 static const SkCanvas::Config8888 kPMColorAlias; 415 416private: 417 friend class SkCanvas; 418 friend struct DeviceCM; //for setMatrixClip 419 friend class SkDraw; 420 friend class SkDrawIter; 421 friend class SkDeviceFilteredPaint; 422 friend class SkDeviceImageFilterProxy; 423 424 friend class SkSurface_Raster; 425 // used to change the backend's pixels (and possibly config/rowbytes) 426 // but cannot change the width/height, so there should be no change to 427 // any clip information. 428 void replaceBitmapBackendForRasterSurface(const SkBitmap&); 429 430 // just called by SkCanvas when built as a layer 431 void setOrigin(int x, int y) { fOrigin.set(x, y); } 432 // just called by SkCanvas for saveLayer 433 SkDevice* createCompatibleDeviceForSaveLayer(SkBitmap::Config config, 434 int width, int height, 435 bool isOpaque); 436 437 /** 438 * Subclasses should override this to implement createCompatibleDevice. 439 */ 440 virtual SkDevice* onCreateCompatibleDevice(SkBitmap::Config config, 441 int width, int height, 442 bool isOpaque, 443 Usage usage); 444 445 /** Causes any deferred drawing to the device to be completed. 446 */ 447 virtual void flush() {} 448 449 SkBitmap fBitmap; 450 SkIPoint fOrigin; 451 SkMetaData* fMetaData; 452 /** 453 * Leaky properties are those which the device should be applying but it isn't. 454 * These properties will be applied by the draw, when and as it can. 455 * If the device does handle a property, that property should be set to the identity value 456 * for that property, effectively making it non-leaky. 457 */ 458 SkDeviceProperties fLeakyProperties; 459 460#ifdef SK_DEBUG 461 bool fAttachedToCanvas; 462#endif 463 464 typedef SkRefCnt INHERITED; 465}; 466 467#endif 468