PyOgre Tutorial1        

PyOgre Tutorial 01

Welcome to the very first PyOgre example.

Don't forget to install prior to starting the example listed below:


Tutorial01.JPG

Application framework

First of all, we need to setup some python framework lines for the pyogre application. The framework has to setup the main-loop and define a class, that is derived from an ogre sampleframework application class.

Preparation

First, you should install Python2.4, psyco, PyOgre and also download the media package and unzip the media package to the directory, where your python file Tutorial01.py will be created during the next steps. The media files have to be relative to the directory of your python file Tutorial01.py. Next, you should copy all dll's and cfg-files from the PyOgre installation folder (C:\Python24\lib\site-packages\pyogre) to the folder where your Tutorial01.py file is located - e.g. C:\Python24\pyogre\tutorial01. (You won't need them during this exercise, but if you will go further with creating an executable with py2exe, it is good use to have all assets available from the very start.)

import statements

PyOgre is installed in C:\Pyton24\lib\site-packages\pyogre. The modules have to be imported first using this import stamements.

import pyogre.ogre as ogre   <<<<<--- This imports accesses ''C:\Python24\lib\site-packages\pyogre''
 import SampleFramework as sf <<<<<--- This import accesses local file at ''C:\Python24\pyogre\demos''
application class



Next on the list is the definition of a framework class, that can handle events.
The _createScene method is invoked when the application is instantiated (i.e. at the start of the application).

class Tutorial01(sf.Application):
    def _createScene(self):
        [...]
Main



This is the application main loop that starts der pyogre application.

if __name__ == '__main__':
    application = Tutorial01()
    application.go()

scene creation


scene Manager

Every application has its scene manager (handler for the objects to be painted and drawn).

mSceneMgr = self.sceneManager
light



Now we add an ambient light to the sceen, giving it some bright colour (RGB = 0.7, 0.7, 0.7))

mSceneMgr.ambientLight = 0.7, 0.7, 0.7
robot entity



Now we create the first entity. We load the mesh of a robot from the file system. You can find some examples for meshes, textures and particles in the media folder, which comes with the additional media package of the binary PyOgre distribution. Models are located at C:\Python24\pyogre\demos\media\models: There you find the robot.mesh file. Please don't forget to copy the media folder to the folder, where your python program is located, since all file access is done relative to the current directory.

ent1 = mSceneMgr.createEntity( "Robot", "robot.mesh" );  <<<<--- file is found relative to the ''Tutorial01.py'' => ''...\media\models\robot.mesh''
robot texture



Now we add a texture to the entity (i.e. robot.mesh). The picture of the texture is not referenced directly. Ogre is able to make complex textures, by defining, how a texture is to be used by PyOgre. Texture descriptions are located inside the text file C:\Python24\pyogre\demos\media\materials\scripts\Example.material. The file Example.material describes, what picture file to use and what techniques to switch on or off (explanation of the file is at the end of this article).
For now, we just tell the engine, what texture description we want to use with that Robot.

ent1.setMaterialName('Examples/RustySteel')
create node



Until now, we only created the object inside the memory, but we wont see it on the graphic output. First we have to "mount" the robot to the scene. But before we do that, we have to create a node, where we can attach the robot.

node1 = mSceneMgr.rootSceneNode.createChildSceneNode( "RobotNode" );
attach robot to the node



Now we attach the robot entity to the scene node.

node1.attachObject( ent1 );
SkyDome



Just like the media packaged robot, we find a cloudy sky inside the media folder. We tell the engine to span a sky dome over the scene.

mSceneMgr.setSkyDome(True, 'Examples/CloudySky', 4.0, 8.0)
camera



Similar to the entity, we create a cameraNode and attach the application's standard camera to it.

cameraNode = mSceneMgr.rootSceneNode.createChildSceneNode()
       cameraNode.attachObject(self.camera)

That's it !

The Tutorial01 application

This is the source, we have worked out so far.

import pyogre.ogre as ogre
 import SampleFramework as sf
 
 class Tutorial01(sf.Application):
    def _createScene(self):
        mSceneMgr = self.sceneManager
        mSceneMgr.ambientLight = 0.7, 0.7, 0.7
 
        ent1 = mSceneMgr.createEntity( "Robot", "robot.mesh" );
        ent1.setMaterialName('Examples/RustySteel')        
        node1 = mSceneMgr.rootSceneNode.createChildSceneNode( "RobotNode" );
        node1.attachObject( ent1 );
 
        mSceneMgr.setSkyDome(True, 'Examples/CloudySky', 4.0, 8.0)
 
        self.camera.setAutoTracking(True, node1)
 
        cameraNode = mSceneMgr.rootSceneNode.createChildSceneNode()
        cameraNode.attachObject(self.camera)
 
 if __name__ == '__main__':
    application = Tutorial01()
    application.go()
material Examples/RustySteel



Have a look inside the text file C:\Python24\pyogre\demos\media\materials\scripts\Example.material. There you find the definition of the textures.

material Examples/RustySteel
 {
     technique
     {
         pass
         {
 
             texture_unit
             {
                 texture RustySteel.jpg        <<<<<----- points to the texture located at ''C:\Python24\pyogre\demos\media\materials\textures''
             }
         }
     }
 }

Preview: Frame Listener



Finally, frame listeners. If you start the Tutorial01.py, you can use mouse and keyboard to move around. This is done be the built in FrameListener _createFrameListener (thanks to sampleframwork.py (!).

What are frame listeners?
Basically, a frame listener is an object that allows you to update your world. It has two methods that are called for every frame rendered (a 3D application is just an animation - the engine renders a bunch of frames on the fly and strings them together for you, creating the illusion of motion), frameStarted and frameEnded. frameStarted it called when frame rendering begins. frameEnded is, you guessed it, called after frame rendering ends. You can use these objects and methods to interact with your world.

OGRE/PyOgre provides a basic frame listener called ExampleFrameListener, whose purpose is to allow you to move around in the world. For every frame, it monitors mouse input and keyboard input, and will allow you to make changes to the world accordingly. Primarily, it moves the camera around. When you move the mouse, it determines how to swing the camera so you can "mouselook". When you press keys, it determines what to do with those keypresses (Think of an FPS game). I'm aware that this probably makes little sense, but it will become rapidly apparent as you begin using them. Frame listeners will be used for much more than moving the camera around, however. Think of them as being the main game loop. Once the game is running, you perform any and all operations that you wish to affect the world with in frame listeners. If you would like, open up _createFrameListener (in sampleframwork.py) and browse through it. It's fairly self-explanatory, assuming you know some basic 3D math, and should give you a feel of how they work. Just remember that frameStarted and frameEnded are your primary concerns there.