Fade to Black - Featured in Warzone demo and April Dev Newsletter

Generally speaking, a fair majority of the features you implement in a project using Torque is going to be extending some existing functionality within the engine. In fact, all of Torque's GUI controls inherit from a single GUI control at some point in their class hierarchies. This one control called the GuiControl, is the most basic of all of the GUI controls, and it is this control we will extend to create our special fade-out control.

The approach I take when creating a new class is to identify two things. First, what task are we trying to accomplish. And second, what things are needed to accomplish that task. For the fade-out control the purpose is to fade a particular scene to black. To accomplish this task we need to be able to keep track of time, specifically three things: How long it takes the control to fade completely to black. How long to wait before starting the fade. And what time do we use as a reference. With these things in mind let's start fleshing out our control.

Note: For the sake of simplicity I am implementing the class entirely inline inside the class structure.


The first thing we need to do is include some headers:

#include "dgl/dgl.h" 		    // some utility drawing routines
#include "console/console.h"      // hooks into scripting
#include "console/consoleTypes.h" // ...
#include "gui/guiControl.h"       // the basic GUI control we derive from

What I'll do now is write out the entire class and fill in the important sections later:

class GuiFadeoutCtrl : public GuiControl
{
   typedef GuiControl Parent;

private:
   U32 referenceTime; // time we use in reference to the other times
   U32 fadeoutTime;   // how long it takes to fade to black
   U32 waitTime;      // how long to wait before starting the fade

public:
   GuiFadeoutCtrl()
   {
	// setup default values
      referenceTime = 0;
      fadeoutTime   = 1000;
      waitTime      = 2000;
   }

   void onPreRender()
   {
      Parent::onPreRender();
      setUpdate(); // when we render, update the entire control
   }

   // tell the engine we want this class to be exposed to scripting
   DECLARE_CONOBJECT(GuiFadeoutCtrl);
   
   bool onWake()
   {
      if(!Parent::onWake())
         return false;
      return true;
   }

   void resetFade()
   {
	// set our reference time to 'now' effectively resetting
	// the fade-out
      referenceTime = Platform::getRealMilliseconds();
   }

   void onRender(Point2I offset, const RectI &updateRect)
   {
      Parent::onRender(offset, updateRect);
	// ...
   }

   static void initPersistFields()
   {
      Parent::initPersistFields();
      addField("fadeoutTime", TypeS32, Offset(fadeoutTime, GuiFadeoutCtrl));
      addField("waitTime",    TypeS32, Offset(waitTime,    GuiFadeoutCtrl));
   }
};

// tell the engine we want this class to be exposed to scripting
IMPLEMENT_CONOBJECT(GuiFadeoutCtrl);

// expose resetFade to the scripting system
ConsoleMethod(GuiFadeoutCtrl, resetFade, void, 2, 2, "")
{
   object->resetFade();
}

Since this is a basic control there is only one function I haven't filled out in the above class, so I'll briefly explain what is going on above and then move onto the onRender function. In the constructor we fill out some default values. These are only ever used if for some reason the script setup for this control does not set them. Two of the three values listed here are exposed to script within the initPersistFields function. The other function worth mentioning is resetFade. This function will set the referenceTime to the current machine's time. Since the fadeoutTime and waitTime are in reference to the referenceTime this will effectively reset the fade control. You'll also notice that this function is exposed to script via a ConsoleMethod which takes the name of the class, the name of a function and binding them to the real function.

Finally the last part of the control to discuss is the onRender function:

void onRender(Point2I offset, const RectI &updateRect)
{
   Parent::onRender(offset, updateRect);

   // subtract current time with reference time to get the time elapsed
   U32 elapsed = Platform::getRealMilliseconds() - referenceTime;
   
   U32 alpha;
   if(elapsed < waitTime)
   {
	// we havn't started fading at all yet
      alpha = 0;
   }
   else if(elapsed < fadeoutTime+waitTime)
   {
	// we've started fading, but we aren't completely faded to black yet
      elapsed -= waitTime;
      alpha = 255 * F32(elapsed) / F32(fadeoutTime);
   }
   else
   {
      // we are completley faded
      alpha = 255;
   }

   // the color black
   ColorI color(0,0,0,alpha);

   // draw a rectangle the size of the entire control
   dglDrawRectFill(offset, mBounds.extent + offset, color);
}

Essentially what is going on is we are figuring out how much time has elapsed since the last time this control was rendered and the referenceTime. We then compare the elapsed time with the waitTime and fadeoutTime's we set in script and set an appropriate alpha value for the color of the rectangle we draw to the screen. This rectangle fills the space of the entire control, in the case of the GDC Demo, a full screen effect.

Finally what a script might look like which utilizes this new control:

new GuiFadeoutCtrl(DemoEndFadeOut) {
   profile = "GuiDefaultProfile";
   horizSizing = "width";
   vertSizing = "height";
   position = "0 0";
   extent = "640 480";
   minExtent = "8 8";
   visible = "0";

   fadeoutTime = "1500";
   waitTime = "2500";
};