GrRenderTarget.h revision ed8659b51d9f2bad3f004df6033d72cc32d71c0d 
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 "GrRect.h"
12#include "GrSurface.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 sizeInBytes() 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    virtual bool readPixels(int left, int top, int width, int height,
47                            GrPixelConfig config,
48                            void* buffer,
49                            size_t rowBytes = 0,
50                            uint32_t pixelOpsFlags = 0) SK_OVERRIDE;
51
52    virtual void writePixels(int left, int top, int width, int height,
53                             GrPixelConfig config,
54                             const void* buffer,
55                             size_t rowBytes = 0,
56                             uint32_t pixelOpsFlags = 0) SK_OVERRIDE;
57
58    // GrRenderTarget
59    /**
60     * If this RT is multisampled, this is the multisample buffer
61     * @return the 3D API's handle to this object (e.g. FBO ID in OpenGL)
62     */
63    virtual GrBackendObject getRenderTargetHandle() const = 0;
64
65    /**
66     * If this RT is multisampled, this is the buffer it is resolved to.
67     * Otherwise, same as getRenderTargetHandle().
68     * (In GL a separate FBO ID is used for the MSAA and resolved buffers)
69     * @return the 3D API's handle to this object (e.g. FBO ID in OpenGL)
70     */
71    virtual GrBackendObject getRenderTargetResolvedHandle() const = 0;
72
73    /**
74     * @return true if the surface is multisampled, false otherwise
75     */
76    bool isMultisampled() const { return 0 != fDesc.fSampleCnt; }
77
78    /**
79     * @return the number of samples-per-pixel or zero if non-MSAA.
80     */
81    int numSamples() const { return fDesc.fSampleCnt; }
82
83    /**
84     * Call to indicate the multisample contents were modified such that the
85     * render target needs to be resolved before it can be used as texture. Gr
86     * tracks this for its own drawing and thus this only needs to be called
87     * when the render target has been modified outside of Gr. This has no
88     * effect on wrapped backend render targets.
89     *
90     * @param rect  a rect bounding the area needing resolve. NULL indicates
91     *              the whole RT needs resolving.
92     */
93    void flagAsNeedingResolve(const GrIRect* rect = NULL);
94
95    /**
96     * Call to override the region that needs to be resolved.
97     */
98    void overrideResolveRect(const GrIRect rect);
99
100    /**
101     * Call to indicate that GrRenderTarget was externally resolved. This may
102     * allow Gr to skip a redundant resolve step.
103     */
104    void flagAsResolved() { fResolveRect.setLargestInverted(); }
105
106    /**
107     * @return true if the GrRenderTarget requires MSAA resolving
108     */
109    bool needsResolve() const { return !fResolveRect.isEmpty(); }
110
111    /**
112     * Returns a rect bounding the region needing resolving.
113     */
114    const GrIRect& getResolveRect() const { return fResolveRect; }
115
116    /**
117     * If the render target is multisampled this will perform a multisample
118     * resolve. Any pending draws to the target are first flushed. This only
119     * applies to render targets that are associated with GrTextures. After the
120     * function returns the GrTexture will contain the resolved pixels.
121     */
122    void resolve();
123
124    // a MSAA RT may require explicit resolving , it may auto-resolve (e.g. FBO
125    // 0 in GL), or be unresolvable because the client didn't give us the
126    // resolve destination.
127    enum ResolveType {
128        kCanResolve_ResolveType,
129        kAutoResolves_ResolveType,
130        kCantResolve_ResolveType,
131    };
132    virtual ResolveType getResolveType() const = 0;
133
134    /**
135     * GrStencilBuffer is not part of the public API.
136     */
137    GrStencilBuffer* getStencilBuffer() const { return fStencilBuffer; }
138    void setStencilBuffer(GrStencilBuffer* stencilBuffer);
139
140protected:
141    GrRenderTarget(GrGpu* gpu,
142                   bool isWrapped,
143                   GrTexture* texture,
144                   const GrTextureDesc& desc)
145        : INHERITED(gpu, isWrapped, desc)
146        , fStencilBuffer(NULL)
147        , fTexture(texture) {
148        fResolveRect.setLargestInverted();
149    }
150
151    friend class GrTexture;
152    // When a texture unrefs an owned render target this func
153    // removes the back pointer. This could be called from
154    // texture's destructor but would have to be done in derived
155    // classes. By the time of texture base destructor it has already
156    // lost its pointer to the rt.
157    void onTextureReleaseRenderTarget() {
158        GrAssert(NULL != fTexture);
159        fTexture = NULL;
160    }
161
162    // override of GrResource
163    virtual void onAbandon() SK_OVERRIDE;
164    virtual void onRelease() SK_OVERRIDE;
165
166private:
167    GrStencilBuffer*  fStencilBuffer;
168    GrTexture*        fTexture; // not ref'ed
169
170    GrIRect           fResolveRect;
171
172    typedef GrSurface INHERITED;
173};
174
175#endif
176