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   friend class GFXD3D9Device;
 57   friend class GFX360Device;
 58
 59private:
 60   S32 mChangeToken;
 61   S32 mLastAppliedChange;
 62
 63protected:
 64
 65   /// Called whenever a change is made to this target.
 66   inline void invalidateState()
 67   {
 68      mChangeToken++;
 69   }
 70
 71   /// Called when the device has applied pending state.
 72   inline void stateApplied()
 73   {
 74      mLastAppliedChange = mChangeToken;
 75   }
 76public:
 77
 78   /// Constructor to initialize the state tracking logic.
 79   GFXTarget() : mChangeToken( 0 ),
 80                 mLastAppliedChange( 0 )
 81   {
 82   }
 83   virtual ~GFXTarget() {}
 84
 85   /// Called to check if we have pending state for the device to apply.
 86   inline const bool isPendingState() const
 87   {
 88      return (mChangeToken != mLastAppliedChange);
 89   }
 90
 91   /// Returns the size in pixels of the render target.
 92   virtual const Point2I getSize()=0;
 93
 94   /// Returns the texture format of the render target.
 95   virtual GFXFormat getFormat()=0;
 96
 97   // GFXResourceInterface
 98   /// The resource should put a description of itself (number of vertices, size/width of texture, etc.) in buffer
 99   virtual const String describeSelf() const;
100
101   /// This is called to set the render target.
102   virtual void activate() { }
103
104   /// This is called when the target is not being used anymore.
105   virtual void deactivate() { }
106
107   /// This tells the target that the contents of this target should be restored
108   /// when activate() is next called.
109   virtual void preserve() { }
110
111   /// Copy this surface to the passed GFXTextureObject.   
112   /// @param tex The GFXTextureObject to copy to.
113   virtual void resolveTo( GFXTextureObject *tex ) { }
114};
115
116/// A render target associated with an OS window.
117///
118/// Various API/OS combinations will implement their own GFXTargets for
119/// rendering to a window. However, they are all subclasses of GFXWindowTarget.
120///
121/// This allows platform-neutral code to safely distinguish between various
122/// types of render targets (using dynamic_cast<>), as well as letting it
123/// gain access to useful things like the corresponding PlatformWindow.
124class GFXWindowTarget : public GFXTarget
125{
126protected:
127   PlatformWindow *mWindow;
128public:
129   GFXWindowTarget() : mWindow(NULL){};
130   GFXWindowTarget( PlatformWindow *windowObject )
131   {
132      mWindow = windowObject;
133   }
134   virtual ~GFXWindowTarget() {}
135
136   /// Returns a pointer to the window this target is bound to.
137   inline PlatformWindow *getWindow() { return mWindow; };
138
139   /// Present latest buffer, if buffer swapping is in effect.
140   virtual bool present()=0;
141
142   /// Notify the target that the video mode on the window has changed.
143   virtual void resetMode()=0;
144};
145
146/// A render target associated with one or more textures.
147///
148/// Although some APIs allow directly selecting any texture or surfaces, in
149/// some cases it is necessary to allocate helper resources to enable RTT
150/// operations.
151///
152/// @note A GFXTextureTarget will retain references to textures that are 
153/// attached to it, so be sure to clear them out when you're done!
154///
155/// @note Different APIs have different restrictions on what they can support
156///       here. Be aware when mixing cubemaps vs. non-cubemaps, or targets of
157///       different resolutions. The devices will attempt to limit behavior
158///       to things that are safely portable, but they cannot catch every
159///       possible situation for all drivers and API - so make sure to
160///       actually test things!
161class GFXTextureTarget : public GFXTarget
162{
163public:
164   enum RenderSlot
165   {
166      DepthStencil,
167      Color0, Color1, Color2, Color3, Color4,
168      MaxRenderSlotId,
169   };
170
171   static GFXTextureObject *sDefaultDepthStencil;
172
173   virtual ~GFXTextureTarget() {}
174
175   /// Attach a surface to a given slot as part of this render target.
176   ///
177   /// @param slot What slot is used for multiple render target (MRT) effects.
178   ///             Most of the time you'll use Color0.
179   /// @param tex A texture and miplevel to bind for rendering, or else NULL/0
180   ///            to clear a slot.
181   /// @param mipLevel What level of this texture are we rendering to?
182   /// @param zOffset  If this is a depth texture, what z level are we 
183   ///                 rendering to?
184   virtual void attachTexture(RenderSlot slot, GFXTextureObject *tex, U32 mipLevel=0, U32 zOffset = 0) = 0;
185
186   /// Support binding to cubemaps.
187   ///
188   /// @param slot What slot is used for multiple render target (MRT) effects.
189   ///             Most of the time you'll use Color0.
190   /// @param tex  What cubemap will we be rendering to?
191   /// @param face A face identifier.
192   /// @param mipLevel What level of this texture are we rendering to?
193   virtual void attachTexture(RenderSlot slot, GFXCubemap *tex, U32 face, U32 mipLevel=0) = 0;
194
195   /// Resolve the current render target data to the associated textures. This method
196   /// will get called automatically when a rendertarget is changed, before new geometry
197   /// is drawn to a different rendertarget. This method can also be called to 
198   /// gather render target data without switching targets.
199   /// 
200   /// By default, this method will resolve all color targets.
201   virtual void resolve()=0;
202};
203
204typedef StrongRefPtr<GFXTarget> GFXTargetRef;
205typedef StrongRefPtr<GFXWindowTarget> GFXWindowTargetRef;
206typedef StrongRefPtr<GFXTextureTarget> GFXTextureTargetRef;
207
208#endif // _GFXTARGET_H_
209