Chapter 1: Getting Started

In this chapter, details on how to install AgateLib and create projects which use AgateLib are described.

Windows - Visual Studio Project Setup - C#

First, for Windows, we recommend that you have a copy of Visual Studio. The express editions can be downloaded for free from Microsoft. This tutorial is specific to Visual C# 2005 Express, but instructions should be very similar for the 2008 version.

Visual C# 2005(8) Express
Start a new project using the "Windows Application" template and save it. AgateLib provides all the functionality necessary for creating windows and drawing to the screen. So you do not need references to many of the default libraries visual studio has.

Take a close look at the solution explorer, expanding any collapsed items (the properties folder can be ignored). Under the reference folder Visual Studio will have automatically added references to System, System.Data, System.Deployment, System.Drawing, System.Windows.Forms, and System.Xml. Delete all of these except System and System.Core (if running on Visual Studio 2008). You may also want to keep System.Xml and System.Xml.Linq if you plan to read/write any XML files. Also delete Form1.cs.

Now you need to add a reference to the AgateLib library. Right click on the References folder in the Solution Explorer and click "Add Reference...", make sure the selected tab is ".NET", and then click the Browse tab. Locate the folder you extracted AgateLib to. If you just want to get on with it, add a reference to AgateLib.dll and AgateOTK.dll, and skip the next section. At some point you should read the page on drivers to get familiar with their requirements.

Visual Studio 2005 contains some nifty features which help you debug applications. Unfortunately, one of these is incompatible with Managed DirectX 1.1, so if you are using AgateMDX instead of AgateOTK we need to disable it. If you are using AgateOTK, skip this step. In the menu bar, go to Debug -> Exceptions. Expand Managed Debugging Assistants. Scroll down to the LoaderLock exception, and uncheck it. Click OK to accept changes. If you skip this step while using AgateMDX, you will notice that the application will get an exception when it starts up. It is important to point out, this is only an issue if you are running your code in the Visual Studio debugger. This is not an issue if you double-click the .exe file outside the debugger, or use CTRL-F5 to run without debugging. It is also not an issue when your game is complete and you wish to send it to other people to play it. Visual Studio is designed so that this is a per-solution setting. So LoaderLock exceptions have to be disabled for every solution with a project using AgateLib and the MDX driver.

Now we are ready to write some code. We will be working with the program.cs file. You may rename it if you wish, by single clicking on it and pressing F2. Double-click program.cs in the Solution Explorer. Visual Studio generated some code which creates a Form from Form1 and shows it. Delete the text in program.cs, and replace it with the following code:

  1. using System;
  2. using System.Collections.Generic;
  3. using AgateLib;
  4. using AgateLib.DisplayLib;
  5. using AgateLib.Geometry;
  6.  
  7. namespace TestAgateLib
  8. {
  9.     class HelloWorldProgram
  10.     {
  11.         /// <summary>
  12.         /// The main entry point for the application.
  13.         /// </summary>
  14.         [STAThread]
  15.         static void Main(string[] args)
  16.         {
  17.             using (AgateSetup setup = new AgateSetup(args))
  18.             {
  19.                 // initialize AgateLib.
  20.                 setup.InitializeAll();
  21.  
  22.                 // if something bad happened, bail out.
  23.                 if (setup.WasCanceled)
  24.                     return;
  25.  
  26.                 // Create a window with resolution 640x480 and title "Hello World"
  27.                 DisplayWindow wind = DisplayWindow.CreateWindowed("Hello World", 640, 480);
  28.  
  29.                 // Run the program while the window is open.
  30.                 while (Display.CurrentWindow.IsClosed == false)
  31.                 {
  32.                     // Display.BeginFrame must be called at the start of every frame,
  33.                     // before rendering takes place.
  34.                     Display.BeginFrame();
  35.  
  36.                     // Clears the display to a nice color.
  37.                     Display.Clear(Color.DarkGreen);
  38.  
  39.                     // End frame must be called after all drawing is finished.
  40.                     Display.EndFrame();
  41.                    
  42.                     // KeepAlive processes events.
  43.                     Core.KeepAlive();
  44.                 }
  45.             }          
  46.         }
  47.     }
  48. }

Linux - Using Monodevelop

To develop with AgateLib on Linux, first you must have Mono installed. You can download Mono from the Mono-Project web site. This includes MonoDevelop, the C# IDE for Linux. Many Linux distributions include a version of mono in their repositories. Check with your distribution to see what package you need to install to get Mono and MonoDevelop. You also need Mono's WinForms implementation.

OpenSUSE 11.1: zypper install mono-complete

Download

Once you have a working copy of Mono, you should download AgateLib version 0.2.5 from the SourceForge site. Extract it to a folder, say ~/Agate.

Creating a Project

Note: These instructions were written for an older version of MonoDevelop. They should still be valid but there may be minor differences.

In MonoDevelop, create a new project (Shift+Ctrl+N) and name it TestAgate. You should be able to pick any language you like, but be sure to pick an Empty Project underneath it. Picking a language other than C# may make the instructions that follow a little different, so you may want to start with C# until you get familiar with how to setup a new project.

Setting the runtime

In order to use AgateLib effectively, you need to be using the .NET 2.0 stack. To make this change, look in the Solution window on the left hand side. There will be a tree there with Solution TestAgate and TestAgate under it. Expand them both. Right click the project (titled TestAgate) and choose Options. In the new window that comes up, underneath General there will be Runtime Options. Click that, and on the right hand side, make sure the runtime version to 2.0 and click Ok.

Adding AgateLib references

Once you have a new project created, look in the Solution window on the left hand side. so that you see the references folder. Right click that folder, and choose Edit References. Pick the tab that is titled .Net Assembly. At the top you will see a file browser. Pick the folder that you extracted AgateLib to, and select all DLL files there. Click Add and then OK to add the references to your project.

Adding Source Code

Now back in the Solution window, we need to add a source code file. Right click on your project (named TestAgate), go down to Add and choose New File.... MonoDevelop will give you several choices on what to add here. You want to click the General category on the left hand side, and then choose Empty File on the right hand side. Name this file TestAgate.cs and click New.

Copy and paste the following code into the TestAgate.cs file.

  1. using System;
  2. using System.Collections.Generic;
  3. using AgateLib;
  4. using AgateLib.DisplayLib;
  5. using AgateLib.Geometry;
  6.  
  7. namespace TestAgateLib
  8. {
  9.     class HelloWorldProgram
  10.     {
  11.         /// <summary>
  12.         /// The main entry point for the application.
  13.         /// </summary>
  14.         [STAThread]
  15.         static void Main(string[] args)
  16.         {
  17.             using (AgateSetup setup = new AgateSetup(args))
  18.             {
  19.                 // initialize AgateLib.
  20.                 setup.InitializeAll();
  21.  
  22.                 // if something bad happened, bail out.
  23.                 if (setup.WasCanceled)
  24.                     return;
  25.  
  26.                 // Create a window with resolution 640x480 and title "Hello World"
  27.                 DisplayWindow wind = DisplayWindow.CreateWindowed("Hello World", 640, 480);
  28.  
  29.                 // Run the program while the window is open.
  30.                 while (Display.CurrentWindow.IsClosed == false)
  31.                 {
  32.                     // Display.BeginFrame must be called at the start of every frame,
  33.                     // before rendering takes place.
  34.                     Display.BeginFrame();
  35.  
  36.                     // Clears the display to a nice color.
  37.                     Display.Clear(Color.DarkGreen);
  38.  
  39.                     // End frame must be called after all drawing is finished.
  40.                     Display.EndFrame();
  41.                    
  42.                     // KeepAlive processes events.
  43.                     Core.KeepAlive();
  44.                 }
  45.             }          
  46.         }
  47.     }
  48. }

Now build and run the application by pressing the F5 key. If you did everything right, then the application should crash with an unhandled exception! Unfortunately, there's one more important step, which should be handled by MonoDevelop but isn't.

== Copying DLL config files ==

If you look inside the directory where you extracted AgateLib (ie. ~/Agate), you should see a file OpenTK.OpenGL.dll.config and a Linux folder. The config file must be manually copied to the same directory as the executable that is produced by the Mono compiler. The Linux folder contains other files that components of AgateLib depend on that are specific to Linux. At the moment, this is only the FMOD library. To use FMOD, these files must also be copied to the same directory as your executable. So open up a terminal window and execute the following two commands:

cp ~/Agate/*.config ~/Projects/TestAgate/TestAgate/bin/Debug
cp ~/Agate/Linux/* ~/Projects/TestAgate/TestAgate/bin/Debug

Note: You may have to change the above lines depending on choices you made previously. If you changed the name of your project from TestAgate, you will have to use your project name. If you didn't choose to make a separate directory for the solution, the target directory structure will be something like ~/Projects/ProjectName/bin/Debug. Also, if you extracted AgateLib to a different directory than ~/Agate, you will need to change that.

Now if you go back to MonoDevelop and push F5 to build and run your project, you should have a window with a "Hello World" title with a green background. Congratulations, you have just written your first application using AgateLib!