TetroGL: An OpenGL Game Tutorial in C++ for Win32 platforms - Part 3

• Download source - 2.49 MB
• Download binaries - 2.11 MB

Foreword

This series of articles focuses on a 2D game development with C++ and OpenGL for Windows platform. The target is to provide a game that is similar to a classic block puzzle game by the end of the series. We will not only focus on OpenGL but also talk about the designs that are commonly used in game programming with a full object oriented approach. You should already be familiar with the C++ language in order to get the maximum out of this series. There is a message board at the bottom of the article that you can use if you have questions, remarks or suggestions.

The series is divided into three articles:

• Part 1 : covers the window creation and the setting-up of OpenGL.
• Part 2 : covers resources handling and displaying simple animations.
• Part 3: groups everything together and talk about the game logic.

Contents

• Introduction
• Drawing Text
• Handling the States of your Game
• Game Example
  • The Menu State
  • The Play State
  • The High-Scores State
• Conclusion
• Links
• Acknowledgement

Introduction

This is the last article in the series, we already saw how to create the main window and display images and animations on it. We will now see how we can use that on a concrete example. Before we do so, we will first look at how we can draw text using OpenGL and how to manage the different states of a game (main menu, play state, high-scores, ...).

Drawing Text

For a lot of games, displaying images loaded from files is not enough: Sometimes you would like to display some text which is not known when you design your game. For example, the player name used in the high-scores, the current player score, etc. You can draw text with OpenGL by making use of display lists. A display list is a list of OpenGL commands that are stored together and which can be executed later as often as you need. Suppose that you have a very complex object for which you have a lot of OpenGL calls (e.g. an object made of a lot of textures) that you would like to draw often. Instead of each time repeating the same OpenGL commands, you can 'execute' the commands once and store them in a display list. You can then call your display list later whenever you want to display the objects instead of calling all the OpenGL functions. When the list is invoked, all the commands in the list are executed in the order in which they were issued. The major advantage of using display lists is optimization: The OpenGL commands are already evaluated and might be stored in a format that is more suitable for your graphic card. For example, a rotation transformation requires quite a lot of calculations because a rotation matrix has to be generated from this command. If you use a display list, the final rotation matrix will be saved, which avoids redoing the complex calculation each time.

So, for what will those display list be useful to draw text? Well, when you create your font (with a specific typeface, height and weight), all the characters that need to be reused later can be drawn in a display list (one list for each character). You can then easily display text later by calling the different display lists of the characters you want to draw. Let's look at the header of the CGameFont class, which is used to draw the text:

// Utility class used to draw text on the screen using a 
// specific font.
class CGameFont
{
public:
  // Default constructor
  CGameFont();
  // Default destructor
  ~CGameFont();

  // Create the font with a specific height and weight.
  void CreateFont(const std::string& strTypeface , 
          int iFontHeight, 
          int iFontWeight);
  // Draw text on the screen at the specified location with
  // the specified colour.
  void DrawText(const std::string& strText, int XPos, 
          int YPos, GLfloat fRed, GLfloat fGreen, 
          GLfloat fBlue);

  // Returns the size of the text. The top and right fields
  // of the returned rectangle are set to 0.
  TRectanglei GetTextSize(const std::string& strText);

  static void SetDeviceContext(HDC hDevContext)  
  { m_hDeviceContext = hDevContext; }

private:
  // The device context used to create the font.
  static HDC m_hDeviceContext;
  // The index of the base of the lists.
  GLuint m_uiListBase;
  // The win32 font
  HFONT m_hFont;
};

The CreateFont function is used to create the font for the specified typeface (e.g. "Arial", "Times New Roman",...), with a specific height and weight (the weight specifies the thickness of the font). Once the font has been created successfully, you can call DrawText to draw the text contained in strText on the screen at the position specified by XPos and YPos, with the specified RGB color (fRed, fGreen and fBlue). The DrawText function should not be called before CreateFont, otherwise an exception will be thrown. In order to be able to create the font, a device context should be supplied. This can be done once through a static function (SetDeviceContext): You can call that function once at the start of your program by calling CGameFont::SetDeviceContext(hDC). The GetTextSize function is a utility function that can be used to retrieve the size of the text prior to draw it on the scree in order to place it correctly. The class also contains the index of the base of the display lists: several display lists can already be created, and those lists are identified by an Id. When you generate several consecutive display lists for your font, the Id of the first one is saved in the m_uiListBase member.

Let's now look at the implementation of CreateFont:

void CGameFont::CreateFont(const std::string& strTypeface, 
               int iFontHeight,
               int iFontWeight)
{
  if (!m_hDeviceContext)
  {
    string strError = "Impossible to create the font: ";
    strError += strTypeface;
    throw CException(strError);
    return;
  }

  // Ask openGL to generate a contiguous set of 255 display lists.
  m_uiListBase = glGenLists(255);
  if (m_uiListBase == 0)
  {
    string strError = "Impossible to create the font: ";
    strError += strTypeface;
    throw CException(strError);
    return;
  }

  // Create the Windows font
  m_hFont = ::CreateFont(-iFontHeight,
                  0,
                  0,
                  0,
                  iFontWeight,
                  FALSE,
                  FALSE,
                  FALSE,
                  ANSI_CHARSET,
                  OUT_TT_PRECIS,
                  CLIP_DEFAULT_PRECIS,
                  ANTIALIASED_QUALITY,
                  FF_DONTCARE|DEFAULT_PITCH,
                  strTypeface.c_str());
  if (m_hFont == NULL)
  {
    m_uiListBase = 0;
    string strError = "Impossible to create the font: ";
    strError += strTypeface;
    throw CException(strError);
    return;
  }

  // Select the newly create font into the device context (and save the previous
  // one).
  HFONT hOldFont = (HFONT)SelectObject(m_hDeviceContext, m_hFont);
  // Generate the font display list (for the 255 characters) starting
  // at display list m_uiListBase.
  wglUseFontBitmaps(m_hDeviceContext, 0, 255, m_uiListBase);  
  // Set the original font back in the device context
  SelectObject(m_hDeviceContext, hOldFont); 
}

The first thing we do there is to verify if a device context has been supplied. If that's not the case, we can't create a font so we throw an exception. We then ask OpenGL to generate a continuous set of 255 diplay lists that will be used for 255 characters. The function returns the Id of the first display list, that is saved in the m_uiListBase member. If the function returns, it means that OpenGL couldn't allocate 255 display lists, so we throw an exception. We then create the font by calling CreateFont (which is a Windows function). I won't list all the parameters of the function but the ones in which we are interested is the font height (the first one), the font weight (the fifth one) and the typeface (the last one). If you are interested, you can have a look at the MSDN documentation here. Note that we supply the font height as a negative number. This is done so that Windows will try to find a matching font using the character height instead of the cell height. If the font creation was successfull, it is returned, otherwise NULL is returned (in which case we throw an exception). We then select this font as the active one in the device context and store the old font in order to set it back when we are done. We then call wglUseFontBitmaps that will generate the display lists for each of the characters based on the selected font in the device context. The second argument is the index of the first character for which we want to generate a display list and the third one is the number of characters (starting from this one) that we would like to generate a display list for. In our case, we would like to generate a display list for all 255 characters. If you look at an ASCII table, you can see that not all characters are usable: The first usable character start at 32 (the space character) and the last one is 127 (the delete character). So, we could have reduced our display lists to 96 lists instead of 255, but this has not be done here to keep things simple. Once all the display lists have been generated, we select the old font again in the device context.

Once the font has been created, we are able to draw text on the screen by calling DrawText:

void CGameFont::DrawText(const std::string& strText, 
             int XPos, int YPos,
             GLfloat fRed, 
             GLfloat fGreen, 
             GLfloat fBlue)
{
  if (m_uiListBase == 0)
  {
    throw CException("Impossible to diplay the text.");
    return;
  }

  // Disable 2D texturing
  glDisable(GL_TEXTURE_2D);
  // Specify the current color
  glColor3f(fRed, fGreen, fBlue);
  // Specify the position of the text
  glRasterPos2i(XPos, YPos);

  // Push the list base value
  glPushAttrib (GL_LIST_BIT);
    // Set a new list base value. 
    glListBase(m_uiListBase);
    // Call the lists to draw the text.
    glCallLists((GLsizei)strText.size(), GL_UNSIGNED_BYTE, 
          (GLubyte *)strText.c_str());
  glPopAttrib ();

  // Reenable 2D texturing
  glEnable(GL_TEXTURE_2D);
}

The first thing we do here is to verify if we have a valid list base (which is generated when the font is created). If that's not the case, we throw an exception. After that, we disable 2D texturing because it interferes with the text and the text color will be affected by the last texture that was applied. We then specify the text color by setting the current color, and then the position of the text by calling glRasterPos2i which sets the current raster position (the position which is used to draw pixels and bitmaps). We then push the 'list bit' in order to save the current list base in OpenGL. This is done so that you won't interfere with other display lists that migh have saved the list base. We then set this list base value by calling glListBase, this tells OpenGL that m_uiListBase is the new base for the display lists. Suppose that when we generated our font, the first available display list was at Id 500. The glListBase command specifies that 500 is the new base for the display list, so that if you call glCallLists, an offset of 500 will be added to the Id we supply to glCallLists. You'll see at the next line of code why we do so. Finally, we draw the text by calling glCallLists: The first argument is the number of display lists to be executed, we need to execute one for each letter we want to draw (thus the number of display lists is the number of characters in the string). The second argument is the type of the values which are passed in the third argument. We pass single byte characters, so the type is GL_UNSIGNED_BYTE. The third argument is the Id's of the list we want to call. Suppose that the first character is an 'A', which correspond to an ASCII code of 65, we will then call the list with Id 565 (because of the offset of the previous example), which correspond to the Id of the list for the letter 'A'. And we do the same for each of the character in the string. Each call to the display list will modify the current raster position and move it to the right of the character that was drawn. That's why the characters do not pile up on each other. We then reset the list base to its previous value (by calling glPopAttrib) and we re-enable 2D texturing.

The display lists should also be destroyed once you don't need them anymore. This is done in the class destructor:

CGameFont::~CGameFont()
{
  if (m_uiListBase)
    glDeleteLists(m_uiListBase,255);
  DeleteObject(m_hFont);
}

If the font was properly initialized (m_uiListBase different than 0), we delete 255 lists starting at index m_uiListBase, which were the lists that were generated for this font. We also delete the Win32 font.

So, displaying text becomes quite easy when using this little class:

// Done once, at the start of the program.
CGameFont::SetDeviceContext(hDC);

...
...

CGameFont newFont;
newFont.CreateFont("Arial", 30, FW_BOLD);
newFont.DrawText("Test",300,150,1.0,1.0,1.0);

Handling the States of your Game

In almost every game, you will encounter different 'states': Usually you have a main menu (which allows the user to start a new game, set some options, view the highscores), the main play state, the highscore state, etc. It quickly becomes a mess in your code if you have to manage everything in the same class: The update and draw functions becomes a gigantic switch in which you have to take care of all the possible states, all the variables are mixed together which makes the code hard to maintain, and so on. Luckily, there's an easy design pattern that elegantly solves the problem: The state pattern. The principle is quite simple: Each state of your game has its own separate class which inherits from a common 'state' class. So, in our example we have a class for the menu, a class for the play state, a class for the highscores, and so on. A state manager class keeps track of the current state of the game and redirect every call to this active state (draw, update, key down, ...). When you have to switch to another state, you simply inform the state manager of the new state. You can find quite a lot of nice articles about this pattern on the net, so I won't enter into much details here. Take a look at the first link in the references if you want to go more in details about this design pattern.

In the sources, you will find a CStateManager class which looks like:

// Manages the different states of the game.
class CStateManager
{
public:
  // Default constructor
  CStateManager();
  // Default destructor
  ~CStateManager();

  // Switches to another active state.
  void ChangeState(CGameState* pNewState)
  {
    if (m_pActiveState)
      m_pActiveState->LeaveState();
    m_pActiveState = pNewState;
    m_pActiveState->EnterState();
  }

  // Returns the current active state.
  CGameState* GetActiveState()  { return m_pActiveState; }

  // 'Events' function, they are simply redirected to
  // the active state.
  void OnKeyDown(WPARAM wKey);
  void OnKeyUp(WPARAM wKey);
  void Update(DWORD dwCurrentTime);
  void Draw();

private:
  // Active State of the game (intro, play, ...)
  CGameState* m_pActiveState;   
};

This class manages the current state of the game and redirects all 'events' call to it: If you look at the implementation of OnKeyDown, OnKeyUp, Update and Draw, you will see that they simply call the same function on the m_pActiveState instance. When switching to another state, the state manager calls the LeaveState of the current state and the EnterState of the new state. States can implement those functions to do special initialization or clean up when the state becomes active or inactive.

The CGameState is very easy too:

// Base class for the different states
// of the game.
class CGameState
{
public:
  // Constructor
  CGameState(CStateManager* pManager);
  // Destructor
  virtual ~CGameState();

  // The different 'events' functions. Child classes can 
  // implement the ones in which they are interested in.
  virtual void OnKeyDown(WPARAM ) { }
  virtual void OnKeyUp(WPARAM )   { }
  virtual void OnChar(WPARAM )   { }
  virtual void Update(DWORD )  { }
  virtual void Draw()  { }

  // Functions called when the state is entered or exited
  // (transition from/to another state).
  virtual void EnterState()  { }
  virtual void ExitState()   { }

protected:
  // Helper function to switch to a new active state.
  void ChangeState(CGameState* pNewState);

  // The state manager.
  CStateManager* m_pStateManager;
};

The different classes that will manage the states of the game inherit from this class. These child classes can then implement the 'event' functions in which they are interested. The ChangeState function is there only as a helper function: It simply call ChangeState of the CStateManager.

Game Example

We have now covered everything that we need in order to create our game. This section explains important parts of the code but doesn't go into all the details here: There's a bit too much code to explain every single line of code in this article. However, the source code is fairly well commented so do not hesitate to take a deeper look.

The game is divided in three states: the menu state, the play state and the high-score state. As explained earlier, each of these states are handled in their own classes, which inherit from the CGameState class. Each of these classes are implemented as singletons.

There is a little addition in this game that is not available in its typical predecessors: A combo multiplier. Each time one (or several) line(s) is (are) completed, the player has a certain time to complete another line to multiply the score of the new completed line (or lines). The multiplier increases each time a new line has been completed before the combo time runs out. If the time runs out, the current muliplier is decreased by one and a new timer starts. Of course, the higher the multiplier is, the faster the time decrases.

The Menu State

This state displays the main menu with the following options: new game, resume game (if there is currently an active game), high scores and exit the game. The header file is:

// Specialization of the CGameState class for 
// the menu state. This displays a menu in which
// the player can start a new game, continue an 
// existing game, see the high-scores or exit the game.
class CMenuState : public CGameState
{
public:
  ~CMenuState();

  void OnKeyDown(WPARAM wKey);
  void Draw();
  void EnterState();

  static CMenuState* GetInstance(CStateManager* pManager);

protected:
  CMenuState(CStateManager* pManager);

private:
  // The player went up or down in 
  // the menu
  void SelectionUp();
  void SelectionDown();
  // The player validated the current selection
  void SelectionChosen();

  CGameFont* m_pFont;
  // Index of the current selected menu item
  int m_iCurrentSelection;

  // A pointer to the current active game (if any).
  CPlayState* m_pCurrentGame;

  // The background and title images
  TImagePtr m_pBackgroundImg;
  TImagePtr m_pTitleImg;

  // The images of the menu items (normal and
  // selected).
  TImagePtr m_pItemBckgndNormal;
  TImagePtr m_pItemBckgndSelected;

  // The text controls of the different entries.
  CTextControl* m_pNewGameText;
  CTextControl* m_pResumeGameText;
  CTextControl* m_pScoresText;
  CTextControl* m_pExitText;
};

SelectionUp, SelectionDown or SelectionChosen functions are called when the up, down or enter key is pressed. The selection up and down functions simply change the m_iCurrentSelection index and the SelectionChosen function switches to another state or exit the game depending of the selected menu item.

The CTextControl is a simple utility class that displays text in a rectangle region with a certain alignment (left, center or right).

The Play State

This state is the most complicated one, because it is there that all the game logic is handled. The play state delegates most of the logic to the CBlocksMatrix class, which is responsible of the management of the playing area. There are 7 different shapes (also called tetrads), which are named by a letter depending on their shape: I, O, Z, S, T, L and J. Each of these tetrads has a specific class to handle it. It is done so because there is no generic way to handle all the different tetrads. For instance, rotations are not always done in the same way: The I tetrad (the line) has only two different position (vertical and horizontal), you don't simply rotate all the cells around a point. So, for this reason, each tetrad has to be handled separately. They all inherits from the CTetrad class, which looks like:

// Base class for all shapes (tetrad)
class CTetrad
{
public:
  // Construct a new tetrad. The image of the block used to draw
  // the tetrad is loaded depending of the tetrad color.
  CTetrad(CBlocksMatrix* pParent, EBlockColor blockColor) 
    : m_pParentMatrix(pParent), m_iXPos(4), m_iYPos(0), 
      m_Orientation(Rotation0), m_pBlockImg(NULL), m_BlockColor(blockColor)  
  { 
    switch (blockColor)
    {
    case bcCyan:
      m_pBlockImg = CImage::CreateImage("Block.PNG",
          TRectanglei(0,BLOCK_HEIGHT,0,BLOCK_WIDTH));
      break;
    case bcBlue:
      m_pBlockImg = CImage::CreateImage("Block.PNG",
          TRectanglei(0,BLOCK_HEIGHT,BLOCK_WIDTH,2*BLOCK_WIDTH));
      break;
    case bcOrange:
      m_pBlockImg = CImage::CreateImage("Block.PNG",
          TRectanglei(0,BLOCK_HEIGHT,2*BLOCK_WIDTH,3*BLOCK_WIDTH));
      break;
    case bcYellow:
      m_pBlockImg = CImage::CreateImage("Block.PNG",
          TRectanglei(0,BLOCK_HEIGHT,3*BLOCK_WIDTH,4*BLOCK_WIDTH));
      break;
    case bcGreen:
      m_pBlockImg = CImage::CreateImage("Block.PNG",
          TRectanglei(0,BLOCK_HEIGHT,4*BLOCK_WIDTH,5*BLOCK_WIDTH));
      break;
    case bcPurple:
      m_pBlockImg = CImage::CreateImage("Block.PNG",
          TRectanglei(BLOCK_HEIGHT,2*BLOCK_HEIGHT,0,BLOCK_WIDTH));
      break;
    case bcRed:
      m_pBlockImg = CImage::CreateImage("Block.PNG",
          TRectanglei(BLOCK_HEIGHT,2*BLOCK_HEIGHT,BLOCK_WIDTH,2*BLOCK_WIDTH));
      break;
    }
  }
  virtual ~CTetrad() { }

  // Tries to rotate the tetrad. If it can't be rotated, 
  // the function returns false.
  virtual bool Rotate() = 0;
  // Tries to move the tetrad to the left. If it can't be 
  // moved, the function returns false.
  virtual bool MoveLeft() = 0;
  // Tries to move the tetrad to the right. If it can't be 
  // moved, the function returns false.
  virtual bool MoveRight() = 0;
  // Tries to move the tetrad down. If it can't be 
  // moved, the function returns false.
  virtual bool MoveDown() = 0;

  // Ask the tetrad to fill the cells in the matrix.
  // This function is called when the tetrad is positioned.
  virtual void FillMatrix() = 0;
  // Checks if the tetrad is at a valid position (do not 
  // overlap with a filled cell in the matrix). This is 
  // called when the tetrad is created to check for game over.
  virtual bool IsValid() = 0;

  // Draw the tetrad at its position in the matrix.
  virtual void Draw() = 0;
  // Draw the tetrad somewhere on the screen (used to
  // display the next shape). The tetrad is centered
  // in the rectangle.
  virtual void DrawOnScreen(const TRectanglei& rect) = 0;

protected:
  // The play area in which the tetrad is used
  CBlocksMatrix* m_pParentMatrix;

  // The position in the play area (in
  // blocks).
  int m_iXPos;
  int m_iYPos;

  enum EOrientation
  {
    Rotation0,
    Rotation90,
    Rotation180,
    Rotation270,
  };
  // Orientation of the tetrad
  EOrientation m_Orientation;

  // The block image use to draw the tetrad.
  TImagePtr m_pBlockImg;
  // The block color.
  EBlockColor m_BlockColor;
};

The child classes implement those virtual methods. They interract with the CBlocksMatrix class to check if some cells are free or not. Here is an example of the rotation function for the Z tetrad:

bool CTetrad_Z::Rotate()
{
  bool bSuccess = false;
  switch (m_Orientation)
  {
  case Rotation0:
  case Rotation180:
    if (m_pParentMatrix->IsCellFree(m_iXPos,m_iYPos-1) &&

      m_pParentMatrix->IsCellFree(m_iXPos-1,m_iYPos+1) )
    {
      m_Orientation = Rotation90;
      bSuccess = true;
    }
    break;

  case Rotation90:
  case Rotation270:
    if (m_pParentMatrix->IsCellFree(m_iXPos,m_iYPos+1) &&
      m_pParentMatrix->IsCellFree(m_iXPos+1,m_iYPos+1))
    {
      m_Orientation = Rotation0;
      bSuccess = true;
    }
    break;
  }
  return bSuccess;
}

Depending of the current rotation of the tetrad, it will check if the cells that will be occupied after the rotation are free or not. If they are free, the m_Orientation member is updated and the function returns true. The other move or rotate functions of all the tetrads are similar, so I won't put here the code for all of them. The Draw function is not very difficult neither:

void CTetrad_Z::Draw()
{
  int screenX=0, screenY=0; 

  switch (m_Orientation)
  {
  case Rotation0:
  case Rotation180:
    m_pParentMatrix->GetScreenPosFromCell(m_iXPos-1,m_iYPos,screenX,screenY);
    m_pBlockImg->BlitImage(screenX,screenY);
    m_pParentMatrix->GetScreenPosFromCell(m_iXPos  ,m_iYPos,screenX,screenY);
    m_pBlockImg->BlitImage(screenX,screenY);
    m_pParentMatrix->GetScreenPosFromCell(m_iXPos  ,m_iYPos+1,screenX,screenY);
    m_pBlockImg->BlitImage(screenX,screenY);
    m_pParentMatrix->GetScreenPosFromCell(m_iXPos+1,m_iYPos+1,screenX,screenY);
    m_pBlockImg->BlitImage(screenX,screenY);
    break;

  case Rotation90:
  case Rotation270:
    m_pParentMatrix->GetScreenPosFromCell(m_iXPos  ,m_iYPos-1,screenX,screenY);
    m_pBlockImg->BlitImage(screenX,screenY);
    m_pParentMatrix->GetScreenPosFromCell(m_iXPos  ,m_iYPos  ,screenX,screenY);
    m_pBlockImg->BlitImage(screenX,screenY);
    m_pParentMatrix->GetScreenPosFromCell(m_iXPos-1,m_iYPos  ,screenX,screenY);
    m_pBlockImg->BlitImage(screenX,screenY);
    m_pParentMatrix->GetScreenPosFromCell(m_iXPos-1,m_iYPos+1,screenX,screenY);
    m_pBlockImg->BlitImage(screenX,screenY);
    break;
  }
}

The screen position of a cell can be retrieved from the CBlocksMatrix class (remember that the m_iXPos and m_iYPos members are the position in the matrix and are not screen positions).

The CBlocksMatrix is responsible to handle all the logic related to checking filled lines and removing them. Let's first look at the class header, we will look at the implementation of some functions later:

// Class managing the playing area (where the shapes are
// falling). It handles all the logic related to lines.
class CBlocksMatrix
{
public:
  // Constructor and destructor
  CBlocksMatrix(CMatrixEventsListener* pListener, int xPos, int yPos);
  ~CBlocksMatrix();

  // Draw and update the matrix
  void Draw();
  void Update(DWORD dwCurrentTime);
  // Reset the matrix to its initial state
  void Reset();

  // Move the current shape
  void ShapeLeft();
  void ShapeRight();
  void ShapeDown();
  void ShapeRotate();

  // Check if the specified cell is free or not.
  bool IsCellFree(int XPos, int YPos);
  // Fill the specified cell with a specific block color
  void FillCell(int XPos, int YPos, EBlockColor BlockColor);
  // Transform a cell coordinates into screen coordinates.
  void GetScreenPosFromCell(int cellXPos, int cellYPos, 
    int& screenXPos, int& screenYPos);

  // Returns the next shape
  CTetrad* GetNextShape() const  { return m_pNextShape; }

  // Sets/Gets the time between two update of the current
  // shape (determines the speed at which it falls).
  void SetTetradUpdate(int iNewUpdate)  { m_iTetradUpdate = iNewUpdate; }
  int  GetTetradUpdate() const  { return m_iTetradUpdate; }

private:
  // Check if there are lines completed in the
  // matrix. This returns true if at least one
  // line is complete
  bool CheckMatrix();
  // Check if the specified line is currently being
  // removed
  bool IsLineRemoved(int iRow);
  // Remove the lines that are complete from the
  // matrix and adjust the remaining blocks.
  void RemoveLines();
  // Tries to create a new shape. If this is not
  // possible (e.g. matrix full), m_bGameOver is
  // set to true.
  void NewShape();

  // The screen coordinates of the top-left 
  // corner.
  int m_iXPos;
  int m_iYPos;

  // The matrix of blocks which are already filled
  int m_pBlocksMatrix[MATRIX_WIDTH][MATRIX_HEIGHT];

  // The images of the 7 different blocks
  TImagePtr m_pBlockImg[7];

  // The tetrad factory
  CTetradFactory m_TetradFactory;
  // Current shape that the player manipulates
  CTetrad* m_pTetrad;
  // Next shape
  CTetrad* m_pNextShape;
  // The last move down of the current shape
  DWORD m_dwLastShapeDown;

  // Flag indicating that one or more
  // lines are being removed (blinking)
  bool m_bRemovingLine;
  // The number of times the line being removed
  // has already blinked.
  int  m_iLineBlinkCount;
  // Specify if the the line being removed is currently
  // visible or not (for blinking)
  bool m_bLineBlinkOn;
  // Vector containing the line numbers of the
  // lines being removed.
  std::vector<int> m_vecLinesRemoved;

  // The event listener
  CMatrixEventsListener* m_pListener;
  // Time (in msec) before the tetrad is moved down
  // one step.
  int m_iTetradUpdate;

  // Flag indicating a game over.
  bool m_bGameOver;
};

The ShapeLeft, ShapeRight, ShapeRotate and ShapeDown functions are simply redirected to the current tetrad (m_pTetrad). The ShapeDown function does a bit more, because if a tetrad cannot move down, some special checks need to be done:

void CBlocksMatrix::ShapeDown()
{
  if (m_pTetrad && !m_pTetrad->MoveDown())
  {
    // If the current shape can't move down,
    // we ask it to fill the matrix.
    m_pTetrad->FillMatrix();
    // Then delete the current shape
    delete m_pTetrad; 
    m_pTetrad = NULL;
    
    // We then check if no lines have been completed
    // and create the next shape. The m_bGameOver flag
    // can be set in this NewShape function.
    if (!CheckMatrix())
      NewShape();
  }
  // Set the last update (down) of the shape to 
  // the current time.
  m_dwLastShapeDown = GetCurrentTime();
}

If the shape cannot be moved down (the MoveDown function returns false), we first ask it to fill the cells of the matrix where it is located, then delete it. We then check if at least one line of the matrix is complete: The CheckMatrix function returns true if at least one line is completed and if that is the case, it will push the line numbers of the ones that are filled in the m_vecLinesRemoved vector and set m_bRemovingLine to true. If no lines were completed, we try to create a new shape by calling NewShape. If the shape cannot be created (because the matrix is full), the m_bGameOver flag will be set to true.

The Update function only checks if the current shape should be moved down:

void CBlocksMatrix::Update(DWORD dwCurrentTime)
{
  if (!m_bGameOver)
  {
    // Check if the current shape should be moved down
    if (dwCurrentTime > m_dwLastShapeDown+m_iTetradUpdate)
      ShapeDown();
  }
}

The m_iTetradUpdate variable specifies the maximum time between two moves down of the current shape. This decreases with the level (the higher the level, the faster the shape will go down). Don't forget that the m_dwLastShapeDown variable is set to the current time in the ShapeDown function (so if the shape is moved manually, this is also set).

Finally, the Draw function takes care of drawing the current state on the screen:

void CBlocksMatrix::Draw()
{
  int iBlockX=0, iBlockY=0;
  // If some lines are currently being removed,
  // We shouldn't draw them all.
  if (m_bRemovingLine)
  {
    for (int j=0; j<MATRIX_HEIGHT;j++)
    {
      // Don't draw the line if it is being removed and blinking off
      if (IsLineRemoved(j) && !m_bLineBlinkOn)
        continue;

      // Else draw the line
      for (int i=0; i<MATRIX_WIDTH;i++)
      {
        if (m_pBlocksMatrix[i][j])
        {
          int color = m_pBlocksMatrix[i][j]-1;
          GetScreenPosFromCell(i, j, iBlockX, iBlockY);
          m_pBlockImg[color]->BlitImage(iBlockX, iBlockY);
        }     
      }
    }

    // Switch the blinking
    if (m_bLineBlinkOn)
      m_bLineBlinkOn = false;
    else
      m_bLineBlinkOn = true;
    m_iLineBlinkCount++;
    // If blink count equals 10, we stop blinking and remove
    // the lines.
    if (m_iLineBlinkCount == 10)
    {
      RemoveLines();
      m_bRemovingLine = false;
      m_bLineBlinkOn = false;
      m_iLineBlinkCount = 0;
      NewShape();
    }
  }
  else 
  {
    // Draw filled blocks
    for (int j=0; j<MATRIX_HEIGHT;j)
    {
      for (int i=0; i<MATRIX_WIDTH;i++)
      {
        if (m_pBlocksMatrix[i][j])
        {
          int color = m_pBlocksMatrix[i][j]-1;
          GetScreenPosFromCell(i, j, iBlockX, iBlockY);
          m_pBlockImg[color]->BlitImage(iBlockX, iBlockY);
        }
      }
    }

    // Finally, draw the current shape
    if (!m_bGameOver)
      m_pTetrad->Draw();
  }

}

The first part of the function (if m_bRemovingLine is true) is only executed when we are removing lines (the lines which are complete will blink before being removed). Remember that in order to display 'animations', the state should be saved in some way for the next frame to be displayed. That's the reason why we have to remember if the lines are currently visible or not (m_bLineBlinkOn) and the number of times they have already blinked (m_iLineBlinkCount). The IsLineRemoved function returns true if the line passed in argument is being removed. When the blinking is finished, the RemoveLines function is called which will remove the lines from the matrix and clean everything (blocks above a removed line will be moved down). The second part of the function gets executed the rest of the time (when no lines are being removed). It simply draws all the filled blocks and the current shape.

As you probably saw, there is also a CMatrixEventsListener class. In fact, this is just an interface that should be implemented by another class in order to be notified about some events that occurs in the blocks matrix (starting to remove lines, lines removed, game over). The CPlayState class implements this interface (and its address is passed to the CBlocksMatrix when constructing it). This technique is used in order to reduce coupling between those classes: The CBlocksMatrix class becomes independant of the class which is using it and which should be notified about the events. The CPlayState looks like:

class CPlayState : public CGameState, 
           public CMatrixEventsListener
{
public:
  ~CPlayState();

  // Implementation of specific events
  void OnKeyDown(WPARAM wKey);
  void Update(DWORD dwCurrentTime);
  void Draw();

  // Implementation of the CMatrixEventsListener class
  void OnStartRemoveLines();
  void OnLinesRemoved(int iLinesCount);
  void OnMatrixFull();

  void Reset();
  bool IsGameOver()  { return m_bGameOver; }

  // Returns the single instance
  static CPlayState* GetInstance(CStateManager* pManager);

protected:
  CPlayState(CStateManager* pManager);

private:
  // The blocks matrix class
  CBlocksMatrix* m_pMatrix;
  // The font used to draw text
  CGameFont* m_pFont;
  // The control in charge of the decreasing 
  // time for the combo score.
  CComboControl* m_pComboControl;

  // The text controls to display the current
  // information.
  CTextControl* m_pScoreControl;
  CTextControl* m_pLevelControl;
  CTextControl* m_pLinesControl;

  // The current number of lines completed
  int m_iTotalLines;
  // The current level
  int m_iCurrentLevel;
  // The current score
  int m_iCurrentScore;

  bool m_bGameOver;

  // The background image
  TImagePtr m_pBackgroundImg;
};

The main role of this class is to coordinate the different elements: The game matrix and the combo control and to manage the score and current lines completed. The implementation of the class is fairly trivial, so I won't describe it here. The CComboControl class handles the combo control: This control shows a decreasing time bar when a line has been completed. If a new line is completed before time is over, a multiplier is applied to the points gained for the line(s) completed. The higher the multiplier, the fastest time will decrease.

When the game is over, a semi-transparent black rectangle will be displayed over the full screen with some text on it. This is done with the help of blending: support for blending has been added in the CMainWindow::InitGL function:

// Specifies the blending function
  glBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA);
// Enable blending
glEnable(GL_BLEND);

The glEnable(GL_BLEND) simply enables the blending, but you also have to specify a blending function. The blending function tells OpenGL how to blend the incoming pixels with the pixels present in the frame buffer. Specifying this is done through the glBlendFunc: The first argument specifies the factor to apply to the RGB components of the source pixels (the incoming pixels) and the second argument specifies the factor to apply to the destination pixels (the pixels which are already in the frame buffer). The final pixel will be the addition of the resulting values (for each components). The code we use to make the semi-transparent black screen is:

if (m_bGameOver)
{
  // In game over, we draw a semi-transparent black screen on top
  // of the background. This is possible because blending has
  // been enabled.
  glColor4f(0.0,0.0,0.0,0.5);
  // Disable 2D texturing because we want to draw a non
  // textured rectangle over the screen.
  glDisable(GL_TEXTURE_2D);
  glBegin(GL_QUADS);
  glVertex3i(0,0,0);
  glVertex3i(0,600,0);
  glVertex3i(800,600,0);
  glVertex3i(800,0,0);
  glEnd();
  glEnable(GL_TEXTURE_2D);

  m_pFont->DrawText("GAME OVER",340,200);
  m_pFont->DrawText("Press Enter to continue",285,300);
}

This means that we first select a black color with an alpha channel of 0.5 and then we draw our rectangle over the complete screen. We have to disable texturing when drawing our rectangle, because we want a non textured black rectangle.

The High-Scores State

This state is responsible to display the high-scores which are saved from previous games. The information is saved in a file for persistency ("HighScores.txt"). The file is not protected, so anybody can edit this file and change the high-scores. This is of course not very nice but describing ways to protect this data is outside the scope of the article. As usual, I'll first show the class declaration before going into some details:

// Specialization of the CGameState class for 
// the high scores state. This displays the high
// scores (player name+score). When a new high 
// score is available after a game, it lets the 
// player enters his name.
class CHighScoreState : public CGameState
{
public:
  ~CHighScoreState();

  // Sets a new score: if this score should be 
  // part of the high scores, the user will need 
  // to enter his name.
  void SetNewHighScore(ULONG ulNewHighScore)  
  { m_ulNewHighScore = ulNewHighScore; }

  // Implementation of specific events
  void OnKeyDown(WPARAM wKey);
  void OnChar(WPARAM wChar);
  void Draw();
  void EnterState();

  static CHighScoreState* GetInstance(CStateManager* pManager);

protected:
  CHighScoreState(CStateManager* pManager);

private:
  // Saves the current high scores
  void SaveScores();

  // Adds a new score in the high-score table and
  // insert it at the correct location.
  void AddNewScore(const std::string& strName, ULONG ulScore);

  // High-score data: score and player name.
  struct HighScoreData
  {
    std::string strPlayer;
    ULONG ulScore;

    // We have to sort in decreasing order, so the <
    // operator returns the opposite.
    bool operator< (const HighScoreData& other)
    {
      if  (this->ulScore > other.ulScore) 
        return true;
      return false;
    }
  };

  // The new high-score, if any.
  ULONG m_ulNewHighScore;
  // Mode in which the user has to enter his name.
  bool m_bEnterName;
  // Char array containing the name currently being entered.
  char m_pCurrentName[26];
  // The index of the next char to be entered.
  int m_iNameIndex;

  CGameFont* m_pFont;

  typedef std::vector<HighScoreData> THighScoreTable;
  // The high-score table.
  THighScoreTable m_vecHighScores;

  // The background and title images.
  TImagePtr m_pBackgroundImg; 
  TImagePtr m_pTitleImg; 
  // The image of the entries background
  TImagePtr m_pEntriesBckgndImg;
  // The 'Enter name' image and the background.
  TImagePtr m_pEnterNameImg; 
  TImagePtr m_pEnterNameBackImg; 
};

The class overrides the EnterState function, it is used to read the high-scores from the file and check if a new high-score should be added in the table:

void CHighScoreState::EnterState()
{
  // Clear the high-score table
  m_vecHighScores.clear();
  ifstream inputFile("HighScores.txt");
  if (inputFile.fail())
  {
    if (m_ulNewHighScore)
      m_bEnterName = true;
    return;
  }

  // Read all entries from the file
  while (!inputFile.eof())
  {
    HighScoreData newScore;
    inputFile >> newScore.strPlayer >> newScore.ulScore;
    m_vecHighScores.push_back(newScore);
  }
  // Sort the table
  sort(m_vecHighScores.begin(), m_vecHighScores.end());

  // Check if we have a new high-score that should be
  // added in the table. If yes, m_bEnterName is set
  // to true.
  ULONG lastScore = 0;
  if (m_vecHighScores.size())
    lastScore = m_vecHighScores[m_vecHighScores.size()-1].ulScore;
  if (m_ulNewHighScore && m_ulNewHighScore>lastScore)
    m_bEnterName = true;
}

When reading the file, we sort the high-scores using the std::sort function. For that purpose, we should provide an operator< for our structure. The std::sort function sorts the elements in ascending order, that's the reason our operator returns the opposite of what is excepted (so that all elements are ordered in the opposite order). When characters are inserted by the user, the OnChar function is called. If the m_bEnterName flag is true, characters will be added to the m_pCurrentName array, until the user presses enter. In that case, the AddNewScore function is called:

void CHighScoreState::AddNewScore(const std::string& strName, ULONG ulScore)
{
  // Create a new high-score and push it into the table 
  HighScoreData newData;
  newData.strPlayer = strName;
  newData.ulScore = ulScore;
  m_vecHighScores.push_back(newData);
  
  // Sort the table
  sort(m_vecHighScores.begin(), m_vecHighScores.end());

  // If too much elements, remove the last one.
  while (m_vecHighScores.size() > 10)
    m_vecHighScores.pop_back();

  SaveScores();
}

The SaveScores is called at the end to save the new high scores in the file:

void CHighScoreState::SaveScores()
{
  // Create the file
  ofstream outputFile("HighScores.txt");
  if (outputFile.fail())
    return;

  // Write all the entries in the file.
  THighScoreTable::iterator iter = m_vecHighScores.begin();
  for (iter; iter != m_vecHighScores.end(); iter++)
  {
    outputFile << iter->strPlayer << " " << iter->ulScore;
  }
}

In normal mode (when the name is not entered), the user can exit the high-score state and return to the main menu by pressing enter or escape.

Conclusion

This was the last article in the series in which we saw how to draw text on the screen and how to manage the different states of a game. Everything we saw during these three tutorials was then used for a concrete example on a classic block game.

Of course, this example is fairly simple because there is no sound, no advanced user interface and no network access. In a more advanced game, you'll probably want to do something like that. Take a look at the references where I have put some links to libraries that supports that.

I hope you enjoyed the series. Don't hesitate to give your impressions through the message board at the bottom of the article or by rating it. Thanks.

Links

[1] State pattern: a good article about the state pattern design pattern.
[2] SFML library: Simple and Fast Multimedia Library. A free multimedia C++ API that provides you low and high level access to graphics, input, audio, etc.
[3] FMOD library: a music and sound effect library which is free for non-commercial distributions.
[4] RakNet: a cross-platform C++ game networking engine.
[5] CEGUI: a free library providing windowing and widgets for graphics APIs.
[6] dafont: a website providing some nice free fonts (the "01 digitall" font used for the game is downloaded from there).

Acknowledgement

I would like to thanks Daniel Metien and Andrew Vos for their very nice work on the graphics. The game wouldn't be very enjoyable without their work :). Thanks also to Jeff (aka El Corazon) for his patience and advices related to OpenGL.