Math Operators: Using Constant Values in C#

• Pre-requisite: it is assumed that you have read through the prior tutorials, and are familiar with the concepts covered in those tutorials.
• It may be useful to refer to refer to the diagram illustrating the Draw-Update loop (which explains that your initialization code will be called once, and then the XNACS1Lib will repeatedly call your Update method (after which it will Draw the screen) ), in order to have a clear picture of how your game executes.

Goals:

• In this tutorial, we will:
  • Examine how to create named constants, so that the C# source code is more readable
  • Examine how to create named constants, so that it's easier to change just that one named constant, and still have the numerous uses of that constant be updated quickly and easily
  • Examine how to use named constants that have already been created for you, for example, as part of the core C# libraries

1. Obtain the example code

• Here is the zip file to the source files and compiled executable of this example.
• Here is the keyboard mapping for the XBOX 360 controller.  
• Here is the main tutorial page for working with XNACS1Lib, and here is the complete documentation of the library: html-page or compiled html help file .

This program draws two rectangles on the screen, as well as a circle.  The circle is labeled with it's area.

At the bottom of the screen are instructions for playing game.  By using the left thumbstick's vertical axis (the Y axis), you can control both the heights of the rectangles, as well as the radius of the circle.  Pushing the left thumbstick up (or forward) increases the heights & radius, pushing downward decreases them.  You'll notice that pushing the thumbstick doesn't change things very quickly; this is done on purpose. 

Additionally, when player presses the 'Back' button (or the keyboard equivalent), the program will exit.

Let's examine the C# source code that produces the behavior we see on-screen

• Declaring the instance variables and named constants

  We need to declare our instance variables and named constants before we can use them. 

  public class Game1 : XNACS1Base {         // Named Constants     private const float REC_WIDTH = 10.0f; // Width of the Rectangles     private const float RATE_SCALE = 0.05f; // Multiplier for rate     // Normal instance variables:     private XNACS1Rectangle leftRec;     private XNACS1Rectangle rightRec;     private XNACS1Circle Circ;

  • We'll need to keep track of each of the rectangles (and the circle) that we see on-screen, so we declare each of them here.
  • You'll notice something new for this tutorial: we've declared two private const float s, to keep track of various pieces of information.  You've seen private float s declared here as instance variables, but what's new here is the word const .  const is short for const ant, meaning that the thing we're declaring does NOT change. 
    • Because these aren't allowed to change once they've been created, we MUST give them an initial, starting value here.   
  • Why would we want to create an unchanging value?  Here are a couple of reasons:
    1. For things that don't change, we can now replace numbers with a word (i.e., replace numbers with the named constants), which makes the code more readable. 
       For example, in the UpdateWorld method, it will be very clear that we're multiplying the left thumbstick's Y value by a value that's intended to scale the rate at which the rectangles/circles change size, because we'll multiply by RATE_SCALE .
    2. For unchanging numbers that we use multiple places, it will now be easier to change just one thing (the declaration of the named constant), and know that everything using that number will also be updated, too.
       In the InitializeWorld method, it will be very clear that both rectangles have the same width, because we will assign REC_WIDTH to both of the rectangles' Width properties.  If we change the REC_WIDTH declaration to be larger, then both rectangles will automatically become larger, without us having to manually update each rectangle.
    3. In some cases, someone else will define a named constant for us, so that we don't have to.
       In the UpdateWorld method, we will make use of a predefined value for Pi to calculate the area of the circle, which is stored in the Math .PI named constant.
• InitializeWorld():

  protected override void   InitializeWorld() {     World.SetWorldCoordinate( new Vector2(0,0), 100.0f);     leftRec = new XNACS1Rectangle ();     leftRec.LowerLeft = new Vector2 (5.0f, 5.0f);     leftRec.Height = 10.0f;     leftRec.Width = REC_WIDTH;     rightRec = new XNACS1Rectangle ();     rightRec.LowerLeft = new Vector2 (20.0f, 5.0f);     rightRec.Height = 10.0f;     rightRec.Width = REC_WIDTH;     Circ = new XNACS1Circle ();     Circ.Center = new Vector2 (70, 30.0f );     Circ.Radius = 10.0f;     Circ.Label = "Area: " + ( float )( Math .PI * Math .Pow(Circ.Radius, 2)); }

  • The first thing that we do is to create and initialize the two rectangles.  Everything should look familiar except for the lines that look like:
        leftRec.Width = REC_WIDTH;

    and

        rightRec.Width = REC_WIDTH;

    • You'll notice that we're assigning REC_WIDTH to (say) leftRec.Width as if it's a number.  We can do this because we declared REC_WIDTH to be a named constant, and to specifically be a float with the value 10.0f.  Thus, C# knows that when we say leftRec.Width = REC_WIDTH; , we really mean leftRec.Width = 10.0f ; , and so it assigns 10.0f to leftRec.Width.
      • Technically, the const means that when the program is compiled, is replaced with 10.0f, so REC_WIDTH is not an 'unchanging variable' (i.e., something stored in memory, but never changed), but is more the equivalent of a solution-wide copy-and-paste that replaces REC_WIDTH with 10.0f. 
        This is different than the C# readonly modifier, which is a way of making a variable into something that can't be changed, but that still occupies space in memory.  This is explained towards the end of  http://msdn.microsoft.com/en-us/library/acdd6hb7(VS.71).aspx .
    • Because we're assigning REC_WIDTH to the Width properties of both rectangles, both rectangles will have the same width.  If the declaration of REC_WIDTH is changed, then both of these rectangles will automatically have the new width, once the program is re-compiled and re-run.
  • The last chunk of code creates and initializes the circle.  Most of this should be familiar from the Circle tutorial.  The only thing that's new is the line:
        Circ.Label = "Area: " + ( float )( Math .PI * Math .Pow(Circ.Radius, 2));

    Let's examine how this works, in detail:

    1. Circ.Label = "Area: " + (float)(Math.PI * Math.Pow(Circ.Radius, 2));
       There are three  types of operators: the assignment operator, the concatenation operator (+, since it's next to some text), and the multiplication operator.  The assignment operator is executed last, so that all the other operations can be done first, and the result assigned to the circle's label, as we'd expect..  Multiplication goes before concatenation, so it normally would go first.  Also, the expression that involves the multiplication is surrounded by an extra set of parentheses, so the multiplication definitely goes before the assignment operator, or the concatenation (the + sign). 
       But before we can do the multiplication, we need to know the values on the left and right side of the * symbol.
    2. Circ.Label = "Area: " + (float)(Math.PI * Math .Pow(Circ.Radius , 2) );
       The value on the right side, for the expression Math .Pow(Circ.Radius, 2) .  Since Circ.Radius starts out as 10, this will evaluate to 100, stored in memory as a double-precision floating point number. 
       Circ.Label = "Area: " + (float)(Math.PI * 100.0 );
       • Note that the standard way to write (in C#) a double-precision number is to specify a number with digits after the decimal point, but without a trailing F .  So 100.0 is a double-precision number, while 100.0f (or 100.0F) is a single-precision floating-point number.
    3. Circ.Label = "Area: " + (float)( Math .PI * 100.0 );
       The value on the left is the pre-defined, named constant Math .PI .  It's a double -precision number, with the value 3.14159265358979.
       Circ.Label = "Area: " + (float)( 3.14159265358979 * 100.0);
    4. Circ.Label = "Area: " + (float) ( 3.14159265358979 * 100.0 ) ;

       Next up, we do the multiplication.  While we're at it, we'll remove the parentheses that surround the multiplication, since we won't need them after this step, giving us:

       Circ.Label = "Area: " + (float) 314.159265358979 ;

    5. Circ.Label = "Area: " + ( float ) 314.159265358979;
       Before we can do the concatenation, we need to first convert the number to a float.  While we could technically get away without doing this, it's good practice to do so, since so much of XNA (and the XNACS1Lib) use single-precision float s, rather than double-precision numbers.  It will also reduce the number of digits in the number, making it easier to read:
       Circ.Label = "Area: " + 314.1593 ;
    6. Circ.Label = "Area: " + 314.1593 ;
       Looking at the + symbol, we realize that this is actually concatenation (joining two blocks of text together), and not addition, since the left side of the + is already text.  Therefore, we first need to convert the number on the right side to be text, which C# will do for us:
       Circ.Label = "Area: " + "314.1593" ;
       Now we can do the concatenation, and create a single, joined string to use as the label:

       Circ.Label = "Area: 314.1593" ;

    7. Lastly, the string is assigned to the circle's label.

  UpdateWorld():

  protected override void UpdateWorld() {     if (GamePad.ButtonBackClicked())         this .Exit();     float leftThumbY = GamePad.ThumbSticks.Left.Y * RATE_SCALE;     // Update the rectangles     leftRec.Height = leftRec.Height + leftThumbY;     rightRec.Height = rightRec.Height + leftThumbY;     // Update the circle     Circ.Radius = Circ.Radius + leftThumbY;     Circ.Label = "Area: " + ( float )( Math .PI * Math .Pow(Circ.Radius, 2));     EchoToBottomStatus( "LeftThumb-Y: adjust height of rectangles, and radius of circle" ); }

  • As per normal, our game will check if the user presses the 'Back' button.  If we're going to exit, there's no sense in doing any work prior to exiting, so we check if we need to exit as the first two lines in the method
  • Let's start by creating a local variable that will hold a copy of the value of the left thumbstick's vertical axis.
        float leftThumbY = GamePad.ThumbSticks.Left.Y * RATE_SCALE;

    You'll notice that there's an extra term, * RATE_SCALE , tacked onto the end.  What this will do is multiply the value of the left thumbstick's vertical axis by the value of the named constant.  So if you pushed the thumbstick all the way up, giving GamePad.ThumbSticks.Left.Y the value of 1, then GamePad.ThumbSticks.Left.Y * RATE_SCALE would have the value of 1 * 0.05f , or 0.05f.

    • Thus, the point of doing this multiplication is to change the raw value coming off the thumbstick.  In this case, we're scaling the input down, so that numbers from the thumbstick are made smaller.  This is why the size of the circle and rectangles change more slowly than you've previously seen.  If we wanted them to change extra-fast, we could change the declaration of RATE_SCALE so that it's larger than one, and scale the thumbstick values up, instead.
  • Everything else in the method should be familiar from previous tutorials, or from the calculation of the area, above.
  • In order to try and be helpful, we also echo a brief message to the bottom status bar, telling the user how to play the game.

          EchoToBottomStatus( "LeftThumb-Y: adjust height of rectangles, and radius of circle" );

FURTHER EXERCISES::  

1. Start from a blank starter project (1000.201, if you need it), and re-do the code from memory as much as possible.  On your first try, do what you can, and keep the above code open so that when you get stuck, you can quickly look up what you forgot (and that after you finish a line, so that you can compare your line to the 'correct' line).  On the next try, do the same thing, but try to use the finished code less.  Repeat this until you can type everything, without refering the tutorial's code.
   • Repeat this exercise daily for several days, so that you really get the hang of this.  As you go on, periodically review this by re-doing this exercise.
2. Named Constants: Easy, Consistent Update
   Using the same project that the above tutorial makes use of, try changing the declaration of  REC_WIDTH so that it's value is 2.0f.  Notice that all the rectangles on the screen change automatically (the next time you compile and run the program).  Try changing it to 40.0f, and notice what changes. 
   • For this example, there's only two rectangles to update, so it's not a huge deal to update them by hand.  But think about scenarios like creating an 8x8  checkerboard pattern on the screen - what if you wanted to change the height & width of all 64 rectangles?  How much easier would it be to define REC_WIDTH and REC_HEIGHT once, and use those declarations for all 64 rectangles?
3. Named Constants: Readable Code
   Using the same project that the above tutorial makes use of change the value of RATE_SCALE, and try rerunning the program.  Note that not only do you get a quick, easy, and consistent update, but it's very clear exactly what you're multiplying the left thumbstick by.  You're multiplying the left thumbstick by a value intended to scale the rate at which the rectangle (and circle) change.
4. Named Constants: Finding and replacing numbers with named constants

   Start this exercise using Exercise_ 2 's starter project , which is a nearly identical copy of the project that was used in the above tutorial.
   Examine the code used in InitializeWorld.  Notice that the height of all the rectangles is 10.0f.  Notice also that this height changes as soon as the user pushes the thumbstick.  For this exercise, in the InitializeWorld method, replace the rectangle's initial heights of 10.0f with a new, named constant called something like REC_STARTING_HEIGHT.

   • Keep the name in ALL CAPS.  This is not only a very common convention in most/all languages, but it's consistent with the named constants that the program already has.
   • You'll need to declare the named constant in a fashion similar to the other, named constants
5. Named Constants: Finding and replacing numbers with named constants appropriately

   Continue working from the same project that you used in the prior exercise.  Notice that in the InitializeWorld method, the starting heights of both rectangles is 10.0f, as defined by the named constant REC_STARTING_HEIGHT.  Notice that the starting radius for the circle is also 10.0f.

   For this exercise, in a comment immediately above the line that assigns a starting value to the circle's radius, answer the following question:
   Should you replace the circle's starting radius with the named constant REC_STARTING_HEIGHT (since the starting radius is also 10.0f)?  What would the advantages of this be, and what would the disadvantages be?

6. Named Constants: Finding and replacing numbers with named constants appropriately

   Continue working from the same project that you used in the prior exercise. 
   Go through the code, and see if there are other numbers that you can replace with named constants.  For each number, put in a quick (1-2 sentence) comment explaining why (or why not) you think that a named constant is a good thing to use.

	This work is supported in part by a grant from Microsoft Research under the Computer Gaming Curriculum in Computer Science RFP, Award Number 15871 and 16531.
2/8/2010