1. First steps

This part of the manual is intended to initiate you to ZweiDe's basic functionality. It is assumed that you have already installed ZweiDe and are able to create a new ZweiDe project. If this is not the case, you should take a look at the Quickstart section.

Let's create a new ZweiDe project using its "ZweiDe Application" template.

The template includes everything a ZweiDe application needs: The module assemblies, several dlls, some basic code and an embedded key file activating ZweiDe's full version assembly.

The key file is absolutely indispensable; if you try to run a ZweiDe application without having embedded this key file, it is assumed that you haven't bought ZweiDe's full version as this is the only possibility to obtain a key file.

When trying to set up a ZweiDe application without using the template be sure to embed(!!) the key file into your base assembly.

There's also a secondary key which is not embedded but compiled with your code. The file holding it is ZweiDeKey.cs; make sure to compile

this file with your project when setting up a ZweiDe project without using the template.

However, when using the template, you don't have to care for any activation key files or procedures.

Analyzing the sample program

When opening the default code file - Program.cs - this is the code that you should see:

using System;
using System.Collections.Generic;
using System.Text;

using Fetze.Module;
using Fetze.Utility;
using Clr = Fetze.Utility.Color;

namespace ZweiDe_Application
{
	class Program
	{
		static void Main(string[] args)
		{
			ZweiDe.CompiledKey = new ZweiDe.ZweiDeVerifier(ZweiDeKey.ZweiDeKey.VerifyKey);
			ZweiDe.Init
				(
					800,
					600,
					32,
					true,
					1
				);
			Console.WriteLine(ZweiDe.VERSION);

			do
			{
				ZweiDe.Cls();

				ZweiDe.DrawRect
					(
						100.0f + (((float)ZweiDe.MainTimer() * 100.0f) % 500.0f),
						200.0f,
						100.0f,
						100.0f
					);

				ZweiDe.Flip();
				ZweiDe.UpdateKeys();
			}
			while
				(
					!ZweiDe.KeyDown(ZweiDe.KeyID.Escape) &&
					(ZweiDe.GetWindowParam(ZweiDe.WindowParam.Opened) != 0)
				);
		}
	}
}

Let's go through it bit by bit and see what certain parts of it do. We'll skip the obvious and directly take a look at the ones that might be more of a question.


ZweiDe.CompiledKey = new ZweiDe.ZweiDeVerifier(ZweiDeKey.ZweiDeKey.VerifyKey);

The first line sets the ZweiDe reference to your compiled full version key. It always looks the same and you don't have to care for it when using the template. If not, make sure that it is executed before calling the init method.

ZweiDe.Init
	(
		800,
		600,
		32,
		true,
		1
	);

This line of code initializes ZweiDe. It creates a new OpenGL window, does a version check and sets some default values. To do this, it needs you to pass some parameters. If you don't, they will take a default value. These are the parameters that are applied here:

#	Description	Example value
0	The width of the OpenGL window's client area (e.g. the "x-part" of our gfx resolution)	800
1	The height of the OpenGL window's client area (e.g. the "y-part" of our gfx resolution)	600
2	The color depth (in bits) applied to the OpenGL window	32
3	Whether or not the OpenGL window is "fullscreen"	true
4	Buffer swap interval preferences. 0 --> No limit, 1 --> Limited by monitor frequency	1

That's it. The next part of the template program that needs our attention is the "do-while"-loop following ZweiDe initialization.
As long as this "main loop" runs, the application runs also simply because there's always more code to proceed with. When the program ends - which would be the case when leaving the main loop here - the OpenGL context is being shut down either.

We should be able to figure out what exactly our "ending" condition is analyzing the loops continue condition:

while
	(
		!ZweiDe.KeyDown(ZweiDe.KeyID.Escape) &&
		(ZweiDe.GetWindowParam(ZweiDe.WindowParam.Opened) != 0)
	);

It consists of two parts:


!ZweiDe.KeyDown(ZweiDe.KeyID.Escape)

and / "&&"


ZweiDe.GetWindowParam(ZweiDe.WindowParam.Opened) != 0

The first part of the condition is fulfilled as long as the escape key is not pressed; the KeyDown command does nothing but returning whether or not a specified key is pressed.
The second part of the condition is true as long as the OpenGL window is opened which is being checked using the GetWindowParam command. It may also be used to return - for example - whether or not it currently is in user GUI focus.
Both KeyDown and GetWindowParam commands only return precalculated values. To update them, it is neccessary to call UpdateKeys which should be done directly before checking whether or not the OpenGL window is still opened. If the user closes the OpenGL window you will get an exception for any try to access the OpenGL context or relating instances, so you should exit your program flow in time.

So far so good.

I'd suggest to compile and run the template program to try out what we've talked about: Ending the program using both escape key and its windows close button. Before doing that you will see a console window containing some irrKlang messages followed by the ZweiDe version string and also a new OpenGL window boldly amazing you with a white, moving rect on a black background.

Whoa! What a show!

The next step is to find out how this effect is achieved but first there's some OpenGL - and thus ZweiDe - theory. If you already know what double buffering is you may skip the following.

Double buffering

So.. what is double buffering? Double buffering is a technique to make it look like everything on screen is drawn at exactly the same moment although we actually draw all the screen content bit by bit.

The concept is really simple: Imagine two sheets of paper - or two sides of one sheet of paper. One is called the Frontbuffer and the other one is called Backbuffer. Whatever you do, you're always manipulating the Backbuffer while the Frontbuffer remains static: And the Frontbuffer is exactly what applies on the user screen! So, while the user sees a static image we can perform any operation we'd like to without him noticing it!

Now when we're finished constructing the next frame the user shall see, we just switch Front- and Backbuffer...

...and what has been hidden for the user now becomes visible for him on screen. What he has seen the last frame is now under our control, stored inside the Backbuffer. Though that is exactly what we constructed for him the last time.

Back to our sample programs code


ZweiDe.Cls();

Before doing anything else, we just Clear the "screen". Keep in mind: Everything we do takes place on the Backbuffer so we basically clear the Backbuffer here.

ZweiDe.DrawRect
	(
		100.0f + (((float)ZweiDe.MainTimer() * 100.0f) % 500.0f),
		200.0f,
		100.0f,
		100.0f
	);

Now we draw a rectangle (100 x 100 pixels) at a specified position. This position is only fixed in the y-axis; the rects x-coordinate depends on the time that has passed since ZweiDe has been initialized which is returned by the MainTimer command.


ZweiDe.Flip();

Last but not least: Switching Front- and Backbuffer.

Conclusion

You've now learned the basics and you understand what the sample program does. Thats enough to play with some lines of code but far from knowing all the possibilities ZweiDe offers you.
This manuals aim is to change that. You may read it from start to end or just pick out single chapters that seem to be more interesting than others.

Whatever way you choose: Have fun!

<-- Return to the last page

Proceed to the next page -->