(Re)learning how to use color blending

When putting together the FadeInOutToy, I had to spend a not so insignificant amount of time figuring out why a behavior from TGB wasn't porting over to T2D so easily. I'd like to summarize what I learned to hopefully help others avoid troubles with the blending methods.

There are several examples in the included Sandbox toys where we can now use human readable names for stock colors.

%object.BlendColor = SlateGray;

or

%object.setBlendColor("SlateGray");

This works fine and the full list of stock colors you can find in the color.cc source file.

What happens when you use SceneObject::getBlendColor()?

%color = %object.getBlendColor();
echo(%color);

In the case of a stock color, you will see the name of that color in the console. For non stock colors, you would get a 4 value float string (red/green/blue/alpha). This dual functionality is not really an issue with setBlendColor, but you have to be careful with getBlendColor.

For the longest time I could not figure out what I was doing wrong here:

%color = %object.getBlendColor();
%red = %color.r;
%green = %color.g;
%blue = %color.b;
%alpha = %color.a;

In the case where you get a stock color name back, it is just that, a string with a name and no color information behind it. To correctly handle cases where you want to manipulate stock colors or even non stock colors, you have to write your script to handle both cases:

%color = %object.getBlendColor();
      
      // Check if this is a stock color or not. If stock, we need to convert the name to RGBA values.
      if(%color.count == 1)
      {
         %colorF = getStockColorF(%color);
         %red = %colorF.r;
         %green = %colorF.g;
         %blue = %colorF.b;
         %alpha = %colorF.a;
      }else
      {
         %red = %color.r;
         %green = %color.g;
         %blue = %color.b;
         %alpha = %color.a;
      }

The additonal step from stock name to RGBA values can be done with the global function getStockColorF. There is also getStockColorI available, but setBlendColor only uses either a name or float values.

This was extremely confusing for me at first. As a suggestion, it would perhaps be better if getBlendColor returns a 5 value string every time (float red/float green/float blue/float alpha/name), where the last value is either a stock color name or left blank if there is no stock color assigned to those float values. This would make handling colors in TorqueScript a bit easier as well.