NOGDUS

Articles, Tutorials, and other things. => Pixie Game Programming => Topic started by: Mattias Gustavsson on January 14, 2010, 02:58:45 PM



Title: Pixie - Tutorial 1 - Hello World
Post by: Mattias Gustavsson on January 14, 2010, 02:58:45 PM
Pixie - Tutorial 1 - Hello World

So, it's time to do a first quick run-through of how to use Pixie for something simple, so how about we do the traditional "Hello World" program - just a simple little app which gets the system started and outputs the words "Hello World" onto the screen.

This is a nice way of getting a first feel for how the engine works, while at the same time providing a sort of minimal program, exhibiting the amount of work required to get up and running.

I'll start by throwing out the entire source code listing for the Hello World program, so you can have a first brief glance through it. But don't worry, you're not alone after that: I'll go through the entire program line-by-line, and explain the whats, the whys and the hows of this short little program.

As you might notice, I'm posting the code as a picture - this is so that I will get nice syntax highlighting (for readability) and line numbers (to make it easier to refer to the different lines). Unfortunately, it means that you can't copy the text - but the source code is included in the download linked to further down on this page.

(http://www.colossusentertainment.com/forumref/emotiguy/Nerd.png) (http://www.colossusentertainment.com/forumref/pixie_helloworldcode.png)

So here's what it breaks down to - but I've left out the blank lines, the lines with just comments, and the lines with just braces:

Line 2: This will include the declarations for all of the Pixie engine - this is the only include file you will ever need when working with Pixie, as it in turn includes all the other header files of the engine. You could include each header file individually if you like to, but this way is more convenient.

Line 3: Includes the Windows functionality. The only reason we need to do that is because line 5 makes use of some of the Windows declarations. The file where you declare your WinMain function is the only file where you need to include <windows.h> - everywhere else, you'll be fine with just "Pixie.h"

Line 5: Declares the starting point of the application. The format of this line is entirely decided upon by the Microsoft people, and you just have to have this as your program starting point when you write a Windows program. We can ignore the specifics of it though, as we will just pass its parameters on to Pixie, so we don't have to worry about it.

Line 8: Here, we tell Pixie that we want the engine to use the default initialization process for Windows. What this actually does, is set up things like the input system and graphics/sound systems to make use of their Windows implementation when running our game. This is the last platform specific thing we have to do, after including <windows.h> and declaring WinMain - from this point on, we will only be using platform independent Pixie functions and classes.

Line 11: Pixie is very flexible in its structure, and doesn't enforce a specific way of doing things. To keep that flexibility, it requires quite a lot of setup code to be done when initializing the engine. That's more flexibility than you usually need though, and for most games the setup code looks almost exactly the same. So, to make this process easier, especially for those just starting out, there is a GameHelper class which does all of that tedious setup automatically. We simply declare an instance of GameHelper like this, and pass to it as a parameter the name of our application. This is the name that will be shown in the title bar of our window, in the task manager and when toggling between apps.

Line 14: If you want to display something to the player, you do it on the screen :) Pixie provides a convenient way of accessing the screen and display things on it. You simply create an instance of the Screen class, and tell it what resolution you want to work with. This doesn't mean that it will change the screen resolution or window size though - it is just telling it how big you want your working area to be. In Pixie, the screen resolution is never changed. Instead, the working area is stretched to fit the screen as well as possible. With todays wide range of display technologies, it can be very difficult to find the best resolution to run at, and which best matches your working area - so Pixie doesn't even try, it just silently adapts the image it displays to the available screen area. There are various options that control how this is done though, and you can check the documentation for the Screen class for more information. The important thing to take away here, is that we've just told Pixie that we see the screen as being 640x480 pixels - and to just handle that for us as best as it can.

Line 17: When you make a game, you make it work by updating it many times per second. Each update results in a new "frame" being drawn. To ensure that things in the game move at the same speed on all machines, you measure the time elapsed between each frame update, and use that to decide how far to move things. To make it easier to take that time measurement, Pixie has a FrameTime class, which we can just create an instance of like this, and then use later on (at line 28).

Line 20: Pixie has a quite advanced sprite system. With sprites, I mean it in the traditional videogame meaning of the word - things that move around on the screen. But Pixie doesn't have any limitations on how big a sprite can be, or how many you can have. It even has different types of sprites, not just ones that display an image, but also ones that display text or basic geometric shapes. And maybe the best thing is, that even if it is advanced in that it has a lot of functionality, it is very simple when it comes to using it. If we want a sprite which can show text on the screen, we just create an instance of the StaticText class like this, and we're all set.

Line 21: And to make this new text-displaying sprite show the desired string of characters, we simple call SetText on the new instance, passing it the desired text string. This is all that is needed to get the words "Hello World" to show up on the screen. Sprites can be manipulated in a lot of ways, and I'll show some of them in future tutorials.

Line 24: Everything is ready to go now, but we can't just let the application exit at this point, as that would mean that we would never get to see the result. As usual when making games, we will run through a main loop, which will update the game over and over again, until the player exits. This line here declares a boolean flag we will use to keep track of whether the game is running or not.

Line 26: And this is the actual loop - it just says to keep going for as long as the flag is set to true.

Line 28: Now we start with the update of a game frame. First, we take a new time measure, and get the time elapsed since the last update, so we can used that when updating all the game elements.

Line 31: Again, we use the GameHelper to make our lives easier. It will make sure all of Pixie's systems are updated properly. If you prefer, you can do this yourself, to exactly control how everything is done - just have a look in the GameHelper implementation to see what it does. But for most cases, you should be ok to just use the GameHelper.

Line 34: We're almost done now, but first we should make sure that there's an easy way to exit the application. This line just checks with Pixie's input system, to see if the user have just pressed the Esc key.

Line 36: If the Esc key was pressed, we just change our flag to false to indicate that we don't want the game to keep running. This means that next time the program gets to line 26, it will break out of the while-loop, and proceed to line 40.

Line 40: Now we're done. We just exit the application with a "no-errors" return code, and that's it.



So, not a whole lot of code here, but then it doesn't do much either - just display the words Hello World in white on a black background - but it is a good example of a very basic Pixie program, and we will build on this in future tutorials, to make something much more fancy. Next time, we'll look at getting a bouncing ball on the screen.

To try this out for yourself, download the most recent version of Pixie, including the source code for this Hello World tutorial:

Download Pixie v0.9c (http://www.colossusentertainment.com/forumref/Pixie_0_9c.zip)

Note: In order for you to compile the engine and the sample, you must have Visual Studio installed, and also the DirectX SDK, and you must point Visual Studio to the DirectX SDK location. I will write up a tutorial about how to do that too, but it will probably be a couple of days, so feel free to ask here if you're having problems with it

I hope you enjoyed this tutorial - but I'd love to hear what you think of it, whether you liked it or not. And if you think there's something that needs improving in Pixie, or have any other comments about it, I'm all ears :)


Title: Re: Pixie - Hello World
Post by: Mattias Gustavsson on January 15, 2010, 04:50:13 AM
Update: Unfortunately, there was a couple of minor errors in v0.9 of Pixie, which only came up when building it in Visual Studio Express 2008 (and not in my version of Visual Studio). It's fixed now, and I've updated the download link above. But here it is again anyway  8)

Download Pixie v0.9c (http://www.colossusentertainment.com/forumref/Pixie_0_9c.zip)


Title: Re: Pixie - Tutorial 1 - Hello World
Post by: RedSlash on January 18, 2010, 09:53:34 PM
Is Pixie cross platform?


Title: Re: Pixie - Tutorial 1 - Hello World
Post by: Mattias Gustavsson on January 19, 2010, 01:39:40 AM
No, unfortunately not yet  :'(  I've started looking at porting to linux, but it's been delayed by me moving (back to the UK, yay!). I'll continue on it once I'm settled in over there though :-) At some point, I'd like to make a OsX version to, but need to get myself a Mac first :P

Anyway, there's not that much code that is platform specific (it's all software rendering, for example), so shouldn't be too hard to port, once I get started on it. I'll let you guys know.


Title: Re: Pixie - Tutorial 1 - Hello World
Post by: RedSlash on January 19, 2010, 02:07:55 AM
Hmm.. too bad. But in any case, nice tutorials! I really like the line by line explanation of the code, you do a pretty good job at it. I wish I could explain myself like this sometimes.


Title: Re: Pixie - Tutorial 1 - Hello World
Post by: jonaSoft on April 29, 2010, 11:31:03 PM
Hi so far I liked the design of pixiel, I was testing, but all I get full screen and not get a smaller screen as what is in the documentation.

SetWindowSize void (int width, int height)

I wanted to get a screen of 400 * 300.

SetWindowSize(400,300);

The other thing I wanted to know, because I do not see this issue within the subject of game programming?


Title: Re: Pixie - Tutorial 1 - Hello World
Post by: Richard Marks on April 30, 2010, 12:16:05 AM
Mattias explained it already.

Quote
Line 14: If you want to display something to the player, you do it on the screen Smiley Pixie provides a convenient way of accessing the screen and display things on it. You simply create an instance of the Screen class, and tell it what resolution you want to work with. This doesn't mean that it will change the screen resolution or window size though - it is just telling it how big you want your working area to be. In Pixie, the screen resolution is never changed. Instead, the working area is stretched to fit the screen as well as possible. With todays wide range of display technologies, it can be very difficult to find the best resolution to run at, and which best matches your working area - so Pixie doesn't even try, it just silently adapts the image it displays to the available screen area. There are various options that control how this is done though, and you can check the documentation for the Screen class for more information. The important thing to take away here, is that we've just told Pixie that we see the screen as being 640x480 pixels - and to just handle that for us as best as it can.

If you want a smaller screen and not full screen, then you need to execute your game with the command line parameter -window

Pixie always runs in full screen by default.


Title: Re: Pixie - Tutorial 1 - Hello World
Post by: Mattias Gustavsson on April 30, 2010, 01:23:22 PM
Richard is right, Pixie runs in fullscreen by default, and you can always specify -window on the command line to make it default to windowed mode.

You can also call Screen::SetFullscreen to switch between windowed and fullscreen mode at any time - and when it switches to windowed, it will use the size you passed to Screen::SetSize. The Screen object is basically just a wrapper for Platform_Screen, so the SetFullscreen call is passed on to Platform_Screen, and you can read a bit more about how it works here (http://pixieuniversity.com/pixiedocs/class_platform___screen.php#dd03796263b9c5b581594d7e46db1593).

As for your other question, I'm not sure I understand what you want to know. Do you wonder about how to use Pixie to make games? If so, you can download the source code to the example games here: http://pixieuniversity.com/downloads.php