DXFramework

1
DXFramework

• DirectX Game Framework
• Jonathan Voigt
• University of Michigan
• Winter 2004

2
Mission

• Simple, Illustrative 2D and 3D Computer Game
  Framework
• DirectX Technology
• C
• MSVC 6.0 or .NET
• Easy to learn abstraction of DirectX

3
The DXFramework Package

• The 0 in 0.9.2 is there for a reason!!!!
• Project hosted and available on SourceForge.NET
• Contains game framework with simple demos

4
The DXFramework Package

• Download and extract
• Contains different directories for source,
  images, sounds, docs, etc.
• Root directory of package contains .NET project
  files, msvc6/ subdirectory contains 6.0 files
• Documentation is located online at SourceForge

5
The DXFramework Package

• If DirectX is installed and MSVC configured
  correctly, everything should build out of the
  box
• Build process takes about 5 minutes on a Pentium
  IV 1.5 GHz
• Run in debug mode, check out section 1.3 in
  online manual
• Problems? Use SourceForge forum

6
2D versus 3D

• Generally, creating 2D games with DXFramework is
  easier than 3D games
• 3D components require 3D modeling
• DXFramework was originally only a 2D engine
• 2D components have more documentation
• 3D components recently added, less mature
• This presentations focus is on DXFrameworks 2D
  components

7
Top Level Design

• DXFramework uses a pseudo model-view-controller
  paradigm
• One container class holds model, view, and
  controller classes
• Although this design is not efficient for all
  applications, it is generally easier to learn,
  design, develop, and debug

8
Top Level Design
9
The Beginning

• WinMain() in main.cpp is the starting point for
  DXFramework
• Creates the top level C_Game object
• Handles windows messages
• Handles unhandled exceptions
• Exceptions are used for fatal errors
• Reports some memory leaks

10
Game Class

• C_Game
• C_GameRun()
• Run, Game, Run!
• (Dave Zarlengo)
• Simple class created by WinMain()
• Most of its code manages the model, view, and
  controller classes that it contains
• Also manages networking class

11
Game Class

• Run() member function
• Executes a frame
• Called once per frame by WinMain()
• Calls primary functions of the model, view, and
  controller classes

12
Model Class Topics

• Model class overview
• An overview of game states
• Game states are key!

13
Model Class

• Management and representation of game state
• Manages C_GameState objects
• Update() is the primary member function of the
  model class
• Called once per frame by C_Game
• Responsible for Updating the game state

14
Game States Overview

• A game state is a set of game objects, sounds,
  game logic, and state information relevant to a
  part of a game application
• Most games can intuitively be broken up into a
  set of game states
• Taking Tetris as an example, its states could be
  menu, options, game, highscore

15
Game States Overview

• The C_GameState class is an abstract base class
• Game states created with the framework inherit it
• The model class manages the different game states

16
Game States Overview

• Example game state the menu state of the
  DXFramework demo, including
• Logic to watch user input (mouse movement,
  checking to see if escape has been pressed)
• All of the pictures and button objects
• Logic defining what objects to display and what
  to do when the user interacts with these objects
• State information (current page)

17
Game States Overview

• Game states allow for a separation of data
• Separating data protects against corruption along
  with making memory management easier
• Only the logic and data relevant to the current
  state is loaded

18
Game States Overview

• Every game state leads to another state
• The initial state is pre-set in the code, each
  new state from then on is determined by the
  users interaction with the current state
• The final state is a special quit state which
  simply attempts a clean exit to the OS

19
Game States Overview

• All said and done, the progression of a
  DXFramework application can be described with a
  state transition diagram
• The (Game Boy) Tetris example

20
View Class Topics

• View class overview
• Rendering
• Screen vs. Window Dimensions
• Translation vs. Location coordinate systems (to
  be changed)

21
View Class Overview

• Initializes and configures display adapter with
  Direct3D using settings from initial dialog
  window
• Manages state information to regain control of
  the device after it has been lost
• A normal event leading to device loss is tasking
  (alt-tab) when in full-screen mode
• Allows easy access to device settings

22
Rendering

• Render() is views primary member function
• Calls Render() on the game state and other
  components so they can draw their objects to the
  back buffer
• Presents the back buffer to display at the end of
  each frame
• Detects device loss

23
Screen vs. Window Dimensions

• Screen dimensions are back buffer dimensions
  (hard coded constants)
• SCREEN_WIDTH, SCREEN_HEIGHT
• Window dimensions are actual display area
  dimensions (can be changed by configuration
  dialog)
• WINDOW_WIDTH, WINDOW_HEIGHT
• The back buffer and window sizes may be different

24
Translation vs. Location

• Translation is in the viewing coordinate system
• Native to device, graphics design
• Used throughout program

25
Translation and Location

• Location is in the traditional coordinate system
• Easier for 2D math
• Location origin can be changed and its use is
  optional
• Converting functions in View class

26
Controller Class

• Gathers and stores data from various input
  devices using DirectInput
• Keyboard, Mouse, and Joystick devices (each
  represented by a class) are supported
• Controller class input abstractions easier to
  deal with than raw DirectInput data
• Can tell if a button was just pressed or just
  released

27
Controller Class

• Calls Input() function on game state
• The game states then query the controller class
  for current input state
• Special console toggle key is handled in Input()
  function (tab key)
• If a tab key is pressed, the consoles viewable
  status is changed

28
Keyboard Input

• DirectInput handles non-buffered keyboard input
  via the Keyboard class
• Buffered input is caught in WinProc() function in
  main.cpp, and is immediately passed to the
  Controller class
• Buffered input is used for the console and other
  text input fields, non-buffered for buttons used
  in game play

29
Keyboard Input

• Non-buffered input is fast, but in rare occasions
  keys may be lost
• Possible cause button is pressed and released
  between device polls
• Buffered input is more latent, but key presses
  will not be lost
• Kind of like TCP vs. UDP

30
Net Class

• Abstraction of DirectPlay networking
• Manages communication between networked games
• Pong demo uses networking but is broken
• (it used to work)
• 0.9.2

31
The 2D Game Loop
32
Audio Topics

• Sound class
• Wave class

33
Sound Class

• Sound class is for using sounds in your game
• Many file formats are supported including
• .wav files of many different parameters
• .mp3 files with many different sampling rates
• .mid midi files
• Uses DirectShow to render sounds, slightly slower
  than wave class

34
Wave Class

• High performance .wav only class
• You must set sampling parameters in the code to
  match the sampling rates of your .wav files
• Renders faster than sound class, its use is
  recommended for short, often used sound effects
  that need to play on events

35
Wave Class

• Constructor also takes a boolean parameter
  whether or not to keep the wav in memory after
  its deleted
• Used to keep the wave around across state changes
• Must be used if the wave is supposed to play
  during a state transition, as deleting the state
  (and therefore the wave object) will stop the wav
  from playing (e.g. menu button clicks)

36
Other 2D Engine Components

• Console class
• 2D game object class
• Sprite class and animation
• Timer class
• Font class

37
Console Class

• Drop-down console included with engine
• Toggle with tab key (by default)
• Useful for
• Dumping debugging information during runtime
• Changing variables on the fly
• Enabling/Disabling features and output

38
Console Class

• Console (when activated) is rendered after game
  state so it is always on top
• Console uses buffered keyboard input
• Current console commands listed in readme.txt
  file
• Change console commands by editing ParseCommand()
  function
• Console commands can have parameters

39
2D Game Object Class

• Abstract base class for game objects
• Game objects are basically collections of
  properties and methods common to entities used in
  games
• Position, scaling, how to handle collisions
• This class bloated, will be rewritten soon

40
2D Game Object Class

• Game objects functions are called from the state
  they are contained in
• Input() is called so the object can gather
  relevant input
• Update() is called to update the objects state
• Render() is called to draw the object
• All three functions are optional

41
Game Object Collisions

• Game states have simple built-in 2D collision
  detection
• When it is used, Collision() is called when the
  object collides with another game object
• A pointer to the other object is passed
• All objects that collide should have a unique
  OBJECT_TYPE

42
Game Object Collisions

• The built in collision detection uses bounding
  boxes based on the objects height and width
• Game objects height and width need to be defined
  for the built in collision detection to work
• If use of bounding radii is desired, define a
  bounding radius of each object and check with
  CheckCircleIntersection()
• Demo B example

43
Sprite Class

• The sprite class is used to hold images
• Pretty much everything drawn on the screen in 2D
  games are sprites
• Notable exception fonts
• Many game objects contain sprites
• Many operations can be performed on sprites
• Rotation, scaling, color filtering, transparency

44
Sprite Class

• Common supported file formats
• .bmp, .png, .jpg, possibly others
• Image files stored in images subdirectory
• A color used as a transparent color can be set in
  the Game class constructor
• If the file format supports transparency (.png
  for example), this can be used without making a
  specific color transparent

45
Sprite Animation

• There is a built in sprite animation mechanism in
  DXFramework
• Encode animation data into image filenames (e.g.
  box-3-2-2.png)
• Animation Name
• Number of animations in image
• Number of rows
• Number of columns

46
Sprite Animation

• box-3-2-2.png
• A is the first animation frame
• B is the second
• C is the third
• D is never used
• The sprite height width is ½ the texture height
  width
• Texture/Sprite difference

47
Sprite Animation

• Use Animate() to advance a frame
• Use SetAnimation() to set a specific animation
  (counting from 0 to n-1)
• Non-animated sprites can be named anything (avoid
  dashes)
• They are essentially always in their first (only)
  animation frame
• Calling Animate() and related functions has no
  effect

48
Timer Class

• The timer class is used as a stopwatch in
  DXFramework
• Used to calculate frames per second
• FPS bug when frame rate locked to refresh
• Uses high performance timer available via DirectX

49
Timer Class

• Update() function must be called once every frame
  to update timer state
• The console command fps dumps the current
  frames per second to the screen
• The TimeMod() function can be used to fire events
  at specified intervals
• Such as recalculating the current FPS every half
  a second instead of each frame

50
Timer Class

• The timer keeps track of time between frames
• Use the GetElapsed() function
• and the time since the last call to its Reset()
  function
• Use the GetTime() function

51
Font Class

• An abstraction of Microsofts CD3DFont class
  (distributed with SDK)
• Uses 3D functions to quickly render fonts
• Font scaling, justification, and color operations
  available
• Use fonts commonly available on systems to avoid
  font not found error

52
Game States Revisited

• Game state functions
• Built In collision detection
• Constructor and destructor
• Using sub-states

53
Game State Functions

• Game states have three major functions that
  should be overridden (but do not have to be)
• Input() Gather input relevant to the state
• Update() Update state information, physics model
• Render() Draw what needs to be drawn

54
Built In Collision Detection

• Game states have simple built in collision
  detection
• Add and remove game objects to the game object
  list, then call CheckCollisions() to check for
  any bounding box collisions in the list
• When adding/removing game objects during
  collision detection, use ScheduleAdd and
  ScheduleRemove

55
Constructor and Destructor

• Use the game states constructor to load up
  objects needed by the state, and to initialize
  any state information
• Use the destructor to remove objects that are no
  longer necessary from memory
• Be careful with wav files that need to play
  across state changes!

56
Using Sub-States

• Some states can intuitively be broken into
  sub-states to make the design and implementation
  process easier
• Review section 2.1 of the manual for a long
  description of sub-states

57
Using Sub-States

• Theoretical example The Sims
• One major state when playing
• Sub-states representing each of the modes on the
  left real-time, buy-mode, build-mode, options
• Actions and state relevant to build-mode do not
  need to be around in real-time mode
• Drawing out walls, the 2 by 4 cutouts, the menu
  toolbar for building

58
Using Sub-States

• Continuing the Sims example
• Other properties do need to be around in both,
  and are stored in the main state
• Bankroll, time of day, map, player locations
• Organizing states into sub-states can make memory
  management automatic and efficient, and can
  increase performance

59
Using Sub-States

• DXFramework has one example of sub-states, the
  Pong example
• See section 2.1 in the manual for details

60
(No Transcript)
61
Miscellaneous Topics

• Tools File
• TCHARs and Unicode
• Custom VECTOR Classes
• Other included user interface classes
• Memory leaks
• Doxygen Documentation
• Links to resources

62
Tools File

• A collection of useful functions, macros, and
  classes that assist in programming and debugging
• Includes conversion functions from strings to
  numbers and vice versa

63
TCHARs and Unicode

• TCHAR is Microsofts solution to Unicode
  portability
• If the symbol UNICODE is defined, TCHARs are 16
  bit chars (type wchar_t)
• Otherwise, TCHARs are 8 bit chars (type char)

64
TCHARs and Unicode

• Wrap all character strings with the macro _T()
  and the compiler will use wchar_t if Unicode is
  defined and char if not
• Look through engine code for examples
• Also use tstring STL class instead of string
• tstring is basic_string

65
TCHARs and Unicode

• DXFramework supports unicode in theory, but it
  has not been tested
• (and is said to not work )
• 0.9.2
• If this is all confusing to you, simply comment
  out the UNICODE symbol in globals.h and it will
  be business as usual
• If you do this, whenever you see tchar its
  simply a char, and all of the _T() macros are
  null and do not do anything

66
Custom VECTOR Classes

• VECTOR2 and VECTOR3 are custom 2D and 3D vector
  classes
• Much useful functionality
• Similar to DirectXs D3DXVECTOR classes but with
  custom function definitions and precision
• Can make integer, float, double, and other types
  of vectors

67
Other User Interface Classes

• DropDownMenu, ScrollBar, and TextInputBox were
  all contributed by a third party
• There is no demo for them (yet)
• Documentation is limited
• Feel free to use them if you can figure them out

68
Memory Leaks

• DXFramework utilizes a memory leak debugging
  facility provided by the .NET (and possibly 6.0)
  compiler
• Check out section 2.9 in the manual for details
• Known memory leaks in md3 and bsp demos (fix them
  for me!!)

69
Doxygen Documentation

• The funny looking comments cluttering the header
  files (and some of the source files) are plumbing
  for the Doxygen documentation
• Use the generated documentation (available on
  both sourceforge and winter) as much detail is
  revealed there

70
DXFramework Networking

• Radically changed for next release, use anonymous
  CVS to get the new code in the interim
• Severed Pong class completely out of networking
  engine, net class now abstract base class that
  does not have to be modified to use

71
Networking with DirectPlay

• Networking is hard, especially real-time
  applications (i.e. most games)
• Get a multiplayer game programming book
• Take a networking course (preferably with Sugih
  Jamin)
• DirectPlay deals with the socket level
• DirectPlay apps simply pass messages
• Messages are guaranteed to arrive in order

72
Networking with DirectPlay

• DirectPlay lets you network without threads
• Threads are handled internally by DirectPlay
• Not using threads with networking is bad
• DirectPlay uses message handler
• Handler similar to WinProc() called by DirectPlay
  thread when some networking event happens

73
DXFramework Networking

• Create net class
• Automatically created with 0.9.2
• You need to inherit it and create it with 0.9.3
• Start() networking
• Initializes state, doesnt connect or listen
• Host() or Join()
• Pass target IP or hostname to join command
• Handle messages (the hard part)
• Stop() to disconnect

74
Sending Messages

• Use Send() command
• Pointer to array of bytes
• Buffer length
• Many different ways to do this
• One way marshall packets

75
Receiving Messages

• Message handler is called from a thread
• Must use thread synchronization mechanisms!
• Easy mutexes in Win32
• CRITICAL_SECTION
• InitializeCriticalSection()
• EnterCriticalSection()
• LeaveCriticalSection()
• DeleteCriticalSection()

76
DXFramework Networking

• STL queues are very useful
• Check out pong for an example
• AVOID memory copies
• memcpy()
• CopyMemory()
• Instead, use the stack (declare local variables)
• The stack is much faster

77
DXFramework Networking

• Much power of DirectPlay is not taken advantage
  of
• Lobbies
• Grouping
• Player names
• etc.
• Feel free to implement it )

78
Resources

• DXFramework home
• http//dxframework.sourceforge.net/
• DXFramework news
• https//sourceforge.net/projects/dxframework/
• Read and post questions here
• https//sourceforge.net/forum/forum.php?forum_id3
  08719
• Download
• https//sourceforge.net/project/showfiles.php?grou
  p_id54927
• Local http//winter.eecs.umich.edu/eecs-494/

79
Resources

• Microsoft DirectX
• http//www.microsoft.com/downloads/details.aspx?Fa
  milyID1d97f320-9dfd-4e7a-b947-3a037ccf84afdispla
  ylangen
• Doxygen
• http//www.stack.nl/dimitri/doxygen/
• Font used in main menu
• Gorilla Milkshake http//www.blambot.com/title2.
  html