From d2c3194bdbf97ab36e88972e17595c107931b07d Mon Sep 17 00:00:00 2001 From: James Turk Date: Mon, 14 Nov 2005 20:02:39 +0000 Subject: [PATCH] added tutorial 01 --- ndoc/Menu.txt | 6 + ndoc/tutorials/tutorial01.txt | 259 ++++++++++++++++++++++++++++++++++ 2 files changed, 265 insertions(+) create mode 100644 ndoc/tutorials/tutorial01.txt diff --git a/ndoc/Menu.txt b/ndoc/Menu.txt index 812b1ac..4af9949 100644 --- a/ndoc/Menu.txt +++ b/ndoc/Menu.txt @@ -83,6 +83,11 @@ Group: photon:: { } # Group: photon:: +Group: Tutorials { + + File: 01 - Getting Started (no auto-title, /home/james/src/photon/ndoc/tutorials/tutorial01.txt) + } # Group: Tutorials + Group: Index { Index: Everything @@ -99,3 +104,4 @@ Group: Index { ##### Do not change or remove these lines. ##### Data: 1(D3333RuEG3lpEG636H93IRutu\38\9oNfG) Data: 1(h3333RuEG3lpEG636H93IRutu\3\fu93Ip`G6) +Data: 1(T3333RuEG3lpEG636H93IRutu\3\fu93tNtuH8po6) diff --git a/ndoc/tutorials/tutorial01.txt b/ndoc/tutorials/tutorial01.txt new file mode 100644 index 0000000..cfdc59e --- /dev/null +++ b/ndoc/tutorials/tutorial01.txt @@ -0,0 +1,259 @@ +Document: Photon Tutorial 01 - Getting Started + +Group: Introduction + +Topic: Before We Start + +This tutorial serves as an introduction to using Photon with C++. It is written +so that those with a moderate amount of C++ experience can follow it and be able +to get started with Photon. This tutorial does *NOT* aim to teach +C++, Game Programming, or how to use every arcane feature available in Photon. +After reading this tutorial, the basic structure of a Photon application should +be understood, and by reading the available +one should be able to start with Photon without much difficulty. + +In addition to having C++ experience, it is assumed that the reader of this +tutorial has already set up Photon and all dependency libraries. For help doing +this look at the page . +You can also ask for help on the Photon mailing lists (). + +Topic: Getting Started +Perhaps the best way to get started it to show what an extremely simple Photon +application looks like. + +(code) +#include +using namespace photon; + +class SomeState : public State +{ +public: + void render() + { + // do any rendering in here + } + + void update() + { + // do any updating of logic in here + } +}; + +int PhotonMain(const StrVec& args) +{ + Application& app(Application::getInstance()); + + app.createDisplay(800,600,32,0,0,false); + + app.setState(); + app.run(); + + return 0; +} +(end) + +Perhaps you can follow the example above fairly well, if so you +probably won't have a tough time picking up Photon as you go. For +those who aren't so sure as to what is going on, fear not, by the end of the +tutorial everything you see will have been addressed. Even if you don't know +what it means, the fact that the above application is all it takes to get +an empty window should indicate Photon really isn't too difficult to use. + +The entrypoint function in any Photon application is a function called +. In order to be as simple to use as possible, Photon +takes care of it's own initialization by defining a main() function that +does all of the work for you. In other libraries you often would write a main +function and fill it with copy & pasted initialization code that doesn't change +from one project to the next, when using Photon you simply create a function +called and everything is taken care of. + +As the entrypoint, is generally where you'll create the display and +set the initial . The state system will be covered in more detail in a +short while. + +One thing you'll notice is that takes something called a , +which is simply a typedef for std::vector. Just like a standard +main() function, it also returns an integer return code which is interpreted +by the operating system as success or failure. + +Group: Digging In: Application and the State system + +Topic: Application +All Photon applications use . Generally Photon applications will +contain code similar to the above example : a display will be created, the state +system will be +initialized, and finally the run method of will be called. We +will now cover exactly what all of this means. + +The first thing you may notice is that is declared as a reference +and accessed in a funny sort of way. is a special kind of class +known as a singleton due to the fact that in any photon application there can +only be one instance. The single instance of Application is +created before any of the code you write is executed, so there is no need to +ever create it. What this means for you is that you cannot write code like: +| Application app; +or +| Application* appPtr = new Application(); + +Instead must always be used via a reference. A reference can +be obtained via Application::getInstance(), which can be called any number of +times, always returning the single instance of . This means that +the following two pieces of code produce identical results: + +(code) +// Sample 1 : Too Much Typing :( +Application::getInstance().createDisplay(800,600,32,0,0,true); +Application::getInstance().setState(); +Application::getInstance().run(); +(end) + + +(code) +// Sample 2 : Preferred +Application& app(Application::getInstance()); +app.createDisplay(800,600,32,0,0,true); +app.setState(); +app.run(); +(end) + + is a fairly important class, it provides the means for managing +the display, input, timer, task and state system. For simple 2D applications +the only thing that needs to be done to configure the display is a single call +to (width, height, depth, 0, 0, fullscreen, title). +The input, timing, and task systems will be addressed in future tutorials, or +check them out in docs. What about the state system? Well that +brings us to our next topic... + +Topic: The State System + are probably the most important entities in Photon. A good portion of +your application's code with be within classes which derive from . Photon +uses the idea that generally a game or application can be derived into a set of +states each of which have their own characteristics and behavior. If you've +ever written a game before you've likely encountered this concept, it is often +solved using a switch statement or something similar. An example of states in +a simple game might be a menu state, a play state, and an options screen state. +Complex games could define a much larger number of states, and it is certainly +possible to only use one state in a photon application. + +Photon's state system is designed to be simple yet powerful, and this tutorial +will only cover the basics of using , however with the available +documentation it isn't hard to do more advanced things with states, a topic that +a future tutorial will cover. + +Creating States: + + is a simple class with a set of virtual functions. In order to define +the behavior of a given state in your application, simply derive from +overloading as few or as many of functions as you desire. The only +function that must be overloaded is , although generally + will be overloaded as well. also has other functions +available allowing for special behavior when a state is paused/resumed or global +input handlers for a state. + +The method and update method are called +regularly in the update and render portions of the state machine +which is the next topic we'll address. + +Running States: + +Once the method is called, it does not return until all + exit. Therefore before it is called it is required that at least one +-derived class is made active using either or +. You'll notice from the example that +these functions both have an odd syntax, they take +a template argument which should be the name of the -derived class, but +they take no formal parameters. The reason for this is an issue of +implementation, and is basically a way of overcoming one of C++'s limitations +(namely that types are not first class entities). + +Group: Wrapping Up + +Topic: Review + +Let's take a look at what we've covered in this tutorial. First let's revisit +the example from earlier and see what it all meant. + +(code) +#include +using namespace photon; + +// State-derived class used for application +class SomeState : public State +{ +public: + void render() + { + // do any rendering in here + } + + void update() + { + // do any updating of logic in here + } +}; + +// the Photon entrypoint, present for all Photon applications +int PhotonMain(const StrVec& args) +{ + // obtain a reference to the Application singleton + Application& app(Application::getInstance()); + + // create the display, in this case a 800x600 window with 32 bit depth + app.createDisplay(800,600,32,0,0,false); + + // set the application state to SomeState (a State-derived class) + app.setState(); + // run the application until the state quits or an exit request is received + app.run(); + + // return 0, just like in a normal application + return 0; +} +(end) + +Hopefully you have a better understanding of what's going on now. The other +tutorials will start assuming a basic understanding of the structure of a Photon +application. + +Topic: Topics Covered + + PhotonMain - The entrypoint for all photon applications. (see ) + Application - Important singleton class used in all Photon applications. + (see ) + Application::createDisplay - Function used to initialize the display. + Application::setState - Function used to set active state. + Application::run - Function called to start processing of active state. + State - Base class for Photon application states, which are vital to + using Photon. (see ) + + +Group: Building a Photon application + +Topic: Compilation +Once you know how to write a basic photon application, you'll need to know how +to compile it in your compiler/build environment of choice. Since I cannot possibly cover +the full range of development environments, I'll speak in general terms and assume +you are familiar with the environment you are using. If you need extra help either +obtain help from a site related to your environment or ask on the Photon mailing +lists. + +Things to do when compiling a photon application: + + - When compiling make sure all includes are in the include path of your compiler. + - When linking make sure all libraries are in the library path of your compiler. + - Ensure that you link against photon and all dependency libraries (photon, + GLFW, OpenAL, OpenGL, GLU, PhysFS, Corona, and Freetype). + - If you are using OpenAL, be sure to define PHOTON_USE_OPENAL + +If you are using a command line compiler (like g++) it will resemble + +| g++ -DPHOTON_USE_OPENAL -c -o test.o test.cpp +| g++ -o test test.o -lphoton -lglfw -lopenal -lGL -lGLU -lphysfs -lcorona -lfreetype + +If you are using an IDE (like Dev-C++, MS Visual C++, or Code::Blocks) you'll +generally only need to specify the libraries you wish to link against. Again, +if you need specific help try asking for help on the Photon mailing lists +(). + +Written for Photon 0.1.0 by James: + $Id: tutorial01.txt,v 1.1 2005/11/14 20:02:39 cozman Exp $