The program we created was built off one of our previous projects (see World Mapper parts 1,2,3) and, as always, the XNA framework. This project turned out to be much more complex than any of our previous programs so it would be impossible to cover all the source code in detail. Instead, this post will provide an overview of the program’s structure and then provide the source code for you to download and explore on your own.

Program Structure

Below is a graphic of all the classes used in the program with our main class named WorldMapper.cs.

We designed three classes to handle the maps tiles – a TileMap, TileSet, and Tile class. The main program only interacts with the TileMap class and the creation of TileSets and Tiles is done automatically.

We also needed a separate class to keep track of where the user is looking on the map. This concept of a “viewport” or “camera” is commonly used in game programming so the program knows which tiles need to be drawn on-screen. It also tracks which TileSet the user is viewing. The class was named GeoCamera2D and contains methods to pan, zoom, and recenter the map. Remembering the discussion in the last post on tile coordinates versus geographic coordinates, our camera stores all it’s location information in tile coordinates like 0,0 or 2.4, 1.3 and relies on the current TileSet class to convert the location to longitude/latitude coordinates when needed.

Both the Keyboard and Mouse classes have been covered in previous posts so we will skip those now. Some of the code was updated but the main functionality remained the same.

C# Programming

Our map tilling program follows the standard XNA structure but with the addition of our tile mapping classes. Some of the source code is covered below.

We first create several variables to store our new classes and constants to define some pixel parameters:

shTileMap _tileMap;
shGeoCamera2D _camera2D;

const int _mapWidth = 800;
const int _mapHeight = 400;

const int _tileWidth = 800;
const int _tileHeight = 400;

In the constructor, we initiate our TileMap class with some general information, including the extent of the entire map (in this case, the entire world). The camera class is also initiated:

_tileMap = new shTileMap("WorldMap", _tileWidth, _tileHeight, -180, -90, 180, 90);
_camera2D = new shGeoCamera2D(_mapWidth, _mapHeight, _tileWidth, _tileHeight);

Next we have to define each of our three TileSets (see part 2 for more information). We first use the AddTileSet method to create a new TileSet with information on it’s zoom level (0), and tile coordinate extent (0,0 to 1,1).

//--> setup TileSet 0
shTileSet newTileSet = _tileMap.AddTileSet(0, 0, 0, 1, 1, _graphics.GraphicsDevice);

We then have to define some conversion parameters (see part 3) to enable the TileSet to convert between tile coordinates and geographic coordinates.

newTileSet.DefineConversionParameters(new Vector2(-180, -90), 360, 180);

We repeat the TileSet creation twice more for the other TileSets.

In the Update method, we check for mouse and keyboard clicks. A mouse click simply shows the user the geographic coordinates of where they clicked on the map.

// check if a mouse click has occured
_mouse.Update();
if (_mouse.LeftButton == ButtonState.Pressed)
{
    //--> convert click position to grid position
    Vector2 gridPos = _camera2D.ConvertScreenPos2GridPos(_mouse.X, _mouse.Y);

    //--> convert grid position to real world position
    Vector2 realPos = _tileMap.ActiveTileSet.ConvertGridPos2RealPos(gridPos.X, gridPos.Y);

    //--> update last click position for display on-screen
    _lastClickPos = realPos;
}

Arrow keys will pan around the map, the Z key zooms in, and the X key zooms out. One of the keyboard checks looks like this:

// check if a key has been pressed
_keyboard.Update(gameTime);
if (_keyboard.IsNewKeyDown(Keys.Left))
{
    _camera2D.PanLeft(_tileMap.ActiveTileSet.MinCol);
}

Every time a pan occurs, we send as a parameter the boundary being approached by the pan to ensure the user can’t go outside the bounding box of the map.

Finally, in the Draw method, displaying the map takes only one line:

_tileMap.Draw(_spriteBatch, _camera2D);

Conclusion

The code involved in this project is rather complex and represents only one approach to making a tile-based mapping program. The objective was to create a framework that could easily be applied to other TileMaps of different sizes, extents, and tile counts. There are aspects of the program that would need to be addressed though before it succeeded in that respect. For example, our program pre-loads all 22 map tiles for convenience but this wouldn’t be practical for a TileMap that has hundreds of tiles. Some form of a “tile cache” would need to be implemented that only loaded and stored tiles within the user’s view.

The source code and compiled program are available to download below. The source code requires the XNA Game Studio Express and the program download requires at minimum the XNA runtime redistributable to run.

protected override void Update(GameTime gameTime)
{
    // check if a mouse click has occured
    mouse.Update();
    if (mouse.LeftButton == ButtonState.Pressed)
    {
        mapserver.ZoomMap(1, mouse.X, mouse.Y);
    }

    // check if a key has been pressed
    KeyboardState keyState = Keyboard.GetState();
    if (keyState.IsKeyDown(Keys.F))
    {
        graphics.ToggleFullScreen();
    }
    else if (keyState.IsKeyDown(Keys.Z))
    {
        mapserver.ZoomMap(2, mapserver.MapPixelCenter.X,
                      mapserver.MapPixelCenter.Y);
    }
    else if (keyState.IsKeyDown(Keys.X))
    {
        mapserver.ZoomMap(-2, mapserver.MapPixelCenter.X,
                      mapserver.MapPixelCenter.Y);
    }
    else if (keyState.IsKeyDown(Keys.C))
    {
        mapserver.ZoomMapFullExtent();
    }
    else if (keyState.IsKeyDown(Keys.Escape))
        this.Exit();

    // check if a new mapserver image needs to be generated
    if (mapserver.RefreshMap)
    {
        mapserver.UpdateMap(graphics.GraphicsDevice);
    }

    base.Update(gameTime);
}

Each option relies on our MapserverXNA class discussed in the last post. Since all the functionality is hidden within this class, coding our main program is very straightforward. Additionally, zooming in and out is performed with the help of our Image Swapping class we created in a previous post. This adds a fading in/out effect but none of this code is even visible in the main program.

As shown above, a mouse click invokes a pan of the map (click here for more information on zooming and panning with Mapscript). The mouse’s X/Y click coordinates will become the new center of the map. Within the MapserverXNA class, we added a shift effect when a pan occurs using the previously mentioned Image Swapping class. Upon the mouse click, the existing image is shifted and then the new image then just replaces it. This sliding effect is an alternative to the fading effect used for zooming b/c it wouldn’t make sense to pan the map and then fade in the new image.

The last portion of code added is in the draw method. Here we draw our map image, mouse cursor, and some text.

protected override void Draw(GameTime gameTime)
{
    graphics.GraphicsDevice.Clear(Color.White);
    spriteBatch.Begin(SpriteBlendMode.AlphaBlend);

    mapserver.DrawMap(spriteBatch, gameTime);

    mouse.Draw(spriteBatch);

    spriteBatch.DrawString(font, "Z = Zoom in", new Vector2(5, 4), Color.Black);
    spriteBatch.DrawString(font, "X = Zoom out", new Vector2(5, 16), Color.Black);
    spriteBatch.DrawString(font, "C = Full Extent", new Vector2(5, 28), Color.Black);
    spriteBatch.DrawString(font, "Click to pan", new Vector2(5, 40), Color.Black);

    spriteBatch.End();

    base.Draw(gameTime);
}

Conclusion

This post concludes probably the most complex project we have demonstrated so far. Some of the Mapserver-related code was not discussed because it has been covered in our previous projects (Mapserver – 10 Minute Tutorial, Mapscript Demo). The entire source code for this project is available to download below. The program’s requirements (C#, XNA, Mapserver, and a valid Mapserver map file) have all been discussed in our other projects. Questions and comments are always welcome at james [at] spatialhorizons.com.

MapserverXNA Class

We named the class MapserverXNA and the properties and methods look like this:

The properties include information on the map’s size (height, width, and center), the location of the map file, and a boolean value (RefreshMap) that tracks whether the map needs to be updated.

The methods include the ability to update the map (i.e. generate a new image from Mapserver) and draw the map onscreen. There are also two zoom methods: ZoomMap allows for zooming in, out, and panning while ZoomMapFullExtent returns the map to the full extent.

We won’t discuss in detail the code inside of this class. It is included in the source code download below so you are welcome to take a look yourself.

Using the MapserverXNA Class

The next step is to setup a XNA program to use the newly designed class. We could start from scratch but instead this project will loosely build off the structure of World Mapper project from a while back. It does follow the standard form of a XNA game application as discussed in a previous post. We also incorporated what we learned in our Mapscript Demo and our post on XNA font.

With our XNA game program setup, we added several more fields (private variables) to the main game class:

GraphicsDeviceManager graphics;
ContentManager content;
SpriteBatch spriteBatch;
shMouse mouse;
shMapserver mapserver;
SpriteFont font;

In the constructor, we then setup our mouse class and initialized the MapserverXNA class with a valid map file string and size in pixels.

public MapscriptXNA()
{
    graphics = new GraphicsDeviceManager(this);
    content = new ContentManager(Services);

    mouse = new shMouse();
    mapserver = new shMapserver(@"C:\ms4w\apps\gmap\htdocs\gmap75.map",
        600, 600);
}

In the initialize method, we resize the screen to match the map size:

protected override void Initialize()
{
    graphics.PreferredBackBufferWidth = mapserver.MapWidth;
    graphics.PreferredBackBufferHeight = mapserver.MapHeight;
    graphics.ApplyChanges();
    base.Initialize();
}

In the load graphics method, we load both the mouse cursor and font from using XNA’s Content Pipeline:

protected override void LoadGraphicsContent(bool loadAllContent)
{
    if (loadAllContent)
    {
        spriteBatch = new SpriteBatch(graphics.GraphicsDevice);
        mouse.Cursor = content.Load(@"Content\Textures\MouseCursor");
        font = content.Load(@"Content\Font\MapFont");
    }
}

We will continue in our next post with the rest of the application’s code but the entire source code can be downloaded below. For new readers, we encourage you to glance over our past projects or read the new FAQs page.

Quick Review

Mapserver is a map-rendering program mainly used for web mapping applications. It can also be used for desktop applications via it’s Mapscript API.

In our previous Mapserver and Mapscript posts, we used a sample dataset of Canada that can be downloaded here. Since it is freely available and easy to use, we will continue to use it in this project. We will cover making your own datasets for Mapserver in a future post.

Adding XNA

We already created a standard forms-based application for interacting with Mapserver. There were some buttons and the map image just switches upon refreshes. If the project were scored on presentation, it would receive low marks. Nothing stands out, the visual aspects are relatively limited and fail to draw the user in. Fortunately XNA, in addition to being a game development platform, also offers a great set of features for producing mapping applications with some graphical enhancements.

Using Mapserver in XNA

It is actually very easy to use Mapserver map images in XNA. Before we begin coding our project, let’s think about the steps needed to do so:

1. Our XNA Program requests a new map image. This request will occur upon startup and any time the user interacts with the map via zooming or panning.
2. Using the Mapscript API, a new map image needs to be generated (see Mapscript Demo 2 for more info). The map image can be returned as a memory stream or saved to a temporary image file in JPEG or PNG format.
3. The XNA program then loads the map image as a 2D texture and displays it on-screen (see XNA and GIS 2 for more info). Our image swapping example shows one way to produce fade in/out transitions we could use when switching map images.

The map image is displayed until another request is made and the process is repeated. Both the speed of Mapserver and XNA enable this process to take less than a second to complete.

We will start coding in our next post and rely on an object oriented design to create a C# class that completes the steps above automatically. Adhering to this type of approach ensures we can easily add Mapserver functionality to other future XNA projects without much hassle. Stay tuned.

Let’s assume that we have a map image already generated by a mapping engine (Mapserver/Mapscript for example).

A user then zooms in on the map and a second image is generated.

Displaying the second image could be as simple as switching between the images. In most desktop applications, each map refresh does just that. Nothing fancy, but when you have a powerful graphical engine at your disposal, there is much more we can do.

Texture Opacity

XNA allows each texture (e.g. map image) to have an opacity (”alpha“) value ranging from 0 (transparent) to 255 (opaque). This gives us the ability to simulate an image fading in or out by quickly changing the alpha value. The texture’s alpha (a) is determined when it is drawn using a sprite batch:

spriteBatch.Draw(texture, rectangle, new Color(r, g, b, a));

Image Swapping Class Design

The first step is to design and program an “image swapping” class that we can use in various applications. This will enable us to easily implement image transitions such as fades or shifts.

The class must accept 2 images, their locations, and how fast the transition will occur. The image fading in is named “InImage” and the image fading out is “OutImage”. After some testing and revisions, our final object model looks like this:

The TransitionType property and SetShiftDestination method will be used in the future for performing an image swap when the map is recentered. It would be unnecessary to fade between 2 images that are at the same scale. Instead, the transition would involve shifting the first image and then the second image immediately replaces the first image.

Using the Image Swap Helper Class

We’ve setup a XNA game application (source code below) that demonstrates how the image swapping class works. It fades between the 2 images shown above. Here is an overview of how the class was implemented in our application.

Create a private variable (”field”) using the object:

shImageSwapHelper _imageSwapper;

Then create a new instance of the class and define a transition time in milliseconds.

_imageSwapper = new shImageSwapHelper();
_imageSwapper.TransitionTime = 5000.0f;

Set the incoming image and outgoing image rectangle sizes. In this scenario, they are both the entire size of the map window so:

_imageSwapper.InRect = new Rectangle(0, 0,
     _mapWidth, _mapHeight);
_imageSwapper.OutRect = new Rectangle(0, 0,
     _mapWidth, _mapHeight);

Load the images into textures from a file name:

_imageSwapper.InImage =
     Texture2D.FromFile(graphics.GraphicsDevice, "Image2.jpg");
_imageSwapper.OutImage =
     Texture2D.FromFile(graphics.GraphicsDevice, "Image1.jpg");

In the Update method, we see if the image transition is occurring. If it isn’t, we start the transition:

if (!_imageSwapper.InProgress)
{
    _imageSwapper.StartTransition();
}

Finally, in the Draw method, our image transition is drawn with one line of code. The individual alpha values of each image are controlled internally by the class.

_imageSwapper.Draw(spritebatch, gameTime);

Upon running the application, the first image will display and over the course of 5000 milliseconds, it will fade out while the second image will fade in. This pattern is repeated until the program is exited.

Conclusion

This is only another building block to our ultimate goal. It does show how easy XNA can be used to improve the graphical quality of an application. As always, the source code is available to download.

Our definition of a console consists of two parts. First is the command prompt line where the user can enter text, press enter, and something occurs if the user enters a valid command. Below that line are past lines of text that the user has typed or it could be used to display information about the program.

Console Object

We first need to design our console object that will be used to store both the input text and the past lines of text for display purposes.

As you can see, we define how many history lines to remember and the pixel height of each line. We also store the prompt symbol (::) separate from the user-inputed text in case we want to change it in our application. The console’s methods includes functions to add text, erase text, clear text, and the actual drawing of the console.

Keyboard Object

Having a console object is only half of the solution. We also need a way to tell the console what text the user is typing and when the user presses keys such as ENTER, SPACE, BACKSPACE, etc. So we decided to create a Keyboard object that will encapsulate code needed to find which key the user pressed.

There is only one public property (LastKeyPressed) and two methods. If you download the source code, you will see that there is also private variable used to store the keyboard state:

KeyboardState keyState;

When either method is called, this keyState is updated just as any other XNA program would do. But since we are creating a console demonstration, we need to convert the pressed key result (Keys.X, Keys.Enter, etc.) to a string so we can add it to our console. For example, if the user presses “S”, we add “S” to the console but if the BACKSPACE key is pressed, we need to remove text from the console. Pressing the space bar should generate a 1 character empty string ” ” to simulate a space. Those examples are why we created a FindPressedKey method.

Using the Objects

We then setup a new XNA game application, add the two new classes for our console and keyboard objects, and develop their code. Following the steps in our last post, we also setup a XNA SpriteFont to store the type of text to be displayed in our console. Using the objects in our main program is fairly easy. Below is a quick summary and the full source code is available below.

Step 1 – Define the classes

shConsole console = new shConsole();
shKeyboard keyboard = new shKeyboard();

Step 2 – Check for pressed keys in the Update function

string keyPress = keyboard.FindPressedKey();
if (keyPress == ">>ESCAPE")
{
  this.Exit();
}
else if (keyPress == ">>ENTER")
{
  if (console.Text == "QUIT") this.Exit();
  console.ClearText();
}
else if (keyPress == ">>BACKSPACE")
{
  console.Backspace(1);
}
else
{
console.AddText(keyPress);
}

Step 3 – Draw the console in the Draw function

console.Draw(spriteBatch, courierNew);

Time Delay

The program runs extremely fast so it could potentially be checking for keyboard presses dozens of times per second. This does create a situation where a single key press by the user is picked up several times by program and consequently the console would show the same letter several times. A simple way to avoid this is to add a slight delay between key presses and that is how our program avoids the duplicate letter effect. After a key press, a 50 millisecond delay is enforced where any subsequent key presses are ignored until the time has passed. This isn’t a perfect solution but does a good enough job for now.

Every XNA game template comes with a GameTime variable already ready to use for both the Update and Draw functions. Finding out how much time has passed since the last frame is easy:

gameTime.ElapsedRealTime.Milliseconds;

To track when a certain time has elapsed, just add a time counter variable:

timeCounter += gameTime.ElapsedRealTime.Milliseconds;

And then use it to avoid performing tasks until an amount if time has pass:

if (timeCounter >= 50)
{
  // do something
  timeCounter = 0;
}

Conclusion

Feel free to download the source code and try it out for yourself. There is a lot of room for improvement but at least we have laid the foundation to include some command-line functionality into our future programs.

Font Preparation

Font is treated similar to any other 2D sprite in XNA except for the source of the texture. Instead of relying on graphics, XNA obtains the font from the font files already installed on your computer. Examples include Times New Roman, Courier New, and Arial.

Preparing to use a font is simple. In any XNA program, right-click in the Solution Explorer and select Add New Item. Scroll to the bottom and select the Sprite Font icon:

This generates a XML configuration file that provides the information that XNA needs to import that font file into the Content Pipeline and thus have the ability to be drawn in the program. For example, to use Courier New font, the first element should be:

<FontName>Courier New</FontName>

Other elements in the XML file that contain information on font size, spacing, and style can be changed accordingly.

Using the Font

Several lines of code need to be added once the configuration file is setup. First define a SpriteFont object:

SpriteFont courierNew;

Then in the LoadGraphicsContent method, create a font object using the asset name of the configuration file:

courierNew = content.Load("Content\\Font\\ConsoleFont");

Finally, use the DrawString method of a SpriteBatch object to draw the font on screen:

spriteBatch.DrawString(courierNew,"Insert Text String", new Vector2(5,5), Color.Red);

There are additional parameters that allow for the text to be rotated or scaled but most of the time we just need a string, the location, and a color.

Next time we will demonstrate a simple application using font. Our focus will be on creating a console-type application that will eventually be part of a larger mapping application.

Resizing the Image

I first created a larger background image (800 pixels x 400) to be used for the rest of this project. Two new variables were added:

int mapWidth = 800;
int mapHeight = 400;

…and used in the Initialize Function:

graphics.PreferredBackBufferWidth = mapWidth;
graphics.PreferredBackBufferHeight = mapHeight;

Mouse Object Creation

As discussed in our previous post, we will now start adding objects in our source code. The simple example shown was that of a Mouse object used to store the mouse’s cursor location and button states. So a new file (shMouse.cs) has been added to the project and used in the code to manage the mouse input.

Full Screen

Another benefit to programming with XNA is how easy it is to switch into full screen mode. I added some code in Update function to switch the program into full screen mode when the F key is pressed:

else if (keyState.IsKeyDown(Keys.F))
{
  graphics.ToggleFullScreen();
}

Pressing F again will switch back to windowed mode. Yes, it is that simple.

Summary

Today’s changes were relatively minimal but did introduce several new concepts that are important to our future objectives. Below is a link to download the updated source code. The download also includes the Mouse object model created using Dia.

For the first time, we’ve added the option to download the source code at the bottom of this page. The primary reason for doing this is because our projects are becoming too complex to list the entire source code in the post itself. Instead, we will now try to highlight only the new and most important code snippets.

Our objective in this project is to rebuild our previous World Mapper project using XNA with some differences. Since official support for text in XNA won’t be available until later this month, the user won’t be available to enter latitude/longitude coordinates. Instead, the mouse can be used to click on the map and add a point. Additionally, by pressing the M key, the program’s mode switches from adding points to deleting points. Clicking on top of an existing point will then remove it from the map.

So let’s begin by creating a new XNA Windows Game as discussed in our previous posts. In our projects, I always first change the default names of files, folders, namespaces, etc. (see the source code for examples of this).

We will use 3 textures in this project: a world map image for the background, a point image, and a delete point image. To add the images to the project, simply right-click in the Solution Explorer and add an existing item. Be sure to set the file type to Content Pipeline Files and then import the images.

The class variables I added for the images look like this:

Texture2D t2dWorldMap;
Texture2D td2Point;
Texture2D td2Delete;

To keep track of the user-added points, I created a List collection of Point variables:

List mapPoints;

In the Initialize function, I resized the window size to match the dimensions of the world map image:

graphics.PreferredBackBufferWidth = 400;
graphics.PreferredBackBufferHeight = 200;
graphics.ApplyChanges();

In the LoadGraphicsContent function, I load the textures into the program using their Content Pipeline names:

t2dWorldMap = content.Load;(@"Content\Textures\WorldMap");
td2Point = content.Load(@"Content\Textures\point");
td2Delete = content.Load(@"Content\Textures\delete");

In the Update function, I check for mouse clicks and keyboard input. If the left mouse button is pressed, a point is either added or deleted depending on the map mode. If the M key is pressed, the mode switches. If the ESC key is pressed, the program ends.

In the Draw function, the textures are drawn in order of lowest to highest on the screen. The background map is drawn first, then any points, and finally the mouse cursor. For example, here is how the points are drawn:

foreach (Point p in mapPoints)
{
  spriteBatch.Draw(td2Point, new Rectangle(p.X - 2, p.Y - 2, 4, 4), Color.White);
}

Again, note how the texture locations are offset by half their size to ensure they are placed at the exact center of the mouse click.

When the user attempts to delete a point, the mouse coordinates are sent to this function and the nearest point within a set tolerance is returned to be removed:

protected Point FindNearestPoint(int x, int y)
{
  int bufferTolerance = 5;
  Point matchPoint = new Point();
  foreach (Point p in mapPoints)
  {
    if ((Math.Abs(p.X - x) <= bufferTolerance) &&
        (Math.Abs(p.Y - y) <= bufferTolerance))
      matchPoint = p;
  }
  return matchPoint;
}

Those are the main points involved in creating this project. Click on the link below to download the source code.