GrRenderTarget.h revision 81beccc4fb1396fe94af15bfce26e68b82b93809 
1/*
2 * Copyright 2011 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 GrRenderTarget_DEFINED
9#define GrRenderTarget_DEFINED
10
11#include "GrSurface.h"
12#include "SkRect.h"
13
14class GrStencilBuffer;
15class GrTexture;
16
17/**
18 * GrRenderTarget represents a 2D buffer of pixels that can be rendered to.
19 * A context's render target is set by setRenderTarget(). Render targets are
20 * created by a createTexture with the kRenderTarget_TextureFlag flag.
21 * Additionally, GrContext provides methods for creating GrRenderTargets
22 * that wrap externally created render targets.
23 */
24class GrRenderTarget : public GrSurface {
25public:
26    SK_DECLARE_INST_COUNT(GrRenderTarget)
27
28    // GrResource overrides
29    virtual size_t gpuMemorySize() const SK_OVERRIDE;
30
31    // GrSurface overrides
32    /**
33     * @return the texture associated with the render target, may be NULL.
34     */
35    virtual GrTexture* asTexture() SK_OVERRIDE { return fTexture; }
36    virtual const GrTexture* asTexture() const SK_OVERRIDE { return fTexture; }
37
38    /**
39     * @return this render target.
40     */
41    virtual GrRenderTarget* asRenderTarget() SK_OVERRIDE { return this; }
42    virtual const GrRenderTarget* asRenderTarget() const  SK_OVERRIDE {
43        return this;
44    }
45
46    // GrRenderTarget
47    /**
48     * If this RT is multisampled, this is the multisample buffer
49     * @return the 3D API's handle to this object (e.g. FBO ID in OpenGL)
50     */
51    virtual GrBackendObject getRenderTargetHandle() const = 0;
52
53    /**
54     * If this RT is multisampled, this is the buffer it is resolved to.
55     * Otherwise, same as getRenderTargetHandle().
56     * (In GL a separate FBO ID is used for the MSAA and resolved buffers)
57     * @return the 3D API's handle to this object (e.g. FBO ID in OpenGL)
58     */
59    virtual GrBackendObject getRenderTargetResolvedHandle() const = 0;
60
61    /**
62     * @return true if the surface is multisampled, false otherwise
63     */
64    bool isMultisampled() const { return 0 != fDesc.fSampleCnt; }
65
66    /**
67     * @return the number of samples-per-pixel or zero if non-MSAA.
68     */
69    int numSamples() const { return fDesc.fSampleCnt; }
70
71    /**
72     * Call to indicate the multisample contents were modified such that the
73     * render target needs to be resolved before it can be used as texture. Gr
74     * tracks this for its own drawing and thus this only needs to be called
75     * when the render target has been modified outside of Gr. This has no
76     * effect on wrapped backend render targets.
77     *
78     * @param rect  a rect bounding the area needing resolve. NULL indicates
79     *              the whole RT needs resolving.
80     */
81    void flagAsNeedingResolve(const SkIRect* rect = NULL);
82
83    /**
84     * Call to override the region that needs to be resolved.
85     */
86    void overrideResolveRect(const SkIRect rect);
87
88    /**
89     * Call to indicate that GrRenderTarget was externally resolved. This may
90     * allow Gr to skip a redundant resolve step.
91     */
92    void flagAsResolved() { fResolveRect.setLargestInverted(); }
93
94    /**
95     * @return true if the GrRenderTarget requires MSAA resolving
96     */
97    bool needsResolve() const { return !fResolveRect.isEmpty(); }
98
99    /**
100     * Returns a rect bounding the region needing resolving.
101     */
102    const SkIRect& getResolveRect() const { return fResolveRect; }
103
104    /**
105     * If the render target is multisampled this will perform a multisample
106     * resolve. Any pending draws to the target are first flushed. This only
107     * applies to render targets that are associated with GrTextures. After the
108     * function returns the GrTexture will contain the resolved pixels.
109     */
110    void resolve();
111
112    /**
113     * Provide a performance hint that the render target's contents are allowed
114     * to become undefined.
115     */
116    void discard();
117
118    // a MSAA RT may require explicit resolving , it may auto-resolve (e.g. FBO
119    // 0 in GL), or be unresolvable because the client didn't give us the
120    // resolve destination.
121    enum ResolveType {
122        kCanResolve_ResolveType,
123        kAutoResolves_ResolveType,
124        kCantResolve_ResolveType,
125    };
126    virtual ResolveType getResolveType() const = 0;
127
128    /**
129     * GrStencilBuffer is not part of the public API.
130     */
131    GrStencilBuffer* getStencilBuffer() const { return fStencilBuffer; }
132    void setStencilBuffer(GrStencilBuffer* stencilBuffer);
133
134protected:
135    GrRenderTarget(GrGpu* gpu,
136                   bool isWrapped,
137                   GrTexture* texture,
138                   const GrTextureDesc& desc)
139        : INHERITED(gpu, isWrapped, desc)
140        , fStencilBuffer(NULL)
141        , fTexture(texture) {
142        fResolveRect.setLargestInverted();
143    }
144
145    // override of GrResource
146    virtual void onAbandon() SK_OVERRIDE;
147    virtual void onRelease() SK_OVERRIDE;
148
149private:
150    friend class GrTexture;
151    // called by ~GrTexture to remove the non-ref'ed back ptr.
152    void owningTextureDestroyed() {
153        SkASSERT(fTexture);
154        fTexture = NULL;
155    }
156
157    GrStencilBuffer*  fStencilBuffer;
158    GrTexture*        fTexture; // not ref'ed
159
160    SkIRect           fResolveRect;
161
162    typedef GrSurface INHERITED;
163};
164
165#endif
166