src/third_party/skia/include/gpu/GrContext.h

   1 /*
   2  * Copyright 2010 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 GrContext_DEFINED
   9 #define GrContext_DEFINED
  10
  11 #include "GrClipData.h"
  12 #include "GrColor.h"
  13 #include "GrPaint.h"
  14 #include "GrPathRendererChain.h"
  15 #include "GrRenderTarget.h"
  16 #include "GrTexture.h"
  17 #include "SkMatrix.h"
  18 #include "SkPathEffect.h"
  19 #include "SkTypes.h"
  20
  21 class GrAARectRenderer;
  22 class GrAutoScratchTexture;
  23 class GrDrawState;
  24 class GrDrawTarget;
  25 class GrFontCache;
  26 class GrFragmentProcessor;
  27 class GrGpu;
  28 class GrGpuTraceMarker;
  29 class GrIndexBuffer;
  30 class GrIndexBufferAllocPool;
  31 class GrInOrderDrawBuffer;
  32 class GrLayerCache;
  33 class GrOvalRenderer;
  34 class GrPath;
  35 class GrPathRenderer;
  36 class GrResourceEntry;
  37 class GrResourceCache;
  38 class GrResourceCache2;
  39 class GrStencilBuffer;
  40 class GrTestTarget;
  41 class GrTextContext;
  42 class GrTextureParams;
  43 class GrVertexBuffer;
  44 class GrVertexBufferAllocPool;
  45 class GrStrokeInfo;
  46 class GrSoftwarePathRenderer;
  47 class SkStrokeRec;
  48
  49 class SK_API GrContext : public SkRefCnt {
  50 public:
  51     SK_DECLARE_INST_COUNT(GrContext)
  52
  53     struct Options {
  54         Options() : fDrawPathToCompressedTexture(false) { }
  55
  56         // EXPERIMENTAL
  57         // May be removed in the future, or may become standard depending
  58         // on the outcomes of a variety of internal tests.
  59         bool fDrawPathToCompressedTexture;
  60     };
  61
  62     /**
  63      * Creates a GrContext for a backend context.
  64      */
  65     static GrContext* Create(GrBackend, GrBackendContext, const Options* opts = NULL);
  66
  67     virtual ~GrContext();
  68
  69     /**
  70      * The GrContext normally assumes that no outsider is setting state
  71      * within the underlying 3D API's context/device/whatever. This call informs
  72      * the context that the state was modified and it should resend. Shouldn't
  73      * be called frequently for good performance.
  74      * The flag bits, state, is dpendent on which backend is used by the
  75      * context, either GL or D3D (possible in future).
  76      */
  77     void resetContext(uint32_t state = kAll_GrBackendState);
  78
  79     /**
  80      * Callback function to allow classes to cleanup on GrContext destruction.
  81      * The 'info' field is filled in with the 'info' passed to addCleanUp.
  82      */
  83     typedef void (*PFCleanUpFunc)(const GrContext* context, void* info);
  84
  85     /**
  86      * Add a function to be called from within GrContext's destructor.
  87      * This gives classes a chance to free resources held on a per context basis.
  88      * The 'info' parameter will be stored and passed to the callback function.
  89      */
  90     void addCleanUp(PFCleanUpFunc cleanUp, void* info) {
  91         CleanUpData* entry = fCleanUpData.push();
  92
  93         entry->fFunc = cleanUp;
  94         entry->fInfo = info;
  95     }
  96
  97     /**
  98      * Abandons all GPU resources and assumes the underlying backend 3D API
  99      * context is not longer usable. Call this if you have lost the associated
 100      * GPU context, and thus internal texture, buffer, etc. references/IDs are
 101      * now invalid. Should be called even when GrContext is no longer going to
 102      * be used for two reasons:
 103      *  1) ~GrContext will not try to free the objects in the 3D API.
 104      *  2) Any GrGpuResources created by this GrContext that outlive
 105      *     will be marked as invalid (GrGpuResource::wasDestroyed()) and
 106      *     when they're destroyed no 3D API calls will be made.
 107      * Content drawn since the last GrContext::flush() may be lost. After this
 108      * function is called the only valid action on the GrContext or
 109      * GrGpuResources it created is to destroy them.
 110      */
 111     void abandonContext();
 112     void contextDestroyed() { this->abandonContext(); }  //  legacy alias
 113
 114     ///////////////////////////////////////////////////////////////////////////
 115     // Resource Cache
 116
 117     /**
 118      *  Return the current GPU resource cache limits.
 119      *
 120      *  @param maxResources If non-null, returns maximum number of resources that
 121      *                      can be held in the cache.
 122      *  @param maxResourceBytes If non-null, returns maximum number of bytes of
 123      *                          video memory that can be held in the cache.
 124      */
 125     void getResourceCacheLimits(int* maxResources, size_t* maxResourceBytes) const;
 126     SK_ATTR_DEPRECATED("This function has been renamed to getResourceCacheLimits().")
 127     void getTextureCacheLimits(int* maxTextures, size_t* maxTextureBytes) const {
 128         this->getResourceCacheLimits(maxTextures, maxTextureBytes);
 129     }
 130
 131     /**
 132      *  Gets the current GPU resource cache usage.
 133      *
 134      *  @param resourceCount If non-null, returns the number of resources that are held in the
 135      *                       cache.
 136      *  @param maxResourceBytes If non-null, returns the total number of bytes of video memory held
 137      *                          in the cache.
 138      */
 139     void getResourceCacheUsage(int* resourceCount, size_t* resourceBytes) const;
 140
 141     SK_ATTR_DEPRECATED("Use getResourceCacheUsage().")
 142     size_t getGpuTextureCacheBytes() const {
 143         size_t bytes;
 144         this->getResourceCacheUsage(NULL, &bytes);
 145         return bytes;
 146     }
 147
 148     SK_ATTR_DEPRECATED("Use getResourceCacheUsage().")
 149     int getGpuTextureCacheResourceCount() const {
 150         int count;
 151         this->getResourceCacheUsage(&count, NULL);
 152         return count;
 153     }
 154
 155     /**
 156      *  Specify the GPU resource cache limits. If the current cache exceeds either
 157      *  of these, it will be purged (LRU) to keep the cache within these limits.
 158      *
 159      *  @param maxResources The maximum number of resources that can be held in
 160      *                      the cache.
 161      *  @param maxResourceBytes The maximum number of bytes of video memory
 162      *                          that can be held in the cache.
 163      */
 164     void setResourceCacheLimits(int maxResources, size_t maxResourceBytes);
 165     SK_ATTR_DEPRECATED("This function has been renamed to setResourceCacheLimits().")
 166     void setTextureCacheLimits(int maxTextures, size_t maxTextureBytes) {
 167         this->setResourceCacheLimits(maxTextures, maxTextureBytes);
 168     }
 169
 170     /**
 171      * Frees GPU created by the context. Can be called to reduce GPU memory
 172      * pressure.
 173      */
 174     void freeGpuResources();
 175
 176     /**
 177      * This method should be called whenever a GrResource is unreffed or
 178      * switched from exclusive to non-exclusive. This
 179      * gives the resource cache a chance to discard unneeded resources.
 180      * Note: this entry point will be removed once totally ref-driven
 181      * cache maintenance is implemented.
 182      */
 183     void purgeCache();
 184
 185     /**
 186      * Purge all the unlocked resources from the cache.
 187      * This entry point is mainly meant for timing texture uploads
 188      * and is not defined in normal builds of Skia.
 189      */
 190     void purgeAllUnlockedResources();
 191
 192     /**
 193      * Stores a custom resource in the cache, based on the specified key.
 194      */
 195     void addResourceToCache(const GrResourceKey&, GrGpuResource*);
 196
 197     /**
 198      * Finds a resource in the cache, based on the specified key. This is intended for use in
 199      * conjunction with addResourceToCache(). The return value will be NULL if not found. The
 200      * caller must balance with a call to unref().
 201      */
 202     GrGpuResource* findAndRefCachedResource(const GrResourceKey&);
 203
 204     /**
 205      * Creates a new text rendering context that is optimal for the
 206      * render target and the context. Caller assumes the ownership
 207      * of the returned object. The returned object must be deleted
 208      * before the context is destroyed.
 209      */
 210     GrTextContext* createTextContext(GrRenderTarget*,
 211                                      const SkDeviceProperties&,
 212                                      bool enableDistanceFieldFonts);
 213
 214     ///////////////////////////////////////////////////////////////////////////
 215     // Textures
 216
 217     /**
 218      * Creates a new entry, based on the specified key and texture and returns it. The caller owns a
 219      * ref on the returned texture which must be balanced by a call to unref.
 220      *
 221      * @param params    The texture params used to draw a texture may help determine
 222      *                  the cache entry used. (e.g. different versions may exist
 223      *                  for different wrap modes on GPUs with limited NPOT
 224      *                  texture support). NULL implies clamp wrap modes.
 225      * @param desc      Description of the texture properties.
 226      * @param cacheID   Cache-specific properties (e.g., texture gen ID)
 227      * @param srcData   Pointer to the pixel values.
 228      * @param rowBytes  The number of bytes between rows of the texture. Zero
 229      *                  implies tightly packed rows. For compressed pixel configs, this
 230      *                  field is ignored.
 231      * @param cacheKey  (optional) If non-NULL, we'll write the cache key we used to cacheKey.
 232      */
 233     GrTexture* createTexture(const GrTextureParams* params,
 234                              const GrTextureDesc& desc,
 235                              const GrCacheID& cacheID,
 236                              const void* srcData,
 237                              size_t rowBytes,
 238                              GrResourceKey* cacheKey = NULL);
 239     /**
 240      * Search for an entry based on key and dimensions. If found, ref it and return it. The return
 241      * value will be NULL if not found. The caller must balance with a call to unref.
 242      *
 243      *  @param desc     Description of the texture properties.
 244      *  @param cacheID Cache-specific properties (e.g., texture gen ID)
 245      *  @param params   The texture params used to draw a texture may help determine
 246      *                  the cache entry used. (e.g. different versions may exist
 247      *                  for different wrap modes on GPUs with limited NPOT
 248      *                  texture support). NULL implies clamp wrap modes.
 249      */
 250     GrTexture* findAndRefTexture(const GrTextureDesc& desc,
 251                                  const GrCacheID& cacheID,
 252                                  const GrTextureParams* params);
 253     /**
 254      * Determines whether a texture is in the cache. If the texture is found it
 255      * will not be locked or returned. This call does not affect the priority of
 256      * the texture for deletion.
 257      */
 258     bool isTextureInCache(const GrTextureDesc& desc,
 259                           const GrCacheID& cacheID,
 260                           const GrTextureParams* params) const;
 261
 262     /**
 263      * Enum that determines how closely a returned scratch texture must match
 264      * a provided GrTextureDesc.
 265      */
 266     enum ScratchTexMatch {
 267         /**
 268          * Finds a texture that exactly matches the descriptor.
 269          */
 270         kExact_ScratchTexMatch,
 271         /**
 272          * Finds a texture that approximately matches the descriptor. Will be
 273          * at least as large in width and height as desc specifies. If desc
 274          * specifies that texture is a render target then result will be a
 275          * render target. If desc specifies a render target and doesn't set the
 276          * no stencil flag then result will have a stencil. Format and aa level
 277          * will always match.
 278          */
 279         kApprox_ScratchTexMatch
 280     };
 281
 282     /**
 283      * Returns a texture matching the desc. It's contents are unknown. Subsequent
 284      * requests with the same descriptor are not guaranteed to return the same
 285      * texture. The same texture is guaranteed not be returned again until it is
 286      * unlocked. Call must be balanced with an unlockTexture() call. The caller
 287      * owns a ref on the returned texture and must balance with a call to unref.
 288      *
 289      * Textures created by createAndLockTexture() hide the complications of
 290      * tiling non-power-of-two textures on APIs that don't support this (e.g.
 291      * unextended GLES2). Tiling a NPOT texture created by lockScratchTexture on
 292      * such an API will create gaps in the tiling pattern. This includes clamp
 293      * mode. (This may be addressed in a future update.)
 294      */
 295     GrTexture* lockAndRefScratchTexture(const GrTextureDesc&, ScratchTexMatch match);
 296
 297     /**
 298      *  When done with an entry, call unlockScratchTexture(entry) on it, which returns
 299      *  it to the cache, where it may be purged. This does not unref the texture.
 300      */
 301     void unlockScratchTexture(GrTexture* texture);
 302
 303     /**
 304      * Creates a texture that is outside the cache. Does not count against
 305      * cache's budget.
 306      */
 307     GrTexture* createUncachedTexture(const GrTextureDesc& desc,
 308                                      void* srcData,
 309                                      size_t rowBytes);
 310
 311     /**
 312      * Returns true if the specified use of an indexed texture is supported.
 313      * Support may depend upon whether the texture params indicate that the
 314      * texture will be tiled. Passing NULL for the texture params indicates
 315      * clamp mode.
 316      */
 317     bool supportsIndex8PixelConfig(const GrTextureParams*,
 318                                    int width,
 319                                    int height) const;
 320
 321     /**
 322      *  Return the max width or height of a texture supported by the current GPU.
 323      */
 324     int getMaxTextureSize() const;
 325
 326     /**
 327      *  Temporarily override the true max texture size. Note: an override
 328      *  larger then the true max texture size will have no effect.
 329      *  This entry point is mainly meant for testing texture size dependent
 330      *  features and is only available if defined outside of Skia (see
 331      *  bleed GM.
 332      */
 333     void setMaxTextureSizeOverride(int maxTextureSizeOverride);
 334
 335     ///////////////////////////////////////////////////////////////////////////
 336     // Render targets
 337
 338     /**
 339      * Sets the render target.
 340      * @param target    the render target to set.
 341      */
 342     void setRenderTarget(GrRenderTarget* target) {
 343         fRenderTarget.reset(SkSafeRef(target));
 344     }
 345
 346     /**
 347      * Gets the current render target.
 348      * @return the currently bound render target.
 349      */
 350     const GrRenderTarget* getRenderTarget() const { return fRenderTarget.get(); }
 351     GrRenderTarget* getRenderTarget() { return fRenderTarget.get(); }
 352
 353     /**
 354      * Can the provided configuration act as a color render target?
 355      */
 356     bool isConfigRenderable(GrPixelConfig config, bool withMSAA) const;
 357
 358     /**
 359      * Return the max width or height of a render target supported by the
 360      * current GPU.
 361      */
 362     int getMaxRenderTargetSize() const;
 363
 364     /**
 365      * Returns the max sample count for a render target. It will be 0 if MSAA
 366      * is not supported.
 367      */
 368     int getMaxSampleCount() const;
 369
 370     /**
 371      * Returns the recommended sample count for a render target when using this
 372      * context.
 373      *
 374      * @param  config the configuration of the render target.
 375      * @param  dpi the display density in dots per inch.
 376      *
 377      * @return sample count that should be perform well and have good enough
 378      *         rendering quality for the display. Alternatively returns 0 if
 379      *         MSAA is not supported or recommended to be used by default.
 380      */
 381     int getRecommendedSampleCount(GrPixelConfig config, SkScalar dpi) const;
 382
 383     ///////////////////////////////////////////////////////////////////////////
 384     // Backend Surfaces
 385
 386     /**
 387      * Wraps an existing texture with a GrTexture object.
 388      *
 389      * OpenGL: if the object is a texture Gr may change its GL texture params
 390      *         when it is drawn.
 391      *
 392      * @param  desc     description of the object to create.
 393      *
 394      * @return GrTexture object or NULL on failure.
 395      */
 396     GrTexture* wrapBackendTexture(const GrBackendTextureDesc& desc);
 397
 398     /**
 399      * Wraps an existing render target with a GrRenderTarget object. It is
 400      * similar to wrapBackendTexture but can be used to draw into surfaces
 401      * that are not also textures (e.g. FBO 0 in OpenGL, or an MSAA buffer that
 402      * the client will resolve to a texture).
 403      *
 404      * @param  desc     description of the object to create.
 405      *
 406      * @return GrTexture object or NULL on failure.
 407      */
 408      GrRenderTarget* wrapBackendRenderTarget(const GrBackendRenderTargetDesc& desc);
 409
 410     ///////////////////////////////////////////////////////////////////////////
 411     // Matrix state
 412
 413     /**
 414      * Gets the current transformation matrix.
 415      * @return the current matrix.
 416      */
 417     const SkMatrix& getMatrix() const { return fViewMatrix; }
 418
 419     /**
 420      * Sets the transformation matrix.
 421      * @param m the matrix to set.
 422      */
 423     void setMatrix(const SkMatrix& m) { fViewMatrix = m; }
 424
 425     /**
 426      * Sets the current transformation matrix to identity.
 427      */
 428     void setIdentityMatrix() { fViewMatrix.reset(); }
 429
 430     /**
 431      * Concats the current matrix. The passed matrix is applied before the
 432      * current matrix.
 433      * @param m the matrix to concat.
 434      */
 435     void concatMatrix(const SkMatrix& m) { fViewMatrix.preConcat(m); }
 436
 437
 438     ///////////////////////////////////////////////////////////////////////////
 439     // Clip state
 440     /**
 441      * Gets the current clip.
 442      * @return the current clip.
 443      */
 444     const GrClipData* getClip() const { return fClip; }
 445
 446     /**
 447      * Sets the clip.
 448      * @param clipData  the clip to set.
 449      */
 450     void setClip(const GrClipData* clipData) { fClip = clipData; }
 451
 452     ///////////////////////////////////////////////////////////////////////////
 453     // Draws
 454
 455     /**
 456      * Clear the entire or rect of the render target, ignoring any clips.
 457      * @param rect  the rect to clear or the whole thing if rect is NULL.
 458      * @param color the color to clear to.
 459      * @param canIgnoreRect allows partial clears to be converted to whole
 460      *                      clears on platforms for which that is cheap
 461      * @param target if non-NULL, the render target to clear otherwise clear
 462      *               the current render target
 463      */
 464     void clear(const SkIRect* rect, GrColor color, bool canIgnoreRect,
 465                GrRenderTarget* target = NULL);
 466
 467     /**
 468      *  Draw everywhere (respecting the clip) with the paint.
 469      */
 470     void drawPaint(const GrPaint& paint);
 471
 472     /**
 473      *  Draw the rect using a paint.
 474      *  @param paint        describes how to color pixels.
 475      *  @param strokeInfo   the stroke information (width, join, cap), and.
 476      *                      the dash information (intervals, count, phase).
 477      *                      If strokeInfo == NULL, then the rect is filled.
 478      *                      Otherwise, if stroke width == 0, then the stroke
 479      *                      is always a single pixel thick, else the rect is
 480      *                      mitered/beveled stroked based on stroke width.
 481      *  The rects coords are used to access the paint (through texture matrix)
 482      */
 483     void drawRect(const GrPaint& paint,
 484                   const SkRect&,
 485                   const GrStrokeInfo* strokeInfo = NULL);
 486
 487     /**
 488      * Maps a rect of local coordinates onto the a rect of destination
 489      * coordinates. The localRect is stretched over the dstRect. The dstRect is
 490      * transformed by the context's matrix. An additional optional matrix can be
 491      *  provided to transform the local rect.
 492      *
 493      * @param paint         describes how to color pixels.
 494      * @param dstRect       the destination rect to draw.
 495      * @param localRect     rect of local coordinates to be mapped onto dstRect
 496      * @param localMatrix   Optional matrix to transform localRect.
 497      */
 498     void drawRectToRect(const GrPaint& paint,
 499                         const SkRect& dstRect,
 500                         const SkRect& localRect,
 501                         const SkMatrix* localMatrix = NULL);
 502
 503     /**
 504      *  Draw a roundrect using a paint.
 505      *
 506      *  @param paint        describes how to color pixels.
 507      *  @param rrect        the roundrect to draw
 508      *  @param strokeInfo   the stroke information (width, join, cap) and
 509      *                      the dash information (intervals, count, phase).
 510      */
 511     void drawRRect(const GrPaint& paint, const SkRRect& rrect, const GrStrokeInfo& strokeInfo);
 512
 513     /**
 514      *  Shortcut for drawing an SkPath consisting of nested rrects using a paint.
 515      *  Does not support stroking. The result is undefined if outer does not contain
 516      *  inner.
 517      *
 518      *  @param paint        describes how to color pixels.
 519      *  @param outer        the outer roundrect
 520      *  @param inner        the inner roundrect
 521      */
 522     void drawDRRect(const GrPaint& paint, const SkRRect& outer, const SkRRect& inner);
 523
 524
 525     /**
 526      * Draws a path.
 527      *
 528      * @param paint         describes how to color pixels.
 529      * @param path          the path to draw
 530      * @param strokeInfo    the stroke information (width, join, cap) and
 531      *                      the dash information (intervals, count, phase).
 532      */
 533     void drawPath(const GrPaint& paint, const SkPath& path, const GrStrokeInfo& strokeInfo);
 534
 535     /**
 536      * Draws vertices with a paint.
 537      *
 538      * @param   paint           describes how to color pixels.
 539      * @param   primitiveType   primitives type to draw.
 540      * @param   vertexCount     number of vertices.
 541      * @param   positions       array of vertex positions, required.
 542      * @param   texCoords       optional array of texture coordinates used
 543      *                          to access the paint.
 544      * @param   colors          optional array of per-vertex colors, supercedes
 545      *                          the paint's color field.
 546      * @param   indices         optional array of indices. If NULL vertices
 547      *                          are drawn non-indexed.
 548      * @param   indexCount      if indices is non-null then this is the
 549      *                          number of indices.
 550      */
 551     void drawVertices(const GrPaint& paint,
 552                       GrPrimitiveType primitiveType,
 553                       int vertexCount,
 554                       const SkPoint positions[],
 555                       const SkPoint texs[],
 556                       const GrColor colors[],
 557                       const uint16_t indices[],
 558                       int indexCount);
 559
 560     /**
 561      * Draws an oval.
 562      *
 563      * @param paint         describes how to color pixels.
 564      * @param oval          the bounding rect of the oval.
 565      * @param strokeInfo    the stroke information (width, join, cap) and
 566      *                      the dash information (intervals, count, phase).
 567      */
 568     void drawOval(const GrPaint& paint,
 569                   const SkRect& oval,
 570                   const GrStrokeInfo& strokeInfo);
 571
 572     ///////////////////////////////////////////////////////////////////////////
 573     // Misc.
 574
 575     /**
 576      * Flags that affect flush() behavior.
 577      */
 578     enum FlushBits {
 579         /**
 580          * A client may reach a point where it has partially rendered a frame
 581          * through a GrContext that it knows the user will never see. This flag
 582          * causes the flush to skip submission of deferred content to the 3D API
 583          * during the flush.
 584          */
 585         kDiscard_FlushBit                    = 0x2,
 586     };
 587
 588     /**
 589      * Call to ensure all drawing to the context has been issued to the
 590      * underlying 3D API.
 591      * @param flagsBitfield     flags that control the flushing behavior. See
 592      *                          FlushBits.
 593      */
 594     void flush(int flagsBitfield = 0);
 595
 596    /**
 597     * These flags can be used with the read/write pixels functions below.
 598     */
 599     enum PixelOpsFlags {
 600         /** The GrContext will not be flushed. This means that the read or write may occur before
 601             previous draws have executed. */
 602         kDontFlush_PixelOpsFlag = 0x1,
 603         /** The src for write or dst read is unpremultiplied. This is only respected if both the
 604             config src and dst configs are an RGBA/BGRA 8888 format. */
 605         kUnpremul_PixelOpsFlag  = 0x2,
 606     };
 607
 608     /**
 609      * Reads a rectangle of pixels from a render target.
 610      * @param target        the render target to read from. NULL means the current render target.
 611      * @param left          left edge of the rectangle to read (inclusive)
 612      * @param top           top edge of the rectangle to read (inclusive)
 613      * @param width         width of rectangle to read in pixels.
 614      * @param height        height of rectangle to read in pixels.
 615      * @param config        the pixel config of the destination buffer
 616      * @param buffer        memory to read the rectangle into.
 617      * @param rowBytes      number of bytes bewtween consecutive rows. Zero means rows are tightly
 618      *                      packed.
 619      * @param pixelOpsFlags see PixelOpsFlags enum above.
 620      *
 621      * @return true if the read succeeded, false if not. The read can fail because of an unsupported
 622      *         pixel config or because no render target is currently set and NULL was passed for
 623      *         target.
 624      */
 625     bool readRenderTargetPixels(GrRenderTarget* target,
 626                                 int left, int top, int width, int height,
 627                                 GrPixelConfig config, void* buffer,
 628                                 size_t rowBytes = 0,
 629                                 uint32_t pixelOpsFlags = 0);
 630
 631     /**
 632      * Copy the src pixels [buffer, row bytes, pixel config] into a render target at the specified
 633      * rectangle.
 634      * @param target        the render target to write into. NULL means the current render target.
 635      * @param left          left edge of the rectangle to write (inclusive)
 636      * @param top           top edge of the rectangle to write (inclusive)
 637      * @param width         width of rectangle to write in pixels.
 638      * @param height        height of rectangle to write in pixels.
 639      * @param config        the pixel config of the source buffer
 640      * @param buffer        memory to read the rectangle from.
 641      * @param rowBytes      number of bytes between consecutive rows. Zero means rows are tightly
 642      *                      packed.
 643      * @param pixelOpsFlags see PixelOpsFlags enum above.
 644      *
 645      * @return true if the write succeeded, false if not. The write can fail because of an
 646      *         unsupported combination of target and pixel configs.
 647      */
 648     bool writeRenderTargetPixels(GrRenderTarget* target,
 649                                  int left, int top, int width, int height,
 650                                  GrPixelConfig config, const void* buffer,
 651                                  size_t rowBytes = 0,
 652                                  uint32_t pixelOpsFlags = 0);
 653
 654     /**
 655      * Reads a rectangle of pixels from a texture.
 656      * @param texture       the texture to read from.
 657      * @param left          left edge of the rectangle to read (inclusive)
 658      * @param top           top edge of the rectangle to read (inclusive)
 659      * @param width         width of rectangle to read in pixels.
 660      * @param height        height of rectangle to read in pixels.
 661      * @param config        the pixel config of the destination buffer
 662      * @param buffer        memory to read the rectangle into.
 663      * @param rowBytes      number of bytes between consecutive rows. Zero means rows are tightly
 664      *                      packed.
 665      * @param pixelOpsFlags see PixelOpsFlags enum above.
 666      *
 667      * @return true if the read succeeded, false if not. The read can fail because of an unsupported
 668      *         pixel config.
 669      */
 670     bool readTexturePixels(GrTexture* texture,
 671                            int left, int top, int width, int height,
 672                            GrPixelConfig config, void* buffer,
 673                            size_t rowBytes = 0,
 674                            uint32_t pixelOpsFlags = 0);
 675
 676     /**
 677      * Writes a rectangle of pixels to a texture.
 678      * @param texture       the render target to read from.
 679      * @param left          left edge of the rectangle to write (inclusive)
 680      * @param top           top edge of the rectangle to write (inclusive)
 681      * @param width         width of rectangle to write in pixels.
 682      * @param height        height of rectangle to write in pixels.
 683      * @param config        the pixel config of the source buffer
 684      * @param buffer        memory to read pixels from
 685      * @param rowBytes      number of bytes between consecutive rows. Zero
 686      *                      means rows are tightly packed.
 687      * @param pixelOpsFlags see PixelOpsFlags enum above.
 688      * @return true if the write succeeded, false if not. The write can fail because of an
 689      *         unsupported combination of texture and pixel configs.
 690      */
 691     bool writeTexturePixels(GrTexture* texture,
 692                             int left, int top, int width, int height,
 693                             GrPixelConfig config, const void* buffer,
 694                             size_t rowBytes,
 695                             uint32_t pixelOpsFlags = 0);
 696
 697     /**
 698      * Copies a rectangle of texels from src to dst. The size of dst is the size of the rectangle
 699      * copied and topLeft is the position of the rect in src. The rectangle is clipped to src's
 700      * bounds.
 701      * @param src           the texture to copy from.
 702      * @param dst           the render target to copy to.
 703      * @param topLeft       the point in src that will be copied to the top-left of dst. If NULL,
 704      *                      (0, 0) will be used.
 705      */
 706     void copyTexture(GrTexture* src, GrRenderTarget* dst, const SkIPoint* topLeft = NULL);
 707
 708     /**
 709      * Resolves a render target that has MSAA. The intermediate MSAA buffer is
 710      * down-sampled to the associated GrTexture (accessible via
 711      * GrRenderTarget::asTexture()). Any pending draws to the render target will
 712      * be executed before the resolve.
 713      *
 714      * This is only necessary when a client wants to access the object directly
 715      * using the backend API directly. GrContext will detect when it must
 716      * perform a resolve to a GrTexture used as the source of a draw or before
 717      * reading pixels back from a GrTexture or GrRenderTarget.
 718      */
 719     void resolveRenderTarget(GrRenderTarget*);
 720
 721     /**
 722      * Provides a perfomance hint that the render target's contents are allowed
 723      * to become undefined.
 724      */
 725     void discardRenderTarget(GrRenderTarget*);
 726
 727 #ifdef SK_DEVELOPER
 728     void dumpFontCache() const;
 729 #endif
 730
 731     ///////////////////////////////////////////////////////////////////////////
 732     // Helpers
 733
 734     class AutoRenderTarget : public ::SkNoncopyable {
 735     public:
 736         AutoRenderTarget(GrContext* context, GrRenderTarget* target) {
 737             fPrevTarget = context->getRenderTarget();
 738             SkSafeRef(fPrevTarget);
 739             context->setRenderTarget(target);
 740             fContext = context;
 741         }
 742         AutoRenderTarget(GrContext* context) {
 743             fPrevTarget = context->getRenderTarget();
 744             SkSafeRef(fPrevTarget);
 745             fContext = context;
 746         }
 747         ~AutoRenderTarget() {
 748             if (fContext) {
 749                 fContext->setRenderTarget(fPrevTarget);
 750             }
 751             SkSafeUnref(fPrevTarget);
 752         }
 753     private:
 754         GrContext*      fContext;
 755         GrRenderTarget* fPrevTarget;
 756     };
 757
 758     /**
 759      * Save/restore the view-matrix in the context. It can optionally adjust a paint to account
 760      * for a coordinate system change. Here is an example of how the paint param can be used:
 761      *
 762      * A GrPaint is setup with GrProcessors. The stages will have access to the pre-matrix source
 763      * geometry positions when the draw is executed. Later on a decision is made to transform the
 764      * geometry to device space on the CPU. The effects now need to know that the space in which
 765      * the geometry will be specified has changed.
 766      *
 767      * Note that when restore is called (or in the destructor) the context's matrix will be
 768      * restored. However, the paint will not be restored. The caller must make a copy of the
 769      * paint if necessary. Hint: use SkTCopyOnFirstWrite if the AutoMatrix is conditionally
 770      * initialized.
 771      */
 772     class AutoMatrix : public ::SkNoncopyable {
 773     public:
 774         AutoMatrix() : fContext(NULL) {}
 775
 776         ~AutoMatrix() { this->restore(); }
 777
 778         /**
 779          * Initializes by pre-concat'ing the context's current matrix with the preConcat param.
 780          */
 781         void setPreConcat(GrContext* context, const SkMatrix& preConcat, GrPaint* paint = NULL) {
 782             SkASSERT(context);
 783
 784             this->restore();
 785
 786             fContext = context;
 787             fMatrix = context->getMatrix();
 788             this->preConcat(preConcat, paint);
 789         }
 790
 791         /**
 792          * Sets the context's matrix to identity. Returns false if the inverse matrix is required to
 793          * update a paint but the matrix cannot be inverted.
 794          */
 795         bool setIdentity(GrContext* context, GrPaint* paint = NULL) {
 796             SkASSERT(context);
 797
 798             this->restore();
 799
 800             if (paint) {
 801                 if (!paint->localCoordChangeInverse(context->getMatrix())) {
 802                     return false;
 803                 }
 804             }
 805             fMatrix = context->getMatrix();
 806             fContext = context;
 807             context->setIdentityMatrix();
 808             return true;
 809         }
 810
 811         /**
 812          * Replaces the context's matrix with a new matrix. Returns false if the inverse matrix is
 813          * required to update a paint but the matrix cannot be inverted.
 814          */
 815         bool set(GrContext* context, const SkMatrix& newMatrix, GrPaint* paint = NULL) {
 816             if (paint) {
 817                 if (!this->setIdentity(context, paint)) {
 818                     return false;
 819                 }
 820                 this->preConcat(newMatrix, paint);
 821             } else {
 822                 this->restore();
 823                 fContext = context;
 824                 fMatrix = context->getMatrix();
 825                 context->setMatrix(newMatrix);
 826             }
 827             return true;
 828         }
 829
 830         /**
 831          * If this has been initialized then the context's matrix will be further updated by
 832          * pre-concat'ing the preConcat param. The matrix that will be restored remains unchanged.
 833          * The paint is assumed to be relative to the context's matrix at the time this call is
 834          * made, not the matrix at the time AutoMatrix was first initialized. In other words, this
 835          * performs an incremental update of the paint.
 836          */
 837         void preConcat(const SkMatrix& preConcat, GrPaint* paint = NULL) {
 838             if (paint) {
 839                 paint->localCoordChange(preConcat);
 840             }
 841             fContext->concatMatrix(preConcat);
 842         }
 843
 844         /**
 845          * Returns false if never initialized or the inverse matrix was required to update a paint
 846          * but the matrix could not be inverted.
 847          */
 848         bool succeeded() const { return SkToBool(fContext); }
 849
 850         /**
 851          * If this has been initialized then the context's original matrix is restored.
 852          */
 853         void restore() {
 854             if (fContext) {
 855                 fContext->setMatrix(fMatrix);
 856                 fContext = NULL;
 857             }
 858         }
 859
 860     private:
 861         GrContext*  fContext;
 862         SkMatrix    fMatrix;
 863     };
 864
 865     class AutoClip : public ::SkNoncopyable {
 866     public:
 867         // This enum exists to require a caller of the constructor to acknowledge that the clip will
 868         // initially be wide open. It also could be extended if there are other desirable initial
 869         // clip states.
 870         enum InitialClip {
 871             kWideOpen_InitialClip,
 872         };
 873
 874         AutoClip(GrContext* context, InitialClip initialState)
 875         : fContext(context) {
 876             SkASSERT(kWideOpen_InitialClip == initialState);
 877             fNewClipData.fClipStack = &fNewClipStack;
 878
 879             fOldClip = context->getClip();
 880             context->setClip(&fNewClipData);
 881         }
 882
 883         AutoClip(GrContext* context, const SkRect& newClipRect)
 884         : fContext(context)
 885         , fNewClipStack(newClipRect) {
 886             fNewClipData.fClipStack = &fNewClipStack;
 887
 888             fOldClip = fContext->getClip();
 889             fContext->setClip(&fNewClipData);
 890         }
 891
 892         ~AutoClip() {
 893             if (fContext) {
 894                 fContext->setClip(fOldClip);
 895             }
 896         }
 897     private:
 898         GrContext*        fContext;
 899         const GrClipData* fOldClip;
 900
 901         SkClipStack       fNewClipStack;
 902         GrClipData        fNewClipData;
 903     };
 904
 905     class AutoWideOpenIdentityDraw {
 906     public:
 907         AutoWideOpenIdentityDraw(GrContext* ctx, GrRenderTarget* rt)
 908             : fAutoClip(ctx, AutoClip::kWideOpen_InitialClip)
 909             , fAutoRT(ctx, rt) {
 910             fAutoMatrix.setIdentity(ctx);
 911             // should never fail with no paint param.
 912             SkASSERT(fAutoMatrix.succeeded());
 913         }
 914
 915     private:
 916         AutoClip fAutoClip;
 917         AutoRenderTarget fAutoRT;
 918         AutoMatrix fAutoMatrix;
 919     };
 920
 921     ///////////////////////////////////////////////////////////////////////////
 922     // Functions intended for internal use only.
 923     GrGpu* getGpu() { return fGpu; }
 924     const GrGpu* getGpu() const { return fGpu; }
 925     GrFontCache* getFontCache() { return fFontCache; }
 926     GrLayerCache* getLayerCache() { return fLayerCache.get(); }
 927     GrDrawTarget* getTextTarget();
 928     const GrIndexBuffer* getQuadIndexBuffer() const;
 929     GrAARectRenderer* getAARectRenderer() { return fAARectRenderer; }
 930     GrResourceCache2* getResourceCache2() { return fResourceCache2; }
 931
 932     // Called by tests that draw directly to the context via GrDrawTarget
 933     void getTestTarget(GrTestTarget*);
 934
 935     void addGpuTraceMarker(const GrGpuTraceMarker* marker);
 936     void removeGpuTraceMarker(const GrGpuTraceMarker* marker);
 937
 938     /**
 939      * Stencil buffers add themselves to the cache using addStencilBuffer. findStencilBuffer is
 940      * called to check the cache for a SB that matches an RT's criteria.
 941      */
 942     void addStencilBuffer(GrStencilBuffer* sb);
 943     GrStencilBuffer* findStencilBuffer(int width, int height, int sampleCnt);
 944
 945     GrPathRenderer* getPathRenderer(
 946                     const SkPath& path,
 947                     const SkStrokeRec& stroke,
 948                     const GrDrawTarget* target,
 949                     bool allowSW,
 950                     GrPathRendererChain::DrawType drawType = GrPathRendererChain::kColor_DrawType,
 951                     GrPathRendererChain::StencilSupport* stencilSupport = NULL);
 952
 953     /**
 954      *  This returns a copy of the the GrContext::Options that was passed to the
 955      *  constructor of this class.
 956      */
 957     const Options& getOptions() const { return fOptions; }
 958
 959 #if GR_CACHE_STATS
 960     void printCacheStats() const;
 961 #endif
 962
 963     class GPUStats {
 964     public:
 965 #if GR_GPU_STATS
 966         GPUStats() { this->reset(); }
 967
 968         void reset() { fRenderTargetBinds = 0; fShaderCompilations = 0; }
 969
 970         int renderTargetBinds() const { return fRenderTargetBinds; }
 971         void incRenderTargetBinds() { fRenderTargetBinds++; }
 972         int shaderCompilations() const { return fShaderCompilations; }
 973         void incShaderCompilations() { fShaderCompilations++; }
 974     private:
 975         int fRenderTargetBinds;
 976         int fShaderCompilations;
 977 #else
 978         void incRenderTargetBinds() {}
 979         void incShaderCompilations() {}
 980 #endif
 981     };
 982
 983 #if GR_GPU_STATS
 984     const GPUStats* gpuStats() const;
 985 #endif
 986
 987 private:
 988     // Used to indicate whether a draw should be performed immediately or queued in fDrawBuffer.
 989     enum BufferedDraw {
 990         kYes_BufferedDraw,
 991         kNo_BufferedDraw,
 992     };
 993     BufferedDraw fLastDrawWasBuffered;
 994
 995     GrGpu*                          fGpu;
 996     SkMatrix                        fViewMatrix;
 997     SkAutoTUnref<GrRenderTarget>    fRenderTarget;
 998     const GrClipData*               fClip;  // TODO: make this ref counted
 999     GrDrawState*                    fDrawState;
1000
1001     GrResourceCache*                fResourceCache;
1002     GrResourceCache2*               fResourceCache2;
1003     GrFontCache*                    fFontCache;
1004     SkAutoTDelete<GrLayerCache>     fLayerCache;
1005
1006     GrPathRendererChain*            fPathRendererChain;
1007     GrSoftwarePathRenderer*         fSoftwarePathRenderer;
1008
1009     GrVertexBufferAllocPool*        fDrawBufferVBAllocPool;
1010     GrIndexBufferAllocPool*         fDrawBufferIBAllocPool;
1011     GrInOrderDrawBuffer*            fDrawBuffer;
1012
1013     // Set by OverbudgetCB() to request that GrContext flush before exiting a draw.
1014     bool                            fFlushToReduceCacheSize;
1015
1016     GrAARectRenderer*               fAARectRenderer;
1017     GrOvalRenderer*                 fOvalRenderer;
1018
1019     bool                            fDidTestPMConversions;
1020     int                             fPMToUPMConversion;
1021     int                             fUPMToPMConversion;
1022
1023     struct CleanUpData {
1024         PFCleanUpFunc fFunc;
1025         void*         fInfo;
1026     };
1027
1028     SkTDArray<CleanUpData>          fCleanUpData;
1029
1030     int                             fMaxTextureSizeOverride;
1031
1032     const Options                   fOptions;
1033
1034     GrContext(const Options&); // init must be called after the constructor.
1035     bool init(GrBackend, GrBackendContext);
1036
1037     void setupDrawBuffer();
1038
1039     class AutoRestoreEffects;
1040     class AutoCheckFlush;
1041     /// Sets the paint and returns the target to draw into. The paint can be NULL in which case the
1042     /// draw state is left unmodified.
1043     GrDrawTarget* prepareToDraw(const GrPaint*, BufferedDraw, AutoRestoreEffects*, AutoCheckFlush*);
1044
1045     void internalDrawPath(GrDrawTarget* target, bool useAA, const SkPath& path,
1046                           const GrStrokeInfo& stroke);
1047
1048     GrTexture* createResizedTexture(const GrTextureDesc& desc,
1049                                     const GrCacheID& cacheID,
1050                                     const void* srcData,
1051                                     size_t rowBytes,
1052                                     bool filter);
1053
1054     // Needed so GrTexture's returnToCache helper function can call
1055     // addExistingTextureToCache
1056     friend class GrTexture;
1057     friend class GrStencilAndCoverPathRenderer;
1058     friend class GrStencilAndCoverTextContext;
1059
1060     // Add an existing texture to the texture cache. This is intended solely
1061     // for use with textures released from an GrAutoScratchTexture.
1062     void addExistingTextureToCache(GrTexture* texture);
1063
1064     /**
1065      * These functions create premul <-> unpremul effects if it is possible to generate a pair
1066      * of effects that make a readToUPM->writeToPM->readToUPM cycle invariant. Otherwise, they
1067      * return NULL.
1068      */
1069     const GrFragmentProcessor* createPMToUPMEffect(GrTexture*, bool swapRAndB, const SkMatrix&);
1070     const GrFragmentProcessor* createUPMToPMEffect(GrTexture*, bool swapRAndB, const SkMatrix&);
1071
1072     /**
1073      *  This callback allows the resource cache to callback into the GrContext
1074      *  when the cache is still overbudget after a purge.
1075      */
1076     static bool OverbudgetCB(void* data);
1077
1078     typedef SkRefCnt INHERITED;
1079 };
1080
1081 /**
1082  * Gets and locks a scratch texture from a descriptor using either exact or approximate criteria.
1083  * Unlocks texture in the destructor.
1084  */
1085 class GrAutoScratchTexture : public ::SkNoncopyable {
1086 public:
1087     GrAutoScratchTexture()
1088         : fContext(NULL)
1089         , fTexture(NULL) {
1090     }
1091
1092     GrAutoScratchTexture(GrContext* context,
1093                          const GrTextureDesc& desc,
1094                          GrContext::ScratchTexMatch match = GrContext::kApprox_ScratchTexMatch)
1095       : fContext(NULL)
1096       , fTexture(NULL) {
1097       this->set(context, desc, match);
1098     }
1099
1100     ~GrAutoScratchTexture() {
1101         this->reset();
1102     }
1103
1104     void reset() {
1105         if (fContext && fTexture) {
1106             fContext->unlockScratchTexture(fTexture);
1107             fTexture->unref();
1108             fTexture = NULL;
1109         }
1110     }
1111
1112     /*
1113      * When detaching a texture we do not unlock it in the texture cache but
1114      * we do set the returnToCache flag. In this way the texture remains
1115      * "locked" in the texture cache until it is freed and recycled in
1116      * GrTexture::internal_dispose. In reality, the texture has been removed
1117      * from the cache (because this is in AutoScratchTexture) and by not
1118      * calling unlockScratchTexture we simply don't re-add it. It will be
1119      * reattached in GrTexture::internal_dispose.
1120      *
1121      * Note that the caller is assumed to accept and manage the ref to the
1122      * returned texture.
1123      */
1124     GrTexture* detach() {
1125         if (NULL == fTexture) {
1126             return NULL;
1127         }
1128         GrTexture* texture = fTexture;
1129         fTexture = NULL;
1130
1131         // This GrAutoScratchTexture has a ref from lockAndRefScratchTexture, which we give up now.
1132         // The cache also has a ref which we are lending to the caller of detach(). When the caller
1133         // lets go of the ref and the ref count goes to 0 internal_dispose will see this flag is
1134         // set and re-ref the texture, thereby restoring the cache's ref.
1135         SkASSERT(!texture->unique());
1136         texture->impl()->setFlag((GrTextureFlags) GrTextureImpl::kReturnToCache_FlagBit);
1137         texture->unref();
1138         SkASSERT(texture->getCacheEntry());
1139
1140         return texture;
1141     }
1142
1143     GrTexture* set(GrContext* context,
1144                    const GrTextureDesc& desc,
1145                    GrContext::ScratchTexMatch match = GrContext::kApprox_ScratchTexMatch) {
1146         this->reset();
1147
1148         fContext = context;
1149         if (fContext) {
1150             fTexture = fContext->lockAndRefScratchTexture(desc, match);
1151             if (NULL == fTexture) {
1152                 fContext = NULL;
1153             }
1154             return fTexture;
1155         } else {
1156             return NULL;
1157         }
1158     }
1159
1160     GrTexture* texture() { return fTexture; }
1161
1162 private:
1163     GrContext*                    fContext;
1164     GrTexture*                    fTexture;
1165 };
1166
1167 #endif