Fading (and Beyond)

#1 The code can also be generalized. I took five minutes to build a GrowOrShrink function to grow or shrink the size of an object on screen:

[b]// Resizes an object linearly to a specified size over the specified amount of time.
// Note that this function also uses the $FadeGranularity global variable.[/b]
function t2dSceneObject::GrowOrShrink(%this, %toWidth, %toHeight, %time, %command)
{	
     if(%time > $FadeGranularity)
     {
          %width = %this.getWidth();
          %height = %this.getHeight();
          %updatesRemaining = %time / $FadeGranularity;
	
          [b]// Essentially we will calculate a Delta value for the alpha using the number of calls left.
          //	 The expected change in value is human readable as:
          //		"value-Distance left to travel divided by the number of increments."[/b]

          %width += (%toWidth - %width) / %updatesRemaining;		
          %height += (%toHeight - %height) / %updatesRemaining;

          [b]// Set the values and schedule the next call.[/b]
          %this.setWidth(%width);
          %this.setHeight(%height);
          %this.schedule($FadeGranularity, GrowOrShrink, %toWidth, %toHeight, %time - $FadeGranularity, %command);
     }
     else
     {
          [b]// Time's up.  Finish.[/b]
          %this.setWidth(%toHeight);
          %this.setHeight(%toHeight);
          if(%command !$= "")
          {
               [b]// Target reached.  Issue "Callback".[/b]
               eval(%command);
          }
     }
}

Further, it wouldn't take much to make a completely generalized version of the function (you could call it something like a LimitBasedIncrementor(...)).

And it gets better, for those of you who are afraid of repeated divisions, an enhanced version:

[b]// Fades an object to a specified opacity over the specified amount of time.
//  Fails to adapt to sudden changes in opacity.[/b]
function t2dSceneObject::fadeFast(%this, %toAlpha, %time, %command)
{
     [b]//-------------------- ERROR CHECKING --------------------//[/b]
     if($FadeGranularity < 1)
     {
          echo("\c2FADE: Invalid $FadeGranularity value of \c1" @ $FadeGranularity @ "\c2.");
          return;
     }
     if((%toAlpha < 0) || (%toAlpha > 1))
     {
          echo("\c2FADE: Invalid Target Alpha value.  Received \c1" @ %toAlpha @ "\c2.");
          return;
     }

     [b]//------------------------ FADING ------------------------//[/b]
     %alpha = %this.getBlendAlpha();
     %updatesRemaining = %time / $FadeGranularity;
     %delta = (%toAlpha - %alpha) / %updatesRemaining;
     %this.fadeFastHelp(%toAlpha, %delta, %time, %command);
}

[b]// Blindly fades based on a preset increment to a specified opacity [in percentage] over the specified amount of time..
//  Does not adapt to sudden changes in opacity.
//  Does not adapt to sudden changes in $FadeGranularity.[/b]
function t2dSceneObject::fadeFastHelp(%this, %toAlpha, %delta, %time, %command)
{
     if(%time > $FadeGranularity)
     {
          %this.setBlendAlpha(%this.getBlendAlpha()+%delta);
          %this.schedule($FadeGranularity, fadeFastHelp, %toAlpha, %delta, %time - $FadeGranularity, %command);
     }
     else
     {
          [b]// Time's up.  Finish.[/b]
          %this.setBlendAlpha(%toAlpha);
          if(%command !$= "")
          {
               [b]// Target reached.  Issue "Callback".[/b]
               eval(%command);
          }
     }
}

There's a trade-off here. The code is reduced to exactly two divisions [which occur during the setup]. The drawback is that the fading doesn't take into consideration any external modifications to the opacity after the initial call to fadeFast().

Note that all three of the above functions use the same $FadingGranularity variable. This value specifies the update interval in milliseconds: a larger value might appear choppy whereas a smaller value will appear generally smoother. The code could easily be modifiable to depend on a per-object basis.

Overall, I believe that the code simplicity, functionality, expandability, and speed make this an overall much nicer implementation of fading than the one presented in the rather dated tutorial. As such, I am considering editing the old tutorial or writing a brand new one. Before I go ahead and do that, though, I'd be interested in hearing the community's thoughts. So, err... thoughts?

#2 Very nice, do you have plans to place this stuff on TDN as tutorials or 'code snippets' ... ?

Useful code snippets are always nice ...

#3 Nice. I too have been playing around with fading. I based mine off the fade routines that used in the Tankbusters demo.

Another feature that I wanted was the ability to fade all objects in a scene.

Let me see if I can find . . .
Ah here we go.

//Fade all objects in a scene
function t2dSceneGraph::fadeAlpha(%sceneGraph, %time, %alpha, %inc, %objcallback, %sceneCallback)
{
      //Get all the Scene Objects
      %sceneObjectList = %sceneGraph.getSceneObjectList();

      //Set a fade schedule for each object in the scene
      for (%i = 0; %i < getWordCount(%sceneObjectList); %i++)
      {
              %sceneObject = getWord(%sceneObjectList, %i);   //Get each scene object
              %sceneObject.fadeToAlpha(%time, %alpha, %inc, %objcallback); //Set a fade for each object
      }

      //Take our last %sceneObject and if we have a scene callback wait for it to finish fading.
      if( !(%sceneCallBack $= ""))
	      %sceneGraph.waitForFade( %sceneObject, %sceneCallBack);

}

function t2dSceneGraph::waitForFade( %sceneGraph, %obj, %sceneCallBack)
{
//Wait for the specified object ot finish fading checking every 10 ms
     if(isEventPending(%obj.alphaFadeSchedule))  //alphaFadeSchedule is set in the object fade function
	     %sceneGraph.schedule(10, "waitForFade", %obj, %sceneCallBack ); 
     else
	     schedule(0, 0, %sceneCallBack);
}

Obiously it would be easy to weak for what ever fade mechanism you choose.
I found it handy to have a callback for each object fade and also one for when the scene finished fading.
It could use some additional refinements, it currently attempts to fade every object in the scene. You could use some sort of object identification to only fade objects that are actually rendered to the display.

You should have a look at how they did it in tankbusters. If you own the pro version of TGB they also use fade routines in the level builder.

Maybe you will find it useful.

#4 Good stuff Eric, I could put this to immediate use.

#5 @David: That's kind of the idea. Would that be helpful to you?

@Guy: I seem to have re-implemented what GG did with their FadeToAlpha function in the TGB code (incidentally, I have a version of the function called "FadeToAlpha", too, that simply calls my general function with a preset time). I did not implement an event management system, which they did, but could easily include that as a portion of the tentative Fade Tutorial (it's a whole two or so lines of code). As for the overall code itself, I believe mine to be cleaner. Certain calls occur extraneously under certain circumstances, making the code a bit tougher to read interpret.

@Todd: Do you think it would be useful to put this up as a Tutorial? Or should I just leave it here in the forums?

#6 @Eric, I believe it would be very helpful for others -- as a TDN Article of some fashion or another

#7 I have started a tutorial on TDN. I was considering putting it up as a script resource but feel that it's more valuable as a learning device as lots of interesting concepts are used in it. That and the old tutorial is getting really dated.

I'll be working on it more tonight/tomorrow.

#8 Looking good!


Now if someone would just do the needed work to let us fade GUIs too.... =)

#9 Great job throwing this up on TDN... btw feel free to re-link the old one to your new one. I originally did that tutorial well over a year ago and long before TGB (called T2D then) had even a Level Builder. It's always awesome seeing great community members step up and contribute good materials to help others out.

#10 Great Job Eric! Thanks for the contribution to the community.

#11 Nice work Eric!

#12 I have finished the tutorial. Take a look at the (essentially) final version here.

Comments and suggestions are definitely welcome!

#13 Eric,
that is such a great tutorial! so helpful.
and those functions are awesome. now i have to go through my game and rewrite a ton of stuff!

thank you.

#14 Looks great -- love the layout

#15 Thank you , this has been huge help.

#16 Haha, no problem! I'm glad to hear the tutorial and/or this post are still useful!

#17 A flash from the past.

#18 Sorry for the "new kid on the block" question, but what does the [b] mean?

I'm trying to schedule a fade out on text object levelText.

function bgClass::onLevelLoaded(%this, %scenegraph)
{
$circlesLeft =0;
levelText.text = "Level" SPC player.world SPC "-" SPC player.level;

levelText.schedule(3000, );

}

thanks.

#19 it's BBCode, probably from the old layout ... anything in [] should be ignored, or treated like HTML. [b] was for bold.