gfxTransformSaver.h

Classes:

class
Helper class to store viewport and matrix stack state, and restore it later.
Detailed Description

  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 _GFX_GFXTRANSFORMSAVER_H_
 25#define _GFX_GFXTRANSFORMSAVER_H_
 26
 27#ifndef _GFXDEVICE_H_
 28#include "gfx/gfxDevice.h"
 29#endif
 30
 31
 32/// Helper class to store viewport and matrix stack state, and restore it
 33/// later.
 34///
 35/// When doing complex out-of-scene rendering, for instance, doing a 
 36/// render to texture operation that needs its own transform state, it
 37/// is very easy to nuke important rendering state, like the viewport
 38/// or the projection matrix stored in vertex shader constant zero.
 39///
 40/// This class simplifies save and cleanup of those properties. You can
 41/// either treat it as a stack helper, e.g.
 42///
 43/// @code
 44/// void myFunc()
 45/// {
 46///    GFXTransformSaver saver;
 47///
 48///    // Lots of nasty render state changes...
 49///
 50///    // Everything is magically cleaned up when saver is destructed!
 51/// }
 52/// @endcode
 53///
 54/// Or you can manually control when you do saves or restores:
 55///
 56/// @code
 57/// void myFunc()
 58/// {
 59///    GFXTransformSaver saver(false, false);
 60///
 61///    if(!somePrecondition)
 62///       return false;     // Note early out.
 63///
 64///    saver.save();
 65///
 66///    // Lots of nasty render state changes...
 67///
 68///    // If we had passed (false, true) to the constructor then it would
 69///    // clean up automagically for us; but we want to do it manually.
 70///    saver.restore();
 71/// }
 72/// @endcode
 73/// 
 74class GFXTransformSaver
 75{
 76protected:
 77
 78   RectI   mSavedViewport;
 79   MatrixF mSavedProjectionMatrix, mSavedViewMatrix;
 80   bool    mHaveSavedData, mRestoreSavedDataOnDestruct;
 81
 82public:
 83
 84   /// Constructor - controls how data is saved.
 85   ///
 86   /// @param saveDataNow If true, indicates that saveData() should be called
 87   ///                    immediately. Otherwise, you can do it manually.
 88   ///
 89   /// @param restoreDataOnDestruct If true, indicates that restoreData() should
 90   ///                              be called on destruct. Otherwise, you'll
 91   ///                              have to do it manually.
 92   GFXTransformSaver(bool saveDataNow = true, bool restoreDataOnDestruct = true)
 93   {
 94      mHaveSavedData = false;
 95
 96      if(saveDataNow)
 97         save();
 98 
 99      mRestoreSavedDataOnDestruct = restoreDataOnDestruct;
100   }
101
102   ~GFXTransformSaver()
103   {
104      if(mRestoreSavedDataOnDestruct)
105         restore();
106   }
107
108   void save()
109   {
110      AssertFatal(mHaveSavedData==false, "GFXTransformSaver::saveData - can't save twice!");
111      mSavedViewport         = GFX->getViewport();
112      mSavedProjectionMatrix = GFX->getProjectionMatrix();
113      mSavedViewMatrix       = GFX->getViewMatrix();
114      GFX->pushWorldMatrix();
115
116      // Note we have saved data!
117      mHaveSavedData = true;
118   }
119
120   void restore()
121   {
122      AssertFatal(mHaveSavedData==true, "GFXTransformSaver::restoreData - no saved data to restore!");
123
124      GFX->popWorldMatrix();
125      GFX->setViewMatrix(mSavedViewMatrix);
126      GFX->setProjectionMatrix(mSavedProjectionMatrix);
127      GFX->setViewport(mSavedViewport);
128
129      // Once we've restored we do not want to be able to restore again...
130      mHaveSavedData = false;
131
132      // And we don't want to restore on destruct!
133      mRestoreSavedDataOnDestruct = false;
134   }
135
136   /// Returns the saved viewport.
137   const RectI& getViewport() const { return mSavedViewport; }
138
139   /// Returns the saved projection matrix.
140   const MatrixF& getProjectionMatrix() const { return mSavedProjectionMatrix; }
141
142   /// Returns the saved projection matrix.
143   const MatrixF& getViewMatrix() const { return mSavedViewMatrix; }
144};
145
146#endif // _GFX_GFXTRANSFORMSAVER_H_
147