OpenSceneGraph Tutrial Michael Kriegel & Meiyii Lim, Herit-Watt University, Edinburgh February 2009 Abut Open Scene Graph: Open Scene Graph is a mdern pen surce scene Graph. Open Scene Graph (r shrt OSG) alng with the cnfusingly similar sunding OpenSG seem t becme the tw leading SceneGraph systems. The main single infrmatin surce n Open Scene Graph is the prject s website: http://www.penscenegraph.rg/prjects/sg. On there yu can find varius dwnlads fr OSG and plugins alng with tutrials, examples and discussin grups. Abut This Tutrial: Unfrtunately, the dcumentatin n the OSG website is a bit incmplete and fragmented (there is n single dcument cvering all basic tpics) and there are als n bks n OSG yet, which is why we prepared this tutrial. We will hwever refer t dcumentatin items frm the website in this tutrial and sme f the examples have been taken frm the website resurces. This tutrial is based arund tasks and yu shuld wrk thrugh it chrnlgically. Task 1: Setup OSG There are several ways f hw t install OSG, which are explained in the annex f this dcument. Fr the purpse f this curse we prepared a Windws XP OSG distributin, which cmes in a zip file cntaining everything yu need t get immediately started. This distributin is already placed in n the I drive in the flder I:\sg. Just make sure the fllwing envirnment variables are set and add them if necessary: - set the fllwing envirnment variables: OSG_ROOT = I:\sg OSGHOME = I:\sg OSG_FILE_PATH = I:\sg\data;I:\sg\data\Images;I:\sg\data\fnts Add t the PATH variable: I:\sg\bin Yu can set envirnment variables via Windws Start Menu / Cntrl Panel / System / (Tab) Advanced / Envirnment Variables. Fr the changes t take effect yu will have t lg ff frm windws and lg in again. Task 2: Run the example applicatins In rder run the examples, g t the OSG bin subflder (I:\sg\bin) and start the file RUN_sg_examples.bat. This batch file will run thrugh a cuple f OSG dem applicatins that demnstrate the varius features f OSG. T end ne dem applicatin and jump t the next ne, press Esc. Apart frm that, a dem will print additinal instructins n the screen if interactin with it is pssible. In all the dems the muse can be used t navigate the camera. The fllwing cntrls are used:
- hld left muse buttn + mve muse rtate scene - hld middle muse buttn + mve muse mve scene - hld right muse buttn + mve muse zm in scene The same cntrls are used in every standard Open Scene Graph applicatin, s familiarize yurself with them. Nte that yu can apply a cnstant autmated rtatin, translatin r zm by using the abve cntrls but releasing the muse buttn befre yu stp the mvement. Try t make a mdel spin by itself. Nte that the surce cde fr all these examples is available, s they are a gd reference if yu want t find ut hw t implement a certain graphics effect later. Task 3: Cmpile yur first OSG applicatin in Visual Studi 2003 Visual Studi 2003 by Micrsft is the prgramming envirnment that yu are ging t use t write, debug and cmpile pen scene graph applicatins. Visual Studi supprts several prgramming languages including C#, C++ and Java, but fr ur Open Scene Graph purpses we will nly use C++. Library lcatins: In rder fr Visual Studi t cmpile yur applicatin, yu shuld first check if Visual Studi knws the lcatin f the OSG libraries: 1. Start Visual Studi 2. In Visual Studi chse menu Tls/Optins and then Prjects/VC++ Directries 3. Add the OSG binary directry (I:\sg\bin) in the categry executable files if it is nt listed there yet 4. Add the OSG include directry (I:\sg\include) in the categry include files if it is nt listed there yet 5. Add the OSG lib directry (I:\sg\lib) in the categry lib files if it is nt listed there yet Slutins and Prjects: If yu are nt familiar with Visual Studi, the distinctin f slutins and prjects might be a bit cnfusing at first. A prject cnsists nrmally f ne r several surce files and has ne utput (usually an executable, but may als be a dll etc.). A nrmal small applicatin f the size yu prduce during these tutrials nrmally be a prject. A slutin is a cllectin f prjects that belng tgether. Fr example if yu have split a bigger applicatin in several separate mdules, each f these mdules shuld be a prject and the whle applicatin a slutin. In a slutin yu can set up dependencies, in ther wrds determine the build rder. It is unlikely that yu will need any f these features fr this tutrial. Hwever, even if yu nly wrk with a single prject yu still need a slutin fr this single prject. Open the first example: Fr nw yu will nt have t make any mdificatins, s just pen the first really simple example slutin/prject. It is lcated in the OSG subflder examples/viewer 1. Cpy the whle flder t smewhere n yur H: drive (Yu wn t be able t cmpile it n the I: drive because yu dn t have write permissin there.). Lad the slutin file simpleviewer.sln and the prject will autmatically be laded as well. Nw g n t cmpile that example (blue play
buttn in the tl bar). If everything ges accrding t plan, the applicatin shuld start nw and yu shuld see a car n screen. Nw we will lk at the surce cde fr this example. It starts with an #include statement blck: #include <istream> #include <sgdb/readfile> #include <sgutil/optimizer> #include <sgprducer/viewer> If yu knw C++ this shuld be familiar. In this blck yu include the header files f the libraries yu are ging t use in yur prgram. Open Scene graph header files are all rganized by namespaces that refer t the different mdules Open Scene Graph cnsists f. The namespace and the name f the particular header file are separated with a slash. All the sg includes directly refer t a file in the include sub-flder. Fr example the 3 rd line allws the prgram t use all functins, types and classes that are defined in the header file I:\sg\include\sgUtil\Optimizer. After, yu ve gne thrugh the whle surce cde, have a lk at thse include files and try t figure ut, why they have been included. In the first line f the real prgram, a viewer is created: int main (int argc, char* argv[]) // Create a Prducer-based viewer sgprducer::viewer viewer; viewer.setupviewer(sgprducer::viewer::standard_settings); The viewer is nt part f the scene graph itself. It is the mdule that is respnsible fr displaying the scene graph. In the next line the viewer is set up with standard settings (that define fr example the way the camera is cntrlled by the muse). // Lad a mdel sg::ref_ptr<sg::nde> ladedmdel = sgdb::readndefile( car.3ds ); if (!ladedmdel) std::cerr << "Prblem pening mdel.\n"; exit (1); In this sectin a mdel is laded. Lets g thrugh this step by step: car.3ds is the file name f the mdel that will be laded. This is a mdel created with 3d studi max. sgdb::readndefile is the functin that handles lading f all 3d mdels independent f their frmat. The prgram will knw which lader plug in t use by lking at the file extensin f the 3d mdel file. The functin returns a pinter t an sg::nde, which is the tp Nde f the mdel s scene graph. The sg::ref_ptr<> template prvides a smart pinter class t bjects f all Open Scene Graph classes. If yu wuld have created a standard pinter (sg::nde *ladedmdel), yu wuld have t remve the laded bject frm memry yurself,
if yu dn t need it anymre r waste memry. Smart pinters autmatically cunt references and delete the assciated bject if the reference cunt drps t zer. In Java this cncept is called Garbage Cllectin. The last if-sectin checks if there were any errrs when lading the mdel. In rder fr the viewer t display smething we need t assciate it t a scene graph, in this simple case the cmplete scene graph is ur laded mdel: viewer.setscenedata (ladedmdel.get()); Ntice that we nly use the get() functin here because ladedmdel is a smart pinter. Thus the variable ladedmdel des nt pint itself t the memry address f the tp nde in the mdel, it rather pints t the memry address f the smart pinter cnstruct. T get the memry address f the Nde (which is what the setscenedata functin expects), yu have t use the get functin. Nw the ladedmdel is ptimized fr perfrmance reasns. This step is ptinal and leaving it ut fr a simple scene graph like ur s wuldn t have any nticeable effects: // Optimize the scene graph (a simple as pssible viewer desn't // really need this. sgutil::optimizer ptosgfile; ptosgfile.ptimize (ladedmdel.get()); The final bit f the prgram is the rendering lp. Fr every run thrugh this while lp a new frame is drawn n the screen (viewer.frame()): // Enter rendering lp viewer.realize(); while (!viewer.dne()) // wait fr all cull and draw threads t cmplete. viewer.sync(); viewer.update(); // fire ff the cull and draw traversals f the scene. viewer.frame(); // Wait fr all cull and draw threads t cmplete befre exit. viewer.sync(); Task 4 lad yur wn mdel Yu have already created a 3d mdel in the VRML sectin f this curse. Yur task is nw t lad that mdel int Open Scene Graph by mdifying the abve example. In fact all yu have t change in the surce cde is the mdel file name. Hwever, ur Open Scene Graph installatin des nt include a VRML lader s if yu try t lad a vrml file (e.g. car.wrl), yu will get an errr message. The easiest way fr yu t imprt yur mdel is via 3d Studi Max. Open 3D Studi Max (shuld be in the start menu under multimedia / Autdesk). In 3D Studi Use File/Imprt t imprt yur wrl file. Nw yu shuld see yur VRML mdel in 3D Studi Max. t make sure that
everything including textures was imprted crrectly, click n the Perspective view, psitin the camera s that yu get a gd view f the mdel, press F10 t pen the Rendering windw and click n Render. If yur mdel uses textures yu might nw get a message that 3ds can t lcate thse textures. If that happens, just add the path where the textures are lcated t 3d Studi s path. If everything is fine with yur mdel, yu can exprt it t a 3ds file by Chsing file/exprt. Nw yu nly need t place this newly created 3ds file and the texture files that were used in a lcatin, where it can be fund by OSG. Yu have several ptins: - the easiest ptin is t just put the files in the same flder in which yur slutin and surce cde files are lcated - Yu culd als put them in the data flder f sg (I:\sg\data remember the path variable OSG_FILE_PATH). If yu check the initial example, the car.3ds file was laded frm that directry. Unfrtunately, yu dn t have write permissin n I:\ s this wn t wrk, but this wuld be the easiest ptin if yu had OSG installed n yur wn PC. - The third ptin is t add anther path t the envirnment variable OSG_FILE_PATH, where yu can place the files. This path bviusly has t pint t smewhere, where yu have permissin t put files s ideally n yur H:\ drive Task 5 D the NPS Tutrials Nw yu will have the chance t create sme prgrams yurself. D that by fllwing the tutrials number 2, 3 and 4 (and mre if yu want) n: http://faculty.nps.edu/jasullivan/sgtutrials/ A few hints that might be useful, while ding the tutrials: Slutin & Prject Creating a new slutin and prject can be quite trublesme, because there are a number f prject settings (cmpiler and linker ptins, etc.) that have t be changed in rder fr an Open Scene Graph prject t cmpile crrectly. The much easier and suggested slutin is t cpy and then mdify an existing slutin. If yu want t create a new slutin and prject frm scratch, refer t the instructins n: http://faculty.nps.edu/jasullivan/sgtutrials/sgprjectsettings.htm Class reference - When yu are prgramming with a cmplex API like Open Scene Graph yu might need an API reference. The OSG API reference can be fund n: http://www.penscenegraph.rg/prjects/sg/wiki/supprt/referenceguides Include files - One thing the tutrials dn t tell yu, is what t put in yur include sectin. Nrmally each class has its wn header file. S fr example, if yu use an sg::transfrm, the matching include cmmand will be #include <sg/transfrm>. Yu dn t have t include every single class yu use, because if yu include ne file, yu autmatically als include all the files that are included by this file, etc. The best way t wrk is t nt wrry abut the include sectin until the time f cmpilatin. At this pint the cmpiler errr message will tell yu, which class is missing, which yu the simply add and cmpile again.