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

   1 /*
   2  * Copyright 2010 The Android Open Source Project
   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 SkDevice_DEFINED
   9 #define SkDevice_DEFINED
  10
  11 #include "SkRefCnt.h"
  12 #include "SkBitmap.h"
  13 #include "SkCanvas.h"
  14 #include "SkColor.h"
  15 #include "SkImageFilter.h"
  16
  17 class SkClipStack;
  18 class SkDraw;
  19 struct SkIRect;
  20 class SkMatrix;
  21 class SkMetaData;
  22 class SkRegion;
  23 struct SkDeviceProperties;
  24 class GrRenderTarget;
  25
  26 class SK_API SkBaseDevice : public SkRefCnt {
  27 public:
  28     SK_DECLARE_INST_COUNT(SkBaseDevice)
  29
  30     /**
  31      *  Construct a new device.
  32     */
  33     SkBaseDevice();
  34     virtual ~SkBaseDevice();
  35
  36     SkBaseDevice* createCompatibleDevice(const SkImageInfo&);
  37
  38     SkMetaData& getMetaData();
  39
  40     /**
  41      *  Return ImageInfo for this device. If the canvas is not backed by pixels
  42      *  (cpu or gpu), then the info's ColorType will be kUnknown_SkColorType.
  43      */
  44     virtual SkImageInfo imageInfo() const;
  45
  46     /**
  47      *  Return the bounds of the device in the coordinate space of the root
  48      *  canvas. The root device will have its top-left at 0,0, but other devices
  49      *  such as those associated with saveLayer may have a non-zero origin.
  50      */
  51     void getGlobalBounds(SkIRect* bounds) const {
  52         SkASSERT(bounds);
  53         const SkIPoint& origin = this->getOrigin();
  54         bounds->setXYWH(origin.x(), origin.y(), this->width(), this->height());
  55     }
  56
  57     int width() const {
  58         return this->imageInfo().width();
  59     }
  60
  61     int height() const {
  62         return this->imageInfo().height();
  63     }
  64
  65     bool isOpaque() const {
  66         return this->imageInfo().isOpaque();
  67     }
  68
  69     /** Return the bitmap associated with this device. Call this each time you need
  70         to access the bitmap, as it notifies the subclass to perform any flushing
  71         etc. before you examine the pixels.
  72         @param changePixels set to true if the caller plans to change the pixels
  73         @return the device's bitmap
  74     */
  75     const SkBitmap& accessBitmap(bool changePixels);
  76
  77     bool writePixels(const SkImageInfo&, const void*, size_t rowBytes, int x, int y);
  78
  79     void* accessPixels(SkImageInfo* info, size_t* rowBytes);
  80
  81     /**
  82      * Return the device's associated gpu render target, or NULL.
  83      */
  84     virtual GrRenderTarget* accessRenderTarget() { return NULL; }
  85
  86
  87     /**
  88      *  Return the device's origin: its offset in device coordinates from
  89      *  the default origin in its canvas' matrix/clip
  90      */
  91     const SkIPoint& getOrigin() const { return fOrigin; }
  92
  93     /**
  94      * onAttachToCanvas is invoked whenever a device is installed in a canvas
  95      * (i.e., setDevice, saveLayer (for the new device created by the save),
  96      * and SkCanvas' SkBaseDevice & SkBitmap -taking ctors). It allows the
  97      * devices to prepare for drawing (e.g., locking their pixels, etc.)
  98      */
  99     virtual void onAttachToCanvas(SkCanvas*) {
 100         SkASSERT(!fAttachedToCanvas);
 101         this->lockPixels();
 102 #ifdef SK_DEBUG
 103         fAttachedToCanvas = true;
 104 #endif
 105     };
 106
 107     /**
 108      * onDetachFromCanvas notifies a device that it will no longer be drawn to.
 109      * It gives the device a chance to clean up (e.g., unlock its pixels). It
 110      * is invoked from setDevice (for the displaced device), restore and
 111      * possibly from SkCanvas' dtor.
 112      */
 113     virtual void onDetachFromCanvas() {
 114         SkASSERT(fAttachedToCanvas);
 115         this->unlockPixels();
 116 #ifdef SK_DEBUG
 117         fAttachedToCanvas = false;
 118 #endif
 119     };
 120
 121 protected:
 122     enum Usage {
 123        kGeneral_Usage,
 124        kSaveLayer_Usage  // <! internal use only
 125     };
 126
 127     struct TextFlags {
 128         uint32_t    fFlags;     // SkPaint::getFlags()
 129     };
 130
 131     /**
 132      *  Device may filter the text flags for drawing text here. If it wants to
 133      *  make a change to the specified values, it should write them into the
 134      *  textflags parameter (output) and return true. If the paint is fine as
 135      *  is, then ignore the textflags parameter and return false.
 136      */
 137     virtual bool filterTextFlags(const SkPaint& paint, TextFlags*) { return false; }
 138
 139     /**
 140      *
 141      *  DEPRECATED: This will be removed in a future change. Device subclasses
 142      *  should use the matrix and clip from the SkDraw passed to draw functions.
 143      *
 144      *  Called with the correct matrix and clip before this device is drawn
 145      *  to using those settings. If your subclass overrides this, be sure to
 146      *  call through to the base class as well.
 147      *
 148      *  The clipstack is another view of the clip. It records the actual
 149      *  geometry that went into building the region. It is present for devices
 150      *  that want to parse it, but is not required: the region is a complete
 151      *  picture of the current clip. (i.e. if you regionize all of the geometry
 152      *  in the clipstack, you will arrive at an equivalent region to the one
 153      *  passed in).
 154      */
 155      virtual void setMatrixClip(const SkMatrix&, const SkRegion&,
 156                                 const SkClipStack&) {};
 157
 158     /** Clears the entire device to the specified color (including alpha).
 159      *  Ignores the clip.
 160      */
 161     virtual void clear(SkColor color) = 0;
 162
 163     SK_ATTR_DEPRECATED("use clear() instead")
 164     void eraseColor(SkColor eraseColor) { this->clear(eraseColor); }
 165
 166     /** These are called inside the per-device-layer loop for each draw call.
 167      When these are called, we have already applied any saveLayer operations,
 168      and are handling any looping from the paint, and any effects from the
 169      DrawFilter.
 170      */
 171     virtual void drawPaint(const SkDraw&, const SkPaint& paint) = 0;
 172     virtual void drawPoints(const SkDraw&, SkCanvas::PointMode mode, size_t count,
 173                             const SkPoint[], const SkPaint& paint) = 0;
 174     virtual void drawRect(const SkDraw&, const SkRect& r,
 175                           const SkPaint& paint) = 0;
 176     virtual void drawOval(const SkDraw&, const SkRect& oval,
 177                           const SkPaint& paint) = 0;
 178     virtual void drawRRect(const SkDraw&, const SkRRect& rr,
 179                            const SkPaint& paint) = 0;
 180
 181     // Default impl calls drawPath()
 182     virtual void drawDRRect(const SkDraw&, const SkRRect& outer,
 183                             const SkRRect& inner, const SkPaint&);
 184
 185     /**
 186      *  If pathIsMutable, then the implementation is allowed to cast path to a
 187      *  non-const pointer and modify it in place (as an optimization). Canvas
 188      *  may do this to implement helpers such as drawOval, by placing a temp
 189      *  path on the stack to hold the representation of the oval.
 190      *
 191      *  If prePathMatrix is not null, it should logically be applied before any
 192      *  stroking or other effects. If there are no effects on the paint that
 193      *  affect the geometry/rasterization, then the pre matrix can just be
 194      *  pre-concated with the current matrix.
 195      */
 196     virtual void drawPath(const SkDraw&, const SkPath& path,
 197                           const SkPaint& paint,
 198                           const SkMatrix* prePathMatrix = NULL,
 199                           bool pathIsMutable = false) = 0;
 200     virtual void drawBitmap(const SkDraw&, const SkBitmap& bitmap,
 201                             const SkMatrix& matrix, const SkPaint& paint) = 0;
 202     virtual void drawSprite(const SkDraw&, const SkBitmap& bitmap,
 203                             int x, int y, const SkPaint& paint) = 0;
 204
 205     /**
 206      *  The default impl. will create a bitmap-shader from the bitmap,
 207      *  and call drawRect with it.
 208      */
 209     virtual void drawBitmapRect(const SkDraw&, const SkBitmap&,
 210                                 const SkRect* srcOrNull, const SkRect& dst,
 211                                 const SkPaint& paint,
 212                                 SkCanvas::DrawBitmapRectFlags flags) = 0;
 213
 214     /**
 215      *  Does not handle text decoration.
 216      *  Decorations (underline and stike-thru) will be handled by SkCanvas.
 217      */
 218     virtual void drawText(const SkDraw&, const void* text, size_t len,
 219                           SkScalar x, SkScalar y, const SkPaint& paint) = 0;
 220     virtual void drawPosText(const SkDraw&, const void* text, size_t len,
 221                              const SkScalar pos[], SkScalar constY,
 222                              int scalarsPerPos, const SkPaint& paint) = 0;
 223     virtual void drawTextOnPath(const SkDraw&, const void* text, size_t len,
 224                                 const SkPath& path, const SkMatrix* matrix,
 225                                 const SkPaint& paint) = 0;
 226     virtual void drawVertices(const SkDraw&, SkCanvas::VertexMode, int vertexCount,
 227                               const SkPoint verts[], const SkPoint texs[],
 228                               const SkColor colors[], SkXfermode* xmode,
 229                               const uint16_t indices[], int indexCount,
 230                               const SkPaint& paint) = 0;
 231     // default implementation unrolls the blob runs.
 232     virtual void drawTextBlob(const SkDraw&, const SkTextBlob*, SkScalar x, SkScalar y,
 233                               const SkPaint& paint);
 234     // default implementation calls drawVertices
 235     virtual void drawPatch(const SkDraw&, const SkPoint cubics[12], const SkColor colors[4],
 236                            const SkPoint texCoords[4], SkXfermode* xmode, const SkPaint& paint);
 237     /** The SkDevice passed will be an SkDevice which was returned by a call to
 238         onCreateDevice on this device with kSaveLayer_Usage.
 239      */
 240     virtual void drawDevice(const SkDraw&, SkBaseDevice*, int x, int y,
 241                             const SkPaint&) = 0;
 242
 243     bool readPixels(const SkImageInfo&, void* dst, size_t rowBytes, int x, int y);
 244
 245     ///////////////////////////////////////////////////////////////////////////
 246
 247     /** Update as needed the pixel value in the bitmap, so that the caller can
 248         access the pixels directly.
 249         @return The device contents as a bitmap
 250     */
 251     virtual const SkBitmap& onAccessBitmap() = 0;
 252
 253     /** Called when this device is installed into a Canvas. Balanced by a call
 254         to unlockPixels() when the device is removed from a Canvas.
 255     */
 256     virtual void lockPixels() {}
 257     virtual void unlockPixels() {}
 258
 259     /**
 260      *  Returns true if the device allows processing of this imagefilter. If
 261      *  false is returned, then the filter is ignored. This may happen for
 262      *  some subclasses that do not support pixel manipulations after drawing
 263      *  has occurred (e.g. printing). The default implementation returns true.
 264      */
 265     virtual bool allowImageFilter(const SkImageFilter*) { return true; }
 266
 267     /**
 268      *  Override and return true for filters that the device can handle
 269      *  intrinsically. Doing so means that SkCanvas will pass-through this
 270      *  filter to drawSprite and drawDevice (and potentially filterImage).
 271      *  Returning false means the SkCanvas will have apply the filter itself,
 272      *  and just pass the resulting image to the device.
 273      */
 274     virtual bool canHandleImageFilter(const SkImageFilter*) { return false; }
 275
 276     /**
 277      *  Related (but not required) to canHandleImageFilter, this method returns
 278      *  true if the device could apply the filter to the src bitmap and return
 279      *  the result (and updates offset as needed).
 280      *  If the device does not recognize or support this filter,
 281      *  it just returns false and leaves result and offset unchanged.
 282      */
 283     virtual bool filterImage(const SkImageFilter*, const SkBitmap&,
 284                              const SkImageFilter::Context& ctx,
 285                              SkBitmap* result, SkIPoint* offset) {
 286         return false;
 287     }
 288
 289 protected:
 290     // default impl returns NULL
 291     virtual SkSurface* newSurface(const SkImageInfo&, const SkSurfaceProps&);
 292
 293     // default impl returns NULL
 294     virtual const void* peekPixels(SkImageInfo*, size_t* rowBytes);
 295
 296     /**
 297      *  The caller is responsible for "pre-clipping" the dst. The impl can assume that the dst
 298      *  image at the specified x,y offset will fit within the device's bounds.
 299      *
 300      *  This is explicitly asserted in readPixels(), the public way to call this.
 301      */
 302     virtual bool onReadPixels(const SkImageInfo&, void*, size_t, int x, int y);
 303
 304     /**
 305      *  The caller is responsible for "pre-clipping" the src. The impl can assume that the src
 306      *  image at the specified x,y offset will fit within the device's bounds.
 307      *
 308      *  This is explicitly asserted in writePixelsDirect(), the public way to call this.
 309      */
 310     virtual bool onWritePixels(const SkImageInfo&, const void*, size_t, int x, int y);
 311
 312     /**
 313      *  Default impl returns NULL.
 314      */
 315     virtual void* onAccessPixels(SkImageInfo* info, size_t* rowBytes);
 316
 317     /**
 318      *  Leaky properties are those which the device should be applying but it isn't.
 319      *  These properties will be applied by the draw, when and as it can.
 320      *  If the device does handle a property, that property should be set to the identity value
 321      *  for that property, effectively making it non-leaky.
 322      */
 323     const SkDeviceProperties& getLeakyProperties() const {
 324         return *fLeakyProperties;
 325     }
 326
 327     /**
 328      *  PRIVATE / EXPERIMENTAL -- do not call
 329      *  Construct an acceleration object and attach it to 'picture'
 330      */
 331     virtual void EXPERIMENTAL_optimize(const SkPicture* picture);
 332
 333     /**
 334      *  PRIVATE / EXPERIMENTAL -- do not call
 335      *  This entry point gives the backend an opportunity to take over the rendering
 336      *  of 'picture'. If optimization data is available (due to an earlier
 337      *  'optimize' call) this entry point should make use of it and return true
 338      *  if all rendering has been done. If false is returned, SkCanvas will
 339      *  perform its own rendering pass. It is acceptable for the backend
 340      *  to perform some device-specific warm up tasks and then let SkCanvas
 341      *  perform the main rendering loop (by return false from here).
 342      */
 343     virtual bool EXPERIMENTAL_drawPicture(SkCanvas*, const SkPicture*, const SkMatrix*,
 344                                           const SkPaint*);
 345
 346     void setPixelGeometry(SkPixelGeometry geo);
 347
 348 private:
 349     friend class SkCanvas;
 350     friend struct DeviceCM; //for setMatrixClip
 351     friend class SkDraw;
 352     friend class SkDrawIter;
 353     friend class SkDeviceFilteredPaint;
 354     friend class SkDeviceImageFilterProxy;
 355     friend class SkDeferredDevice;    // for newSurface
 356
 357     friend class SkSurface_Raster;
 358
 359     // used to change the backend's pixels (and possibly config/rowbytes)
 360     // but cannot change the width/height, so there should be no change to
 361     // any clip information.
 362     // TODO: move to SkBitmapDevice
 363     virtual void replaceBitmapBackendForRasterSurface(const SkBitmap&) {}
 364
 365     virtual bool forceConservativeRasterClip() const { return false; }
 366
 367     // just called by SkCanvas when built as a layer
 368     void setOrigin(int x, int y) { fOrigin.set(x, y); }
 369     // just called by SkCanvas for saveLayer
 370     SkBaseDevice* createCompatibleDeviceForSaveLayer(const SkImageInfo&);
 371
 372     virtual SkBaseDevice* onCreateDevice(const SkImageInfo&, Usage) {
 373         return NULL;
 374     }
 375
 376     /** Causes any deferred drawing to the device to be completed.
 377      */
 378     virtual void flush() {}
 379
 380     virtual SkImageFilter::Cache* getImageFilterCache() { return NULL; }
 381
 382     SkIPoint    fOrigin;
 383     SkMetaData* fMetaData;
 384     SkDeviceProperties* fLeakyProperties;   // will always exist.
 385
 386 #ifdef SK_DEBUG
 387     bool        fAttachedToCanvas;
 388 #endif
 389
 390     typedef SkRefCnt INHERITED;
 391 };
 392
 393 #endif