src/third_party/skia/include/core/SkDevice.h

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