Developing Programming Assignments on the XBOX 360 Console

 

Section II: The XnaAssignmentBase Library

a. The library SDK

 

Back to workshop main page

This is a wrapper class over the XNA framework. This class is designed to be simple and easy to use. As such, only drawings of circles and rectangles in 2D space are supported. Except for input from the Gamepad, programmers working with the XnaAssignmentBase class do not need to know anything about the XNA framework. If you are interested (and only if you are interested) here is the source code to the XnaAssignmentBase library. Note that you do not need to look at the source code implementation to learn how to work with the library. You should be able to read through this entire tutorial without looking at the source code of the XnaAssignmentBase library.

 

This document uses a simple working program (download the TemplateAssignment.zip) to explain how to work with the XnaAssignmentBase class.

 

The Sample Template Application:

Unzip TemplateAssignment.zip and you will see a folder named TemplateAssignment, inside this folder are two items:

  1. Assignment_PC.sln: this is the XNA Game Studio Express (GSE) solution file.

 

  1. Assignment: this is a folder including the following files and subfolders:

 

Folders/Files

Purposes

Assignment_PC.csproj

GSE project description file. This file is necessary but we will not work with this file.

Assignment.cs

This is the one file that contains the interesting source code of our project. This document will only refer to source code from this file.

Program.cs

A dummy container. We do not need to be concerned with the contents of this file.

Game.ico

GameThumbnail.png

Image on the top-left corner of the title bar of the application window and when the application window is iconized.

SupportFiles/XnaAssignmentBase_PC.dll

The DLL library file that contains the XnaAssignmentBase.

Properties/AssemblyInfo.cs

Contains miscellaneous information on the application. We will not work with this file. 

Content/Content.contentproj

GSE content project description file. This file is necessary but we will not work with this file.

Content/Resources/Fonts/Arial.spritefont

 The font used by our application. This folder and the font that must exist for all XnaAssignmentBase projects!

Content/Resources/Textures/bgTexture.jpg

Content/Resoruces/Textures/uwb_logo.jpg

Images that are used as textures in our drawings. We will discuss the use of these images when discussing drawing of circles and rectangles.

Content/Resoruces/Audio/GameAudio.xap

This is a project file created by the Microsoft Cross-Platform Audio Creation Tool. We will discuss this file in details at the very last of this tutorial guide.

Table 1: Folders and Files of the sample template project

 

Now, start the GSE, build and run the program. Figure 1 shows what you will see when running this application.

 

 

You should observe an application window with light pink background color; four circles one at each corner of the window; a small rectangle in the center; and two rather large rectangles connecting top and bottom right to the center. To interact with this example:

 

Left/Right Triggers: press and hold the left or right trigger on the controller, the center rectangle and bottom right circle will rotate and the controller will vibrate (no vibration effects on the keyboard).

 

The rest of this document explains, in detailed, how to accomplish all these functionality.

 

To work with the XnaAssignmentBase class to implement the sample template application, we only need to pay attention to Assignment.cs file. Please refer to Assignment.cs file for the following discussion.

 

There are 6 important aspects to using the XnaAssignmentBase class:

 

1. Declaring and Using Library

The very first few lines of source code in Assignment.cs file are the C# using statements:

using System;                           // System libraries

using System.Text;                      // Text

using System.Collections.Generic;       // Collections

 

using Microsoft.Xna.Framework;          // XNA libraries

using Microsoft.Xna.Framework.Graphics; // Utilities (e.g.,Vector2)

using Microsoft.Xna.Framework.Input;    // For GamePad object

 

using XnaAssignments;                   // Our own library

 

Notice that besides using typical system libraries, we must also use the XNA libraries. The XnaAssignments is referring to the XnaAssignmentBase library.

 

To ensure proper linking, the XnaAssignmentBase must be properly referenced from the References folder. As shown in Table 1, the library file, XnaAssignmentBase_PC.dll, is located in the SupportFiles folder of the project.

 

2. Resources Folders (Fonts, and Texture Images)

The XnaAssignmentBase library assumes that the Resources folders to be part of the uapplication project. The following figure shows the Resources folders.


 

Notice that the Audio, Fonts and Textures subfolders must be present:

  1. Content/Resources/Audio/GameAudio.xap

This is a project file created by the Microsoft Cross-Platform Audio Creation Tool. This tool is part of the XNA Game Studio distribution. You should be able to double click this file and start the audio creation tool. If this file is missing, your application will still run. However, without this file your application cannot generate any audio effects. We will discuss audio support at the very last of this tutorial.

 

  1. Content/Resources/Fonts/Arial.spritefont

This is the font used by the library in displaying status to the application window. This Font must be present in this folder, otherwise, the application will fail!

 

  1. Content/Resources/Textures/images

These are jpg images referenced by our drawing routines. Notice that these images are in jpg format. Any images referenced by drawing must be stored into this folder, otherwise, the application will fail.

 

3. Subclass from XnaAssignmentBase

The main class for the application (in this case the Assignment class) must be a sub-class of the XnaAssignmentBase class. The following code shows the declaration of the Assignment class.

 

public class Assignment : XnaAssignmentBase {

   private const float WORLD_MIN_X = 5.0f;  // min corner is (5, 10)

   private const float WORLD_MIN_Y = 10.0f;

   private const float WORLD_WIDTH = 20.0f; // width is 20.0

          

   // Notice we must call the base constructor!

   public Assignment() :

          base(new Vector2(WORLD_MIN_X, WORLD_MIN_Y), WORLD_WIDTH)

   {

          // Notice: memory allocation and initialization should be performed

          //         in InitializedWorld(). The constructor should be empty.

   }

 

Notice that we must call the base class constructor when constructing the Assignment class. In this case, we are defining a drawing area where the bottom-left corner is defined to be (5,10) with the width of the drawing area being 20.  Since the graphics device is created and initialized after the constructor, to avoid potential bugs, it is recommended that all memory allocation and initialization be performed in the InitializedWorld() function. The constructor should be left empty.

 

A note about drawing dimension:

When calling the base class constructor, we as the programmer, we can define the coordinate range for drawing in the application window. Noice that this range is independent from the hardware pixel units. In this case, for illustration purposes, we have chosen the lower left corner to be cooridnate position . This is to say, if we draw a circle with radius of 1 at position (6,11), the circle will show up at the lower left corner with left and bottom of the circle touching the left and bottom edges of the application window. The light gray circle at the lower left corner of Figure 1 is such a circle. We will examine the details of drawing this circle later.

 

Due to the aspect ratio limitation of HDTV, the height and width of the drawing area are always related with a fixed aspect ratio:


In this case, with a width of 20, the height of the drawing area is:


This means, the center of the drawing area is:


As highlighted at the bottom of Figure 1 and as will be discussed later, when running the sample template application, the computed center position is indeed (15, 15.625). We will examine the computation of these values later.

 

4. Override functions

As a programmer using the XnaAssignmentBase class, we must override three functions:

protected override void InitializeWorld() {

   // BackgroundTexture = @"bgTexture"; // texture image name              

   BackgroundColor = Color.LightPink;

}

protected override void UpdateWorld() {

   … // Input values from the Gamepad

     // Details shown in the last section.

   m_Rotation += rotR - rotL;

   if (rotR > 0)

       XnaAssignmentBase.PlayACue(1.0f, "Right"); // right audio effect

   …

}

protected override void DrawWorld() {

   … // Draws all the circles and rectangles

     // Details shown in next section.

}

 

  1. InitializeWorld()

This function is called exactly once at the beginning of the application. We should allocate memory and initialize variables in this routine. In the above case, we initialize the background color to be light pink. The commented out code sets the background to be an textured image. You are encouraged to un-comment the line and re-compile/re-run the application to observe the differences. We will discuss about BackgroundColor and BackgroundTexture later.

 

NOTE: The commented out line assigns bgTexture to be the background texture image. Notice that “beTexture” is the name of the “bgTexture.jpg” file located in the Content/Resources/Textures folder. Notice that the image file must exist in the texture folder. In addition, notice that the image file is referred to without the “.jpg” extension.

 

  1. UpdateWorld()

This function is called once about every 25 milliseconds. Notice that this is frequent enough for real time animations. As an application programmer, we should udpate the values of the instance variables according to the logics of our application. In this case, rotR and rotL are values from the gamepad triggers: when the user press the gamepad triggers, rotR and rotL will become non-zero. We increase/decrease the m_Rotation value accordingly. The m_Rotation value will be used in DrawWorld() to rotate the center rectangle and bottom right circle.  The PlayACue() function plays a short snipet of audio effect. In this case, a pre-recorded wave file that contains a cue namde “right” is played. We will discuss audio effect at the very last of this tutorial.

 

NOTE: It is very important to never issue any drawing commands from the UpdateWorld() function. DrawWorld() should be the only function that issues drawing commands.

 

  1. DrawWorld()

This function is also called once about every 25  milliseconds. This function complements the UpdateWorld() function, where after the application state is updated, this function will be responsible for drawing everything. The details of drawing is left until next section.

 

NOTE: It is very important to never change any application state (i.e., instance variables) in this function. UpdateWorld() is the function that is responsible for updating the instance variables. This function should only issue drawing commands.

 

5. Drawing and State Accessing Functions

 

The XnaAssignmentBase class supports a total of 3 2D drawing routines, and two different status echo functions. In addition, an application program can inquire about the drawing dimension and set the background color/texture. No other functions are supported. The simplicity and restriction are results of concious design decisions. We want to keep the library simple such that people with no gaming or graphics background can begin programming with minimal overhead.

 

Set background color/texture:

As we have already seen (in InitializeWorld()):

Color BackgroundColor – A write-only variable for setting the background of the drawing area (application window).

String BackgroundTexture – A write-only variable for setting an image to be the background of the drawing area (application window).

Notice that when BackgroundTexture is pointing to a valid image, the image will be displayed in the application window and BackgroundColor is ignored.

 

Inquire Drawing Dimension:

At any point in our application, when we need to find out about the dimension of the drawing area, we can access:

Vector2 WorldMin – A read-only variable that returns the coordinate position at lower left corner.

Vector2 WorldMax – A read-only variable that returns the cooridnate position at the upper right corner.

Notice that these variables are read-only. This means, once the cooridnate range is defined (during the base contructor call),  it cannot be changed during run-time.

 

Output Status Functions:

Please refer to Figure 1, the top and bottom left of the application window include text displays of the application status.

void EchoToTopStatus(String msg)

void EchoToBottomStatus(string msg)

 

 

Each of the above two functions is capable of echoing status to the corresponding area of the application window.

 

Draw Circle/Rectangle Functions:

The DrawCircle() function draws a circle based on a center and radius:

 

The first DrawRectangle() function draws a rectangle based on the center and dimension of the rectangle: