Getting Started With Visual C# .NET

Estimated Time to Complete: 10 - 15 Minutes

Difficulty Level : Beginner

Notice: This tutorial assumes that you have a basic level of knowledge in Visual C# .NET, and are able to do some programming in it. If you do not have a basic level of experience in C#.NET, we highly recommend that you spend some time learning the language before embarking on 3d programming. A good introductory level set of tutorials can be found at C# Station.

This tutorial has been created using Visual Studio 2008. Generally it is considered advisable to use the latest version of Visual Studio, A free Express version of Visual Studio 2008 can be downloaded from the Visual Studio Express 2008 site

Objective of this tutorial

This tutorial will cover the step-by-step processing of creating a simple first program with TrueVision3D. The finished files are available here for your reference.

By the end of this tutorial you will be able to:-

  • Create a new Truevision3D application.
  • Reference the Truevision3D Library in your application.
  • Initialise the Main Engine.
  • Initialise the Input Engine.
  • Create the application loop.
  • Render to screen.
  • Respond to keyboard events.
  • Write text to the screen.

Getting Started

If you have not already done so download and install a copy of the Truevision3D SDK from here

Open Visual Studio and create a new project from the File→New→Project menu option and create a new Windows Form Application.

I am going to call my application “MyFirstTV3DApplication” you can edit this to your personal preference.

The next stage is to add a reference to the Truevision3D library, if you have followed the default installation of the Truevision3D SDK you will find the library to reference in C:\Program Files\TV3D SDK 6.5\sdk\dotnet.

You can add a reference two ways in Visual Studio either click Project→Add References or right click on References in your Solution Explorer and select Add References, i would personally recommend that you get in the habit of using the second method as this becomes less confusing when running multiple projects in one solution.

Navigate to your library folder and add a reference to MTV3D65

Creating the Engine

Before we do anything you program needs to know that it can use the TV3D6D namespace to do this right click on Form1.cs in your solution explorer and select view code add the following line of code after the line “using System.Windows.Forms;” to you code.

using MTV3D65;

The namespace declaration, using MTV3D65;, indicates that you are referencing the Truevision3d 6.5 namespace. Namespaces contain groups of code that can be called upon by C# programs. With the using MTV3D65; declaration, you are telling your program that it can reference the code in the namespace without pre-pending the word MTV3D65 to every reference.

The complete code should now read

using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Linq;
using System.Text;
using System.Windows.Forms;
using MTV3D65;
 
namespace MyFirstTV3DApplication
{
    public partial class Form1 : Form
    {
        public Form1()
        {
            InitializeComponent();
        }
    }
}

The next stage is to create some class level variables which will hold the references to the Truevision3D Base Engine and Input Engine. Add the following variables to your class level declaration area.

        private TVEngine _myTVEngine;
        private TVInputEngine _myTVInputEngine;

Your Form1 class should now look like this:-

    public partial class Form1 : Form
    {
        //private variable to hold the instance of TVEngine.
        private TVEngine _myTVEngine;
 
        //private variavle to hold the instance of TVInputEngine.
        private TVInputEngine _myTVInputEngine;
 
        public Form1()
        {
            InitializeComponent();
        }
    }

Now we have the variables to use we must create an instance of the TVEngine and TVInputEngine objects so that we can work with them going forward.

As we have created the variables at the class level the once the objects have been created they will be available anywhere within the class.

The best place to create the objects is when the form first loads in order to do this we need a Form_Load method to be created the most simple way of doing this is by clicking the “Form1.cs [Design]” tab at the top of Visual Studio and double clicking the title bar of you new window in the designer. This will automagically create a new Form1_Load method and switch back to code view for you.

Firstly we need to create and initialise the Engine object this is done by using the following lines of code.

            _myTVEngine = new TVEngine();
            _myTVEngine.Init3DWindowed(Handle);

The first line creates the object and the second line initialises it. The parameter Handle refers to the forms Handle which is a unique reference to your form and provides information to the main engine of what it is using for the application.

Next we need to create and initialise the InputEngine object this is done by using the following lines of code.

            _myTVInputEngine = new TVInputEngine();
            _myTVInputEngine.Initialize(true,true);

The first line creates the object and the second line initialises it. The parameters true,true stipulates that we want to intialise both the keyboard and the mouse, it is not compulsory to have both but for this tutorial we will keep both as true.

Your Form1_Load method should now read:-

        private void Form1_Load(object sender, EventArgs e)
        {
 
            //Create and Initialise TVEngine Object
            _myTVEngine = new TVEngine();
            _myTVEngine.Init3DWindowed(Handle);
 
            //Create and Initialise InputEngine Object
            _myTVInputEngine = new TVInputEngine();
            _myTVInputEngine.Initialize(true,true);
 
        }

The Main Loop

Every game consists of a sequence of getting user input, updating the game state, handling AI, playing music and sound effects, and displaying the game. This sequence is handled through the main loop.

During the next part of the tutorial we will be creating the main loop, the main loop in essence is nothing more than a while statement, however for this to function properly we need to know if the loop is still required. To do this add the following variable to the class level declaration.

private bool _isRunning;

Next we need to create our main loop method so lets add the following code under your Form1_Load method.

        private void MainLoop()
        {
            
        }

And now we need to create the actual loop. The loop needs to run indefenitly until the _isRunning variable is false so lets add the following code to your MainLoop method.

            _isRunning = true;
 
            while (_isRunning)
            {
                
            }
 

It is okay to set _isRunning to true in the MainLoop method as we will only be calling this method once in our application.

So we have our main loop now the next stage is to start putting the engine to work at its most basic level the engine needs to perform two functions in each loop, clear what was rendered in the last iteration of the loop and render what is required in this iteration of the loop. Lets add the following lines of code inside our while loop to achieve this.

_myTVEngine.Clear();
_myTVEngine.RenderToScreen();

Now as we have said previously this loop will run indefinitely we must give the user a way of exiting the loop in order to end the application to do this we need to add two sections of code.

The first section checks the InputEngine to determine if the escape key has been pressed and if so sets the _isRunning to false therefore terminating the loop.

                if(_myTVInputEngine.IsKeyPressed(CONST_TV_KEY.TV_KEY_ESCAPE))
                {
                    _isRunning = false;
                }

The second section is used to terminate the application once the loop has been terminated. Place this section after the closing brace of your while loop in the MainLoop method.

Application.Exit();

Okay we are nearly there so lets add a call to MainLoop in order to start our loop and ensure that the form is displayed and has focus.

Show();
Focus();
MainLoop();

Lets have a quick check of our code here is the full code you should have so far.

using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Linq;
using System.Text;
using System.Windows.Forms;
using MTV3D65;
 
namespace MyFirstTV3DApplication
{
    public partial class Form1 : Form
    {
        //private variable to hold the instance of TVEngine.
        private TVEngine _myTVEngine;
 
        //private variavle to hold the instance of TVInputEngine.
        private TVInputEngine _myTVInputEngine;
 
        //boolean to hold if the main loop is still required.
        private bool _isRunning;
 
        public Form1()
        {
            InitializeComponent();
        }
 
        private void Form1_Load(object sender, EventArgs e)
        {
 
            //Create and Initialise TVEngine Object
            _myTVEngine = new TVEngine();
            _myTVEngine.Init3DWindowed(Handle);
 
            //Create and Initialise InputEngine Object
            _myTVInputEngine = new TVInputEngine();
            _myTVInputEngine.Initialize(true,true);
 
            //Display our form
            Show();
 
            //Give our form focus
            Focus();
 
            //Start the Main Loop
            MainLoop();
 
        }
 
        private void MainLoop()
        {
            _isRunning = true;
 
            while (_isRunning)
            {
                //Clear the last iteration of the loop.
                _myTVEngine.Clear();
 
                //check the InputEngine for the escape key
                if(_myTVInputEngine.IsKeyPressed(CONST_TV_KEY.TV_KEY_ESCAPE))
                {
                    //set _isRunning to false to terminate the main loop
                    _isRunning = false;
                }
 
                //Render this iteration of the loop to screen.
                _myTVEngine.RenderToScreen();
            }
 
            Application.Exit();
        }
    }
}
 

If this all looks okay lets press F5 and run our first Truevision3D application. You should have a window that looks like the image below, The label FPS in the top right hand corner refers to frames per second and will vary depending on the system configuration of your machine.

Running this application you may find some odd behaviour if you click off the form into another window this is because the application is only running the loop and not processing any other events for the form. In order to correct this behaviour we need to add a new line of code to tell the application to process its form events add the following code just after the render call.

Application.DoEvents();

This will fix the odd behaviour of the form allowing it to process other events such as the forms redraw event when regaining focus.

Hello World

Time to achieve our final objective from this tutorial and draw some text to the screen in a traditional format for your first program we are going to render the string “Hello World...” to the screen.

Firstly we need to add a new class level variable to hold the TVScreen2DText object. Add the following code to your class level declarations.

private TVScreen2DText _myTVScreen2DText;

Now in our Form_Load method we need to create the object TVScreen2DText is different from the previous Truevision3D objects we have used in that it does not require intialising before we use it. So after the TVInputEngine initialisation add the the following line of code.

_myTVScreen2DText = new TVScreen2DText();

Now its time to add our text to the screen this is quite simple add the following line of code between your engine clear and engine render calls.

_myTVScreen2DText.NormalFont_DrawText("Hello World...", 50, 50, -16710933);

This tells the engine to draw the string “Hello World...” 50 pixels from the left and 50 pixels from the top using the colour blue which is represented by the integer -16710933.

And Finally

If you are anything like me you have been conditioned to close an application by using the close button at the top of the form, you would have noticed that doing this causes the application to continue in debug mode, which is a bit annoying so lets add some code to tidy this up.

Click on the “Form 1 [Design]” tab at the top of Visual Studio and click on the properties panel. At the top of this panel look for the button and select it. This will display the forms events.

Look for the FormClosing event and double click the empty space next to it. Again this will automagically create a new method called Form1_FormClosing and add the following line of code to this new method.

_isRunning = false;

That will fix the annoyance.

Your final code should now look like this.

using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Linq;
using System.Text;
using System.Windows.Forms;
using MTV3D65;
 
namespace MyFirstTV3DApplication
{
    public partial class Form1 : Form
    {
        //private variable to hold the instance of TVEngine.
        private TVEngine _myTVEngine;
 
        //private variable to hold the instance of TVInputEngine.
        private TVInputEngine _myTVInputEngine;
 
        //private variable to hold the instance of TVScreen2DText
        private TVScreen2DText _myTVScreen2DText;
 
        //boolean to hold if the main loop is still required.
        private bool _isRunning;
 
        public Form1()
        {
            InitializeComponent();
        }
 
        private void Form1_Load(object sender, EventArgs e)
        {
 
            //Create and Initialise TVEngine Object
            _myTVEngine = new TVEngine();
            _myTVEngine.Init3DWindowed(Handle);
 
            //Create and Initialise InputEngine Object
            _myTVInputEngine = new TVInputEngine();
            _myTVInputEngine.Initialize(true,true);
 
            //Create a new TVScreen2DText Object
            _myTVScreen2DText = new TVScreen2DText();
 
            //Display our form
            Show();
 
            //Give our form focus
            Focus();
 
            //Start the Main Loop
            MainLoop();
 
        }
 
        private void MainLoop()
        {
            _isRunning = true;
 
            while (_isRunning)
            {
                //Clear the last iteration of the loop.
                _myTVEngine.Clear();
 
                //check the InputEngine for the escape key
                if(_myTVInputEngine.IsKeyPressed(CONST_TV_KEY.TV_KEY_ESCAPE))
                {
                    //set _isRunning to false to terminate the main loop
                    _isRunning = false;
                }
 
                //Add our Hello World text to the application
                _myTVScreen2DText.NormalFont_DrawText("Hello World...", 50, 50, -16710933);
 
                //Render this iteration of the loop to screen.
                _myTVEngine.RenderToScreen();
 
                // do events in the application
                Application.DoEvents();
            }
 
            Application.Exit();
        }
 
        private void Form1_FormClosing(object sender, FormClosingEventArgs e)
        {
           //terminate the main loop
            _isRunning = false;
        }
    }
}

And to finally run your first Truevision3D application press F5 you should see the following displayed.

Well Done!! You have successfully created your first Truevision3D application and this can now be used as a base for your projects going forward. Remember the files from this tutorial can be download from here and any further help you need can be found at the Truevision3D forums or the community IRC channel on irc.Truevision3d.com

Good Luck and Happy Coding.

 
tv3dbeta/getting_started_with_visual_c-sharp.net.txt · Last modified: 2013/11/22 13:31