Technical - Articles

Using Animated Pieces in a Board-based Game wit...

Sat, 25 Feb 2012 04:33:01 +0000

This article by Kurt Jaegers, author of XNA 4.0 Game Development by Example: Beginner's Guide, enhances a board-based puzzle game called Flood Control in XNA 4.0 using animation. In this article, we will cover:

Animating the rotation of pieces when manipulated by the player
Gradually fading out pieces of completed scoring chains
Animating the falling of pieces into place on the board

All of these enhancements will give the player a better game experience, as well as give us the opportunity to learn more about how the SpriteBatch class can be used for animation.

Animated pieces
We will define three different types of animated pieces: rotating, falling, and fading. The animation for each of these types will be accomplished by altering the parameters of the SpriteBatch.Draw() call.

Classes for animated pieces
In order to represent the three types of animated pieces, we will create three new classes. Each of these classes will inherit from the GamePiece class, meaning they will contain all of the methods and members of the GamePiece class, but add additional information to support the animation.

Child classes
Child classes inherit all of their parent's members and methods. The RotatingPiece class can refer to the pieceType and suffix of the piece without recreating them within RotatingPiece itself. Additionally, child classes can extend the functionality of their base class, adding new methods and properties or overriding old ones. In fact, Game1 itself is a child of the Micrsoft.Xna.Game class, which is why all of the methods we use (Update(), Draw(), LoadContent(), and so on) are declared as "override".

Let's begin by creating the class we will use for rotating pieces.

Time for action – rotating pieces
Open your existing Flood Control project in Visual C# Express if it is not already active.

Add a new class to the project called "RotatingPiece".

Add "using Microsoft.Xna.Framework;" to the using area at the top of the class.

Update the declaration of the class to read class RotatingPiece : GamePiece.

Add the following declarations to the RotatingPiece class:

public bool clockwise;

public static float rotationRate = (MathHelper.PiOver2 / 10);
private float rotationAmount = 0;
public int rotationTicksRemaining = 10;

Add a property to retrieve the current rotation amount:

public float RotationAmount
{
get
{
  if (clockwise)
	return rotationAmount;
  else
	return (MathHelper.Pi*2) - rotationAmount;
}
}

Add a constructor for the RotatingPiece class:

public RotatingPiece(string pieceType, bool clockwise)
	  : base(pieceType)
{
  this.clockwise = clockwise;
}

Add a method to update the piece:

public void UpdatePiece()
{
   rotationAmount += rotationRate;
   rotationTicksRemaining = (int)MathHelper.Max(0,
							rotationTicksRemaining-1);
}

What just happened?
In step 2, we modified the declaration of the RotatingPiece class by adding : GamePiece to the end of it. This indicates to Visual C# that the RotatingPiece class is a child of the GamePiece class.

The clockwise variable stores a "true" value if the piece will be rotating clockwise and "false" if the rotation is counter-clockwise.

When a game piece is rotated, it will turn a total of 90 degrees (or pi/2 radians) over 10 animation frames. The MathHelper class provides a number of constants to represent commonly used numbers, with MathHelper.PiOver2 being equal to the number of radians in a 90 degree angle. We divide this constant by 10 and store the result as the rotationRate for use later. This number will be added to the rotationAmount float, which will be referenced when the animated piece is drawn.

Working with radians
All angular math is handled in radians from XNA's point of view. A complete (360 degree) circle contains 2*pi radians. In other words, one radian is equal to about 57.29 degrees. We tend to relate to circles more often in terms of degrees (a right angle being 90 degrees, for example), so if you prefer to work with degrees, you can use the MathHelper.ToRadians() method to convert your values when supplying them to XNA classes and methods.

The final declaration, rotationTicksRemaining, is reduced by one each time the piece is updated. When this counter reaches zero, the piece has finished animating.

When the piece is drawn, the RotationAmount property is referenced by a spriteBatch. Draw() call and returns either the rotationAmount property (in the case of a clockwise rotation) or 2*pi (a full circle) minus the rotationAmount if the rotation is counter-clockwise.

The constructor in step 7 illustrates how the parameters passed to a constructor can be forwarded to the class' parent constructor via the :base specification. Since the GamePiece class has a constructor that accepts a piece type, we can pass that information along to its constructor while using the second parameter (clockwise) to update the clockwise member that does not exist in the GamePiece class. In this case, since both the clockwise member and the clockwise parameter have identical names, we specify this.clockwise to refer to the clockwise member of the RotatingPiece class. Simply clockwise in this scope refers only to the parameter passed to the constructor.

this notation
You can see that it is perfectly valid C# code to have method parameter names that match the names of class variables, thus potentially hiding the class variables from being used in the method (since referring to the name inside the method will be assumed to refer to the parameter). To ensure that you can always access your class variables even when a parameter name conflicts, you can preface the variable name with this. when referring to the class variable. this. indicates to C# that the variable you want to use is part of the class, and not a local method parameter.

Lastly, the UpdatePiece() method simply increases the rotationAmount member while decreasing the rotationTicksRemaining counter (using MathHelper.Max() to ensure that the value does not fall below zero).

Time for action – falling pieces
Add a new class to the Flood Control project called "FallingPiece".

Add using Microsoft.Xna.Framework; to the using area at the top of the class.

Update the declaration of the class to read class FallingPiece : GamePiece

Add the following declarations to the FallingPiece class:

public int VerticalOffset;
public static int fallRate = 5;

Add a constructor for the FallingPiece class:

public FallingPiece(string pieceType, int verticalOffset)
	: base(pieceType)
{
  VerticalOffset = verticalOffset;
}

Add a method to update the piece:

public void UpdatePiece()
{
   VerticalOffset = (int)MathHelper.Max(
			0,
			VerticalOffset - fallRate);
}

What just happened?
Simpler than a RotatingPiece, a FallingPiece is also a child of the GamePiece class. A falling piece has an offset (how high above its final destination it is currently located) and a falling speed (the number of pixels it will move per update).

As with a RotatingPiece, the constructor passes the pieceType parameter to its base class constructor and uses the verticalOffset parameter to set the VerticalOffset member. Note that the capitalization on these two items differs. Since VerticalOffset is declared as public and therefore capitalized by common C# convention, there is no need to use the "this" notation, since the two variables technically have different names.

Lastly, the UpdatePiece() method subtracts fallRate from VerticalOffset, again using the MathHelper.Max() method to ensure the offset does not fall below zero.

Time for action – fading pieces
Add a new class to the Flood Control project called "FadingPiece".

Add using Microsoft.Xna.Framework; to the using area at the top of the class.

Update the declaration of the class to read class FadingPiece : GamePiece

Add the following declarations to the FadingPiece class:

public float alphaLevel = 1.0f;
public static float alphaChangeRate = 0.02f;

Add a constructor for the FadingPiece class:

public FadingPiece(string pieceType, string suffix)
	: base(pieceType, suffix)
{
}

Add a method to update the piece:

public void UpdatePiece()
{
alphaLevel = MathHelper.Max(
	   0,
	   alphaLevel - alphaChangeRate);
}

What just happened?
The simplest of our animated pieces, the FadingPiece only requires an alpha value (which always starts at 1.0f, or fully opaque) and a rate of change. The FadingPiece constructor simply passes the parameters along to the base constructor.

When a FadingPiece is updated, alphaLevel is reduced by alphaChangeRate, making the piece more transparent.

Managing animated pieces
Now that we can create animated pieces, it will be the responsibility of the GameBoard class to keep track of them. In order to do that, we will define a Dictionary object for each type of piece.

A Dictionary is a collection object similar to a List, except that instead of being organized by an index number, a dictionary consists of a set of key and value pairs. In an array or a List, you might access an entity by referencing its index as in dataValues[2] = 12; With a Dictionary, the index is replaced with your desired key type. Most commonly this will be a string value. This way, you can do something like fruitColors["Apple"]="red";

Time for action – updating GameBoard to support animated pieces
In the declarations section of the GameBoard class, add three dictionaries:

public Dictionary fallingPieces =
new Dictionary();
public Dictionary rotatingPieces =
new Dictionary();
public Dictionary fadingPieces =
new Dictionary();

Add methods to the GameBoard class to create new falling piece entries in the dictionaries:

public void AddFallingPiece(int X, int Y,
  string PieceName, int VerticalOffset)
{
  fallingPieces[X.ToString() + "_" + Y.ToString()] = new
	   FallingPiece(PieceName, VerticalOffset);
}

public void AddRotatingPiece(int X, int Y,
string PieceName, bool Clockwise)
{
  rotatingPieces[X.ToString() + "_" + Y.ToString()] = new
	   RotatingPiece(PieceName, Clockwise);
}

public void AddFadingPiece(int X, int Y, string PieceName)
{
  fadingPieces[X.ToString() + "_" + Y.ToString()] = new
	   FadingPiece(PieceName,"W");
}

Add the ArePiecesAnimating() method to the GameBoard class:

{
if ((fallingPieces.Count == 0) &&
	 (rotatingPieces.Count == 0) &&
	 (fadingPieces.Count == 0))
{
   return false;
}
else
{
   return true;
}
}

Add the UpdateFadingPieces() method to the GameBoard class:

private void UpdateFadingPieces()
{
  Queue RemoveKeys = new Queue();

  foreach (string thisKey in fadingPieces.Keys)
  {
	fadingPieces[thisKey].UpdatePiece();
	if (fadingPieces[thisKey].alphaLevel == 0.0f)
		RemoveKeys.Enqueue(thisKey.ToString());
  }
  while (RemoveKeys.Count > 0)
	  fadingPieces.Remove(RemoveKeys.Dequeue());
}

Add the UpdateFallingPieces() method to the GameBoard class:

private void UpdateFallingPieces()
{
  Queue RemoveKeys = new Queue();
  foreach (string thisKey in fallingPieces.Keys)
  {
   fallingPieces[thisKey].UpdatePiece();
   if (fallingPieces[thisKey].VerticalOffset == 0)
	   RemoveKeys.Enqueue(thisKey.ToString());
  }
  while (RemoveKeys.Count > 0)
	 fallingPieces.Remove(RemoveKeys.Dequeue());
}

Add the UpdateRotatingPieces() method to the GameBoard class:

private void UpdateRotatingPieces()
{
  Queue RemoveKeys = new Queue();
  foreach (string thisKey in rotatingPieces.Keys)
  {
   rotatingPieces[thisKey].UpdatePiece();
   if (rotatingPieces[thisKey].rotationTicksRemaining == 0)
	   RemoveKeys.Enqueue(thisKey.ToString());
  }
  while (RemoveKeys.Count > 0)
	   rotatingPieces.Remove(RemoveKeys.Dequeue());
}

Add the UpdateAnimatedPieces() method to the GameBoard class:

public void UpdateAnimatedPieces()
{
  if (fadingPieces.Count == 0)
  {
	UpdateFallingPieces();
	UpdateRotatingPieces();
  }
  else
  {
	UpdateFadingPieces();
  }
}

What just happened?
After declaring the three Dictionary objects, we have three methods used by the GameBoard class to create them when necessary. In each case, the key is built in the form "X_Y", so an animated piece in column 5 on row 4 will have a key of "5_4". Each of the three Add... methods simply pass the parameters along to the constructor for the appropriate piece types after determining the key to use.

When we begin drawing the animated pieces, we want to be sure that animations finish playing before responding to other input or taking other game actions (like creating new pieces). The ArePiecesAnimating() method returns "true" if any of the Dictionary objects contain entries. If they do, we will not process any more input or fill empty holes on the game board until they have completed.

The UpdateAnimatedPieces() method will be called from the game's Update() method and is responsible for calling the three different update methods above (UpdateFadingPiece(), UpdateFallingPiece(), and UpdateRotatingPiece()) for any animated pieces currently on the board. The first line in each of these methods declares a Queue object called RemoveKeys. We will need this because C# does not allow you to modify a Dictionary (or List, or any of the similar "generic collection" objects) while a foreach loop is processing them.

A Queue is yet another generic collection object that works like a line at the bank. People stand in a line and await their turn to be served. When a bank teller is available, the first person in the line transacts his/her business and leaves. The next person then steps forward. This type of processing is known as FIFO, or First In, First Out.

Using the Enqueue() and Dequeue() methods of the Queue class, objects can be added to the Queue (Enqueue()) where they await processing. When we want to deal with an object, we Dequeue() the oldest object in the Queue and handle it. Dequeue() returns the first object waiting to be processed, which is the oldest object added to the Queue.

Collection classes
C# provides a number of different "collection" classes, such as the Dictionary, Queue, List, and Stack objects. Each of these objects provides different ways to organize and reference the data in them. For information on the various collection classes and when to use each type, see the following MSDN entry: http://msdn.microsof.../6tc79sx1(VS.80).aspx

Each of the update methods loops through all of the keys in its own Dictionary and in turn calls the UpdatePiece() method for each key. Each piece is then checked to see if its animation has completed. If it has, its key is added to the RemoveKeys queue. After all of the pieces in the Dictionary have been processed, any keys that were added to RemoveKeys are then removed from the Dictionary, eliminating those animated pieces.

If there are any FadingPieces currently active, those are the only animated pieces that UpdateAnimatedPieces() will update. When a row is completed, the scoring tiles fade out, the tiles above them fall into place, and new tiles fall in from above. We want all of the fading to finish before the other tiles start falling (or it would look strange as the new tiles pass through the fading old tiles).

Fading pieces
In the discussion of UpdateAnimatedPieces(), we stated that fading pieces are added to the board whenever the player completes a scoring chain. Each piece in the chain is replaced with a fading piece.

Time for action – generating fading pieces
In the Game1 class, modify the CheckScoringChain() method by adding the following call inside the foreach loop before the square is set to "Empty":

gameBoard.AddFadingPiece(
(int)ScoringSquare.X,
(int)ScoringSquare.Y,
gameBoard.GetSquare(
  (int)ScoringSquare.X,
  (int)ScoringSquare.Y));

What just happened?
Adding fading pieces is simply a matter of getting the square (before it is replaced with an empty square) and adding it to the FadingPieces dictionary. We need to use the (int) typecasts because the ScoringSquare variable is a Vector2 value, which stores its X and Y components as floats.

Falling pieces
Falling pieces are added to the game board in two possible locations: From the FillFromAbove() method when a piece is being moved from one location on the board to another, and in the GenerateNewPieces() method, when a new piece falls in from the top of the game board.

Time for action – generating falling pieces
Modify the FillFromAbove() method of the GameBoard class by adding a call to generate falling pieces right before the rowLookup = -1; line:

AddFallingPiece(x, y, GetSquare(x, y),
   GamePiece.PieceHeight *(y-rowLookup));

Update the GenerateNewPieces() method by adding the following call right after the RandomPiece(x,y) line:

AddFallingPiece(x, y, GetSquare(x, y),
   GamePiece.PieceHeight * GameBoardHeight);

What just happened?
When FillFromAbove() moves a piece downward, we now create an entry in the FallingPieces dictionary that is equivalent to the newly moved piece. The vertical offset is set to the height of a piece (40 pixels) times the number of board squares the piece was moved. For example, if the empty space was at location 5,5 on the board, and the piece above it (5,4) is being moved down one block, the animated piece is created at 5,5 with an offset of 40 pixels (5-4 = 1, times 40).

When new pieces are generated for the board, they are added with an offset equal to the height (in pixels) of the game board, determined by multiplying the GamePiece.PieceHeight value by the GameBoardHeight. This means they will always start above the playing area and fall into it.

Rotating pieces
The last type of animated piece we need to deal with adding during play is the rotation piece. This piece type is added whenever the user clicks on a game piece.

Time for action – modify Game1 to generate rotating pieces
Update the HandleMouseInput() method in the Game1 class to add rotating pieces to the board by adding the following inside the if (mouseState.LeftButton == ButtonState.Pressed) block before gameBoard.RotatePiece() is called:

gameBoard.AddRotatingPiece(x, y,
	gameBoard.GetSquare(x, y), false);

Still in HandleMouseInput(), add the following in the same location inside the if block for the right mouse button:

gameBoard.AddRotatingPiece(x, y,
   gameBoard.GetSquare(x, y), true);

What just happened?
Recall that the only difference between a clockwise rotation and a counter-clockwise rotation (from the standpoint of the AddRotatingPiece() method) is a true or false in the final parameter. Depending on which button is clicked, we simply add the current square (before it gets rotated, otherwise the starting point for the animation would be the final position) and "true" for right mouse clicks or "false" for left mouse clicks.

Calling UpdateAnimatedPieces()
In order for the UpdateAnimatedPieces() method of the GameBoard class to run, the game's Update() method needs to be modified to call it.

Time for action – updating Game1 to update animated pieces
Modify the Update() method of the Game1 class by replacing the current case statement for the GameState.Playing state with:

case GameStates.Playing:
  timeSinceLastInput +=
	(float)gameTime.ElapsedGameTime.TotalSeconds;
  if (gameBoard.ArePiecesAnimating())
  {
   gameBoard.UpdateAnimatedPieces();
  }
  else
  {
   gameBoard.ResetWater();

   for (int y = 0; y < GameBoard.GameBoardHeight; y++)
   {
	CheckScoringChain(gameBoard.GetWaterChain(y));
   }
   gameBoard.GenerateNewPieces(true);

   if (timeSinceLastInput >= MinTimeSinceLastInput)
   {
	HandleMouseInput(Mouse.GetState());
   }
  }
  break;

What just happened?
This method is very similar to its previous incarnation. In this instance, we check to see if there are outstanding animated pieces to process. If there are, UpdateAnimatedPieces() is run. If no animated pieces currently exist, the previous behaviour of the GameStates. Playing case is executed.

Drawing animated pieces
Our animated pieces are almost completed. In fact, they all function right now but you cannot see them because we have not yet updated Draw() to take them into account.

Time for action – update Game1 to draw animated pieces
Add methods to the Game1 class to draw each potential type of game piece (animated and non-animated):

private void DrawEmptyPiece(int pixelX, int pixelY)
{
  spriteBatch.Draw(
   playingPieces,
   new Rectangle(pixelX, pixelY,
	GamePiece.PieceWidth, GamePiece.PieceHeight),
	EmptyPiece,
	Color.White);
}

private void DrawStandardPiece(int x, int y,
  int pixelX, int pixelY)
{
  spriteBatch.Draw(
   playingPieces, new Rectangle(pixelX, pixelY,
	 GamePiece.PieceWidth, GamePiece.PieceHeight),
   gameBoard.GetSourceRect(x, y),
   Color.White);
}

private void DrawFallingPiece(int pixelX, int pixelY,
	string positionName)
{
  spriteBatch.Draw(
   playingPieces,
   new Rectangle(pixelX, pixelY -
	 gameBoard.fallingPieces[positionName].VerticalOffset,
	  GamePiece.PieceWidth, GamePiece.PieceHeight),
	  gameBoard.fallingPieces[positionName].GetSourceRect(),
	 Color.White);
}

private void DrawFadingPiece(int pixelX, int pixelY,
   string positionName)
{
  spriteBatch.Draw(
   playingPieces,
   new Rectangle(pixelX, pixelY,
	GamePiece.PieceWidth, GamePiece.PieceHeight),
   gameBoard.fadingPieces[positionName].GetSourceRect(),
   Color.White *
	gameBoard.fadingPieces[positionName].alphaLevel);
}

private void DrawRotatingPiece(int pixelX, int pixelY,
   string positionName)
{
  spriteBatch.Draw(
   playingPieces,
   new Rectangle(pixelX + (GamePiece.PieceWidth / 2),
	   pixelY + (GamePiece.PieceHeight / 2),
	   GamePiece.PieceWidth,
	   GamePiece.PieceHeight),
   gameBoard.rotatingPieces[positionName].GetSourceRect(),
   Color.White,
   gameBoard.rotatingPieces[positionName].RotationAmount,
   new Vector2(GamePiece.PieceWidth / 2,
	 GamePiece.PieceHeight / 2),
   SpriteEffects.None, 0.0f);
}

Modify the Draw() method of the Game1 class by replacing the for loop that currently draws the playing pieces with:

for (int x = 0; x < GameBoard.GameBoardWidth; x++)
  for (int y = 0; y < GameBoard.GameBoardHeight; y++)
  {
   int pixelX = (int)gameBoardDisplayOrigin.X +
	   (x * GamePiece.PieceWidth);
   int pixelY = (int)gameBoardDisplayOrigin.Y +
	   (y * GamePiece.PieceHeight);

   DrawEmptyPiece(pixelX, pixelY);

   bool pieceDrawn = false;

   string positionName = x.ToString() + "_" + y.ToString();

   if (gameBoard.rotatingPieces.ContainsKey(positionName))
   {
	DrawRotatingPiece(pixelX, pixelY, positionName);
	pieceDrawn = true;
   }

   if (gameBoard.fadingPieces.ContainsKey(positionName))
   {
	DrawFadingPiece(pixelX, pixelY, positionName);
	pieceDrawn = true;
   }

   if (gameBoard.fallingPieces.ContainsKey(positionName))
   {
	DrawFallingPiece(pixelX, pixelY, positionName);
	pieceDrawn = true;
   }

   if (!pieceDrawn)
   {
	DrawStandardPiece(x, y, pixelX, pixelY);
   }
}

Try it out! Run your game and complete a few rows.

What just happened?
To keep things organized, we have split the drawing of each of the different potential piece types into its own small method. These methods (DrawEmptyPiece(), DrawStandardPiece(), DrawFallingPiece(), DrawFadingPiece(), and DrawRotatingPiece()) each contain only a single statement to draw the piece.

Before we look at how each of the pieces is actually drawn, let's examine the way we determine which of these methods to call when drawing a piece. The structure of the drawing loop is still the same as it was before we added animated pieces: each square on the board is looped through, with a blank square being drawn first in each position.

After the blank space, a new Boolean value called pieceDrawn is declared and set to false. If an animated piece occupies a square, only the animated piece will be drawn, and not the underlying game piece.

The reason for this is that when the user clicks on the mouse button to rotate a piece, in memory the piece is rotated immediately. The animated piece that the user sees is inserted into the drawing process so it looks like the piece is turning. If both the animated piece and the real underlying piece were to be drawn, the final rotation position would be visible overlaid on top of the rotating piece while the rotation animation was playing.

The positionName string contains the dictionary key for the space we are currently drawing (in "X_Y" format). We use this to check each of the animated piece dictionaries to see if they contain an entry for that key.

If they do, the animated piece is drawn and the pieceDrawn variable is set to true. If the piece still has not been drawn after all of the dictionaries have been checked, the base piece is drawn just as it was before.

SpriteBatch overloads
Both falling and fading pieces are drawn using the SpriteBatch.Draw() overload that we are already familiar with; where a Texture2D, destination Rectangle, source Rectangle, and Color are specified when drawing. By multiplying our base drawing color (white) by the alpha value for a fading piece, we cause the whole piece to be drawn partially transparent. As the time passes, the alpha value will reach zero, and the piece will be fully transparent.

However, rotated pieces need to use an extended version of the SpriteBatch.Draw() call. The first four parameters are the same as our existing Draw() calls. To these parameters, we add a float for the rotation amount, a Vector2 for the origin around which the rotation takes place, a SpriteEffects property (set to SpriteEffects.None in this case) and a sorting depth (set to 0, or the top level).

When using a rotation with this form of the SpriteBatch.Draw() call, it is necessary to specify the point around which the sprite should be rotated. If we were to set the origin to Vector2.Zero (equivalent to 0, 0) the sprite would rotate around the upper left corner of the image, swinging into the spaces of other tiles on the board. The center point of the sprite is specified in local sprite coordinates (as opposed to screen coordinates, or even coordinates within the texture the sprite is being pulled from). The local coordinates of the sprite range from 0, 0 in the upper left corner to the height and width of the sprite in the lower right. In our case, the lower right corner of the sprite is GamePiece.PieceWidth, GamePiece.PieceHeight, or 40, 40.

By specifying new Vector2(GamePiece.PieceWidth/2, GamePiece.PieceHeight/2) we are setting the origin to the center of the sprite, meaning it will rotate in place as expected.

Summary
In the above article we covered:

Animating the rotation of pieces when manipulated by the player
Gradually fading out pieces of completed scoring chains
Animating the falling of pieces into place on the board

How we Built an iOS game on PC

Thu, 23 Feb 2012 20:54:34 +0000

This article chronicles Catch the Monkey from ideation to sale worldwide in the App Store.

You can find out more about Mirthwerx and our projects at our website.

Intro
Many people want to get into making games, specifically mobile games. Well, we were one of you! This series is for anyone who wants to jump in and do it. Our goal is twofold:
1) To demonstrate that it is possible
2) To share lessons we learned that will hopefully benefit those starting out

About Us
We at Mirthwerx are a team of two: Thomas the self taught programmer and Alex the artist who studied classical animation at Sheridan. We met 20 years ago in highschool and have tried to make a game ever since.

Before we embarked on this project, I had been writing business web/mobile software with Microsoft technologies for about 15 years. With this background, we knew how to build software properly (OOP, design specs, usability concerns). But you will see later how we failed to apply it.

Design and Prototyping

Technology
From day one, we knew we wanted two things:

1) Android is the future, but iPhone is the now. We will build for both

2) We want to build on a windows platform with familiar environment and tools

I started investigating the Mac platform and XCode by buying a mac-mini. After spending a day with ObjectiveC I knew I did not want to work in that language at all, it would drive me batty. Fortunately we could address both goals with one solution: Marmalade (formerly called Airplay before Apple started calling everything Airplay).

Here you can see using VS2008 C++ debugging and tracing in real time with an iOS emulator

Marmalade allows the user to write once in Visual Studio C++ and run anywhere (iOS, Android, Blackberry, Windows Phone, Bada, and more). The simulator is excellent, with all the performance monitoring you’d expect, so it was a total win finding this technology. The pricing for independent developers is also very reasonable.

Design
Given this was our first title, we wanted to keep the design of the app simple. The initial concept was this:
The player swipes their finger to tickle monkeys in a farmer’s field. The monkeys come more and faster in each level. The end.

It seemed so simple at the time, and there were only two of us, that we thought we didn’t need a proper specification document. Instead we used Xmind (free!) for mind mapping all our ideas and kept “the design” in there. The game was intentionally art heavy, as our artist was able to work full time on this project, but I was only able to work after hours/weekends.

Mind Mapping is a powerful way to capture ideas quickly and organize them well for later reference. Xmind is a free open source tool for mind mapping.

Prototype
In business software an initial prototype for the users is critical. It removes all the guess work that comes from reading and interpreting a Word document.

Rather than programming a prototype for real, we used an extremely powerful and inexpensive ($40 for a registered version!) game making tool called GameMaker 8. This allowed us to throw together the graphics that had already been drawn with a few play mechanics and see if we had something fun or not. I think all in the first prototype took 20 hours. Since it was running on a windows screen, there was no way to test the actual touch/swipe mechanic, so we just resorted to clicking, each click simulating a swipe. So the big question: Is it fun?

First prototype of Catch the Monkey made in Game Maker 8

No. It was not fun. We changed around several variables (speed of monkey, clicks to make them laugh, number of monkeys at one time) but it was just too simple. There wasn’t enough to do. We couldn’t see playing it for more than 2 minutes. We had no desire to make a “gag game” so we went back to the drawing board.

In our design brainstorming session we came up with the idea of using different kinds of tools to interact with the monkeys. Tickling was just the initial tool, a feather, but later you could get other tools. This seemed to have some promise. So we thought up several types of tools, narrowed it down to a few that were easy to put into a prototype, and then made prototype 2. In this version the player has an inventory of each tool. When one ran out, the farmer would call his wife for a refill which would appear in a few moments. It made the player have to think about what tool to use when. We also gave the player control of the farmer, they could direct the farmer to walk to certain areas or pickup a certain monkey. Finally we added the concept of catching stars. Every so often a star would pop out and the player would have to click it to catch it. Stars would be used later for upgrades, though we never built it into the prototype. So: Is it fun?

Prototype 2 Made with Game Maker, notice the inventory counts for the differing tools

Yes and no. There was a kernel of fun in there that was trying to get out, but there were still many things blocking it. We knew choosing (essentially strategizing) between tools was fun and catching stars was fun (it was spontaneous, different, and difficult). We dropped controlling the farmer (too cumbersome), dropped the refill concept (too complex and arbitrary). We needed a game mechanic to allow the player to strategize and manage resource(s).

I must note that when we prototyped, we didn't just do it amongst ourselves, but with others who were not involved in the project to get their honest feedback. Those working on a project are too biased to give a proper perspective to what they are testing. You’ll see later how this also came to bite us in the butt.

Conclusion
At this stage we sat down for our third and final all day brainstorming session. We went through many concepts before considering the mana/cooldown mechanic in WoW. In WoW the player can’t just cast all the spells they want, they have a mana bar limiting the number that can be used in a short period of time. But some spells are so powerful that while they do use up mana, they must cool down for a long time (several minutes) so they cannot be used in a single battle. We felt if every tool required a common energy pool, but had varying cooldowns, we could strike the strategic balance we were looking for. By having enough variables we could keep things fresh and interesting for the player, and therefore they would be engaged and have fun.

One additional thing we decided was to create Star Powers. Stars to this point were only used as a currency to purchase upgrades, but a Star Power is a special ability that can help you now mid level for a certain cost in stars. By making stars dual purpose, and facing the player with a decision for a momentary benefit now rather than a long term pay off later, is a great mechanic we tried to bring to other aspects. It became a fun challenge for us as designers to make star powers that were really really useful, but the smart player only uses sparingly so they can get all the upgrades.

The final toolbelt design.

With the design phase basically finished (design happens all the way through), we proceeded into building the core game.

Building the Core

Intro
In the first article, we covered how Catch the Monkey started from initial simple concept, to the technology we chose, through the prototyping phase. At the end of prototyping we had a greatly increased design, but despite knowing better, we didn’t document it thoroughly. We knew we had 12 tools to create, 10 types of monkeys, and some vague concept of a store which would allow the purchase of upgrades. How many upgrades and what they would do was not finalized. It was time to start coding!

This article is longer than the previous, I have attempted to keep it of reasonable length by highlighting only the most interesting aspects from the core construction phase. If you have a specific question, just post a comment and I’ll respond.

We Going to Do this or Not?!
As mentioned in the first article, the artist was working full time but I as the programmer was only able to work part time as I was required by other aspects of the business. The project dragged. It finally reached a point where the project would be cancelled due to lack of progress. Instead, I mapped out the time remaining to build the game. About 6 weeks (50hrs x 6 = 300hrs) should do it. I made an extreme decision: I booked a 6 week hiatus from work to go to my cottage and focus 100% on the game. While my wife was less than thrilled, she was supportive of seeing me get the game done. It was time to go “all in”. Hind sight confirms this was the right way to recover the project.

Our Single Biggest Mistake
Not having a properly defined design document would appear to be our largest mistake, but we made one that completely dwarfed it.

If you study the zombies in Plants vs Zombies, you will see there are many types of zombies, but they are made up of several graphical parts (head, body, arm, arm, legs) and several optional decorators (pylon, helmet, paper). By reusing and varying these components you can have many different types of zombie with minimal memory requirements. We wanted a similar approach with many kinds of monkeys each with varying abilities and weaknesses.

However, and we painfully learned this later, if you want to have this kind of reuse, you have to lay down very specific rules of what the characters can and cannot do. Notice in plants verses zombies that the zombies always face the camera (like the 2D South Park animation). No matter what they do, they never turn away from the camera to a profile view.

Well, early on in our animation and prototyping we decided when the monkey arrives at a plant he will plop down, TURN HIS BACK, and begin digging. Then when he gets a potato, he will TURN BACK and proceed to eat it. We completed all the artwork for the regular monkey before we discovered what a problem this was. When we wanted to have a hat monkey, we thought we would just create a separate hat object, attach it to the monkey, and off we go. Well as we did it we realized the hat (or vest, or sunglasses) has to turn with the monkey as he turns away from the camera. This requires one decorator frame per monkey frame and pixel perfect alignment. This means a whole host of painstakingly researched coordinates per frame to get it all to look right. It was so much work, and we didn’t want to redraw the digging animation, so we made an expedient decision: just duplicate all the frames for the regular monkey to the hat monkey with the hat pasted right into the frame. The artist went ahead and did this for each of the 6 additional types of monkeys.

Here is the math of why this was such a problem later:
1 monkey has a set of interaction sprite sheets (fear, ducky, laughing, walking, climbing, etc.) taking about 20mb of VRAM memory.
7 monkey types x 20mb = 140mb VRAM
The iPhone 3GS (iPod 3+) only has ~55MB of VRAM available (with a 15MB heap) before it starts crashing.
We had initially wanted to target the iPod Touch 2+, but it has only 30MB of VRAM and it became impossible. So we increased the system requirements to iPod 3+ and scrambled to get the VRAM down. We’ll talk more about this in the next article.

So the lesson is always map out memory requirements during the design phase, before you build it, rather than in the middle, or after. Had we of known the ramifications of the monkey turning away from the camera we would have gone a different direction with the art and the game wouldn’t be noticeably different.

Cute Monkeys in a Nasty Real-Time World
Many business developers I know avoid writing multi-threaded solutions when they can avoid it. Why? Because the race conditions that can occur between two separate threads doing their own thing are a nightmare for testing. There are so many permutations of what could be happening simultaneously in the application that if it crashes, it is difficult to reproduce never mind fix permanently.

When it comes to games, they are already real-time in that the Update() loop is executed every so many milliseconds not matter what. There is no concept of “blocking” calls like there is in Windows Forms development. This is just the way games are, and this is not what I’m referring to.

I’m talking about a real-time game verses a turn based game. A turn based game waits for user input, then responds accordingly; while waiting for user interaction there may be things happening on screen, nice effects and such, but the actual state of the game doesn’t change. In a real-time system the game state is constantly changing regardless of player interaction.

For our first time game, we NEVER should have chosen to do a real-time game.

Catch the Monkey was an incredible amount of effort to make everything work in a constantly changing environment. The number of testing scenarios is probably 20 times greater than a turn based system. The ability to replicate scenarios is extremely difficult, even when programming specific unit tests to occur. There was a point late the construction phase I wasn’t sure I could ever get it to stop crashing. Fortunately Marmalade has some amazing memory monitoring tools built into it I was able to find all the issues (I think!).

We learned this lesson so bitterly the next title we are currently working on is turn based.

Object Hierarchy
Obviously the power of OOP is the ability to build small, focused, encapsulated objects and then work with them at a higher level. My goal was to create an object hierarchy that knew how to instantiate, move, and render itself.

There was a time in my career where I didn’t do modelling. Once someone showed me Rational Rose, UML, and modelling I never went back. I always model my code, even personal projects no one will ever see, because I find it the best way to think through the problems before the code gets in the way. Rational Rose (or any proper modelling tool) helps you think through the design as you design. I used Rational Rose for several years, but when I went out on my own I couldn’t afford the $2,000/seat license. Fortunately the Open Source community came to the rescue with StarUML. StarUML is a powerful free object modeling tool. It is virtually identical to Rational Rose (at least to the last version I used in 2003).

Looking at the class design diagram, notice the two fundamental objects: GameObject and UIObject. Both of these inherit from Graphic. Graphic encapsulates all the Marmalade 2D API interaction, and therefore is necessary for rendering whether it is a monkey, a story slide, or a text object.

A GameObject is an object used in a GameScene (which is a level you play). It manages its own state, sprite sheets, depth calculation, scaling (based on depth), click handling, and hit detection. All play objects inherit from GameObject. UIObject is similar to GameObject, but is more lightweight and designed for non-play scenes, such as text, buttons, and images in the store or tool selection screens.

Design Patterns
We used GoF design patterns as necessary. For example:

We used the Factory pattern for our Level class; feed in a week and day, and it spits out a formatted level object, complete with any necessary tutorials.
We used two singletons for caching image files and sound files called GraphicManager and SoundManager, so even though each object is responsible for loading/unloading it’s assets, it does it through these caches to minimize the actual memory used.We used a singleton for player state (number of stars, current progress, which tutorials have fired, upgrades purchased). This made it extremely simple to serialize/deserialize player progress.
We used the Decorator pattern for adding graphical effects to any GameObject, such as fade in, fade out, flashing, etc.

One of the early conceptual struggles I had was how to bring all the different types of screens (a store, a tool selection, story modes, title screens, option/menu screens, game modes) together into a nice organized OOP paradigm. While researching I found two excellent articles by iPhone game maker rivermanmedia:
The Scene System
The GUI Stack

I knew this paradigm was the way forward not just for this game, but probably all future games.

The Scene system breaks down the game into a series of scenes. In Catch the Monkey I ended up with 19, like SceneTitle and SceneDialog. Each of these inherit a common interface from Scene such as: Init(), Update(), Render(), Shutdown(). I created a SceneManager singleton that contains all the logic related to scene creation, shutdown, and transition. Now my code can be blissfully unaware of what else is going on at a higher level. If I want a scene to end and begin a new scene, I call:

SM->ChangeScene(new SceneShop());

If I want the new scene to be focused and on top of the current scene, I call:

SM->AddScene(new SceneOptions());

The SceneManager knows if there currently are other scenes involved, winding them down appropriately, removing their assets from memory, doing a fading transition, then initializing and firing up the new scene. With this in place the real-time game now behaves more like a Windows Form application, with dialogs able to call dialogs and just let the OS worry about sorting it all out.

The second key concept is the GUIStack. The GUI Stack sits inside the SceneManager and replicates “focus” of a scene just like how Windows does for forms and dialogs. By pushing and popping scenes onto the stack, I can control which scene has its Update() and Render() code called. If a scene doesn’t receive the Update() call, it is effectively frozen in time (paused). In pure form, the top scene is the only one to have its Update() called, while all in the stack have their Render() called. Later in testing I removed calling Render() to every scene in the stack for performance improvement. For scenes that require a background scene (such as a dialog window appearing over top of the game screen) I Instead take a screenshot of the current state, then display that as a backdrop to whatever the current scene is.

Using Marmalade in 2D
As previously mentioned, we were targeting both iPhone and Android simultaneously with C++ in Visual Studio 2008. While Marmalade is a 3D framework, we knew we were making a 2D title and therefore focused on the Iw2D APIs. I’ll highlight the fundamentals of 2D animation with Marmalade’s 2D API.

As you you’ll see, Marmalade works at a pretty low level. This isn’t GameSalad here, and that is one of the reasons I chose it. Given the choice, I prefer the flexibility and power of a low level API rather than being limited to what a framework designer decided I should be able to do (or not!).

Marmalade works it magic by using a custom make file called an MKB. This file allows the user to define Marmalade libraries to pull into the project, source code, assets (sounds), fonts, and texture groups.

Marmalade has a resource manager that allows the management of image groups (texture groups) by defining them like this in the MKB file:

# Provide access to resource objects via IDE
		  ["Resources"]
		  (data)		
		  fonts.group
		  templates.itx
		  UI.group
		  Loading.group
		  Title.group

You then define all your images in custom group files:

UI.GROUP
CIwResGroup
{
		  name "UI"  
		  shared true
		  useTemplate "image"	"image_template"
		
		  "./accountbuttons.png"
		  "./account1.png"
		  "./account2.png"
		  "./account3.png"
		  "./black.png"
		  "./bluestarbg.png"
		  "./pause.png"

Within the code you can test if resource groups are already loaded into memory, and then load/unload them through two simple function calls:

if (IwGetResManager()->GetGroupNamed("farm", IW_RES_PERMIT_NULL_F) != NULL)
IwGetResManager()->LoadGroup("farm.group");

Or:

 		 IwGetResManager()->DestroyGroup("farm");

Images are loaded (and automatically uploaded to OpenGL VRAM) by asking for the image by name (without the .png extension) by using:

CIw2DImage* img = Iw2DCreateImageResource(name);

Once you have an image in memory, it can be rendered simply by calling the image drawing routine with the image you want, and the 2D vector position.

Iw2DDrawImage(img, CIwSVec2(x,y));

Marmalade automatically queues up all of the drawing calls in the order in which you called them, so this way you can control layering by doing your background draw calls first. So before I would run through my Render() routine I would sort all my objects by depth (lowest to highest) and then draw them in that sequence.

To complete the rendering I call these two routines, which tells Marmalade I’m finished, show it to the world:

Iw2DFinishDrawing();
Iw2DSurfaceShow();

That’s it. Call those drawing routines each frame and you’ve got yourself a game.

Simplifying Sprite Sheets
The game comprises over 4,000 frames of hand drawn animation, most is for the monkeys interacting with their world. To manage all these images, we put them into spritesheets. Two issues needed to be considered:

No dimension of the sprite sheet could be larger than 1024 (iPhone doesn’t like textures bigger than this and Marmalade started fuzzing them)
Sprite sheet dimensions needed to be to the power of 2 (32,64,128,256,512,1024) for the graphics card. If they weren’t, the graphics card would pad them out to make them to the power of 2 anyway.

An example of a GameMaker strip.

Photoshop does not have an easy way to make a sprite sheet where each frame is universal in height/width. So we discovered a trick that saved us dozens of hours:

Save each frame in PNG from photoshop
Create a sprite in Game Maker to drag and drop each PNG frame from the file system for a given animation
Export the sprite from Game Maker as an animation strip, which is each frame appended into one long horizontal PNG with the number of frames appended to the file name.
Run our custom sprite sheet program on the strip, which would break it out into a rectangle of the smallest power of 2 dimension as a PNG.

While it sounds involved, we could go from a collection of png frames to a squared sprite sheet in under 2 minutes. Just for its ability to create sprite strips GameMaker is well worth having!

The final spritesheet, power of 2 sized.You can't tell, but we also dropped the color depth from 32bit to 16bit for memory.

Conclusion
Who is the harshest critic, the audience or the musician? The musician, for they have the double burden of knowing every note they missed and how much better they played during practice. So while the creator is extremely biased and forgiving of their creation, there is a harsh reality of what they intended and what they ended up making. I would say the music is always much sweeter in the imagination than on the page.

At the end of the 6 weeks I had finished building the core of the game. I came in around 340hrs. Knowing I have a personal biased, having played the game over a thousand times during build cycles, I concluded this game is actually fun. There was something magical about trying to entertain 3-5 monkeys simultaneously. Because I was away at the cottage, the artist had to take my word for it. And since I hadn’t yet figured out how to deploy it, he had no way to play it other than on my laptop. But, knowing we had a good core, something we were proud of, gave us the determination for the toughest fight yet: Polishing.

Balancing and Polishing

Intro
At this point we had a working game, around 90% feature complete. The player could start a new game, play each level, interact with all 7 monkeys, use all 10 tools, save up stars, buy 28 upgrades in the store, use all 4 star powers, and save/resume their game. We declared ourselves feature complete. If we had created a more detailed design document we would have realized how untrue that statement actually was!

The Last 10% takes 90% of the Time
We didn’t know how long it would take to establish a publisher relationship, so we started showing an early prototype to some publishing agents. One commented that the game core was good, we definitely have a quality AAA title here, but we still have a lot of work left for polishing. We thought that was a rather silly statement, and proceeded to finishing off the loose ends and game balance figuring we would be in the store in about 2 weeks.

This is where games are vastly different than business software. In business software, when we are feature complete with all unit testing completed, 80%-90% of the work really has been done. Integration testing reveals its issues, but they are generally just misunderstandings between developers and spec that need to be resolved. A real-time game integration testing is about 50% of the work because of the layered interactivity/dependencies of the game elements to each other.

Getting it on a Device
Up until this point, the game could only be played in the Marmalade PC simulator. We still had no idea if performance would be an issue (memory or FPS) on real devices. It also severely hampered unit testing as the artist couldn’t test the game at all. It was time to deploy to a device.

Marmalade Deployment Tool for making the IPA file

Apple is extremely careful of what can be put onto their devices. This is good as it cuts down on piracy, but it also creates a whole series of hoops you must jump through to sign your code and get device ids and certificates for deploying test builds to a device.

If you are using xCode on a mac (especially the latest version of xCode), it is a relatively straight forward process, where xCode takes care of most of it for you. All of apple’s documentation tells you step by step how to do it with xCode. If you are on PC, well prepare for some hassle.

There are two things you must do: 1) Setup your machine for iOS deployments and 2) Setup your project for iOS distribution. Fortunately, the documentation in Marmalade 5.2 for how to create distribution builds is much improved over previous versions. There is a walk through that explains you to create a certificate, which you then upload to Apple, and download the Apple certificate(s) and where to put them.

With the PC setup, the project must be setup and signed for distribution. The Apple dev portal is used to assign UDIDs of devices allowable to an application. Apple provides a provisioning certificate used to sign your project. Marmalade has a deployment tool that appears when making a release ARM build of the project. You enter in provisioning and OS specific options into this tool (it saves the settings to the custom MKB file) and it does the magic of making you an IPA that can be deployed through iTunes to your iOS device.

All in I was able to get the game on my iPod in about 10 hours. This was a vital step, because we needed the touch screen to test our gestures.

Getting Jiggy with Gestures
If you recall, our core design was a player using their finger to tickle a monkey through swiping. After some prototyping, we needed other tools to break up the monotony of constantly swiping back and forth. One of our early influences was a GameLoft game Bailout Wars. The player flicks bankers to their doom, but you also have to make other motions as well.

We studied numerous games and came up with this list:

Tap
Tap & hold
Swipe Horizontal
Swipe Down
Flick Up
Circle (clockwise or counter clockwise)

We chose Tap, Swipe Horizontal, Swipe Down, and Flick Up. (We also had Tap & Hold, but cut it later.) We tied these gestures to tools that we felt made sense: the paper bag, for instance, is placed on a monkey’s head, so the player swipes the bag down onto the head.

iOS and Android support multi-touch (up to 10 points) but we decided to stick to just single touch. A touch is nothing more than a click event, so we inspect the s3ePointerEvent in Marmalade to capture it into a global touch variable like this:

void SingleTouchButtonCB(s3ePointerEvent* event)
{
		g_Touches[0].active = event->m_Pressed != 0;
		g_Touches[0].x = event->m_x;
		g_Touches[0].y = event->m_y;
		g_Touches[0].when = (int32)s3eTimerGetMs();
		g_Touches[0].handled = false;
}

While it is all nice to know where a finger currently is, how do you know if they are making a gesture or not? The answer is you have to do that yourself.

A gesture begins when the finger touches the screen. From then on, the current position of that touch must be tracked at a regular interval until it is released (finger is lifted). The difference in origin, progression across the points, and exit must be analyzed to determine what kind of gesture was made. I used the Strategy Pattern in a generic Tool class with the child class for each tool implementing their own unique gesture recognition.

So while this explains the technical on how to do gestures, there was a lot of refinement necessary to get it to “feel” right. It is amazing how different each person performs a simple left/right swipe. Some people do very gentle little swipes of 10 pixels, while others go all the way across the screen. Some do it straight across, others on a diagonal. Some do it so slow it didn’t register, and some do it so fast it didn’t register (we found the “right” granularity for the timing interval of each point is 50ms). At the end of the day, we went from a very strict gesture system where a horizontal swipe couldn’t have more than 20 pixels of vertical movement, to a very loose one where just about anything goes!

Saving the Story To Last
Catch the Monkey is an action game. While we need some sort of story to set the context for the player’s actions, we knew we didn’t need Crime and Punishment here. From the very beginning, we had a rough story outline:

A farmer in South Africa has a potato farm. As he sits down to lunch with his wife, a monkey is spotted in the field. He goes outside to take care of the monkey, but more and more keep coming. Eventually he overcomes all the monkeys and returns to a cold lunch. Fin.

Ok, so we aren’t winning any Oscars for screenplay writing, but it was enough to get going so we focused on building the game and then would circle back to the story.

BIG MISTAKE!

When it came time to do the story sequences, I decided to involve my friend Rob for help. We sat down one evening to hash out the story. He started asking basic background questions for which I had no answer:

How well does the farmer do, is he poor or rich?
How’s his marriage, good or strained?
What’s his demeanor: happy or surly?
How long have they lived in this location?

This may seem like silly fluffy stuff, but it isn’t. I knew from research in how to write fiction that before you have a story, you have to have a character. It is the characters that drive the story and we didn’t have characters. So Rob and I had to define the characters first.

Throughout the game the player unlocks new tools. How are these communicated to the player? We decided it was by the farmer’s wife “finding” them and making them available to the farmer in his tool shed. We chose to use a dialog sequence to put the tool arrival into some context. Well, you cannot write effective dialog (even simple monkey catching dialog) without knowing the characters voice. So these “fluffy” questions had to be answered before we could write a single line of dialog.

We then had to answer the two big questions:

1) Why are the monkeys coming to the farm in the first place? (Why now and not a year ago, or why not a year from now?)
2) How is it that the player stops the monkeys from coming (by resolving #1)?

We went through a lot of ideas that night, but everything good we came up with changed the flow of the game, or introduced new characters (like a boss monkey), and we just couldn’t afford to do all those changes this late in the game development. It was overwhelmingly evident we should have had this meeting in the first week of the game, not the last.

Before you can write a line of dialog, you have to know the character's voice

We wrote the best story we could without changing the game or requiring a lot of new art assets. The first rule of writing is “write what you know”. In the end, I based the farmer and wife on myself and my wife. The problem the farmer faces of trying to get rid of the monkeys, which seems so simple from the beginning, becomes overwhelming and takes over his whole life. This is actually a metaphor for what the monkey game became to me. When the farmer bemoans the monkeys never ending, that’s how I felt about the amount of work the game kept requiring. But in the background, unfazed, is the wife. Helping where she can, encouraging when needed. Many of the lines in the game are verbatim what my wife said. When the farmer’s wife goes away on a girl’s trip in the middle of it all, this also happened in real life.

Of course, all this is probably far too sophisticated for a simple action monkey catching game, but it is in there none the less.

Levels and the Game Master
I’ll admit this up front: sometimes I’m just plain lazy. But sometimes laziness is the mother of invention.

When we built the second prototype each level had scripted events: when a monkey is to be released down a tree, the type of monkey, the size of a wave of monkeys at one time. Most of these events were time driven. This is how classic action games, like Capcom’s 1942, are made. Each play through is the same.

It was a lot of work scripting each level with all the events, and frankly I didn’t want to do it again in the real game. There are also problems with scripting: how do you know if the player is bored or sufficiently challenged? Releasing a monkey every 10 seconds may be fun for me, but too easy/hard for you.

So we tried to think of an alternative: what if we had a Game Master (to borrow the RPG term) that determines when, where, and type of monkey to release based on how well the player is doing. If a player is doing poorly it won’t become ridiculously intense, and if they are doing well it won’t get boring. We will define rules for the GM to behave by, and vary those rules from level to level. For instance, some levels the GM will be fast and furious, in others a slow build up. Even better, the GM can monitor things in real time, like the players energy level, and make smart decisions at the time of knowledge rather than guessing with scripting.

This seemed like a radical idea to us, so we weren’t sure what the negatives would be to building this dynamic AI “level designer” just so I didn’t have to do all that scripting.

I don’t remember why, but for some reason I felt I should play Valve’s Left for Dead FPS zombie game. I generally don’t like zombie shooters so I had never played it before. I got it off steam and noticed somewhere in the description about “The Director”, which is essentially a level AI that responds in real-time to the players to give different experiences each play through. Once I saw Valve did it, I knew we were on the right path!

If Valve did it, so can we!

It took a few days to build the Level GM, but once it was done it was a total win. No scripting required, all we had to do was define for the GM the resources it has (types of monkeys, total number of each monkey allowed at a time) and the level of intensity we want (earlier levels are easier than later ones).

In the book Andrew Rollings and Ernest Adams on Game Design (some of it is free on google ebooks) they explain how it is more fun to have waves of intensity followed by relief followed by intensity rather than constant intensity. Plants vs Zombies follows this formula perfectly by providing big waves of zombies followed by few zombies so you can rebuild. We implemented this concept by adding “moods” to the GM. Based on many factors, the GM will “go evil” on you and break the rules of intensity we set out. But at other times it will “go nice” and give you a chance to catch your breath.

We’ve detailed plenty of our mistakes in these articles, so we’re proud to say this is one where we nailed it! We’ll be using this approach in our future titles.

Game Balancing: Redeeming Features
Game balancing is tough stuff! There are no strict rules as to what makes something fun, especially in combinations. In the end we had to go with our personal play experience, and then test on others.

It took 6 weeks to make the core game, and another 10 weeks to balance it. As I look over my work logs, up until the last day we were changing cooldowns, upgrade costs, and energy costs. I could give many examples from our time of play balancing, but I believe the most valuable lesson I can share is how we took something that wasn’t good and made it great. This at the core is what the balancing phase entails. So here is the brief story of the Paper Bag:

In reading a book on fiction writing it stated every character thinks they are the hero of the story, so give them a chance to shine. Think of how in Lord of the Rings Sam, a tag along character for much of the story, gets to be the hero when he carries Mr. Frodo up Mount Doom. I think this applies to game features, in our case every tool should get to be the hero and legitimate chance of being a player’s favorite.

Each tool has its own purpose. Some are for taking out individual monkeys, some are for dealing with groups. Some are to prevent them from coming in, some are for dealing with them as they come in. Some require the player’s attention and dexterity, some are great because they don’t require any attention.

The paper bag is a high cost high impact tool that completely paralyzes one monkey (intended for a high threat monkey) for a long period of time. It also has an Area of Effect (AOE) which causes other monkeys to be distracted and laugh at the silly monkey stumbling around.

In the first iteration, once the bag was placed onto a monkey’s head it immediately made all monkeys in range laugh. Play testing revealed players preferring other tools over the bag. It’s not that it was bad, but it wasn’t good.

We played around with the cost, cool down, and range. At one point it made all the monkeys in the field laugh. But still the other tools were better.

Then we thought: what if instead of a onetime AOE effect it had a continual AOE? For the entire time the target monkey stumbled around any monkeys in range would be influenced. This changed the best time to use a paperbag from where a lot of monkeys are currently, to where a lot of monkeys WOULD BE. By making this AOE effect continuous we now had a very effective crowd control AOE tool while incapacitating one target monkey.

Now the paper bag is fantastic!

During game balancing some diamonds are in the rough. Some are rougher than others. It requires determination to cut into them to let the inner brilliance shine forth.

Features: Knowing when and how to say NO!
A game can be built forever. Should I even mention the obvious example of Duke Nukem Forever? When the goal is to create a rich enjoyable play experience, the temptation is to keep adding more and more features, because more = better, right?

Sometimes no. In our case we had to ship the game, not just for financial reasons but for psychological ones. After 2 years it is hard to keep up the enthusiasm. As we played and balanced, many ideas would come up. For instance:

We needed to add an easy (casual) mode for non-gamers or younger children
We needed a visual and audio warning to the player that they just lost a plant (seems obvious now, but it wasn’t added until the second last day)
We needed more sound effects
We changed the “level complete” requirement from reaching a certain number of monkeys, to reaching a certain number AND clearing the whole field

All of the above were implemented, but they were unscheduled tasks and our release date kept being pushed further and further out.

To decide what HAD to be done we asked ourselves these two simple questions:

1) Is the game broken without it? Meaning it is too hard to play, or doesn’t make sense to the average player, or boring/repetitive

2) Would we be embarrassed to release without it? Meaning it is obvious we cut a corner.

The second question may sound a little strange. Personal pride and brand reputation are at stake writing a game. If we tried our best and failed, that is ok. Sometimes that is life. But if we cut corners, therefore reducing chance of success, and we failed, that is just being lazy or foolish.

To reach our timeline some things had to give:

Cut a type of monkey
Cut two tools
We wanted level ranking and gamecenter integration, but we had to cut it

Watergun didn't make the cut. Maybe there will be a sequel we can put it into!

Finally, the hardest thing we had to do was what I’ll call “compress” the game. Our goal had always been to have 50 levels, each of about 3 minutes (earlier ones are shorter, later ones are longer) for 150 minutes of perfect play.

Upon play balancing we saw there were fun levels and not as fun levels. Fun levels generally had the player getting something new (a new tool, star power, monkey type). So we decided to compress the game by removing the low fun content; 13 levels. It hurt to see all that work go away. But in the end what the player now experiences is peak to peak fun with no valleys.

Conclusion
After spending twice as much time polishing the game as it took to build it, we had a game that was truly feature complete. It was fun, it flowed well, and we are proud of it. It takes some going, but once you hit the sweet spot mid way through the game it is a ton of fun. We were finally ready for testing with others.

Testing, Release, Marketing

Intro
We had a game! Hurray! It worked, it played well, it has a beginning, middle, and ending. We were ready to get the sucker out the door. But before release, we had to go through the final stage of development: testing. Wow, what an eye opener!

No one Knows How to Play Your Game, and They Don’t Care to Learn!
I submit I may be the strangest person alive.

I grew up in the 80’s and early 90’s. This is where many of my early gaming habits formed. Back then when I bought a new computer game, such as Civilization, Ultima, or Wing Commander, I would sit down and read the entire manual cover to cover before attempting to play the game. And this was when manuals were works of art: the civilization manual was over 100 pages and filled with fascinating sidebar historical facts. I continued this practice, though I’ve stopped now that the manuals are nothing more than epilepsy warnings and telling me where the square button is on my controller. (Fortunately board games still have amazing manuals, so I can enjoy those )

The good old days when games were hard and manuals were thicker than your arm!

Apparently no one else read manuals so the gaming industry moved away from them altogether. Players want to play, not learn how to play. I sort of knew this, I read about it in game design books, but I didn’t have the experiential knowledge of it. It quickly came.

At our pre-release party (unfortunately 3 months before the actual release, but who’s counting) we had several iOS devices with a 4 level demo version of Catch the Monkey installed on them for people to play. We watched people pick up the game and play it for the first time. We learned two things: people enjoyed playing with the monkeys, but they had no clue how to do it. So while they had fun, they were frustrated not knowing how to use the various tools.

It seems obvious as I write this, but we discovered our need for tutorials built into the game. All I can say is that when you work on something closely for 2 years you lose track of what is “intuitive” and what isn’t. Observe strangers and reality will come crashing in. So, we used our character dialog system to retrofit in a tutorial system.

First Iteration of Tutorials. Nobody reads em.

Weeks before release, we tested with a focus group of teenage girls (our demographic) to see how they enjoyed the game. I squirmed in my seat as I watched them tap “next, next, next” and completely bypass the tutorial to get on to the game. Once there, they didn’t know how to use certain features, started losing, and became frustrated.

Final version of tutorials. If you can't follow that, there's no helping you!!!

We learned valuable lessons as we went through three iterations of tutorials:

People assume they already know how to play your game. I can’t for the life of me figure out why they come with this belief, but they do. Work with it, not against it.
People don’t want to learn (because of the above), they want to play. So teach them one basic thing and set them off playing
When teaching, we observed the average player’s patience is two: Two screens of slides, two steps of interaction, two dialog boxes, then they don’t care anymore and want to skip forward
After playing, people want to learn. There is a correlation between how long they play and how interested they are in learning to play. In the first 2 minutes, they have 0% interest, at 5 minutes they have 10% interest, at 10 minutes they have 50% interest. You have to space your lessons appropriately
Remove all flowery “in character” text from the tutorial, they want to learn as quickly and efficiently as possible and could care less if a character starts each sentence with “”
They don’t want to read, they want to do. Make the tutorial visual and interactive
Pre-plan your tutorials into the main story/progression of the game. Don’t do what we did and try to retrofit it in, it was a lot of work after the fact

Testing with Testflight
As previously mentioned, iOS locks down the devices to which you can install a binary. This requires the unique UDID of each device, registering it through the apple portal, including the provisioning profile at compile time into the binary, and then copying a provisioning profile to the device through iTunes (which provides zero feedback if it was done successfully) and finally copying the binary to the device through iTunes. I can’t think of a process more antithetical to the apple “it just works” mantra. So, you can do all that OR you can use testflightapp.com.

Testflight for build distribution during testing; epic win!

With testflight, you send testers (family, friends, enemies) an email link and they go to it on their device. Testflight takes care of finding the device UDID, os version, make/model of device, and sending it to you the developer, installing the provisioning certificate. As a developer, all you need to do is register the device id to your binary. Now you can upload a build (with release notes) to testflight, and everyone you autohrize is sent an email a link to download it. It bypasses all the silly itunes file copying. Testflight’s reporting allows you to see who has what installed. Valuable when they start reporting problems as you can definitively say “Oh, that’s because you’re on a build that was so yesterday! That build was terrible! Install the NEW build, it’s wonderful.”

Testing with Non-Gamers
Would you rather know about an issue during development, or once it’s released? Of course during development!

Testing with people who play similar games as the one you are making is very helpful. You can be sure you are meeting your demographics’ demands and they can often make suggestions or give articulate feedback on issues as they have a frame of reference.

However, we found great value in testing with people who have never ever played an electronic game in their life. You know who I’m talking about: your mother-in-law whose only game experience is yahtzee on the dining room table; the friend who didn’t know brick breaker was pre-installed on his blackberry.

The official term is blackbox testing. These people can confirm if your tutorials work, but more importantly they do things you never in a million years would do. But make sure you watch them closely, they won’t be able to tell you what they did or did not do. Here is an example:

We finished our final bug free never crashes build Dec 15. Over the Christmas holidays I showed a non-gamer friend the finished game. Within 2 minutes of playing he crashed it.

How? He never once lifted his finger from the screen. If you recall from part 3 about our gesture system, it tracks the current finger position every 50ms. Well if the player never ever lifts their finger from the screen, it becomes one giant gesture of 2,400 points after 2 minutes (affecting performance). Even worse, the initial target object of the gesture may be destroyed while waiting for the gesture to finish, resulting in a NULL reference and therefore a crash.

It was relatively easy to replicate and fix once I saw what he did, but I have to admit I never imagined someone not lifting their finger!

How Do You Know When You are Done Testing?
This may seem like a silly question, especially coming from a business software background. In business software you would already have all your test cases written before hand (Right?) and execute them. When they all pass, you know you are good to release. Typically we would then get the customer to test the application in a pilot project, and that is the “real world” test. If it’s good, we release.

Well in games, it’s different. There is no “customer” to sign off and take responsibility that the application is good, you just have to decide at some point: it’s done.

Release too early, and the game will crash or misbehave for customers. Release too late, and you’ve squandered valuable effort that could have gone into another title.

I was listening to the MIT Open Courseware on Game Design and they asked this very question: how do you know testing is done?

Their answer: When you are out of time.

When you can't take another step forward, you might be done testing.

That seemed like a cheeky answer, but having now lived it, I agree. Now, of course, we made certain all features worked, it was as fun as we could make it, and it didn’t crash. (Of course now as I write this we’ve heard reports of a bug in one of our tutorials, oops!). The game will never be perfect, there is always more to add, more to test. There comes a point where you have to draw a line in the sand and ship it. For perfectionists, this is a very difficult thing to do. I am fortunate that I’m not working solo on this project, both the artist and I together were able to agree the game was ready to go out. That gave me confidence I wasn’t deluding myself or just fed up. J For those soloing it, I recommend you ask a friend to be your “quality control” and help give you the thumbs up for releasing.

Judging the Difficulty
I read in the book Level Up: Guide to Great Game Design that the game makers are the worst people for judging the difficulty. So, I knew this going in, but it is still difficult in practice. Obviously the first people that need to be happy are the ones making the game, that is your first quality control gate.

We also tested on young children (3, 8, and 9). Why? Because they’ll test for free all day long and they have nothing better to do. (And they are the artist’s children). We found that young kids love to play Catch the Monkey, but the mid game was too hard for them. So thinking this was a secondary market, we created an Easy mode that gives the player more energy and reduces the maximum number of monkeys in the field at a single time. The kids loved the easy mode and were able to finish the game, so we were happy.

Later, when doing focus group testing, two of the teenage girls couldn’t get past a certain level and were getting frustrated. We recommended they restart the game in easy mode. As soon as they started playing in easy mode they said “Oh wow, this is much more fun.”

At this point we had a dilemma: do we make easy mode normal mode, and normal mode hard mode? We did and made all the code changes to reflect this.

Then, a few days later, we fixed a bug in the Level GM AI and found it was working much better than previously. So we flipped it all back to Easy and Normal rather than Normal and Hard.

Big mistake.

Now that we have released and friends/family have been buying it, the most common complaint we hear from casual gamers is that it is too hard. When we tell them through facebook to try it on easy mode, they always come back with “Oh wow, this is much more fun.” Even post release we’re still learning things the hard way!

Here are the key lessons we’ve learned:

Make the game too easy, rather than too hard. Too easy can still be enjoyable, too hard never is.
Casual gamers are not looking for a challenge, they are looking to pass the time. Easy fits within this expectation.
Don’t make the game hard with the ability for the player to opt into easy. Make it easy with the ability to opt into hard.

Releasing to the App Store
After making it through the arduous testing phase, we were ready to release this sucker. This has several steps:

1) Making a build signed for App Store, as opposed to ad-hoc provisioning build

2) Uploading the binary to Apple

3) Waiting for approval

It was time to fire up Visual Studio one last time and create an app store build. It was relatively easy to do, I simply copied the deployment options from my test flight build in Marmalade and off I went. Now here’s the thing: you cannot test your app store build before you upload it. Why? Because it can only be installed on a device through the app store. So better get it right!

And we didn’t.

iTunes Connect is how you control your app in the app store

I made two blunders when doing the final build. The first was somehow I didn’t copy the proper icon image settings from the internal build to the final build, so it went to the app store with the default app icon. Doh! The second was far, far worse.

We knew our game didn’t work on anything below iPhone 3GS or iPod 3. I saw other games show this requirement in the app store along the left column. I didn’t see any way to set this through marmalade deployment, so I assumed it was done in the app store itself.

Well when you upload an app, especially your first, iTunes Connect walks you through a wizard. The answers you provide can never be changed, you got one shot to do it right. These we did right. Again, I didn’t see anywhere I could set the requirements, so I figured it was after I uploaded the binary. I uploaded the binary and it went into the queue for review and approval.

Well, 8 days later, it was approved. But still no way to set the system requirements. It wasn’t until later that I found out you need to modify the plist.info file to include the OpenGL ES version to 2.0 to target the devices we wanted.

No biggie, I modified the plist.info file and proceeded to upload the new binary.
ERROR!

Apple does not allow a developer to set more narrow restrictions on an application update than the app first had. So in short: if your initial version says it will run on iPod 2, you can’t later do an update that makes it no longer run on iPod 2. We screwed up the one thing you cannot correct through an app update. After much back and forth with apple support we had to resort to putting the requirement right into the app description. We already know people don’t read, but it’s the best we can do at this point.

And one final thing to know about releasing to the app store when you make your app on a PC: you REQUIRE a mac to upload the binary to apple.

ITunes Connect used to allow you to upload through http, but no longer. There is a binary uploader program in the iOS SDK that checks and uploads your binary to apple. That uploader program only works on a mac. So while you can build and test the entire app on a PC, you need a mac for 10 minutes to upload your final binary. I’ve seen someone suggest just going to an apple store and using a demo mac to upload. In my case I already had the mac mini, so it wasn’t terribly inconvenient, but it was a real surprise.

Releasing to the World
By default, all apps uploaded to apple are released to every itunes store in the world, unless you specifically turn a store off.

There be a lot of iTunes Stores. Fortunately you only need 6 translations to cover them all.

We had always intended to release to multiple countries, so we tried to minimize the amount of text in game and use symbols where we could (the monkey story sequences use icons rather than text for this reason, although it actually made more sense conceptually too: how do you write “monkey speak” anyway?!).

The key is to get your app description translated from your native language into the various app store languages. It costs about $100 per language to use a translation service to translate our app description. Of course, the difficulty is we have no way to judge how good the translation is!

Initial Marketing
As I write this fourth part, our game has been out in the world for 22 days. Sales haven’t skyrocketed, so we’re in no position to advise on how to market a game. However, there are two things we can share.

First, Apple controls the app store. They make their decisions based on volume. The sections like “What’s Hot” and “New and Noteworthy” are driven by volume. The more volume you can drive in the initial days, the more likely you are to appear in those sections. Obviously the key is to get into the “Top 100 Free” or “Top 100 Paid”. The only way you get there is through volume.

We've made it to #45 in the Family What's Hot. Go little monkey! Go!

Secondly, we knew review sites are important to get initial buzz going, but how do you find all the review sites out there? A google search will return some of the biggies, but also blogs that haven’t been updated in 2 years. So we devised a clever way to make a short list of review sites: most games put their reviews or quotes from review sites in the top part of their app description. By clicking through about 20 apps we were able to compile a list of 41 respectable mobile game review sites.

Most if not all review sites work from a backlog of about 3-4 weeks. And they all want a promo code to get the game for free, they won’t pay money for your app. Apple allows you 50 promo codes per release. Once you make a new release, the unused promo codes are invalidated.

In the 3 weeks we’ve been waiting, we’ve had 1 review come back. Fortunately it was a good one.

For our next title we’ll be doing more on the pre-release marketing side to get the game buzz out before release. As we were taking so long on Catch the Monkey and we didn’t really know if or when we would be done, we had to forgo pre-release marketing.

Conclusion
Well, there you have it: a summary of our ups and downs over roughly 2 years trying to make an iphone game.

We set a goal, and despite great difficulties, achieved it. Beyond this, three things have brought great satisfaction:

1. Our first review came in:

We received 4/5 stars and an editor’s choice award from the family mobile gaming site famigo.com. It’s nice to know someone objective thinks what we made is good!

2. A review someone wrote on the US store:
How fun can catching monkeys be? Hours of fun! I love this game because it's something for my kids to do that's different from princess games and phonics—and it’s something that I can do when I’m commuting, waiting for my next appointment, or just to relax. This has got to be one of the best non-violent games I’ve ever seen. Great graphics, good story, and entertaining for everyone.

3. The popularity of these articles.
When we first set out to talk about our experience, we didn’t know who would be interested. Over 3,000 reads and counting on the first article makes all this writing effort worthwhile! Thanks!

What’s next for Mirthwerx?
We’re currently working on a few things:

Playbook version (taking full advantage of having used Marmalade)
Android version (dido)
Free version (different from a lite version, it’s a different but similar game)
And our second title which is a puzzle game for the masses (remember, turn based!)

I’ve enjoyed writing these articles, I hope they’ve been of benefit. I have some ideas for maybe doing an “encore” 5^th article next week, but I’d be looking for questions or comments from people before I decide to do it.

Until next we meet,
Lord Yabo

3D Animation Techniques with XNA Game Studio 4.0

Thu, 23 Feb 2012 20:34:11 +0000

In this article, we will look at several ways to make the objects in our scene move. First, we will look at the animation of objects as a whole. We will do this through simple linear interpolation between start and end values, and through a more complex curve interpolation. We will also look at more complex animations through keyframed animation.

This article by Sean James, author of 3D Graphics with XNA Game Studio 4.0, covers:

Object animation
Keyframed animation
Curve interpolation

Object animation
We will first look at the animation of objects as a whole. The most common ways to animate an object are rotation and translation (movement). We will begin by creating a class that will interpolate a position and rotation value between two extremes over a given amount of time. We could also have it interpolate between two scaling values, but it is very uncommon for an object to change size in a smooth manner during gameplay, so we will leave it out for simplicity's sake.

The ObjectAnimation class has a number of parameters—starting and ending position and rotation values, a duration to interpolate during those values, and a Boolean indicating whether or not the animation should loop or just remain at the end value after the duration has passed:

public class ObjectAnimation
{
  Vector3 startPosition, endPosition, startRotation, endRotation;
  TimeSpan duration;
  bool loop;
}

We will also store the amount of time that has elapsed since the animation began, and the current position and rotation values:

TimeSpan elapsedTime = TimeSpan.FromSeconds(0);

public Vector3 Position { get; private set; }
public Vector3 Rotation { get; private set; }

The constructor will initialize these values:

public ObjectAnimation(Vector3 StartPosition, Vector3 EndPosition,
  Vector3 StartRotation, Vector3 EndRotation, TimeSpan Duration,
  bool Loop)
{
  this.startPosition = StartPosition;
  this.endPosition = EndPosition;
  this.startRotation = StartRotation;
  this.endRotation = EndRotation;
  this.duration = Duration;
  this.loop = Loop;
  Position = startPosition;
  Rotation = startRotation;
}

Finally, the Update() function takes the amount of time that has elapsed since the last update and updates the position and rotation values accordingly:

public void Update(TimeSpan Elapsed)
{
  // Update the time
  this.elapsedTime += Elapsed;

  // Determine how far along the duration value we are (0 to 1)
  float amt = (float)elapsedTime.TotalSeconds / (float)duration.
TotalSeconds;

  if (loop)
	 while (amt > 1) // Wrap the time if we are looping
		   amt -= 1;
  else // Clamp to the end value if we are not
	 amt = MathHelper.Clamp(amt, 0, 1);

  // Update the current position and rotation
  Position = Vector3.Lerp(startPosition, endPosition, amt);
  Rotation = Vector3.Lerp(startRotation, endRotation, amt);
}

As a simple example, we'll create an animation (in the Game1 class) that rotates our spaceship in a circle over a few seconds:

We'll also have it move the model up and down for demonstration's sake:

ObjectAnimation anim;

We initialize it in the constructor:

models.Add(new CModel(Content.Load("ship"),
  Vector3.Zero, Vector3.Zero, new Vector3(0.25f), GraphicsDevice));

anim = new ObjectAnimation(new Vector3(0, -150, 0),
	   new Vector3(0, 150, 0),
	   Vector3.Zero, new Vector3(0, -MathHelper.TwoPi, 0),
	   TimeSpan.FromSeconds(10), true);

We update it as follows:

anim.Update(gameTime.ElapsedGameTime);

models[0].Position = anim.Position;
models[0].Rotation = anim.Rotation;

Keyframed animation
Our ObjectAnimation class allows us to create simple linear animations, but we can't create anything more complex. For example, we can't make our spaceship move in a circle with this class. To achieve more complex animations, we will use what is called keyframed animation. In this method, we specify "key" frames where we want the object to be in a specific position and orientation. We then rely on the code to interpolate between those values to fill in the frames between the key frames.

The following screenshot shows our spaceship at the keyframed positions along a path, and the black line shows the path that would be taken by interpolating between keyframes:

Keyframed animation is useful because it is a fast way to create somewhat complex animations without having to animate each frame. For example, birds flying through the air, soldiers on patrol, or even a camera flying through a scene, can all be animated through keyframes. This is probably the easiest way to move the camera during a cutscene, for example. We represent a key frame with the ObjectAnimationFrame class. Like the previous class, it contains position and rotation values. It also, however, contains a time value, marking this frame's time offset from the beginning of the animation.

public class ObjectAnimationFrame
{
  public Vector3 Position { get; private set; }
  public Vector3 Rotation { get; private set; }
  public TimeSpan Time { get; private set; }

  public ObjectAnimationFrame(Vector3 Position, Vector3 Rotation,
   TimeSpan Time)
  {
	this.Position = Position;
	this.Rotation = Rotation;
	this.Time = Time;
  }
}

We can now create a new animation class that uses key frames:

public class KeyframedObjectAnimation
{
List frames = new List();
bool loop;
TimeSpan elapsedTime = TimeSpan.FromSeconds(0);

public Vector3 Position { get; private set; }
public Vector3 Rotation { get; private set; }

public KeyframedObjectAnimation(List Frames,
  bool Loop)
{
  this.frames = Frames;
   this.loop = Loop;
  Position = Frames[0].Position;
  Rotation = Frames[0].Rotation;
}
}

Finally, the Update() function fï»¿igures out which frame we are on and interpolates between its values and the next frame's values, based on how far between them we are:

public void Update(TimeSpan Elapsed)
{
  // Update the time
  this.elapsedTime += Elapsed;

  TimeSpan totalTime = elapsedTime;
  TimeSpan end = frames[frames.Count - 1].Time;

  if (loop) // Loop around the total time if necessary
	while (totalTime > end)
	   totalTime -= end;
  else // Otherwise, clamp to the end values
  {
	Position = frames[frames.Count - 1].Position;
	Rotation = frames[frames.Count - 1].Rotation;
	return;
  }

  int i = 0;
  // Find the index of the current frame
  while(frames[i + 1].Time	  i++;
  // Find the time since the beginning of this frame
  totalTime -= frames[i].Time;

  // Find how far we are between the current and next frame (0 to 1)
  float amt = (float)((totalTime.TotalSeconds) /
	 (frames[i + 1].Time - frames[i].Time).TotalSeconds);

  // Interpolate position and rotation values between frames
  Position = Vector3.Lerp(frames[i].Position, frames[i + 1].Position,
   amt);
  Rotation = Vector3.Lerp(frames[i].Rotation, frames[i + 1].Rotation,
   amt);
}

For example, we can now create a new animation to move our spaceship in a square:

KeyframedObjectAnimation anim;

We set it up as follows:

List frames = new List();

frames.Add(new ObjectAnimationFrame(new Vector3(-1000, 100, -1000),
  new Vector3(0, MathHelper.ToRadians(-90), 0),
  TimeSpan.FromSeconds(0)));
frames.Add(new ObjectAnimationFrame(new Vector3(1000, 100, -1000),
  new Vector3(0, MathHelper.ToRadians(-90), 0),
  TimeSpan.FromSeconds(3)));
frames.Add(new ObjectAnimationFrame(new Vector3(1000, 100, -1000),
  new Vector3(0, MathHelper.ToRadians(-180), 0),
  TimeSpan.FromSeconds(6)));
frames.Add(new ObjectAnimationFrame(new Vector3(1000, 100, 1000),
  new Vector3(0, MathHelper.ToRadians(-180), 0),
  TimeSpan.FromSeconds(9)));
frames.Add(new ObjectAnimationFrame(new Vector3(1000, 100, 1000),
  new Vector3(0, MathHelper.ToRadians(-270), 0),
  TimeSpan.FromSeconds(12)));
frames.Add(new ObjectAnimationFrame(new Vector3(-1000, 100, 1000),
  new Vector3(0, MathHelper.ToRadians(-270), 0),
  TimeSpan.FromSeconds(15)));
frames.Add(new ObjectAnimationFrame(new Vector3(-1000, 100, 1000),
  new Vector3(0, MathHelper.ToRadians(-360), 0),
  TimeSpan.FromSeconds(18)));
frames.Add(new ObjectAnimationFrame(new Vector3(-1000, 100, -1000),
  new Vector3(0, MathHelper.ToRadians(-360), 0),
  TimeSpan.FromSeconds(21)));
frames.Add(new ObjectAnimationFrame(new Vector3(-1000, 100, -1000),
  new Vector3(0, MathHelper.ToRadians(-450), 0),
  TimeSpan.FromSeconds(24)));

anim = new KeyframedObjectAnimation(frames, true);

The Update code remains the same. Running the game, you will see the spaceship move from corner to corner of a box, turning towards the next corner at each stop.

Curve interpolation
We now have the ability to make animations with multiple key frames, which allows us to create more complex animations. However, we are still interpolating linearly between those key frames. This looks good for rotations, for example, but it would not look good for an object following a path, as the object would abruptly change direction after reaching a key frame in its animation. Instead, we want to be able to have our objects follow a smooth curve through the positions defined in the key frames. We will do this with what is called Catmull-Rom interpolation. This is a process that will create a curve through our key frame positions, allowing for much smoother object animation:

Let's modify the KeyframedObjectAnimation class to use Catmull-Rom interpolation for the position value. XNA has a built-in function to calculate an interpolated position between the second and third points in a set of four points using Catmull-rom interpolation. However, it works only in one dimension, so we'll need to create a function that will interpolate between a set of instances of Vector3:

Vector3 catmullRom3D(Vector3 v1, Vector3 v2, Vector3 v3,
Vector3 v4, float amt)
{
return new Vector3(
  MathHelper.CatmullRom(v1.X, v2.X, v3.X, v4.X, amt),
  MathHelper.CatmullRom(v1.Y, v2.Y, v3.Y, v4.Y, amt),
  MathHelper.CatmullRom(v1.Z, v2.Z, v3.Z, v4.Z, amt));
}

The amt argument specifies how far (0 to 1) between the second and third vectors the new position should be. We can now modify the position calculation to use this new function:

// Interpolate position and rotation values between frames
Position = catmullRom3D(frames[wrap(i - 1, frames.Count - 1)].
Position,
  frames[wrap(i, frames.Count - 1)].Position,
  frames[wrap(i + 1, frames.Count - 1)].Position,
  frames[wrap(i + 2, frames.Count - 1)].Position, amt);

The wrap() function wraps the value that it is given around a certain interval—in this case [0, frames.Count – 1]. This means that we will not have to worry about our indices going out of range when finding the last point, next point, and so on, but it does mean that this type of interpolation will work best with a closed curve—a circle, for example:

// Wraps the "value" argument around [0, max]
int wrap(int value, int max)
{
  while (value > max)
	value -= max;

  while (value	 value += max;
  return value;
}

We could now create the following keyframed animation with a curved path to demonstrate our new interpolation method:

List frames = new List();

frames.Add(new ObjectAnimationFrame(new Vector3(-500, 100, 1000),
  new Vector3(0, MathHelper.ToRadians(0), 0),
  TimeSpan.FromSeconds(0)));
frames.Add(new ObjectAnimationFrame(new Vector3(500, 100, 500),
  new Vector3(0, MathHelper.ToRadians(0), 0),
  TimeSpan.FromSeconds(3)));
frames.Add(new ObjectAnimationFrame(new Vector3(-500, 100, 0),
  new Vector3(0, MathHelper.ToRadians(0), 0),
  TimeSpan.FromSeconds(6)));
frames.Add(new ObjectAnimationFrame(new Vector3(500, 100, -500),
  new Vector3(0, MathHelper.ToRadians(0), 0),
  TimeSpan.FromSeconds(9)));
frames.Add(new ObjectAnimationFrame(new Vector3(-500, 100, -1000),
  new Vector3(0, MathHelper.ToRadians(180), 0),
  TimeSpan.FromSeconds(12)));
frames.Add(new ObjectAnimationFrame(new Vector3(-500, 100, 1000),
  new Vector3(0, MathHelper.ToRadians(180), 0),
  TimeSpan.FromSeconds(15)));
frames.Add(new ObjectAnimationFrame(new Vector3(-500, 100, 1000),
  new Vector3(0, MathHelper.ToRadians(360), 0),
  TimeSpan.FromSeconds(18)));

anim = new KeyframedObjectAnimation(frames, true);

Summary
In this article we have covered the following concepts:

Object animation
Keyframed animation
Curve interpolation

Producer Consumer Using Double Queues

Wed, 22 Feb 2012 15:11:21 +0000

Download source - 4.02 KB

License: Zlib

Introduction

Producer consumer is an old computer science problem. Many solutions have been proposed to solve this problem. The general approach is using a common queue. A single queue to which the producer writes data to and the consumer reads data from. Avoiding race conditions is done by locking the queue so that when the producer is writing, the consumer is not reading and vice versa.

The problem with this approach is that whenever the producer puts data to the queue, it has to acquire a lock. Similarly whenever the consumer gets data, it has to lock the queue. This solution is inadequate on systems where the producer generates data in excess of a hundred thousand updates per second. In my opinion, a hundred thousand locks on the queue in one second is a huge performance penalty.

Background

Once while going over this conundrum with my better half, I was introduced to the concept of double queuing. Something similar to the double buffering used in graphics applications to avoid flicker. As far as my research goes, I was not able to find a similar solution to the producer consumer problem. In case this is duplication, my apologies. I would be indebted if you can point me to the original work.

Double Queuing

The solution proposed is very simple and elegant. Instead of using a single queue, we use two queues. At a given time, one queue is designated write queue and the other, the read queue. This helps us to avoid locking the queue while reading and writing to it. The producer is free to fill the write queue and the consumer is free to empty the read queue.

When the consumer is done reading the read queue, the producer is blocked briefly and the queues are switched. Now the old read queue becomes the new write queue and the old write queue becomes the new read queue. After switching, if there is no data in the new read queue, the consumer is blocked. When the producer gets more data, it unblocks the consumer.

The Code

This solution makes use of Events for synchronization between the consumer and the producer. The producer code looks like this:



public void ProducerFunc()
{
	int data = 0;

	for (int i = 0; i < 10000; i++)
	{
		data += 1;
		MessageHandler(data);
		Thread.Sleep(m_Random.Next(0, 2));
	}
}

private void MessageHandler(int data)
{
	m_UnblockHandlerEvent.WaitOne();
	m_HandlerFinishedEvent.Reset();

	m_CurrentWriteQueue.Enqueue(data);
	m_ProducerData.WriteLine(data); // logging

	m_DataAvailableEvent.Set();
	m_HandlerFinishedEvent.Set();
}

The ProducerFunc() is a thread function that is invoked 10,000 times. Every time MessageHandler() is called, it checks to see if it has been blocked by the consumer. If not, it resets the ManualResetEvent to indicate to the consumer that the producer has not yet finished. This is useful when the consumer is trying to switch the queues and wants to know if the producer is finished writing to the queue. The rest of the code is straight forward. Data is written to queue and an event is set to wake up the consumer incase it was blocked. Finally, an event is set to indicate that the producer is finished writing to queue.

This is the consumer code:



public void ConsumerFunc()
{
	int count;
	int data;
	Queue readQueue;

	while (true)
	{
		m_DataAvailableEvent.WaitOne();

		m_UnblockHandlerEvent.Reset(); // block the producer
		m_HandlerFinishedEvent.WaitOne(); // wait for the producer to finish
		readQueue = m_CurrentWriteQueue;
		// switch the write queue
		m_CurrentWriteQueue = (m_CurrentWriteQueue == m_Q1) ? m_Q2 : m_Q1;
		m_UnblockHandlerEvent.Set(); // unblock the producer

		count = ;
		while (readQueue.Count > )
		{
			count += 1;

			data = readQueue.Dequeue();
			m_ConsumerData.WriteLine(data); // logging

			Thread.Sleep(m_Random.Next(0, 2));
		}
		Console.WriteLine("Removed {0} items from queue: {1}",
					count, readQueue.GetHashCode());
	}
}

The ConsumerFunc() is a separate thread function. When the function starts, it checks to see if the data present event has been set. If not, then it is blocked till we get data written by the producer. Once data is present in the queue, the consumer resets the event to block the producer and waits for the producer to finish. The current write queue is now cached for reading and the current write queue is switched. After the queue is switched, the producer is unblocked to enable it to start writing to the new write queue. Meanwhile the consumer is busy reading from the read queue. Once the queue is empty, the entire process is repeated.

Points of Interest

On further discussing this solution with others, I was told using synchronization events causes more performance problems than using lock. What do you think about that argument? Can you shed some light on this from your experiences with lock and synchronization events?

About the Author

Nothing to brag about! Just another passionate software developer!

Work to make a living, don't live to work!

License

This article was authored by Ram Mohan Raja and reproduced for the benefit of our viewers under the terms of the Zlib license.

Introducing Xcode Tools for iPhone Development

Wed, 22 Feb 2012 03:36:41 +0000

In this article by Steven F. Daniel, author of Xcode 4 iPhone Development , we shall:

Learn about the features and components of the Xcode development tools.
Lean about Xcode, Cocoa, Cocoa-Touch, and Objective-C.
Take a look into each of the iOS Technology Layers and their Components.
Take a look into what comprises the Xcode Developer set of Tools.
Take a look at the new features within the iOS4 SDK.

There is a lot of fun stuff to cover, so let's get started.

Development using the Xcode Tools
If you are running Mac OSX 10.5, chances are your machine is already running Xcode. These are located within the /Developer/Applications folder. Apple also makes this freely available through the Apple Developer Connection at http://developer.apple.com/.

The iPhone SDK includes a suite of development tools to assist you with your development of your iPhone, and other iOS device applications. We describe these in the following table.

iPhone SDK Core Components This is the main Integrated Development Environment (IDE) that enables you to manage, edit, and debug your projects. This enables you to develop web-based iPhone and iPad applications, and Dashboard widgets. The iPhone Simulator is a Cocoa-based application, which provides a software simulator to simulate an iPhone or iPad on your Mac OSX. These are the Analysis tools, which help you optimize your applications and monitor for memory leaks in real-time.

The Xcode tools require an Intel-based Mac running Mac OS X version 10.6.4 or later in order to function correctly.

Inside Xcode, Cocoa, and Objective-C
Xcode 4 is a complete toolset for building Mac OSX (Cocoa-Based) and iOS applications. The new single-windowed development interface has been redesigned to be a lot easier and even more helpful to use than it has been in previous releases. It can now also identify mistakes in both syntax and logical errors, and will even fix your code for you.

It provides you with the tools to enable you to speed up your development process, therefore becoming more productive. It also takes care of the deployment of both your Mac OSX and iOS applications.

The Integrated Development Interface (IDE) allows you to do the following:

Create and manage projects, including specifying platforms, target requirements, dependencies, and build configurations.
Supports Syntax Colouring and automatic indenting of code.
Enables you to navigate and search through the components of a project, including header files and documentation.
Enables you to Build and Run your project.
Enables you to debug your project locally, run within the iOS simulator, or remotely, within a graphical source-level debugger.

Xcode incorporates many new features and improvements, apart from the redesigned user interface; it features a new and improved LLVM (Low Level Virtual Machine) debugger, which has been supercharged to run 3 times faster and 2.5 times more efficient.

This new compiler is the next generation compiler technology designed for high-performance projects and completely supports C, Objective-c, and now C++. It is also incorporated into the Xcode IDE and compiles twice as fast and quickly as GCC and your applications will run faster.

The following list includes the many improvements made to this release.

The interface has been completely redesigned and features a single-window integrated development interface.
Interface Builder has now been fully integrated within the Xcode development IDE.
Code Assistant opens in a second window that shows you the file that you are working on, and can automatically find and open the corresponding header file(s).
Fix-it checks the syntax of your code and validates symbol names as you type. It will even highlight any errors that it finds and will even fix them for you.
The new Version Editor works with GIT (Free Open-Source) version control software or Subversion. This will show you the files entire SCM (software configuration management) history and will even compare any two versions of the file.
The new LLVM 2.0 compiler includes full support for C, Objective-C, and C++
The LLDB debugger has now been improved to be even faster, it uses less memory than the GDB debugging engine.
The new Xcode 4 development IDE now lets you work on several interdependent projects within the same window. It automatically determines its dependencies so that it builds the projects in the right order.

Xcode allows you to customize an unlimited number of build and debugging tools, and executable packaging. It supports several source-code management tools, namely, CVS "Version control software which is an important component of the Source Configuration Management (SCM)" and Subversion, which allows you to add files to a repository, commit changes, get updated versions and compare versions using the Version Editor tool.

The iPhone Simulator
The iPhone Simulator is a very useful tool that enables you to test your applications without using your actual device, whether this being your iPhone or any other iOS device. You do not need to launch this application manually, as this is done when you Build and run your application within the Xcode Integrated Development Environment (IDE). Xcode installs your application on the iPhone Simulator for you automatically.

The iPhone Simulator also has the capability of simulating different versions of the iPhone OS, and this can become extremely useful if your application needs to be installed on different iOS platforms, as well as testing and debugging errors reported in your application when run under different versions of the iOS.

While the iPhone Simulator acts as a good test bed for your applications, it is recommended to test your application on the actual device, rather than relying on the iPhone Simulator for testing. The iPhone Simulator can be found at the following location /Developer/Platforms/iPhoneSimulator.Platform/Developer/Applications.

Layers of the iOS Architecture
According to Apple, they describe the set of frameworks and technologies that are currently implemented within the iOS operating system as a series of layers. Each of these layers is made up of a variety of different frameworks that can be used and incorporated into your applications.

Layers of the iOS Architecture

We shall now go into detail and explain each of the different layers of the iOS Architecture; this will give you a better understanding of what is covered within each of the Core layers.

The Core OS Layer
This is the bottom layer of the hierarchy and is responsible for the foundation of the Operating system, which the other layers sit on top of. This important layer is in charge of managing memory - allocating and releasing of memory once it has finished with it, taking care of file system tasks, handles networking, and other Operating System tasks. It also interacts directly with the hardware.

The Core OS Layer consists of the following components:

The Core Services Layer
The Core Services layer provides an abstraction over the services provided in the Core OS layer. It provides fundamental access to the iPhone OS services. The Core Services Layer consists of the following components:

The Media Layer
The Media Layer provides Multimedia services that you can use within your iPhone, and other iOS devices. The Media Layer is made up of the following components:

The Cocoa-Touch Layer
The Cocoa-Touch layer provides an abstraction layer to expose the various libraries for programming the iPhone, and other IOS devices. You probably can understand why Cocoa-Touch is located at the top of the hierarchy due to its support for Multi-Touch capabilities. The Cocoa-Touch Layer is made up of the following components:

Understanding Cocoa, the language of the Mac
Cocoa is defined as the development framework used for the development of most native Mac OSX applications. A good example of a Cocoa related application is Mail or Text Edit.

This framework consists of a collection of shared object code libraries known as the Cocoa frameworks. It consists of a runtime system and a development environment. These set of frameworks provide you with a consistent and optimized set of prebuilt code modules that will speed up your development process.

Cocoa provides you with a rich-layer of functionality, as well as a comprehensive object-oriented like structure and APIs on which you can build your applications. Cocoa uses the Model-View-Controller (MVC) design pattern.

What are Design Patterns?
Design Patterns represent and handle specific solutions to problems that arise when developing software within a particular context. These can be either a description or a template, on how to go about to solve a problem in a variety of different situations.

What is the difference between Cocoa and Cocoa-Touch?
Cocoa-Touch is the programming language framework that drives user interaction on iOS. It consists and uses technology derived from the cocoa framework and was redesigned to handle multi-touch capabilities. The power of the iPhone and its User Interface are available to developers throughout the Cocoa-Touch frameworks.

Cocoa-Touch is built upon the Model-View-Controller structure; it provides a solid stable foundation for creating mind blowing applications. Using the Interface builder developer tool, developers will find it both very easy and fun to use the new drag-and-drop method when designing their next great masterpiece application on iOS.

The Model-View-Controller
The Model-View-Controller (or MVC) comprises a logical way of dividing up the code that makes up the GUI (Graphical User Interface) of an application. Object-Oriented applications like Java and .Net have adopted the MVC design pattern.

The MVC model comprises three distinctive categories:Model : This part defines your application's underlying data engine. It is responsible for maintaining the integrity of that data.

View : This part defines the user interface for your application and has no explicit knowledge of the origin of data displayed in that interface. It is made up of Windows, controls, and other elements that the user can see and interact with.
Controller : This part acts as a bridge between the model and view and facilitates updates between them. It binds the Model and View together and the application logic decides how to handle the user's inputs.

What is Object-Oriented Programming?
Object-Oriented programming (or formally known as "OOP"), provides an abstraction layer of the data on which you operate, it provides a concrete foundation between the data and the operations you perform with the data, in effect giving the data behavior.

By using the power of Object-Oriented programming, it allows us to create classes and later extend its characteristics to incorporate additional functionality. Objects within a class can be protected to prevent those elements being exposed; this is called "Data Hiding".

If you are interested in learning more about Object-Oriented Programming, please consult the Apple Developer documentation or via the following link https://developer.ap...cles/ooOOP.html.

What is Objective-C?
When I first started to develop for the iPhone, I realised that I needed to learn Objective-C, as this is the development language for Mac and iOS. I found it to be one of the strangest looking languages I had ever come across. Today, I really enjoy developing and working with it, so will you too.

Objective-C is an object-oriented programming language used by Apple primarily for programming Mac OSX, iPhone, and other iOS applications. It is an extension of the C-Programming Language. If you have not done any OOP programming before, I would seriously recommend that you read the OOP document from the Apple Developer website.

On the other hand, if you have used and are familiar with C, .Net or Java, learning Objective-C should be relatively easy for you to understand.

Objective-C consists of two types of files:

.h : These types of files are called 'Header' or 'Interface files'
.m: These types of files are those which contain your program code logic and make use of the 'Header' files. These are also referred to as 'implementation' files.

Most Object-Oriented development environments consist of several parts:

An Object-Oriented programming language.
An extensive library consisting of objects.
A development suite of developer tools.
A runtime environment.

For example, here is a piece of code written in Objective-C


-(int)method:(int)i {
	return [self square_root: i];
}

If we were to compare this same code to how it would be written within C, it would look like this:


int function(int i) {
	return square_root(i);
}

Let's investigate the code
Now, let's examine the code line by line to understand what is happening.


-(int)method:(int)i {

We declare a function called method and a variable i, which is passed in as a parameter. We then pass the value to a function called square_root to calculate the value and the calculated result is returned.


return [self square_root: i];

Directives
In C/C++, we use directives to include any other header files that our application will need to access, this is done by using #include. In Objective-C, we use the #import directive. If you observe the content of the MyClass.h file, you will notice that at the top of the file is a #import statement.


#import
@Interface myClass : NSObject{
}
@end

The #import statement is known as a "pre-processor directive". As I mentioned previously, in C/C++, you use the #include pre-processor directive to include a files content with the current source file. In Objective-C, you use the #import statement to do the same, with the exception that the compiler ensures that the file is only included once.

To import a header file from one of the framework libraries, you would specify the header filename using the angle brackets (), within the #import statement. If you were wanting to import one of your own header files to be used within your project, you would specify and make use of the (" "), as you can see from our code file, MyClass.m.


#import "MyClass.h"
@implementation MyClass
@end

Objective-C Classes
A Class can be simply be defined as a representation of a type of object; think of it as a blueprint that describes the object. Just as a single blueprint can be used to build multiple versions of a car engine, a class can be used to create multiple copies of an object. In Objective-C, you will spend most of your time dealing with classes and class objects. An example of a class object is the NSObject class. NSObject is the root class of most of the Objective-C classes. It defines the basic interface of a class and contains methods that are common to all classes that inherit from it.

@interface
To declare a class, you use the @interface compiler directive, as follows:


@interface MyClass : NSObject {
}

@implementation
To implement a class declared within a header file, you use the @implementation compiler directive, as follows:


#import "MyClass.h"
@implementation MyClass
@end

Class Instantiation
In Objective-C, in order for us to create an instance of a class, you would typically use the alloc keyword to allocate memory for the object and then return the variable in a class type This is shown in the following example:


MyClass *myClass = [MyClass alloc];

Class Access Privileges
In OOP, when you are defining your classes, bear in mind that by default, the access privilege of all fields within a class are @protected. These fields can also be defined as @public, or @private.

The following table shows the various access privileges that a class can contain.
A class member is made visible to all classes that instantiate this class. Class members are made visible to the class that declares it as well as other classes which inherit from the base class.

We have only covered a small part of the Objective-C programming concepts. If you are interested in reading a bit more about this area, please refer to the following website: http:// developer.apple.com/documentation/Cocoa/Conceptual/ObjectiveC/ObjC.pdf.

Introducing the Xcode Developer set of Tools
The Xcode developer set of tools comprise the Xcode Development Environment (IDE), Interface Builder, iPhone Simulator, and Instruments for Performance Analysis. These tools have been designed to integrate and work harmoniously together.

Introducing the Core Tools
The Xcode IDE is a complete full-featured development environment, which has been redesigned and built around to allow for a better smoother workflow development environment. With the integration of the GUI designer (Interface Builder), it allows a better way to integrate the editing of source code, building, compiling and debugging.

The Interface Builder is an easy to use GUI designer, which enables you to design every aspect of your applications UI, for Mac OSX and iOS applications.

All of your form objects are stored within one or more resource files, these files contain the associated relationships to each of the objects. Any changes that you make to the form design; these are automatically synchronized back to your code.

The iPhone Simulator provides you with a means of testing your application out, and to see how it will appear on the actual phone device. The Simulator makes it a perfect choice to ensure that your user interface works and behaves they way you intended it to and makes it easier for you to debug your application. The iPhone Simulator does contain some limitations, which cannot be used to test certain features, so it is always better to deploy your app to your iOS device.

The Welcome to Xcode Screen
To launch Xcode, double-click the Xcode icon located in the /Developer/Applications folder. Alternatively, you can use Spotlight to search for this: simply type Xcode into the search box and Xcode should be displayed in the list at the top.

When Xcode is launched, you should see the Welcome to Xcode Screen as shown in the following screenshot below. From this screen, you are able to create new projects, check out existing projects from the SCM and modify those files within the Xcode integrated development environment. It also contains some information about learning Xcode as well as Apple Developer resources.

The panel to the right-hand side of the screen will display any recent projects that you have opened. These can be opened and loaded into the IDE by clicking on them.

The Xcode – Integrated Development Environment
The Xcode Integrated Development Environment is what you will be using to start to code your iPhone applications.

This consists of a single-window user interface, consisting of the Project Window, Jump and Navigation Bars, and the newly integrated Interface Builder designer.

(Move the mouse over the image to enlarge.)

Features of the iPhone Simulator
The"iPhone Simulator", simulates various features of a real iOS device. Although the iPhone simulator is just a simulator to simulate certain tasks, it does come with some limitations.

Following is the list of some of the features which you are able to test using the iPhone Simulator. The following screenshot below displays the iPhone 4 simulator.

Please bear in mind, that being the "iPhone Simulator", it is just only a simulator. It does, however, pose some features which are impossible to handle. These have been defined as follows:

Making Phone calls
Accessing the Accelerometer/Gyroscope
Sending and Receiving SMS messages
Installing applications from the App Store
Accessibility to the Camera
Use of the Microphone
Several Core OpenGL ES Features

Companion Tools and Features
These tools are classified as profiling tools which are the instruments that handle the following:

Performance and Power Analysis Tools
Unit testing tools
Source Code Management (SCM) / Subversion
Version Comparison Tool

Instruments
The Xcode instruments allow you to dynamically trace and profile the performance of your Mac OSX, iPhone, and iPad applications. You can also create your own Instruments using DTrace and the Instruments custom builder.

Through the use of instruments, you can achieve the following:

Ability to perform Stress-tests on your applications.
Monitor your applications for memory leaks, which can cause unexpected results.
Gain a deeper understanding of the execution behavior of your applications.
Track down difficult to reproduce problems in your applications.
In the following figure, we display the Instruments environment where you can start to create your robust test harness for your application to ensure that any memory leaks and resource intensive tasks are rectified to avoid problems later when your users download your app and experience issues.

If you are interested in learning more about the instruments that are included with Xcode and the iOS 4 SDK, please consult the Apple Developer documentation.

iPhone OS4 SDK New Features
The iOS4 SDK comes jam-packed and is loaded with as many as 1,500 APIs. It contains some high quality enhancements and improvements, which allows endless possibilities for developers to create some stunning applications.
This is perhaps the most awaited feature everyone has been waiting for. It is an assortment of seven different services: Audio, VoIP, location, local and push notifications, task completions and fast app switching that will make it possible and simple enough to use many applications at the same time. This will allow you to play the audio continuously, receive calls while your device is locked or other apps are being used, location based applications will continue to guide you, and receiving alerts will be possible without the app running and the app will finish even when the customer leaves in the middle of it. Another important feature in iOS4 is the Apps Folder, this feature allows you to drag an icon on top of another one and a new folder will be automatically created. It will be named according to the name of the category the particular icon or application comes from. This has been vastly improved to allow for an organized approach of grouping various mails into one particular folder according to the conversation thread. Added support to handle more than one exchange account, which can also be opened through many third-party applications. Game Center provides social networking services, where you can take part in leader boards and participate in other online activities with other players. iAd is a mobile advertising platform to allow developers to incorporate advertisements into their application. It is currently supported on iPhone, iPod Touch, and iPad.

The previous list contains some of the important new features of iOS 4. If you are interested in a more detailed listing of all of the features in each of the releases; check out the following http://en.wikipedia....Version_History.

Summary
In this article, hopefully you have gained a good understanding of the Xcode and the development tools and the new and improved Single-Windowed development IDE. We have also covered some of the basics relating to Object-Oriented Programming and Objective-C. It will soon become apparent why Objective-C was chosen as the language of choice for developing Mac OSX and iOS applications.

Cocos2d: Working with Sprites

Wed, 22 Feb 2012 03:33:53 +0000

Cocos2d is first and foremost a rich graphical API which allows a game developer easy access to a broad range of functionality. In this article, we will take a look at the basic uses of sprites.

In this article by Nathan Burba, author of Cocos2d for iPhone 1 Game Development Cookbook, we will cover the following topics:

Drawing sprites
The most fundamental task in 2D game development is drawing a sprite. Cocos2d provides the user with a lot of flexibility in this area. In this recipe we will cover drawing sprites using CCSprite, spritesheets, CCSpriteFrameCache, and CCSpriteBatchNode. We will also go over mipmapping. In this recipe we see a scene with Alice from Through The Looking Glass.

Getting ready
Please refer to the project RecipeCollection01 for the full working code of this recipe.

How to do it...
Execute the following code:


@implementation Ch1_DrawingSprites
-(CCLayer*) runRecipe {
  /*** Draw a sprite using CCSprite ***/
  CCSprite *tree1 = [CCSprite spriteWithFile:@"tree.png"];

  //Position the sprite using the tree base as a guide (y anchor 
point = 0)
[tree1 setPosition:ccp(20,20)];
  tree1.anchorPoint = ccp(0.5f,0);
  [tree1 setScale:1.5f];
  [self addChild:tree1 z:2 tag:TAG_TREE_SPRITE_1];

  /*** Load a set of spriteframes from a PLIST file and draw one by
name ***/

  //Get the sprite frame cache singleton
  CCSpriteFrameCache *cache = [CCSpriteFrameCache
sharedSpriteFrameCache];

  //Load our scene sprites from a spritesheet
  [cache addSpriteFramesWithFile:@"alice_scene_sheet.plist"];

  //Specify the sprite frame and load it into a CCSprite
  CCSprite *alice = [CCSprite spriteWithSpriteFrameName:@"alice.png"];

  //Generate Mip Maps for the sprite
  [alice.texture generateMipmap];
  ccTexParams texParams = { GL_LINEAR_MIPMAP_LINEAR, GL_LINEAR, GL_
CLAMP_TO_EDGE, GL_CLAMP_TO_EDGE };
  [alice.texture setTexParameters:&texParams];

  //Set other information.
  [alice setPosition:ccp(120,20)];
  [alice setScale:0.4f];
  alice.anchorPoint = ccp(0.5f,0);

  //Add Alice with a zOrder of 2 so she appears in front of other
sprites
  [self addChild:alice z:2 tag:TAG_ALICE_SPRITE];

  //Make Alice grow and shrink.
  [alice runAction: [CCRepeatForever actionWithAction:
   [CCSequence actions:[CCScaleTo actionWithDuration:4.0f scale
:0.7f], [CCScaleTo actionWithDuration:4.0f scale:0.1f], nil] ] ];

  /*** Draw a sprite CGImageRef ***/
  UIImage *uiImage = [UIImage imageNamed: @"cheshire_cat.png"];
  CGImageRef imageRef = [uiImage CGImage];
  CCSprite *cat = [CCSprite spriteWithCGImage:imageRef key:@
"cheshire_cat.png"];
  [cat setPosition:ccp(250,180)];
  [cat setScale:0.4f];
  [self addChild:cat z:3 tag:TAG_CAT_SPRITE];

  /*** Draw a sprite using CCTexture2D ***/
  CCTexture2D *texture = [[CCTextureCache sharedTextureCache]
addImage:@"tree.png"];
  CCSprite *tree2 = [CCSprite spriteWithTexture:texture];
  [tree2 setPosition:ccp(300,20)];
  tree2.anchorPoint = ccp(0.5f,0);
  [tree2 setScale:2.0f];
  [self addChild:tree2 z:2 tag:TAG_TREE_SPRITE_2];

  /*** Draw a sprite using CCSpriteFrameCache and CCTexture2D ***/
  CCSpriteFrame *frame = [CCSpriteFrame frameWithTexture:texture
rect:tree2.textureRect];
  [[CCSpriteFrameCache sharedSpriteFrameCache] addSpriteFrame:
frame name:@"tree.png"];
  CCSprite *tree3 = [CCSprite spriteWithSpriteFrame:[[CCSpriteFrame
Cache sharedSpriteFrameCache] spriteFrameByName:@"tree.png"]];
  [tree3 setPosition:ccp(400,20)];
  tree3.anchorPoint = ccp(0.5f,0);
  [tree3 setScale:1.25f];
  [self addChild:tree3 z:2 tag:TAG_TREE_SPRITE_3];

  /*** Draw sprites using CCBatchSpriteNode ***/

  //Clouds
  CCSpriteBatchNode *cloudBatch = [CCSpriteBatchNode
batchNodeWithFile:@"cloud_01.png" capacity:10];
  [self addChild:cloudBatch z:1 tag:TAG_CLOUD_BATCH];
  for(int x=0; x   CCSprite *s = [CCSprite spriteWithBatchNode:cloudBatch
rect:CGRectMake(0,0,64,64)];
   [s setOpacity:100];
   [cloudBatch addChild:s];
   [s setPosition:ccp(arc4random()%500-50, arc4random()%150+200)];
  }

  //Middleground Grass
  int capacity = 10;
  CCSpriteBatchNode *grassBatch1 = [CCSpriteBatchNode
batchNodeWithFile:@"grass_01.png" capacity:capacity];
  [self addChild:grassBatch1 z:1 tag:TAG_GRASS_BATCH_1];
  for(int x=0; x   CCSprite *s = [CCSprite spriteWithBatchNode:grassBatch1
rect:CGRectMake(0,0,64,64)];
   [s setOpacity:255];
   [grassBatch1 addChild:s];
   [s setPosition:ccp(arc4random()%500-50, arc4random()%20+70)];
  }

  //Foreground Grass
  CCSpriteBatchNode *grassBatch2 = [CCSpriteBatchNode
batchNodeWithFile:@"grass_01.png" capacity:10];
  [self addChild:grassBatch2 z:3 tag:TAG_GRASS_BATCH_2];
  for(int x=0; x   CCSprite *s = [CCSprite spriteWithBatchNode:grassBatch2
rect:CGRectMake(0,0,64,64)];
   [s setOpacity:255];
   [grassBatch2 addChild:s];
   [s setPosition:ccp(arc4random()%500-50, arc4random()%40-10)];
  }

  /*** Draw colored rectangles using a 1px x 1px white texture ***/

  //Draw the sky using blank.png
  [self drawColoredSpriteAt:ccp(240,190) withRect:CGRectMa
ke(0,0,480,260) withColor:ccc3(150,200,200) withZ:0];

  //Draw the ground using blank.png
  [self drawColoredSpriteAt:ccp(240,30)
withRect:CGRectMake(0,0,480,60) withColor:ccc3(80,50,25) withZ:0];

  return self;
}

-(void) drawColoredSpriteAt:(CGPoint)position withRect:(CGRect)rect
withColor:(ccColor3B)color withZ:(float)z {
  CCSprite *sprite = [CCSprite spriteWithFile:@"blank.png"];
  [sprite setPosition:position];
  [sprite setTextureRect:rect];
  [sprite setColor:color];
  [self addChild:sprite];

  //Set Z Order
  [self reorderChild:sprite z:z];
}

@end

How it works...
This recipe takes us through most of the common ways of drawing sprites:

Creating a CCSprite from a file:
First, we have the simplest way to draw a sprite. This involves using the CCSprite class method as follows:
```
+(id)spriteWithFile:(NSString*)filename;
```
This is the most straightforward way to initialize a sprite and is adequate for many situations.
Other ways to load a sprite from a file:
After this, we will see examples of CCSprite creation using UIImage/CGImageRef, CCTexture2D, and a CCSpriteFrame instantiated using a CCTexture2D object. CGImageRef support allows you to tie Cocos2d into other frameworks and toolsets. CCTexture2D is the underlying mechanism for texture creation.
Loading spritesheets using CCSpriteFrameCache:
Next, we will see the most powerful way to use sprites, the CCSpriteFrameCache class. Introduced in Cocos2d-iPhone v0.99, the CCSpriteFrameCache singleton is a cache of all sprite frames. Using a spritesheet and its associated PLIST file we can load multiple sprites into the cache. From here we can create CCSprite objects with sprites from the cache:
```
+(id)spriteWithSpriteFrameName:(NSString*)filename;
```
Mipmapping:
Mipmapping allows you to scale a texture or to zoom in or out of a scene without aliasing your sprites. When we scale Alice down to a small size, aliasing will inevitably occur. With mipmapping turned on, Cocos2d dynamically generates lower resolution textures to smooth out any pixelation at smaller scales. Go ahead and comment out the following lines:
```
[alice.texture generateMipmap];
  ccTexParams texParams = { GL_LINEAR_MIPMAP_LINEAR, GL_LINEAR,
GL_CLAMP_TO_EDGE, GL_CLAMP_TO_EDGE };
  [alice.texture setTexParameters:&texParams];
```
Now you should see this pixelation as Alice gets smaller.
Drawing many derivative sprites with CCSpriteBatchNode:
The CCSpriteBatchNode class, added in v0.99.5, introduces an efficient way to draw and re-draw the same sprite over and over again. A batch node is created with the following method:
```
CCSpriteBatchNode *cloudBatch = [CCSpriteBatchNode
batchNodeWithFile:@"cloud_01.png" capacity:10];
```
Then, you create as many sprites as you want using the follow code:
```
CCSprite *s = [CCSprite spriteWithBatchNode:cloudBatch
rect:CGRectMake(0,0,64,64)];
  [cloudBatch addChild:s];
```
Setting the capacity to the number of sprites you plan to draw tells Cocos2d to allocate that much space. This is yet another tweak for extra efficiency, though it is not absolutely necessary that you do this. In these three examples we draw 10 randomly placed clouds and 60 randomly placed bits of grass.
Drawing colored rectangles:
Finally, we have a fairly simple technique that has a variety of uses. By drawing a sprite with a blank 1px by 1px white texture and then coloring it and setting its textureRect property we can create very useful colored bars:
```
CCSprite *sprite = [CCSprite spriteWithFile:@"blank.png"];
[sprite setTextureRect:CGRectMake(0,0,480,320)];
[sprite setColor:ccc3(255,128,0)];
```
In this example we have used this technique to create very simple ground and sky backgrounds.

Coloring sprites
In the previous recipe we used colored rectangles to draw both the ground and the sky. The ability to set texture color and opacity are simple tools which, if used properly, can create very cool effects. In this recipe we will create a cinematic scene where two samurai face each other with glowing swords.

Getting ready
Please refer to the project RecipeCollection01 for full working code of this recipe. Also, note that some code has been omitted for brevity.

How to do it...
Execute the following code:


#import "CCGradientLayer.h

@implementation Ch1_ColoringSprites

-(CCLayer*) runRecipe {
  [self initButtons];

  //The Fade Scene Sprite
  CCSprite *fadeSprite = [CCSprite spriteWithFile:@"blank.png"];
  [fadeSprite setOpacity:0];
  [fadeSprite setPosition:ccp(240,160)];
  [fadeSprite setTextureRect:CGRectMake(0,0,480,320)];
  [self addChild:fadeSprite z:3 tag:TAG_FADE_SPRITE];

  //Add a gradient below the mountains
//CCGradientDirectionT_B is an enum provided by CCGradientLayer
  CCGradientLayer *gradientLayer = [CCGradientLayer layerWithColor:
ccc4(61,33,62,255) toColor:ccc4(65,89,54,255) withDirection:
CCGradient DirectionT_B width:480 height:100];
  [gradientLayer setPosition:ccp(0,50)];
  [self addChild:gradientLayer z:0 tag:TAG_GROUND_GRADIENT];

  //Add a sinister red glow gradient behind the evil samurai
  CCGradientLayer *redGradient = [CCGradientLayer
layerWithColor:ccc4(0,0,0,0) toColor:ccc4(255,0,0,100) withDirection
:CCGradientDirectionT_B width:200 height:200];
  [redGradient setPosition:ccp(280,60)];
  [redGradient setRotation:-90];
  [self addChild:redGradient z:2 tag:TAG_RED_GRADIENT];

  // Make the swords glow
  [self glowAt:ccp(230,280) withScale:CGSizeMake(3.0f, 11.0f)
withColor:ccc3(0,230,255) withRotation:45.0f withSprite:goodSamurai];
  [self glowAt:ccp(70,280) withScale:CGSizeMake(3.0f, 11.0f)
withColor:ccc3(255,200,2) withRotation:-45.0f withSprite:evilSamurai];

  return self;
}

-(void) initButtons {
  [CCMenuItemFont setFontSize:16];

  //'Fade To Black' button
  CCMenuItemFont* fadeToBlack = [CCMenuItemFont itemFromString:@
"FADE TO BLACK" target:self selector:@selector(fadeToBlackCallback:)];
  CCMenu *fadeToBlackMenu = [CCMenu menuWithItems:fadeToBlack, nil];
   fadeToBlackMenu.position = ccp( 180 , 20 );
   [self addChild:fadeToBlackMenu z:4 tag:TAG_FADE_TO_BLACK];
}

/* Fade the scene to black */
-(void) fadeToBlackCallback:(id)sender {
  CCSprite *fadeSprite = [self getChildByTag:TAG_FADE_SPRITE];
  [fadeSprite stopAllActions];
  [fadeSprite setColor:ccc3(0,0,0)];
  [fadeSprite setOpacity:0.0f];
  [fadeSprite runAction:
  [CCSequence actions:[CCFadeIn actionWithDuration:2.0f], [CCFadeOut
actionWithDuration:2.0f], nil] ];
}

/* Create a glow effect */
-(void) glowAt:(CGPoint)position withScale:(CGSize)size
withColor:(ccColor3B)color withRotation:(float)rotation
withSprite:(CCSprite*)sprite {
  CCSprite *glowSprite = [CCSprite spriteWithFile:@"fire.png"];
  [glowSprite setColor:color];
  [glowSprite setPosition:position];
  [glowSprite setRotation:rotation];
  [glowSprite setBlendFunc: (ccBlendFunc) { GL_ONE, GL_ONE }];
  [glowSprite runAction: [CCRepeatForever actionWithAction:
   [CCSequence actions:[CCScaleTo actionWithDuration:0.9f
scaleX:size.width scaleY:size.height], [CCScaleTo
actionWithDuration:0.9f scaleX:size.width*0.75f scaleY:size.
height*0.75f], nil] ] ];
  [glowSprite runAction: [CCRepeatForever actionWithAction:
   [CCSequence actions:[CCFadeTo actionWithDuration:0.9f
opacity:150], [CCFadeTo actionWithDuration:0.9f opacity:255], nil] ]
];
  [sprite addChild:glowSprite];
}

@end

How it works...
This recipe shows a number of color based techniques.

Setting sprite color:
The simplest use of color involves setting the color of a sprite using the following method:
```
-(void) setColor:(ccColor3B)color;
```
Setting sprite color effectively reduces the color you can display but it allows some programmatic flexibility in drawing. In this recipe we use setColor for a number of things, including drawing a blue sky, a yellow sun, black "dramatic movie bars", and more.
ccColor3B is a C struct which contains three GLubyte variables. Use the following helper macro to create ccColor3B structures:
```
ccColor3B ccc3(const GLubyte r, const GLubyte g, const GLubyte
b);
```
Cocos2d also specifies a number of pre-defined colors as constants. These include the following:
```
ccWHITE, ccYELLOW, ccBLUE, ccGREEN, ccRED,
ccMAGENTA, ccBLACK, ccORANGE, ccGRAY
```
Fading to a color:
To fade a scene to a specific color we use the blank.png technique we went over in the last recipe. We first draw a sprite as large as the screen, then color the sprite to the color we want to fade to, and then finally run a CCFadeIn action on the sprite to fade to that color:
```
[fadeSprite setColor:ccc3(255,255,255)];
[fadeSprite setOpacity:0.0f];
[fadeSprite runAction: [CCFadeIn actionWithDuration:2.0f] ];
```
Using CCGradientLayer:
Using the CCGradientLayer class we can programmatically create gradients. To make the mountains in the background fade into the ground the two samurai are standing on we created a gradient using this method:
```
  CCGradientLayer *gradientLayer = [CCGradientLayer layerWithColor
:ccc4(61,33,62,255) toColor:ccc4(65,89,54,255) withDirection:CCGra
dientDirectionT_B width:480 height:100];
  [gradientLayer setPosition:ccp(0,50)];
  [self addChild:gradientLayer z:0 tag:TAG_GROUND_GRADIENT];
```
Because CCGradientLayer lets you control opacity as well as color, it has many uses. As you can see there is also a sinister red glow behind the evil samurai.

Making a sprite glow: To make the swords in the demo glow we use subtle color manipulation, additive blending and fading and scaling actions. First we load the fire.png sprite supplied by Cocos2d. By changing its X and Y scale independently we can make it thinner or fatter. Once you have the desired scale ratio (in this demo we use x:y 3:11 because the sword is so thin) you can constantly scale and fade the sprite in and out to give some life to the effect. You also need to set the blend function to { GL_ONE, GL_ONE } for additive blending. Finally this effect sprite is added to the actual sprite to make it seem like it glows.


CCSprite *glowSprite = [CCSprite spriteWithFile:@"fire.png"];
  [glowSprite setColor:color];
  [glowSprite setPosition:position];
  [glowSprite setRotation:rotation];
  [glowSprite setBlendFunc: (ccBlendFunc) { GL_ONE, GL_ONE }];
  [glowSprite runAction: [CCRepeatForever actionWithAction:
  [CCSequence actions:[CCScaleTo actionWithDuration:0.9f
scaleX:size.width scaleY:size.height], [CCScaleTo
actionWithDuration:0.9f scaleX:size.width*0.75f scaleY:size.
height*0.75f], nil] ] ];
  [glowSprite runAction: [CCRepeatForever actionWithAction:
  [CCSequence actions:[CCFadeTo actionWithDuration:0.9f
opacity:150], [CCFadeTo actionWithDuration:0.9f opacity:255], nil]
] ];
  [sprite addChild:glowSprite];

Animating sprites
Now it is time to add some animation to our sprites. One thing that should be stressed about animation is that it is only as complicated as you make it. In this recipe we will use very simple animation to create a compelling effect. We will create a scene where bats fly around a creepy looking castle. I've also added a cool lightning effect based on the technique used to make the swords glow in the previous recipe.

Getting ready
Please refer to the project RecipeCollection01 for full working code of this recipe. Also note that some code has been omitted for brevity.

How to do it...
Execute the following code:


//SimpleAnimObject.h
@interface SimpleAnimObject : CCSprite {
  int animationType;
  CGPoint velocity;
}

@interface Ch1_AnimatingSprites {
  NSMutableArray *bats;
  CCAnimation *batFlyUp;
  CCAnimation *batGlideDown;
  CCSprite *lightningBolt;
  CCSprite *lightningGlow;
  int lightningRemoveCount;
}

-(CCLayer*) runRecipe {
  //Add our PLIST to the SpriteFrameCache
  [[CCSpriteFrameCache sharedSpriteFrameCache] 
addSpriteFramesWithFile:@"simple_bat.plist"];

  //Add a lightning bolt
  lightningBolt = [CCSprite spriteWithFile:@"lightning_bolt.png"];
  [lightningBolt setPosition:ccp(240,160)];
  [lightningBolt setOpacity:64];
  [lightningBolt retain];

  //Add a sprite to make it light up other areas.
  lightningGlow = [CCSprite spriteWithFile:@"lightning_glow.png"];
  [lightningGlow setColor:ccc3(255,255,0)];
  [lightningGlow setPosition:ccp(240,160)];
  [lightningGlow setOpacity:100];
  [lightningGlow setBlendFunc: (ccBlendFunc) { GL_ONE, GL_ONE }];
  [lightningBolt addChild:lightningGlow];

  //Set a counter for lightning duration randomization
  lightningRemoveCount = 0;

  //Bats Array Initialization
  bats = [[NSMutableArray alloc] init];

  //Add bats using a batch node.
  CCSpriteBatchNode *batch1 = [CCSpriteBatchNode
batchNodeWithFile:@"simple_bat.png" capacity:10];
  [self addChild:batch1 z:2 tag:TAG_BATS];

  //Make them start flying up.
  for(int x=0; x   //Create SimpleAnimObject of bat
   SimpleAnimObject *bat = [SimpleAnimObject
spriteWithBatchNode:batch1 rect:CGRectMake(0,0,48,48)];
  [batch1 addChild:bat];
  [bat setPosition:ccp(arc4random()%400+40, arc4random()%150+150)];

  //Make the bat fly up. Get the animation delay (flappingSpeed).
  float flappingSpeed = [self makeBatFlyUp:bat];

  //Base y velocity on flappingSpeed.
  bat.velocity = ccp((arc4random()%1000)/500 + 0.2f, 0.1f/
flappingSpeed);

  //Add a pointer to this bat object to the NSMutableArray
  [bats addObject:[NSValue valueWithPointer:bat]];
  [bat retain];

  //Set the bat's direction based on x velocity.
  if(bat.velocity.x > 0){
   bat.flipX = YES;
  }
 }

  //Schedule physics updates
  [self schedule:@selector(step:)];

  return self;
}

-(float)makeBatFlyUp:(SimpleAnimObject*)bat {
  CCSpriteFrameCache * cache = [CCSpriteFrameCache
sharedSpriteFrameCache];

  //Randomize animation speed.
  float delay = (float)(arc4random()%5+5)/80;
  CCAnimation *animation = [[CCAnimation alloc] initWithName:@
"simply_bat_fly" delay:delay];

  //Randomize animation frame order.
  int num = arc4random()%4+1;
  for(int i=1; i   [animation addFrame:[cache spriteFrameByName:[NSString
stringWithFormat:@"simple_bat_0%i.png",num]]];
   num++;
   if(num > 4){ num = 1; }
  }

  //Stop any running animations and apply this one.
  [bat stopAllActions];
  [bat runAction:[CCRepeatForever actionWithAction: [CCAnimate 
actionWithAnimation:animation]]];

  //Keep track of which animation is running.
  bat.animationType = BAT_FLYING_UP;

  return delay; //We return how fast the bat is flapping.
}

-(void)makeBatGlideDown:(SimpleAnimObject*)bat {
  CCSpriteFrameCache * cache = [CCSpriteFrameCache
sharedSpriteFrameCache];

  //Apply a simple single frame gliding animation.
  CCAnimation *animation = [[CCAnimation alloc] initWithName:@
"simple_bat_glide" delay:100.0f];
 [animation addFrame:[cache spriteFrameByName:@"simple_bat_01.png"]];

  //Stop any running animations and apply this one.
  [bat stopAllActions];
  [bat runAction:[CCRepeatForever actionWithAction: [CCAnimate 
actionWithAnimation:animation]]];

  //Keep track of which animation is running.
  bat.animationType = BAT_GLIDING_DOWN;
}

-(void)step:(ccTime)delta {
  CGSize s = [[CCDirector sharedDirector] winSize];

for(id key in bats){
  //Get SimpleAnimObject out of NSArray of NSValue objects.
  SimpleAnimObject *bat = [key pointerValue];

  //Make sure bats don't fly off the screen
  if(bat.position.x > s.width){
   bat.velocity = ccp(-bat.velocity.x, bat.velocity.y);
   bat.flipX = NO;
  }else if(bat.position.x	bat.velocity = ccp(-bat.velocity.x, bat.velocity.y);
   bat.flipX = YES;
  }else if(bat.position.y > s.height){
   bat.velocity = ccp(bat.velocity.x, -bat.velocity.y);
   [self makeBatGlideDown:bat];
  }else if(bat.position.y	bat.velocity = ccp(bat.velocity.x, -bat.velocity.y);
   [self makeBatFlyUp:bat];
  }

  //Randomly make them fly back up
  if(arc4random()%100 == 7){
   if(bat.animationType == BAT_GLIDING_DOWN){ [self
makeBatFlyUp:bat]; bat.velocity = ccp(bat.velocity.x, -bat.
velocity.y); }
   else if(bat.animationType == BAT_FLYING_UP){ [self
makeBatGlideDown:bat]; bat.velocity = ccp(bat.velocity.x, -bat.
velocity.y); }
  }

  //Update bat position based on direction
  bat.position = ccp(bat.position.x + bat.velocity.x, bat.position.y
+ bat.velocity.y);
  }

  //Randomly make lightning strike
  if(arc4random()%70 == 7){
  if(lightningRemoveCount	[self addChild:lightningBolt z:1 tag:TAG_LIGHTNING_BOLT];
   lightningRemoveCount = arc4random()%5+5;
   }
  }

  //Count down
  lightningRemoveCount -= 1;

  //Clean up any old lightning bolts
  if(lightningRemoveCount == 0){
   [self removeChildByTag:TAG_LIGHTNING_BOLT cleanup:NO];
  }
}

@end

How it works...
This recipe shows us how to structure animation based classes through the use of SimpleAnimObject:

Animated object class structure:
When switching from one animation to another it is often important to keep track of what state the animated object is in. In our example we use SimpleAnimObject, which keeps an arbitrary animationType variable. We also maintain a velocity variable that has a Y scalar value that is inversely proportional to the animation frame delay:
```
@interface SimpleAnimObject : CCSprite {
  int animationType;
  CGPoint velocity;
}
```
Depending on how in-depth you want your animation system to be you should maintain more information such as, for example, a pointer to the running CCAnimation instance, frame information, and physical bodies.

There's more...
As you get more involved with Cocos2d game development you will become more and more tempted to use asynchronous actions for gameplay logic and AI. Derived from the CCAction class, these actions can be used for everything from moving a CCNode using CCMoveBy to animating a CCSprite using CCAnimate. When an action is run, an asynchronous timing mechanism is maintained in the background. First time game programmers often over-rely on this feature. The extra overhead required by this technique can multiply quickly when multiple actions are being run. In the following example we have used a simple integer timer that allows us to regulate how long lightning lasts onscreen:


//Randomly make lightning strike
if(arc4random()%70 == 7){
 if(lightningRemoveCount   [self addChild:lightningBolt z:1 tag:TAG_LIGHTNING_BOLT];
  lightningRemoveCount = arc4random()%5+5;
 }
}

//Count down
lightningRemoveCount -= 1;

//Clean up any old lightning bolts
if(lightningRemoveCount == 0){
 [self removeChildByTag:TAG_LIGHTNING_BOLT cleanup:NO];
}

Synchronous timers like the one shown in the preceding code snippet are often, but not always, preferable to asynchronous actions. Keep this in mind as your games grow in size and scope.

Summary
In this article we took a look at the basic uses of sprites.

Introduction to Game Development Using Unity 3D

Tue, 21 Feb 2012 17:47:26 +0000

This article by Ryan Henson Creighton, author of Unity 3D Game Development by Example, introduces you to Unity 3D—an amazing game engine that enables you to create games and deploy them to a number of different devices, including (at the time of writing) the Web, PCs, iOS platforms, and WiiWare, with modules for Android and Xbox Live Arcade deployment in the works. You'll play a number of browser-based Unity 3D games to get a sense of what the engine can handle, from a massively-multiplayer online game all the way down to a simple kart racer. You'll download and install your own copy of Unity 3D, and mess around with the beautiful Island Demo that ships with the product.

Technology is a tool. It helps us accomplish amazing things, hopefully more quickly and more easily and more amazingly than if we hadn't used the tool. Before we had newfangled steam-powered hammering machines, we had hammers. And before we had hammers, we had the painful process of smacking a nail into a board with our bare hands. Technology is all about making our lives better and easier. And less painful.

Introducing Unity 3D
Unity 3D is a new piece of technology that strives to make life better and easier for game developers. Unity is a game engine or a game authoring tool that enables creative folks like you to build video games.

By using Unity, you can build video games more quickly and easily than ever before. In the past, building games required an enormous stack of punch cards, a computer that filled a whole room, and a burnt sacrificial offering to an ancient god named Fortran. Today, instead of spanking nails into boards with your palm, you have Unity. Consider it your hammer—a new piece of technology for your creative tool belt.

Unity takes over the world
We'll be distilling our game development dreams down to small, bite-sized nuggets instead of launching into any sweepingly epic open-world games. The idea here is to focus on something you can actually finish instead of getting bogged down in an impossibly ambitious opus. When you're finished, you can publish these games on the Web, Mac, or PC.

The team behind Unity 3D is constantly working on packages and export opinions for other platforms. At the time of this writing, Unity could additionally create games that can be played on the iPhone, iPod, iPad, Android devices, Xbox Live Arcade, PS3, and Nintendo's WiiWare service. Each of these tools is an add-on functionality to the core Unity package, and comes at an additional cost. As we're focusing on what we can do without breaking the bank, we'll stick to the core Unity 3D program for the remainder of this article. The key is to start with something you can finish, and then for each new project that you build, to add small pieces of functionality that challenge you and expand your knowledge. Any successful plan for world domination begins by drawing a territorial border in your backyard.

Browser-based 3D? Welcome to the future
Unity's primary and most astonishing selling point is that it can deliver a full 3D game experience right inside your web browser. It does this with the Unity Web Player—a free plugin that embeds and runs Unity content on the Web.

Time for action – install the Unity Web Player
Before you dive into the world of Unity games, download the Unity Web Player. Much the same way the Flash player runs Flash-created content, the Unity Web Player is a plugin that runs Unity-created content in your web browser.

Go to http://unity3D.com.
Click on the install now! button to install the Unity Web Player.

Click on Download Now!
Follow all of the on-screen prompts until the Web Player has finished installing.

Welcome to Unity 3D!
Now that you've installed the Web Player, you can view the content created with the Unity 3D authoring tool in your browser.

What can I build with Unity?
In order to fully appreciate how fancy this new hammer is, let's take a look at some projects that other people have created with Unity. While these games may be completely out of our reach at the moment, let's find out how game developers have pushed this amazing tool to its very limits.

FusionFall
The first stop on our whirlwind Unity tour is FusionFall—a Massively Multiplayer Online Role-Playing Game (MMORPG). You can find it at fusionfall.com. You may need to register to play, but it's definitely worth the extra effort!

FusionFall was commissioned by the Cartoon Network television franchise, and takes place in a re-imagined, anime-style world where popular Cartoon Network characters are all grown up. Darker, more sophisticated versions of the Powerpuff Girls, Dexter, Foster and his imaginary friends, and the kids from Codename: Kids Next Door run around battling a slimy green alien menace.

Completely hammered
FusionFall is a very big and very expensive high-profile game that helped draw a lot of attention to the then-unknown Unity game engine when the game was released. As a tech demo, it's one of the very best showcases of what your new technological hammer can really do! FusionFall has real-time multiplayer networking, chat, quests, combat, inventory, NPCs (non-player characters), basic AI (artificial intelligence), name generation, avatar creation, and costumes. And that's just a highlight of the game's feature set. This game packs a lot of depth.

Should we try to build FusionFall?
At this point, you might be thinking to yourself, "Heck YES! FusionFall is exactly the kind of game I want to create with Unity, and this article is going to show me how!"

Unfortunately, a step-by-step guide to creating a game the size and scope of FusionFall would likely require its own flatbed truck to transport, and you'd need a few friends to help you turn each enormous page. It would take you the rest of your life to read, and on your deathbed, you'd finally realize the grave error that you had made in ordering it online in the first place, despite having qualified for free shipping.

Here's why: check out the game credits link on the FusionFall website: http://www.fusionfal...ame/credits.php.

This page lists all of the people involved in bringing the game to life. Cartoon Network enlisted the help of an experienced Korean MMO developer called Grigon Entertainment. There are over 80 names on that credits list! Clearly, only two courses of action are available to you:

Build a cloning machine and make 79 copies of yourself. Send each of those copies to school to study various disciplines, including marketing, server programming, and 3D animation. Then spend a year building the game with your clones. Keep track of who's who by using a sophisticated armband system.
Give up now because you'll never make the game of your dreams.

Another option
Before you do something rash and abandon game development for farming, let's take another look at this. FusionFall is very impressive, and it might look a lot like the game that you've always dreamed of making. This article is not about crushing your dreams. It's about dialing down your expectations, putting those dreams in an airtight jar, and taking baby steps. Confucius said: "A journey of a thousand miles begins with a single step." I don't know much about the man's hobbies, but if he was into video games, he might have said something similar about them—creating a game with a thousand awesome features begins by creating a single, less feature-rich game.

So, let's put the FusionFall dream in an airtight jar and come back to it when we're ready. We'll take a look at some smaller Unity 3D game examples and talk about what it took to build them.

Off-Road Velociraptor Safari
No tour of Unity 3D games would be complete without a trip to Blurst.com—the game portal owned and operated by indie game developer Flashbang Studios. In addition to hosting games by other indie game developers, Flashbang has packed Blurst with its own slate of kooky content, including Off-Road Velociraptor Safari. (Note: Flashbang Studios is constantly toying around with ways to distribute and sell its games. At the time of this writing, Off-Road Velociraptor Safari could be played for free only as a Facebook game. If you don't have a Facebook account, try playing another one of the team's creations, like Minotaur China Shop or Time Donkey).

In Off-Road Velociraptor Safari, you play a dinosaur in a pith helmet and a monocle driving a jeep equipped with a deadly spiked ball on a chain (just like in the archaeology textbooks). Your goal is to spin around in your jeep doing tricks and murdering your fellow dinosaurs (obviously).

For many indie game developers and reviewers, Off-Road Velociraptor Safari was their first introduction to Unity. Some reviewers said that they were stunned that a fully 3D game could play in the browser. Other reviewers were a little bummed that the game was sluggish on slower computers. We'll talk about optimization a little later, but it's not too early to keep performance in mind as you start out.

Fewer features, more promise

If you play Off-Road Velociraptor Safari and some of the other games on the Blurst site, you'll get a better sense of what you can do with Unity without a team of experienced Korean MMO developers. The game has 3D models, physics (code that controls how things move around somewhat realistically), collisions (code that detects when things hit each other), music, and sound effects. Just like FusionFall, the game can be played in the browser with the Unity Web Player plugin. Flashbang Studios also sells downloadable versions of its games, demonstrating that Unity can produce standalone executable game files too.

Maybe we should build Off-Road Velociraptor Safari?

Right then! We can't create FusionFall just yet, but we can surely create a tiny game like Off-Road Velociraptor Safari, right? Well... no. Again, this article isn't about crushing your game development dreams. But the fact remains that Off-Road Velociraptor Safari took five supremely talented and experienced guys eight weeks to build on full-time hours, and they've been tweaking and improving it ever since. Even a game like this, which may seem quite small in comparison to full-blown MMO like FusionFall, is a daunting challenge for a solo developer. Put it in a jar up on the shelf, and let's take a look at something you'll have more success with.

I bent my Wooglie
Wooglie.com is a Unity game portal hosted by M2H Game Studio in the Netherlands. One glance at the front page will tell you that it's a far different portal than Blurst.com. Many of the Wooglie games are rough around the edges, and lack the sophistication and the slick professional sheen of the games on Blurst. But here is where we'll make our start with Unity. This is exactly where you need to begin as a new game developer, or as someone approaching a new piece of technology like Unity.

Play through a selection of games on Wooglie. I'll highlight a few of them for your interest:

Big Fun Racing
Big Fun Racing is a simple but effective game where you zip around collecting coins in a toy truck. It features a number of different levels and unlockable vehicles. The game designer sunk a few months into the game in his off-hours, with a little help from outsource artists to create the vehicle models.

Diceworks
Diceworks is a very simple, well-polished game designed for the iPhone in Unity 3D. We won't be covering any iPhone development, but it's good to know that your Unity content can be deployed to a number of other devices and platforms, including the Apple iPhone or iPod touch, and the Nintendo Wii. The iPhone and Wii versions of the software cost an additional fee, but you can deploy your games to the Web, to the Mac, and to the PC for free using the indie version of Unity.

Diceworks was created by one artist and one programmer working together as a team. It's rare to find a single person who possesses both programming and artistic talent simultaneously; scientists say that these disciplines are split between two different lobes in our brains, and we tend to favor one or the other. The artist-programmer pairing that produced Diceworks is a common setup in game development. What's your own brain telling you? Are you more comfy with visuals or logic? Art or programming? Once you discover the answer, it's not a bad plan to find someone to make up the other half of your brain so that your game handles both areas competently.

At any event, with Diceworks we're definitely getting closer to the scope and scale that you can manage on your own as you start out with Unity.

It's also interesting to note that Diceworks is a 2D game created in a 3D engine. The third "D" is largely missing, and all of the game elements appear to exist on a flat plane. Nixing that extra dimension when you're just starting out isn't a half bad idea. Adding depth to your game brings a whole new dimension of difficulty to your designs, and it will be easier to get up and running with Unity by focusing on the X and Y axes, and leaving the Z-axis in one of those dream jars. With a few sturdy working game examples under your belt, it won't be long before you can take that Z-jar down off the shelf and pop it open. The games that we'll be dealing with in this article will stick to a two-dimensional plane, using three-dimensional models. Even so, certain games have taken this concept and ran with it: New Super Mario Bros. Wii locked its 3D characters to a 2D plane and wound up an extremely complex and satisfying platformer.

Walk before you can run (or double jump)
A common mistake that new game developers make is biting off more than they can chew. Even experienced game developers make this mistake when they get really excited about a project, or when they approach a new technology and expect to be immediately proficient at using it. The real danger here is that you'll sit down and try to create your dream—let's say it's a sword and sorcery RPG epic that combines all the best parts of Diablo, ChuChu Rocket!, and Microsoft Excel. When you've sunk days and weeks and months into it and it still looks nothing like the game you envisioned, you give up. You figure that since you failed at creating your dream game, you were never really cut out to be a game developer to begin with.

You owe it to yourself to start small! Rome wasn't built in a day, and neither was your dream kart racing game starring famous figures from Roman history. By taking smaller steps, you can experience success with a number of smaller games. Then you can take what you learn and add to it, slowly building your expertise until you're in a position to take that dream game jar off the shelf.

For now, let's keep our dream shelf fully stocked, and turn our attention to something small and achievable. Best would be to have a collection of working games that started out simply, and grew more and more complex as you got smarter.

There are real-world examples of games that began as simple, effective ideas and later grew into enormously complex and feature-rich titles. From small acorns, mighty multiplayer oak tree games grow.

There's no such thing as "finished"
Some game developers who produce content for fixed media such as game discs and cartridges are used to producing a gold master—the final build of the game—and calling it a day. One of the joys of deploying games to the Web is that they're never truly finished. You can continue tweaking your web games and modifying them until you end up with a far more fun and polished game than you started with.

If you follow Flashbang Studios on Twitter or if you read the studio's blog, you'll see that they're constantly modifying and improving their games, even years after they were "finished". At the time of this writing, Off-Road Velociraptor Safari was two years old, and the studio's Twitter stream revealed that they're still actively tweaking the game.

Likewise, we may start with some games that are really raw and unfinished at first. But as we learn more about how to program the crucial bits and pieces common to many games, we'll keep revisiting our rough, early games to add those pieces and improve them.

Stop! Hammer time
Now that you've seen some of what Unity can do, it's time to download the program and kick the tires! Unity indie version is available for the low price of free (at the time of this writing) from the Unity 3D website.

Explore Demo island
When Unity first opens, you should see a splash screen referring you to different tutorial resources and language guides. How helpful! Now close it. (Don't worry, it'll be there next time, unless you uncheck the Show at Startup box).

Because you chose to download the sample project, it should automatically load the first time you run Unity. Navigate to Window | Layouts | 2 by 3 to see the different panels that we're about to tour.

To try out the demo, click on the Play button at the top-center of the screen.

You can walk around the Island Demo using the WASD keys on your keyboard. Jump by pressing the Space bar. When you're finished exploring, click on the Play button again to end the demo.

The wonders of technology!
Unity contains all of the tools that you need to create an island similar to the one you see in this demo. It has terrain tools that let you model your level right inside the software. It contains a ready-made First Person Controller Prefab object you can plunk into the world with automatic WASD keyboard controls that will allow you to explore the terrain. Unity automatically takes care of the rendering (drawing), collisions, physics, and sound effects. That's one fancy hammer!

Wide-open worlds with Will
If you'd like to learn how to sculpt your own terrain in Unity, and to add 3D models, sounds, and interactivity to create a simple but functional 3D open-world game, check out, "Unity Game Development Essentials", Will Goldstone, Packt Publishing.

Much of what you see in the Island Demo can be built directly in Unity using the engine's terrain sculpting tools. The demo contains special models, like the bridge, which were imported from 3D software packages, including 3D Studio Max, Maya, or Blender. Certain elements, like the birds, have scripts attached to them that teach them how to fly. Scripts are lists of instructions that tell the items in the game world how to behave.

Let's take a quick look around the Unity interface and note a few points of interest.

The Scene window
The Scene window is where you can position your Game Objects and move things around. This window has various controls to change its level of detail. Use these controls to toggle lighing on and off, and to display the window contents with textures, wireframes, or a combination of both. You can use the colorful gizmo in the top-right corner to constrain the window to the X, Y, and Z axes to view the top and sides of your scene. Click on the white box in the middle to return to perspective view. This is what the Scene window looks like when you start a new project or create a new Scene. You can think of scenes as levels or stages in your game.

The Game window
The Game window shows you what your players will see. When you click on the Play button to test your game (as you just did with the Island Demo), the results of your efforts play out in this window. Toggle the Maximize on Play button to test your game in full-screen mode.

The Hierarchy
The Hierarchy panel lists all of the Game Objects in your Scene. Game Objects—cameras, lights, models, and prefabs—are the things that make up your game. They can be "tangible" things like the birds and the bridge in the Island Demo. They can also include intangible things, which only you as the game developer get to see and play with, such as the cameras, the lights, and colliders, which are special invisible shapes that tell the game engine when two Game Objects are touching.

The Island Demo Hierarchy contains Game Objects for the birds, the sea foam, the terrain, and the sun, to name a few. It also lists something called the First Person Controller Prefab, which has one of those invisible Colliders with a camera stuck to it. That's how the player can see the island. The demo lists something called Performance—an empty Game Object with a special script at ached to it that helps the demo run more quickly depending on the player's computer specs. So, Game Objects can include touchy-feely "physical" objects like birds and bridges, as well as behind-the-scenes intangible things like lights, cameras, and actions (scripts).

Click on a Game Object in the Hierarchy panel, and then hover your mouse over the Scene window. Press the F key on your keyboard, and the Scene window will automatically pan and zoom directly to that object. Alternatively, you can go to Edit | Frame Selected, which can be more reliable than using the keyboard shortcut. (I like to think of the F as standing for Focus to help me remember what this shortcut does).

The Project panel
he Project panel lists all of the elements that you'll use to create Game Objects in your project. For example, the Island Demo seagull Game Object is made up of a mesh that represents the seagull's shape, a material to depict its "skin" or coloring, and a script that controls its flight behavior. The seagull material itself could include a texture (image) file. All of these goodies are listed in the Project panel.

You got a lot of gull
The actual seagulls in the Island Demo are actually more complex than the ones in our simple example. To see what went into creating them, click on the gray arrow next to Birds in the Project panel. Then click on the arrow next to Seagull. Don't worry if you don't understand what you're seeing—the key here is to understand that the Project panel contains many of the elements, or ingredients, that go into making our Game Objects.

The Project panel displays the contents of a special folder called Assets. Unity automatically creates the Assets folder for you when you create a new project. If you drag a compatible file, like a 3D model, a sound effect, or an image into the Project panel, Unity copies it to the Assets folder behind the scenes, and displays it in the Project panel.

Don't mess with the Assets folder!
Unity stores metadata about the folder, and by moving stuff around or deleting things through your operating system, you may break your project. If you need to make changes, make them right inside Unity in the Project panel.

The Inspector
The Inspector is a context-sensitive panel, which means that it changes depending on what you select elsewhere in Unity. This is where you can adjust the position, rotation, and scale of Game Objects listed in the Hierarchy panel. The Inspector can also display controls to configure components that add functionality to Game Objects. Between the three main panels in Unity (Hierarchy, Project, and Inspector), the Inspector is where you'll likely spend most of your time because that's where you'll be tweaking and fiddling with every aspect of the elements that comprise your game projects.

This screenshot of the Inspector shows the components attached to the First Person Controller Prefab in the Island Demo: two scripts (FPSWalker and Mouse Look) and a Character Controller component. To see the same content on your computer, click to select the First Person Controller Prefab in the Hierarchy panel.

Invade Island Demo as a paratrooper
Let's use the Inspector panel to make a quick change to the start position of the player character. We'll begin the demo with the player 400 feet in midair, giving the player a beautiful bird's eye view of the action as he parachutes into the island.

The First Person Controller Prefab that you just clicked on represents the player in the game. It has a camera embedded in it that the player looks through, and a pill-shaped Character collider that tells the game engine when the player is touching other things in the Scene. The Character collider is what keeps the player from falling through the ground.

We can use the Inspector panel to change the start position of the player. In the Scene view, you should see the First Person Controller Prefab—it looks like a green pill with what looks like a speaker icon on top of it (this is blocking the Camera icon). If you don't see it, follow these steps:

Click to select the First Person Controller Prefab in the Hierarchy panel.
Navigate to Edit | Frame Selected to focus on the Game Object. Alternatively, you can hover your mouse over the Scene view and press the F key on your keyboard. The First Person Controller Prefab should swing into view.
Click on the Move button, which looks like four connected arrows.

A tripod of three arrows appears at the center of the Game Object. The blue Z- axis runs through where the player's belly button would be. The red X-axis runs perpendicular to the X-axis. And the green Y-axis runs straight up and down through the player as if the player was hanging by a piece of string tied to the top of her head. The Y-axis is the up or down axis that we want to adjust.
You can click-and-drag the green Y-axis arrow to move the player up into the sky, but a better method is to change the Y-axis position in the Inspector panel. Expand the gray arrow next to Transform in the Inspector panel if it's not already open, and change the Y value under Position to 400.
Now, when you press Play to test the game, your character will start way up in the sky, floating down to the island before making a soft, quiet landing. It's a good thing that the Unity people didn't write a fall damage script, otherwise we might have some crumpled legs to contend with!

Layers and layout dropdowns
Above the Inspector panel, you'll see the Layers and Layout dropdowns. Game Objects can be grouped into layers, much like in Photoshop or Flash. Unity stores a few commonly used layouts in the Layout dropdown. You can also save and load your own custom layouts.

Playback controls
These three buttons help you test your game and control playback. As you've seen, the Play button starts and stops your game. The Pause button works as expected—it pauses your game so that you can make changes to it on the fly. The third button is a Step-Through control; use it to advance frame-by-frame through your game so that you can more tightly control what's going on.

Changes you make while testing don't stick!
One of the more surprising features of Unity is that you can make changes to Game Objects and variables on the fly while you're testing your game. But it's important to know that the changes you make during testing will not "stick". Once you stop testing your game, the changes that you made during testing will revert to the state they were in before you clicked on the Play button. It's disheartening to make a number of changes to your game, only to realize that the Play button was on the entire time, and your changes will be lost. One way to avoid this problem is to toggle the Maximize on Play button in the Game window so that you'll be more aware of when you're testing and when you're not.

Scene controls
At the top-left of your screen, you'll see four controls that help you move around your Scene, and position Game Objects within it. These controls are mapped to the Q, W, E, and R keys on your keyboard. From left to right, they are:

The Hand tool (Q): Use it to click-and-drag around your scene. Hold down the Alt key on your keyboard to rotate the view. Hold down the Ctrl key (Windows) or the Command key (Apple) to zoom in and out. Your mouse wheel will also zoom the scene. Hold down the Shift key to pan, zoom, and rotate in larger increments to speed things up. This is a way for you to navigate around the game world. It doesn't actually impact the way the player sees the game. To modify the Game view, you need to use the Move or Rotate tools to modify the Camera position.
The Move tool (W): This tool lets you move the Game Objects around your scene. You can either drag the object(s) around by the X, or Y, or Z-axis handles, or by the square in the center for freeform movement. Holding down the Ctrl key will snap movement to set grid increments. We saw this tool when we were positioning the First Person Controller Prefab in the middle of the sky.
Rotate tool (E): Use it to spin your objects around using a neat spherical gizmo. The red, green, and blue lines map to the X, Y, and Z axes.
Scale tool ®: This tool works much the same as the Move and Rotate tools. Use it to make your Game Objects larger or smaller. Dragging an X, Y, or Z handle will non-uniformly scale (squash and stretch) the object, while dragging the gray cube in the center will uniformly scale it.

Don't stop there—live a little!
We've glanced briefly at the key elements of the Unity interface, but there's no need to stop poking around. Far beyond the scope of this article, there is a wealth of menu options, buttons, and controls that we haven't covered. Why not explore those menus or start randomly clicking on things that you don't yet understand? Now is the time to safely break stuff. You didn't work hard to create the Island Demo, so why not mess around with it a little bit?

Here are some things to try:

Select some of the Game Objects in the Hierarchy panel and move them around in the Scene window using the Scene controls. What happens when you put the bridge in the middle of the sky? Can you make one of the birds fly into a tree? What happens when you walk way out into the ocean while testing the game?
Randomly right-click in the three different panels and read through the context menu options to see what you're getting yourself into.
Poke around in the GameObject | Create Other menu. There's a whole list of interesting things that you can add to this scene without even touching the 3D modeling program.
What happens when you delete the lights from the scene? Or the camera? Can you add another camera? More lights? How does that affect the Scene?
Can you move the First Person Controller Prefab to another part of the island to change your starting position? How about starting on top of those two gigantic rocks on the beach?
Can you replace the audio files to make the seagulls sound like car horns?
Download a picture of kittens from the Internet and see if you can wrap it around the boulder model. Kittens rock! You can pull the kittens into your project using the Assets | Import New Asset option in the menu.

A tuner's paradise
The Unity 3D interface is designed to be customized. Not only can you define your own custom window layouts, but you can even write custom scripts to make certain buttons and panels appear inside Unity to speed up your workflow. That kind of thing is well beyond the scope of this article, but if you're the kind of person who really likes to get under the hood, you'll be happy to know that you can tweak Unity 3D to your heart's content—maybe add a few racing stripes and install an enormous pair of subwoofers in the back?

Summary
This article was all about getting a feel for what Unity can do and for what the program interface had to offer. Here's what we found out:

Massive 80 person teams, all the way down to tiny one- or two-person teams are using Unity to create fun games.
By thinking small, we'll have more success in learning Unity and producing fully functional games instead of huge but half-baked abandoned projects.
Different flavors of Unity help us deploy our games to different platforms. By using the free indie version, we can deploy to the Web, and the Mac and PC platforms.
The Unity interface has controls and panels that let us visually compose our game assets, and test games on the fly right inside the program!

I hope you've taken some time to thoroughly vandalize the Island Demo. Save the file by clicking on File | Save Project in case you want to come back and wreak more havoc a little later.

How to Do Gesture Recognition With Kinect Using...

Tue, 21 Feb 2012 11:57:12 +0000

GLSL 4.0: Discarding Fragments to Create a Perf...

Tue, 07 Feb 2012 02:41:41 +0000

Fragment shaders can make use of the discard keyword to "throw away" fragments. Use of this keyword causes the fragment shader to stop execution, without writing anything (including depth) to the output buffer. This provides a way to create holes in polygons without using blending. In fact, since fragments are completely discarded, there is no dependence on the order in which objects are drawn, saving us the trouble of doing any depth sorting that might have been necessary if blending was used. In this recipe by David Wolff, author of OpenGL 4.0 Shading Language Cookbook, we'll draw a teapot, and use the discard keyword to remove fragments selectively based on texture coordinates.

The result will look like the following image:

Getting ready
The vertex position, normal, and texture coordinates must be provided to the vertex shader from the OpenGL application. The position should be provided at location 0, the normal at location 1, and the texture coordinates at location 2. As in previous examples, the lighting parameters must be set from the OpenGL application via the appropriate uniform variables.

How to do it...
To create a shader program that discards fragments based on a square lattice (as in the preceding image), use the following code:

Use the following code for the vertex shader:

#version 400

layout (location = 0) in vec3 VertexPosition;
layout (location = 1) in vec3 VertexNormal;
layout (location = 2) in vec2 VertexTexCoord;

out vec3 FrontColor;
out vec3 BackColor;
out vec2 TexCoord;

struct LightInfo {
  vec4 Position; // Light position in eye coords.
  vec3 La; // Ambient light intensity
  vec3 Ld; // Diffuse light intensity
  vec3 Ls; // Specular light intensity
};
uniform LightInfo Light;

struct MaterialInfo {
  vec3 Ka; // Ambient reflectivity
  vec3 Kd; // Diffuse reflectivity
  vec3 Ks; // Specular reflectivity
  float Shininess; // Specular shininess factor
};
uniform MaterialInfo Material;

uniform mat4 ModelViewMatrix;
uniform mat3 NormalMatrix;
uniform mat4 ProjectionMatrix;
uniform mat4 MVP;

void getEyeSpace( out vec3 norm, out vec4 position )
{
  norm = normalize( NormalMatrix * VertexNormal);
  position = ModelViewMatrix * vec4(VertexPosition,1.0);
}

vec3 phongModel( vec4 position, vec3 norm )
{
  // The ADS shading calculations go here (see: "Using
  // functions in shaders," and "Implementing
  // per-vertex ambient, diffuse and specular (ADS) shading")
  ...
}

void main()
{
  vec3 eyeNorm;
  vec4 eyePosition;

  TexCoord = VertexTexCoord;

  // Get the position and normal in eye space
  getEyeSpace(eyeNorm, eyePosition);

  FrontColor = phongModel( eyePosition, eyeNorm );
  BackColor = phongModel( eyePosition, -eyeNorm );

  gl_Position = MVP * vec4(VertexPosition,1.0);
}

Use the following code for the fragment shader:

#version 400

in vec3 FrontColor;
in vec3 BackColor;
in vec2 TexCoord;

layout( location = 0 ) out vec4 FragColor;

void main() {
  const float scale = 15.0;
  bvec2 toDiscard = greaterThan( fract(TexCoord * scale),
								 vec2(0.2,0.2) );

if( all(toDiscard) )
	discard;

if( gl_FrontFacing )
	FragColor = vec4(FrontColor, 1.0);
else
	FragColor = vec4(BackColor, 1.0);
}

Compile and link both shaders within the OpenGL application, and install the shader program prior to rendering.

How it works...
Since we will be discarding some parts of the teapot, we will be able to see through the teapot to the other side. This will cause the back sides of some polygons to become visible. Therefore, we need to compute the lighting equation appropriately for both sides of each face. We'll use the same technique presented earlier in the two-sided shading recipe.

The vertex shader is essentially the same as in the two-sided shading recipe, with the main difference being the addition of the texture coordinate. The differences are highlighted in the above listing. To manage the texture coordinate, we have an additional input variable, VertexTexCoord, that corresponds to attribute location 2. The value of this input variable is passed directly on to the fragment shader unchanged via the output variable TexCoord. The ADS shading model is calculated twice, once using the given normal vector, storing the result in FrontColor, and again using the reversed normal, storing that result in BackColor.

In the fragment shader, we calculate whether or not the fragment should be discarded based on a simple technique designed to produce the lattice-like pattern shown in the preceding image. We first scale the texture coordinate by the arbitrary scaling factor scale. This corresponds to the number of lattice rectangles per unit (scaled) texture coordinate. We then compute the fractional part of each component of the scaled texture coordinate using the built-in function fract. Each component is compared to 0.2 using the built-in function greaterThan, and the result is stored in the bool vector toDiscard. The greaterThan function compares the two vectors component-wise, and stores the Boolean results in the corresponding components of the return value.

If both components of the vector toDiscard are true, then the fragment lies within the inside of each lattice frame, and therefore we wish to discard this fragment. We can use the built-in function all to help with this check. The function all will return true if all of the components of the parameter vector are true. If the function returns true, we execute the discard statement to reject the fragment.

In the else branch, we color the fragment based on the orientation of the polygon, as in the two-sided shading recipe presented earlier.

Summary
This recipe showed us how to use the discard keyword to "throw away" fragments and create a perforated look.

GLSL 4.0: Using Subroutines to Select Shader Fu...

Fri, 03 Feb 2012 02:41:38 +0000

In GLSL, a subroutine is a mechanism for binding a function call to one of a set of possible function definitions based on the value of a variable. Subroutines therefore provide a way to select alternate implementations at runtime without swapping shader programs and/or recompiling, or using if statements along with a uniform variable.

In this article by David Wolff, author of OpenGL 4.0 Shading Language Cookbook, we'll demonstrate the use of subroutines by rendering a teapot twice. The first teapot will be rendered with the full ADS shading model described earlier. The second teapot will be rendered with diffuse shading only. A subroutine uniform will be used to choose between the two shading techniques.

In many ways it is similar to function pointers in C. A uniform variable serves as the pointer and is used to invoke the function. The value of this variable can be set from the OpenGL side, thereby binding it to one of a few possible definitions. The subroutine's function definitions need not have the same name, but must have the same number and type of parameters and the same return type.

A single shader could be written to provide several shading algorithms intended for use on different objects within the scene. When rendering the scene, rather than swapping shader programs (or using a conditional statement), we can simply change the subroutine's uniform variable to choose the appropriate shading algorithm as each object is rendered.

Since performance is crucial in shader programs, avoiding a conditional statement or a shader swap can be very valuable. With subroutines, we can implement the functionality of a conditional statement or shader swap without the computational overhead.

In the following image, we see an example of a rendering that was created using subroutines. The teapot on the left is rendered with the full ADS shading model, and the teapot on the right is rendered with diffuse shading only. A subroutine is used to switch between shader functionality.

Getting ready
As with previous recipes, provide the vertex position at attribute location 0 and the vertex normal at attribute location 1. Uniform variables for all of the ADS coefficients should be set from the OpenGL side, as well as the light position and the standard matrices.

We'll assume that, in the OpenGL application, the variable programHandle contains the handle to the shader program object.

How to do it...
To create a shader program that uses a subroutine to switch between pure-diffuse and ADS shading, use the following code:

Use the following code for the vertex shader:

#version 400

subroutine vec3 shadeModelType( vec4 position, vec3 normal);

subroutine uniform shadeModelType shadeModel;

layout (location = 0) in vec3 VertexPosition;
layout (location = 1) in vec3 VertexNormal;

out vec3 LightIntensity;

struct LightInfo {
  vec4 Position; // Light position in eye coords.
  vec3 La; // Ambient light intensity
  vec3 Ld; // Diffuse light intensity
  vec3 Ls; // Specular light intensity
};
uniform LightInfo Light;

struct MaterialInfo {
  vec3 Ka; // Ambient reflectivity
  vec3 Kd; // Diffuse reflectivity
  vec3 Ks; // Specular reflectivity
  float Shininess; // Specular shininess factor
};
uniform MaterialInfo Material;

uniform mat4 ModelViewMatrix;
uniform mat3 NormalMatrix;
uniform mat4 ProjectionMatrix;
uniform mat4 MVP;

void getEyeSpace( out vec3 norm, out vec4 position )
{
  norm = normalize( NormalMatrix * VertexNormal);
  position = ModelViewMatrix * vec4(VertexPosition,1.0);
}

subroutine( shadeModelType )

vec3 phongModel( vec4 position, vec3 norm )
{
  // The ADS shading calculations go here (see: "Using
  // functions in shaders," and "Implementing
  // per-vertex ambient, diffuse and specular (ADS) shading")
  ...
}

subroutine( shadeModelType )

vec3 diffuseOnly( vec4 position, vec3 norm )
{
  vec3 s = normalize( vec3(Light.Position - position) );
  return
	  Light.Ld * Material.Kd * max( dot(s, norm), 0.0 );
}

void main()
{
  vec3 eyeNorm;
  vec4 eyePosition;

  // Get the position and normal in eye space

  getEyeSpace(eyeNorm, eyePosition);

  // Evaluate the shading equation. This will call one of
  // the functions: diffuseOnly or phongModel.
  LightIntensity = shadeModel( eyePosition, eyeNorm );

  gl_Position = MVP * vec4(VertexPosition,1.0);
}

Use the following code for the fragment shader:

#version 400

in vec3 LightIntensity;

layout( location = 0 ) out vec4 FragColor;

void main() {
FragColor = vec4(LightIntensity, 1.0);
}

In the OpenGL application, compile and link the above shaders into a shader program, and install the program into the OpenGL pipeline.

Within the render function of the OpenGL application, use the following code:

GLuint adsIndex =
glGetSubroutineIndex( programHandle,
					 GL_VERTEX_SHADER,"phongModel" );
GLuint diffuseIndex =
  glGetSubroutineIndex(programHandle,
					   GL_VERTEX_SHADER, "diffuseOnly");

glUniformSubroutinesuiv( GL_VERTEX_SHADER, 1, &adsIndex);
... // Render the left teapot

glUniformSubroutinesuiv( GL_VERTEX_SHADER, 1, &diffuseIndex);
... // Render the right teapot

How it works...
In this example, the subroutine is defined within the vertex shader. The first step involves declaring the subroutine type.

subroutine vec3 shadeModelType( vec4 position,
					 vec3 normal);

This defines a new subroutine type with the name shadeModelType. The syntax is very similar to a function prototype, in that it defines a name, a parameter list, and a return type. As with function prototypes, the parameter names are optional.

After creating the new subroutine type, we declare a uniform variable of that type named shadeModel.

subroutine uniform shadeModelType shadeModel;

This variable serves as our function pointer and will be assigned to one of the two possible functions in the OpenGL application.

We declare two functions to be part of the subroutine by prefixing their definition with the subroutine qualifier:

subroutine ( shadeModelType )

This indicates that the function matches the subroutine type, and therefore its header must match the one in the subroutine type definition. We use this prefix for the definition of the functions phongModel and diffuseOnly. The diffuseOnly function computes the diffuse shading equation, and the phongModel function computes the complete ADS shading equation.

We call one of the two subroutine functions by utilizing the subroutine uniform shadeModel within the main function.

LightIntensity = shadeModel( eyePosition, eyeNorm );

Again, this call will be bound to one of the two functions depending on the value of the subroutine uniform shadeModel, which we will set within the OpenGL application.

Within the render function of the OpenGL application, we assign a value to the subroutine uniform with the following steps. First, we query for the index of each subroutine function using glGetSubroutineIndex. The first argument is the program handle. The second is the shader stage. In this case, the subroutine is defined within the vertex shader, so we use GL_VERTEX_SHADER here. The third argument is the name of the subroutine. We query for each function individually and store the indexes in the variables adsIndex and diffuseIndex.

To select the appropriate subroutine function, we need to set the value of the subroutine uniform shadeModel. To do so, we call glUniformSubroutinesuiv. This function is designed for setting multiple subroutine uniforms at once. In our case, of course, we are setting only a single uniform. The first argument is the shader stage (GL_VERTEX_SHADER), the second is the number of uniforms being set, and the third is a pointer to an array of subroutine function indexes. Since we are setting a single uniform, we simply provide the address of the GLuint variable containing the index, rather than a true array of values. Of course, we would use an array if multiple uniforms were being set. In general, the array of values provided as the third argument is assigned to subroutine uniform variables in the following way. The ith element of the array is assigned to the subroutine uniform variable with index i. Since we have provided only a single value, we are setting the subroutine uniform at index zero.

You may be wondering, "How do we know that our subroutine uniform is located at index zero? We didn't query for the index before calling glUniformSubroutinesuiv!" The reason that this code works is that we are relying on the fact that OpenGL will always number the indexes of the subroutines consecutively starting at zero. If we had multiple subroutine uniforms, we could (and should) query for their indexes using glGetSubroutineUniformLocation, and then order our array appropriately.

Finally, we select the phongModel function by setting the uniform to adsIndex and then render the left teapot. We then select the diffuseOnly function by setting the uniform to diffuseIndex and render the right teapot.

There's more...
A subroutine function defined in a shader can match multiple subroutine types. In that case, the subroutine qualifier can contain a comma-separated list of subroutine types. For example, if a subroutine matched the types type1 and type2, we could use the following qualifier:

subroutine( type1, type2 )

This would allow us to use subroutine uniforms of differing types to refer to the same subroutine function.

Summary
With subroutines we can implement the functionality of a conditional statement or shader swap without the computational overhead.

Building a Complete Board-based Puzzle Game wit...

Wed, 01 Feb 2012 17:51:05 +0000

This article by Kurt Jaegers, author of XNA 4.0 Game Development by Example: Beginner's Guide, introduces a board-based puzzle game called Flood Control. We introduce the XNA Content Pipeline, and build a recursive function to determine the state of the game board while playing.

This article focuses on the following concepts:

Using the Content Pipeline to load textures from disk
Creating classes to divide code into logical units
Recursively evaluating the status of the game board to check for scoring chains
Drawing textures using the SpriteBatch.Draw() method
Managing simple game states

It was just another day at the bottom of the ocean until an explosion in one of the storage bays cracked the protective dome around Deep Sea Research Lab Alpha. Now the entire place is flooding, and the emergency pump system is a chaotic jumble of loose parts.

Designing a puzzle game
The Puzzler has always been a popular game genre. From old standbys like Tetris to modern crazes like Bejeweled, puzzle games are attractive to players because they do not require a long-term time investment or a steep learning curve.

The game mechanic is the heart of any good puzzle game. This mechanic is usually very simple, with perhaps a few twists to keep the players on their toes.

In Flood Control, the player will be faced with a board containing 80 pieces of pipe. Some will be straight pipes and some will be curved. The objective of the game is to rotate the pipes to form a continuous line to pump water from the left side of the board to the right side of the board.

Completing a section of pipe drains water out of the base and scores points for the player, but destroys the pipes used. New pipes will fall into place for the player to begin another row.

Time for action - set up the Flood Control projectWhat just happened?
You have now set up a workspace for building Flood Control, and created a couple of folders for organizing game content. You have also imported the sample graphics for the Flood Control game into the project.

Introducing the Content Pipeline
The Flood ControlContent (Content) project inside Solution Explorer is a special kind of project called a Content Project. Items in your game's content project are converted into .XNB resource files by Content Importers and Content Processors.

If you right-click on one of the image files you just added to the Flood Control project and select Properties, you will see that for both the Importer and Processor, the Content Pipeline will use Texture - XNA Framework. This means that the Importer will take the file in its native format (.PNG in this case) and convert it to a format that the Processor recognizes as an image. The Processor then converts the image into an .XNB file which is a compressed binary format that XNA's content manager can read directly into a Texture2D object.

There are Content Importer/Processor pairs for several different types of content—images, audio, video, fonts, 3D models, and shader language effects files. All of these content types get converted to .XNB files which can be used at runtime.

In order to see how to use the Content Pipeline at runtime, let's go ahead and write the code to read these textures into memory when the game starts:

Time for action - reading textures into memory

Double-click on Game1.cs in Solution Explorer to open it or bring it to the front if it is already open.

In the Class Declarations area of Game1 (right below SpriteBatch spriteBatch;), add:

	
Texture2D playingPieces;
	Texture2D backgroundScreen;
	Texture2D titleScreen;

Add code to load each of the Texture2D objects at the end of LoadContent():

	
playingPieces = Content.Load(@"Textures\Tile_Sheet");
	backgroundScreen = 
		Content.Load(@"Textures\Background");
	titleScreen = Content.Load(@"Textures\TitleScreen");

What just happened?
In order to load the textures from disk, you need an in-memory object to hold them. These are declared as instances of the Texture2D class.

A default XNA project sets up the Content instance of the ContentManager class for you automatically. The Content object's Load() method is used to read .XNB files from disk and into the Texture2D instances declared earlier.

One thing to note here is that the Load() method requires a type identifier, specified in angled brackets (), before the parameter list. Known in C# as a "Generic", many classes and methods support this kind of type specification to allow code to operate on a variety of data types. We will make more extensive use of Generics later when we need to store lists of objects in memory. The Load() method is used not only for textures, but also for all other kinds of content (sounds, 3D models, fonts, etc.) as well. It is important to let the Load() method know what kind of data you are reading so that it knows what kind of object to return.

Sprites and sprite sheets
As far as XNA and the SpriteBatch class are concerned, a sprite is a 2D bitmapped image that can be drawn either with or without transparency information to the screen.

Sprites vs. Textures
XNA defines a "sprite" as a 2D bitmap that is drawn directly to the screen. While these bitmaps are stored in Texture2D objects, the term "texture" is used when a 2D image is mapped onto a 3D object, providing a visual representation of the surface of the object. In practice, all XNA graphics are actually performed in 3D, with 2D sprites being rendered via special configurations of the XNA rendering engine.

The simple form of the SpriteBatch.Draw() call when drawing squares only needs three parameters: a Texture2D to draw, a Rectangle indicating where to draw it, and a Color to specify the tint to overlay onto the sprite.

Other overloads of the Draw() method, however, also allow you to specify a Rectangle representing the source area within the Texture2D to copy from. If no source Rectangle is specified, the entire Texture2D is copied and resized to fit the destination Rectangle.

Overloads
When multiple versions of the same method are declared with either different parameters lists or different return values, each different declaration is called an "overload" of the method. Overloads allow methods to work with different types of data (for example, when setting a position you could accept two separate X and Y coordinates or a Vector2 value), or leave out parameters that can then be assigned default values.

By specifying a source Rectangle, however, individual pieces can be pulled from a large image. A bitmap with multiple sprites on it that will be drawn this way is called a "sprite sheet".

The Tile_Sheet.png file for the Flood Control project is a sprite sheet containing 13 different sprites that will be used to represent the pieces of pipe used in the game. Each image is 40 pixels wide and 40 pixels high, with a one pixel border between each sprite and also around the entire image. When we call SpriteBatch.Draw() we can limit what gets drawn from our texture to one of these 40 by 40 squares, allowing a single texture to hold all of the playing piece images that we need for the game:

The Tile_Sheet.png file was created with alpha-based transparency. When it is drawn to the screen, the alpha level of each pixel will be used to merge that pixel with any color that already occupies that location on the screen.

Using this fact, you can create sprites that don't look like they are rectangular. Internally, you will still be drawing rectangles, but visually the image can be of any shape.

What we really need now to be able to work with the playing pieces is a way to reference an individual piece, knowing not only what to draw to the screen, but what ends of the pipe connect to adjacent squares on the game board.

Alpha blending
Each pixel in a sprite can be fully opaque, fully transparent, or partially transparent. Fully opaque pixels are drawn directly, while fully transparent pixels are not drawn at all, leaving whatever has already been drawn to that pixel on the screen unchanged. In 32-bit color mode, each channel of a color (Red, Green, Blue, and Alpha) are represented by 8 bits, meaning that there are 256 different degrees of transparency between fully opaque (255) and fully transparent (0). Partially transparent pixels are combined with the current pixel color at that location to create a mixed color as if the pixels below were being seen through the new color.

Classes used in Flood Control
While it would certainly be possible to simply pile all of the game code into the Game1 class, the result would be difficult to read and manage later on. Instead, we need to consider how to logically divide the game into classes that can manage themselves and help to organize our code.

A good rule of thumb is that a class should represent a single thing or type of thing. If you can say "This object is made up of these other objects" or "This object contains these objects", consider creating classes to represent those relationships.

The Flood Control game contains a game board made up of 80 pipes. We can abstract these pipes as a class called GamePiece, and provide it with the code it needs to handle rotation and provide the code that will display the piece with a Rectangle that can be used to pull the sprite off the sprite sheet.

The game board itself can be represented by a GameBoard class, which will handle managing individual GamePiece objects and be responsible for determining which pieces should be filled with water and which ones should be empty.

The GamePiece class
The GamePiece class represents an individual pipe on the game board. One GamePiece has no knowledge of any other game pieces (that is the responsibility of the GameBoard class), but it will need to be able to provide information about the pipe to objects that use the GamePiece class. Our class has the following requirements:

Identify the sides of each piece that contain pipe connectors
Differentiate between game pieces that are filled with water and that are empty
Allow game pieces to be updated
Automatically handle rotation by changing the piece type to the appropriate new piece type
Given one side of a piece, provide the other sides of the piece in order to facilitate determining where water can flow through the game board
Provide a Rectangle that will be used when the piece is drawn, to locate the graphic for the piece on the sprite sheet

Identifying a GamePiece
While the sprite sheet contains thirteen different images, only twelve of them are actual game pieces (the last one is an empty square). Of the twelve remaining pieces, only six of them are unique pieces. The other six are the water-filled versions of the first six images.

Each of the game pieces can be identified by which sides of the square contain a connecting pipe. This results in two straight pieces and four pieces with 90 degree bends in them.

A second value can be tracked to determine if the piece is filled with water or not instead of treating filled pieces as separate types of pieces.

Time for action - build a GamePiece class - declarations

Switch back to your Visual C# window if you have your image editor open.
Right-click on Flood Control in Solution Explorer and select Add | Class...
Name the class GamePiece.cs and click on Add.
At the top of the GamePiece.cs file, add the following to the using directives already in the class:
```
	
using Microsoft.Xna.Framework.Graphics;
	using Microsoft.Xna.Framework;	
	
```

In the class declarations section, add the following:

	
public static string[] PieceTypes = 
	{ 
	  "Left,Right", 
	  "Top,Bottom", 
	  "Left,Top", 
	  "Top,Right",
	  "Right,Bottom", 
	  "Bottom,Left",
	  "Empty"
	};
	
	public const int PieceHeight = 40;
	public const int PieceWidth = 40;
	
	public const int MaxPlayablePieceIndex = 5;
	public const int EmptyPieceIndex = 6;
	
	private const int textureOffsetX = 1;
	private const int textureOffsetY = 1;
	private const int texturePaddingX = 1;
	private const int texturePaddingY = 1;
	
	private string pieceType = "";
	private string pieceSuffix = "";

Add two properties to retrieve information about the piece:

	
public string PieceType
	{
		get { return pieceType; }
	}
	
	public string Suffix
	{
		get { return pieceSuffix; }
	}

What just happened?
You have created a new code file called GamePiece.cs and included the using statements necessary to access the pieces of the XNA Framework that the class will use.

Using Directives
Adding the XNA Framework using directives at the top of the class file allows you to access classes like Rectangle and Vector2 without specifying their full assembly names. Without these statements, you would need Microsoft.Xna.Framework.Rectangle in your code every time you reference the type, instead of simply typing Rectangle.

In the declarations area, you have added an array called PieceTypes that gives a name to each of the different types of game pieces that will be added to the game board. There are two straight pieces, four angled pieces, and an empty tile with a background image on it, but no pipe. The array is declared as static because all instances of the GamePiece class will share the same array. A static member can be updated at execution time, but all members of the class will see the same changes.

Then, you have declared two integer constants that specify the height and width of an individual playing piece in pixels, along with two variables that specify the array index of the last piece that can be placed on the board (MaxPlayablePieceIndex) and of the fake "Empty" piece.

Next are four integers that describe the layout of the texture file you are using. There is a one pixel offset from the left and top edge of the texture (the one pixel border) and a single pixel of padding between each sprite on the sprite sheet.

Constants vs. Numeric literals
Why create constants for things like PieceWidth and PieceHeight and have to type them out when you could simply use the number 40 in their place? If you need to go back and resize your pieces later, you only need to change the size in one place instead of hoping that you find each place in the code where you entered 40 and change them all to something else. Even if you do not change the number in the game you are working on, you may reuse the code for something else later and having easily changeable parameters will make the job much easier.

There are only two pieces of information that each instance of GamePiece will track about itself—the type of the piece and any suffix associated with the piece. The instance members pieceType and pieceSuffix store these values. We will use the suffix to determine if the pipe that the piece represents is empty or filled with water.

However, these members are declared as private in order to prevent code outside the class from directly altering the values. To allow them to be read but not written to, we create a pair of properties (pieceType and pieceSuffix) that contain get blocks but no set blocks. This makes these values accessible in a read-only mode to code outside the GamePiece class.

Creating a GamePiece
The only information we need to create an instance of GamePiece is the piece type and, potentially, the suffix.

Time for action - building a GamePiece class: constructors

Add two constructors to your GamePiece.cs file after the declarations:

	
public GamePiece(string type, string suffix)
	{
		pieceType=type;
		pieceSuffix=suffix;
	}
	
	public GamePiece(string type)
	{
		pieceType=type;
		pieceSuffix="";
	}

What just happened?
A constructor is run when an instance of the GamePiece class is created. By specifying two constructors, we will allow future code to create a GamePiece by specifying a piece type with or without a suffix. If no suffix is specified, an empty suffix is assumed.

Updating a GamePiece
When a GamePiece is updated, you can change the piece type, the suffix, or both.

Time for action - GamePiece class methods - part 1 - updating

Add the following methods to the GamePiece class:

	
public void SetPiece(string type, string suffix)
	{
		pieceType = type;
		pieceSuffix = suffix;
	}
	
	public void SetPiece(string type)
	{
		  SetPiece(type,"");
	}
	
	public void AddSuffix(string suffix)
	{
		if (!pieceSuffix.Contains(suffix))
			pieceSuffix += suffix;
	}
	
	public void RemoveSuffix(string suffix)
	{
		pieceSuffix = pieceSuffix.Replace(suffix, "");
	}

The first two methods are overloads with the same name, but different parameter lists. In a manner similar to the GamePiece constructors, code that wishes to update a GamePiece can pass it a piece type, and optionally a suffix.

Additional methods have been added to modify suffixes without changing the pieceType associated with the piece. The AddSuffix() method first checks to see if the piece already contains the suffix. If it does, nothing happens. If it does not, the suffix value passed to the method is added to the pieceSuffix member variable.

The RemoveSuffix() method uses the Replace() method of the string class to remove the passed suffix from the pieceSuffix variable.

Rotating pieces
The heart of the Flood Control play mechanic is the ability of the player to rotate pieces on the game board to form continuous pipes. In order to accomplish this, we can build a table that, given an existing piece type and a rotation direction, supplies the name of the piece type after rotation. We can then implement this code as a switch statement:

Time for action - GamePiece class methods - part 2 - rotation

Add the RotatePiece() method to the GamePiece class:

	
public void RotatePiece(bool Clockwise)
	{
		 switch (pieceType)
		{
			case "Left,Right":
				pieceType = "Top,Bottom";
				break;
			case "Top,Bottom":
				pieceType = "Left,Right";
				break;
			case "Left,Top":
				if (Clockwise)
					pieceType = "Top,Right";
				else
					pieceType = "Bottom,Left";
				break;
			case "Top,Right":
				if (Clockwise)
					pieceType = "Right,Bottom";
				else
					pieceType = "Left,Top";
				break;
			case "Right,Bottom":
				if (Clockwise)
					pieceType = "Bottom,Left";
				else
					pieceType = "Top,Right";
				break;
			case "Bottom,Left":
				if (Clockwise)
					pieceType = "Left,Top";
				else
					pieceType = "Right,Bottom";
				break;
			case "Empty":
				break;
		}
	}

What just happened?
The only information the RotatePiece() method needs is a rotation direction. For straight pieces, rotation direction doesn't matter (a left/right piece will always become a top/bottom piece and vice versa).

For angled pieces, the piece type is updated based on the rotation direction and the diagram above.

Why all the strings?
It would certainly be reasonable to create constants that represent the various piece positions instead of fully spelling out things like Bottom,Left as strings. However, because the Flood Control game is not taxing on the system, the additional processing time required for string manipulation will not impact the game negatively and helps clarify how the logic works.

Pipe connectors
Our GamePiece class will need to be able to provide information about the connectors it contains (Top, Bottom, Left, and Right) to the rest of the game. Since we have represented the piece types as simple strings, a string comparison will determine what connectors the piece contains.

Time for action - GamePiece class methods - part 3 -connection methods

Add the GetOtherEnds() method to the GamePiece class:

	
public string[] GetOtherEnds(string startingEnd)
	{
		List opposites = new List();
	
		foreach (string end in pieceType.Split(','))
		{
			if (end != startingEnd)
				opposites.Add(end);
		}
		 return opposites.ToArray();
	}

Add the HasConnector() method to the GamePiece class:

	
public bool HasConnector(string direction)
	{
		return pieceType.Contains(direction);
	}

The GetOtherEnds() method creates an empty List object for holding the ends we want to return to the calling code. It then uses the Split() method of the string class to get each end listed in the pieceType. For example, the Top,Bottom piece will return an array with two elements. The first element will contain Top and the second will contain Bottom. The comma delimiter will not be returned with either string.

If the end in question is not the same as the startingEnd parameter that was passed to the method, it is added to the list. After all of the items in the string have been examined, the list is converted to an array and returned to the calling code.

In the previous example, requesting GetOtherEnds("Top") from a GamePiece with a pieceType value of Top,Bottom will return a string array with a single element containing Bottom.

We will need this information in a few moments when we have to figure out which pipes are filled with water and which are empty.

The second function, HasConnector() simply returns "true" if the pieceType string contains the string value passed in as the direction parameter. This will allow code outside the GamePiece class to determine if the piece has a connector facing in any particular direction.

Sprite sheet coordinates
Because we set up the PieceTypes array listing the pieces in the same order that they exist on the sprite sheet texture, we can calculate the position of the rectangle to draw from based on the pieceType.

Time for action - GamePiece class methods - part 4 - GetSourceRect

Add the GetSourceRect() method to the GamePiece class:

	
public Rectangle GetSourceRect()
	{
		int x = textureOffsetX;
		int y = textureOffsetY;
	
		if (pieceSuffix.Contains("W"))
			x += PieceWidth + texturePaddingX;
	
		y += (Array.IndexOf(PieceTypes, pieceType) * 
			 (PieceHeight + texturePaddingY));
	
	
		return new Rectangle(x, y, PieceWidth, PieceHeight);
	}

What just happened?
Initially, the x and y variables are set to the textureOffsets that are listed in the GamePiece class declaration. This means they will both start with a value of one.

Because the sprite sheet is organized with a single type of pipe on each row, the x coordinate of the Rectangle is the easiest to determine. If the pieceSuffix variable does not contain a W (signifying that the piece is filled with water), the x coordinate will simply remain 1.

If the pieceSuffix does contain the letter W (indicating the pipe is filled), the width of a piece (40 pixels), along with the padding between the pieces (1 pixel), are added to the x coordinate of the source Rectangle. This shifts the x coordinate from 1 to a value of 1 + 40 + 1, or 42 which corresponds to the second column of images on the sprite sheet.

To determine the y coordinate for the source rectangle, Array.IndexOf(PieceTypes, pieceType) is used to locate the pieceType within the PieceTypes array. The index that is returned represents the position of the tile on the sprite sheet (because the array is organized in the same order as the pieces on the image). For example, Left,Right returns zero, while Top,Bottom returns one and Empty returns six.

The value of this index is multiplied by the height of a game piece plus the padding between pieces. For our sprite sheet, an index of 2 (the Left,Top piece) would be multiplied by 41 (PieceHeight of 40 plus texturePaddingY of 1) resulting in a value of 82 being added to the y variable.

Finally, the new Rectangle is returned, comprised of the calculated x and y coordinates and the predefined width and height of a piece:

The GameBoard class
Now that we have a way to represent pieces in memory, the next logical step is to create a way to represent an entire board of playing pieces.

The game board is a two-dimensional array of GamePiece objects, and we can build in some additional functionality to allow our code to interact with pieces on the game board by their X and Y coordinates.

The GameBoard class needs to:

Store a GamePiece object for each square on the game board
Provide methods for code using the GameBoard to update individual pieces by passing calls through to the underlying GamePiece instances
Randomly assign a piece type to a GamePiece
Set and clear the "Filled with water" flags on individual GamePieces
Determine which pipes should be filled with water based on their position and orientation and mark them as filled
Return lists of potentially scoring water chains to code using the GameBoard

Time for action - create the GameBoard.cs class

As you did to create the GamePiece class, right-click on Flood Control in Solution Explorer and select Add | Class... Name the new class file GameBoard.cs.
Add the using directive for the XNA framework at the top of the file:
```
	
using Microsoft.Xna.Framework;	
	
```

Add the following declarations to the GameBoard class:

	
Random rand = new Random();
	
	public const int GameBoardWidth = 8;
	public const int GameBoardHeight = 10;
	
	private GamePiece[,] boardSquares = 
	  new GamePiece[GameBoardWidth, GameBoardHeight];
	
	private List WaterTracker = new List();

What just happened?
We used the Random class in SquareChase to generate random numbers. Since we will need to randomly generate pieces to add to the game board, we need an instance of Random in the GameBoard class.

The two constants and the boardSquares array provide the storage mechanism for the GamePiece objects that make up the 8 by 10 piece board.

Finally, a List of Vector2 objects is declared that we will use to identify scoring pipe combinations. The List class is one of C#'s Generic Collection classes—classes that use the Generic templates (angle brackets) we first saw when loading a texture for SquareChase. Each of the Collection classes can be used to store multiple items of the same type, with different methods to access the entries in the collection. We will use several of the Collection classes in our projects. The List class is much like an array, except that we can add any number of values at runtime, and remove values in the List if necessary.

A Vector2 is a structure defined by the XNA Framework that holds two floating point values, X and Y. Together the two values represent a vector pointing in any direction from an imaginary origin (0, 0) point. We will use Vector2 structures to represent the locations on our game board in Flood Control, placing the origin in the upper left corner of the board.

Creating the game board
If we were to try to use any of the elements in the boardSquares array, at this point, we would get a Null Reference exception because none of the GamePiece objects in the array have actually been created yet.

Time for action - initialize the game board

Add a constructor to the GameBoard class:

	
public GameBoard()
	{
	  ClearBoard();
	}

Add the ClearBoard() helper method to the GameBoard class:

	
public void ClearBoard()
	{
		for (int x = 0; x		 for (int y = 0; y			 boardSquares[x, y] = new GamePiece("Empty");
	}

What just happened?
When a new instance of the GameBoard class is created, the constructor calls the ClearBoard() helper method, which simply creates 80 empty game pieces and assigns them to each element in the array.

Helper methods
Why not simply put the two for loops that clear the board into the GameBoard constructor? Splitting the work into methods that accomplish a single purpose greatly helps to keep your code both readable and maintainable. Additionally, by splitting ClearBoard() out as its own method we can call it separately from the constructor. When we add increasing difficulty levels, we make use of this call when a new level starts.

Updating GamePieces
The boardSquares array in the GameBoard class is declared as a private member, meaning that the code that uses the GameBoard will not have direct access to the pieces contained on the board.

In order for code in our Game1 class to interact with a GamePiece, we will need to create public methods in the GameBoard class that expose the pieces in boardSquares.

Time for action - manipulating the game board

Add public methods to the GameBoard class to interact with GamePiece:

	
public void RotatePiece(int x, int y, bool clockwise)
	{
		boardSquares[x, y].RotatePiece(clockwise);
	}
	
	public Rectangle GetSourceRect(int x, int y)
	{
		return boardSquares[x, y].GetSourceRect();
	}
	
	public string GetSquare(int x, int y)
	{
		return boardSquares[x, y].PieceType;
	}
	
	public void SetSquare(int x, int y, string pieceName)
	{
		boardSquares[x, y].SetPiece(pieceName);
	}
	
	public bool HasConnector(int x, int y, string direction)
	{
		return boardSquares[x, y].HasConnector(direction); 
	}
	
	public void RandomPiece(int x, int y)
	{
	  boardSquares[x, y].SetPiece(GamePiece.PieceTypes[rand.Next(0, 
		   GamePiece.MaxPlayablePieceIndex+1)]);
	}

What just happened?
RotatePiece(), GetSourceRect(), GetSquare(), SetSquare(), and HasConnector() methods simply locate the appropriate GamePiece within the boardSquares array and pass on the function request to the piece.

The RandomPiece() method uses the rand object to get a random value from the PieceTypes array and assign it to a GamePiece. It is important to remember that with the Random.Next() method overload used here, the second parameter is non-inclusive. In order to generate a random number from 0 through 5, the second parameter needs to be 6.

Filling in the gaps
Whenever the player completes a scoring chain, the pieces in that chain are removed from the board. Any pieces above them fall down into the vacated spots and new pieces are generated.

Time for action - filling in the gaps

Add the FillFromAbove() method to the GameBoard class.

	
public void FillFromAbove(int x, int y)
	{
		int rowLookup = y - 1;
	
		while (rowLookup >= 0)
		{
			if (GetSquare(x, rowLookup) != "Empty")
			{
				SetSquare(x, y,
				  GetSquare(x, rowLookup));
				SetSquare(x, rowLookup, "Empty");
				rowLookup = -1;
			}
			rowLookup--;
		}
	}

What just happened?
Given a square to fill, FillFromAbove() looks at the piece directly above to see if it is marked as Empty. If it is, the method will subtract one from rowLookup and start over until it reaches the top of the board. If no non-empty pieces are found when the top of the board is reached, the method does nothing and exits.

When a non-empty piece is found, it is copied to the destination square, and the copied piece is changed to an empty piece. The rowLookup variable is set to -1 to ensure that the loop does not continue to run.

Generating new pieces
We can create a single method that will fill any empty spaces on the game board, and use it when the game begins and when pieces are removed from the board after scoring.

Time for action - generating new pieces

Add the GenerateNewPieces() method to the GameBoard class:

	
public void GenerateNewPieces(bool dropSquares)
	{
	
		if (dropSquares)
		{
			for (int x = 0; x		 {
				for (int y = GameBoard.GameBoardHeight - 1; y >= 0; y--)
				{
					if (GetSquare(x, y) == "Empty")
					{
						FillFromAbove(x, y);
					}
				}
			}
		}
	
		for (int y = 0; y		 for (int x = 0; x		 {
				if (GetSquare(x, y) == "Empty")
				{
					RandomPiece(x, y);
				}
			}
	}

What just happened?
When GenerateNewPieces() is called with "true" passed as dropSquares, the looping logic processes one column at a time from the bottom up. When it finds an empty square it calls FillFromAbove() to pull a filled square from above into that location.

The reason the processing order is important here is that, by filling a lower square from a higher position, that higher position will become empty. It, in turn, will need to be filled from above.

After the holes are filled (or if dropSquares is set to false) GenerateNewPieces() examines each square in boardSquares and asks it to generate random pieces for each square that contains an empty piece.

Water filled pipes
Whether or not a pipe is filled with water is managed separately from its orientation. Rotating a single pipe could change the water-filled status of any number of other pipes without changing their rotation.

Instead of filling and emptying individual pipes, however, it is easier to empty all of the pipes and then refill the pipes that need to be marked as having water in them.

Time for action - water in the pipes

Add a method to the GameBoard class to clear the water marker from all pieces:

	
public void ResetWater()
	{
		for (int y = 0; y		 for (int x = 0; x			 boardSquares[x,y].RemoveSuffix("W");
	}

Add a method to the GameBoard class to fill an individual piece with water:

	
public void FillPiece(int X, int Y)
	{
		boardSquares[X,Y].AddSuffix("W");
	}

What just happened?
The ResetWater() method simply loops through each item in the boardSquares array and removes the W suffix from the GamePiece. Similarly, to fill a piece with water, the FillPiece() method adds the W suffix to the GamePiece. Recall that by having a W suffix, the GetSourceRect() method of GamePiece shifts the source rectangle one tile to the right on the sprite sheet, returning the image for a pipe filled with water instead of an empty pipe.

Propagating water
Now that we can fill individual pipes with water, we can write the logic to determine which pipes should be filled depending on their orientation.

Time for action - making the connection

Add the PropagateWater() method to the GameBoard class:

	
public void PropagateWater(int x, int y, string fromDirection)
	{
		if ((y >= 0) && (y		 (x >= 0) && (x	 {
			if (boardSquares[x,y].HasConnector(fromDirection) &&
				!boardSquares[x,y].Suffix.Contains("W"))
			{
				FillPiece(x, y);
				WaterTracker.Add(new Vector2(x, y));
				foreach (string end in
						 boardSquares[x,y].GetOtherEnds(fromDirection))
					switch (end)
						  {
						case "Left": PropagateWater(x - 1, y, "Right");
							break;
						case "Right": PropagateWater(x + 1, y, "Left");
							break;
						case "Top": PropagateWater(x, y - 1, "Bottom");
							break;
						case "Bottom": PropagateWater(x, y + 1, "Top");
							break;
					}
			}
		}
	}

Add the GetWaterChain() method to the GameBoard class:

	
public List GetWaterChain(int y)
	{
		WaterTracker.Clear();
		PropagateWater(0, y, "Left");
		return WaterTracker;
	}

What just happened?
Together, GetWaterChain() and PropagateWater() are the keys to the entire Flood Control game, so understanding how they work is vital. When the game code wants to know if the player has completed a scoring row, it will call the GetWaterChain() method once for each row on the game board:

The WaterTracker list is cleared and GetWaterChain() calls PropagateWater() for the first square in the row, indicating that the water is coming from the Left direction.

The PropagateWater() method checks to make sure that the x and y coordinates passed to it exist within the board and, if they do, checks to see if the piece at that location has a connector matching the fromDirection parameter and that the piece is not already filled with water. If all of these conditions are met, that piece gets filled with water and added to the WaterTracker list.

Finally, PropagateWater() gets a list of all other directions that the piece contains (in other words, all directions the piece contains that do not match fromDirection). For each of these directions PropagateWater() recursively calls itself, passing in the new x and y location as well as the direction the water is coming from.

Building the game
We now have the component classes we need to build the Flood Control game, so it is time to bring the pieces together in the Game1 class.

Declarations
We only need a handful of game-wide declarations to manage things like the game board, the player's score, and the game state.

Time for action - Game1 declarations

Double click on the Game1.cs file in Solution Explorer to reactivate the Game1.cs code file window.

Add the following declarations to the Game1 class member declaration area:

	
GameBoard gameBoard;
	
	Vector2 gameBoardDisplayOrigin = new Vector2(70, 89);
	
	int playerScore = 0;
	
	enum GameStates { TitleScreen, Playing };
	GameStates gameState = GameStates.TitleScreen;
	
	Rectangle EmptyPiece = new Rectangle(1, 247, 40, 40);
	
	const float MinTimeSinceLastInput = 0.25f;
	float timeSinceLastInput = 0.0f;

What just happened?
The gameBoard instance of GameBoard will hold all of the playing pieces, while the gameBoardDisplayOrigin vector points to where on the screen the board will be drawn. Using a vector like this makes it easy to move the board in the event that you wish to change the layout of your game screen.

As we did in SquareChase, we store the player's score and will display it in the window title bar.

In order to implement a simple game state mechanism, we define two game states. When in the TitleScreen state, the game's title image will be displayed and the game will wait until the user presses the Space bar to start the game. The state will then switch to Playing, which will display the game board and allow the user to play.

If you look at the sprite sheet for the game, the pipe images themselves do not cover the entire 40x40 pixel area of a game square. In order to provide a background, an empty tile image will be drawn in each square first. The EmptyPiece Rectangle is a convenient pointer to where the empty background is located on the sprite sheet.

Just as we used an accumulating timer in SquareChase to determine how long to leave a square in place before moving it to a new location, we will use the same timing mechanism to make sure that a single click by the user does not send a game piece spinning unpredictably. Remember that the Update() method will be executing up to 60 times each second, so slowing the pace of user input is necessary to make the game respond in a way that feels natural.

Initialization
Before we can use the gameBoard instance, it needs to be initialized. We will also need to enable the mouse cursor.

Time for action - updating the Initialize() method

Update the Initialize() method to include the following:

	
this.IsMouseVisible = true;
	graphics.PreferredBackBufferWidth = 800;
	graphics.PreferredBackBufferHeight = 600;
	graphics.ApplyChanges();
	gameBoard = new GameBoard();

What just happened?
After making the mouse cursor visible, we set the size of the BackBuffer to 800 by 600 pixels. On Windows, this will size the game window to 800 by 600 pixels as well.

The constructor for the GameBoard class calls the ClearBoard() member, so each of the pieces on the gameBoard instance will be set to Empty.

The Draw() method - the title screen
In the declarations section, we established two possible game states. The first (and default) state is GameStates.TitleScreen, indicating that the game should not be processing actual game play, but should instead be displaying the game's logo and waiting for the user to begin the game.

Time for action - drawing the screen - the title screen

Modify the Draw() method of Game1 to include the code necessary to draw the game's title screen after GraphicsDevice.Clear(Color.CornflowerBlue);

	
if (gameState == GameStates.TitleScreen)
	{
		spriteBatch.Begin();
		spriteBatch.Draw(titleScreen,
			new Rectangle(0, 0,
				this.window.ClientBounds.Width,
				this.window.ClientBounds.Height),
			Color.White);
		spriteBatch.End();
	}

Run the game and verify that the title screen is displayed. You will not be able to start the game however, as we haven't written the Update() method yet.
Stop the game by pressing Alt + F4.

What just happened?
The title screen is drawn with a single call to the Draw() method of the spriteBatch object. Since the title screen will cover the entire display, a rectangle is created that is equal to the width and height of the game window.

The Draw() method - the play screen
Finally, we are ready to display the playing pieces on the screen. We will accomplish this by using a simple loop to display all of the playing pieces in the gameBoard object.

Time for action - drawing the screen - the play screen

Update the Draw() method of the Game1 class to add the code to draw the game board after the code that draws the title screen:

	
if (gameState == GameStates.Playing)
	{
		spriteBatch.Begin();
	
		spriteBatch.Draw(backgroundScreen,
			new Rectangle(0, 0,
				this.window.ClientBounds.Width,
				this.window.ClientBounds.Height),
			Color.White);
	
		for (int x = 0; x		 for (int y = 0; y		 {
				int pixelX = (int)gameBoardDisplayOrigin.X + 
					(x * GamePiece.PieceWidth);
				int pixelY = (int)gameBoardDisplayOrigin.Y + 
					(y * GamePiece.PieceHeight);
	
				spriteBatch.Draw(
					playingPieces,
					new Rectangle(
					  pixelX, 
					  pixelY, 
					  GamePiece.PieceWidth, 
					  GamePiece.PieceHeight),
					EmptyPiece,
					Color.White);
	
				spriteBatch.Draw(
					playingPieces, new Rectangle(
						pixelX, 
						pixelY, 
						GamePiece.PieceWidth, 
						GamePiece.PieceHeight),
					gameBoard.GetSourceRect(x, y),
					Color.White);
			}
	
		this.window.Title = playerScore.ToString();
	
		spriteBatch.End();
	}

What just happened?
As you can see, the code to draw the game board begins exactly like the code to draw the title screen. Since we are using a background image that takes up the full screen, we draw it exactly the same way as the title screen.

Next, we simply loop through gameBoard to draw the squares. The pixelX and pixelY variables are calculated to determine where on the screen each of the game pieces will be drawn. Since both x and y begin at 0, the (x * GamePiece.PieceWidth) and (y * GamePiece.PieceHeight) will also be equal to zero, resulting in the first square being drawn at the location specified by the gameBoardDisplayOrigin vector.

As x increments, each new piece is drawn 40 pixels further to the right than the previous piece. After a row has been completed, the y value increments, and a new row is started 40 pixels below the previous row.

The first spriteBatch.Draw() call uses Rectangle(pixelX, pixelY, GamePiece.PieceWidth, GamePiece.PieceHeight) as the destination rectangle and EmptyPiece as the source rectangle. Recall that we added this Rectangle to our declarations area as a shortcut to the location of the empty piece on the sprite sheet.

The second spriteBatch.Draw() call uses the same destination rectangle, overlaying the playing piece image onto the empty piece that was just drawn. It asks the gameBoard to provide the source rectangle for the piece it needs to draw.

The player's score is displayed in the window title bar, and spriteBatch.End() is called to finish up the Draw() method.

Keeping score
Longer chains of filled water pipes score the player more points. However, if we were to simply assign a single point to each piece in the pipe chain, there would be no scoring advantage to making longer chains versus quickly making shorter chains.

Time for action - scores and scoring chains

Add a method to the Game1 class to calculate a score based on the number of pipes used:

	
private int DetermineScore(int SquareCount)
	{
		return (int)((Math.Pow((SquareCount/5), 2) + SquareCount)*10);
	}

Add a method to evaluate a chain to determine if it scores and process it:

	
private void CheckScoringChain(List WaterChain)
	{
	
		if (WaterChain.Count > 0)
		{
			Vector2 LastPipe = WaterChain[WaterChain.Count - 1];
	
			if (LastPipe.X == GameBoard.GameBoardWidth - 1)
			{
				if (gameBoard.HasConnector(
					(int)LastPipe.X, (int)LastPipe.Y, "Right"))
				{
					playerScore += DetermineScore(WaterChain.Count);
	
					foreach (Vector2 ScoringSquare in WaterChain)
					{
						gameBoard.SetSquare((int)ScoringSquare.X,
							(int)ScoringSquare.Y, "Empty");
					}
				}
			}
		}
	}

What just happened?
DetermineScore() accepts the number of squares in a scoring chain and returns a score value for that chain. The number of squares in the chain is divided by 5, and that number is squared. The initial number of squares is added to the result, and the final amount is multiplied by 10.


Score = (((Squares / 5) ^ 2) + Squares) * 10

For example, a minimum scoring chain would be 8 squares (forming a straight line across the board). This would result in 1 squared plus 8 times 10, or 90 points. If a chain had 18 squares the result would be 3 squared plus 18 times 10, or 270 points. This makes longer scoring chains (especially increments of five squares) award much higher scores than a series of shorter chains.

The CheckScoringRow() method makes sure that there are entries in the WaterChain list, and then examines the last piece in the chain and checks to see if it has an X value of 7 (the right-most column on the board). If it does, the HasConnector() method is checked to see if the last pipe has a connector to the right, indicating that it completes a chain across the board.

After updating playerScore for the scoring row, CheckScoringRow() sets all of the pieces in the scoring row to Empty. They will be refilled by a subsequent call to the GenerateNewPieces() method.

Input handling
The player interacts with Flood Control using the mouse. For readability reasons, we will create a helper method that deals with mouse input and call it when appropriate from the Update() method.

Time for action - handling mouse input

Add the HandleMouseInput() helper method to the Game1 class:

	
private void HandleMouseInput(MouseState mouseState)
	{
	
		int x = ((mouseState.X -
			(int)gameBoardDisplayOrigin.X) / GamePiece.PieceWidth);
	
		int y = ((mouseState.Y -
			(int)gameBoardDisplayOrigin.Y) / GamePiece.PieceHeight);
	
		if ((x >= 0) && (x	   (y >= 0) && (y	 {
			if (mouseState.LeftButton == ButtonState.Pressed)
			{
				gameBoard.RotatePiece(x, y, false);
				timeSinceLastInput = 0.0f;
			}
	
			if (mouseState.RightButton == ButtonState.Pressed)
			{
				gameBoard.RotatePiece(x, y, true);
				timeSinceLastInput = 0.0f;
			}
		}
	}

What just happened?
The MouseState class reports the X and Y position of the mouse relative to the upper left corner of the window. What we really need to know is what square on the game board the mouse was over.

We calculate this by taking the mouse position and subtracting the gameBoardDisplayOrigin from it and then dividing the remaining number by the size of a game board square.

If the resulting X and Y locations fall within the game board, the left and right mouse buttons are checked. If the left button is pressed, the piece is rotated counterclockwise. The right button rotates the piece clockwise. In either case, the input delay timer is reset to 0.0f since input was just processed.

Letting the player play!
Only one more section to go and you can begin playing Flood Control. We need to code the Update() method to tie together all of the game logic we have created so far.

Time for action - letting the player play

Modify the Update() method of Game1.cs by adding the following before the call to base.Update(gameTime):

	
switch (gameState)
	{
		case GameStates.TitleScreen:
			if (Keyboard.GetState().IsKeyDown(Keys.Space))
			{
				gameBoard.ClearBoard();
				gameBoard.GenerateNewPieces(false);
				playerScore = 0;
				gameState = GameStates.Playing;
			}
			break;
	
		case GameStates.Playing:
			timeSinceLastInput +=
			  (float)gameTime.ElapsedGameTime.TotalSeconds;
	
			if (timeSinceLastInput >= MinTimeSinceLastInput)
			{
				HandleMouseInput(Mouse.GetState());
			}
	
			gameBoard.ResetWater();
	
			for (int y = 0; y		 {
				CheckScoringChain(gameBoard.GetWaterChain(y));		
			}
	
			gameBoard.GenerateNewPieces(true);
	
			break;
	}

What just happened?
The Update() method performs two different functions, depending on the current gameState value. If the game is in TitleScreen state, Update() examines the keyboard, waiting for the Space bar to be pressed. When it is, Update() clears the gameBoard, generates a new set of pieces, resets the player's score, and changes gameState to Playing.

While in the Playing state, Update() accumulates time in timeSinceLastInput in order to pace the game play properly. If enough time has passed, the HandleMouseInput() method is called to allow the player to rotate game pieces.

Update() then calls ResetWater() to clear the water flags for all pieces on the game board. This is followed by a loop that processes each row, starting at the top and working downward, using CheckScoringChain() and GetWaterChain() to "fill" any pieces that should have water in them and check the results of each row for completed chains.

Finally, GenerateNewPieces() is called with the "true" parameter for dropSquares, which will cause GenerateNewPieces() to fill the empty holes from the squares above, and then generate new pipes to replace the empty squares.

Play the game
You now have all of the components assembled, and can run Flood Control and play!

Summary
You now have a working Flood Control game. In this article we have looked at:

Adding content objects to your project and loading them into textures at runtime using an instance of the ContentManager class
Dividing the code into classes that represent objects in the game
Building a recursive method
Use the SpriteBatch.Draw() method to display images
Divide the Update() and Draw() code into different units based on the current game state

In the next article, we will spruce up the Flood Control game, adding animation by modifying the parameters of the SpriteBatch.Draw() method and creating text effects in order to make the game visually more appealing.

JIRA: Programming Workflows

Wed, 01 Feb 2012 03:30:23 +0000

In this article by Jobin Kuruvilla author of JIRA Development Cookbook, we will cover:

Writing a workflow condition
Writing a workflow validator
Writing a workflow post function
Editing an active workflow

Introduction
Workflows are one standout feature which help users to transform JIRA into a user-friendly system. It helps users to define a lifecycle for the issues, depending on the issue type, the purpose for which they are using JIRA, and so on. As the Atlassian documentation says at http://confluence.at...guring+Workflow:

A JIRA workflow is the set of steps and transitions an issue goes through during its lifecycle. Workflows typically represent business processes.

JIRA uses Opensymphony's OSWorkflow which is highly configurable, and more importantly pluggable, to cater for the various requirements. JIRA uses three different plugin modules to add extra functionalities into its workflow, which we will see in detail through this chapter.
To make things easier, JIRA ships with a default workflow. We can't modify the default workflow, but can copy it into a new workflow and amend it to suit our needs. Before we go into the development aspect of a workflow, it makes sense to understand the various components of a workflow.
The two most important components of a JIRA workflow are Step and Transition. At any point of time, an Issue will be in a step. Each step in the workflow is linked to a workflow Status (http://confluence.at...+%27Status%27+F ield+Values) and it is this status that you will see on the issue at every stage. A transition, on the other hand, is a link between two steps. It allows the user to move an issue from one step to another (which essentially moves the issue from one status to another).
Few key points to remember or understand about a workflow:

An issue can exist in only one step at any point in time
A status can be mapped to only one step in the workflow
A transition is always one-way. So if you need to go back to the previous step, you need a different transition
A transition can optionally specify a screen to be presented to the user with the right fields on it

OSWorkflow, and hence JIRA, provides us with the option of adding various elements into a workflow transition which can be summarized as follows:

Conditions: A set of conditions that need to be satisfied before the user can actually see the workflow action (transition) on the issue
Validators: A set of validators which can be used to validate the user input before moving to the destination step
Post Functions: A set of actions which will be performed after the issue is successfully moved to the destination step

These three elements give us the flexibility of handling the various use cases when an issue is moved from one status to another. JIRA ships with a few built-in conditions, validators, and post functions. There are plugins out there which also provide a wide variety of useful workflow elements. And if you still don't find the one you are looking for, JIRA lets us write them as plugins. We will see how to do it in the various recipes in this chapter. Hopefully, that gives you a fair idea about the various workflow elements. A lot more on JIRA workflows can be found in the JIRA documentation at http://confluence.at...guring+Workflow.

Writing a workflow condition
What are workflow conditions? They determine whether a workflow action is available or not. Considering the importance of a workflow in installations and how there is a need to restrict the actions either to a set of people, roles, and so on, or based on some criteria (for example, the field is not empty!), writing workflow conditions is inevitable.
Workflow conditions are created with the help of the workflow-condition module. The following are the key attributes and elements supported. See http://confluence.at...ules-Conditions for more details.

Attributes:

Class to provide contexts for rendered velocity templates. Must implement the com.atlassian.jira.plugin.workflow.WorkflowPluginConditionFactory interface.
Elements:

Class to determine whether the user can see the workflow transition. Must implement com.opensymphony.workflow.Condition. Recommended to extend the com.atlassian.jira.workflow.condition.AbstractJiraCondition class.
Getting ready
As usual, create a skeleton plugin. Create an eclipse project using the skeleton plugin and we are good to go!

How to do it...
In this recipe, let's assume we are going to develop a workflow condition that limits a transition only to the users belonging to a specific project role. The following are the steps to write our condition:

Define the inputs needed to configure the workflow condition.
We need to implement the WorkflowPluginFactory interface, which mainly exists to provide velocity parameters to the templates. It will be used to extract the input parameters that are used in defining the condition. To make it clear, the inputs here are not the inputs while performing the workflow action, but the inputs in defining the condition.
The condition factory class, RoleConditionFactory in this case, extends the AbstractWorkflowPluginFactory, which implements the WorkflowPluginFactory interface. There are three abstract methods that we should implement, that is, getVelocityParamsForInput, getVelocityParamsForEdit, and getVelocityParamsForView. All of them, as the name suggests, are used for populating the velocity parameters for the different scenarios.
In our example, we need to limit the workflow action to a certain project role, and so we need to select the project role while defining the condition. The three methods will be implemented as follows:
```
	
		private static final String ROLE_NAME = "role";
			private static final String ROLES = "roles";
			.......
			@Override
			  protected void getVelocityParamsForEdit(Map
			velocityParams, AbstractDescriptor descriptor) {
				velocityParams.put(ROLE, getRole(descriptor));
				velocityParams.put(ROLES, getProjectRoles());
			  }  @Override
			  protected void getVelocityParamsForInput(Map
			velocityParams) {
				velocityParams.put(ROLES, getProjectRoles());
			  }  @Override
			  protected void getVelocityParamsForView(Map
			velocityParams, AbstractDescriptor descriptor) {
				velocityParams.put(ROLE, getRole(descriptor));
			  }	
			
```
Let's look at the methods in detail:
- getVelocityParamsForInput: This method defines the velocity parameters for input scenario, that is, when the user initially configures the workflow. In our example, we need to display all the project roles so that the user can select one to define the condition. The method getProjectRoles merely returns all the project roles and the collection of roles is then put into the velocity parameters with the key ROLES.
- getVelocityParamsForView: This method defines the velocity parameters for the view scenario, that is, how the user sees the condition after it is configured. In our example, we have defined a role and so we should display it to the user after retrieving it back from the workflow descriptor. If you have noticed, the descriptor, which is an instance of AbstractDescriptor, is available as an argument in the method. All we need is to extract the role from the descriptor, which can be done as follows:
```
	
		private ProjectRole getRole(AbstractDescriptor descriptor){
				if (!(descriptor instanceof ConditionDescriptor)) {
				  throw new IllegalArgumentException("Descriptor must be a
			ConditionDescriptor.");
				}
				
			  ConditionDescriptor functionDescriptor = (ConditionDescriptor)
			descriptor;
				
			 String role = (String) functionDescriptor.getArgs().get(ROLE);
				if (role!=null && role.trim().length()>0)
				  return getProjectRole(role);
				else
				  return null;
			  }	
			
```
  Just check if the descriptor is a condition descriptor or not, and then extract the role as shown in the preceding snippet.
- getVelocityParamsForEdit: This method defines the velocity parameters for the edit scenario, that is, when the user modifies the existing condition. Here we need both the options and the selected value. Hence, we put both the project roles collection and the selected role on to the velocity parameters.

The second step is to define the velocity templates for each of the three aforementioned scenarios: input, view, and edit. We can use the same template here for input and edit with a simple check to keep the old role selected for the edit scenario. Let us look at the templates:
- edit-roleCondition.vm: Displays all project roles and highlights the already-selected one in the edit mode. In the input mode, the same template is reused, but the selected role will be null and hence a null check is done:
```
	
	
	
		
		
			
			#foreach ($field in $roles)
						  #if ($role && (${field.id}==${role.id}))
					SELECTED
				#end
				>$field.name
			#end
			
			
	Select the role in which the user
	should be present!
		
	
	
	
```
- view-roleCondition.vm: Displays the selected role:
```
	
#if ($role)
	  User should have ${role.name} Role!
	#else
	  Role Not Defined
	#end	
	
```
The third step is to write the actual condition. The condition class should extend the AbstractJiraCondition class. Here we need to implement the passesCondition method. In our case, we retrieve the project from the issue, check if the user has the appropriate project role, and return true if the user does:
```
	
public boolean passesCondition(Map transientVars, Map args,
	PropertySet ps) throws WorkflowException {
		Issue issue = getIssue(transientVars);
		User user = getCaller(transientVars, args);	project project = issue.getProjectObject();
		String role = (String)args.get(ROLE);
		Long roleId = new Long(role);	return projectRoleManager.isUserInProjectRole(user,
	projectRoleManager.getProjectRole(roleId), project);
	}	
	
```
The issue on which the condition is checked can be retrieved using the getIssue method implemented in the AbstractJiraCondition class. Similarly, the user can be retrieved using the getCaller method. In the preceding method, projectRoleManager is injected in the constructor, as we have seen before.
We can see that the ROLE key is used to retrieve the project role ID from the args parameter in the passesCondition method. In order for the ROLE key to be available in the args map, we need to override the getDescriptorParams method in the condition factory class, RoleConditionFactory in this case. The getDescriptorParams method returns a map of sanitized parameters, which will be passed into workflow plugin instances from the values in an array form submitted by velocity, given a set of name:value parameters from the plugin configuration page (that is, the 'input-parameters' velocity template). In our case, the method is overridden as follows:
```
	
public Map getDescriptorParams(Map
	conditionParams) {
		if (conditionParams != null &&
	conditionParams.containsKey(ROLE))
			{
				return EasyMap.build(ROLE,
	extractSingleParam(conditionParams, ROLE));
			}
			// Create a 'hard coded' parameter
			return EasyMap.build();
	  }	
	
```
The method here builds a map of the key:value pair, where key is ROLE and the value is the role value entered in the input configuration page. The extractSingleParam method is implemented in the AbstractWorkflowPluginFactory class. The extractMultipleParams method can be used if there is more than one parameter to be extracted!
All that is left now is to populate the atlassian-plugin.xml file with the aforementioned components. We use the workflow-condition module and it looks like the following block of code:
```
	
	
	
```
Package the plugin and deploy it!
How it works...
After the plugin is deployed, we need to modify the workflow to include the condition. The following screenshot is how the condition looks when it is added initially. This, as you now know, is rendered using the input template:

After the condition is added (that is, after selecting the Developers role), the view is rendered using the view template and looks as shown in the following screenshot:

/sites/default/files/Article-Images/1803-04-02.png

(Move the mouse over the image to enlarge.)

If you try to edit it, the screen will be rendered using the edit template, as shown in the following screenshot:

Note that the Developers role is already selected.
After the workflow is configured, when the user goes to an issue, he/she will be presented with the transition only if he/she is a member of the project role where the issue belongs. It is while viewing the issue that the passesCondition method in the condition class is executed.

Writing a workflow validator
Workflow validators are specific validators that check whether some pre-defined constraints are satisfied or not while progressing on a workflow. The constraints are configured in the workflow and the user will get an error if some of them are not satisfied. A typical example would be to check if a particular field is present or not before the issue is moved to a different status.
Workflow validators are created with the help of the workflow- validator module. The following are the key attributes and elements supported.

Attributes:

Class to provide contexts for rendered velocity templates. Must implement the com.atlassian.jira.plugin.workflow.WorkflowPluginValidatorFactory interface.
Elements:

Class which does the validation. Must implement com.opensymphony.workflow.Validator.

See http://confluence.at...ules-Validators for more details.

Getting ready
As usual, create a skeleton plugin. Create an eclipse project using the skeleton plugin and we are good to go!

How to do it...
Let us consider writing a validator that checks whether a particular field has a value entered on the issue or not! We can do this using the following steps:

Define the inputs needed to configure the workflow validator:
We need to implement the WorkflowPluginValidatorFactory interface, which mainly exists to provide velocity parameters to the templates. It will be used to extract the input parameters that are used in defining the validator. To make it clear, the inputs here are not the input while performing the workflow action, but the inputs in defining the validator.
The validator factory class, FieldValidatorFactory in this case, extends the AbstractWorkflowPluginFactory interface and implements the WorkflowPluginValidatorFactory interface. Just like conditions, there are three abstract methods that we should implement. They are getVelocityParamsForInput, getVelocityParamsForEdit, and getVelocityParamsForView. All of them, as the names suggest, are used for populating the velocity parameters in different scenarios.
In our example, we have a single input field, which is the name of a custom field. The three methods will be implemented as follows:
```
	
		@Override
			protected void getVelocityParamsForEdit(Map velocityParams,
			AbstractDescriptor descriptor) {
				velocityParams.put(FIELD_NAME, getFieldName(descriptor));
			  velocityParams.put(FIELDS, getCFFields());
			}@Override
			protected void getVelocityParamsForInput(Map velocityParams) {
				velocityParams.put(FIELDS, getCFFields());
			}@Override
			protected void getVelocityParamsForView(Map velocityParams,
			AbstractDescriptor descriptor) {
				velocityParams.put(FIELD_NAME, getFieldName(descriptor));
			}	
			
```
You may have noticed that the methods look quite similar to the ones in a workflow condition, except for the business logic! Let us look at the methods in detail:
- getVelocityParamsForInput: This method defines the velocity parameters for input scenario, that is, when the user initially configures the workflow. In our example, we need to display all the custom fields, so that the user can select one to use in the validator. The method getCFFields returns all the custom fields and the collection of fields is then put into the velocity parameters with the key fields.
- getVelocityParamsForView: This method defines the velocity parameters for the view scenario, that is, how the user sees the validator after it is configured. In our example, we have defined a field and so we should display it to the user after retrieving it back from the workflow descriptor. You may have noticed that the descriptor, which is an instance of AbstractDescriptor, is available as an argument in the method. All we need is to extract the field name from the descriptor, which can be done as follows:
```
	
		private String getFieldName(AbstractDescriptor descriptor){
			  if (!(descriptor instanceof ValidatorDescriptor)) {
				throw new IllegalArgumentException('Descriptor must be a
			ValidatorDescriptor.');
			  }
			  
			  ValidatorDescriptor validatorDescriptor = (ValidatorDescriptor)
			descriptor;  String field = (String)
			validatorDescriptor.getArgs().get(FIELD_NAME);
			  if (field != null && field.trim().length() > 0)
				return field;
			  else
				return NOT_DEFINED;
			}	
			
```
  Just check if the descriptor is a validator descriptor or not and then extract the field as shown in the preceding snippet.
- getVelocityParamsForEdit: This method defines the velocity parameters for the edit scenario, that is, when the user modifies the existing validator. Here we need both the options and the selected value. Hence we put both the custom fields' collection and the field name onto the velocity parameters.

The second step is to define the velocity templates for each of the three aforementioned scenarios, namely, input, view, and edit. We can use the same template here for input and edit with a simple checking to keep the old field selected for the edit scenario. Let us look at the template:
- edit-fieldValidator.vm: Displays all custom fields and highlights the already selected one in edit mode. In input mode, the field variable will be null, and so nothing is pre-selected:
```
	
	
	
	  
	  
		
		#foreach ($cf in $fields)
				  #if ($cf.name.equals($field)) SELECTED #end
		  >$cf.name
		#end
		
		
	Select the Custom Field to be validated
	for NULL
	  
	
	
	
```
- view-fieldValidator.vm: Displays the selected field:
```
	
#if ($field)
	  Field '$field' is Required!
	#end	
	
```

The third step is to write the actual validator. The validator class should implement the Validator interface. All we need here is to implement the validate method. In our example, we retrieve the custom field value from the issue and throw an InvalidInputException if the value is null (empty):

	
public void validate(Map transientVars, Map args, PropertySet ps)
	throws InvalidInputException, WorkflowException {
		Issue issue = (Issue) transientVars.get("issue");
		String field = (String) args.get(FIELD_NAME);	  CustomField customField =
	customFieldManager.getCustomFieldObjectByName(field);	if (customField!=null){
		  //Check if the custom field value is NULL
		  if (issue.getCustomFieldValue(customField) == null){
			throw new InvalidInputException("The field:"+field+" is
				 required!"); }
		}
	  }

The issue on which the validation is done can be retrieved from the transientVars map. customFieldManager is injected in the constructor as usual.

All that is left now is to populate the atlassian-plugin.xml file with these components. We use the workflow-validator module, and it looks like the following block of code:

	
class="com.jtricks.FieldValidatorFactory">
		Field Not Empty Workflow Validator	com.jtricks.FieldValidator	location="templates/com/jtricks/view-fieldValidator.vm"/>
		location="templates/com/jtricks/edit-fieldValidator.vm"/>
		location="templates/com/jtricks/edit-fieldValidator.vm"/>

Package the plugin and deploy it!
Note that we have stored the role name instead of the ID in the workflow, unlike what we did in the workflow condition. However, it is safe to use the ID because administrators can rename the roles, which would then need changes in the workflows.

How it works...
After the plugin is deployed, we need to modify the workflow to include the validator. The following screenshot is how the validator looks when it is added initially. This, as you now know, is rendered using the input template:

After the validator is added (after selecting the Test Number field), it is rendered using the view template and looks as follows:

If you try to edit it, the screen will be rendered using the edit template, as shown in the following screenshot:

Note that the Test Number field is already selected.
After the workflow is configured, when the user goes to an issue and tries to progress it, the validator will check if the Test Number field has a value or not. It is at this point that the validate method in the FieldValidator class is executed.
If the value is missing, you will see an error, as shown in the following screenshot:

Writing a workflow post function
Let us now look at workflow post functions. Workflow post functions are very effective and heavily used. They allow you to do a lot of things when you progress on the workflow on an issue. A lot of customizations and workarounds take this route!
Workflow post functions are created with the help of the workflow-function module. The following are the key attributes and elements supported.

Attributes:

Class to provide contexts for rendered velocity templates. Must implement the com.atlassian.jira.plugin.workflow.WorkflowNoInputPluginFactory interface if the function doesn't need input, or com.atlassian.jira.plugin.workflow.WorkflowPluginFunctionFactory if it needs input.
Elements:

Class which does the validation. Must implement com.opensymphony.workflow.FunctionProvider. Recommended to extend com.atlassian.jira.workflow.function.issue.AbstractJiraFunctionProvider, as it already implements many useful methods.
There are three other elements that can be used with a post function. They are explained as follows:

orderable – (true/false) Specifies if this function can be re-ordered within the list of functions associated with a transition. The position within the list determines when the function actually executes.
unique – (true/false) Specifies if this function is unique, that is, if it is possible to add multiple instances of this post function on a single transition.
deletable – (true/false) Specifies if this function can be removed from a transition.

See http://confluence.at...dules-Functions for more details.

Getting ready
As usual, create a skeleton plugin. Create an eclipse project using the skeleton plugin and we are good to go!

How to do it...
Assume we have a user custom field and we want to set the current user or a specified user name on to the custom field when a particular transition happens. A typical use case for this will be to store the name of the user who last resolved an issue. The following are the steps to write a generic post function that sets the current username or a username provided by the user on a user custom field:

Define the inputs needed to configure the workflow post function:
As opposed to workflow conditions and validators, there are two interfaces available for a workflow post function factory class. If there are no inputs needed to configure the function, the factory class must implement WorkflowNoInputPluginFactory.
An example will be to set the current user's name as the custom field value instead of the user configured name. If inputs are needed to configure the post function, the factory class must implement WorkflowPluginFunctionFactory. In our example, we take the username as the input.
Both the interfaces mainly exist to provide velocity parameters to the templates. They will be used to extract the input parameters that are used in defining the functions. To make it clear, the inputs here are not the input while performing the workflow action, but the inputs in defining the post function.
The function factory class, SetUserCFFunctionFactory in this case, extends the AbstractWorkflowPluginFactory and implements the WorkflowPluginFunctionFactory interface. Just like conditions, there are three abstract methods that we should implement, namely, getVelocityParamsForInput, getVelocityParamsForEdit, and getVelocityParamsForView. All of them, as the names suggest, are used for populating the velocity parameters for the different scenarios:
```
	
		@Override
			protected void getVelocityParamsForEdit(Map velocityParams,
			AbstractDescriptor descriptor) {
				velocityParams.put(USER_NAME, getUserName(descriptor));
			}@Override
			protected void getVelocityParamsForInput(Map velocityParams) {
				velocityParams.put(USER_NAME, CURRENT_USER); }@Override
			protected void getVelocityParamsForView(Map velocityParams,
			AbstractDescriptor descriptor) {
				velocityParams.put(USER_NAME, getUserName(descriptor));
			}	
			
```
You may have noticed that the methods look very similar to the ones in workflow conditions or validators, except for the business logic! Let us look at the methods in detail:
- getVelocityParamsForInput : This method defines the velocity parameters for input scenario, that is, when the user initially configures the workflow. In our example, we need to use a text field that captures the username to be added on the issue.
- getVelocityParamsForView: This method defines the velocity parameters for the view scenario, that is, how the user sees the post function after it is configured. In our example, we have defined a field, and so we should display it to the user after retrieving it from the workflow descriptor. You may have noticed that the descriptor, which is an instance of AbstractDescriptor, is available as an argument in the method. All we need is to extract the username from the descriptor, which can be done as follows:
```
	
		private String getUserName(AbstractDescriptor descriptor){
				if (!(descriptor instanceof FunctionDescriptor)) {
				  throw new IllegalArgumentException("Descriptor must be a
			 FunctionDescriptor.");
				}	FunctionDescriptor functionDescriptor =
			(FunctionDescriptor) descriptor;
			 String user = (String)
			functionDescriptor.getArgs().get(USER_NAME);
				if (user!=null && user.trim().length()>0)
				  return user;
				else
				  return CURRENT_USER;
			  }	
			
```
  Just check if the descriptor is a validator descriptor or not, and then extract the field as shown in the preceding snippet.
- getVelocityParamsForEdit: This method defines the velocity parameters for the edit scenario, that is, when the user modifies the existing validator. Here we need both the options and the selected value. Hence, we put both the custom fields' collection and the field name on to the velocity parameters.

The second step is to define the velocity templates for each of the three scenarios: input, view, and edit. We can use the same template here for input and edit with a simple checking to keep the old field selected for the edit scenario. Let us look at the templates:
- edit-userCFFunction.vm: Displays all custom fields and highlights the already selected one in the edit mode:
```
	
	
	
```
- view-userCFFunction.vm .displays the selected field:
```
	
#if ($user)
	  The 'Test User' CF will be set with value : $user!
	#end	
	
```

The third step is to write the actual function. The function class must extend the AbstractJiraFunctionProvider interface. All we need here is to implement the execute method. In our example, we retrieve the username from the issue and set it on the Test User custom field:

	
public void execute(Map transientVars, Map args, PropertySet ps)
	throws WorkflowException {
		MutableIssue issue = getIssue(transientVars);
		User user = null;	if (args.get("user") != null) {
		  String userName = (String) args.get("user");
		  if (userName.equals("Current User")){
			// Set the current user here!
			user = authContext.getUser();
		  } else {
			user = userUtil.getUser(userName);
		  }
		} else {
		  // Set the current user here!
		  user = authContext.getUser();
		}
		// Now set the user value to the custom field
		CustomField userField =
	customFieldManager.getCustomFieldObjectByName("Test User");
		if (userField != null) {
		  try {
			setUserValue(issue, user, userField);
		  } catch (FieldLayoutStorageException e) {
			System.out.println("Error while setting the user Field");
		  }
		}
	 }

Like a validator, the issue on which the post function is executed can be retrieved using the transientVars map. The user can be retrieved from the args map.
Here the setUserValue method simply sets the username on the passed custom field, as shown in the following block of code:

	
private void setUserValue(MutableIssue issue, User user,
	CustomField userField) throws FieldLayoutStorageException {
		issue.setCustomFieldValue(userField, user);
		Map modifiedFields = issue.getModifiedFields();
		FieldLayoutItem fieldLayoutItem =
	ComponentManager.getInstance().getFieldLayoutManager().getFieldLay
	out(issue).getFieldLayoutItem(userField);
		DefaultIssueChangeHolder issueChangeHolder = new
	DefaultIssueChangeHolder();
		final ModifiedValue modifiedValue = (ModifiedValue)
	modifiedFields.get(userField.getId());	
	userField.updateValue(fieldLayoutItem, issue, modifiedValue,
	issueChangeHolder);
	  }

All that is left now is to populate the atlassian-plugin.xml file with these components. We use the workflow-condition module and it looks like the following block of code:
```
	
	
	
```
Package the plugin and deploy it!
How it works...
After the plugin is deployed, we need to modify the workflow to include the function. The following is where the function appears along with the built-in ones:

/sites/default/files/Article-Images/1803-04-08.png

Clicking on our post function takes us to the configuration page, shown next. This, as you now know, is rendered using the input template:

After the function is added (after entering in the UserName field), it looks as follows:

If you try to edit, the screen will be rendered using the edit template, as shown in the following screenshot:

Note that the UserName field is already populated.
After the workflow is configured, when the user executes the workflow action, the Test User custom field is set with the value jobinkk.

Editing an active workflow
We have seen how the workflow plays an important role in configuring our JIRA and how we can write plugins to add more workflow conditions, validators, and post functions. Once these plugins are added, we need to modify the workflow to include the newly created components at the appropriate transitions.
Modifying an inactive workflow or creating a new workflow is pretty easy. You can add the conditions/validators/post functions when you create the transition or just click on the transition to modify them. But to edit an active workflow, there are a few more steps involved which we will see in this recipe.
A workflow is active when it is being used in an active workflow scheme that is tied to a project. You can check whether a workflow is active by navigating to Administration Global Settings | Workflows|.

How to do it...
The following are the steps to edit an active workflow:

Login as a JIRA Administrator.
Navigate to Administration Global Settings | Workflows|.
Click on the Create a draft workflow link on the workflow you want to edit. The link can be found under the Operations column.
Click on the step or transition that you want to modify.
Make the changes. The changes won't be effective until the workflow is published.
After all the changes are made, click on the publish this draft link at the top of the page if you are still viewing the modified workflow. You can also click on Publish under the Operations column while viewing all the workflows.
Make a copy of the old workflow, when prompted, if you need a backup, and click on Publish.

How it works...
After making changes on the draft and clicking on Publish, the new workflow will be active. However, there are some limitations to this procedure, which are detailed as follows:

You can't delete an existing workflow step
You can't edit the status associated with an existing step
If an existing step has no outgoing transitions, you can't add any new outgoing transitions
You can't change the step IDs for any existing steps

If you want to overcome these limitations, you need to copy the workflow, modify the copy, and make it active by migrating the projects on to the new workflow.
After the new workflow is active, any transitions on the issue will be based on the new workflow.

There's more...
If you want to modify an active workflow, thus overcoming some of the limitations aforementioned but don't want to go through the pain of migrating all the projects involved, you might want to look at modifying it directly in the JIRA database.
Note that we should be careful about the workflow changes when we do this. For example, if there are issues in a status that is removed in the modified workflow, those issues will be stuck at the removed status. The same can happen for the removed steps.

Modifying workflows in JIRA database

The following are the steps to modify the workflows in the database:

export the workflow that needs to be modified into XML. You can do it using the XML link under the Operations column of a workflow.
Modify the XML to include your changes (or alternatively, make changes in a copy of the JIRA workflow and export that as XML).
Stop the JIRA instance.
Connect to your JIRA database.
Take a backup of the existing database. We can revert to this backup if anything goes wrong.
Update the JIRAWORKFLOWS table to modify the descriptor column with the new XML file for the appropriate workflow. When the workflow XML is huge, it might be useful to rely on database-specific methods to update the table. For example, we can use Oracle XML database utilities (http://download.orac...90/xdb01int.htm), if JIRA is connected to the Oracle database.
Commit the changes and disconnect from the database.
Start the JIRA instance.
Re-index JIRA.

.NET Generics 4.0: Container Patterns and Best...

Wed, 01 Feb 2012 03:28:05 +0000

There are several generic containers and generic algorithms available in the .NET Framework and a couple of other majorly accepted APIs such as Power Collections and C5.
In this article by Sudipta Mukherjee, author of .NET Generics 4.0 Beginner’s Guide, we will take a look at:

Generic container patterns: There are several patterns that are used more than the others in code bases that use Generics. Here, we shall walk through some of these very popular generic structures.
Best practices: Here we shall walk through a list of best practices with succinct causes to back them.

Generic container patterns
There are several generic containers such as List, Dictionary, and so on. Now, let's take a look at some of the patterns involving these generic containers that show up more often in code.

How these are organized
Each pattern discussed in this article has a few sections. First is the title. This is written against the pattern sequence number. For example, the title for Pattern 1 is One-to-one mapping. The Pattern interface section denotes the interface implementation of the pattern. So anything that conforms to that interface is a concrete implementation of that pattern. For example, Dictionary is a concrete implementation of IDictionary. The Example usages section shows some implementations where TKey and TValue are replaced with real data types such as string or int. The last section, as the name suggests, showcases some ideas where this pattern can be used.

Pattern 1: One-to-one mapping

One-to-one mapping maps one element to another.

Pattern interface

The following is an interface implementation of this pattern:
IDictionary

Some concrete implementations

Some concrete implementations of this pattern are as follows:

Example usages

The following are examples where TKey and TValue are replaced with real data types such as string or int:

Dictionary
SortedDictionary
SortedList
Dictionary

Some situations where this pattern can be used

One-to-one mapping can be used in the following situations:

Mapping some class objects with a string ID
Converting an enum to a string
General conversion between types
Find and replace algorithms where the find and replace strings become key and value pairs
Implementing a state machine where each state has a description, which becomes the key, and the concrete implementation of the IState interface becomes the value of a structure such as Dictionary

Pattern 2: One-to-many unique value mapping

One-to-many unique value mapping maps one element to a set of unique values.

Pattern interface

The following is an interface implementation of this pattern:
IDictionary>

Some concrete implementations

Some concrete implementations of this pattern are as follows:

Dictionary>
SortedDictionary>
SortedList>
Dictionary>

Example usages

The following are examples where TKey and TValue are replaced with real data types such as string or int:

Some situations where this pattern can be used

One-to-many unique value mapping can be used in the following situations:

Mapping all the anagrams of a given word
Creating spell check where all spelling mistakes can be pre-calculated and stored as unique values

Pattern 3: One-to-many value mapping

One-to-many value mapping maps an element to a list of values. This might contain duplicates.

Pattern interface

The following are the interface implementations of this pattern:

Some concrete implementations

Some concrete implementations of this pattern are as follows:

Dictionary>
SortedDictionary>
SortedList>
Dictionary>

Example usages

The following are examples where TKey and TValue are replaced with real data types such as string or int:

Dictionary>
SortedDictionary>
SortedList>
Dictionary>

Some situations where this pattern can be used

One-to-many value mapping can be used in the following situations:

Mapping all the grades obtained by a student. The ID of the student can be the key and the grades obtained in each subject (which may be duplicate) can be stored as the values in a list.
Tracking all the followers of a Twitter account. The user ID for the account will be the key and all follower IDs can be stored as values in a list.
Scheduling all the appointments for a patient whose user ID will serve as the key.

Pattern 4: Many-to-many mapping

Many-to-many mapping maps many elements of a group to many elements in other groups. Both can have duplicate entries.

Pattern interface

The following are the interface implementations of this pattern:

Some concrete implementations

A concrete implementation of this pattern is as follows:
IList>>

Example usages

The following are examples where TKey and TValue are replaced with real data types such as string or int:

Some situations where this pattern can be used

Many-to-many mapping can be used in the following situations:

If many independent values can be mapped to a set of values, then these patterns should be used. ISet implementations don't allow duplicates while ICollection implementations, such as IList, do.
Imagine a company wants to give a pay hike to its employees based on certain conditions. In this situation, the parameters for conditions can be the independent variable of the Tuples, and IDs of employees eligible for the hike can be stored in an ISet implementation.

For concurrency support, replace non-concurrent implementations with their concurrent cousins. For example, replace Dictionary with ConcurrentDictionary.

A special Tuple pattern
Since Tuple is a new inclusion in the .NET 4.0 Framework and can prove to be handy in a lot of situations, I thought it would be a great place to showcase an unusual use of this beautiful data representation technique.

Let's say we have situations involving four integers. This is generally represented using nested if-else blocks, as shown in the following code. However, we can use a Tuple to refactor this code, as we shall see in a while:

Create a console app and add these four variables:

	
static int x = 11;
	static int y = 9;
	static int z = 20;
	static int w = 30;

Now, add these nested if-else blocks in the Main() method:

	
if (x > 9)
	{
	  if (y > x)
	  {
		if (z > y)
		{
		  if (w > 10)
		  {
			Console.WriteLine(" y > x and z > y and w > 10 ");
		  }
		  else
		  {
			Console.WriteLine(" y > x and z > y and w	   }
		}
		else
		{
		  if (w > 10)
		  {
			Console.WriteLine(" y > x and z  10 ");
		  }
		  else
		  {
			Console.WriteLine(" y > x and z	   }
		}
	  }
	  else
	  {
		if (z > y)
		{
		  if (w > 10)
		  {
			Console.WriteLine(" y  y and w > 10 ");
		  }
		  else
		  {
			Console.WriteLine(" y  y and w	   }
		}
		else
		{
		  if (w > 10)
		  {
			Console.WriteLine(" y  10 ");
		  }
		  else
		  {
			Console.WriteLine(" y	   }
		}
	  }
	}

If you run this, you shall see the following output:
```
	
y  y and w > 10	
	
```
Although this code performs the job, it has the following problems:
- It is very long. Most programmers will lose track of what they were reading.
- It is impossible to re-use any part of the code that is available under a specific branching.

Time for action – refactoring deeply nested if-else blocks
Follow the given steps:

We must acknowledge that by using a maximum of four variables there can be 16 different branchings. Of these only eight are shown here. This type of code can be remodeled using the following structure. Now, delete everything in the Main() method and copy the following code:

	
//Creating rules list
	List>>
	rules =
	new Liststring>>>();
	
	//adding rules.The benefit is that entire nested if-else is
	//flatend.
	rules.Add(new Tupleint, string>>
	(x > 9, y > x, z > y, w > 10, DoThis));
	rules.Add(new Tupleint, string>>
	(x > 9, y > x, z > y, w rules.Add(new Tupleint, string>>
	(x > 9, y > x, z  10, DoThis));
	rules.Add(new Tupleint, string>>
	(x > 9, y > x, z rules.Add(new Tupleint, string>>
	(x > 9, y  y, w > 10, DoThis));
	rules.Add(new Tupleint, string>>
	(x > 9, y  y, w rules.Add(new Tupleint, string>>
	(x > 9, y  10, DoThis));
	rules.Add(new Tupleint, string>>
	(x > 9, y 
	Console.WriteLine ("Printing using tuple");
	//Finding the first rule that matches these conditions.
	Tuple>
	matchingRule
				= rules.First
				   (
					 rule =>
						rule.Item1 == GetExpression(x, 9)
						//represents x > 9
						&& rule.Item2 == GetExpression(y, x)
						//represents y > x
						&& rule.Item3 == GetExpression(z, y)
						//represents z > y
						&& rule.Item4 == GetExpression(w, 10)
						//represents w > 10
					  );
	//Find the Matching function.
	Func function = matchingRule.Item5;
	//Invoke the function.
	Console.WriteLine(function.Invoke(x,y,z,w));

This will not compile yet because the DoThis() and GetExpression() methods are not defined. So add these methods as follows:

	
private static string DoThis(int x, int y, int z, int w)
	{
	  string partOne = y > x ? " y > x " : " y   string partTwo = z > y ? " z > y " : " z   string partThree = w > 10 ? " w > 10 " : " w   return partOne + "and" + partTwo + "and" + partThree;
	}
	
	private static bool GetExpression(int x, int y)
	{
	  return x > y;
	}

What just happened?
Now if you run the program, you shall see the same output as before:


y  y and w > 10

So you saw how the if-else blocks were removed while the rules are still intact. Moreover, the code is more readable now.

Let's see how this worked. Notice carefully that the last parameter of the Tuples used in the rules is Func. This means, we can place any function that takes four integer parameters and returns a string. The DoThis() method matches this requirement and so we place it in the list:


Tuple>

The previous list represents a relationship between four Boolean expressions and a function. These Boolean expressions are independent and the associated function is found using the following concern:


Func function = matchingRule.Item5;

Invoke() is a method to call the function.

Best practices when using Generics
The following are the best practices to be followed while using Generics:

Don't use Generics when you know the situation won't always be generic.
Use Stack for a Last In First Out (LIFO) list implementation.
Use Queue for a First In First Out (FIFO) implementation.
Use List for random access lists with zero-based indexing.
Use LinkedList to implement a deque because it offers faster insertion and deletion at both ends as opposed to other collections.
If you have to frequently insert random locations in the list, prefer LinkedList over List because LinkedList is a constant time operation to insert one item in between two elements in a linked list.
If the random list does not have a duplicate, use HashSet instead. It is the fastest.
Don't use a for loop over a IDictionary implementation. It can give incorrect results. Use a foreach loop over the keys collection instead.
Avoid using ElementAt() or, its cousin, the ElementAtOrDefault() method on generic collections that natively don't support zero-based integer indexing, (for example, Stack or Dictionary); since dictionary elements are not guaranteed to be available on an index where they were added.
Don't use a Tuple with more than seven parameters. Create a class with those parameters and then create a list of that class' objects. Using a Tuple with more than four parameters makes the code look messy and it's not efficient.
Use SortedDictionary just to get the entries sorted. Don't use it to store simple associative "one-to-one" and "one-to-many" relationships as keeping the keys sorted isn't absolutely necessary. It is very slow compared to a normal dictionary.
Use HashSet to create a generic set. It's the fastest set implementation available in the .NET Framework.
Use SortedSet only to create a sorted generic set. Don't use it when you don't want the set to be sorted because it is slower than HashSet.
Don't expect indexing to work on an array or a list as it would on sets or dictionaries, because sets and dictionaries use hashing or tree-based internal data structures to place elements in the collection.
Use the available bare minimum implementation for your customized need or resort to creating your own custom collection class from the interfaces. This is a design guideline. Try to make sure your code is as lightweight as possible. If you want a queue, use a Queue instead of a List.
Use LinkedList when you need to insert elements at arbitrary positions but you don't need to access them randomly via integer indexing.
Use KeyValuePair to store a key value pair. Avoid using Tuple> for this purpose because KeyValuePair is more efficient.
Prefer Dictionary> over List> whenever possible for representing a one-to- many relationship between two entities. Lookup speed will be much faster and client code will be less clumsy.
Prefer List> to represent a many-to-one relationship between two entities over Dictionary,TValue> if there is a duplicate.
If no more entries need to be added to a collection, call TrimExcess() to free up the extra memory.
Prefer LINQ Standard Query Operator Where() over Contains(), Exists(), or Find() methods to check whether a value is present in a List instance.
If you implement IEnumerable in your custom collection, don't forget to implement IEnumerable also. This is to ensure backward compatibility and the Liskov substitution principle.
Use SortedList if you want a concrete implementation of IDictionary that supports native indexing. However, it is slower than Dictionary. Avoid SortedList when you don't want indexing.
Don't use the ElementAt() or the ElementAtOrDefault() method on IDictionary implementations except SortedList, because dictionary elements are not guaranteed to be in the index where they are added.
Avoid conversions between data structure formats (for example, array to list, or vice versa using LINQ operators) as far as possible. Use other language constructs. For example, consider using a foreach loop than converting an IEnumerable instance to a list using the ToList() method before performing some operations on each item in the list.
Use the OrderBy() or the OrderByDescending() method to sort any IEnumerable.

Selecting a generic collection
Not all generic containers are geared to do each job well, as we already know it. Here is a table that will let you pick a generic container that supports some features listed in the lefthand column.

You can download the GenGuru app from the support website. It's a kind of wizard that will recommend the generic containers available in .NET Generics that you should use. It will ask you few questions and recommend a collection. You can see it in action at http:// sudipta.posterous.com/private/niixaeFlmk.

Best practices when creating custom generic collections
The following are the best practices while creating custom generic collections:

Try to use built-in generic classes for maintaining internal data structures.
Try to use interfaces as return type and method arguments for publicly exposed methods for your collection. For example, consider using IEnumerable over List.
Try to keep the names aligned as much as possible towards the names available in frameworks. For example, if you are creating a concrete implementation of IDictionary then try to use the suffix Dictionary in the name of the class, such as MultiDictionary.
Try to provide overloaded constructors to offer flexibility such that the class can be created from many diverse data sources.
Use Generics constraints judiciously. Remember that these constraints are like boomerangs. You should know what exactly you can allow as an input parameter for a constrained generic type. Otherwise, these can backfire and hurt you and the users of your collection.
Make sure to always implement the IEnumerable, IEnumerable, ICollection, IDisposable, and IClonable interfaces.
Make sure that your collection confirms to the Liskov substitution principle. Divide into subclasses only when it makes sense, otherwise use composition.
Offer a constructor overload to create a thread-safe instance of your collection.
Make sure it supports LINQ, which will be obvious if you implement IEnumearble properly. LINQ is changing the way we see and solve problems. So if you miss LINQ, your collection will probably fail to impress a large section of the target audience.
Thrive for performance. Make sure that performance is as best as it could be.
Make sure your collection is as lightweight as possible. If a Queue can do what you want done internally in your collection, use it. Don't consider using a more versatile list implementation such as List.
Don't write raw events by yourself to monitor the collection; rather expose ObservableCollection to offer this functionality.
Don't provide functionalities that can be achieved by a simple combination of exposed functions. For example, take a look at the Date Time API from the .NET Framework. There is a method called AddDays() that can take a positive or negative integer such that you can go to a past or a future date. However, the framework doesn't provide a method or a public property to compute Tomorrow() or Yesterday() as they can be easily calculated using the AddDays() method. While exposing public functions for your generic collection, remember to expose only those methods that can be used as building blocks for several reasons.
However, you have to strike a balance. The framework also has the AddYears() method because it will be cumbersome, although technically achievable, to duplicate AddYears() using the AddDays() method.

Remember these points while coming up with your own generic collection.

Summary
In this article, we took a look at generic container patterns and best practices for Generics.

Sedge: An Automated Error Reporting Tool

Mon, 30 Jan 2012 20:26:03 +0000

License: Ms-PL

Introduction

Every developer knows how important a good bug report is, and every developer wants as much details about the issue as the user can provide. There are different solutions that aim to facilitate the error reporting process, from tiny third-party components to such powerful technologies like Microsoft Windows Error Reporting, but most of them are designed to report fatal error only.

Missed text, incorrect functionality, wrong output - your users may want to report these issues too. And, even if it looks like a minor problem for the user, you may want to see log files, configurations, system information, etc. Moreover, the user may use multiple applications developed by your company, and to locate the problem, you may be interested to add to the report a few common logs or configurations.

All these thoughts were taken into account during the designing of Sedge - an Open Source, free utility that helps to automate error reporting by collecting all the necessary information, files, descriptions, and presenting it in a nice HTML view. The target platform is Microsoft .NET 2.0.

How it works

Sedge is a wizard style application, and proposes the user to take an issue screenshot, enter description and contact information, and add the user's files. The last step of the wizard is a report generation. Sedge copies all the files you want to see in the report, collects system information, creates report HTML pages, and zips the report. The user can review the report and email it to you.

The configuration file (default extension is .sedge) is the key to all the features of the tool. The configuration describes all the aspects of the process - the wizard's steps, files, and information to collect, report representation, etc. If the path to the configuration file is not provided as a command line parameter, Sedge will try to read it from Sedge.exe.config and tries to search for it in the current folder and subfolders.

Command line example:



Sedge.exe /suite="C:\Apps\QuickStart.sedge"

Configuration example:



?>
xml version="1.0" encoding="UTF-8" >

  	   caption="TaggedFrog Error Reporting" partial="no">

The main unit of the configuration is a suite. The suite represents a collection of the related applications, and could be described in one file or split into multiple parts. This means that you can have one main configuration file describing the wizard UI and the common properties, and add/remove the suite part when you install/uninstall applications. The error report will include information requested in the main configuration plus information specific for the reported application (see Sample 4 in the attached archive).

The schedule section describes the steps that will be displayed to the user. Every step tag represents a class implementing the IStepController interface, and you can easily create your own steps to add or replace the existing ones (Sample 5). Because the GUI code is separated from the logic, you can even completely replace the user interface, for example, if you like to use WPF instead of WinForms.

Eventually, you are able to customize almost every aspect of the process. For example, if you don't like e-mail as a method of reports delivering, you can add your own transport protocol.

Report

The next aspect of the report generations is... the report itself. The configuration defines the structure of the report while the style is controlled by the template. The template consists of the HTML, CSS files, and the images, so you can modify it to match your corporate style.

Every page may include one or more sources of information to report. There are four types of sources:

displays information provided by the user (screenshots, error details, etc.)
displays information about the files - path, size, and version
instructs the application to copy files to the report and print links to these files on the page
is actually a meta-source; the name attribute is used to select a class implementing the IDataSource interface and returning the required information

Out of the box, there are three classes:

Processes to display the running processes information
System to display information about the OS and the hardware
Table to print the provided information in the table form; it can be used to display the information contained in the properties

And as usual, you can create your own source:



<Data name="CurrentDate" assembly="${custom.dll}" caption="Now" />

A property is a container that can store text information, and can be set directly in the configuration to get a value from the Registry. If you'd like to setup a property in a different way, for example from .ini files, you are able to create a custom property handler.



public class EchoProperty : ICustomProperty
{
	public string GetValue(Options options)
	{
		return String.Concat("Echo: ", 
		  options.GetGeneralOption("Param", "param"));
	}
}




		  value="${sedge.this.folder}\DLL\Demo.Customization.dll" />
		  assembly="${custom.dll}" value="Echo">

Two predefined properties are available in every configuration: ${sedge.this.folder} - the path to the configuration file, and ${sedge.this.file} - the configuration file name.

To be usable in the real world, Sedge supports localization and rebranding. All strings are located in a separate file; you can modify the current translation or add a new one, and change the application name.

Conclusion

Sedge aims to help your customers create better bug reports, and gives you a way to control what information should be added to the report. With Sedge, users can report not only fatal crashes but also usability issues, incorrect functionality, etc. One of the main tasks of the application is to provide an error report in the context of the application suites, and it could be achieved using partial configurations. Sedge can be used as a ready-to-go tool, or customized to satisfy your specific goals.

Project site: sedge.codeplex.com.

First version of the article.

About the Author

I am a software developer from Toronto with 15 years of experience in software design and development. My major professional area is the development of highly customized software solutions, including desktop and web applications. Industrial process automation and hardware-related software development are among my favorite projects and I enjoyed developing several applications for semiconductor manufacturing companies.

My blog: http://LunarFrog.com/blog

License

This article was authored by Andrei Marukovich and reproduced for the benefit of our viewers under the terms of the Ms-PL license.

Wrapper Pattern for Silverlight and WPF

Mon, 30 Jan 2012 20:22:05 +0000

Download sample (Silverlight and WPF) - 368 KB

License: Ms-PL

Table of contents

Introduction

It has been a long time since my last article. This one is short and a bit less creative than the previous ones, but I hope you'll like it!

I hope none of you have never particularly talked about that before, but probably you have already used what I will talk about, without naming it: the wrapper pattern in WPF and Silverlight.

Pattern sheet

Pattern type: Presentation pattern.

Problem: You want to create an animation or to bind on a property which does not exist on your object -the target- or doesn't support the use of Storyboard or Binding.

Solution: Create an object -a wrapper- which will expose this property, and will modify the target object accordingly.

Alternatives:

Use attached properties; however, it will fail in Silverlight 3.0 (it does not support animation on attached properties in XAML).
Use a decorator, but it doesn't exist on Silverlight, and sometimes makes your XAML harder to read.

Actor:

The object we want to animate is called the "target".
The object we will create to expose new properties to animate is called the "wrapper".

Concrete examples

The first is a common problem in Silverlight: binding to the ActualWidth/Height property.
The second is an element hider; it allows you to show or "push" an element at the border of the screen (like dockable views in Visual Studio).

For these two examples, the wrapper pattern provides a really nice solution.

Example 1 - Binding to ActualWidth and ActualHeight

Here is the example:

The sliders are bound to the Height and Width of a grid which wraps the green rectangle. The red rectangle's width and height are bound to ActualWidth and ActualHeight of the green rectangle. The Height and Width properties of the green rectangle are not set.

Here is the code:



<StackPanel>
	<Canvas Background="Yellow" Height="500" Width="500" >
		<Grid x:Name="grid" Canvas.Top="0" Height="100" Width="100">
			<Rectangle x:Name="greenRect" Fill="Green"></Rectangle>
		</Grid>
		<Rectangle Canvas.Top="300" Fill="Red" 
		  Height="{Binding ActualHeight, ElementName=greenRect}" 
		  Width="{Binding ActualWidth, ElementName=greenRect}"></Rectangle>
	</Canvas>
	
	<Slider Maximum="500" Minimum="0" 
	  Value="{Binding Height, ElementName=grid, Mode=TwoWay}"></Slider>
	<Slider Maximum="500" Minimum="0" 
	  Value="{Binding Width, ElementName=grid, Mode=TwoWay}"></Slider>
</StackPanel>

I want the green and red rectangle to have the same size, and everything goes well in the world of WPF... but Silverlight can't bind to ActualHeight and ActualWidth. So, what is the solution? It's simple, we will create a wrapper, SizeWrapper, with three properties: RealWidth, RealHeight, and Element, the target element.

It will listen to the SizeChanged event of the target element and update its two properties. Here is the code:



public class SizeWrapper : FrameworkElement
{
	public FrameworkElement Element
	{
		get
		{
			return (FrameworkElement)GetValue(ElementProperty);
		}
		set
		{
			SetValue(ElementProperty, value);
		}
	}

	public double RealHeight
	{
		get
		{
			return (double)GetValue(RealHeightProperty);
		}
		set
		{
			SetValue(RealHeightProperty, value);
		}
	}

	// Using a DependencyProperty as the backing store for RealHeight.
	// This enables animation, styling, binding, etc...
	public static readonly DependencyProperty RealHeightProperty =
		DependencyProperty.Register("RealHeight", 
		typeof(double), typeof(SizeWrapper), Helper.CreateMetadata(.));

	public double RealWidth
	{
		get
		{
			return (double)GetValue(RealWidthProperty);
		}
		set
		{
			SetValue(RealWidthProperty, value);
		}
	}

	// Using a DependencyProperty as the backing store for RealWidth.
	// This enables animation, styling, binding, etc...
	public static readonly DependencyProperty RealWidthProperty =
		DependencyProperty.Register("RealWidth", 
		typeof(double), typeof(SizeWrapper), Helper.CreateMetadata(.));

	// Using a DependencyProperty as the backing store
	// for Element. This enables animation, styling, binding, etc...
	public static readonly DependencyProperty ElementProperty =
		DependencyProperty.Register("Element", typeof(FrameworkElement), 
		typeof(SizeWrapper), Helper.CreateMetadata(null, OnElementChanged));

	private static void OnElementChanged(DependencyObject sender, 
			DependencyPropertyChangedEventArgs args)
	{
		var wrapper = (SizeWrapper)sender;
		var oldElement = args.OldValue as FrameworkElement;
		var newElement = args.NewValue as FrameworkElement;
		if(oldElement != null)
			oldElement.SizeChanged -= wrapper.SizeChanged;
		if(newElement != null)
		{
			newElement.SizeChanged += wrapper.SizeChanged;
			wrapper.UpdateSize(new Size(newElement.ActualWidth, 
										newElement.ActualHeight));
		}
	}

	void SizeChanged(object sender, SizeChangedEventArgs e)
	{
		UpdateSize(e.NewSize);
	}

	private void UpdateSize(Size size)
	{
		RealHeight = size.Height;
		RealWidth = size.Width;
	}
}

Now, here is the slightly modified version. The only modification is that the red rectangle binds to the wrapper's properties instead of the green rectangle directly. As you will expect, it works well. The wrapper is inside the canvas.



<StackPanel>
	<Canvas Height="500" Width="500" >
		<wrappers:SizeWrapper x:Name="sizeWrapper" 
				   Element="{Binding ElementName=greenRect}"></wrappers:SizeWrapper>
		<Grid x:Name="grid" Canvas.Top="0" 
				   Height="100" Width="100">
			<Rectangle x:Name="greenRect" Fill="Green"></Rectangle>
		</Grid>
		<Rectangle Canvas.Top="300" Fill="Red" 
		  Height="{Binding RealHeight, ElementName=sizeWrapper}" 
		  Width="{Binding RealWidth, ElementName=sizeWrapper}"></Rectangle>
	</Canvas>

	<Slider Maximum="500" Minimum="0" 
	  Value="{Binding Height, ElementName=grid, Mode=TwoWay}"></Slider>
	<Slider Maximum="500" Minimum="0" 
	 Value="{Binding Width, ElementName=grid, Mode=TwoWay}"></Slider>
</StackPanel>

Example 2 - Element hider

Some of you might say: well, it's just useful for a specific workaround; wait a second, read this second example, and you'll appreciate the simplicity!

This example should deserve its own article because I suspect lots people would want it.

This time we will use a wrapper called 'ElementHidderWrapper' to "push" an element on the border of the screen (as you can do with the dockable views in Visual Studio).

If Show is 0, then the target is completely collapsed; if it is 1.0, it's completely visible. MinMargin is the minimum margin to show when Show equals 0. HideSide is the side where the element will hide. Here is how to use it:



<Grid>
	<wrappers:ElementHidderWrapper
		x:Name="hidder"
		Element="{Binding ElementName=border}"
		MinMargin="20"
		HideSide="Left"
		Show="1.0"
		></wrappers:ElementHidderWrapper>

	<Border x:Name="border" HorizontalAlignment="Left" 
			VerticalAlignment="Top" BorderThickness="1.0" 
			Width="100" Height="300" 
			BorderBrush="Black" 
			CornerRadius="0,10,10,0" Background="Green">
		<Grid>
			<TextBlock Text="blabla" 
			   HorizontalAlignment="Center" 
			   VerticalAlignment="Top"></TextBlock>
			<CheckBox IsChecked="True" 
			   HorizontalAlignment="Right" 
			   VerticalAlignment="Bottom" 
			   Click="CheckBox_Click">
			</CheckBox>
		</Grid>
	</Border>
</Grid>

The target element is the border. Initially, everything is shown. MinMargin is set to 20 px; this way, we can always click on the checkbox. When you click on the checkbox, it will hide/show the border to the left. It's easy to do, I just need to fire an animation on the Show property of my wrapper.



private void CheckBox_Click(object sender, RoutedEventArgs e)
{
	CheckBox checkBox = (CheckBox)sender;
	Storyboard storyBoard = new Storyboard();
	DoubleAnimation showAnimation = new DoubleAnimation();
	Storyboard.SetTarget(showAnimation, hidder);
	Storyboard.SetTargetProperty(showAnimation, new PropertyPath("Show"));
	showAnimation.Duration = new Duration(new TimeSpan(, , , , 400));
	showAnimation.To = checkBox.IsChecked.Value ? 1. : .;
	storyBoard.Children.Add(showAnimation);
	storyBoard.Begin();
}

The code of the wrapper is not the point, but I will quickly explain: every time a property of the wrapper changes, I recalculate the margins of the target, and it's done.



public enum HideSide
{
	Top,
	Bottom,
	Left,
	Right
}

public class ElementHidderWrapper : FrameworkElement
{
	public double MinMargin
	{
		get
		{
			return (double)GetValue(MinMarginProperty);
		}
		set
		{
			SetValue(MinMarginProperty, value);
		}
	}

	// Using a DependencyProperty as the backing store for MaxShow.
	// This enables animation, styling, binding, etc...
	public static readonly DependencyProperty MinMarginProperty =
		DependencyProperty.Register("MinMargin", typeof(double), 
		typeof(ElementHidderWrapper), 
		Helper.CreateMetadata(., MinMarginChanged));

	private static void MinMarginChanged(DependencyObject sender, 
						DependencyPropertyChangedEventArgs args)
	{
		ElementHidderWrapper hidder = (ElementHidderWrapper)sender;
		hidder.UpdateElement();
	}

	public HideSide HideSide
	{
		get
		{
			return (HideSide)GetValue(HideSideProperty);
		}
		set
		{
			SetValue(HideSideProperty, value);
		}
	}

	// Using a DependencyProperty as the backing store
	// for HideSide. This enables animation, styling, binding, etc...
	public static readonly DependencyProperty HideSideProperty =
		DependencyProperty.Register("HideSide", typeof(HideSide), 
		typeof(ElementHidderWrapper), Helper.CreateMetadata(HideSide.Bottom));

	public double Show
	{
		get
		{
			return (double)GetValue(ShowProperty);
		}
		set
		{
			SetValue(ShowProperty, value);
		}
	}

	// Using a DependencyProperty as the backing store for Show.
	// This enables animation, styling, binding, etc...
	public static readonly DependencyProperty ShowProperty =
		DependencyProperty.Register("Show", typeof(double), 
		typeof(ElementHidderWrapper), Helper.CreateMetadata(1., ShowChanged));

	public FrameworkElement Element
	{
		get
		{
			return (FrameworkElement)GetValue(ElementProperty);
		}
		set
		{
			SetValue(ElementProperty, value);
		}
	}

	// Using a DependencyProperty as the backing store for Element.
	// This enables animation, styling, binding, etc...
	public static readonly DependencyProperty ElementProperty =
		DependencyProperty.Register("Element", 
		typeof(FrameworkElement), typeof(ElementHidderWrapper), 
		Helper.CreateMetadata(null, ElementChanged));

	private static void ElementChanged(DependencyObject sender, 
						DependencyPropertyChangedEventArgs args)
	{
		ElementHidderWrapper hidder = (ElementHidderWrapper)sender;
		FrameworkElement oldValue = args.OldValue as FrameworkElement;
		FrameworkElement newValue = args.NewValue as FrameworkElement;
		if(oldValue != null)
			oldValue.SizeChanged -= hidder.SizeChanged;
		if(newValue != null)
			newValue.SizeChanged += hidder.SizeChanged;
		hidder.UpdateElement();
	}

	private void SizeChanged(object sender, SizeChangedEventArgs e)
	{
		UpdateElement();
	}

	private static void ShowChanged(DependencyObject sender, 
			DependencyPropertyChangedEventArgs args)
	{
		ElementHidderWrapper hidder = (ElementHidderWrapper)sender;
		hidder.UpdateElement();
	}

	private void UpdateElement()
	{
		if(Element == null)
			return;
		var maxValue = GetMaxShowValue(Element);
		var minValue = MinMargin;
		var calculatedShowValue = minValue + (maxValue - minValue) * Show;
		var marginValue = maxValue - calculatedShowValue;
		SetMarginValue(Element, marginValue);

	}

	private void SetMarginValue(FrameworkElement element, double marginValue)
	{
		if(HideSide == HideSide.Left)
		{
			element.Margin = new Thickness(-marginValue, 
			  element.Margin.Top, element.Margin.Right, element.Margin.Bottom);
		}
		else if(HideSide == HideSide.Top)
		{
			element.Margin = new Thickness(element.Margin.Left, 
			  -marginValue, element.Margin.Right, element.Margin.Bottom);
		}
		else if(HideSide == HideSide.Right)
		{
			element.Margin = new Thickness(element.Margin.Left, 
			  element.Margin.Top, -marginValue, element.Margin.Bottom);
		}
		else if(HideSide == HideSide.Bottom)
		{
			element.Margin = new Thickness(element.Margin.Left, 
			  element.Margin.Top, element.Margin.Right, -marginValue);
		}
	}

	private double GetMaxShowValue(FrameworkElement element)
	{
		if(HideSide == HideSide.Bottom || HideSide == HideSide.Top)
			return element.ActualHeight;
		else
			return element.ActualWidth;
	}
}

Conclusion

This pattern is not great news; however, putting a name on something will help people to use and remember where it fits well. This pattern should definitively be in the toolbox of the WPF/SL developer.

About the Author

My goal as a developer, a community member, and enterpreneur is the same : making the minimal product that will help then getting myself out the way. My work is yours.

If you are interested for working with me, this way

License

This article was authored by Nicolas Dorier and reproduced for the benefit of our viewers under the terms of the Ms-PL license.

Inter-Process Communication (IPC) Introduction...

Mon, 30 Jan 2012 20:18:28 +0000

Download IPC source code - 229.21 KB

License: Ms-PL

Introduction

Inter-Process Communication (IPC) is a set of techniques for the exchange of data among multiple threads in one or more processes. Processes may be running on one or more computers connected by a network. IPC techniques include Named Pipes, File Mapping, Mailslot, Remote Procedure Calls (RPC), etc.

In All-In-One Code Framework, we have already implemented samples (C++ and C#) for Named Pipes, File Mapping, Mail Slot, and Remoting. We are going to add more techniques like: Clickbord, Winsock, etc. You can download the latest code from http://cfx.codeplex.com/.

Background

All-In-One Code Framework (short as AIO) delineates the framework and skeleton of most Microsoft development techniques (e.g., COM, Data Access, IPC) using typical sample codes in different programming languages (e.g., Visual C#, VB.NET, Visual C++).

Using the Code

Find samples by following the steps below:

Download the zip file and unzip it.
Open the folder [Visual Studio 2008].
Open the solution file IPC.sln. You must pre-install Visual Studio 2008 on the machine.
In the Solution Explorer, open the [Process] \ [IPC and RPC] folder.

Samples Structure and Relationship

Named Pipe

Named pipes is a mechanism for one-way or bi-directional inter-process communication between a pipe server and one or more pipe clients in the local machine or across computers in an intranet:



[b]PIPE_ACCESS_INBOUND:[/b]

Client (GENERIC_WRITE) ---> Server (GENERIC_READ)


[b]PIPE_ACCESS_OUTBOUND:[/b]

Client (GENERIC_READ) <--- Server (GENERIC_WRITE)


[b]PIPE_ACCESS_DUPLEX:[/b]

Client (GENERIC_READ or GENERIC_WRITE, or both) 
				<--> Server (GENERIC_READ and GENERIC_WRITE)

This sample demonstrates a named pipe server, \\.\pipe\HelloWorld, that supports PIPE_ACCESS_DUPLEX. It first creates such a named pipe, then it listens to the client's connection. When a client is connected, the server attempts to read the client's requests from the pipe and writes a response.

A named pipe client attempts to connect to the pipe server, \\.\pipe\HelloWorld, with the GENERIC_READ and GENERIC_WRITE permissions. The client writes a message to the pipe server and receives its response.

Code Logic

Server-side logic:

Create a named pipe. (CreateNamedPipe)
Wait for the client to connect. (ConnectNamedPipe)
Read client requests from the pipe and write the response. (ReadFile, WriteFile)
Disconnect the pipe, and close the handle. (DisconnectNamedPipe, CloseHandle)

Client-side logic:

Try to open a named pipe. (CreateFile)
Set the read mode and the blocking mode of the specified named pipe. (SetNamedPipeHandleState)
Send a message to the pipe server and receive its response. (WriteFile, ReadFile)
Close the pipe. (CloseHandle)

Code - CreateNamedPipe (C++)



// Create the named pipe.
HANDLE hPipe = CreateNamedPipe(

strPipeName,					  // The unique pipe name. This string must
								  // have the form of \\.\pipe\pipename
PIPE_ACCESS_DUPLEX,			   // The pipe is bi-directional; both 
								  // server and client processes can read
								  // from and write to the pipe
PIPE_TYPE_MESSAGE |			   // Message type pipe
PIPE_READMODE_MESSAGE |		   // Message-read mode
PIPE_WAIT,						// Blocking mode is enabled
PIPE_UNLIMITED_INSTANCES,		 // Max. instances

// These two buffer sizes have nothing to do with the buffers that
// are used to read from or write to the messages. The input and
// output buffer sizes are advisory. The actual buffer size reserved
// for each end of the named pipe is either the system default, the
// system minimum or maximum, or the specified size rounded up to the
// next allocation boundary. The buffer size specified should be
// small enough that your process will not run out of nonpaged pool,
// but large enough to accommodate typical requests.

BUFFER_SIZE,					  // Output buffer size in bytes
BUFFER_SIZE,					  // Input buffer size in bytes
NMPWAIT_USE_DEFAULT_WAIT,		 // Time-out interval
&sa							   // Security attributes
)

For more code samples, please download AIO source code.

Security Attribute for Named Pipes

If lpSecurityAttributes of CreateNamedPipe is NULL, the named pipe gets a default security descriptor and the handle cannot be inherited. The ACLs in the default security descriptor for a named pipe grants full control to the LocalSystem account, administrators, and the creator owner. They also grant read access to members of the Everyone group and the anonymous account. In other words, with NULL as the security attribute, the named pipe cannot be connected with WRITE permission across the network, or from a local client running as a lower integrity level. Here, we fill the security attributes to grant EVERYONE all access (not just the connect access) to the server. This solves the cross-network and cross-IL issues, but it creates a security hole right there: the clients have WRITE_OWNER access and then the server just loses the control of the pipe object.

Code - Security Attributes (C++)



SECURITY_ATTRIBUTES sa;
sa.lpSecurityDescriptor = (PSECURITY_DESCRIPTOR)malloc(SECURITY_DESCRIPTOR_MIN_LENGTH);
InitializeSecurityDescriptor(sa.lpSecurityDescriptor, SECURITY_DESCRIPTOR_REVISION);
// ACL is set as NULL in order to allow all access to the object.
SetSecurityDescriptorDacl(sa.lpSecurityDescriptor, TRUE, NULL, FALSE);
sa.nLength = sizeof(sa);
sa.bInheritHandle = TRUE;

.NET Named Pipe

.NET supports named pipes in two ways:

P/Invoke the native APIs.
By P/Invoke-ing the native APIs from .NET, we can mimic the code logic in CppNamedPipeServer to create the named pipe server, \\.\pipe\HelloWorld, that supports PIPE_ACCESS_DUPLEX.

PInvokeNativePipeServer first creates such a named pipe, then it listens to the client's connection. When a client is connected, the server attempts to read the client's requests from the pipe and write a response.
System.IO.Pipes namespace
In .NET Framework 3.5, the namespace System.IO.Pipes and a set of classes (e.g., PipeStream, NamedPipeServerStream) are added to the .NET BCL. These classes make the programming of named pipes in .NET much easier and safer than P/Invoke-ing the native APIs directly.

BCLSystemIOPipeServer first creates such a named pipe, then it listens to the client's connection. When a client is connected, the server attempts to read the client's requests from the pipe and write a response.

Code - Create Named Pipe (C#)



// Prepare the security attributes 
// Granting everyone the full control of the pipe is just for 
// demo purpose, though it creates a security hole. 
PipeSecurity pipeSa = new PipeSecurity(); 
pipeSa.SetAccessRule(new PipeAccessRule("Everyone", 
	   PipeAccessRights.ReadWrite, AccessControlType.Allow)); 

// Create the named pipe 
pipeServer = new NamedPipeServerStream( 
	strPipeName,					// The unique pipe name. 
	PipeDirection.InOut,			// The pipe is bi-directional 
	NamedPipeServerStream.MaxAllowedServerInstances, 
	PipeTransmissionMode.Message,   // Message type pipe 
	PipeOptions.None,			   // No additional parameters 
	BUFFER_SIZE,					// Input buffer size 
	BUFFER_SIZE,					// Output buffer size 
	pipeSa,						 // Pipe security attributes 
	HandleInheritability.None	   // Not inheritable 
);

File Mapping

File mapping is a mechanism for one-way or bi-directional inter-process communication among two or more processes in the local machine. To share a file or memory, all of the processes must use the name or the handle of the same file mapping object.

To share a file, the first process creates or opens a file by using the CreateFile function. Next, it creates a file mapping object by using the CreateFileMapping function, specifying the file handle and a name for the file mapping object. The names of events, semaphores, mutexes, waitable timers, jobs, and file mapping objects share the same namespace. Therefore, the CreateFileMapping and OpenFileMapping functions fail if they specify a name that is in use by an object of another type.

To share memory that is not associated with a file, a process must use the CreateFileMapping function and specify INVALID_HANDLE_VALUE as the hFile parameter instead of an existing file handle. The corresponding file mapping object accesses memory backed by the system paging file. You must specify a size greater than zero when you specify an hFile of INVALID_HANDLE_VALUE in a call to CreateFileMapping.

Processes that share files or memory must create file views by using the MapViewOfFile or MapViewOfFileEx functions. They must coordinate their access using semaphores, mutexes, events, or some other mutual exclusion techniques.

This example demonstrates a named shared memory server, Local\HelloWorld, that creates the file mapping object with INVALID_HANDLE_VALUE. By using the PAGE_READWRITE flag, the process has read/write permission to the memory through any file view that is created.

The named shared memory client, Local\HelloWorld, can access the string written to the shared memory by the first process. The console displays the message "Message from the first process" that is read from the file mapping created by the first process.

Code Logic

Service-side logic:

Create a file mapping. (CreateFileMapping)
Map the view of the file mapping into the address space of the current process. (MapViewOfFile)
Write message to the file view. (CopyMemory)
Unmap the file view and close the file mapping objects. (UnmapViewOfFile, CloseHandle)

Client-side logic:

Try to open a named file mapping. (OpenFileMapping)
Maps the view of the file mapping into the address space of the current process. (MapViewOfFile)
Read message from the view of the shared memory.
Unmap the file view and close the file mapping objects. (UnmapViewOfFile, CloseHandle)

Code - CreateFileMapping (C++)



// In terminal services: The name can have a "Global\" or "Local\" prefix
// to explicitly create the object in the global or session namespace.
// The remainder of the name can contain any character except the  
// backslash character (\). For details, please refer to: 
// http://msdn.microsoft.com/en-us/library/aa366537.aspx 
TCHAR szMapFileName[] = _T("Local\\HelloWorld"); 

// Create the file mapping object 
HANDLE hMapFile = CreateFileMapping( 
	   INVALID_HANDLE_VALUE,	  // Use paging file instead of existing file. 
								  // Pass file handle to share in a file. 

	   NULL,					  // Default security 
	   PAGE_READWRITE,			// Read/write access 
	   ,						 // Max. object size 
	   BUFFER_SIZE,			   // Buffer size  
	   szMapFileName			  // Name of mapping object 
);

.NET only supports P/Invoke native APIs currently. By P/Invoke, .NET can simulate similar behaviors as native code.

Sample Code 4 (C# - P/Invoke)



/// <summary> 
/// Creates or opens a named or unnamed file mapping object for 
/// a specified file. 
/// </summary> 
/// <param name="hFile">A handle to the file from which to create 
/// a file mapping object.</param> 
/// <param name="lpAttributes">A pointer to a SECURITY_ATTRIBUTES 
/// structure that determines whether a returned handle can be 
/// inherited by child processes.</param> 
/// <param name="flProtect">Specifies the page protection of the 
/// file mapping object. All mapped views of the object must be 
/// compatible with this protection.</param> 
/// <param name="dwMaximumSizeHigh">The high-order DWORD of the 
/// maximum size of the file mapping object.</param> 
/// <param name="dwMaximumSizeLow">The low-order DWORD of the 
/// maximum size of the file mapping object.</param> 
/// <param name="lpName">The name of the file mapping object. 
/// </param> 
/// <returns>If the function succeeds, the return value is a 
/// handle to the newly created file mapping object.</returns> 
[DllImport("Kernel32.dll", SetLastError = true)] 
public static extern IntPtr CreateFileMapping( 
	IntPtr hFile,				   // Handle to the file 
	IntPtr lpAttributes,			// Security Attributes 
	FileProtection flProtect,	   // File protection 
	uint dwMaximumSizeHigh,		 // High-order DWORD of size 
	uint dwMaximumSizeLow,		  // Low-order DWORD of size 
	string lpName				   // File mapping object name 
);

Mailslot

Mailslot is a mechanism for one-way inter-process communication in the local machine or across computers in the intranet. Any client can store messages in a mailslot. The creator of the slot, i.e., the server, retrieves the messages that are stored there:



Client (GENERIC_WRITE) ---> Server (GENERIC_READ)

This sample demonstrates a mailslot server, \\.\mailslot\HelloWorld. It first creates such a mailslot, then it reads the new messages in the slot every five seconds. Then, a mailslot client connects and writes to the mailslot \\.\mailslot\HelloWorld.

Code Logic

Server-side logic:

Create a mailslot. (CreateMailslot)
Check messages in the mailslot. (ReadMailslot)
- Check for the number of messages in the mailslot. (GetMailslotInfo)
- Retrieve the messages one by one from the mailslot. While reading, update the number of messages that are left in the mailslot. (ReadFile, GetMailslotInfo)
Close the handle of the mailslot instance. (CloseHandle)

Client-side logic:

Open the mailslot. (CreateFile)
Write messages to the mailslot. (WriteMailslot, WriteFile)
Close the slot. (CloseHandle)

Code - GetMailslotInfo (C++)



///////////////////////////////////////////////////////////////////////// 
// Check for the number of messages in the mailslot. 
//bResult = GetMailslotInfo( 
		hMailslot,					// Handle of the mailslot 
		NULL,						 // No maximum message size 
		&cbMessageBytes,			  // Size of next message 
		&cMessages,				   // Number of messages 
		NULL);						// No read time-out

Code - CreateMailslot (C# - P/Invoke)



/// <summary> 
/// Creates an instance of a mailslot and returns a handle for subsequent 
/// operations. 
/// </summary> 
/// <param name="lpName">mailslot name</param> 
/// <param name="nMaxMessageSize">The maximum size of a single message 
/// </param> 
/// <param name="lReadTimeout">The time a read operation can wait for a 
/// message</param> 
/// <param name="lpSecurityAttributes">Security attributes</param> 
/// <returns>If the function succeeds, the return value is a handle to 
/// the server end of a mailslot instance.</returns> 
[DllImport("kernel32.dll", SetLastError = true)] 
public static extern IntPtr CreateMailslot( 
	string lpName,			  // Mailslot name 
	uint nMaxMessageSize,	   // Max size of a single message in bytes 
	int lReadTimeout,		   // Timeout of a read operation 
	IntPtr lpSecurityAttributes // Security attributes 
);

Remoting

.NET Remoting is a mechanism for one-way inter-process communication and RPC between .NET applications in the local machine or across computers in the intranet and internet.

.NET Remoting allows an application to make a remotable object available across remoting boundaries, which includes different appdomains, processes, or even different computers connected by a network. .NET Remoting makes a reference of a remotable object available to a client application, which then instantiates and uses a remotable object as if it were a local object. However, the actual code execution happens at the server-side. All requests to the remotable object are proxied by the .NET Remoting runtime over Channel objects that encapsulate the actual transport mode, including TCP streams, HTTP streams, and named pipes. As a result, by instantiating proper Channel objects, a .NET Remoting application can be made to support different communication protocols without recompiling the application. The runtime itself manages the act of serialization and marshalling of objects across the client and server appdomains.

Code - Create and Register a Channel (C#)



///////////////////////////////////////////////////////////////////// 
// Create and register a channel (TCP channel in this example) that 
// is used to transport messages across the remoting boundary. 
//// Properties of the channel 
IDictionary props = new Hashtable(); 
props["port"] = 6100;   // Port of the TCP channel 
props["typeFilterLevel"] = TypeFilterLevel.Full; 
// Formatters of the messages for delivery 
BinaryClientFormatterSinkProvider clientProvider = null; 
BinaryServerFormatterSinkProvider serverProvider = 
			  new BinaryServerFormatterSinkProvider(); 
serverProvider.TypeFilterLevel = TypeFilterLevel.Full; 

// Create a TCP channel 
TcpChannel tcpChannel = new TcpChannel(props, clientProvider, serverProvider); 

// Register the TCP channel 
ChannelServices.RegisterChannel(tcpChannel, true);

Code - Register Remotable Types (VB.NET)



'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
' Register the remotable types on the service end as
' server-activated types (aka well-known types) or client-activated
' types.
' Register RemotingShared.SingleCallObject as a SingleCall server-
' activated type.
RemotingConfiguration.RegisterWellKnownServiceType(GetType(RemotingShared.SingleCallObject), _
					  "SingleCallService", WellKnownObjectMode.SingleCall)
' Register RemotingShared.SingletonObject as a Singleton server-
' activated type.
RemotingConfiguration.RegisterWellKnownServiceType(GetType(RemotingShared.SingletonObject), _
					  "SingletonService", WellKnownObjectMode.Singleton)
' Register RemotingShared.ClientActivatedObject as a client-
' activated type.
RemotingConfiguration.ApplicationName = "RemotingService"
RemotingConfiguration.RegisterActivatedServiceType(_
		GetType(Global.RemotingShared.ClientActivatedObject))

Points of Interest

In the pilot phase of the AIO project, we focus on five techniques: COM, Library, IPC, Office, and Data Access. There has been 42 code examples in the project. The collection currently grows at a rate of seven examples per week.

This article was created on 3/12/2009.

About the Author

Microsoft All-In-One Code Framework delineates the framework and skeleton of Microsoft development techniques through typical sample codes in three popular programming languages (Visual C#, VB.NET, Visual C++). Each sample is elaborately selected, composed, and documented to demonstrate one frequently-asked, tested or used coding scenario based on our support experience in MSDN newsgroups and forums. If you are a software developer, you can fill the skeleton with blood, muscle and soul. If you are a software tester or a support engineer like us, you may extend the sample codes a little to fit your specific test scenario or refer your customer to this project if the customer's question coincides with what we collected.
http://cfx.codeplex.com/

License

This article was authored by All-In-One Code Framework and reproduced for the benefit of our viewers under the terms of the Ms-PL license.

Parallel programming in .NET - Internals

Mon, 30 Jan 2012 20:16:20 +0000

Download demo - 2.67 KB

License: Ms-PL

Introduction

.NET 4 brings a powerful Task library to support a piece of code to run in parallel processors. It just simply spawns threads into multiple processes using the newly written Task libraries (System.Threading.Tasks) in Mscorlib 4.0. Task libraries contain methods like For, ForEach, and Invoke to support parallelism in .NET languages, which I will discuss in detail later on.

Let's see what's got changed in .NET 4.0 to bring up parallel extensions.

CLR Thread Pool 4.0

The old thread pool of .NET 2.0 used to support only 1-4 processors, where the "single queue", "single lock" schema was sufficient. The improved thread pool in .NET 4.0 can hold up to 16-256 processors.

The new ThreadPool significantly reduces the synchronization overhead associated with pushing/pulling work items to/from the pool. While in previous versions, the ThreadPool queue was implemented as a linked list protected by a big lock, the new version of the queue is based on the new array-style, lock-free, GC-friendly ConcurrentQueue class.
The CLR 4.0 thread pool also supports a local queue per task, and implements a work stealing algorithm that load balances the work amongst the queues.
In the 4.0 version of the CLR thread pool, the 'thread injection and retirement algorithm' has changed. In cases where there are more running threads than CPUs, instead of creating new threads at the rate of 1 thread per 0.5 second, the new thread pool takes the liberty to 'hold back' threads (i.e., reduce the concurrency level) for a while.

MSCORLIB 4.0

System.Collections.Concurrent Namespace

The System.Collections.Concurrent namespace provides several thread-safe collection classes that should be used in place of the corresponding types in the System.Collections and System.Collections.Generic namespaces whenever multiple threads are accessing the collection concurrently.

System.Threading.Tasks Namespace

The System.Threading.Tasks namespace provides types that simplify the work of writing concurrent and asynchronous code. The main types are System.Threading.Tasks.Task, which represents an asynchronous operation that can be waited on and cancelled, and System.Threading.Tasks.Task(Of TResult), which is a task that can return a value. The Factory class provides static methods for creating and starting tasks, and the System.Threading.Tasks.TaskScheduler class provides the default thread scheduling infrastructure.

.NET 4 Cancellation Framework

A very interesting addition to .NET 4 is a set of new types that specifically assist with building cancellation-aware applications and libraries. The new types enable rich scenarios for convenient and safe cancellation, and help simplify situations that used to be be difficult and error-prone and non-composable.

Two new types form the basis of the framework: a CancellationToken is a struct that represents a 'potential request for cancellation'. This struct is passed into method calls as a parameter, and the method can poll on it or register a callback to be fired when cancellation is requested. A CancellationTokenSource is a class that provides the mechanism for initiating a cancellation request, and it has a Token property for obtaining an associated token. It would have been natural to combine these two classes into one, but this design allows the two key operations (initiating a cancellation request vs. observing and responding to cancellation) to be cleanly separated. In particular, methods that take only a CancellationToken can observe a cancellation request but cannot initiate one.

How it Works

Now you have got enough familiarization of the changes in .NET to bring up code parallelization. Let's start with a simple entity of parallelization called Task in our case. The new System.Threading.Tasks.Task class takes care of thread allocation and synchronization; yeah, it's internally using threads, but in a very efficient way.

The Task class implements the IThreadPoolWorkItem interface, which is responsible for executing work items from the thread pool queue. The full flow of task parallelization is shown in the diagram below:

The ThreadPoolTaskScheduler class pushes Tasks (IThreadPoolWorkItem) to a global queue using the ThreadPool API. Worker threads picks up the tasks from Global Queue (QueueSegment). Once the processing is done, it informs the task by calling the manual reset event of System.Threading. If a task is created within a task, then it will not be pushed to the Global Queue, but instead maintained in a local queue (work stealing queue). Any task item in the work stealing queue can be shared by any other worker thread. How does work stealing work? The worker thread looks first into the local queue; if there is no work item to pick, then it searches the global queue. Still, if there is no work for the thread, it will look for any pending work item in other queues. So during the task processing, none of the threads are sitting idle, which actually gives 100% utilization of all cores of machines.

I think we have a lot of benefits of Local Queues and Work Stealing Queues, which were missing in the legacy thread pool, like less contention in the Global Queue, thread workers are effectively used, and many more. One thing to notice is that the huge performance improvement is also caused by changing the linked list based queues to array style queues; all the local and global queues are array based, which means there is no Big Lock for concurrency.

Let's hit Visual Studio now..

I ran the below sample of code in my dual core machine, better to try in a quad core.



//In Static void Main
DoSomeBigStuff(1, 10000);
DoSomeBigStuff(2, 10000);

//In some class
public void DoSomeBigStuff(int inp,int limit)
{
	ProcessItem();

	if (inp > limit)
	{
		return;
	}
	DoSomeBigStuff(++inp, limit);
}

public void ProcessItem()
{
	Thread.SpinWait(100000);
}

Running this on my dual core system gets the result in 8431ms, but if you check out the CPU performance, only 50% of the CPU is getting used.

Let's make some changes to the above code, and put DoSomeBigStuff in a task:



Task t1 = new Task(() =>
{
	DoSomeBigStuff(1, 10000);
});
Task t2 = new Task(() =>
{
	DoSomeBigStuff(2, 10000);
});

The CPU picture totally changes and now starts using both the cores. The code finishes in 4589 ms, which is a drastic improvement. Now I don't have to think about scaling up my code; just run the same code on an 8 proc machine and it will take lesser than 1000ms. The Task class encapsulates the logic of handling the number of threads based on processors and work item allocation.

There is some overhead associated with threading, so the individual tasks may take a little longer - in this case, they went from about 82 milliseconds for the single-threaded example to a wide range, some as high as 300 milliseconds, in the parallel.

This overhead should be part of your decision about when and what to parallelize in your application. What's more important for your application: that it finishes faster, or uses less total CPU time? Another consideration is ordering of the work.

Let's look at the threads. Check the thread debug window; you can see two new threads spawned with the Main thread.

The Parallel Library has started two threads to do the work equal to the number of cores. One more thread got created, which handles the callbacks from the queue to the main thread.

Check out the call stack of a single thread; it does the same stuff as we discussed above in the diagram.

You can figure out what the Execute method is doing; it just pushes the item into the global queue. The interesting method that I want to discuss here is ThreadPoolWorkQueue.Dispatch(). Let's go step by step in this method.



ThreadPoolGlobals.workQueue.MarkThreadRequestSatisfied();

This decrements the outstanding thread request, which means it gets the thread out of the pool.



ThreadPoolWorkQueueThreadLocals tl = 
   ThreadPoolGlobals.workQueue.EnsureCurrentThreadHasQueue();

This creates a Local Queue if not already created for the current thread worker.



ThreadPoolGlobals.workQueue.Dequeue(tl, out callback, out missedSteal);

This dequeues the task from the work queue. The Dequeue method is intelligent enough to pick the task if not present in the global or local queue; then it tries to steal the task from other queues.



callback.ExecuteWorkItem();
ThreadPool.NotifyWorkItemComplete();
ThreadPoolGlobals.workQueue.EnsureThreadRequested();

Execute the work item and notify the thread pool that the work is completed. If successful, it returns the thread back to the pool.

All this looks simple to me, but efficient logic to work out with threads. The picture below will give quite a good idea about the thread handling part done by the Task libraries.

What's Extra

The Task Parallel library provides one more class to play with, called Parallel. The APIs present in the Parallel class are used for iterations like For, ForEach, and Invoke. All these extension methods use the same Task libraries discussed above.

We will see one more example before proceeding ahead.

				

				for (int i=0; i < 1000; i++){
					Calculate(i);
				}
				public void Calculate(int pos){
					double result = new Random().NextDouble();
					for (int i = ; i < 20000; i++){
						result += Math.Acos(new 
						Random().NextDouble());
					}
				}

				

				Parallel.For(, 1000, delegate(int i)
				{
					Calculate(i);
				}
				);

Completed in half of the time compared to the legacy For loop.
Parallel.For directly jumps into the ForWorker method with the following params in the Parallel class:



ForWorker<object>(fromInclusive, toExclusive, 
		  s_defaultParallelOptions, body, null, null, null, null);

Internally, the ForWorker method creates an instance of ParallelForReplicatingTask which inherits from Task, with the default set to InternalTaskOptions.SelfReplicating. ForWorker creates an empty root task, and iteration tasks are created as child tasks of the root task.



rootTask.RunSynchronously(parallelOptions.EffectiveTaskScheduler);

This method starts the self-replication process of child tasks, and starts queuing them in the local queue. The Parallel class decides the number of thread workers which is equal to the number of processors.

In all methods of the Parallel class, it's been taken care that if any cancel task request comes, the threads will not be aborted, but cancelled softly.

While self replicating, .NET has to make sure the following points:

Self-replicating should have an inter-replica communication mechanism for communicating the completion of the overall activity.
Only use when the cost of this communication and the management of partitions is considerably less than the potential benefit gained from parallelism.
Do not assume that the task is always replicated. It is only replicated if there are available resources. For the same reason, do not assume that there will be a specific number of replicas.
In some instances, the number of replicas could far exceed the number of cores in the machine.
You may choose to use optimistic concurrency when it is possible to correctly deal with multiple executions of the same step.

And I think they have done a good job in handling the number of thread workers, using concurrency queues and the effective cancellation framework.

Here is the demo source code:

Below are the results after running the source on a dual core and quad core:

A Bonus Item

Visual Stuido Team Launched Concurrency Analyzer: If you have VS 2010, you can see the option under Analyze->Launch Performance Wizard->Concurrency.

It generates a full analysis report with graphs about the thread and cores usage. If building a thread intensive app, then you should go through this analysis. Also see the Concurrency Analyzer Video.

Good job done .NET Parallel Extension team!!

License

This article was authored by Manabendra Roy (Manab) and reproduced for the benefit of our viewers under the terms of the Ms-PL license.

Kinect Reception

Mon, 30 Jan 2012 20:07:42 +0000

Download source - 1.01 MB

License: Ms-PL

Introduction

The Idea: TV Screen in the Reception, When nothing happens (no one is in the reception) we can display videos on the screen but when someone enters the frame, show him the Kinect Image, and if the user is doing something funny, capture his image and save it.

The question is how can I know if the person is doing something funny?

For that, I've created Image AuthenticManager that contains a set of rules defining what positions or combinations are funny.

For example: If right hand position is higher than head position, then add 2 points, if the left foot position is crossing the right foot, then add an additional 2 points, etc.
When the user reaches the goal, we decide then to take his picture.

Before jumping to coding, let's talk about the application flow:
The main window is controlled by two Timers and the AuthenticManager:

SeriousTimer set to 10 secs and it starts Ticking as the Kinect Skeleton Event is first fired (this event will only work when the Kinect identifies a full person skeleton).
Inside the SkeletonFrameReady, we also have integer called _fpsCount that increases itself by 1 each time the SkeletonFrameReady is called after starting the SeriousTimer, this will help us to make sure the user is standing in front of the Kinect and not just walk by him.

Now how can the _fbsCount tell me that? ll we need to do is multiply the SeriousTimer seconds interval by the Minimum Fps (for example 10) and the _fpsCount should be bigger if the user stands in front of the Kinect.

In this case, the Timer will stop the Video feed and will display the Kinect Image.

IdleTimer by default is set to 30 seconds and each time the SkeletonFrameReady method is fired, we restart the IdleTimer.

So if there are no events for SkeletonFrameReady, the IdleTimer will return the Video feed.

JointID - AuthenticManager works with RuleObject that contains JointID Source and JointID Target (More about Joints - Kinect - Getting Started - Become The Incredible Hulk).
AuthenticManager is the heart of Kinect Reception application, this class will check if the user position is funny by your own rules.

What is Joint?
[indent]
The data is provided from the Kinect application code as a set of points, called skeleton positions, that compose a skeleton structure.[/indent]



public enum JointID
  {
	HipCenter = ,
	Spine = 1,
	ShoulderCenter = 2,
	Head = 3,
	ShoulderLeft = 4,
	ElbowLeft = 5,
	WristLeft = 6,
	HandLeft = 7,
	ShoulderRight = 8,
	ElbowRight = 9,
	WristRight = 10,
	HandRight = 11,
	HipLeft = 12,
	KneeLeft = 13,
	AnkleLeft = 14,
	FootLeft = 15,
	HipRight = 16,
	KneeRight = 17,
	AnkleRight = 18,
	FootRight = 19,
	Count = 20,
  }

Vector - For Source and Target Joints, you also have to define the Vector to check X or Y against one another.
Operator - Do you expect the Source Vector to be Bigger or Smaller than the Target Vector?
Score - If the rule is true, what is the score for the rule.

Background

Since Microsoft has released the Kinect.NET SDK, I wrote many articles on that subject:

I think Kinect is very cool and I'm searching for more projects and good ideas for Kinect. A couple of days ago, I talked with my friend Guy Burstein and he came up with an idea for Kinect application, he said what if people will enter the Microsoft Israel reception and instead of video screen showing commercials, let's add something interesting with Kinect.

Using the Code

Using Kinect events, I can see when user enters the frame, using two timers I can check if the user is just passing by or is standing in front of the camera.

The below image describes the application flow, at the beginning the application will show random videos, when the Kinect Skeleton Event will raise then the Serious Timer will begin ticking, each tick based on the FPS rate will be aggregated to variable called NumTicks, when the Serious Timer completes we check if NumTicks is big enough based on the FPS, if so then we'll start the Idle Timer and switch to Kinect Image.

Idle Timer - Each time the Kinect Skeleton Event is raised, the Idle Timer will be restart, so if there is no one in front of the Kinect camera, the Idle Timer will switch back to Videos.

As you can see from the images below (or Full Video), when I moved my hands or legs, the Score Bar has changed based on the rules you defined:

You reached the Goal!!!

The entire application works with 4 managers:

Kinect Manager
Configuration Manager
Video Manager
Authentic Manager

Kinect Manager

I've shown how to get started with Kinect many times in my previous posts, but for this application, I've created a singleton class to handle everything related to the Kinect settings, from restarting the Kinect RunTime object to changing the camera angle.



public KinectManager()
{
	try
	{

	KinectNui = new Runtime();

	KinectNui.Initialize(RuntimeOptions.UseColor | RuntimeOptions.UseSkeletalTracking |
							RuntimeOptions.UseColor);

	KinectNui.VideoStream.Open(ImageStreamType.Video, 2, 
	ImageResolution.Resolution640x480, 
			ImageType.ColorYuv);

	KinectNui.SkeletonEngine.TransformSmooth = true;
	var parameters = new TransformSmoothParameters
							{
							Smoothing = 1.0f,
							Correction = .1f,
							Prediction = .1f,
							JitterRadius = .05f,
							MaxDeviationRadius = .05f
							};
	KinectNui.SkeletonEngine.SmoothParameters = parameters;

	_lastTime = DateTime.Now;
	Camera = KinectNui.NuiCamera;

	IsInitialize = true;
	StatusMessage = Properties.Resources.KinectReady;
	}
	catch (InvalidOperationException ex)
	{
	IsInitialize = false;
	StatusMessage = ex.Message;
	}
}

Another important method the KinectManager has is the CameraAngle control.



public void ChangeCameraAngle(ChangeDirection dir)
{
	if (!IsInitialize) return;

	try
	{
	if (dir == ChangeDirection.Up)
		Camera.ElevationAngle = Camera.ElevationAngle +
		Properties.Settings.Default.ElevationAngleInterval;
	else
		Camera.ElevationAngle = Camera.ElevationAngle -
		Properties.Settings.Default.ElevationAngleInterval;

	StatusMessage = Properties.Resources.KinectReady;
	}
	catch (InvalidOperationException ex)
	{
	StatusMessage = ex.Message;
	}
	catch (ArgumentOutOfRangeException outOfRangeException)
	{
	StatusMessage = outOfRangeException.Message;
	}
}

Video Manager

The Video Manager has two specific types of Videos to play and the main Videos folders to pick random video each time.

Specific? When the user enters the Kinect Range, you can choose to play a specific video just before the Kinect Image will appear, and when the user leaves Kinect Range, you can choose to play the Out Video.

Define the type of video you want to play. If you ask for out video and there isn't one, return null - Stop Video and start showing Kinect Image. If you ask for in video and there isn't one, then return random video.



public static Uri GetVideo(VideoType type)
{
  if (string.IsNullOrEmpty(Properties.Settings.Default.VideosLibraryFolder) ||
	  !Directory.Exists(Properties.Settings.Default.VideosLibraryFolder))
	  return null;
  else
  {
	  string value = null;
	  switch (type)
	  {
		  case VideoType.In:
			  value = Properties.Settings.Default.VideosLibraryInFile;
			  return string.IsNullOrEmpty(value) || !File.Exists(value) ?
				  CollectRandomMovie() : new Uri(value);
		  case VideoType.Out:
			  value = Properties.Settings.Default.VideosLibraryOutFile;
			  return string.IsNullOrEmpty(value) || !File.Exists(value) ?
				  null : new Uri(value);
		  default:
			  return CollectRandomMovie();
	  }
  }
} 
 private static Uri CollectRandomMovie()
{
	var movies = new ArrayList();

	foreach (var filter in Properties.Settings.Default.VideoFilter)
		movies.AddRange(Directory.GetFiles(Properties.Settings.Default.VideosLibraryFolder,
			filter));

	if (movies.Count == ) return null;

	var rnd = new Random();
	return new Uri(movies[rnd.Next(movies.Count)].ToString());
}

Configuration Manager
Kinect Reception allows you to set a range or rules to define what is considered Funny, the rule are based on Joint to Joint and each rule defines the Score if the rule applies.

The RuleObject contains the Source Joint and Target Joint, Vector to check for both, the operator (Bigger or Smaller) and the Score.

So what does the configuration manager do? It saves the rules. (Using MemoryStream to translate the Rule to string and then save it into the application resources.)



public static ObservableCollection Load()
{
	var deserializer = new XmlSerializer(typeof(ObservableCollection));
	try
	{
		var xs = new XmlSerializer(typeof(ObservableCollection));
		var memoryStream = 
	new MemoryStream(Encoding.UTF8.GetBytes(Properties.Settings.Default.Rules));
		var xmlTextWriter = new XmlTextWriter(memoryStream, Encoding.UTF8);
		return (ObservableCollection)xs.Deserialize(memoryStream);
	}
	catch (Exception)
	{
		return new ObservableCollection();
	}
} 
public static void Save(ObservableCollection items)
{
	try
	{
		var memoryStream = new MemoryStream();
		var xs = new XmlSerializer(typeof(ObservableCollection));

		var xmlTextWriter = new XmlTextWriter(memoryStream, Encoding.UTF8);
		xs.Serialize(xmlTextWriter, items);

		memoryStream = (MemoryStream)xmlTextWriter.BaseStream;
		var xmlizedString = Encoding.UTF8.GetString(memoryStream.ToArray());

		Properties.Settings.Default.Rules = xmlizedString;
	}
	catch (Exception ex)
	{
		throw new ArgumentException(ex.Message);
	}
}

Authentic Manager

The Authentic Manager is the core of Kinect Reception, he will take all rules defined by you and check them against the Skeleton Joints.

The method below will extract the UnTracked joints and will make sure the joints quality are enough for calculation (We don't want the user moving out of the picture to be considered as funny ).

If the Skeleton Joints reach the Goal Score you define then an event will raise telling the main window to save the current Image and display for the user.



public void ChecksForAuthentic(JointsCollection joints)
{
  if (_rules.Count == ) return;

  var fixJoints =
	  joints.Cast().Where(
		  joint => joint.Position.W >= .6f &&
			  joint.TrackingState == JointTrackingState.Tracked).ToList();

  var sb = new StringBuilder();
  for (var index = ; index < _rules.Count; index++)
  {
	var rule = _rules[index];
	var s = (from j in fixJoints.Where(joint => joint.ID == rule.Source) select j).
		DefaultIfEmpty(new Joint() { TrackingState = JointTrackingState.NotTracked }).
		Single();

	var t = (from j in fixJoints.Where(joint => joint.ID == rule.Target) select j).
		DefaultIfEmpty(new Joint() { TrackingState = JointTrackingState.NotTracked }).
		Single();

	if (s.TrackingState == JointTrackingState.NotTracked ||
		t.TrackingState == JointTrackingState.NotTracked) break;

	var sv = s.ToFloat(rule.SourceVector);
	var tv = t.ToFloat(rule.TargetVector);

	if (rule.Operator == Operators.Bigger && sv > tv)
	{
	  Score = Score + rule.Score;
	  sb.AppendLine(string.Format("Bigger -> Source: {0}, Target:{1} , Vector:{2}",
		  rule.Source, rule.Target, rule.SourceVector));
	}
	else if (rule.Operator == Operators.Smaller && sv < tv)
	{
	  Score = Score + rule.Score;
	  sb.AppendLine(string.Format("Smaller -> Source: {0}, Target:{1} , Vector:{2}",
		  rule.Source, rule.Target, rule.SourceVector));
	}
  }

  if (Score >= _goal)
	IsAuthentic(Score, sb.ToString());
}

About the Author

Shai Raiten is VS ALM MVP, currently working for Sela Group as a ALM senior consultant and trainer specializes in Microsoft technologies especially Team System and .NET technology. He is currently consulting in various enterprises in Israel, planning and analysis Load and performance problems using Team System, building Team System customizations and adjusts ALM processes for enterprises. Shai is known as one of the top Team System experts in Israel. He conducts lectures and workshops for developers\QA and enterprises who want to specialize in Team System.

My Blog: http://blogs.microso...il/blogs/shair/

License

This article was authored by Shai Raiten and reproduced for the benefit of our viewers under the terms of the Ms-PL license.

The Basics of GLSL 4.0 Shaders

Fri, 27 Jan 2012 04:46:14 +0000

Shaders give us the power to implement alternative rendering algorithms and a greater degree of flexibility in the implementation of those techniques. With shaders, we can run custom code directly on the GPU, providing us with the opportunity to leverage the high degree of parallelism available with modern GPUs.

This article by David Wolff, author of OpenGL 4.0 Shading Language Cookbook, provides examples of basic shading techniques such as diffuse shading, two-sided shading, and flat shading. Specifically, we will cover:

Implementing diffuse, per-vertex shading with a single point light source
Implementing per-vertex ambient, diffuse, and, specular (ADS) shading
Using functions in shaders
Implementing two sided shading
Implementing flat shading

Introduction
Shaders were first introduced into OpenGL in version 2.0, introducing programmability into the formerly fixed-function OpenGL pipeline. Shaders are implemented using the OpenGL Shading Language (GLSL). The GLSL is syntactically similar to C, which should make it easier for experienced OpenGL programmers to learn. Due to the nature of this text, I won't present a thorough introduction to GLSL here. Instead, if you're new to GLSL, reading through these recipes should help you to learn the language by example. If you are already comfortable with GLSL, but don't have experience with version 4.0, you'll see how to implement these techniques utilizing the newer API. However, before we jump into GLSL programming, let's take a quick look at how vertex and fragment shaders fit within the OpenGL pipeline.

Vertex and fragment shaders
In OpenGL version 4.0, there are five shader stages: vertex, geometry, tessellation control, tessellation evaluation, and fragment. In this article we'll focus only on the vertex and fragment stages.

Shaders replace parts of the OpenGL pipeline. More specifically, they make those parts of the pipeline programmable. The following block diagram shows a simplified view of the OpenGL pipeline with only the vertex and fragment shaders installed.

Vertex data is sent down the pipeline and arrives at the vertex shader via shader input variables. The vertex shader's input variables correspond to vertex attributes (see Sending data to a shader using per-vertex attributes and vertex buffer objects). In general, a shader receives its input via programmer-defined input variables, and the data for those variables comes either from the main OpenGL application or previous pipeline stages (other shaders). For example, a fragment shader's input variables might be fed from the output variables of the vertex shader. Data can also be provided to any shader stage using uniform variables (see Sending data to a shader using uniform variables). These are used for information that changes less often than vertex attributes (for example, matrices, light position, and other settings). The following figure shows a simplified view of the relationships between input and output variables when there are two shaders active (vertex and fragment).

The vertex shader is executed once for each vertex, possibly in parallel. The data corresponding to vertex position must be transformed into clip coordinates and assigned to the output variable gl_Position before the vertex shader finishes execution. The vertex shader can send other information down the pipeline using shader output variables. For example, the vertex shader might also compute the color associated with the vertex. That color would be passed to later stages via an appropriate output variable.

Between the vertex and fragment shader, the vertices are assembled into primitives, clipping takes place, and the viewport transformation is applied (among other operations). The rasterization process then takes place and the polygon is filled (if necessary). The fragment shader is executed once for each fragment (pixel) of the polygon being rendered (typically in parallel). Data provided from the vertex shader is (by default) interpolated in a perspective correct manner, and provided to the fragment shader via shader input variables. The fragment shader determines the appropriate color for the pixel and sends it to the frame buffer using output variables. The depth information is handled automatically.

Replicating the old fixed functionality
Programmable shaders give us tremendous power and flexibility. However, in some cases we might just want to re-implement the basic shading techniques that were used in the default fixed-function pipeline, or perhaps use them as a basis for other shading techniques. Studying the basic shading algorithm of the old fixed-function pipeline can also be a good way to get started when learning about shader programming.

In this article, we'll look at the basic techniques for implementing shading similar to that of the old fixed-function pipeline. We'll cover the standard ambient, diffuse, and specular (ADS) shading algorithm, the implementation of two-sided rendering, and flat shading. in the next article, we'll also see some examples of other GLSL features such as functions, subroutines, and the discard keyword.

Implementing diffuse, per-vertex shading with a single point light source
One of the simplest shading techniques is to assume that the surface exhibits purely diffuse reflection. That is to say that the surface is one that appears to scatter light in all directions equally, regardless of direction. Incoming light strikes the surface and penetrates slightly before being re-radiated in all directions. Of course, the incoming light interacts with the surface before it is scattered, causing some wavelengths to be fully or partially absorbed and others to be scattered. A typical example of a diffuse surface is a surface that has been painted with a matte paint. The surface has a dull look with no shine at all.

The following image shows a torus rendered with diffuse shading.

The mathematical model for diffuse reflection involves two vectors: the direction from the surface point to the light source (s), and the normal vector at the surface point (n). The vectors are represented in the following diagram.

The amount of incoming light (or radiance) that reaches the surface is partially dependent on the orientation of the surface with respect to the light source. The physics of the situation tells us that the amount of radiation that reaches a point on a surface is maximal when the light arrives along the direction of the normal vector, and zero when the light is perpendicular to the normal. In between, it is proportional to the cosine of the angle between the direction towards the light source and the normal vector. So, since the dot product is proportional to the cosine of the angle between two vectors, we can express the amount of radiation striking the surface as the product of the light intensity and the dot product of s and n.

Where L_d is the intensity of the light source, and the vectors s and n are assumed to be normalized. You may recall that the dot product of two unit vectors is equal to the cosine of the angle between them.

As stated previously, some of the incoming light is absorbed before it is re-emitted. We can model this interaction by using a reflection coefficient (K_d), which represents the fraction of the incoming light that is scattered. This is sometimes referred to as the diffuse reflectivity, or the diffuse reflection coefficient. The diffuse reflectivity becomes a scaling factor for the incoming radiation, so the intensity of the outgoing light can be expressed as follows:

Because this model depends only on the direction towards the light source and the normal to the surface, not on the direction towards the viewer, we have a model that represents uniform (omnidirectional) scattering.

In this recipe, we'll evaluate this equation at each vertex in the vertex shader and interpolate the resulting color across the face.

In this and the following recipes, light intensities and material reflectivity coefficients are represented by 3-component (RGB) vectors. Therefore, the equations should be treated as component-wise operations, applied to each of the three components separately. Luckily, the GLSL will make this nearly transparent because the needed operators will operate component-wise on vector variables.

Getting ready
Start with an OpenGL application that provides the vertex position in attribute location 0, and the vertex normal in attribute location 1 (see Sending data to a shader using per-vertex attributes and vertex buffer objects). The OpenGL application also should provide the standard transformation matrices (projection, modelview, and normal) via uniform variables.

The light position (in eye coordinates), Kd, and Ld should also be provided by the OpenGL application via uniform variables. Note that Kd and Ld are type vec3. We can use a vec3 to store an RGB color as well as a vector or point.

How to do it...
To create a shader pair that implements diffuse shading, use the following code:

Use the following code for the vertex shader.

	
#version 400
	
	layout (location = 0) in vec3 VertexPosition;
	layout (location = 1) in vec3 VertexNormal;
	
	out vec3 LightIntensity;
	
	uniform vec4 LightPosition; // Light position in eye coords.
	uniform vec3 Kd; // Diffuse reflectivity
	uniform vec3 Ld; // Light source intensity
	
	uniform mat4 ModelViewMatrix;
	uniform mat3 NormalMatrix;
	uniform mat4 ProjectionMatrix;
	uniform mat4 MVP; // Projection * ModelView
	
	void main()
	{
	  // Convert normal and position to eye coords
	  vec3 tnorm = normalize( NormalMatrix * VertexNormal);
	  vec4 eyeCoords = ModelViewMatrix *
					   vec4(VertexPosition,1.0));
	  vec3 s = normalize(vec3(LightPosition - eyeCoords));
	
	  // The diffuse shading equation
	  LightIntensity = Ld * Kd * max( dot( s, tnorm ), 0.0 );
	
	  // Convert position to clip coordinates and pass along
	  gl_Position = MVP * vec4(VertexPosition,1.0);
	}

Use the following code for the fragment shader.

	
#version 400
	
	in vec3 LightIntensity;
	
	layout( location = 0 ) out vec4 FragColor;
	
	void main() {
		FragColor = vec4(LightIntensity, 1.0);
	}

Compile and link both shaders within the OpenGL application, and install the shader program prior to rendering. See Tips and Tricks for Getting Started with OpenGL and GLSL 4.0 for details about compiling, linking, and installing shaders.

How it works...
The vertex shader does all of the work in this example. The diffuse reflection is computed in eye coordinates by first transforming the normal vector using the normal matrix, normalizing, and storing the result in tnorm. Note that the normalization here may not be necessary if your normal vectors are already normalized and the normal matrix does not do any scaling.

The normal matrix is typically the inverse transpose of the upper-left 3x3 portion of the model-view matrix. We use the inverse transpose because normal vectors transform differently than the vertex position. For a more thorough discussion of the normal matrix, and the reasons why, see any introductory computer graphics textbook. (A good choice would be Computer Graphics with OpenGL by Hearn and Baker.) If your model-view matrix does not include any non-uniform scalings, then one can use the upper-left 3x3 of the model-view matrix in place of the normal matrix to transform your normal vectors. However, if your model-view matrix does include (uniform) scalings, you'll still need to (re)normalize your normal vectors after transforming them.

The next step converts the vertex position to eye (camera) coordinates by transforming it via the model-view matrix. Then we compute the direction towards the light source by subtracting the vertex position from the light position and storing the result in s.

Next, we compute the scattered light intensity using the equation described above and store the result in the output variable LightIntensity. Note the use of the max function here. If the dot product is less than zero, then the angle between the normal vector and the light direction is greater than 90 degrees. This means that the incoming light is coming from inside the surface. Since such a situation is not physically possible (for a closed mesh), we use a value of 0.0. However, you may decide that you want to properly light both sides of your surface, in which case the normal vector needs to be reversed for those situations where the light is striking the back side of the surface (see Implementing two-sided shading).

Finally, we convert the vertex position to clip coordinates by multiplying with the model-view projection matrix, (which is: projection * view * model) and store the result in the built-in output variable gl_Position.


gl_Position = MVP * vec4(VertexPosition,1.0);

The subsequent stage of the OpenGL pipeline expects that the vertex position will be provided in clip coordinates in the output variable gl_Position. This variable does not directly correspond to any input variable in the fragment shader, but is used by the OpenGL pipeline in the primitive assembly, clipping, and rasterization stages that follow the vertex shader. It is important that we always provide a valid value for this variable.

Since LightIntensity is an output variable from the vertex shader, its value is interpolated across the face and passed into the fragment shader. The fragment shader then simply assigns the value to the output fragment.

There's more...
Diffuse shading is a technique that models only a very limited range of surfaces. It is best used for surfaces that have a "matte" appearance. Additionally, with the technique used above, the dark areas may look a bit too dark. In fact, those areas that are not directly illuminated are completely black. In real scenes, there is typically some light that has been reflected about the room that brightens these surfaces. In the following recipes, we'll look at ways to model more surface types, as well as provide some light for those dark parts of the surface.

Implementing per-vertex ambient, diffuse, and specular (ADS) shading
The OpenGL fixed function pipeline implemented a default shading technique which is very similar to the one presented here. It models the light-surface interaction as a combination of three components: ambient, diffuse, and specular. The ambient component is intended to model light that has been reflected so many times that it appears to be emanating uniformly from all directions. The diffuse component was discussed in the previous recipe, and represents omnidirectional reflection. The specular component models the shininess of the surface and represents reflection around a preferred direction. Combining these three components together can model a nice (but limited) variety of surface types. This shading model is also sometimes called the Phong reflection model (or Phong shading model), after Bui Tuong Phong.

An example of a torus rendered with the ADS shading model is shown in the following screenshot:

The ADS model is implemented as the sum of the three components: ambient, diffuse, and specular. The ambient component represents light that illuminates all surfaces equally and reflects equally in all directions. It is often used to help brighten some of the darker areas within a scene. Since it does not depend on the incoming or outgoing directions of the light, it can be modeled simply by multiplying the light source intensity (L_a) by the surface reflectivity (K_a).

The diffuse component models a rough surface that scatters light in all directions (see Implementing diffuse per-vertex shading with a single point light source above). The intensity of the outgoing light depends on the angle between the surface normal and the vector towards the light source.

The specular component is used for modeling the shininess of a surface. When a surface has a glossy shine to it, the light is reflected off of the surface in a mirror-like fashion. The reflected light is strongest in the direction of perfect (mirror-like) reflection. The physics of the situation tells us that for perfect reflection, the angle of incidence is the same as the angle of reflection and that the vectors are coplanar with the surface normal, as shown in the following diagram:

In the preceding diagram, r represents the vector of pure-reflection corresponding to the incoming light vector (-s), and n is the surface normal. We can compute r by using the following equation:

To model specular reflection, we need to compute the following (normalized) vectors: the direction towards the light source (s), the vector of perfect reflection (r), the vector towards the viewer (v), and the surface normal (n). These vectors are represented in the following image:

We would like the reflection to be maximal when the viewer is aligned with the vector r, and to fall off quickly as the viewer moves further away from alignment with r. This can be modeled using the cosine of the angle between v and r raised to some power (f).

(Recall that the dot product is proportional to the cosine of the angle between the vectors involved.) The larger the power, the faster the value drops towards zero as the angle between v and r increases. Again, similar to the other components, we also introduce a specular light intensity term (L_s) and reflectivity term (K_s).

The specular component creates specular highlights (bright spots) that are typical of glossy surfaces. The larger the power of f in the equation, the smaller the specular highlight and the shinier the surface appears. The value for f is typically chosen to be somewhere between 1 and 200.

Putting all of this together, we have the following shading equation:

In the following code, we'll evaluate this equation in the vertex shader, and interpolate the color across the polygon.

Getting ready
In the OpenGL application, provide the vertex position in location 0 and the vertex normal in location 1. The light position and the other configurable terms for our lighting equation are uniform variables in the vertex shader and their values must be set from the OpenGL application.

How to do it...
To create a shader pair that implements ADS shading, use the following code:

Use the following code for the vertex shader:

	
#version 400
	
	layout (location = 0) in vec3 VertexPosition;
	layout (location = 1) in vec3 VertexNormal;
	
	out vec3 LightIntensity;
	
	struct LightInfo {
	  vec4 Position; // Light position in eye coords.
	  vec3 La; // Ambient light intensity
	  vec3 Ld; // Diffuse light intensity
	  vec3 Ls; // Specular light intensity
	};
	uniform LightInfo Light;
	
	struct MaterialInfo {
	  vec3 Ka; // Ambient reflectivity
	  vec3 Kd; // Diffuse reflectivity
	  vec3 Ks; // Specular reflectivity
	  float Shininess; // Specular shininess factor
	};
	uniform MaterialInfo Material;
	
	uniform mat4 ModelViewMatrix;
	uniform mat3 NormalMatrix;
	uniform mat4 ProjectionMatrix;
	uniform mat4 MVP;
	
	void main()
	{
	  vec3 tnorm = normalize( NormalMatrix * VertexNormal);
	  vec4 eyeCoords = ModelViewMatrix *
					   vec4(VertexPosition,1.0);
	  vec3 s = normalize(vec3(Light.Position - eyeCoords));
	  vec3 v = normalize(-eyeCoords.xyz);
	  vec3 r = reflect( -s, tnorm );
	  vec3 ambient = Light.La * Material.Ka;
	  float sDotN = max( dot(s,tnorm), 0.0 );
	  vec3 diffuse = Light.Ld * Material.Kd * sDotN;
	  vec3 spec = vec3(0.0);
	  if( sDotN > 0.0 )
		spec = Light.Ls * Material.Ks *
			   pow( max( dot(r,v), 0.0 ), Material.Shininess );
	
	  LightIntensity = ambient + diffuse + spec;
	  gl_Position = MVP * vec4(VertexPosition,1.0);
	}

Use the following code for the fragment shader:

	
#version 400
	
	in vec3 LightIntensity;
	
	layout( location = 0 ) out vec4 FragColor;
	
	void main() {
		FragColor = vec4(LightIntensity, 1.0);
	}

Compile and link both shaders within the OpenGL application, and install the shader program prior to rendering.

How it works...
The vertex shader computes the shading equation in eye coordinates. It begins by transforming the vertex normal into eye coordinates and normalizing, then storing the result in tnorm. The vertex position is then transformed into eye coordinates and stored in eyeCoords.

Next, we compute the normalized direction towards the light source (s). This is done by subtracting the vertex position in eye coordinates from the light position and normalizing the result.

The direction towards the viewer (v) is the negation of the position (normalized) because in eye coordinates the viewer is at the origin.

We compute the direction of pure reflection by calling the GLSL built-in function reflect, which reflects the first argument about the second. We don't need to normalize the result because the two vectors involved are already normalized.

The ambient component is computed and stored in the variable ambient. The dot product of s and n is computed next. As in the preceding recipe, we use the built-in function max to limit the range of values to between one and zero. The result is stored in the variable named sDotN, and is used to compute the diffuse component. The resulting value for the diffuse component is stored in the variable diffuse. Before computing the specular component, we check the value of sDotN. If sDotN is zero, then there is no light reaching the surface, so there is no point in computing the specular component, as its value must be zero. Otherwise, if sDotN is greater than zero, we compute the specular component using the equation presented earlier. Again, we use the built-in function max to limit the range of values of the dot product to between one and zero, and the function pow raises the dot product to the power of the Shininess exponent (corresponding to f in our lighting equation).

If we did not check sDotN before computing the specular component, it is possible that some specular highlights could appear on faces that are facing away from the light source. This is clearly a non-realistic and undesirable result. Some people solve this problem by multiplying the specular component by the diffuse component, which would decrease the specular component substantially and alter its color. The solution presented here avoids this, at the cost of a branch statement (the if statement).

The sum of the three components is then stored in the output variable LightIntensity. This value will be associated with the vertex and passed down the pipeline. Before reaching the fragment shader, its value will be interpolated in a perspective correct manner across the face of the polygon.

Finally, the vertex shader transforms the position into clip coordinates, and assigns the result to the built-in output variable gl_Position (see Implementing diffuse, per-vertex shading with a single point light source).

The fragment shader simply applies the interpolated value of LightIntensity to the output fragment by storing it in the shader output variable FragColor.

There's more...
This version of the ADS (Ambient, Diffuse, and Specular) reflection model is by no means optimal. There are several improvements that could be made. For example, the computation of the vector of pure reflection can be avoided via the use of the so-called "halfway vector".

Using a non-local viewer

We can avoid the extra normalization needed to compute the vector towards the viewer (v), by using a so-called non-local viewer. Instead of computing the direction towards the origin, we simply use the constant vector (0, 0, 1) for all vertices. This is similar to assuming that the viewer is located infinitely far away in the z direction. Of course, it is not accurate, but in practice the visual results are very similar, often visually indistinguishable, saving us normalization.

In the old fixed-function pipeline, the non-local viewer was the default, and could be adjusted (turned on or off) using the function glLightModel.

Per-vertex vs. Per-fragment

Since the shading equation is computed within the vertex shader, we refer to this as per-vertex lighting. One of the disadvantages of per-vertex lighting is that specular highlights can be warped or lost, due to the fact that the shading equation is not evaluated at each point across the face. For example, a specular highlight that should appear in the middle of a polygon might not appear at all when per-vertex lighting is used, because of the fact that the shading equation is only computed at the vertices where the specular component is near zero.

Directional lights

We can also avoid the need to compute a light direction (s), for each vertex if we assume a directional light. A directional light source is one that can be thought of as located infinitely far away in a given direction. Instead of computing the direction towards the source for each vertex, a constant vector is used, which represents the direction towards the remote light source.

Light attenuation with distance

You might think that this shading model is missing one important component. It doesn't take into account the effect of the distance to the light source. In fact, it is known that the intensity of radiation from a source falls off in proportion to the inverse square of the distance from the source. So why not include this in our model?

It would be fairly simple to do so, however, the visual results are often less than appealing. It tends to exaggerate the distance effects and create unrealistic looking images. Remember, our equation is just an approximation of the physics involved and is not a truly realistic model, so it is not surprising that adding a term based on a strict physical law produces unrealistic results.

In the OpenGL fixed-function pipeline, it was possible to turn on distance attenuation using the glLight function. If desired, it would be straightforward to add a few uniform variables to our shader to produce the same effect.

Using functions in shaders
The GLSL supports functions that are syntactically similar to C functions. However, the calling conventions are somewhat different. In this example, we'll revisit the ADS shader using functions to help provide abstractions for the major steps.

Getting ready
As with previous recipes, provide the vertex position at attribute location 0 and the vertex normal at attribute location 1. Uniform variables for all of the ADS coefficients should be set from the OpenGL side, as well as the light position and the standard matrices.

How to do it...
To implement ADS shading using functions, use the following code:

Use the following vertex shader:

	
#version 400
	
	layout (location = 0) in vec3 VertexPosition;
	layout (location = 1) in vec3 VertexNormal;
	
	out vec3 LightIntensity;
	
	struct LightInfo {
	  vec4 Position; // Light position in eye coords.
	  vec3 La; // Ambient light intensity
	  vec3 Ld; // Diffuse light intensity
	  vec3 Ls; // Specular light intensity
	};
	uniform LightInfo Light;
	
	struct MaterialInfo {
	  vec3 Ka; // Ambient reflectivity
	  vec3 Kd; // Diffuse reflectivity
	  vec3 Ks; // Specular reflectivity
	  float Shininess; // Specular shininess factor
	};
	uniform MaterialInfo Material;
	
	uniform mat4 ModelViewMatrix;
	uniform mat3 NormalMatrix;
	uniform mat4 ProjectionMatrix;
	uniform mat4 MVP;
	
	void getEyeSpace( out vec3 norm, out vec4 position )
	{
	  norm = normalize( NormalMatrix * VertexNormal);
	  position = ModelViewMatrix * vec4(VertexPosition,1.0);
	}
	
	vec3 phongModel( vec4 position, vec3 norm )
	{
	  vec3 s = normalize(vec3(Light.Position - position));
	  vec3 v = normalize(-position.xyz);
	  vec3 r = reflect( -s, norm );
	  vec3 ambient = Light.La * Material.Ka;
	  float sDotN = max( dot(s,norm), 0.0 );
	  vec3 diffuse = Light.Ld * Material.Kd * sDotN;
	  vec3 spec = vec3(0.0);
	  if( sDotN > 0.0 )
		  spec = Light.Ls * Material.Ks *
				 pow( max( dot(r,v), 0.0 ), Material.Shininess );
	  return ambient + diffuse + spec;
	}
	
	void main()
	{
	  vec3 eyeNorm;
	  vec4 eyePosition;
	  // Get the position and normal in eye space
	  getEyeSpace(eyeNorm, eyePosition);
	  // Evaluate the lighting equation.
	  LightIntensity = phongModel( eyePosition, eyeNorm );
	  gl_Position = MVP * vec4(VertexPosition,1.0);
	}

Use the following fragment shader:

	
#version 400
	in vec3 LightIntensity;
	layout( location = 0 ) out vec4 FragColor;
	void main() {
		FragColor = vec4(LightIntensity, 1.0);
	}

Compile and link both shaders within the OpenGL application, and install the shader program prior to rendering.

How it works...
In GLSL functions, the evaluation strategy is "call by value-return" (also called "call by copyrestore" or "call by value-result"). Parameter variables can be qualified with in, out, or inout. Arguments corresponding to input parameters (those qualified with in or inout) are copied into the parameter variable at call time, and output parameters (those qualified with out or inout) are copied back to the corresponding argument before the function returns. If a parameter variable does not have any of the three qualifiers, the default qualifier is in.

We've created two functions in the vertex shader. The first, named getEyeSpace, transforms the vertex position and vertex normal into eye space, and returns them via output parameters. In the main function, we create two uninitialized variables (eyeNorm and eyePosition) to store the results, and then call the function with the variables as the function's arguments. The function stores the results into the parameter variables (norm and position) which are copied into the arguments before the function returns.

The second function, phongModel, uses only input parameters. The function receives the eye-space position and normal, and computes the result of the ADS shading equation. The result is returned by the function and stored in the shader output variable LightIntensity.

There's more...
Since it makes no sense to read from an output parameter variable, output parameters should only be written to within the function. Their value is undefined.

Within a function, writing to an input only parameter (qualified with in) is allowed. The function's copy of the argument is modified, and changes are not reflected in the argument.

The const qualifier

The additional qualifier const can be used with input-only parameters (not with out or inout). This qualifier makes the input parameter read-only, so it cannot be written to within the function.

Function overloading

Functions can be overloaded by creating multiple functions with the same name, but with different number and/or type of parameters. As with many languages, two overloaded functions may not differ in return type only.

Passing arrays or structures to a function

It should be noted that when passing arrays or structures to functions, they are passed by value. If a large array or structure is passed, it can incur a large copy operation which may not be desired. It would be a better choice to declare these variables in the global scope.

Implementing two-sided shading
When rendering a mesh that is completely closed, the back faces of polygons are hidden. However, if a mesh contains holes, it might be the case that the back faces would become visible. In this case, the polygons may be shaded incorrectly due to the fact that the normal vector is pointing in the wrong direction. To properly shade those back faces, one needs to invert the normal vector and compute the lighting equations based on the inverted normal.

The following image shows a teapot with the lid removed. On the left, the ADS lighting model is used. On the right, the ADS model is augmented with the two-sided rendering technique discussed in this recipe.

In this recipe, we'll look at an example that uses the ADS model discussed in the previous recipes, augmented with the ability to correctly shade back faces.

Getting ready
The vertex position should be provided in attribute location 0 and the vertex normal in attribute location 1. As in previous examples, the lighting parameters must be provided to the shader via uniform variables.

How to do it...
To implement a shader pair that uses the ADS shading model with two-sided lighting, use the following code:

Use the following code for the vertex shader:

	
#version 400
	
	layout (location = 0) in vec3 VertexPosition;
	layout (location = 1) in vec3 VertexNormal;
	
	out vec3 FrontColor;
	out vec3 BackColor;
	
	struct LightInfo {
	  vec4 Position; // Light position in eye coords.
	  vec3 La; // Ambient light intensity
	  vec3 Ld; // Diffuse light intensity
	  vec3 Ls; // Specular light intensity
	};
	uniform LightInfo Light;
	
	struct MaterialInfo {
	  vec3 Ka; // Ambient reflectivity
	  vec3 Kd; // Diffuse reflectivity
	  vec3 Ks; // Specular reflectivity
	  float Shininess; // Specular shininess factor
	};
	uniform MaterialInfo Material;
	
	uniform mat4 ModelViewMatrix;
	uniform mat3 NormalMatrix;
	uniform mat4 ProjectionMatrix;
	uniform mat4 MVP;
	
	vec3 phongModel( vec4 position, vec3 normal ) {
	  // The ADS shading calculations go here (see: "Using
	  // functions in shaders," and "Implementing
	  // per-vertex ambient, diffuse and specular (ADS) shading")
	  ...
	}
	
	void main()
	{
	  vec3 tnorm = normalize( NormalMatrix * VertexNormal);
	  vec4 eyeCoords = ModelViewMatrix *
					   vec4(VertexPosition,1.0);
	
	  FrontColor = phongModel( eyeCoords, tnorm );
	
	  BackColor = phongModel( eyeCoords, -tnorm );
	
	  gl_Position = MVP * vec4(VertexPosition,1.0);
	}

Use the following for the fragment shader:

	
#version 400
	
	in vec3 FrontColor;
	in vec3 BackColor;
	
	layout( location = 0 ) out vec4 FragColor;
	
	void main() {
	
	  if( gl_FrontFacing ) {
		  FragColor = vec4(FrontColor, 1.0);
	  } else {
		  FragColor = vec4(BackColor, 1.0);
	  }
	}

Compile and link both shaders within the OpenGL application, and install the shader program prior to rendering.

How it works...
In the vertex shader, we compute the lighting equation using both the vertex normal and the inverted version, and pass each resultant color to the fragment shader. The fragment shader chooses and applies the appropriate color depending on the orientation of the face.

The vertex shader is a slightly modified version of the vertex shader presented in the recipe Implementing per-vertex ambient, diffuse, and specular (ADS) shading. The evaluation of the shading model is placed within a function named phongModel. The function is called twice, first using the normal vector (transformed into eye coordinates), and second using the inverted normal vector. The combined results are stored in FrontColor and BackColor, respectively.

Note that there are a few aspects of the shading model that are independent of the orientation of the normal vector (such as the ambient component). One could optimize this code by rewriting it so that the redundant calculations are only done once. However, in this recipe we compute the entire shading model twice in the interest of making things clear and readable.

In the fragment shader, we determine which color to apply based on the value of the built-in variable gl_FrontFacing. This is a Boolean value that indicates whether the fragment is part of a front or back facing polygon. Note that this determination is based on the winding of the polygon, and not the normal vector. (A polygon is said to have counter-clockwise winding if the vertices are specified in counter-clockwise order as viewed from the front side of the polygon.) By default when rendering, if the order of the vertices appear on the screen in a counter-clockwise order, it indicates a front facing polygon, however, we can change this by calling glFrontFace from the OpenGL program.

There's more...
In the vertex shader we determine the front side of the polygon by the direction of the normal vector, and in the fragment shader, the determination is based on the polygon's winding. For this to work properly, the normal vector must be defined appropriately for the face determined by the setting of glFrontFace.

Using two-sided rendering for debugging

It can sometimes be useful to visually determine which faces are front facing and which are back facing. For example, when working with arbitrary meshes, polygons may not be specified using the appropriate winding. As another example, when developing a mesh procedurally, it can sometimes be helpful to determine which faces are oriented in the proper direction in order to help with debugging. We can easily tweak our fragment shader to help us solve these kinds of problems by mixing a solid color with all back (or front) faces. For example, we could change the else clause within our fragment shader to the following:


FragColor = mix( vec4(BackColor,1.0),
				vec4(1.0,0.0,0.0,1.0), 0.7 );

This would mix a solid red color with all back faces, helping them to stand out, as shown in the following image. In the image, back faces are mixed with 70% red as shown in the preceding code.

Implementing flat shading
Per-vertex shading involves computation of the shading model at each vertex and associating the result (a color) with that vertex. The colors are then interpolated across the face of the polygon to produce a smooth shading effect. This is also referred to as Gouraud shading. In earlier versions of OpenGL, this per-vertex shading with color interpolation was the default shading technique.

It is sometimes desirable to use a single color for each polygon so that there is no variation of color across the face of the polygon, causing each polygon to have a flat appearance. This can be useful in situations where the shape of the object warrants such a technique, perhaps because the faces really are intended to look flat, or to help visualize the locations of the polygons in a complex mesh. Using a single color for each polygon is commonly called flat shading.

The images below show a mesh rendered with the ADS shading model. On the left, Gouraud shading is used. On the right, flat shading is used.

In earlier versions of OpenGL, flat shading was enabled by calling the function glShadeModel with the argument GL_FLAT. In which case, the computed color of the last vertex of each polygon was used across the entire face.

In OpenGL 4.0, flat shading is facilitated by the interpolation qualifiers available for shader input/output variables.

How to do it...
To modify the ADS shading model to implement flat shading, use the following steps:

Use the same vertex shader as in the ADS example provided earlier. Change the output variable LightIntensity as follows:

	
#version 400
	
	layout (location = 0) in vec3 VertexPosition;
	layout (location = 1) in vec3 VertexNormal;
	
	flat out vec3 LightIntensity;
	
	// the rest is identical to the ADS shader...

Use the following code for the fragment shader:

	
#version 400
	
	flat in vec3 LightIntensity;
	
	layout( location = 0 ) out vec4 FragColor;
	
	void main() {
		FragColor = vec4(LightIntensity, 1.0);
	}

Compile and link both shaders within the OpenGL application, and install the shader program prior to rendering.

How it works...
Flat shading is enabled by qualifying the vertex output variable (and its corresponding fragment input variable) with the flat qualifier. This qualifier indicates that no interpolation of the value is to be done before it reaches the fragment shader. The value presented to the fragment shader will be the one corresponding to the result of the invocation of the vertex shader for either the first or last vertex of the polygon. This vertex is called the provoking vertex, and can be configured using the OpenGL function glProvokingVertex. For example, the call:


glProvokingVertex(GL_FIRST_VERTEX_CONVENTION);

This indicates that the first vertex should be used as the value for the flat shaded variable. The argument GL_LAST_VERTEX_CONVENTION indicates that the last vertex should be used.

Summary
This article provided examples of basic shading techniques such as diffuse shading, two-sided shading, and flat shading.

OpenGL 4.0: Using Uniform Blocks and Uniform Bu...

Fri, 27 Jan 2012 04:42:12 +0000

If your OpenGL/GLSL program involves multiple shader programs that use the same uniform variables, one has to manage the variables separately for each program. Uniform blocks were designed to ease the sharing of uniform data between programs. In this article by David Wolff, author of OpenGL 4.0 Shading Language Cookbook, we will create a buffer object for storing the values of all the uniform variables, and bind the buffer to the uniform block. Then when changing programs, the same buffer object need only be re-bound to the corresponding block in the new program.

Uniform locations are generated when a program is linked, so the locations of the uniforms may change from one program to the next. The data for those uniforms may have to be re-generated and applied to the new locations.

A uniform block is simply a group of uniform variables defined within a syntactical structure known as a uniform block. For example, in this recipe, we'll use the following uniform block:


uniform BlobSettings {
  vec4 InnerColor;
  vec4 OuterColor;
  float RadiusInner;
  float RadiusOuter;
};

This defines a block with the name BlobSettings that contains four uniform variables. With this type of block definition, the variables within the block are still part of the global scope and do not need to be qualified with the block name.

The buffer object used to store the data for the uniforms is often referred to as a uniform buffer object. We'll see that a uniform buffer object is simply just a buffer object that is bound to a certain location.

For this recipe, we'll use a simple example to demonstrate the use of uniform buffer objects and uniform blocks. We'll draw a quad (two triangles) with texture coordinates, and use our fragment shader to fill the quad with a fuzzy circle. The circle is a solid color in the center, but at its edge, it gradually fades to the background color, as shown in the following image.

Getting ready
Start with an OpenGL program that draws two triangles to form a quad. Provide the position at vertex attribute location 0, and the texture coordinate (0 to 1 in each direction) at vertex attribute location 1 (see: Sending data to a shader using per-vertex attributes and vertex buffer objects).

We'll use the following vertex shader:


#version 400

layout (location = 0) in vec3 VertexPosition;
layout (location = 1) in vec3 VertexTexCoord;

out vec3 TexCoord;

void main()
{
	TexCoord = VertexTexCoord;
	gl_Position = vec4(VertexPosition,1.0);
}

The fragment shader contains the uniform block, and is responsible for drawing our fuzzy circle:


#version 400
in vec3 TexCoord;
layout (location = 0) out vec4 FragColor;

uniform BlobSettings {
  vec4 InnerColor;
  vec4 OuterColor;
  float RadiusInner;
  float RadiusOuter;
};

void main() {
	float dx = TexCoord.x - 0.5;
	float dy = TexCoord.y - 0.5;
	float dist = sqrt(dx * dx + dy * dy);
	FragColor =
	   mix( InnerColor, OuterColor,
			 smoothstep( RadiusInner, RadiusOuter, dist )
	   );
}

The uniform block is named BlobSettings. The variables within this block define the parameters of our fuzzy circle. The variable OuterColor defines the color outside of the circle. InnerColor is the color inside of the circle. RadiusInner is the radius defining the part of the circle that is a solid color (inside the fuzzy edge), and the distance from the center of the circle to the inner edge of the fuzzy boundary. RadiusOuter is the outer edge of the fuzzy boundary of the circle (when the color is equal to OuterColor).

The code within the main function computes the distance of the texture coordinate to the center of the quad located at (0.5, 0.5). It then uses that distance to compute the color by using the smoothstep function. This function provides a value that smoothly varies between 0.0 and 1.0 when the value of the third argument is between the values of the first two arguments. Otherwise it returns 0.0 or 1.0 depending on whether it is less than the first or greater than the second, respectively. The mix function is then used to linearly interpolate between InnerColor and OuterColor based on the value returned by the smoothstep function.

How to do it...
In the OpenGL program, after linking the shader program, use the following steps to send data to the uniform block in the fragment shader:

Get the index of the uniform block using glGetUniformBlockIndex.

	
GLuint blockIndex = glGetUniformBlockIndex(programHandle,
											  "BlobSettings");

Allocate space for the buffer to contain the data for the uniform block. We get the size of the block using glGetActiveUniformBlockiv.

	
GLint blockSize;
	
	glGetActiveUniformBlockiv(programHandle, blockIndex,
						  GL_UNIFORM_BLOCK_DATA_SIZE, &blockSize);
	
	GLubyte * blockBuffer= (GLubyte *) malloc(blockSize);

Query for the offset of each variable within the block. To do so, we first find the index of each variable within the block.

	
// Query for the offsets of each block variable
	const GLchar *names[] = { "InnerColor", "OuterColor",
							  "RadiusInner", "RadiusOuter" };
	
	GLuint indices[4];
	glGetUniformIndices(programHandle, 4, names, indices);
	
	GLint offset[4];
	glGetActiveUniformsiv(programHandle, 4, indices,
						  GL_UNIFORM_OFFSET, offset);

Place the data into the buffer at the appropriate offsets.

	
GLfloat outerColor[] = {0.0f, 0.0f, 0.0f, 0.0f};
	GLfloat innerColor[] = {1.0f, 1.0f, 0.75f, 1.0f};
	GLfloat innerRadius = 0.25f, outerRadius = 0.45f;
	
	memcpy(blockBuffer + offset[0], innerColor,
									4 * sizeof(GLfloat));
	memcpy(blockBuffer + offset[1], outerColor,
									4 * sizeof(GLfloat));
	memcpy(blockBuffer + offset[2], &innerRadius,
									sizeof(GLfloat));
	memcpy(blockBuffer + offset[3], &outerRadius,
									sizeof(GLfloat));

Create the OpenGL buffer object and copy the data into it.

	
GLuint uboHandle;
	glGenBuffers( 1, &uboHandle );
	glBindBuffer( GL_UNIFORM_BUFFER, uboHandle );
	glBufferData( GL_UNIFORM_BUFFER, blockSize, blockBuffer,
				  GL_DYNAMIC_DRAW );

Bind the buffer object to the uniform block.

	
glBindBufferBase( GL_UNIFORM_BUFFER, blockIndex, uboHandle );

How it works...
Phew! This seems like a lot of work! However, the real advantage comes when using multiple programs where the same buffer object can be used for each program. Let's take a look at each step individually.

First, we get the index of the uniform block by calling glGetUniformBlockIndex, then we query for the size of the block by calling glGetActiveUniformBlockiv. After getting the size, we allocate a temporary buffer named blockBuffer to hold the data for our block.

The layout of data within a uniform block is implementation dependent, and implementations may use different padding and/or byte alignment. So, in order to accurately layout our data, we need to query for the offset of each variable within the block. This is done in two steps. First, we query for the index of each variable within the block by calling glGetUniformIndices. This accepts an array of variable names (third argument) and returns the indices of the variables in the array indices (fourth argument). Then we use the indices to query for the offsets by calling glGetActiveUniformsiv. When the fourth argument is GL_UNIFORM_OFFSET, this returns the offset of each variable in the array pointed to by the fifth argument. This function can also be used to query for the size and type; however, in this case we choose not to do so, to keep the code simple (albeit less general).

The next step involves filling our temporary buffer blockBuffer with the data for the uniforms at the appropriate offsets. Here we use the standard library function memcpy to accomplish this.

Now that the temporary buffer is populated with the data with the appropriate layout, we can create our buffer object and copy the data into the buffer object. We call glGenBuffers to generate a buffer handle, and then bind that buffer to the GL_UNIFORM_BUFFER binding point by calling glBindBuffer. The space is allocated within the buffer object and the data is copied when glBufferData is called. We use GL_DYNAMIC_DRAW as the usage hint here, because uniform data may be changed somewhat often during rendering. Of course, this is entirely dependent on the situation.

Finally, we associate the buffer object with the uniform block by calling glBindBufferBase. This function binds to an index within a buffer binding point. Certain binding points are also so-called "indexed buffer targets". This means that the target is actually an array of targets, and glBindBufferBase allows us to bind to one index within the array.

There's more...
If the data for a uniform block needs to be changed at some later time, one can call glBufferSubData to replace all or part of the data within the buffer. If you do so, don't forget to first bind the buffer to the generic binding point GL_UNIFORM_BUFFER.

Using an instance name with a uniform block
A uniform block can have an optional instance name. For example, with our BlobSettings block, we could have used the instance name Blob, as shown here:


uniform BlobSettings {
  vec4 InnerColor;
  vec4 OuterColor;
  float RadiusInner;
  float RadiusOuter;
} Blob;

In this case, the variables within the block are placed within a namespace qualified by the instance name. Therefore our shader code needs to refer to them prefixed with the instance name. For example:


FragColor =
   mix( Blob.InnerColor, Blob.OuterColor,
	   smoothstep( Blob.RadiusInner, Blob.RadiusOuter, dist )
   );

Additionally, we need to qualify the variable names within the OpenGL code when querying for variable indices. The OpenGL specification says that they must be qualified with the block name (BlobSettings). However, my tests using the ATI Catalyst (10.8) drivers required me to use the instance name (Blob).

Using layout qualifiers with uniform blocks
Since the layout of the data within a uniform buffer object is implementation dependent, it required us to query for the variable offsets. However, one can avoid this by asking OpenGL to use the standard layout std140. This is accomplished by using a layout qualifier when declaring the uniform block. For example:


layout( std140 ) uniform BlobSettings {
   ...
};

The std140 layout is described in detail within the OpenGL specification document (available at http://www.opengl.org).

Other options for the layout qualifier that apply to uniform block layouts include packed and shared. The packed qualifier simply states that the implementation is free to optimize memory in whatever way it finds necessary (based on variable usage or other criteria). With the packed qualifier, we still need to query for the offsets of each variable. The shared qualifier guarantees that the layout will be consistent between multiple programs and program stages provided that the uniform block declaration does not change. If you are planning to use the same buffer object between multiple programs and/or program stages, it is a good idea to use the shared option.

There are two other layout qualifiers that are worth mentioning: row_major and column_major. These define the ordering of data within the matrix type variables within the uniform block.

One can use multiple qualifiers for a block. For example, to define a block with both the row_major and shared qualifiers, we would use the following syntax:


layout( row_major, shared ) uniform BlobSettings {
   ...
};

Summary
This article covered the topic of Using Uniform Blocks and Uniform Buffer Objects.