Calling A Function That Produces A Return Value

Need (library reference):

• Random function - this will be covered later in this module.

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 how to use a pre-existing function that returns a value to the caller
  • Examine how to define a function that returns a value to the caller, 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 the current location of the soccer ball at the bottom of the screen.  You may also notice that the size of the ball is continuously, randomly changing.

2. Examining The Program:Using a function that is built into the CS1XNALib

Since the source code to this program is nearly identical to the program uses in the previous tutorial, we will only examine the code that's new, or different. 

Let's start by examining how to use a pre-existing function, that returns a value.  
Our goal here is to randomly change the radius of the soccer ball with each update of the game.  We will call a pre-existing function, that will produce the random number, and we'll use that to set the radius of the circle.

• PrintMessageToTopStatus():

  private void PrintMessageToTopStatus() {     EchoToTopStatus("Watch the ball size change randomly?!"); }

  • The first, minor change that we'll examine is the new message that we're printing at the top of the screen. 
  • We continue to print the message from the PrintMessageToTopStatus method, so the only thing we need to change is the message itself.
• 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 + RandomFloat();     aBall.Texture = "SoccerBall"; }

  • The code for InitializeWorld is almost identical to the previous tutorial's version, with the exception of the line:
    aBall.Radius = BALL_INIT_RADIUS + RandomFloat();
    This line will ensure that the radius of the soccer ball is initialized to a random value, within a limited range of possible random values.
    • The RandomFloat() method, which is built into the XNACS1Lib (and NOT into the core C# libraries, nor into basic XNA) will produce a number between 0 and 1, pseudo-randomly. 
      • This function may produce the value 0.
      • This function will NOT produce the value 1.  It may produce values incredibly close to 1 (such as 0.9999f), but will never actually produce 1 itself.
      • It's worth noting that the function will only produce positive, floating point numbers.
    • Let's examine what happens when this line of code is executed.  First, we can mentally replace BALL_INIT_RADIUS with it's declared value, 3.0f.  Next, C# will call the RandomFloat function, which produces a random number.  Let's say that it produces the value 0.347f.  Having both 3.0f, and 0.347f., C# will then add them together to get 3.347f, which it then assigns to aBall.Radius.
  • Because of the above code, the starting radius for the soccer ball may be anywhere from 3.0f, all the way up to (but NOT including) 4.0f.
• 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;     // Calling the RandomFloat() function to get a random number between 0 to 1     aBall.Radius = BALL_INIT_RADIUS + RandomFloat();     // here is the function that prints!     PrintMessageToTopStatus();     EchoToBottomStatus("Soccer Ball position: " + aBall.Center + " Random Integer=" + GetANumber()); }

  • Pretty much all the code in UpdateWorld should be familiar, with the exception of the call to EchoToBottomStatus (which we will examine below), and the line:
        aBall.Radius = BALL_INIT_RADIUS + RandomFloat();
    • This line should actually be familiar from the InitializeWorld routine.
    • This line will, just like in the InitializeWorld function, randomly set the radius of the circle to be anywhere from 3.0f up to (but not including) 4.0f
  • Since this line will be executed every single time that UpdateWorld runs, the program will change the radius of the circle, randomly, many times per second.

2. Examining The Program:Creating Our Own, New Function

Let's move on to examining how to use a function that returns a value, that we've created ourselves.

• Defining the RandomFloat() function

  private void PrintMessageToTopStatus()     {         EchoToTopStatus("Watch the ball size change randomly?!");     }     /// <summary>     /// This is a simple function that returns an integer.     /// The purpose of this function is to demonstrate how to     /// implement a function with a return value.     /// </summary>     /// <returns>A random integer.</returns>     private int GetANumber()     {         return RandomInt(5, 15);     }     #endregion

  • Let's start by looking at the syntax for the new function definition. This definition is located in the 'Utility Function' region of the program's source code.
    First, we have the function's comment area, which lets us know what the intended effect of the function is:

        /// <summary>

        /// This is a simple function that returns an integer.

        /// The purpose of this function is to demonstrate how to

        /// implement a function with a return value.

        /// </summary>

        /// <returns>A random integer.</returns>

  • Next, we have the actual function definition itself.  The first line looks like:
        private int GetANumber()
    • We'll continue to use the word private.
    • Next, the keyword tells int C# that this function will do some work, and when it's done, it will return a value to the rest of the program.  Specifically, the function will produce an integer value.  There are a couple of implications to this declaration:
      • First, this function MUST produce an integer.  If C# thinks that it's somehow possible to leave this function in a way that doesn't produce an integer value, then you'll get a compiler error saying that.
      • Second, when your function tells C# what the return value is, the function ends.  It's very common to have the function end early, once it's got the value it wants to return.
    • We decided to name this function GetANumber; we tell C# that this will be the function's name by typing it out, here.
      • There are actually rules for creating multiple methods that all share the same name (this is called method overloading).  For now, we're going to leave that alone, and instead tell you to make sure that all your functions have unique names.
    •  The () at the end are still required.
  • The body of the function still starts with the opening curly brace - { -, and ends with the matching, closing curly brace - }. 
  • You'll notice that the only line of executable code in the function is
        return RandomInt(5, 15);
    • The return keyword is how we tell C# what the return value is.  When this line of code is executed, then follows the return keyword will be returned to the calling function, and execution of this function will stop.
    • Notice that we're using a function that's built into XNACS1Lib - RandomInt.  RandomInt will pseudo-randomly produce an integer that may be as small as 5, and as large as 14 (i.e., it will produce a random integer up to, but NOT including, 15)
      • There is a very similar, but not identical, way to generate random integers that's built into the core C# libraries.  If you're interested, you should look up documentation on a C#/.Net class called "Random".
  • Let's examine how we use this function in UpdateWorld:
• 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;     // Calling the RandomFloat() function to get a random number between 0 to 1     aBall.Radius = BALL_INIT_RADIUS + RandomFloat();     // here is the function that prints!     PrintMessageToTopStatus();     EchoToBottomStatus("Soccer Ball position: " + aBall.Center + " Random Integer=" + GetANumber()); }

  • Everything should be very familiar, except for the very last part of the line line (the new part is listed here in bold underline)
        EchoToBottomStatus("Soccer Ball position: " + aBall.Center + " Random Integer=" + GetANumber());
    • The very last part
      " Random Integer=" + GetANumber());

      will call the GetANumber() function that we defined, above.  GetANumber will call RandomInt to produce a number as low as 5, and as high as 14.  GetANumber will then return that value back to here, where the code will concatenate that number onto the string that we're displaying at the bottom of the screen.
      

  • Before we look at the semantics of defining and 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 make the function definition exactly, just like when we call the EchoToBottomStatus function.
    • This syntax works for situations where we've defined the new function within the same class as the UpdateWorld method.  In this case, both the UpdateWorld and GetANumber methods are within the Game1 class.  Don't worry too much about this detail right now - mostly we're just pointing this out to warn you that later on you'll see other, different ways of calling functions/methods.
• We'll examine the semantics of function definition, and function calling, with the aid of the following picture:
  
  • NOTE that the code in the above picture has been arranged so that everything fits easily on one screen - the actual source code in the example project may be identical to what's above.
  • Since you're already familiar with everything else in UpdateWorld, we will look at just the line that does the EchoToBottomStatus.  You can think of it as happening like this:
    1. The program gets the value of aBall.Center, and converts that number from a float to text.  It then concatenates "Soccer Ball position: " to the textual representation of that number.  Let's just say, for the sake of example, that the center of the circle is as (50, 35).  That means that this step will produce the text "Soccer Ball position: {X:50 Y:35}"
    2. The result of the previous step will be concatenated onto " Random Integer=", yielding "Soccer Ball position: {X:50 Y:35} Random Integer=".
    3. We can't do anything with this until we know what return value GetANumber will produce.  So C# calls this function, which causes the program to pause it's execution of UpdateWorld(), and jump to the GetANumber() function.
    4. The body of the GetANumber function consists of a single statement: return RandomInt(5, 15);.  Let's say that RandomInt produces the number 9, which GetANumber then returns to UpdateWorld in the next step.
    5. After we've finished executing all the statements in the function's body, we jump back up to UpdateWorld, and resume executing UpdateWorld.
       • This step takes the value "9", which was produced in the previous step, and send it back to UpdateWorld.
       • Technically, we jump back to the spot where we left from.  This makes a lot of sense, since we were about to concatenate "Soccer Ball position: {X:50 Y:35} Random Integer=" onto whatever GetANumber produced.  Mentally, we can think of this as taking the line
             EchoToBottomStatus("Soccer Ball position: {X:50 Y:35} Random Integer=" + GetANumber());

         and replacing it with

             EchoToBottomStatus("Soccer Ball position: {X:50 Y:35} Random Integer=" + 9);

    6. The next step is to convert the integer 9 into the text "9", and concatenate it onto the text "Soccer Ball position: {X:50 Y:35} Random Integer=", yielding "Soccer Ball position: {X:50 Y:35} Random Integer=9".
    7. Once all of the above has finished, we then pass the text along to EchoToBottomStatus, which actually displays it at the bottom of the screen.

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. Using GetANumber To Set The Soccer Ball's Radius
   For this exercise, you should use the same project that was explained in the above tutorial.
   See if you can build on what was shown to you above, and randomly set the radius to be an integer value between 8.0f, and 17.0f.  It should be possible for your code to set the radius to 8.0f, or to 17.0f.
3. Using GetANumber To Update The Top Status Bar
   For this exercise, you should use the same project that was explained in the above tutorial.
   See if you can build on what was shown to you above, and modify the PrintMessageToTopStatus so that it prints out a randomly selected integer, using the GetANumber function.

	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