gfxTarget.h

Public Typedefs

StrongRefPtr< GFXTarget >

GFXTargetRef 

StrongRefPtr< GFXTextureTarget >

GFXTextureTargetRef 

StrongRefPtr< GFXWindowTarget >

GFXWindowTargetRef 

Public Typedefs

typedef StrongRefPtr< GFXTarget > GFXTargetRef 

typedef StrongRefPtr< GFXTextureTarget > GFXTextureTargetRef 

typedef StrongRefPtr< GFXWindowTarget > GFXWindowTargetRef 

  1
  2//-----------------------------------------------------------------------------
  3// Copyright (c) 2012 GarageGames, LLC
  4//
  5// Permission is hereby granted, free of charge, to any person obtaining a copy
  6// of this software and associated documentation files (the "Software"), to
  7// deal in the Software without restriction, including without limitation the
  8// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
  9// sell copies of the Software, and to permit persons to whom the Software is
 10// furnished to do so, subject to the following conditions:
 11//
 12// The above copyright notice and this permission notice shall be included in
 13// all copies or substantial portions of the Software.
 14//
 15// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 16// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 17// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 18// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 19// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 20// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 21// IN THE SOFTWARE.
 22//-----------------------------------------------------------------------------
 23
 24#ifndef _GFXTARGET_H_
 25#define _GFXTARGET_H_
 26
 27#ifndef _REFBASE_H_
 28#include "core/util/refBase.h"
 29#endif
 30#ifndef _GFXENUMS_H_
 31#include "gfx/gfxEnums.h"
 32#endif
 33#ifndef _GFXRESOURCE_H_
 34#include "gfx/gfxResource.h"
 35#endif
 36#ifndef _MPOINT3_H_
 37#include "math/mPoint3.h"
 38#endif
 39
 40
 41class Point2I;
 42class PlatformWindow;
 43class GFXCubemap;
 44class GFXTextureObject;
 45
 46/// Base class for a target to which GFX can render.
 47///
 48/// Most modern graphics hardware supports selecting render targets. However,
 49/// there may be multiple types of render target, with wildly varying
 50/// device-level implementations, resource requirements, and so forth.
 51///
 52/// This base class is used to represent a render target; it might be a context
 53/// tied to a window, or a set of surfaces or textures.
 54class GFXTarget : public StrongRefBase, public GFXResource
 55{
 56
 57private:
 58   S32 mChangeToken;
 59   S32 mLastAppliedChange;
 60
 61protected:
 62
 63   /// Called whenever a change is made to this target.
 64   inline void invalidateState()
 65   {
 66      mChangeToken++;
 67   }
 68
 69   /// Called when the device has applied pending state.
 70   inline void stateApplied()
 71   {
 72      mLastAppliedChange = mChangeToken;
 73   }
 74public:
 75
 76   /// Constructor to initialize the state tracking logic.
 77   GFXTarget() : mChangeToken( 0 ),
 78                 mLastAppliedChange( 0 )
 79   {
 80   }
 81   virtual ~GFXTarget() {}
 82
 83   /// Called to check if we have pending state for the device to apply.
 84   inline const bool isPendingState() const
 85   {
 86      return (mChangeToken != mLastAppliedChange);
 87   }
 88
 89   /// Returns the size in pixels of the render target.
 90   virtual const Point2I getSize()=0;
 91
 92   /// Returns the texture format of the render target.
 93   virtual GFXFormat getFormat()=0;
 94
 95   // GFXResourceInterface
 96   /// The resource should put a description of itself (number of vertices, size/width of texture, etc.) in buffer
 97   virtual const String describeSelf() const;
 98
 99   /// This is called to set the render target.
100   virtual void activate() { }
101
102   /// This is called when the target is not being used anymore.
103   virtual void deactivate() { }
104
105   /// This tells the target that the contents of this target should be restored
106   /// when activate() is next called.
107   virtual void preserve() { }
108
109   /// Copy this surface to the passed GFXTextureObject.   
110   /// @param tex The GFXTextureObject to copy to.
111   virtual void resolveTo( GFXTextureObject *tex ) { }
112};
113
114/// A render target associated with an OS window.
115///
116/// Various API/OS combinations will implement their own GFXTargets for
117/// rendering to a window. However, they are all subclasses of GFXWindowTarget.
118///
119/// This allows platform-neutral code to safely distinguish between various
120/// types of render targets (using dynamic_cast<>), as well as letting it
121/// gain access to useful things like the corresponding PlatformWindow.
122class GFXWindowTarget : public GFXTarget
123{
124protected:
125   PlatformWindow *mWindow;
126public:
127   GFXWindowTarget() : mWindow(NULL){};
128   GFXWindowTarget( PlatformWindow *windowObject )
129   {
130      mWindow = windowObject;
131   }
132   virtual ~GFXWindowTarget() {}
133
134   /// Returns a pointer to the window this target is bound to.
135   inline PlatformWindow *getWindow() { return mWindow; };
136
137   /// Present latest buffer, if buffer swapping is in effect.
138   virtual bool present()=0;
139
140   /// Notify the target that the video mode on the window has changed.
141   virtual void resetMode()=0;
142};
143
144/// A render target associated with one or more textures.
145///
146/// Although some APIs allow directly selecting any texture or surfaces, in
147/// some cases it is necessary to allocate helper resources to enable RTT
148/// operations.
149///
150/// @note A GFXTextureTarget will retain references to textures that are 
151/// attached to it, so be sure to clear them out when you're done!
152///
153/// @note Different APIs have different restrictions on what they can support
154///       here. Be aware when mixing cubemaps vs. non-cubemaps, or targets of
155///       different resolutions. The devices will attempt to limit behavior
156///       to things that are safely portable, but they cannot catch every
157///       possible situation for all drivers and API - so make sure to
158///       actually test things!
159class GFXTextureTarget : public GFXTarget
160{
161public:
162   enum RenderSlot
163   {
164      DepthStencil,
165      Color0, Color1, Color2, Color3, Color4, Color5,
166      MaxRenderSlotId,
167   };
168
169   static GFXTextureObject *sDefaultDepthStencil;
170
171   virtual ~GFXTextureTarget() {}
172
173   /// Attach a surface to a given slot as part of this render target.
174   ///
175   /// @param slot What slot is used for multiple render target (MRT) effects.
176   ///             Most of the time you'll use Color0.
177   /// @param tex A texture and miplevel to bind for rendering, or else NULL/0
178   ///            to clear a slot.
179   /// @param mipLevel What level of this texture are we rendering to?
180   /// @param zOffset  If this is a depth texture, what z level are we 
181   ///                 rendering to?
182   virtual void attachTexture(RenderSlot slot, GFXTextureObject *tex, U32 mipLevel=0, U32 zOffset = 0) = 0;
183
184   /// Support binding to cubemaps.
185   ///
186   /// @param slot What slot is used for multiple render target (MRT) effects.
187   ///             Most of the time you'll use Color0.
188   /// @param tex  What cubemap will we be rendering to?
189   /// @param face A face identifier.
190   /// @param mipLevel What level of this texture are we rendering to?
191   virtual void attachTexture(RenderSlot slot, GFXCubemap *tex, U32 face, U32 mipLevel=0) = 0;
192
193   /// Resolve the current render target data to the associated textures. This method
194   /// will get called automatically when a rendertarget is changed, before new geometry
195   /// is drawn to a different rendertarget. This method can also be called to 
196   /// gather render target data without switching targets.
197   /// 
198   /// By default, this method will resolve all color targets.
199   virtual void resolve()=0;
200
201   /// Returns true if the automatic generation of mip maps is enabled
202   inline bool isGenMipsEnabled() const { return mGenMips; }
203
204protected:
205   bool mGenMips;
206};
207
208typedef StrongRefPtr<GFXTarget> GFXTargetRef;
209typedef StrongRefPtr<GFXWindowTarget> GFXWindowTargetRef;
210typedef StrongRefPtr<GFXTextureTarget> GFXTextureTargetRef;
211
212#endif // _GFXTARGET_H_
213