Simple Function Call

Need (library reference):

• Working with Texture files

• Make sure that we cover nested/chained fnx calls: f( 1, 2, g(3) ), etc

References:

• Pre-requisite: it is assumed that you have read through the prior tutorials, and are familiar with the concepts covered in those tutorials.

Goals:

• In this tutorial, we will:
  • Examine a simple variation on programs you've already seen, in which the player controls a soccer ball using the right thumbstick
  • Examine how to define a basic function, and to call that function from within the UpdateWorld function

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.

When the game starts, you'll see a screen that looks similar to this:

As you can see, there is a single soccer ball on the screen.  Using the right thumbstick, you can move the soccer ball around (if you want, you can even move it off the screen).  The program prints out a simple, purely textual message at the top of the screen, and it prints the current location of the soccer ball at the bottom of the screen.

The game will exit if you press the 'Back' button, as is true for all the tutorials so far.  Because this is a standard feature of our programs, it will not be mentioned in future tutorials.

2. Examining The Program:

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

• Declaring the instance variables

  We need to declare (to define, really) our instance variables before we can use them. 

  public class Game1 : XNACS1Base {      private XNACS1Circle aBall; // a soccer ball     // Constants for circle/ball definition     private const float BALL_INIT_X = 50.0f;     private const float BALL_INIT_Y = 35.0f;     private const float BALL_INIT_RADIUS = 3.0f;

  • As we can see from the picture above, this program features a soccer ball that the player can move around the screen.  At this point, we have two options for drawing things onscreen: use a circle, or use a rectangle.  Clearly, a circle is a better approximation for a soccer ball than a rectangle is, so we'll use the circle, like so:
    private XNACS1Circle aBall; // a soccer ball
    • The basic strategy that we'll use it is to represent the ball using an XNACS1Circle object, and then just paste the picture of the soccer ball over that object.  We'll setup the picture below, in the initialization step
  • We also define several named constants, so that we have the the option of changing these numbers in just one place, and having those numbers automatically get updated throughout the program.  Specifically, we want to define the starting location of the ball.  We do that by defining the X value, and Y value, of the coordinates where the ball will be placed:
        private const float BALL_INIT_X = 50.0f;

        private const float BALL_INIT_Y = 35.0f;

  • We also want to define the radius of the soccer ball here, as well:
        private const float BALL_INIT_RADIUS = 3.0f;
• InitializeWorld():

  protected override void InitializeWorld() {     World.SetWorldCoordinate(new Vector2(0,0), 100.0f);     // initialize the soccer ball     aBall = new XNACS1Circle();     aBall.Center = new Vector2(BALL_INIT_X, BALL_INIT_Y);     aBall.Radius = BALL_INIT_RADIUS;     aBall.Texture = "SoccerBall"; }

  • We create a new XNACS1Circle object, and assign that object to the aBall instance variable, as we've frequently done in the past:
        aBall = new XNACS1Circle();
  • Next, we assign a Vector2 to the ball's Center property, in order to set the initial location of the ball. 
    aBall.Center = new Vector2(BALL_INIT_X, BALL_INIT_Y);
    • You'll notice that we're using (BALL_INIT_X, BALL_INIT_Y), instead of typing in numeric values.  Since BALL_INIT_X was declared to have the value 50.0f, and since BALL_INIT_Y was declared to have the value 35.0f, this line is the same as typing:
      aBall.Center = new Vector2(50.0f, 35.0f);
  • Similarly, we assign a radius to the circle:
    aBall.Radius = BALL_INIT_RADIUS;
    • Again, this has the same effect as if we'd typed:
      aBall.Radius = 3.0f;
  • This is also located in 4000.010
    What may be new is the fourth statement, aBall.Texture = "SoccerBall";.  A Texture is (essentially) another word for an image, and "SoccerBall" is the name of an image that has been added to the project's Content/Resource/Textures folder (notice that this is the file's name, but without the file extension).  Once you've added the texture file to the project, you can put an image onto the screen by assigning the name of the texture to the object's .Texture property, like we do here.
    • If you need to add an image to your game, you can do so by opening up the Solution Explorer (normally it's on the right side of Visual Studio's screen - click on View→Solution Explorer if you don't see it), then right-clicking on the Content/Resources/Textures folder, and selecting Add→Existing Item from the context menu.  Since the starter project that you're given already has this image added to it, you do not need to do that for this tutorial (but it's always good to know how!).
      
    • XNA doesn�t support all types of images. The following types are supported: .bmp, .dds, .dib, .hdr, .jpg, .pfm, .png, .ppm, and .tga. (From http://msdn2.microsoft.com/en-us/library/bb447762.aspx - look for "Texture - XNA Framework")
• UpdateWorld():
  

  protected override void UpdateWorld() {     if (GamePad.ButtonBackClicked())         this.Exit();     // Change Ball position with Right Thumb Stick     aBall.CenterX += GamePad.ThumbSticks.Right.X;     aBall.CenterY += GamePad.ThumbSticks.Right.Y;     // here is the function that prints!     PrintMessageToTopStatus();     EchoToBottomStatus("Soccer Ball position: " + aBall.Center); }

  • 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.  In future tutorials, this code won't be mentioned again, unless it's customized for a particular program.
  • The first two, new lines of code should look somewhat familiar, but not identical, to what you've seen previously.  They serve to move the soccer ball, based on input from the player.
        aBall.CenterX += GamePad.ThumbSticks.Right.X;

        aBall.CenterY += GamePad.ThumbSticks.Right.Y;

    • What's going on here is this: it's very, very common to type things like:
      a = a + 1; or score = score + 10;
      So common, in fact, that there is a shorthand operator for it:   +=
      a += 1;; is exactly equivalent to typing a = a + 1;
      score += 10; is exactly equivalent to typing score = score + 10;
    • The a line like
          aBall.CenterX += GamePad.ThumbSticks.Right.X;

      is really the same thing as
          aBall.CenterX = aBall.CenterX + GamePad.ThumbSticks.Right.X;

      In other words, take the current X value off the right thumbstick, add that to the current value of the soccer ball's CenterX property, and then assign that sum back to the soccer ball's CenterX property.  The next line does the same thing, but for the ball's CenterY property

  • Skipping a couple of lines, we see the familiar code to print the coordinates of the soccer ball's center point to the bottom of the status bar:
        EchoToBottomStatus("Soccer Ball position: " + aBall.Center);
  • Next, we see a line of code that looks very similar to the EchoToBottomStatus bar:
        // here is the function that prints!

        PrintMessageToTopStatus();

    
    

    This line of code represents a call to a function (just like EchoToBottomStatus), except that this is not a built in function.  Instead, this is a function that we have defined, ourselves. 

  • Before we do a detailed description of this, let's see the other 'half' of this function: the definition of the PrintMessageToStatus() function.
• PrintMessageToTopStatus():
  

  #region utility functions     /// <summary>     /// This is the "comment area" for the function. You should     /// use this area to explain the details of what your function does.     /// In this case:     ///     /// This function prints a simple message to the     /// TopStatus area in the application window.     /// </summary>     private void PrintMessageToTopStatus()     {         EchoToTopStatus("A Ball and function call. This is pretty cool eh?!");     } #endregion

  • First, you'll notice that we've enclosed this area of the code in a #region, so that we can 'fold up' all the functions that we'll be putting into here.  Right now we've only got a single function's definition, but eventually, we'll have many functions here, so it may be useful to fold the functions away if we're trying to focus on other aspects of the program.  You can fold up the region by clicking on the small box with the - sign in it, that's in the left margin of the text editor.
  • Let's start by looking at the syntax for the function definition. You'll notice that our function definition starts off with a comment area, which attempts to explain what the function does.  Technically, this area is optional, but it's a good idea to put it in when creating your own functions.

        /// <summary>

        /// This is the "comment area" for the function. You should

        /// use this area to explain the details of what your function does.

        /// In this case:

        ///

        /// This function prints a simple message to the

        /// TopStatus area in the applicaiton window.

        /// </summary>

    •  The goal of the comment is to provide a quick, accurate summary of what the function does. There are many possible purposes for this comment, including
      1. Other people may (hopefully) use the summary as an overview, before they read through the function the first time, in order to figure out what the function does.
      2. We can use the summary to remind for ourselves, so that later on, when we need to remember what the function does, we can re-read the summary, and perhaps avoid having to reread all the details of the function itself.
      3. Lastly, C# has tools to quickly generate documentation for our functions, classes, etc, when we format the comment area in a particular fashion.
    • You'll notice that these comments start with THREE slashes, rather than just the normal TWO:
      /// Function comment - three slashes
      vs.
      // Normal comment - two slashes

      The THREE slashes is a hint to C#, to tell C# that we've formatted the comment in such a way that we can use various C# tools to quickly produce documentation, automatically, from these comments.  For our purposes, the two different styles will do the same thing, so we won't spend any more time on them here.

  • Next, we have the actual function definition itself.  The first line looks like:
        private void PrintMessageToTopStatus()
    • For right now, we can ignore the private keyword.  As a general rule of thumb, you should make all of your functions private, unless you have a specific reason not to.
    • Next, the keyword tells C# that this function will do some work, but will not return a value to the rest of the program.
    • We decided to name this function PrintMessageToTopStatus; we tell C# that this will be the function's name by typing it out, here.
      • Function names must start with a letter (upper or lowercase), or the underscore character).  Function names can only contain letters (upper or lowercase), underscore characters, or numbers (0 through 9). 
      • Specifically, you are NOT allowed to put spaces into your functions' names!!
    •  Finally, the () at the end are required.  Even though we're not doing anything with them quite yet, they're still required.
  • The body of the function starts with the opening curly brace - { -, and ends with the matching, closing curly brace - }.  All the statements between the opening and closing curly braces are called the body of the function
  • For this tutorial, the body consists of a single line of code:
        EchoToTopStatus("A Ball and function call. This is pretty cool eh?!");
  • This statement should be familiar to you, from prior tutorials.
• Before we look at the semantics of defining a calling a function, let's backtrack and look at the syntax of the function call, in UpdateWorld:
      // here is the function that prints!

      PrintMessageToTopStatus();

  • You'll notice that when we want to call the function, we simply write out the name of the function, followed by open and close parentheses, followed by the ending semi-colon.
    • The spelling and capitalization has to match the function definition exactly, just like when we call the EchoToBottomStatus function.
• We'll examine the semantics of function definition, and function calling, with the aid of the following picture:
  
  • When the UpdateWorld method is called, it will do the following things, in the following order (as illustrated above)
    1. Check if the player has pushed the Back button, and if so, exit the game
    2. Update the X value of the current location of the soccer ball, based on user input from the right thumbstick
    3. Update the Y value of the current location of the soccer ball, based on user input from the right thumbstick
    4. On the line that reads "PrintMessageToTopStatus();", the program will temporarily pause the UpdateWorld function, and jump down to the PrintMessageToTopStatus  function.
    5. Technically, the program needs to do some bookkeeping, etc, before it can begin executing this step.  Although there isn't a whole lot going on in this program, more will happen at this step when we see function parameters, so we will include this step here even though it doesn't do much (that we can see).
    6. Once we've jumped to PrintMessageToTopStatus, we execute all the statements in the body of the function, from top to bottom, just like normal.  For this function, the only statement is to echo a message to the top of the screen.
    7. After we've finished executing all the statements in the function's body, we jump back up to UpdateWorld, and resume executing UpdateWorld.
       • Technically, we jump back to the spot where we left from, so that if there was any more work to do on that line, we'd do it.  There's isn't any more work on that line, in this program, so we go on to the next step.
    8. Finally, we finish executing the statements in UpdateWorld. For this program, the only remaining statement is the call to EchoToBottomStatus.

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. For this exercise, you should use the same project that was explained in the above tutorial.
   Create a new function, named EchoMessageToBottomStatus.  It should print out the words "Hello, Everyone!" to the bottom of the screen.  Make sure that you call this function from the UpdateWorld method.
3. For this exercise, you should use the same project that was explained in the above tutorial.
   Create a new function, named EchoMessageToBottomStatus2.  It should print out the words "Soccer Ball Position: ", followed by the current center of the soccer ball, to the bottom of the screen (just like you see in the provided starter project).  Make sure that you call this function from the UpdateWorld method.

	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