Introduction to the Universe class

• Universe is the "container" for all objects in the simulation
• Objects can include:
  • Geometry
  • Lights
  • Sensors
  • Viewpoints
  • Serial ports
  • etc.
• Objects are automatically maintained by the WTK Simulation Manager
• Universe methods DO NOT take pointers to universe as the first argument
• Only one universe for every simulation at any time

Universe construction and destruction

• WTuniverse_new
  • Must be the first WTK function call in a program exceptions are the WTinit functions
  • Can only be called once -- NEVER in the action function
  • Performs the following functionality:
    • Initializes the graphics device
    • Configures for a particular output device
    • Creates:
      • A default viewpoint
      • A default ambient light
      • A default root node
      • A window type
        
  • Function Description

void WTuniverse_new(DISPLAY_CONFIG, WINDOW_CONFIG)

Creates a new empty universe container

Parameters:

DISPLAY_CONFIG -- Can be one of the following listed predefined types:

Parameter	Meaning
WTDISPLAY_DEFAULT	Creates a single window
WTDISPLAY_NOWINDOW	No window will be created.  sometimes useful when creating a GUI using Motif, MFC, or WTK UI functions
WTDISPLAY_CRYSTALEYES	For CrystalEyes glasses.  Creates a single full screen stereo window which has no border.
WTDISPLAY_STEREO	Creates 2 windows.  Should only be used by legacy code.
WTDISPLAY_NEEDSTENCIL	Can be combined with WTDISPLAY_DEFAULT or WTDISPLAY_NOWINDOW by using the OR operator (|), to request the use of the stencil buffer.

WINDOW_CONFIG -- predefined type the specifies host specific window parameters. Provides the characteristics for the window the WTK will render to.

Parameter	Meaning
WTWINDOW_DEFUALT	No special attributes window has a border
WTWINDOW_STEREO	Creates a stereo window on systems that have hardware support for stereo.   On systems without hardware stereo support, this option will create 2 images in the window (one on top with the left eye view, the other on the bottom with the right eye view).  On Windows platforms, if this option is selected and the WTDISPLAY_NEEDSTENCIL option is selected in the display_param parameter, the behavior you will obtain is that of WTWINDOW_STEREOVSPLIT.
WTWINDOW_STEREOVSPLIT	This option can be combined wiht the WTWINDOW_STEREO option by using the OR operator (|), to create 2 images in the window (one on top wiht the left eye view and one on bottom with the right eye view), even if you system has hardware stereo support.   In essence, the option will cause WTK to disable you system's stereo hardware and to create a "vertically split" stereo window instead.
WTWINDOW_RBSTEREO	Red/Blue stereo display
WTWINDOW_INTERLACEEVENODD	Creates an interlaced stereo window whose even numbered scan lines correspond to the left eye view and whose odd numbered scanlines correspond to the right eye view.  This option requires that the WTDISPLAY_NEEDSTENCIL option be selected for the display_config parameter.
WTWINDOW_INTERLACEODDEVEN	Opposite of WTWINDOW_INTERLACEEVEODD.
WTWINDOW_NOBORDER	Window without a border
WTWINDOW_SCREENn	n is a number from 0 - 8. This constant is used in the multi-pipe/multi-processor version of WTK and indicates the screen number upon which the window will be created.

• WTuniverse_delete
  • Should be the last call in your main program
  • Frees all of the objects in the universe.
  • Includes those that have been "removed" for the simulation
  • Cleans up an closes the graphics hardware or WTK display
  • Function description:

void WTuniverse_delete(void);

Understanding the Simulation Manager

• Heart of all WTK applications
• Entered by calling WTuniverse_go or WTuniverse_go1
• Loop is broken with a call to WTuniverse_stop
• Order of events can be altered using WTuniverse_seteventorder

Readying the loop -- Before calling WTuniverse_go you must call WTuniverse_ready

• WTuniverse_ready()
  • Prepares the application for entry into the main loop
  • Should be called BEFORE entering the simulation loop for the first time
  • Should be called AFTER all graphical entities have been created.
  • Assists in providing smooth frame-rates when objects come into view.

Launching the loop -- go VS go1 -- WTuniverse_go put the loop into an endless cycle (infinite loop) go1 runs the simulation loop once.

• WTuniverse_go
  • Enters the simulation loop
  • Loop is not exited until a call to WTuniverse_stop is found if the application
  • Must be called AFTER WTuniverse_new and WTuniverse_ready
  • Is not reenterant it MUST NOT be called from the universe action function

Function description:

void WTuniverse_go(void);

• WTuniverse_go1
  • Causes the simulation loop to run only once
  • Is not reenterant it MUST NOT be called from the universe action function
  • Must be called after WTuniverse_new and WTuniverse_ready

Function Description:

void WTuniverse_go1(void);

Setting and Getting the Simulation Loop Event Order

• WTuniverse_seteventorder
  • Changes the order in which the simulation loop is executed
  • Uses predefined constants

Function description

FLAG WTuniverse_seteventorder(short nevents, short *events);

Parameters

short nevents -- always four is only provided for future compatibility
short *events -- a pointer to an array of four shorts containing the following values:

Parameter	Meaning
WTEVENT_ACTIONS	User defined action function
WTEVENT_OBJECTSENSOR	Graphical objects and viewpoints are updated with sensor input
WTEVENT_TASKS	Object task functions
WTEVENT_PATHS	Paths in record or playback mode are stepped.

Example of usage:

short eventorder[4];
FLAG success;
eventorder[0] = WTEVENT_OBJECTSENSOR;
eventorder[1] = WTEVENT_TASKS;
eventorder[2] = WTEVENT_ACTIONS;
eventorder[3] = WTEVENT_PATHS;
success = WTuniverse_seteventorder(4, eventorder);

• WTuniverse_geteventorder
  • This function returns the current order of execution of events in the simulation loop

Function Description

short *WTuniverse_geteventorder(void);

Example of usage:

short eventorder[4];
eventorder = WTuniverse_geteventorder();

Important Notes:

DO NOT modify the returned array or the results are undefined since it is a pointer to the event order array!!!!!

 

Understanding the User Defined Action Function

• Used to define and control the activity in the simulation.
• Actions involving any WTK objects, graphical or otherwise, can be specified
• Is call by the simulation manager once each time through the simulation loop.
• Examples of actions which might occur in the action function:
  • Program termination
  • Simulation activities
  • Changes to rendering parameters
  • Handling sensor button input
  • Handling keyboard input
  • Should be called AFTER WTuniverse_new and BEFORE WTuniverse_ready.

Function Description

void WTuniverse_setactions(void (*actionfn)(void));

Parameters:

void (* actionfn)(void) -- a pointer to the function defined by the user

Note

The action function can have no parameters

Example of Usage:

#include "wt.h"
void actionfn(void);
void main(void)
{

WTuniverse_new(WTDISPLAY_DEFAULT, WTWINDOW_DEFAULT);
….
….
WTuniverse_setactions(actionfn);
….
WTuniverse_ready();
WTuniverse_go();
WTunvierse_delete();

}

void actionfn(void)
{

/* functionality included here */

}

 

Introduction to platform compatibility

• WTK provides functions to assist you in maintaining platform compatibility. Well start with some of the most commonly used functions.
  • WTmessage -- prints a message to the console screen

    void WTmessage(char *format);

    Example:

    WTmessage("hello");

  • WTkeyboard_open -- opens communication with the keyboard

    void WTkeyboard_open(void);

  • WTkeyboard_getkey() -- retrieves a key press from the keyboard

    short WTkeyboard_getkey(void);

    Example:

    short key;
    key = WTkeyboard_getkey();

Lab 1 -- Your first WTK application -- HELLO WORLD

• Functions covered
  • WTuniverse_new
  • WTuniverse_ready
  • WTuniverse_go
  • WTmessage
  • WTkeyboard_new
  • WTkeyboard_getkey
  • WTuniverse_stop
  • WTuniverse_delete
• Project definition
  • Create a WTK application that contains the following functionality:
  • Creates a universe in monoscopic mode with a bordered window
  • Uses a user defined action function to:
    • print the message "Hello World" to the console window
    • exists the simulation loop when a q is pressed on the keyboard.
    • Make sure that your code is well commented so that it is easier for you to understand next time you use it.

Universe Objects

• Objects in WTK can be of many types including:
  • Scene Graphs and their nodes
  • Sensors
  • Viewpoints
  • Lights
  • Paths
  • Polygons
  • Windows
  • etc.….
• WTK objects are stored in Linked Lists
  • You use Get and Next functions to access the objects in the list
  • All the following get functions return the first object in the linked list for that object. The next functions are used to iterate through the linked list of all the objects of that type in the simulation.

     

    Get Functions	Next Function
    WTsensor *WTuniverse_getsensors(void);	WTsensor *WTsensor_next(WTsensor *sensor);
    WTpath *WTuniverse_getpaths(void);	WTpath *WTpath_next(WTpath *path);
    WTwindow *WTuniverse_getwindows(void);	WTwindow *WTwindow_next(WTwindow *window);
    WTviewpoint *WTuniverse_getviewpoints(void);	WTviewpoint *WTviewpoint_next(WTviewpoint *viewpoint);
    WTnode *WTuniverse_getrootnodes(void);	WTnode *WTrootnode_next(WTnode *root);
    WTmotionlink *WTuniverse_getmotionlinks(void);	WTmotionlink *WTmotionlink_next(WTmotionlink *motionlink);

• Other get and set functions
  • WTwindow *WTuniverse_getcurrwindow(void); -- returns the window with the current focus
  • WTwindidtype WTuniverse_getcurrwinidx(void); -- returns the window id of the window with the input focus
  • int WTuniverse_getcurrscridx(void); -- returns the screen number with the input focus
  • WTnode *WTuniverse_setviewpoint(WTviewpoint *viewpoint); assigns the specified viewpoint to be the current viewpoint
  • void WTuniverse_getinitialview(WTpq position); -- get viewpoint information read from a geometry file.
  • void WTuniverse_deletelink(void *source, void *target); -- deletes a motion link

Introduction to Global Rendering Parameters

• WTK allows the programmer to specify certain global rendering parameters and display options. These are a few of the more commonly set options:
  • Bounding box color

    void WTuniverse_setbboxrgb(float r, float g. float b);

    • effects the color of the lines used to draw bounding boxes around nodes.
    • The r, g, and b values are scaled from 0.0 to 1.0 with 1.0, 1.0, 1.0 being WHITE and 0.0, 0.0, 0.0 being BLACK
  • Global Rendering Style

    void WTuniverse_setrendering(FLAG style);

    • Used to specify the universe rendering style.
    • Style argument is a bitmask which allows you to set several different flags simultaneously
    • The following predefined types can be used as a style argument

Style	Meaning
WTRENDER_GOUROUD	Enable gouraud shading
WTRENDER_TEXTURED	Enable texturing
WTRENDER_PERSPECTIVE	Enable texture perspective corrections
WTRENDER_ANTIALIAS	Enable anti-aliasing
WTRENDER_WIREFRAME	Enable wireframe rendering
WTRENDER_BEST	Enables all of the above.