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